Runnin...mentary(3pm)

🦋 Running::Commentary 🦋

straight out of the User Contributed Perl Documentation, 3pm section, no cap ✨

---

🌸 NAME 🌸

Running::Commentary — it calls system cleanly, and it keeps you posted with tracking messages the whole time. bestie behaviour fr fr 💖

---

✨ VERSION ✨

this doc is describing Running::Commentary version 0.000005. iconic number, love that for us 🎀

---

🎀 SYNOPSIS 🎀

okay so here's the vibe:

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 'Resetting' => "rm -rf '$ROOT_DIR'"
    or die "Couldn't reset";

# Act like system(), but croak() if the command fails...
run -critical, 'Building Makefile' => 'perl Makefile.PL';

# Calls to run() may be nested, to allow subtasks to be tracked...
run 'Running tests'
    => 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";
        }
};

like… look at it. nested. tracked. gorgeous. 😭💜

---

🌈 DESCRIPTION 🌈

this module gives you exactly one subroutine: run(). and the whole point of it is that it's a more informative, less error-prone glow-up of the built-in system(). 💅

it ALSO gives you a compile-time keyword: run_with, which is how you set lexically scoped default options for run(). so like, set it once, it applies for the rest of the scope. main character energy tbh 👑

---

💖 INTERFACE 💖

🌟 run $MESSAGE => $SYSTEM_CMD;

this does the system $SYSTEM_CMD thing, EXCEPT:

• it returns true on success and false on failure (not that cursed raw exit-status situation)
• it announces what it's doing like a little narrator 🫶

example time:

run 'Resetting directories' => "rm -rf @STD_DIRS"

…would first print out:

Resetting directories...

…then it actually runs the system command, and then it finishes the message:

Resetting directories...done

and if the command failed for some reason, the completion part tells you what went wrong:

Resetting directories...
rm: tets: No such file or directory
Resetting directories...exited with value 1

or, in the other flavour of bad:

Resetting directories...failed to execute: No such file or directory

note bestie: that tets up there is exactly what the original says. we do not fix, we do not touch, we preserve ✋ (keeping every detail is the whole assignment)

🌟 run $MESSAGE => sub {...};

this flavour wants a subroutine reference as its second argument, not a string. same deal though: prints the tracking message, runs the sub, prints the outcome. 💫

the sub gets run inside an eval block, so any exceptions it throws get caught and reported as the outcome at the end of the tracking message. if you want those exceptions to actually escape back out of the run() call instead, that's what the -critical option is for (scroll down, it's in OPTIONS, we got you).

for example:

run 'Printing your data' => sub {
    for my $datum (@data) {
        say "    $datum->{key}: $datum->{value}";
    }
}

would output:

Printing your data...
    Name: Fred
    Age: 28
    Score: 87
Printing your data...done

and you can nest calls to run() using this form. like:

run 'Running your request' => sub {
    for my $cmd (split /\n/, $request) {
        run "Running '$cmd'" => $cmd;
    }
}

which would produce:

Running your request...
    Running 'rm source'...done
    Running 'rebuild_files'...done
    Running 'make test'.......done
Running your request...done

look at those little dots lining up 😭 the alignment ate, honestly

🌟 run $SYSTEM_CMD;

🌟 run sub {...};

when you call it with no message, run() just executes the system command or the subroutine and prints absolutely no progress message whatsoever. in other words it's just a quietly better system(). still better though. always better. 💅

🌟 run_with @OPTIONS;

the run_with keyword takes any of the options that run() accepts (check "OPTIONS" below). whatever options you hand it become the default arguments for run() for the rest of the current lexical scope. set it and forget it ✨

say you want every subsequent failed command to throw an exception…

{
    run_with -critical;

    run "loading"     => $LOAD_CMD;
    run "checking"    => $CHECK_CMD;
    run "installing"  => $INSTALL_CMD;
    run "cleaning up" => $CLEANUP_CMD;
}

…or you want to silence message printing on request:

{
    run_with -nomessage if $opt{-quiet};

    run "loading"     => $LOAD_CMD;
    run "checking"    => $CHECK_CMD;
    run "installing"  => $INSTALL_CMD;
    run "cleaning up" => $CLEANUP_CMD;
}

⚠️ important bestie: run_with is a compile-time keyword, NOT a subroutine. so you only ever call it as a statement, aka in void context. don't be out here trying to use its return value, there isn't one 🫠

---

💅 OPTIONS 💅

all of these can go anywhere in the argument list of a call to run() or run_with. sprinkle as needed 🎀

• -nomessage — run the command with no tracking message. usually you'd use it as a conditional lexical option, like:

run_with -nomessage if $opt{quiet};

the output of the actual system command still gets printed though — unless -nooutput or -silent is also in play.

• -showmessage — run the command with the tracking message printed. this is your girl when you need to turn message printing back ON inside a scope where -nomessage is already in effect. 💫
• -nooutput — run the command without echoing any of its output. the tracking message still prints — unless -nomessage or -silent is also specified. 🤫
• -showoutput — run the command and echo the output. perfect for flipping command echoing back on inside a scope where -nooutput is already in effect. 🔥
• -silent — literally identical to: -nomessage, -nooutput. the stealth mode combo ✨
• -showall — literally identical to: -showmessage, -showoutput. super handy for overriding -silent in a nested scope. the un-stealth 💅
• -critical — normally, if a call to run() fails it just returns undef. but with -critical, any call to run that fails immediately throws an exception. no quiet failure, we're not doing that 🙅
• -nocritical — puts run() back to returning undef on failure. useful for overriding -critical in a nested scope. 🫶
• -dry — instead of actually executing the specified system command, it just prints it out. ideal for dry runs while you're developing and testing. no accidental rm -rf situations, we love to see it 🙈
• -colour => \%COLOUR_SPEC — specify the colours used for messages and output. the values of the hash are the colours, and the keys say what each colour is for. like so:

