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/