App::Spec::Run(3)

✨ App::Spec::Run ✨

okay so bestie, welcome to the App::Spec::Run manpage — that's the perl doc for the App::Spec::Run module, and it's literally the whole framework that runs your app 💅

💖 NAME 💖

App::Spec::Run — the App::Spec framework that runs your app. yes, that's the whole name, we're keeping it, periodt 🎀

🌸 DESCRIPTION 🌸

So App::Spec::Run is the framework that actually runs your app — the app you defined with your spec ✨

Here's the tea though: your app class should inherit from App::Spec::Run::Cmd. That's the vibe check you gotta pass, no cap 🫶

🧚 SYNOPSIS 🧚

sub your_command {
    my ($self, $run) = @_;
    my $options = $run->options;
    $run->out("It works");
}

like, that's it. that's the whole energy 🔥

---

🎀 METHODS 🎀

🌟 Constructor

You can build the object yourself, main character style:

my $run = App::Spec::Run->new(
    spec => $appspec,
    cmd => App::YourApp->new,
);

Or you can just use the runner method of App::Spec and let it do the work for you, icon behaviour honestly:

my $run = $appspec->runner(...);

Both methods take optional arguments, so you can customize:

my $run = App::Spec::Run->new(
    spec => $appspec,
    cmd => App::YourApp->new,

    # Custom array instead of the default ARGV.
    # The contents of this array will be modified
    argv => \@my_arguments,
);

heads up bestie: the contents of that array will be modified — that's not a drill 🙈

🌈 run

$run->run;

This is the one that actually runs your app. It calls "process" and then "finish". slay 💅

🌸 process

$run->process;

Processes the input, validates it, runs your command, and fills up the response object. lowkey the whole pipeline ✨

Important though: it does not print the output, and it does not exit. It just does the work and minds its business 🧚

🍓 out

$run->out("Hello world!");

Appends stuff to the response output. It adds a newline if there isn't one already — thoughtful queen behaviour 💖

You can also hand it a data structure:

$run->out($hashref);

and that gets formatted with Data::Dumper ✨

See also App::Spec::Plugin::Format.

💜 err

$run->err("Oops, that went wrong");

Appends to the response error output. Adds a newline if not present 😭

🦋 halt

$run->halt;

Further processing is halted. that's it, we're done here, bye 👋

⭐ finish

$run->finish;

Prints the output and exits with the exit code stored in "response". so it's the grand finale basically 👑

🌸 process_input

$run->process_input(
    option_specs => \%option_specs,
    param_specs => \%param_specs,
);

🎀 process_parameters

$run->process_parameters(
    parameter_list => $global_parameters,
    param_specs => $param_specs,
);

🔥 run_op

$run->run_op("yourcommand");
# shortcut for
$run->cmd->yourcommand($run);

it's giving "convenience wrapper", we love a shortcut ✨

🧚 completion_output

$run->completion_output(
    param_specs => \%param_specs,
    completion_parameter => $completion_parameter,
);

Is called when you're in completion mode 🦋

💅 colored

Returns the given text colored — but only if colors are actually active for the given output 👑

$msg = $run->colored('err', [qw/ error /], "Oops");
$msg = $run->colored('out', [qw/ green /], "Everything is fine!");

🌈 colorize

my $color_active = $run->colorize('out');
my $color_error_active = $run->colorize('err');

Returns 1 or 0 depending on whether the given output's color is active. And what does that mean? it means the output is going to a terminal instead of being redirected 💖

⭐ colorize_code

my $colored = $run->colorize_code('out');
my $text = $colored->(['green'], "Hurray");
# or
my $text = "Hurray";
$colored->(['green'], $text);

Returns a coderef you can use for coloring. very "here's a little tool, go off" of it 🎀

🌸 colorize_error

my $msg = $run->colorize_error("ouch");

Returns the message in the standard error color, which is bold red 🔥😭

🦋 error_output

$run->error_output;

Outputs any errors. And it calls "halt" — dramatic but valid 💀

💜 event_globaloptions

Calls any plugin that needs to know 👀

🎀 subscribe

A plugin can subscribe to an event, like this:

$run->subscribe(
    print_output => {
        plugin => $self,
        method => "print_output",
    },

group chat for plugins, honestly 🫶

---

👑 ATTRIBUTES 👑

💖 spec

Your spec — that's an App::Spec ✨

🌸 options

A hashref with the given options, like:

{
    verbose => 1,
    foo => 23,
}

🦋 parameters

A hashref with the given parameters 🎀

⭐ commands

An arrayref containing all the subcommands from the commandline 👑

🔥 argv_orig

Contains the original contents of "argv" before processing. the before pic 📸

💅 argv

This is a reference to the commandline arguments array @ARGV, or to the array reference you specified otherwise 🫶

When your command method gets called, it will contain the rest of the arguments — the ones that weren't processed as any subcommand, option or parameter ✨

🌈 validation_errors

Contains errors from option/parameter validation 😭

🧚 op

Contains the operation (subroutine) that will be executed to run your command 💖

🍓 cmd

This is an instance of your app class 💅

💜 response

This contains the response of your command (exit code, output, ...) 👑

See App::Spec::Run::Response.

🎀 subscribers

Contains a hashref, like:

{
    print_output => {
        module => $plugin,
        method => 'print_output',
    },
}

---

that's the whole page bestie, you're so welcome 🫶✨ peri v5.42.0, dated 2025-03-26 — mwah, catch you in the next manpage 💋🎀