.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 "Running::Commentary 3pm"
.TH Running::Commentary 3pm "2022-06-17" "perl v5.34.0" "User Contributed Perl Documentation"
.\" 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"
Running::Commentary \- call "system" cleanly, with tracking messages
.SH "VERSION"
.IX Header "VERSION"
This document describes Running::Commentary version 0.000005
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Running::Commentary;
\&
\&    # Set a lexically scoped flag for all subsequent calls...
\&    # (No announcements, if this flag set)
\&    run_with \-nomessage if !$verbose;
\&
\&    # Act like system(), only louder and cleaner...
\&    run \*(AqResetting\*(Aq => "rm \-rf \*(Aq$ROOT_DIR\*(Aq"
\&        or die "Couldn\*(Aqt reset";
\&
\&    # Act like system(), but croak() if the command fails...
\&    run \-critical, \*(AqBuilding Makefile\*(Aq => \*(Aqperl Makefile.PL\*(Aq;
\&
\&    # Calls to run() may be nested, to allow subtasks to be tracked...
\&    run \*(AqRunning tests\*(Aq
\&        => sub {
\&            for my $file (@profiled_files) {
\&                push @profiles, "$NAMING_ROOT/$file.out";
\&                local $ENV{NYTPROF} = "file=$profiles[\-1]";
\&
\&                run \-nooutput, "Testing $file"
\&                    => "perl \-d:NYTProf $profiled_path/$file >& /dev/null";
\&            }
\&    };
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a single subroutine: \f(CW\*(C`run()\*(C'\fR
which is designed to be a more informative and less error-prone
replacement for the built-in \f(CW\*(C`system()\*(C'\fR.
.PP
It also provides a compile-time keyword: \f(CW\*(C`run_with\*(C'\fR
with which you can set lexically scoped default options for \f(CW\*(C`run()\*(C'\fR.
.SH "INTERFACE"
.IX Header "INTERFACE"
.ie n .IP """run $MESSAGE => $SYSTEM_CMD;""" 4
.el .IP "\f(CWrun $MESSAGE => $SYSTEM_CMD;\fR" 4
.IX Item "run $MESSAGE => $SYSTEM_CMD;"
This acts like \f(CW\*(C`system $SYSTEM_CMD\*(C'\fR, except that it returns true on success
and false on failure, and it announces what it's doing. For example:
.Sp
.Vb 1
\&    run \*(AqResetting directories\*(Aq => "rm \-rf @STD_DIRS"
.Ve
.Sp
\&...would first output:
.Sp
.Vb 1
\&    Resetting directories...
.Ve
.Sp
\&...then execute the system command, and finish the message:
.Sp
.Vb 1
\&    Resetting directories...done
.Ve
.Sp
If the command failed for some reason, the completion would reflect
the problem:
.Sp
.Vb 3
\&    Resetting directories...
\&    rm: tets: No such file or directory
\&    Resetting directories...exited with value 1
.Ve
.Sp
Or:
.Sp
.Vb 1
\&    Resetting directories...failed to execute: No such file or directory
.Ve
.ie n .IP """run $MESSAGE => sub {...};""" 4
.el .IP "\f(CWrun $MESSAGE => sub {...};\fR" 4
.IX Item "run $MESSAGE => sub {...};"
This form of the command expects a subroutine reference, rather than a string,
as its second argument. Once again it prints the tracking message, then
executes the subroutine, then prints the outcome.
.Sp
The subroutine is run inside an \f(CW\*(C`eval\*(C'\fR block, so any exceptions it throws
are intercepted, and reported as the outcome at the end of the tracking
message. To have exceptions inside the subroutine propagate back out of the
call to \f(CW\*(C`run()\*(C'\fR, use the \f(CW\*(C`\-critical\*(C'\fR option (see below).
.Sp
For example:
.Sp
.Vb 5
\&    run \*(AqPrinting your data\*(Aq => sub {
\&        for my $datum (@data) {
\&            say "    $datum\->{key}: $datum\->{value}";
\&        }
\&    }
.Ve
.Sp
Would output:
.Sp
.Vb 5
\&    Printing your data...
\&        Name: Fred
\&        Age: 28
\&        Score: 87
\&    Printing your data...done
.Ve
.Sp
You can also nest calls to \f(CW\*(C`run()\*(C'\fR using this form.
For example:
.Sp
.Vb 5
\&    run \*(AqRunning your request\*(Aq => sub {
\&        for my $cmd (split /\en/, $request) {
\&            run "Running \*(Aq$cmd\*(Aq" => $cmd;
\&        }
\&    }
.Ve
.Sp
Would produce:
.Sp
.Vb 5
\&    Running your request...
\&        Running \*(Aqrm source\*(Aq...done
\&        Running \*(Aqrebuild_files\*(Aq...done
\&        Running \*(Aqmake test\*(Aq.......done
\&    Running your request...done
.Ve
.ie n .IP """run $SYSTEM_CMD;""" 4
.el .IP "\f(CWrun $SYSTEM_CMD;\fR" 4
.IX Item "run $SYSTEM_CMD;"
.PD 0
.ie n .IP """run sub {...};""" 4
.el .IP "\f(CWrun sub {...};\fR" 4
.IX Item "run sub {...};"
.PD
When called without a message, \f(CW\*(C`run()\*(C'\fR simply executes the system
command or subroutine without printing any kind of progress message.
In other words, it merely acts as a (quietly) better \f(CW\*(C`system()\*(C'\fR.
.ie n .IP """run_with @OPTIONS;""" 4
.el .IP "\f(CWrun_with @OPTIONS;\fR" 4
.IX Item "run_with @OPTIONS;"
The \f(CW\*(C`run_with\*(C'\fR keyword can be called with any of the options available
to \f(CW\*(C`run()\*(C'\fR (see \*(L"\s-1OPTIONS\*(R"\s0). It takes the options given to it and
makes them the default arguments to \f(CW\*(C`run()\*(C'\fR for the remainder of the
current lexical scope.
.Sp
For example, to cause any subsequent failed command to throw an
exception...
.Sp
.Vb 2
\&    {
\&        run_with \-critical;
\&
\&        run "loading"     => $LOAD_CMD;
\&        run "checking"    => $CHECK_CMD;
\&        run "installing"  => $INSTALL_CMD;
\&        run "cleaning up" => $CLEANUP_CMD;
\&    }
.Ve
.Sp
\&...or to silence message printing on request:
.Sp
.Vb 2
\&    {
\&        run_with \-nomessage if $opt{\-quiet};
\&
\&        run "loading"     => $LOAD_CMD;
\&        run "checking"    => $CHECK_CMD;
\&        run "installing"  => $INSTALL_CMD;
\&        run "cleaning up" => $CLEANUP_CMD;
\&    }
.Ve
.PP
Note that \f(CW\*(C`run_with\*(C'\fR is a compile-time keyword, not a subroutine,
so it should only be called as a statement (i.e. in void context).
.SH "OPTIONS"
.IX Header "OPTIONS"
The following options can be included anywhere in the argument list of
a call to \f(CW\*(C`run()\*(C'\fR or \f(CW\*(C`run_with\*(C'\fR.
.ie n .IP """\-nomessage""" 4
.el .IP "\f(CW\-nomessage\fR" 4
.IX Item "-nomessage"
Run the command without printing the tracking message.
Normally used as a conditional lexical option:
.Sp
.Vb 1
\&    run_with \-nomessage if $opt{quiet};
.Ve
.Sp
The output of the actual system command is still
printed (unless \f(CW\*(C`\-nooutput\*(C'\fR or \f(CW\*(C`\-silent\*(C'\fR is also specified)
.ie n .IP """\-showmessage""" 4
.el .IP "\f(CW\-showmessage\fR" 4
.IX Item "-showmessage"
Run the command, printing the tracking message.
Useful to turn message printing back on inside
a scope where \f(CW\*(C`\-nomessage\*(C'\fR is already in effect.
.ie n .IP """\-nooutput""" 4
.el .IP "\f(CW\-nooutput\fR" 4
.IX Item "-nooutput"
Run the command without echoing any of its output.
The tracking message is still printed
(unless \f(CW\*(C`\-nomessage\*(C'\fR or \f(CW\*(C`\-silent\*(C'\fR is also specified)
.ie n .IP """\-showoutput""" 4
.el .IP "\f(CW\-showoutput\fR" 4
.IX Item "-showoutput"
Run the command, echoing any output.
Useful to turn command echoing back on inside
a scope where \f(CW\*(C`\-nooutput\*(C'\fR is already in effect.
.ie n .IP """\-silent""" 4
.el .IP "\f(CW\-silent\fR" 4
.IX Item "-silent"
Identical to: \f(CW\*(C`\-nomessage, \-nooutput\*(C'\fR
.ie n .IP """\-showall""" 4
.el .IP "\f(CW\-showall\fR" 4
.IX Item "-showall"
Identical to: \f(CW\*(C`\-showmessage, \-showoutput\*(C'\fR.
Useful to override \f(CW\*(C`\-silent\*(C'\fR in a nested scope.
.ie n .IP """\-critical""" 4
.el .IP "\f(CW\-critical\fR" 4
.IX Item "-critical"
Normally, if a call to \f(CW\*(C`run()\*(C'\fR fails, it simply returns \f(CW\*(C`undef\*(C'\fR.
However, if the \f(CW\*(C`\-critical\*(C'\fR option is specified, any call to \f(CW\*(C`run\*(C'\fR
that fails will immediately throw an exception.
.ie n .IP """\-nocritical""" 4
.el .IP "\f(CW\-nocritical\fR" 4
.IX Item "-nocritical"
Revert \f(CW\*(C`run()\*(C'\fR to returning \f(CW\*(C`undef\*(C'\fR on failure.
Useful to override \f(CW\*(C`\-critical\*(C'\fR in a nested scope.
.ie n .IP """\-dry""" 4
.el .IP "\f(CW\-dry\fR" 4
.IX Item "-dry"
Instead of executing the specified system command, just print it out.
Useful for dry runs during development and testing.
.ie n .IP """\-colour => \e%COLOUR_SPEC""" 4
.el .IP "\f(CW\-colour => \e%COLOUR_SPEC\fR" 4
.IX Item "-colour => %COLOUR_SPEC"
Specify the colours to be used for messages and output. Colours
are specified as the values of the hash, with the keys indicating
what purpose each colour is to be used for. For example:
.Sp
.Vb 6
\&    run_with \-colour => {
\&        MESSAGE => \*(Aqwhite\*(Aq,          # Colour for tracking messages
\&        DONE    => \*(Aqbold cyan\*(Aq,      # Colour for success messages
\&        FAILED  => \*(Aqyellow on_red\*(Aq,  # Colour for failure messages
\&        OUTPUT  => \*(Aqclear\*(Aq           # Colour for command output
\&    };
.Ve
.Sp
The colour specifications must be single strings, which are split on
whitespace and then passed to the \f(CW\*(C`Term::ANSIColor\*(C'\fR module. If that module
is not available, this option is silently ignored.
.Sp
This option may also be spelled \f(CW\*(C`\-color\*(C'\fR.
.ie n .IP """\-nocolour""" 4
.el .IP "\f(CW\-nocolour\fR" 4
.IX Item "-nocolour"
Print all messages and output without any special colours.
.Sp
This option may also be spelled \f(CW\*(C`\-nocolor\*(C'\fR.
.SH "ERROR HANDLING"
.IX Header "ERROR HANDLING"
On failure \f(CW\*(C`run()\*(C'\fR normally either returns \f(CW\*(C`undef\*(C'\fR or throws
an exception (if \f(CW\*(C`\-critical\*(C'\fR is specified).
.PP
However, \f(CW\*(C`Running::Commentary\*(C'\fR incorporates the \f(CW\*(C`Lexical::Failure\*(C'\fR
module, so you can also request other failure responses for any
particular scope, by passing a named argument when loading the module:
.PP
.Vb 2
\&    # Report errors by confess()\-ing...
\&    use Running::Commentary  fail => \*(Aqconfess\*(Aq;
\&
\&    # Report errors by returning a failure object...
\&    use Running::Commentary  fail => \*(Aqfailobj\*(Aq;
\&
\&    # Report errors by setting a flag variable...
\&    use Running::Commentary  fail => \e$error;
\&
\&    # Report errors by calling a subroutine...
\&    use Running::Commentary  fail => \e&error_handler;
.Ve
.PP
For details of the available options, see the documentation
of \f(CW\*(C`Lexical::Failure\*(C'\fR.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.ie n .IP """Bad argument to \*(Aquse Running::Commentary\*(Aq""" 4
.el .IP "\f(CWBad argument to \*(Aquse Running::Commentary\*(Aq\fR" 4
.IX Item "Bad argument to use Running::Commentary"
The module accepts only one named argument:
.Sp
.Vb 1
\&    use Running::Commentary  \*(Aqfail\*(Aq => $fail_mode;
.Ve
.Sp
(see \*(L"\s-1ERROR HANDLING\*(R"\s0).
.Sp
You apparently passed it something else.
Or perhaps misspelt 'fail'?
.ie n .IP """Useless call to run() with no command""" 4
.el .IP "\f(CWUseless call to run() with no command\fR" 4
.IX Item "Useless call to run() with no command"
\&\f(CW\*(C`run()\*(C'\fR expects at least one argument (apart from any
configuration options); namely, something to execute.
That can be either a string containing a system command,
or else a subroutine reference.
.Sp
You didn't give it either of those, so the call to \f(CW\*(C`run()\*(C'\fR
was superfluous.
.Sp
Or, possibly, you wanted \f(CW\*(C`run_with\*(C'\fR instead.
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "CONFIGURATION AND ENVIRONMENT"
Running::Commentary requires no configuration files or environment variables.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
This module requires Perl v5.14 or later.
.PP
It also requires the modules:
\&\f(CW\*(C`Lexical::Failure\*(C'\fR, and
\&\f(CW\*(C`Keyword::Simple\*(C'\fR.
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
None reported.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
No bugs have been reported.
.PP
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-running\-commentary@rt.cpan.org\*(C'\fR, or through the web interface at
<http://rt.cpan.org>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Damian Conway  \f(CW\*(C`<DCONWAY@CPAN.org>\*(C'\fR
.SH "LICENCE AND COPYRIGHT"
.IX Header "LICENCE AND COPYRIGHT"
Copyright (c) 2012, Damian Conway \f(CW\*(C`<DCONWAY@CPAN.org>\*(C'\fR. All rights reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See perlartistic.
.SH "DISCLAIMER OF WARRANTY"
.IX Header "DISCLAIMER OF WARRANTY"
\&\s-1BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE SOFTWARE \*(L"AS IS\*(R" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
NECESSARY SERVICING, REPAIR, OR CORRECTION.\s0
.PP
\&\s-1IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
THE SOFTWARE\s0 (\s-1INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE\s0), \s-1EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.\s0