App::CELL::Status

NAME

App::CELL::Status − class for return value objects

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

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 status
"caller" − an array reference containing the three-item list generated
by the "caller" function

The typical use cases for this object are:
As a return value from a function call
To trigger a higher-severity log message

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

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 ""<NONE>"" if none present.

args
Accessor method − returns value of the ’args’ property.

text
Accessor method, returns text of status object, or the code if no text present. If neither code nor text are present, returns ""<NONE>""

caller
Accessor method. Returns array reference containing output of "caller" function associated with this status object, or "[]" 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.

Logs a warning if an existing payload is changed.

Returns the (new) payload or undef.

msgobj
Accessor method (returns the parent message object)

expurgate
Make a deep copy of the status object, unbless it, and remove certain attributes deemed "extraneous".