Decision::Depends - Perform actions based upon file dependencies
use Decision::Depends; Decision::Depends::Configure( { File => $depfile } ); if_dep { @targ_dep_list } action { action };
Decision::Depends is a module which simplifies the creation of procedures with intermediate steps which can be skipped if certain dependencies are met. Think of it as a procedural version of make.
Decision::Depends is useful when there are several steps in a process, each of which depends upon the last. If the process is interrupted, or if it is to be redone with changes to parameters in later steps, and if intermediate results can be kept, then Decision::Depends can insure that only the minimal number of steps be redone.
Each step must result in a tangible product (a file). For complicated steps with many products the step's successful completion may be indicated by creating an empty file whose existance indicates completion. This file (a status file in Decision::Depends terminology) can be automatically created if requested.
status
Decision::Depends determines if the product for a given step is older than any files required to produce it. It can also check whether the contents of a file have changed since the product was last created. This is useful in the case where a configuration file must be created anew each time, but results in action only if changed since the product was last created. Finally, it can determine if a variable's value has changed since the product was last created.
Decision::Depends must keep some dependency information between runs (for signature and variable dependencies). It stores this in a file, which must be named by the application. The application indicates the file by calling the Decision::Depends::Configure subroutine.
This file is updated after completion of successful actions and when the program is exited.
Decision::Depends can be put into a state where it checks dependencies and pretends to update targets in order to check what actions might need to be taken. This is done by passing the Pretend attribute to Decision::Depends::Configure. In this mode no actions are actually performed, but are assumed to have successfully created their products.
Pretend
Decision::Depends will output to STDOUT its musings if the Verbose attribute is passed to Decision::Depends::Configure.
Verbose
To simply test if a dependency exists, without requiring that an action be performed, use the test_dep function.
Each step must construct a single Perl list of products, also called targets (as in make), and dependencies. The list has a simple syntax - it is a sequence of values, each of which may have one or more attributes. Attributes precede values and apply only to the next value (unless values are grouped), and always begin with a - character. Multiple attributes may be applied to a single value.
-
-target => $file, -depend => -sig => $dep
(Note the use of the perl => operator to avoid quoting of attributes.) Values which begin with the - character (which may be confused with attributes) may be passed by reference. Depend recognizes negative numbers, so those need not be handled specially.
=>
-target => \'-strange_file', -target => -33.99e24
Values may be grouped by placing them in anonymous arrays:
-target => [ $file1, $file2 ]
Attributes are applied to all elements of the group; additional attributes may modify individual group members:
-target => [ -sfile => $file1, $file2 ]
Groups may be nested.
To negate an attribute, introduce the same attribute with a prefix of -no_:
-no_
-target => -sfile => [ $file1, -no_sfile => $file2 ]
Attributes may have values, although they are in general boolean values. The syntax is '-attr=value'. Note that because of the = character, Perl's automatic quoting rules when using the => operator are insufficient to ensure appropriate quoting. For example
=
'-slink=foo' => $target
assigns the -slink attribute to $target and gives the attribute the value foo. If no value is specified, a default value of 1 is assigned. Most attributes are boolean, so no value need be assigned them.
-slink
$target
foo
1
Hash references may be used to pair attribute values with ordinary values. For example, the following
-var => { $attr1 => $val1, $attr2 => $val2 }
assigns $val1 the attribute -var with the value $attr1, $val2 the attribute -var with the value $attr2, etc. This is most useful when specifying variable dependencies (see Dependencies).
$val1
-var
$attr1
$val2
$attr2
Targets are identified either by having the -target or -targets attributes, or by being the first value (or group) in the target-dependency list and not having the -depend attribute. For example, the following are equivalent
-target
-targets
-depend
( -target => $targ1, -target => $targ2, ... ) ( -target => [ $targ1, $targ2 ], ... ) ( [ $targ1, $targ2 ], ... )
There must be at least one target. Target values may have the following attributes:
This indicates the value is a target.
This indicates that the target is a status file. It will be automatically created upon successful completion of the step.
This indicates that the target is a status file which is linked to an imaginary file linkfile. Any step which explicitly depends upon linkfile will instead depend upon the target file instead. Multiple links to linkfile may be created. Links are checked in order of appearance, and are useful only as time dependencies. For example, rather than depending upon the target of the previous step, a step might depend upon the linkfile. It's then possible to introduce new intermediate steps which link their status files to linkfile without having to rewrite the current step. For example
linkfile
( -target => '-slink=step1' => 'step1a', ... ) ( -target => '-slink=step1' => 'step1b', ... ) ( -target => $result, -depend => 'step1' )
In this case, the final step will depend upon step1a and step1b. One could later add a step1c and not have to change the dependencies for the final step.
The target status file will be automatically created upon successful completion of the step.
-force
If set to non-zero (the default if no value is specified), this will force the target to always be out-of-date. This can be used to override a global forcing of out-of-dateness (done via the Depend::Configure function) by setting it to zero. It is probably most useful for targets which have no dependencies.
Dependencies are identified either as not being the first value (or group) in the list and not having the -target attribute, or by having the attributes -depend or -depends. There need not be any dependencies.
-depends
There are three types of dependencies: time, signature, and variable. The default type is time. The defining attributes are:
-time
Time dependencies are the default if no attribute is not specified. A time dependency results in a comparison of the timestamps of the target and dependency files. If the target is older than the dependency file, the step must be redone.
-sig
Signature dependencies check the current contents of the dependency file against the contents the last time the target was created. If the contents have changed, the step must be redone. An MD5 checksum signature is computed for signature dependency files; these are what is stored and compared.
A new signature is recorded upon successful completion of the step.
Variable dependencies check the value of a variable against its value the last time the target was created. If the contents have changed, the step must be redone. The new value is recorded upon successful completion of the step.
Variable values may be scalars, hashes, or arrays. The latter two must be passed as a reference to a hashref and a reference to an arrayref (not just plain hashrefs and arrayrefs), as Decision::Depends uses hashrefs and arrayrefs to group values and atributes. For example,
\\%hash \$hashref \\@array \$arrayref
There are several methods of specifying the variable name and value.
The -var attribute may be assigned the name of the variable:
'-var=var_name' => $var_value
This leads to fairly crufty looking code:
'-var=var1_name' => $var1_value, '-var=var2_name' => $var2_value
So the use of a hash reference to pair the variable names and values comes in handy:
-var => { var1_name => $var1_value, var2_name => $var2_value }
This allows the nice short hand of
-var => \%variables
With this method, you cannot have a variable named 1, which shouldn't be too limiting.
The variable name can be provided as if it were another attribute:
-var => -var_name => $var_value
With this method variables cannot have the same name as any of the reserved names for attributes.
Scalar variable dependencies may have the following additional attributes:
-case
If specified, variable value comparisons will be case sensitive. They are normally not case sensitive.
-numcmp
If specified, treat the value as a number (integer or floating point). Generally Decision::Depends does a good job at guessing whether a value is a number or not; this forces it to treat it as a number if it guesses wrong. This may not be mixed with the -strcmp attribute.
-strcmp
If specified, treat the value as a string. Generally Decision::Depends does a good job at guessing whether a value is a number or not; this forces it to treat it as a string if it guesses wrong. This may not be mixed with the -str attribute.
Hash and array values are compared via Data::Compare; there is no means of forcing numeric or string comparisons.
Dependencies may be given special attributes independent of the type of dependency. These are:
If set to non-zero (the default if no value is specified), this will force the dependency to always be out-of-date. This can be used to override a global forcing of dependencies (done via the Depend::Configure function) by setting it to zero. For example:
Decision::Depends::Configure( { Force => 1 } ); if_dep { -target => $target, -depend => '-force=0' => $dep } action { ... }
Decision::Depends exports the function if_dep, which is used by the application to specify the targets and dependencies and the action to be taken if the dependencies have not been met. It has the form
if_dep { targdep } action { actions };
where targdep is Perl code which results in a target and dependency list and actions is Perl code to generate the target. Note the final semi-colon.
The target dependency list code is generally very simple:
if_dep { -target => 'foo.out', -depend => 'foo.in' } action { ... }
The action routine is passed (via @_) a reference to a hash with the names of targets whose dependencies were not met as the keys. The values are hash references, with the following keys:
@_
A reference to an array of the dependency files which were newer than the target.
A reference to an array of the variables whose values had changed.
A reference to an array of the files whose content signatures had changed.
If these lists are empty, the target file does not exist. For example,
if_dep { -target => 'foo.out', -depend => 'foo.in' } action { my ( $deps ) = @_; ... };
If foo.out did not exist
$deps = { 'foo.out' => { time => [], var => [], sig => [] } };
If foo.out did exist, but was older than foo.in,
%deps = { 'foo.out' => { time => [ 'foo.in' ], var => [], sig => [] } };
Unless the target is a status file (with attributes -sfile or -slink), the action routine must create the target file. It must indicate the success or failure of the action by calling die() if there is an error:
-sfile
if_dep { -target => 'foo.out', -depend => 'foo.in' } action { my ( $deps ) = @_; frobnagle( 'foo.out' ) or die( "error frobnagling!\n" ); };
if_dep will catch the die(). There are two manners in which the error will be passed on by if_dep. If if_dep is called in a void context (i.e., its return value is being ignored), it will croak() (See Carp). If called in a scalar context, it will return true upon success and false upon error. In either case the $@ variable will contain the text passed to the original die() call.
true
false
$@
The following two examples have the same result:
eval{ if_dep { ... } action { ... } }; die( $@ ) if $@; if_dep { ... } action { ... } or die $@;
Sometimes life is so complicated that you need to first test for a dependency before you know what to do. In that case, use the test_dep function, which has the form
test_dep( targdep )
where targdep is identical to that passed to the if_dep function. In a scalar environment, test_dep will return true if the dependency is not met. In a list environment, it will return a hash (not a hashref) with the dependency information (the same hash as passed to the action routine, but here it's a hash, not a hash ref). For example:
if ( test_dep( @targdep ) ) { # dependency was not met } %deps = test_dep( @targdep );
This routine sets various attributes which control Decision::Depends behavior, including the file to which Decision::Depends writes its dependency information. Attributes are option-value pairs, and may be passed as lists of pairs, arrayrefs (containing pairs), or hashrefs (or any mix thereof):
@attr2 = ( $attr => $value ); $attr{$attr} = $value; Decision::Depends::Configure( \%attr, $attr => $value, \@attr );
A dependency file is not required if there are no signature or variable dependencies. In that case, if no attributes need be set, this routine need not be called at all.
The available attributes are
The name of a file which contains (or will contain) dependency information. In general this should be an absolute path, unless the directory will not be changed.
If set to a non-zero value, all dependencies will be out-of-date, forcing execution of all actions.
If set to a non-zero value, Decision::Depends will simulate the actions to track what might happen.
If set to a non-zero value, Decision::Depends will be somewhat verbose.
For example,
Decision::Depends::Configure( { File => $depfile Pretend => 1, Verbose => 1 } );
The following routines are exported into the caller's namespace if_dep, action, test_dep.
This module was heavily influenced by the ideas in the cons software construction tool.
The {targdep} and {actions} clauses to if_dep are actually anonymous subroutines. Any subroutine reference will do in their stead
{targdep}
{actions}
if_dep \&targdep action \&actions;
No bugs have been reported.
Please report any bugs or feature requests to bug-decision-depends@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Decision-Depends.
bug-decision-depends@rt.cpan.org
Copyright (c) 2008 The Smithsonian Astrophysical Observatory
Decision::Depends is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.
Diab Jerius <djerius@cpan.org>
To install Decision::Depends, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Decision::Depends
CPAN shell
perl -MCPAN -e shell install Decision::Depends
For more information on module installation, please visit the detailed CPAN module installation guide.