NAME

App::Ariza::Resources - find ariza's own bundled data files, installed or in a checkout

SYNOPSIS

use App::Ariza::Resources;

# One file, by its META6 `resources` key:
my $toml = resource('versions.toml').slurp;
my $tpl  = resource('templates/launcher-posix.sh.j2').slurp;

# Everything under a directory:
for resource-list('templates/ci') -> $rel {
    say $rel;                       # templates/ci/release.yml.j2
    say resource($rel).slurp;
}

# Where the checkout is, if this is a checkout at all:
with checkout-root() -> $root {
    say "running from source at $root";
}

DESCRIPTION

ariza ships data — Jinja2 templates, shell partials, the pinned versions.toml — and has to read it in two very different worlds:

• Installed. zef install copies every file listed in META6 resources into the installation's resource store under a content-hashed name. The original directory structure is gone; %?RESOURCES{'templates/launcher-posix.sh.j2'} is the only way back to the bytes.

• A source checkout. Running raku -Ilib bin/ariza ... from the distribution directory usually leaves %?RESOURCES unpopulated, but the files are sitting right there in resources/.

Every module in ariza reads its data through this one module so that neither world is a special case anywhere else, and so that "I added a resource but forgot to list it in META6" fails the same way everywhere: loudly, naming the path it tried.

SUBROUTINES

resource(Str $rel --> IO::Path)

Resolve a distribution-relative resource path to a real, existing IO::Path. $rel is exactly the string used as the META6 resources entry, always with forward slashes and never with a leading resources/.

Order of attempts:

• %?RESOURCES{$rel}, if it yields a path that exists.

• < <checkout-root>/resources/$rel >, if a checkout was found and the file exists.

Dies otherwise. The message names the path that was tried, since the cause is nearly always a resource that exists on disk but is missing from META6 resources — in which case the installed distribution simply does not contain it.

Only files count. A $rel that names a directory — templates/ci rather than templates/ci/release.yml.j2 — dies like any other missing resource. That is not pedantry: installed, Distribution::Resources answers any key with a resource whose path degrades to the resource store directory, so without this rule a mistyped path would come back as a real, existing directory and fail much later as something inexplicable ("malformed TOML in .../resources").

resource-list(Str $prefix --> List)

The sorted, distribution-relative paths of every resource file directly under $prefix (one level; subdirectories are not descended into). Returns an empty list for a prefix with no resources.

The paths come back with forward slashes on every platform, including Windows. They are META6 resources keys — the strings you hand back to resource, and the strings the manifest is written with — rather than paths into the filesystem, so the separator is fixed by the packaging spec and not by the machine. The checkout branch walks a real directory and normalises before returning.

In a checkout this is a directory read, so a file you have just created shows up before you have listed it in META6. Installed, it comes from < $?DISTRIBUTION.meta<resources> >, so it shows exactly what was packaged. That asymmetry is deliberate and useful: development sees the working tree, production sees the manifest.

checkout-root(--> IO::Path)

The distribution root when running from source, or the undefined IO::Path type object when running installed. Test with with:

with checkout-root() -> $root {
    # e.g. reach a sibling app repository checked out next to ariza
    my $app = $root.parent.add('App-Moneymoor');
}

Detection is structural rather than environmental: the path four parents above this source file must still have a resources/ directory next to it. An installed copy of the module lives under the repository's sources/ store, where that is not true.

AUTHOR

Matt Doughty

COPYRIGHT AND LICENSE

Copyright 2026 Matt Doughty

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.