Test::StagedFileProducer(3)

💖 Test::StagedFileProducer 💖

okay bestie, so this is Test::StagedFileProducer from the Test::StagedFileProducer manual page (section 3, the library-section girlies 🎀) — it's an mtime-based file production engine, and yeah that sounds like a lot but stay with me, it's actually so good.

---

✨ NAME ✨

Test::StagedFileProducer — mtime-based file production engine 🌸

🦋 SYNOPSIS 🦋

  use Test::StagedFileProducer;

  my $wherever = '/your/test/directory';

  my $producer = Test::StagedFileProducer->new(path => $wherever);
  $producer->exclude("$wherever/log", "$wherever/build-stamp");

  my $output = "$wherever/file.out";
  $producer->add_stage(
        products => [$output],
        build =>sub {
            print encode_utf8("Building $output.\n");
        },
        skip =>sub {
            print encode_utf8("Skipping $output.\n");
        }
  );

  $producer->run(minimum_epoch => time, verbose => 1);

look at that. absolutely ate. no notes. 💅

👑 DESCRIPTION 👑

so basically, this module gives you a way to define and stack file production stages that all depend on subsets of the same group of files. same little file family, different stages, one shared vibe check. ✨

once the stages are defined, the processing engine takes an inventory of all files in a target directory. then it excludes some files — like logs, bestie, logs are ALWAYS the problem — because those should not be considered. 🙈

each stage adds its own products to the list of files to be excluded before deciding whether to produce them. the decision is based on relative file modification times, plus a systemic rebuilding threshold. and before rebuilding, each stage asks a lower stage to make the same determination. it's giving "let me check with my friend first" energy. 🫶

the result? an engine with file production stages that depend on successively larger sets of files. it builds up. iconic behaviour. 🔥

💜 FUNCTIONS 💜

• new(path => PATH) — makes you a brand new instance, focused on the files in directory PATH. first step, always. 🌱
• exclude(LIST) — excludes all absolute paths in LIST from all mtime comparisons. this is especially useful for logs (of course it is). it calls Path::Tiny->realpath on the elements to make sure they're canonical and actually have a chance of matching something returned by File::Find::Rule. like, you gotta be in the right outfit to get into the club, y'know? 💅
• add_stage(HASH) — adds a stage defined by HASH to the processing engine, and it gets processed after the stages that were previously added. HASH can define the following keys:
  • $HASH{products} => LIST — a list of full-path filenames to be produced. the deliverables, the main character moments. ✨
  • $HASH{minimum_epoch} => EPOCH — an integer threshold for maximum age. 🩷
  • $HASH{build} => SUB — a sub executed when production is required. do the thing!! 🔨
  • $HASH{skip} => SUB — a sub executed when production is not required. not today, bestie. 🛌
• run(PARAMETERS) — runs the defined engine using the given parameters, which are arranged in a matching list suitable for assignment to a hash. the following two parameters are currently available:
  • minimum_epoch => EPOCH — a systemic threshold, in epochs, below which rebuilding is mandatory for any product. no skipping allowed, fr fr.
  • verbose => BOOLEAN — an option to enable more verbose reporting. if you like lore drops, turn this on. 📢
• _process_remaining_stages(LIST) — an internal subroutine that's used recursively to execute the stages. the list passed describes the list of files to be excluded from subsequent mtime calculations. (it's internal, so don't come for her, she's just doing her job.) 🙈

okay this part is lowkey important: the bulk of the execution takes place after calling the next lower stage. that's on purpose! it makes sure any lower build targets (or products, in our parlance 💅) are met before the present stage attempts to do its job. order matters, periodt.

---

heads up bestie: this is a manpage, so everything above is the real deal — every option, every key, every behaviour. no cap. 🧚

and that's the whole page, you're welcome 💖 this was Test::StagedFileProducer(3) from Lintian, version v2.139.0ubuntu2, dated 2026-10-08 — mwah, go build something, ily, byeee 🫶🌸