The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-Dochazka-REST-0.559
River stage zero No dependents
1 ++
/ App::Dochazka::REST::Model::Shared

NAME

App::Dochazka::REST::Model::Shared - functions shared by several modules within the data model

SYNOPSIS

    use App::Dochazka::REST::Model::Shared;

    ...

EXPORTS

FUNCTIONS

canonicalize_date

Given a string that PostgreSQL might recognize as a date, pass it to the database via the SQL statement:

    SELECT CAST( ? AS date )

and return the resulting status object.

canonicalize_ts

Given a string that might be a timestamp, "canonicalize" it by running it through the database in the SQL statement:

    SELECT CAST( ? AS timestamptz )

canonicalize_tsrange

Given a string that might be a tsrange, "canonicalize" it by running it through the database in the SQL statement:

    SELECT CAST( ? AS tstzrange )

Returns an App::CELL::Status object. If the status code is OK, then the tsrange is OK and its canonicalized form is in the payload. Otherwise, some kind of error occurred, as described in the status object.

cud

Attempts to Create, Update, or Delete a single database record. Takes the following PARAMHASH:

  • conn

    The DBIx::Connector object with which to gain access to the database.

  • eid

    The EID of the employee originating the request (needed for the audit triggers).

  • object

    The Dochazka datamodel object to be worked on.

  • sql

    The SQL statement to execute (should be INSERT, UPDATE, or DELETE).

  • attrs

    An array reference containing the bind values to be plugged into the SQL statement.

Returns a status object.

Important note: it is up to the programmer to not pass any SQL statement that might affect more than one record.

cud_generic

Attempts to execute a generic Create, Update, or Delete database operation. Takes the following PARAMHASH:

  • conn

    The DBIx::Connector object with which to gain access to the database.

  • eid

    The EID of the employee originating the request (needed for the audit triggers).

  • sql

    The SQL statement to execute (should be INSERT, UPDATE, or DELETE).

  • bind_params

    An array reference containing the bind values to be plugged into the SQL statement.

Returns a status object.

Important note: it is up to the programmer to not pass any SQL statement that might affect more than one record.

decode_schedule_json

Given JSON string representation of the schedule, return corresponding HASHREF.

get_history

This function takes a number of arguments. The first two are (1) a SCALAR argument, which can be either 'priv' or 'schedule', and (2) a DBIx::Connector object.

Following these there is a PARAMHASH which can have one or more of the properties 'eid', 'nick', and 'tsrange'. At least one of { 'eid', 'nick' } must be specified. If both are specified, the employee is determined according to 'eid'.

The function returns the history of privilege level or schedule changes for that employee over the given tsrange, or the entire history if no tsrange is supplied.

The return value will always be an App::CELL::Status object.

Upon success, the payload will be a reference to an array of history objects. If nothing is found, the array will be empty. If there is a DBI error, the payload will be undefined.

load

Load a database record into an object based on an SQL statement and a set of search keys. The search key must be an exact match: this function returns only 1 or 0 records. Call, e.g., like this:

    my $status = load( 
        conn => $conn,
        class => __PACKAGE__, 
        sql => $site->DOCHAZKA_SQL_SOME_STATEMENT,
        keys => [ 44 ]
    );

The status object will be one of the following:

  • 1 record found

    Level OK, code DISPATCH_RECORDS_FOUND, payload: object of type 'class'

  • 0 records found

    Level NOTICE, code DISPATCH_NO_RECORDS_FOUND, payload: none

  • Database error

    Level ERR, code DOCHAZKA_DBI_ERR, text: error message, payload: none

load_multiple

Load multiple database records based on an SQL statement and a set of search keys. Example:

    my $status = load_multiple( 
        conn => $conn,
        class => __PACKAGE__, 
        sql => $site->DOCHAZKA_SQL_SOME_STATEMENT,
        keys => [ 'rom%' ] 
    );

The return value will be a status object, the payload of which will be an arrayref containing a set of objects. The objects are constructed by calling $ARGS{'class'}->spawn

For convenience, a 'count' property will be included in the status object.

make_test_exists

Returns coderef for a function, 'test_exists', that performs a simple true/false check for existence of a record matching a scalar search key. The record must be an exact match (no wildcards).

Takes one argument: a type string $t which is concatenated with the string 'load_by_' to arrive at the name of the function to be called to execute the search.

The returned function takes a single argument: the search key (a scalar value). If a record matching the search key is found, the corresponding object (i.e. a true value) is returned. If such a record does not exist, 'undef' (a false value) is returned. If there is a DBI error, the error text is logged and undef is returned.

noof

Given a DBIx::Connector object and the name of a data model table, returns the total number of records in the table.

    activities employees intervals locks privhistory schedhistory
    schedintvls schedules tempintvls

On failure, returns undef.

priv_by_eid

Given an EID, and, optionally, a timestamp, returns the employee's priv level as of that timestamp, or as of "now" if no timestamp was given. The priv level will default to 'passerby' if it can't be determined from the database.

schedule_by_eid

Given an EID, and, optionally, a timestamp, returns the SID of the employee's schedule as of that timestamp, or as of "now" if no timestamp was given.

_st_by_eid

Function that 'priv_by_eid' and 'schedule_by_eid' are wrappers of.

select_single

Given a DBIx::Connector object in the 'conn' property, a SELECT statement in the 'sql' property and, in the 'keys' property, an arrayref containing a list of scalar values to plug into the SELECT statement, run a selectrow_array and return the resulting list.

Returns a standard status object (see load routine, above, for description).

select_set_of_single_scalar_rows

Given DBIx::Connector object, an SQL statement, and a set of keys to bind into the SQL statement, assume that the statement can return 0-n records and that each record consists of a single field that must fit into a single scalar value.

split_tsrange

Given a string that might be a tsrange, run it through the database using the SQL statement:

    SELECT lower(CAST( ? AS tstzrange )), upper(CAST( ? AS tstzrange ))

If all goes well, the result will be an array ( from, to ) of two timestamps.

Returns a status object.

timestamp_delta_minus

Given a timestamp string and an interval string (e.g. "1 week 3 days" ), subtract the interval from the timestamp.

Returns a status object. If the database operation is successful, the payload will contain the resulting timestamp.

timestamp_delta_plus

Given a timestamp string and an interval string (e.g. "1 week 3 days" ), add the interval to the timestamp.

Returns a status object. If the database operation is successful, the payload will contain the resulting timestamp.

tsrange_intersection

Given two strings that might be tsranges, consult the database and return the result of tsrange1 * tsrange2 (also a tsrange).

tsrange_equal

Given two strings that might be equal tsranges, consult the database and return the result (true or false).

AUTHOR

Nathan Cutler, <presnypreklad@gmail.com>