App-Yath-Script/README at script · Test-More/App-Yath-Script · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
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. Only paths are preserved; @INC hooks cannot cross an exec and
      are reinstalled in the new process by whatever added them.

    $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/App-Yath-Script/.

MAINTAINERS

    Chad Granum <exodist7@gmail.com>

AUTHORS

    Chad Granum <exodist7@gmail.com>

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/