/ 
App-Yath-Script-2.000016
/ App::Yath::Script

NAME

App::Yath::Script - Script initialization and utility functions for Test2::Harness

SYNOPSIS

The yath script uses this module as its entry point:

#!/usr/bin/perl
use strict;
use warnings;

BEGIN {
    return if $^C;
    require App::Yath::Script;
    App::Yath::Script::do_begin();
}

exit(App::Yath::Script::do_runtime());

DESCRIPTION

This module provides the initial entry point for the yath script. It handles script discovery, configuration loading, version detection, and delegation to version-specific script modules (App::Yath::Script::V{X}).

During the BEGIN phase, do_begin() locates .yath.rc and .yath.user.rc configuration files, determines the harness version to use, and delegates to the appropriate App::Yath::Script::V{X} module. At runtime, do_runtime() hands off execution to that module.

Version Detection

A version may come from any of these sources, in priority order: an explicit V# / v# as the first CLI argument, the rc files found walking upward from the cwd, a working-copy checkout under ./lib/App/Yath/Script/V#.pm, or finally the highest App::Yath::Script::V# module installed in @INC. V0 is reserved for script validation, is never auto-selected, and must be requested explicitly.

When walking upward, each directory is scanned in this order:

  1. A .yath.rc symlink whose target filename matches .yath.v#.rc / .yath.V#.rc -- the version is extracted from the target name. This lets projects keep a stable .yath.rc name while pointing at the versioned file.

  2. Explicitly versioned files .yath.v#.rc / .yath.V#.rc -- the highest version present in the directory wins, both for the chosen rc file and the captured version.

  3. A plain .yath.rc (not a symlink to a versioned file) -- the rc file is used but no version is captured; the caller falls through to the checkout / @INC sources above.

The same priority applies to user-level configuration (.yath.user.rc / .yath.user.v#.rc).

If both project-level and user-level rc files capture a version, the user-level version takes precedence. This allows individual developers to override the project-level version when needed.

When an explicit V# is given on the CLI, the lookup prefers a matching versioned rc file but falls back to a plain .yath.rc / .yath.user.rc if no versioned file is found.

PRIMARY API

These are the main entry points used by the yath script:

do_begin()

Called during BEGIN. Discovers the script path, injects include paths, loads .yath.rc / .yath.user.rc configuration files, determines the harness version, and delegates to App::Yath::Script::V{X}->do_begin(...).

$exit = do_runtime()

Called after BEGIN. Delegates to App::Yath::Script::V{X}->do_runtime() and returns the exit code.

EXPORTS

All exports are optional (via Importer).

$script_file = script()

Returns the path to the currently executing script file.

$yath_module = module()

Returns the name of the currently loaded App::Yath::Script::V{X} module.

do_exec(\@argv)

Re-executes the current script with the given arguments. Sets the T2_HARNESS_INCLUDES environment variable to preserve the current @INC.

$clean_path = clean_path($path)
$clean_path = clean_path($path, $absolute)

Converts a path to an absolute, normalized form. By default resolves symbolic links using realpath. Pass a false second argument to skip realpath resolution.

$full_path = find_in_updir($file)

Searches for a file starting from the current directory and moving up through parent directories until found. Returns the full path to the file or undef if not found.

$file = mod2file($mod)

Converts a module name (e.g., App::Yath::Script) to a file path (e.g., App/Yath/Script.pm).

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

Copyright 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/