App::Y...:Script(3pm)

💖 App::Yath::Script — bestie edition 💖

okay so real talk, this is App::Yath::Script, from the User Contributed Perl Documentation section of your friendly neighborhood perl man pages. it lives inside Test2::Harness and it's basically the little bouncer standing at the door of the yath script. let's get into it 🫶

---

✨ NAME ✨

App::Yath::Script — script initialization and utility functions for Test2::Harness, no cap 💅

---

🌸 SYNOPSIS 🌸

the yath script literally uses this module as its entry point, like that's the whole job:

#!/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 🦋

so this module is the initial entry point for the yath script. it's the one handling script discovery, configuration loading, version detection, and then hand-off to version-specific script modules — those live at App::Yath::Script::V{X} 🎀

during the BEGIN phase, do_begin() goes and locates .yath.rc and .yath.user.rc config files, figures out which harness version to use, and delegates to the right App::Yath::Script::V{X} module. then at runtime, do_runtime() passes execution off to that module. that's the whole vibe 🔥

👑 Version Detection 👑

a version can come from any of these sources, and yes the order matters — this is priority order, bestie:

1. an explicit V# / v# as the first CLI argument
2. the rc files found walking upward from the cwd
3. a working-copy checkout under ./lib/App/Yath/Script/V#.pm
4. finally, the highest App::Yath::Script::V# module installed in @INC

and here's the tea ☕ V0 is reserved for script validation, it is never auto-selected, and it must be requested explicitly. periodt.

when walking upward, each directory gets scanned in this order:

1. A .yath.rc symlink whose target filename matches .yath.v#.rc / .yath.V#.rc — the version gets extracted from the target name. this is so projects can keep a stable .yath.rc name while pointing at the versioned file. iconic, honestly.
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 exact same priority applies to user-level configuration (.yath.user.rc / .yath.user.v#.rc) 💜

now if both project-level and user-level rc files capture a version? the user-level version takes precedence. that's so individual devs can override the project-level version when they need to. slay, honestly 🌈

and when an explicit V# is given on the CLI, the lookup prefers a matching versioned rc file — but it falls back to a plain .yath.rc / .yath.user.rc if no versioned file is found. flexible queen 💅

---

💫 PRIMARY API 💫

these are the main entry points the yath script actually uses:

• do_begin() — called during BEGIN. it discovers the script path, injects include paths, loads .yath.rc / .yath.user.rc configuration files, figures out the harness version, and delegates to App::Yath::Script::V{X}->do_begin(...). the whole opening act 🎬
• $exit = do_runtime() — called after BEGIN. it delegates to App::Yath::Script::V{X}->do_runtime() and returns the exit code. that's it, that's the function ✨

---

🎀 EXPORTS 🎀

okay so all exports are optional (via Importer), nobody's forcing anything on you 🫶

• $script_file = script() — returns the path to the currently executing script file. where am i? this function knows.
• $yath_module = module() — returns the name of the currently loaded App::Yath::Script::V{X} module. identity check 💅
• do_exec(\@argv) — re-executes the current script with the given arguments. it sets the T2_HARNESS_INCLUDES environment variable to preserve the current @INC. so it keeps the receipt of where everything came from 🧾
• $clean_path = clean_path($path) / $clean_path = clean_path($path, $absolute) — converts a path to an absolute, normalized form. by default it resolves symbolic links using realpath. pass a false second argument to skip realpath resolution. choose your fighter ✨
• $full_path = find_in_updir($file) — searches for a file starting from the current directory and moving up through parent directories until it's found. returns the full path to the file, or undef if it's not found. if you're lost, it'll find you 🌸
• $file = mod2file($mod) — converts a module name (e.g., App::Yath::Script) to a file path (e.g., App/Yath/Script.pm). glow-up transformation 🔄

---

💜 SOURCE 💜

the source code repository for Test2-Harness can be found at <http://github.com/Test-More/Test2-Harness/> — go look, bestie 👀

---

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

---

and that's the whole page, babes 💖 this was perl v5.40.1, dated 2026-05-10, and yep, it really is App::Yath::Script(3pm) from your User Contributed Perl Documentation. go forth and yath responsibly 🫶✨🎀