/ 
Class-Usul-0.43.1
River stage one • 3 direct dependents • 3 total dependents
/ Class::Usul::Functions

Name

CatalystX::Usul::Functions - Globally accessible functions

Synopsis

package MyBaseClass;

use CatalystX::Usul::Functions;

Description

Provides globally accessible functions

Subroutines/Methods

abs_path

$absolute_untainted_path = abs_path $some_path;

Untaints path. Makes it an absolute path and returns it. Returns undef otherwise. Traverses the filesystem

app_prefix

$prefix = app_prefix __PACKAGE__;

Takes a class name and returns it lower cased with :: changed to _, e.g. App::Munchies becomes app_munchies

arg_list

$args = arg_list @rest;

Returns a hash ref containing the passed parameter list. Enables methods to be called with either a list or a hash ref as it's input parameters

assert

assert $ioc_object, $condition, $message;

By default does nothing. Does not evaluate the passed parameters. The assert constant can be set via an inherited class attribute to do something useful with whatever parameters are passed to it

assert_directory

$untainted_path = assert_directory $path_to_directory;

Untaints directory path. Makes it an absolute path and returns it if it exists. Returns undef otherwise

base64_decode_ns

$decoded_value = base64_decode_ns $encoded_value;

Decode a scalar value encode using base64_encode_ns

base64_encode_ns

$encoded_value = base64_encode_ns $encoded_value;

Base 64 encode a scalar value using an output character set that preserves the input values sort order (natural sort)

bsonid

$bson_id = bsonid;

Generate a new BSON id. Returns a 24 character string of hex digits that are reasonably unique across hosts and are in ascending order. Use this to create unique ids for data streams like message queues and file feeds

bsonid_time

$seconds_elapsed_since_the_epoch = bsonid_time $bson_id;

Returns the time the BSON id was generated as Unix time

bson64id

$base64_encoded_extended_bson64_id = bson64id;

Like "bsonid" but better thread long running process support. A custom Base64 encoding is used to reduce the id length

bson64id_time

$seconds_elapsed_since_the_epoch = bson64id_time $bson64_id;

Returns the time the BSON64 id was generated as Unix time

build

$code_ref = build { }, $code_ref;

Returns a code ref which when called returns the result of calling the block passing in the result of calling the optional code ref. Delays the calling of the input code ref until the output code ref is called

class2appdir

$appdir = class2appdir __PACKAGE__;

Returns lower cased "distname", e.g. App::Munchies becomes app-munchies

classdir

$dir_path = classdir __PACKAGE__;

Returns the path (directory) of a given class. Like "classfile" but without the .pm extension

classfile

$file_path = classfile __PACKAGE__ ;

Returns the path (file name plus extension) of a given class. Uses File::Spec for portability, e.g. App::Munchies becomes App/Munchies.pm

create_token

$random_hex = create_token $seed;

Create a random string token using the first available Digest algorithm. If $seed is defined then add that to the digest, otherwise add some random data. Returns a hexadecimal string

data_dumper

data_dumper $thing;

Uses Data::Printer to dump $thing in colour to stderr

distname

$distname = distname __PACKAGE__;

Takes a class name and returns it with :: changed to -, e.g. App::Munchies becomes App-Munchies

downgrade

$sv_pv = downgrade $sv_pvgv;

Horrendous Perl bug is promoting PV and PVMG type scalars to PVGV. Serializing these values with Storable throws a can't store SCALAR items error. This functions copies the string value of the input scalar to the output scalar but resets the output scalar type to PV

elapsed

$elapsed_seconds = elapsed;

Returns the number of seconds elapsed since the process started

emit

emit @lines_of_text;

Prints to STDOUT the lines of text passed to it. Lines are chomped and then have newlines appended. Throws on IO errors

emit_err

emit_err @lines_of_text;

Like "emit" but output to STDERR

emit_to

emit_to $filehandle, @lines_of_text;

Prints to the specified file handle

ensure_class_loaded

ensure_class_loaded $some_class, $options_ref;

Require the requested class, throw an error if it doesn't load

env_prefix

$prefix = env_prefix $class;

Returns upper cased app_prefix. Suitable as prefix for environment variables

escape_TT

$text = escape_TT '[% some_stash_key %]';

The left square bracket causes problems in some contexts. Substitute a less than symbol instead. Also replaces the right square bracket with greater than for balance. Template::Toolkit will work with these sequences too, so unescaping isn't absolutely necessary

exception

$e = exception $error;

Expose the catch method in the exception class CatalystX::Usul::Exception. Returns a new error object

find_apphome

$directory_path = find_apphome $appclass, $homedir, $extns

Returns the path to the applications home directory. Searches the following:

# 0.  Undef appclass and pass the directory in (short circuit the search)
# 1a. Environment variable - for application directory
# 1b. Environment variable - for config file
# 2a. Users home directory - dot file containing shell env variable
# 2b. Users home directory - dot directory is apphome
# 3.  Well known path containing shell env file
# 4.  Default install prefix
# 5a. Config file found in @INC - underscore as separator
# 5b. Config file found in @INC - dash as separator
# 6.  Pass the default in
# 7.  Default to /tmp

find_source

$path = find_source $module_name;

Find absolute path to the source code for the given module

first_char

$single_char = first_char $some_string;

Returns the first character of $string

fold

*sum = fold { $a + $b } 0;

Classic reduce function with optional base value

fqdn

$domain_name = fqdn $hostname;

Call gethostbyname on the supplied hostname whist defaults to this host

fullname

$fullname = fullname;

Returns the untainted first sub field from the gecos attribute of the object returned by a call to "get_user". Returns the null string if the gecos attribute value is false

get_cfgfiles

