- PUBLIC METHODS
App::CELL::Status - class for return value objects
use App::CELL::Status; # as a return value: in function XYZ return App::CELL::Status->new( ... ); # 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!' );
This module inherits from
A 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 status
fullpath- full path to file where the status occurred
filename- alternatively, the name of the file where the status occurred
line- line number where the status occurred
The typical use cases for this object are:
- As a return value from a function call
- To trigger a higher-level log message
All calls to
App::CELL::Status->new with a status other than OK trigger a log message.
@permitted_levels array contains a list of permissible log levels.
This module provides the following public methods:
Construct a status object and trigger a log message if the level is anything other than "OK". Returns the object.
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
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; );
level can be one of the following: OK, NOTICE, WARN, ERR, CRIT.
Write an existing status object to syslog. Takes the object, and logs it. Always returns true, because we don't want the program to croak just because syslog is down.
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.
Accessor method (returns the parent message object)