.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "App::CELL::Status 3pm"
.TH App::CELL::Status 3pm "2020-04-01" "perl v5.30.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
App::CELL::Status \- class for return value objects
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    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
.Ve
.SH "INHERITANCE"
.IX Header "INHERITANCE"
This module inherits from \f(CW\*(C`App::CELL::Message\*(C'\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
An App::CELL::Status object is a reference to a hash containing some or
all of the following keys (attributes):
.ie n .IP """level"" \- the status level (see ""new"", below)" 4
.el .IP "\f(CWlevel\fR \- the status level (see ``new'', below)" 4
.IX Item "level - the status level (see new, below)"
.PD 0
.ie n .IP """message"" \- message explaining the status" 4
.el .IP "\f(CWmessage\fR \- message explaining the status" 4
.IX Item "message - message explaining the status"
.ie n .IP """caller"" \- an array reference containing the three-item list generated by the ""caller"" function" 4
.el .IP "\f(CWcaller\fR \- an array reference containing the three-item list generated by the \f(CWcaller\fR function" 4
.IX Item "caller - an array reference containing the three-item list generated by the caller function"
.PD
.PP
The typical use cases for this object are:
.IP "As a return value from a function call" 4
.IX Item "As a return value from a function call"
.PD 0
.IP "To trigger a higher-severity log message" 4
.IX Item "To trigger a higher-severity log message"
.PD
.PP
All calls to \f(CW\*(C`App::CELL::Status\->new\*(C'\fR with a status other than \s-1OK\s0
trigger a log message.
.SH "PUBLIC METHODS"
.IX Header "PUBLIC METHODS"
This module provides the following public methods:
.SS "new"
.IX Subsection "new"
Construct a status object and trigger a log message if the level is anything
other than \*(L"\s-1OK\*(R".\s0 Always returns a status object. If no level is specified, the
level will be '\s-1ERR\s0'. If no code is given, the code will be undefined (I think).
.SS "dump"
.IX Subsection "dump"
Dump an existing status object. Takes: \s-1PARAMHASH.\s0 Parameter 'to' determines
destination, which can be 'string' (default), 'log' or 'fd'.
.PP
.Vb 3
\&    # dump object to string
\&    my $dump_str = $status\->dump();
\&       $dump_str = $status\->dump( to => \*(Aqstring\*(Aq );
\&
\&    # dump object to log
\&    $status\->dump( to => \*(Aqlog\*(Aq );
\&
\&    # dump object to file descriptor
\&    $status\->dump( fd => STDOUT );
\&    $status\->dump( to => \*(Aqfd\*(Aq, fd => \e*STDOUT );
.Ve
.PP
Always returns a true value.
.SS "ok"
.IX Subsection "ok"
If the first argument is blessed, assume we're being called as an
instance method: return true if status is \s-1OK,\s0 false otherwise.
.PP
Otherwise, assume we're being called as a class method: return a 
new \s-1OK\s0 status object with optional payload (optional parameter to the
method call, must be a scalar).
.SS "not_ok"
.IX Subsection "not_ok"
Similar method to 'ok', except it handles '\s-1NOT_OK\s0' status.
.PP
When called as an instance method, returns a true value if the status level
is anything other than '\s-1OK\s0'. Otherwise false.
.PP
When called as a class method, returns a '\s-1NOT_OK\s0' status object.
Optionally, a payload can be supplied as an argument.
.SS "level"
.IX Subsection "level"
Accessor method, returns level of status object in ALL-CAPS. All status
objects must have a level attribute.
.SS "code"
.IX Subsection "code"
Accesor method, returns code of status object, or "\f(CW\*(C`<NONE>\*(C'\fR" if none
present.
.SS "args"
.IX Subsection "args"
Accessor method \- returns value of the 'args' property.
.SS "text"
.IX Subsection "text"
Accessor method, returns text of status object, or the code if no text
present. If neither code nor text are present, returns "\f(CW\*(C`<NONE>\*(C'\fR"
.SS "caller"
.IX Subsection "caller"
Accessor method. Returns array reference containing output of \f(CW\*(C`caller\*(C'\fR
function associated with this status object, or \f(CW\*(C`[]\*(C'\fR if not present.
.SS "payload"
.IX Subsection "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.
.PP
Logs a warning if an existing payload is changed.
.PP
Returns the (new) payload or undef.
.SS "msgobj"
.IX Subsection "msgobj"
Accessor method (returns the parent message object)
.SS "expurgate"
.IX Subsection "expurgate"
Make a deep copy of the status object, unbless it, and remove certain
attributes deemed \*(L"extraneous\*(R".