--- name: "Test2::Harness::Util" section: "3pm" platform: "linux" package: "libtest2-harness-perl" version: "1.000158-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Test2::Harness::Util" --- # Test2::Harness::Util(3pm) General utiliy functions. ## NAME Test2::Harness::Util - General utiliy functions. ## DESCRIPTION ## METHODS ### MISC - apply\_encoding($fh, $enc) Apply the specified encoding to the filehandle. **Justification**: PERLBUG 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 \ ## AUTHORS - Chad Granum \ ## COPYRIGHT Copyright 2020 Chad Granum \. 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/*