Class::Usul::Functions - Globally accessible functions
package MyBaseClass; use Class::Usul::Functions qw( functions to import );
Provides globally accessible functions
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
App::Munchies
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
BSON
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
BSON64
canonicalise
$untainted_canonpath = canonicalise $base, $relpath;
Appends $relpath to $base using File::Spec::Functions. The $base and $relpath arguments can be an array reference or a scalar. The return path is untainted and canonicalised
$relpath
$base
class2appdir
$appdir = class2appdir __PACKAGE__;
Returns lower cased "distname", e.g. App::Munchies becomes app-munchies
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
App/Munchies.pm
create_token
$random_hex = create_token $optional_seed;
Create a random string token using "digest". If $seed is defined then add that to the digest, otherwise add some random data provided by a call to "urandom". Returns a hexadecimal string
$seed
create_token64
$random_base64 = create_token64 $optional_seed;
Like "create_token" but the output is base64 encoded
base64
cwdp
$current_working_directory = cwdp;
Returns the current working directory, physical location
dash2under
$string_with_underscores = dash2under 'a-string-with-dashes';
Substitutes underscores for dashes
data_dumper
data_dumper $thing;
Uses Data::Printer to dump $thing in colour to stderr
$thing
digest
$digest_object = digest $seed;
Creates an instance of the first available Digest class and adds the seed. The constant DIGEST_ALGORITHMS is consulted for the list of algorithms to search for. Returns the digest object reference
DIGEST_ALGORITHMS
distname
$distname = distname __PACKAGE__;
Takes a class name and returns it with :: changed to -, e.g. App::Munchies becomes App-Munchies
App-Munchies
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
chomp
emit_err
emit_err @lines_of_text;
Like "emit" but output to STDERR
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 Class::Usul::Exception. Returns a new error object
catch
find_apphome
$directory_path = find_apphome $appclass, $homedir, $extns
Returns the path to the applications home directory. Searches the following:
# 0. Pass the directory in (short circuit the search) # 1a. Environment variable - for application directory # 1b. Environment variable - for config file # 2a. Users XDG_DATA_HOME env variable or XDG default share directory # 2b. Users home directory - dot file containing shell env variable # 2c. 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. 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
$string
fqdn
$domain_name = fqdn $hostname;
Call gethostbyname on the supplied hostname whist defaults to this host
gethostbyname
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_or_name;
Returns the user object from a call to either getpwuid or getpwnam depending on whether an integer or a string was passed. The User::pwent package is loaded so objects are returned. On MSWin32 systems returns an instance of Class::Null. Defaults to the current uid but will lookup the supplied uid if provided
getpwuid
getpwnam
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
lib/my_package
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_ntfs
$bool = is_ntfs;
Returns true if "is_win32" is true or the $OSNAME is cygwin
$OSNAME
is_win32
$bool = is_win32;
Returns true if the $OSNAME is unfortunate
list_attr_of
$attribute_list = list_attr_of $object_ref, @exception_list;
Lists the attributes of the object reference, including defining class name, documentation, and current value
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;
Deprecated. Returns untainted the first true value returned by; the environment variable USER, the environment variable LOGNAME, and the function "loginid"
USER
LOGNAME
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
$dest
$src
$defaults
nonblocking_write_pipe_pair
$array_ref = non_blocking_write_pipe;
Returns a pair of file handles, read then write. The write file handle is non blocking, binmode is set on both
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
ns_environment
$value = ns_environment $class, $key, $value;
An accessor / mutator for the environment variables prefixed by the supplied class name. Providing a value is optional, always returns the current value
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
$pad_char
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 ::
ucfirst
join
socket_pair
($reader, $writer) = @{ socket_pair };
Return a socketpair reader then writer. The writer has been closed on the reader and the reader has been closed on the writer
socketpair
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
symlink
$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
thread_id
$tid = thread_id;
Returns the id of this thread. Returns zero if threads are not loaded
throw
throw 'error_message', [ '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
$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 Class::Usul::Constants
untaint_identifier
$untainted_identifier = untaint_identifier $maybe_tainted_identifier;
Returns an untainted identifier string. Calls "untaint_string" with the matching regex from Class::Usul::Constants
untaint_path
$untainted_path = untaint_path $maybe_tainted_path;
Returns an untainted file path. Calls "untaint_string" with the matching regex from Class::Usul::Constants
untaint_string
$untainted_string = untaint_string $regex, $maybe_tainted_string;
Returns an untainted string or throws
urandom
$bytes = urandom $optional_length, $optional_provider;
Returns random bytes. Length defaults to 64. The provider defaults to /dev/urandom and can be any type accepted by "io". If the provider exists and is readable, length bytes are read from it and returned. Otherwise some bytes from the second best generator are returned
uuid
$uuid = uuid $optional_uuid_proc_filesystem_path;
Return the contents of /proc/sys/kernel/random/uuid
whiten
$encoded = whiten 'plain_text_to_be_obfuscated';
Lifted from Acme::Bleach this function encodes the passed scalar as spaces, tabs, and newlines. The encrypt and decrypt functions take a seed attribute in their options hash reference. A whitened line of Perl code would be a suitable value
zip
%hash = zip @list_of_keys, @list_of_values;
Zips two list of equal size together to form a hash
chain
$result = chain $sub1, $sub2, $sub3
Call each sub in turn passing the returned value as the first argument to the next function call
compose
$code_ref = compose { }, $code_ref;
Returns a code reference which when called returns the result of calling the block passing in the result of calling the optional code reference. Delays the calling of the input code reference until the output code reference is called
curry
$curried_code_ref = curry $code_ref, @args; $result = $curried_code_ref->( @more_args );
Returns a subroutine reference which when called, calls and returns the initial code reference passing in the original argument list and the arguments from the curried call. Must be called with a code reference and at least one argument
fold
*sum = fold { $a + $b } 0;
Classic reduce function with optional base value
Y
$code_ref = Y( $code_ref );
The Y-combinator function
factorial
$result = factorial $n;
Calculates the factorial for the supplied integer
fibonacci
$result = fibonacci $n;
Calculates the Fibonacci number for the supplied integer
product
$product = product 1, 2, 3, 4;
Returns the product of the list of numbers
sum
$total = sum 1, 2, 3, 4;
Adds the list of values
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, <pjfl@cpan.org>
<pjfl@cpan.org>
Copyright (c) 2017 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.