plucky (3) Test2::Harness::Util.3pm.gz

Provided by: libtest2-harness-perl_1.000156-1_all bug

NAME

       Test2::Harness::Util - General utiliy functions.

DESCRIPTION

METHODS

   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:

           list => \@START
               Paths to start the new list.

               Optional.

           ch_dir => $path
               Prefix to prepend to all paths in the "list" param. No effect without an initial list.

           include_current => $bool
               This will add all paths from @INC to the output, after the initial list.  Note that '.', if in
               @INC will be moved to the end of the final output.

           clean => $bool
               If included all paths except '.' will be cleaned using clean_path().

           include_dot => $bool
               If true '.' will be appended to the end of the output.

               Note even if this is set to false '.' may still be included if it was in the initial list, or if
               it was in @INC and @INC was included using the "include_current" parameter.

   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.

SOURCE

       The source code repository for Test2-Harness can be found at http://github.com/Test-More/Test2-Harness/.

MAINTAINERS

       Chad Granum <exodist@cpan.org>

AUTHORS

       Chad Granum <exodist@cpan.org>

       Copyright 2020 Chad Granum <exodist7@gmail.com>.

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

       See http://dev.perl.org/licenses/