App::Yath::Script(3)

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