run_with -colour => {
    MESSAGE => 'white',          # Colour for tracking messages
    DONE    => 'bold cyan',      # Colour for success messages
    FAILED  => 'yellow on_red',  # Colour for failure messages
    OUTPUT  => 'clear'           # Colour for command output
};

each colour spec has to be a single string, which gets split on whitespace and then passed along to the Term::ANSIColor module. if that module isn't available, this option is silently ignored. (rude of it, but okay.)

this option may also be spelled -color.

• -nocolour — print all messages and output with no special colours at all. neutral palette era 🤍

this option may also be spelled -nocolor.

---

😭 ERROR HANDLING 😭

on failure, run() normally does one of two things: returns undef, OR throws an exception (if -critical is specified).

BUT. plot twist. Running::Commentary incorporates the Lexical::Failure module, so you can also request other failure responses for any particular scope, just by passing a named argument when you load the module:

# Report errors by confess()-ing...
use Running::Commentary  fail => 'confess';

# Report errors by returning a failure object...
use Running::Commentary  fail => 'failobj';

# Report errors by setting a flag variable...
use Running::Commentary  fail => \$error;

# Report errors by calling a subroutine...
use Running::Commentary  fail => \&error_handler;

for the details of all the available options, go read the documentation of Lexical::Failure. it's the whole plug-and-play failure system, obsessed 💜

---

🔍 DIAGNOSTICS 🔍

• Bad argument to 'use Running::Commentary' — the module accepts exactly one named argument:

use Running::Commentary  'fail' => $fail_mode;

(see "ERROR HANDLING" up there 👆)

so yeah, you apparently passed it something else. or maybe you misspelled 'fail'? we've all been there bestie, no judgement 🫶

• Useless call to run() with no command — run() expects at least one argument (aside from any configuration options), namely: something to execute. that something can be either a string containing a system command, or a subroutine reference.

you gave it neither of those, so the call to run() was superfluous. nothing to run, nothing happened, awkward 💀

or, possibly, you wanted run_with instead. (classic mix-up, honestly)

---

🧚 CONFIGURATION AND ENVIRONMENT 🧚

Running::Commentary requires no configuration files and no environment variables. zero setup, we just work ✨ (a low-maintenance king)

---

🍓 DEPENDENCIES 🍓

• this module requires Perl v5.14 or later.
• it also requires the modules: Lexical::Failure, and Keyword::Simple.

---

🌈 INCOMPATIBILITIES 🌈

none reported. 💅 (nothing to see here, move along)

---

💀 BUGS AND LIMITATIONS 💀

no bugs have been reported. 😌

please report any bugs or feature requests to bug-running-commentary@rt.cpan.org, or through the web interface at <http://rt.cpan.org>. (link as-is, bestie, we keep it verbatim)

---

👑 AUTHOR 👑

Damian Conway "<DCONWAY@CPAN.org>"

---

💜 LICENCE AND COPYRIGHT 💜

Copyright (c) 2012, Damian Conway "<DCONWAY@CPAN.org>". All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

💀 DISCLAIMER OF WARRANTY 💀

okay bestie, deep breath, this is the part where the lawyers start SCREAMING in all caps and honestly? valid. 🫶

so here's the deal: this software is licensed FREE OF CHARGE, and because of that, THERE IS NO WARRANTY FOR THE SOFTWARE, to the extent permitted by applicable law. none. zero. nada. 💀

and like — unless somebody literally said otherwise in writing, the copyright holders and/or other parties are handing you the software "AS IS", with NO WARRANTY OF ANY KIND, whether expressed or implied. and yes that includes (but is not limited to, bestie, they're covering their bases) the implied warranties of MERCHANTABILITY and FITNESS FOR A PARTICULAR PURPOSE. it's giving "you get what you get". 🙈

the entire risk as to the quality and performance of the software? that's on YOU. all yours. and if the software turns out to be defective, you assume the cost of all necessary servicing, repair, or correction. not them. you. 💅

---

okay and now the second paragraph, which is the big one, the main character of liability clauses:

IN 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. any of them. including any general, special, incidental, or consequential damages arising out of the use or inability to use the software.

and just so we're being thorough (they are, they're being SO thorough), that includes but is not limited to:

• loss of data 📉
• data being rendered inaccurate
• losses sustained by you or third parties
• a failure of the software to operate with any other software

and this holds EVEN IF such holder or other party has been advised of the possibility of such damages. like, even if they knew it could go wrong, still not their problem. no cap. 😭

---

so yeah. that's the vibe. it's free, it's "as is", and the risk is yours to hold. iconic legal behaviour, honestly. 💅✨

and that's a wrap on the whole page, bestie!! 🎀 this one came from the perl v5.34.0 docs, dated 2022-06-17 — go forth and run stuff, just like, at your own risk. mwah. 💖🦋🌸