PUBLIC

Bedrock - Set of useful utilities used throughout Bedrock

SYNOPSIS

use Bedrock qw(:all);

my $text = slurp_file 'foo.txt';

DESCRIPTION

This module contains a group of useful utilities used throughout Bedrock. They are documented here so that you can use them too!

Including this module in your script will also add the necessary paths to @INC that will allow you to use other documented modules inside of Bedrock.

Why Does Bedrock Hack @INC?

In short, the module hierarchy is deep. Modifying @INC allows for cleaner, more readable use statements within the application logic:

use TagX::TAG;

rather than...

use Bedrock::Text::TagX::TAG;

...or even more deeply into the hierarchy...

use TagX::TAG::WithBody::If;

rather than...

use Bedrock::Text::TagX::TAG::WithBody::If;

EXPORT TAGS

:all

:booleans, :file, force_array

:booleans

is_array
is_bedrock_array
is_bedrock_hash
is_blessed
is_hash
is_regexp
is_scalar
to_boolean

:file

create_temp_file
find_in_path
resolve_stream
slurp_file

EXPORTED VARIABLES

$BEDROCK_DIST_DIR

The absolute path to the installed Bedrock distribution directory (e.g., /usr/local/share/perl/5.34/auto/share/dist/Bedrock-Core).

This is determined dynamically via File::ShareDir and is useful for locating shared assets, default configuration files, or templates shipped with the distribution.

use Bedrock qw($BEDROCK_DIST_DIR);

my $default_conf = "$BEDROCK_DIST_DIR/config/log4perl.conf";

METHODS AND SUBROUTINES

Methods on Objects

is_array

Equivalent to:

ref $x && reftype($x) eq 'ARRAY'

is_bedrock_array

Equivalent to:

ref $x && ref($x) eq 'Bedrock::Array'

is_bedrock_hash

Equivalent to:

ref $x && ref($x) eq 'Bedrock::Hash'

is_blessed

Equivalent to:

ref $x && blessed($x)

is_hash

Equivalent to:

ref $x && reftype($x) eq 'HASH'

is_regexp

Equivalent to:

ref $x && ref($x) eq 'Regexp'

is_scalar

Equivalent to:

ref $x

Methods on Files

create_temp_dir

create_temp_dir(options)

Creates a temporary directory (and optional sub-directories), populating them with files specified in a manifest. Returns the name of the temporary directory created.

• cleanup

  Boolean that indicates that the directory and all files beneath it should be removed when the program terminates.

• manifest

  Reference to an array of hash reference where each element of the hash represent a set of files to be copied from a soruce to a sub-directory of the temporary directory.

  • source

    Source of the files to copy.

  • dest_dir

    Destination directory. If omitted, files are copied to the root of the temporary directory.

  • files

    List of file names to copy.

• dir

find_in_path

find_in_path(options)

In list context, returns a list of absolute paths to files found in a list of paths, filtered by a pattern or file name. In scalar context, returns the number of files found.

Either file or pattern is required. Options are described below:

• max_items

  Maximum number of items to return.

• find_one

  Equivalent to max_items => 1.

• path_list

  An array reference to a list of paths to search. If no path_list is passed or the list is empty, the current working directory (and its sub-directories) will be traversed.

• file

  The name of the file to search for.

• pattern

  A regular expression that will be used as a filter.

Examples:

Find the first occurrence of file foo in current working directory ( and sub-directories ).

my ($file) = find_in_path(file => 'foo', max_items => 1);

Roughly equivalent to:

$ find . -name foo

Find all files named foo in a list of directories.

my @files = find_in_path( file => 'foo', path_list => [ $ENV{PATH} ] );

Find all .xml files in list of directories.

my @xml_files = find_in_path(pattern => qr/[.]xml$/, path_list => [$ENV{CONFIG_PATH}]);

resolve_stream

resolve_stream(filename|filehandle|text)

Returns a filehandle by examining the passed argument and determining an action to take based on its type. Throws an exception if the file or text reference cannot be opened for reading.

NOTE: This is a handy tool when you want to create a method or class that requires a stream and you want to support multiple input types.

• filename => open the file and return a filehandle
• filehandle => return the passed argument

• text => open a handle to the text reference

  NOTE: You should pass a reference to a scalar object (text), not a text string. As a convenience, if you happen to forget and do not pass a text reference AND it contains new lines, the method will store the text in a scalar and return a handle to it. However, it will emit a warning, as you should strictly pass scalar references for content.

slurp_file

slurp_file(filename|handle)

In scalar context returns entire contents of a file. In list context returns a list of the lines in the file. Throws an exception if the file cannot be opened.

WARNING: If use this method and it returns an integer you likely called the method in list context and assigned the result to a scalar!

slurp_json

slurp_json(filename|handle)

Returns a Perl object from a JSON file.

MISCELLANEOUS

choose

choose { ... }

Executes a block of code and returns the result. This utility is particularly useful for creating a localized scope where a return statement will exit the block (returning a value to the caller of choose) rather than exiting the enclosing subroutine. It preserves the calling context (scalar vs list).

# $val gets the result of the logic block
my $val = choose {
    return 'A' if $condition;
    return 'B';
};

force_array

force_array(@_)

Returns a reference to an array that contains the passed parameter(s). If the passed value is already an array reference it is simply returned. This method is useful for ensuring a value is a reference or creating a new array reference from a list.

my $array = force_array(@_);

grab_bag

grab_bag( \@array_of_hashes, @keys )

Extracts specific keys from a list of hash references. Returns a new list of anonymous hash references containing only the requested keys and their values.

my $users = [
  { id => 1, user => 'fred', password => '123' },
  { id => 2, user => 'wilma', password => '456' }
];

# Returns: [ { user => 'fred' }, { user => 'wilma' } ]
my $safe_list = grab_bag( $users, 'user' );

muddle

muddle( $string )

Obfuscates a string by masking all characters except the first and the last with asterisks. Useful for logging sensitive data like tokens or passwords without revealing the full value. If the string is 2 characters or less, it is returned unchanged.

# Returns 's****t'
muddle('secret');

to_boolean

to_boolean('yes')

Converts a string (case insensitive) that represents a boolean into a 0 or 1.

true  => 1
false => 0
yes   => 1
no    => 0
on    => 1
off   => 0
'0'   => 0
'1'   => 1

to_loglevel

to_loglevel(level)

Converts a numeric verbosity level or string representing a log level to a Log4perl log level.

Verbosity levels supported are:

0 = error
1 = warn
2 = info
3 = debug
4 = trace

Any numeric level higher than 4 is treated as 'trace'.

String log levels (case insensitive):

error
warn
info
debug
trace

Any string other than those above will be converted to the 'error' level.

to_regexp

Returns a compiled regular expression from a string of the forms:

'some text'
'qr/some text/'

Examples:

my $re = to_regexp('^#');
my $re = to_regexp('qr/^package\s[^;]+;$/xsm');

AUTHOR

Rob Lauer - bigfoot@cpan.org