Dir::Manifest(3pm)

📦
version 0.6.1 · 2 versions
, in fedora 43

💖 Dir::Manifest — the perl manpage, bestie edition ✨

okay so you're reading the User Contributed Perl Documentation for Dir::Manifest, and honestly? it's giving "I keep all my test fixtures in one folder and I want them to be cute and safe." let's get into it 🫶

🌸 NAME 🌸

Dir::Manifest — treat a directory and a manifest file as a hash/dictionary of keys to texts or blobs.

that's the whole vibe. a whole folder, but make it a lookup table. 💅

✨ VERSION ✨

version 0.6.1 — iconic, current, slaying.

🎀 SYNOPSIS 🎀

bestie, here's the whole thing in code, untouched, exactly as the module intends:

use Dir::Manifest ();

my $obj = Dir::Manifest->new(
    {
        manifest_fn => "./t/data/texts/list.txt",
        dir         => "./t/data/texts/texts",
    }
);

# Or alternatively:
my $obj = Dir::Manifest->dwim_new(
    {
        base => "./t/data/texts",
    }
);

# TEST
is (
    scalar(`my-process ...`),
    $obj->text("my-process-output1", {lf => 1,}),
    "Good output of my-process.",
);

look at her go. 💖

🦋 DESCRIPTION 🦋

okay so the primary use case, and I need you to lock in: you have several long texts (and/or binary blobs) that you wish to load from the code — like, say, for the want/expected values of tests — and you wish to conveniently edit them, track them and maintain them.

with Dir::Manifest you can put each one in a separate file in a directory, create a manifest file listing all valid filenames/keys, and then just say something like my $text = $dir->text("deal24solution.txt", {lf => 1}). and hopefully it will be done securely and reliably. 🧚 (the "hopefully" is doing a lot of work here but that's what it says, no cap)

👑 METHODS 👑

🌈 my $obj = Dir::Manifest->new({manifest_fn => "/path/to/base-dir/list.txr", dir => "/path/to/base-dir/texts",});

constructs a new Dir::Manifest object from a separate manifest_fn and a directory holding the texts. two separate things, both your besties.

🍓 my $obj = Dir::Manifest->dwim_new({base => "/path/to/base-dir"});

constructs a new Dir::Manifest with manifest_fn being $base->child("list.txt") and dir being $base->child("texts"). it's "Convention over configuration", aka let me guess for you bestie. 🫶

added in version 0.6.0.

💜 $self->manifest_fn()

the path to the manifest file. that's it. that's the girl.

🌸 $self->dir()

the path to the directory containing the texts and blobs as files.

⭐ $self->get_keys()

returns a sorted array reference containing the available keys as strings. sorted. alphabetical. organized. main character energy.

🦋 $self->get_obj($key)

returns the Dir::Manifest::Key object associated with the string $key. throws an error if $key was not given in the manifest — so don't be trying keys that aren't on the list, bestie, she WILL catch you. 💀

✨ $self->fh($key)

returns the Path::Tiny objects for the key, which is usable as a path in string context. equivalent to $self->get_obj($key)->fh().

(added in version 0.2.0. — note the lil stray period, we love her.)

🎀 my $contents = $self->text("$key", {%OPTS})

slurps the key using Dir::Manifest::Slurp. yes, slurps. as in drinks it up. obsessed. 🔥

🧚 my $hash_ref = $obj->texts_dictionary( {slurp_opts => {},} );

returns a hash reference (a dictionary) containing all keys and their slurped contents as values. slurp_opts is passed to text().

👑 $obj->add_key( {key => "new_key", utf8_val => $utf8_text, } );

adds a new key with a file with the new UTF-8 contents encoded as $utf8_text. (added in version 0.4.0).

💅 $obj->remove_key( {key => "existing_key_id", } );

removes the key from the dictionary while deleting its associated file. ⚠️ note: the file is gone gone. (added in version 0.4.0).

💐 DEDICATION 💐

this code is dedicated to the memory of Jonathan Scott Duff <https://metacpan.org/author/DUFF> a.k.a PerlJam and perlpilot, who passed away some days before the first release of this code. for more about him, see:

🫶 rest in peace.

🎧 MEDIA RECOMMENDATION 🎧

kristian vuljar <https://www.jamendo.com/artist/441226/kristian-vuljar> used to have a jamendo track called "Keys" based on Shine 4U <https://www.youtube.com/watch?v=B8ehY5tutHs> by Carmen and Camille. you can find it at <http://www.shlomifish.org/Files/files/dirs/kristian-vuljar--keys/> .

a track called "Keys" in a module about keys?? the theming is immaculate, honestly. 🎶

🌈 SUPPORT 🌈

💻 Websites

the following websites have more information about this module, and may be of help to you. as always, in addition to those websites please use your favorite search engine to discover more resources.

  • MetaCPAN

a modern, open-source CPAN search engine, useful to view POD in HTML format.

<https://metacpan.org/release/Dir-Manifest>

  • Search CPAN

the default CPAN search engine, useful to view POD in HTML format.

<http://search.cpan.org/dist/Dir-Manifest>

  • RT: CPAN's Bug Tracker

the RT ( Request Tracker ) website is the default bug/issue tracking system for CPAN.

<https://rt.cpan.org/Public/Dist/Display.html?Name=Dir-Manifest>

  • CPAN Ratings

the CPAN Ratings is a website that allows community ratings and reviews of Perl modules.

<http://cpanratings.perl.org/d/Dir-Manifest>

  • CPANTS

the CPANTS is a website that analyzes the Kwalitee ( code metrics ) of a distribution.

<http://cpants.cpanauthors.org/dist/Dir-Manifest>

  • CPAN Testers

the CPAN Testers is a network of smoke testers who run automated tests on uploaded CPAN distributions.

<http://www.cpantesters.org/distro/D/Dir-Manifest>

  • CPAN Testers Matrix

the CPAN Testers Matrix is a website that provides a visual overview of the test results for a distribution on various Perls/platforms.

<http://matrix.cpantesters.org/?dist=Dir-Manifest>

  • CPAN Testers Dependencies

the CPAN Testers Dependencies is a website that shows a chart of the test results of all dependencies for a distribution.

<http://deps.cpantesters.org/?module=Dir::Manifest>

🐛 Bugs / Feature Requests

please report any bugs or feature requests by email to bug-dir-manifest at rt.cpan.org, or through the web interface at <https://rt.cpan.org/Public/Bug/Report.html?Queue=Dir-Manifest>. you will be automatically notified of any progress on the request by the system. the system will keep you posted, bestie, it's got you. 💌

🧑‍💻 Source Code

the code is open to the world, and available for you to hack on. please feel free to browse it and play with it, or whatever. if you want to contribute patches, please send me a diff or prod me to pull from your repository :)

<https://github.com/shlomif/Dir-Manifest>

git clone https://github.com/shlomif/Dir-Manifest.git

💜 AUTHOR 💜

Shlomi Fish <shlomif@cpan.org>

💀 BUGS 💀

please report any bugs or feature requests on the bugtracker website <https://github.com/shlomif/dir-manifest/issues>

when submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. a repro or it didn't happen, that's the rule. 🫶

this software is Copyright (c) 2019 by Shlomi Fish.

this is free software, licensed under:

The MIT (X11) License

okay that's the whole page bestie, go forth and manifest your manifests 💖 and for the record: this was perl v5.42.0, dated 2025-07-25, from the Dir::Manifest(3pm) page. mwah. 🎀✨

📦 where this page comes from