---
name: "App::CELL::Status"
section: "3pm"
platform: "linux"
package: "libapp-cell-perl"
version: "0.231-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/App::CELL::Status"
---

# App::CELL::Status(3pm)

class for return value objects

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