NAME
App::CELL::Status - class for return value objects
VERSION
Version 0.150
SYNOPSIS
use App::CELL::Status;
# simplest usage
my $status = App::CELL::Status->ok;
print "ok" if ( $status->ok );
$status = App::CELL::Status->not_ok;
print "NOT ok" if ( $status->not_ok );
# as a return value: in the caller
my $status = $XYZ( ... );
return $status if not $status->ok; # handle failure
my $payload = $status->payload; # handle success
# just to log something more serious than DEBUG or INFO (see
# App::CELL::Log for how to log those)
App::CELL::Status->new( 'WARN', 'Watch out!' );
App::CELL::Status->new( 'NOTICE', 'Look at this!' );
INHERITANCE
This module inherits from App::CELL::Message
DESCRIPTION
An App::CELL::Status object is a reference to a hash containing some or all of the following keys (attributes):
level
- the status level (see "new", below)message
- message explaining the statuscaller
- an array reference containing the three-item list generated by thecaller
function
The typical use cases for this object are:
All calls to App::CELL::Status->new
with a status other than OK trigger a log message.
PUBLIC METHODS
This module provides the following public methods:
new
Construct a status object and trigger a log message if the level is anything other than "OK". Always returns a status object. If no level is specified, the level will be 'ERR'. If no code is given, the code will be
The most frequent case will be a status code of "OK" with no message (shown here with optional "payload", which is whatever the function is supposed to return on success:
# all green
return App::CELL::Status->new( level => 'OK',
payload => $my_return_value,
);
To ensure this is as simple as possible in cases when no return value (other than the simple fact of an OK status) is needed, we provide a special constructor method:
# all green
return App::CELL::Status->ok;
In most other cases, we will want the status message to be linked to the filename and line number where the new
method was called. If so, we call the method like this:
# relative to me
App::CELL::Status->new( level => 'ERR',
code => 'CODE1',
args => [ 'foo', 'bar' ],
);
It is also possible to report the caller's filename and line number:
# relative to my caller
App::CELL::Status->new( level => 'ERR',
code => 'CODE1',
args => [ 'foo', 'bar' ],
caller => [ caller ],
);
It is also possible to pass a message object in lieu of code
and msg_args
(this could be useful if we already have an appropriate message on hand):
# with pre-existing message object
App::CELL::Status->new( level => 'ERR',
msg_obj => $my_msg;
);
Permitted levels are listed in the @permitted_levels
package variable in App::CELL::Log
.
dump
Dump an existing status object. Takes: PARAMHASH. Parameter 'to' determines destination, which can be 'string' (default), 'log' or 'fd'.
# dump object to string
my $dump_str = $status->dump();
$dump_str = $status->dump( to => 'string' );
# dump object to log
$status->dump( to => 'log' );
# dump object to file descriptor
$status->dump( fd => STDOUT );
$status->dump( to => 'fd', fd => STDOUT );
Always returns a true value.
ok
If the first argument is blessed, assume we're being called as an instance method: return true if status is OK, false otherwise.
Otherwise, assume we're being called as a class method: return a new OK status object with optional payload (optional parameter to the method call, must be a scalar).
not_ok
Similar method to 'ok', except it handles 'NOT_OK' status.
When called as an instance method, returns a true value if the status level is anything other than 'OK'. Otherwise false.
When called as a class method, returns a 'NOT_OK' status object. Optionally, a payload can be supplied as an argument.
level
Accessor method, returns level of status object in ALL-CAPS. All status objects must have a level attribute.
code
Accesor method, returns code of status object, or undef
if none present.
text
Accessor method, returns text of status object, or the code if no text present. If neither code nor text are present, returns undef
.
caller
Accessor method. Returns array reference containing output of caller
function associated with this status object, or undef
if not present.
payload
When called with no arguments, acts like an accessor method. When called with a scalar argument, either adds that as the payload or changes the payload to that.
Generates a warning if an existing payload is changed.
Returns the (new) payload or undef.
msgobj
Accessor method (returns the parent message object)