diff options
author | Russ Allbery <rra@cpan.org> | 2021-12-23 21:57:43 -0800 |
---|---|---|
committer | Russ Allbery <rra@cpan.org> | 2021-12-23 21:57:43 -0800 |
commit | 74c5d402923e0d4085200a38cfddeea8af16f341 (patch) | |
tree | 3fa4aa45d6510ce64f6c9f0443c3f4a6779e2b4e /lib/App/DocKnot/Util.pm | |
parent | 75c60cbc6a3c81f1991fac42966e13fa3cc77b51 (diff) |
Move utility functions to new module
Move is_newer, print_checked, and print_fh into a new
App::DocKnot::Util module to share them between the multiple modules
that use them.
Diffstat (limited to 'lib/App/DocKnot/Util.pm')
-rw-r--r-- | lib/App/DocKnot/Util.pm | 172 |
1 files changed, 172 insertions, 0 deletions
diff --git a/lib/App/DocKnot/Util.pm b/lib/App/DocKnot/Util.pm new file mode 100644 index 0000000..a72b37a --- /dev/null +++ b/lib/App/DocKnot/Util.pm @@ -0,0 +1,172 @@ +# Shared utility functions for other DocKnot modules. +# +# A collection of random utility functions that are used by more than one +# DocKnot module but don't make sense as App::DocKnot methods. +# +# SPDX-License-Identifier: MIT + +############################################################################## +# Modules and declarations +############################################################################## + +package App::DocKnot::Util 5.00; + +use 5.024; +use autodie; +use warnings; + +use Carp qw(croak); +use Exporter qw(import); +use List::SomeUtils qw(all); + +our @EXPORT_OK = qw(is_newer print_checked print_fh); + +############################################################################## +# Public interface +############################################################################## + +# Check if a file, which may not exist, is newer than another list of files. +# +# $file - File whose timestamp to compare +# @others - Other files to compare against +# +# Returns: True if $file exists and is newer than @others, false otherwise +sub is_newer { + my ($file, @others) = @_; + return if !-e $file; + my $file_mtime = (stat($file))[9]; + my @others_mtimes = map { (stat)[9] } @others; + return all { $file_mtime >= $_ } @others_mtimes; +} + +# print with error checking. autodie unfortunately can't help us because +# print can't be prototyped and hence can't be overridden. +# +# @args - Arguments to print to stdout +# +# Returns: undef +# Throws: Text exception on output failure +sub print_checked { + my (@args) = @_; + print @args or croak('print failed'); + return; +} + +# print with error checking and an explicit file handle. autodie +# unfortunately can't help us because print can't be prototyped and +# hence can't be overridden. +# +# $fh - Output file handle +# $file - File name for error reporting +# @args - Remaining arguments to print +# +# Returns: undef +# Throws: Text exception on output failure +sub print_fh { + my ($fh, $file, @args) = @_; + print {$fh} @args or croak("cannot write to $file: $!"); + return; +} + +############################################################################## +# Module return value and documentation +############################################################################## + +1; +__END__ + +=for stopwords +Allbery DocKnot MERCHANTABILITY NONINFRINGEMENT sublicense FH autodie + +=head1 NAME + +App::DocKnot::Util - Shared utility functions for other DocKnot modules + +=head1 SYNOPSIS + + use App::DocKnot::Util qw(is_newer print_checked print_fh); + + print_checked('some stdout output'); + if (!is_newer('/output', '/input-1', '/input-2')) { + open(my $fh, '>', '/output'); + print_fh($fh, '/output', 'some stuff'); + close($fh); + } + +=head1 REQUIREMENTS + +Perl 5.24 or later and the List::SomeUtils module, available from CPAN. + +=head1 DESCRIPTION + +This module collects utility functions used by other App::DocKnot modules. It +is not really intended for use outside of DocKnot, but these functions can be +used if desired. + +=head1 FUNCTIONS + +=over 4 + +=item is_newer(FILE, SOURCE[, SOURCE ...]) + +Returns a true value if FILE exists and has a last modified time that is newer +or equal to the last modified times of all SOURCE files, and otherwise returns +a false value. Used primarily to determine if a given output file is +up-to-date with respect to its source files. + +=item print_checked(ARG[, ARG ...]) + +The same as print (without a file handle argument), except that it throws a +text exception on failure as if autodie affected print (which it unfortunately +doesn't because print cannot be prototyped). + +=item print_fh(FH, NAME, DATA[, DATA ...]) + +Writes the concatenation of the DATA elements (interpreted as scalar strings) +to the file handle FH. NAME should be the name of the file open as FH, and is +used for error reporting. + +This is mostly equivalent to C<print {fh}> but throws a text exception in the +event of a failure. + +=back + +=head1 AUTHOR + +Russ Allbery <rra@cpan.org> + +=head1 COPYRIGHT AND LICENSE + +Copyright 1999-2011, 2013, 2021 Russ Allbery <rra@cpan.org> + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +=head1 SEE ALSO + +L<App::DocKnot> + +This module is part of the App-DocKnot distribution. The current version of +DocKnot is available from CPAN, or directly from its web site at +L<https://www.eyrie.org/~eagle/software/docknot/>. + +=cut + +# Local Variables: +# copyright-at-end-flag: t +# End: |