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 undefined (I think).

   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 ""<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".