/ 
Test2-Harness-1.000174
⭐ Starred 23 / App::Yath::Util

NAME

App::Yath::Util - General utilities for yath that do not fit anywhere else.

DESCRIPTION

This package exports several tools used throughout yath that did not fit into any other package.

SYNOPSIS

use App::Yath::Util qw{
    find_pfile
    find_in_updir
    is_generated_test_pl
    fit_to_width
    isolate_stdout
    find_yath
};

EXPORTS

Note that nothing is exported by default, you must request each function to import.

$path_to_pfile = find_pfile($settings, %params)

The first argument must be an instance of Test2::Harness::Settings.

Currently the only supported param is vivify, when set to true the pfile will be created if one does not already exist.

The pfile is a file that tells yath that a persistent runner is active, and how to communicate with it.

$path_to_file = find_in_updir($file_name)

Look for $file_name in the current directory or any parent directory.

$bool = is_generated_test_pl($path_to_test_file)

Check if the specified test file was generated by the yath init command.

fit_to_width($width, $join, $text)

This will split the $text on space, and then recombine it using $join inserting newlines as necessary in an attempt to fit the text into $width horizontal characters. If any words are larger than $width they will not be split and text-wrapping may occur if used for terminal display.

$stdout = isolate_stdout()

This will close STDOUT and reopen it to point at STDERR. The result of this is that any print statement that does not specify a filehandle will print to STDERR instead of STDOUT, in addition any print directly to STDOUT will instead go to STDERR. A filehandle to the real STDOUT is returned for you to use when you actually want to write to STDOUT.

This is used by some yath processes that need to print structured data to STDOUT without letting any third part modules they may load write to the real STDOUT.

$path_to_script = find_yath()

This will attempt to find the yath command line script. When possible this will return the path that was used to launch yath. If $App::Yath::Script::SCRIPT is not set the following are searched, in order:

The YATH_SCRIPT environment variable

The yath script sets this, so it identifies the script that launched the current process tree. Under a yath run this also covers a checkout's own script: App::Yath::Script re-execs into an executable ./scripts/yath of its own accord when the current directory has one, and the script it re-execs into sets this variable to itself.

<base>/blib/script for any <base>/blib/lib or <base>/blib/arch in @INC

This finds the script when the App::Yath::Script distribution is being used uninstalled from its build directory, as CPAN smokers do.

The paths specified in the Config module
<base>/bin for any <base>/lib/perl5 in @INC

Anything after lib/perl5 is ignored, so <base>/lib/perl5/5.36.0/x86_64-linux also gives <base>/bin. This finds the script in a local::lib or cpanm -l tree.

The PATH environment variable

Every candidate but the PATH ones only needs to be readable, because the script is run as an argument to perl rather than executed. A candidate found via PATH must also be executable.

This will throw an exception if the script cannot be found. The exception lists every path that was checked, along with the current directory, @INC, PATH, and PERL5LIB, so the missing case can be reported.

Note: The result is cached so that subsequent calls will return the same path even if something installs a new yath script in another location that would otherwise be found first. This guarantees that a single process will not switch scripts.

SOURCE

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

MAINTAINERS

Chad Granum <exodist7@gmail.com>

AUTHORS

Chad Granum <exodist7@gmail.com>

COPYRIGHT

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/