NAME

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

VERSION

Version 0.121

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

log

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.

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

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 non-OK status object with optional payload (optional parameter to the method call, must be a scalar).

notice

Boolean function, returns true if status object has level 'NOTICE', false otherwise.

warn

Boolean function, returns true if status object has level 'WARN', false otherwise.

err

Boolean function, returns true if status object has level 'ERR', false otherwise.

level

Accessor method.

text

Accessor method.

caller

Accessor method.

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)

cpanm App::CELL

perl -MCPAN -e shell
install App::CELL