/ 
App-Dochazka-CLI-0.240
River stage zero No dependents
/ App::Dochazka::CLI::Util

NAME

App::Dochazka::CLI::Util - Various reusable components

PACKAGE VARIABLES AND EXPORTS

FUNCTIONS

authenticate_to_server

All communication between App::Dochazka::CLI and the App::Dochazka::REST server goes via the send_req routine in Web::MREST::CLI. This routine takes its connection parameters (address of REST server, nick and password) from the following configuration parameters:

$meta->MREST_CLI_URI_BASE
$meta->CURRENT_EMPLOYEE_NICK
$meta->CURRENT_EMPLOYEE_PASSWORD

The first parameter, MREST_CLI_URI_BASE, is assumed to be set before this routine is called. The second and third are meta parameters and are set by this routine.

After setting the meta parameters, the routine causes a GET request for the employee/self/full resource to be send to the server, and uses the response to initialize the $current_emp and $current_priv variables which are imported from the App::Dochazka::CLI package.

Takes PROPLIST with two properties:

user

The username to authenticate as (defaults to 'demo')

password

The password to use (defaults to the value of the user parameter)

Since this routine returns the status object returned by the "GET employee/self/full" request, it is actually a wrapper around send_req.

datelist_from_token

Takes a numeric month and a _DATELIST token - e.g. "5,6,10-13,2".

Convert the token into an array of dates and return a reference. So, upon success, the return value will look something like this:

[ "2015-01-01", "2015-01-06", "2015-01-22" ]

If there's a problem, writes an error message to the log and returns undef.

determine_employee

Given what might possibly be an employee specification (as obtained from the user from the EMPLOYEE_SPEC token of the command line), return a status object that will either be an error (not OK) or contain the employee object in the payload.

If the employee specification is empty or undefined, the payload will contain the $current_emp object.

lookup_employee

EMPLOYEE_SPEC may be "nick=...", "sec_id=...", "eid=...", or simply "employee=...", in which case we use a clever algorithm to look up employees (i.e. try looking up search key as nick, sec_id, and EID - in that order).

init_logger

Logger initialization routine

init_prompt

(Re-)initialize the date/time-related package variables

month_alpha_to_numeric

Given a month written in English (e.g. "January"), return the ordinal number of that month (i.e. 1 for January) or undef if it cannot be determined.

normalize_date

Normalize a date entered by the user. A date can take the following forms (case is insignificant):

YYYY-MM-DD
YY-MM-DD
MM-DD
TODAY
TOMORROW
YESTERDAY
+n
-n

and any of the two-digit forms can be fulfilled by a single digit, for example 2014-3-4 is March 4th, 2014.

All the forms except the first are converted into the YYYY-MM-DD form. The last two forms listed, +n and -n, are calculated as offsets from the "prompt date" (the date shown in the prompt), where n is interpreted as a number of days.

If an undefined or empty string is given, the prompt date is returned.

If the string does not match any of the forms, undef is returned.

Caveats:

  • two-digit years

    If only YY is given, it is converted into YYYY by appending two digits corresponding to the prompt century (e.g. 22 becomes 2022 during 2000-2099).

  • special date forms

    The special date forms "TODAY", "TOMORROW", and "YESTERDAY" are recognized, and only the first three letters are significant, so "todMUMBOJUMBO" converts to today's date.

  • offsets

    The n in the offset can be any number in the range 0-999.

  • no year

    If no year is given, the prompt year is used.

  • no date

    If no date is given, the prompt date is used.

  • single-digit forms

    If a single-digit form is given for MM or DD, a leading zero is appended.

normalize_time

Normalize a time entered by the user. A time can take the following forms

HH:MM:SS
HH:MM

and any of the two-digit forms can be fulfilled by a single digit, for example 6:4:9 is 6:04 a.m. and nine seconds

  • single-digit forms

    If a single-digit form is given, a leading zero is appended.

  • seconds

    If seconds are given, they are ignored.

  • no validation

    No attempt is made to validate the time -- this is done later, by PostgreSQL.

parse_test

Given a reference to the PARAMHASH a command handler was called with, check if there is a PARSE_TEST property there, and if it is true return the full subroutine name of the caller.

refresh_current_emp

REST calls are cheap, so look up $current_emp again just to make sure.

rest_error

Given a non-OK status object and a string briefly identifying (for the user) the operation during which the error occurred, construct and return a new App::CELL::Status object bearing (in the payload) a string containing the "error report" - perhaps suitable for displaying to the user. The code of that object is REST_ERROR and its level is taken from the passed-in status object. The other attributes of the original (passed-in) status object are preserved in the returned status object as follows:

payload -> rest_payload
uri_path -> uri_path 
http_status -> http_status

truncate_to

Given a string and a maximum length (defaults to 32), truncates to that length. Returns a copy of the string. If any characters were actually removed in the truncate operation, '...' is appended -- unless the maximum length is zero, in which case the empty string is returned.