view release on metacpan or  search on metacpan

lib/App/CELL/Status.pm  view on Meta::CPAN

=head1 DESCRIPTION

An App::CELL::Status object is a reference to a hash containing some or
all of the following keys (attributes):

=over 

=item C<level> - the status level (see L</new>, below)

=item C<message> - message explaining the status

=item C<caller> - an array reference containing the three-item list
generated by the C<caller> function

=back

The typical use cases for this object are:

=over

=item As a return value from a function call

=item To trigger a higher-severity log message

=back

All calls to C<< App::CELL::Status->new >> with a status other than OK
trigger a log message.



=head1 PUBLIC METHODS

This module provides the following public methods:



=head2 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).

=cut

sub new {
    my ( $class, @ARGS ) = @_;
    my %ARGS = @ARGS;
    my $self;

    # default to ERR level
    unless ( defined $ARGS{level} and grep { $ARGS{level} eq $_ } $log->permitted_levels ) {
        $ARGS{level} = 'ERR';
    }

    # if caller array not given, create it
    if ( not $ARGS{caller} ) {
        $ARGS{caller} = [ CORE::caller() ];
    }

    $ARGS{args} = [] if not defined( $ARGS{args} );
    $ARGS{called_from_status} = 1;

    if ( $ARGS{code} ) {
        # App::CELL::Message->new returns a status object
        my $status = $class->SUPER::new( %ARGS );
        if ( $status->ok ) {
            my $parent = $status->payload;
            $ARGS{msgobj} = $parent;
            $ARGS{code} = $parent->code;
            $ARGS{text} = $parent->text;
        } else {
            $ARGS{code} = $status->code;
            if ( $ARGS{args} ) {
               $ARGS{text} = $status->text . stringify_args( $ARGS{args} );
            } else {
               $ARGS{text} = $status->text;
            }
        }
    }

    # bless into objecthood
    $self = bless \%ARGS, 'App::CELL::Status';

    # Log the message
    $log->status_obj( $self, cell => ( $ARGS{cell} || 0 ) ) if ( $ARGS{level} ne 'OK' and $ARGS{level} ne 'NOT_OK' );

    # return the created object
    return $self;
}


=head2 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.

=cut

sub dump {
    my $self = shift;
    my ( %ARGS ) = validate( @_, { 'to' => 0, 'fd' => 0 } );
    my ( $action, $fh );
    if ( not %ARGS ) {
        $action = 'string';

lib/App/CELL/Status.pm  view on Meta::CPAN

            code => $self->code,
            text => $self->text,
        );
    } elsif ( $action eq "log" ) {
        $log->status_obj( $self );
    } elsif ( $action eq "fd" ) {
        print $fh _prep_dump_string(
            level => $self->level,
            code => $self->code,
            text => $self->text,
        ), "\n";
    } else {
        die "App::CELL->Status->dump() doing nothing (bad things happening)";
    }

    return 1;
}


sub _prep_dump_string {
    my %ARGS = validate( @_, {
        'level' => 1,
        'code' => 0,
        'text' => 1,
    } );

    my $prepped_string = "$ARGS{'level'}: ";
    if ( $ARGS{'code'} and $ARGS{'code'} ne $ARGS{'text'} ) {
        $prepped_string .= "($ARGS{'code'}) ";
    }
    $prepped_string .= "$ARGS{'text'}";

    return $prepped_string;
}


=head2 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).

=cut

sub ok {

    my ( $self, $payload ) = @_;
    my $ARGS = {};

    if ( blessed $self ) 
    { # instance method
        return 1 if ( $self->level eq 'OK' );
        return 0;

    } 
    $ARGS->{level} = 'OK';
    $ARGS->{payload} = $payload if $payload;
    $ARGS->{caller} = [ CORE::caller() ];
    return bless $ARGS, __PACKAGE__;
}


=head2 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.

=cut

sub not_ok {

    my ( $self, $payload ) = @_;
    my $ARGS = {};

    if ( blessed $self ) 
    { # instance method
        return 1 if $self->{level} ne 'OK';
        return 0;
    } 
    $ARGS->{level} = 'NOT_OK';
    $ARGS->{payload} = $payload if $payload;
    $ARGS->{caller} = [ CORE::caller() ];
    return bless $ARGS, __PACKAGE__;
}


=head2 level

Accessor method, returns level of status object in ALL-CAPS. All status
objects must have a level attribute.

=cut

sub level { 
    my $self = shift;
    $self->{'level'} = $_[0] if @_;
    return $self->{'level'};
}


=head2 code

Accesor method, returns code of status object, or "C<< <NONE> >>" if none
present.

=cut

sub code { 
    my $self = shift;
    $self->{'code'} = $_[0] if @_;
    return $self->{'code'} || "<NONE>";
}
    

=head2 args

Accessor method - returns value of the 'args' property.

=cut

sub args { 
    my $self = shift;
    $self->{'args'} = $_[0] if @_;
    return $self->{'args'};
}


=head2 text

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

=cut

sub text {
    return $_[0]->{text} if $_[0]->{text};
    return $_[0]->code;
}


=head2 caller