.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Test::StagedFileProducer 3"
.TH Test::StagedFileProducer 3 2024-02-05 "Lintian v2.117.0" "Debian Package Checker"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Test::StagedFileProducer \-\- mtime\-based file production engine
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Test::StagedFileProducer;
\&
\&  my $wherever = \*(Aq/your/test/directory\*(Aq;
\&
\&  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.\en");
\&        },
\&        skip =>sub {
\&            print encode_utf8("Skipping $output.\en");
\&        }
\&  );
\&
\&  $producer\->run(minimum_epoch => time, verbose => 1);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Provides a way to define and stack file production stages that all
depend on subsets of the same group of files.
.PP
After the stages are defined, the processing engine takes an inventory
of all files in a target directory. It excludes some files, like logs,
that should not be considered.
.PP
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, in addition to a systemic rebuilding
threshold. Before rebuilding, each stage asks a lower stage to make
the same determination.
.PP
The result is an engine with file production stages that depend on
successively larger sets of files.
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.IP "new(path => PATH)" 4
.IX Item "new(path => PATH)"
Create a new instance focused on files in directory PATH.
.IP exclude(LIST) 4
.IX Item "exclude(LIST)"
Excludes all absolute paths in LIST from all mtime comparisons.
This is especially useful for logs. Calls to Path::Tiny\->realpath
are made to ensure the elements are canonical and have a chance
of matching something returned by File::Find::Rule.
.IP add_stage(HASH) 4
.IX Item "add_stage(HASH)"
Add a stage defined by HASH to the processing engine for processing
after stages previously added. HASH can define the following keys:
.Sp
\&\f(CW$HASH\fR{products} => LIST; a list of full-path filenames to be
produced.
.Sp
\&\f(CW$HASH\fR{minimum_epoch} => EPOCH; an integer threshold for maximum age
.Sp
\&\f(CW$HASH\fR{build} => SUB; a sub executed when production is required.
.Sp
\&\f(CW$HASH\fR{skip} => SUB; a sub executed when production is not required.
.IP run(PARAMETERS) 4
.IX Item "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:
.Sp
minimum_epoch => EPOCH; a systemic threshold, in epochs, below
which rebuilding is mandatory for any product.
.Sp
verbose => BOOLEAN; an option to enable more verbose reporting
.IP _process_remaining_stages(LIST) 4
.IX Item "_process_remaining_stages(LIST)"
An internal subroutine that is used recursively to execute
the stages. The list passed describes the list of files to
be excluded from subsequent mtime calculations.
.Sp
Please note that the bulk of the execution takes place
after calling the next lower stage. That is to ensure that
any lower build targets (or products, in our parlance) are
met before the present stage attempts to do its job.