CatalystX::Usul::Functions - Globally accessible functions
package MyBaseClass; use CatalystX::Usul::Functions;
Provides globally accessible functions
$absolute_untainted_path = abs_path $some_path;
Untaints path. Makes it an absolute path and returns it. Returns undef otherwise. Traverses the filesystem
$prefix = app_prefix __PACKAGE__;
Takes a class name and returns it lower cased with :: changed to _, e.g. App::Munchies becomes app_munchies
App::Munchies
app_munchies
$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 $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
$untainted_path = assert_directory $path_to_directory;
Untaints directory path. Makes it an absolute path and returns it if it exists. Returns undef otherwise
$decoded_value = base64_decode_ns $encoded_value;
Decode a scalar value encode using 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)
$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
BSON
$seconds_elapsed_since_the_epoch = bsonid_time $bson_id;
Returns the time the BSON id was generated as Unix time
$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
$seconds_elapsed_since_the_epoch = bson64id_time $bson64_id;
Returns the time the BSON64 id was generated as Unix time
BSON64
$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
$appdir = class2appdir __PACKAGE__;
Returns lower cased "distname", e.g. App::Munchies becomes app-munchies
app-munchies
$dir_path = classdir __PACKAGE__;
Returns the path (directory) of a given class. Like "classfile" but without the .pm extension
$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
App/Munchies.pm
$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
$seed
data_dumper $thing;
Uses Data::Printer to dump $thing in colour to stderr
$thing
$distname = distname __PACKAGE__;
Takes a class name and returns it with :: changed to -, e.g. App::Munchies becomes App-Munchies
App-Munchies
$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
PV
PVMG
PVGV
$elapsed_seconds = elapsed;
Returns the number of seconds elapsed since the process started
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
chomp
emit_err @lines_of_text;
Like "emit" but output to STDERR
STDERR
emit_to $filehandle, @lines_of_text;
Prints to the specified file handle
ensure_class_loaded $some_class, $options_ref;
Require the requested class, throw an error if it doesn't load
$prefix = env_prefix $class;
Returns upper cased app_prefix. Suitable as prefix for environment variables
app_prefix
$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
$e = exception $error;
Expose the catch method in the exception class CatalystX::Usul::Exception. Returns a new error object
catch
$directory_path = find_apphome $appclass, $homedir, $extns
Returns the path to the applications home directory
$path = find_source $module_name;
Find absolute path to the source code for the given module
$single_char = first_char $some_string;
Returns the first character of $string
$string
*sum = fold { $a + $b } 0;
Classic reduce function with optional base value
$domain_name = fqdn $hostname;
Call gethostbyname on the supplied hostname whist defaults to this host
gethostbyname
$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
$paths = get_cfgfiles $appclass, $dirs, $extns
Returns an array ref of configurations file paths for the application
$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
getpwuid
$string = hex2str $pairs_of_hex_digits;
Converts the pairs of hex digits into a string of characters
$appldir = home2appldir $home_dir;
Strips the trailing lib/my_package from the supplied directory path
lib/my_package
$io_object_ref = io $path_to_file_or_directory;
Returns a File::DataClass::IO object reference
$bool = is_arrayref $scalar_variable
Tests to see if the scalar variable is an array ref
$bool = is_coderef $scalar_variable
Tests to see if the scalar variable is a code ref
$bool = is_hashref $scalar_variable
Tests to see if the scalar variable is a hash ref
$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
$bool = is_win32;
Returns true if the $OSNAME is evil
$OSNAME
$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;
Returns untainted the first true value returned by; the environment variable USER, the environment variable LOGNAME, and the function "loginid"
USER
LOGNAME
$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
$dest
$src
$defaults
$prefix = my_prefix $PROGRAM_NAME;
Takes the basename of the supplied argument and returns the first _ (underscore) separated field. Supplies basename with extensions
$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
$pad_char
$class = prefix2class $PROGRAM_NAME;
Calls "my_prefix" with the supplied argument, splits the result on dash, ucfirsts the list and then joins that with ::
ucfirst
join
$product = product 1, 2, 3, 4;
Returns the product of the list of numbers
$field = split_on__ $string, $field_no;
Splits string by _ (underscore) and returns the requested field. Defaults to field zero
$field = split_on_dash $string, $field_no;
Splits string by - (dash) and returns the requested field. Defaults to field zero
$string = squeeze $string_containing_muliple_spacesd;
Squeezes multiple whitespace down to a single space
$stripped = strip_leader 'my_program: Error message';
Strips the leading "program_name: whitespace" from the passed argument
$sub_name = sub_name $level;
Returns the name of the method that calls it
$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
$from
$to
$base
$tid = thread_id;
Returns the id of this thread. Returns zero if threads are not loaded
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 @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
$EVAL_ERROR
$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
$text = unescape_TT '<% some_stash_key %>';
Do the reverse of escape_TT
escape_TT
$untainted_cmdline = untaint_cmdline $maybe_tainted_cmdline;
Returns an untainted command line string. Calls "untaint_string" with the matching regex from CatalystX::Usul::Constants
$untainted_identifier = untaint_identifier $maybe_tainted_identifier;
Returns an untainted identifier string. Calls "untaint_string" with the matching regex from CatalystX::Usul::Constants
$untainted_path = untaint_path $maybe_tainted_path;
Returns an untainted file path. Calls "untaint_string" with the matching regex from CatalystX::Usul::Constants
$untainted_string = untaint_string $regex, $maybe_tainted_string;
Returns an untainted string or throws
$uuid = uuid( $optional_uuid_proc_filesystem_path );
Return the contents of /proc/sys/kernel/random/uuid
%hash = zip @list_of_keys, @list_of_values;
Zips two list of equal size together to form a hash
None
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
There are no known bugs in this module. Please report problems to the address below. Patches are welcome
Peter Flanigan, <Support at RoxSoft.co.uk>
<Support at RoxSoft.co.uk>
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
To install Class::Usul, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Class::Usul
CPAN shell
perl -MCPAN -e shell install Class::Usul
For more information on module installation, please visit the detailed CPAN module installation guide.