$paths = get_cfgfiles $appclass, $dirs, $extns

Returns an array ref of configurations file paths for the application

get_user

$user_object = get_user $optional_uid;

Returns the user object from a call to getpwuid with get User::pwent package loaded. On MSWin32 systems returns an instance of Class::Null. Defaults to the current uid but will lookup the supplied uid if provided

hex2str

$string = hex2str $pairs_of_hex_digits;

Converts the pairs of hex digits into a string of characters

home2appldir

$appldir = home2appldir $home_dir;

Strips the trailing lib/my_package from the supplied directory path

io

$io_object_ref = io $path_to_file_or_directory;

Returns a File::DataClass::IO object reference

is_arrayref

$bool = is_arrayref $scalar_variable

Tests to see if the scalar variable is an array ref

is_coderef

$bool = is_coderef $scalar_variable

Tests to see if the scalar variable is a code ref

is_hashref

$bool = is_hashref $scalar_variable

Tests to see if the scalar variable is a hash ref

is_member

$bool = is_member 'test_value', qw( a_value test_value b_value );

Tests to see if the first parameter is present in the list of remaining parameters

is_win32

$bool = is_win32;

Returns true if the $OSNAME is evil

loginid

$loginid = loginid;

Returns the untainted name attribute of the object returned by a call to "get_user" or 'unknown' if the name attribute value is false

logname

$logname = logname;

Returns untainted the first true value returned by; the environment variable USER, the environment variable LOGNAME, and the function "loginid"

merge_attributes

$dest = merge_attributes $dest, $src, $defaults, $attr_list_ref;

Merges attribute hashes. The $dest hash is updated and returned. The $dest hash values take precedence over the $src hash values which take precedence over the $defaults hash values. The $src hash may be an object in which case its accessor methods are called

my_prefix

$prefix = my_prefix $PROGRAM_NAME;

Takes the basename of the supplied argument and returns the first _ (underscore) separated field. Supplies basename with extensions

pad

$padded_str = pad $unpadded_str, $wanted_length, $pad_char, $direction;

Pad a string out to the wanted length with the $pad_char which defaults to a space. Direction can be; both, left, or right and defaults to right

prefix2class

$class = prefix2class $PROGRAM_NAME;

Calls "my_prefix" with the supplied argument, splits the result on dash, ucfirsts the list and then joins that with ::

product

$product = product 1, 2, 3, 4;

Returns the product of the list of numbers

split_on__

$field = split_on__ $string, $field_no;

Splits string by _ (underscore) and returns the requested field. Defaults to field zero

split_on_dash

$field = split_on_dash $string, $field_no;

Splits string by - (dash) and returns the requested field. Defaults to field zero

squeeze

$string = squeeze $string_containing_muliple_spacesd;

Squeezes multiple whitespace down to a single space

strip_leader

$stripped = strip_leader 'my_program: Error message';

Strips the leading "program_name: whitespace" from the passed argument

sub_name

$sub_name = sub_name $level;

Returns the name of the method that calls it

sum

$total = sum 1, 2, 3, 4;

Adds the list of values

$message = symlink $from, $to, $base;

It creates a symlink. If either $from or $to is a relative path then $base is prepended to make it absolute. Returns a message indicating success or throws an exception on failure

thread_id

$tid = thread_id;

Returns the id of this thread. Returns zero if threads are not loaded

throw

throw error => 'error_key', args => [ 'error_arg' ];

Expose "throw" in Class::Usul::Exception. Class::Usul::Constants has a class attribute Exception_Class which can be set change the class of the thrown exception

throw_on_error

throw_on_error @args;

Passes it's optional arguments to "exception" and if an exception object is returned it throws it. Returns undefined otherwise. If no arguments are passed "exception" will use the value of the global $EVAL_ERROR

trim

$trimmed_string = trim $string_with_leading_and_trailing_whitespace;

Remove leading and trailing whitespace including trailing newlines. Takes an additional string used as the character class to remove. Defaults to space and tab

unescape_TT

$text = unescape_TT '<% some_stash_key %>';

Do the reverse of escape_TT

untaint_cmdline

$untainted_cmdline = untaint_cmdline $maybe_tainted_cmdline;

Returns an untainted command line string. Calls "untaint_string" with the matching regex from CatalystX::Usul::Constants

untaint_identifier

$untainted_identifier = untaint_identifier $maybe_tainted_identifier;

Returns an untainted identifier string. Calls "untaint_string" with the matching regex from CatalystX::Usul::Constants

untaint_path

$untainted_path = untaint_path $maybe_tainted_path;

Returns an untainted file path. Calls "untaint_string" with the matching regex from CatalystX::Usul::Constants

untaint_string

$untainted_string = untaint_string $regex, $maybe_tainted_string;

Returns an untainted string or throws

uuid

$uuid = uuid( $optional_uuid_proc_filesystem_path );

Return the contents of /proc/sys/kernel/random/uuid

zip

%hash = zip @list_of_keys, @list_of_values;

Zips two list of equal size together to form a hash

Diagnostics

None

Configuration and Environment

None

Dependencies

CatalystX::Usul::Constants
Data::Printer
Digest
File::HomeDir
List::Util
Path::Class::Dir

Incompatibilities

The "home2appldir" method is dependent on the installation path containing a lib

The "uuid" method with only work on a OS with a /proc filesystem

Bugs and Limitations

There are no known bugs in this module. Please report problems to the address below. Patches are welcome

Author

Peter Flanigan, <Support at RoxSoft.co.uk>

License and Copyright

Copyright (c) 2014 Peter Flanigan. All rights reserved

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic

This program is distributed in the hope that it will be useful, but WITHOUT WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE