MISC

apply_encoding($fh, $enc)

Apply the specified encoding to the filehandle.

Justification: PERLBUG 31923 <https://rt.perl.org/Public/Bug/Display.html?id=31923> If utf8 is requested we use ':utf8' instead of ':encoding(utf8)' in order to avoid the thread segfault.

This is a reusable implementation of this:

    sub apply_encoding {
        my ($fh, $enc) = @_;
        return unless $enc;
        return binmode($fh, ":utf8") if $enc =~ m/^utf-?8$/i;
        binmode($fh, ":encoding($enc)");
    }
    

$clean = clean_path($path)

Take a file path and clean it up to a minimal absolute path if possible. Always returns a path, but if it cannot be cleaned up it is unchanged.

$hashref = find_libraries($search)

$hashref = find_libraries($search, @paths)

@INC is used if no @paths are provided.

$search should be a module name with "*" wildcards replacing sections.

    find_libraries('Foo::*::Baz')
    find_libraries('*::Bar::Baz')
    find_libraries('Foo::Bar::*')
    

These all look for modules matching the search, this is a good way to find plugins, or similar patterns.

The result is a hashref of "{ $module => $path }". If a module exists in more than 1 search path the first is used.

$mod = fqmod($prefix, $mod)

This will automatically add $prefix to $mod with '::' to join them. If $mod starts with the '+' character the character will be removed and the result returned without prepending $prefix.

hub_truth

This is an internal implementation detail, do not use it.

$hashref = parse_exit($?)

This parses the exit value as typically stored in $?.

Resulting hash:

    {
        sig => ($? & 127), # Signal value if the exit was caused by a signal
        err => ($? >> 8),  # Actual exit code, if any.
        dmp => ($? & 128), # Was there a core dump?
        all => $?,         # Original exit value, unchanged
    }
    

@list = process_includes(%PARAMS)

This method will build up a list of include dirs fit for @INC. The returned list should contain only unique values, in proper order.

Params:

FOR DEALING WITH MODULE <-> FILE CONVERSION

These convert between module names like "Foo::Bar" and filenames like "Foo/Bar.pm".

$file = mod2file($mod)

$mod = file2mod($file)

FOR READING/WRITING FILES

$fh = open_file($path, $mode)

$fh = open_file($path)

If no mode is provided '<' is assumed.

This will open the file at $path and return a filehandle.

An exception will be thrown if the file cannot be opened.

NOTE: This will automatically use IO::Uncompress::Bunzip2 or IO::Uncompress::Gunzip to uncompress the file if it has a .bz2 or .gz extension.

$text = read_file($file)

This will open the file at $path and return all its contents.

An exception will be thrown if the file cannot be opened.

NOTE: This will automatically use IO::Uncompress::Bunzip2 or IO::Uncompress::Gunzip to uncompress the file if it has a .bz2 or .gz extension.

$fh = maybe_open_file($path)

$fh = maybe_open_file($path, $mode)

If no mode is provided '<' is assumed.

This will open the file at $path and return a filehandle.

"undef" is returned if the file cannot be opened.

NOTE: This will automatically use IO::Uncompress::Bunzip2 or IO::Uncompress::Gunzip to uncompress the file if it has a .bz2 or .gz extension.

$text = maybe_read_file($path)

This will open the file at $path and return all its contents.

This will return "undef" if the file cannot be opened.

NOTE: This will automatically use IO::Uncompress::Bunzip2 or IO::Uncompress::Gunzip to uncompress the file if it has a .bz2 or .gz extension.

@content = write_file($path, @content)

Write content to the specified file. This will open the file with mode '>', write the content, then close the file.

An exception will be thrown if any part fails.

@content = write_file_atomic($path, @content)

This will open a temporary file, write the content, close the file, then rename the file to the desired $path. This is essentially an atomic write in that $file will not exist until all content is written, preventing other processes from doing a partial read while @content is being written.