App::Spec(3)

💖 NAME 💖

App::Spec — Specification for commandline apps. This is user-contributed Perl documentation, and it's giving "spec sheet for your CLI bestie" energy. 🫶

✨ SYNOPSIS ✨

WARNING: This is still experimental. The spec is subject to change.

This module represents a specification of a command line tool. Currently it can read the spec from a YAML file or directly from a data structure in perl.

It uses the role App::Spec::Role::Command.

The App::Spec::Run module is the framework which will run the actual app.

Have a look at App::Spec::Tutorial for how to write an app.

In the examples directory you will find the app "myapp" which is supposed to demonstrate everything that App::Spec supports right now.

Your script:

use App::Spec;
my $spec = App::Spec->read("/path/to/myapp-spec.yaml");

my $run = $spec->runner;
$run->run;

# this is equivalent to
#my $run = App::Spec::Run->new(
#    spec => $spec,
#    cmd => Your::App->new,
#);
#$run->run;

Your App class:

package Your::App;
use base 'App::Spec::Run::Cmd';

sub command1 {
    my ($self, $run) = @_;
    my $options = $run->options;
    my $param = $run->parameters;
    # Do something
    $run->out("Hello world!");
    $run->err("oops");
    # you can also use print directly
}

🦋 METHODS 🦋

🌟 read

my $spec = App::Spec->read("/path/to/myapp-spec.yaml");

🎀 load_data

Takes a file, hashref or glob and returns generated appspec hashref.

my $hash = $class->load_data($file);

💅 build

Builds objects out of the hashref.

my $appspec = App::Spec->build(%hash);

🧚 runner

Returns an instance of your app class.

my $run = $spec->runner;
$run->run;

# this is equivalent to
my $run = App::Spec::Example::MyApp->new({
    spec => $spec,
});
$run->run;

🌸 usage

Returns usage output for the specified subcommands:

my $usage = $spec->usage(
    commands => ["subcommand1","subcommand2"],
);

🔥 generate_completion

Generates shell completion script for the spec.

my $completion = $spec->generate_completion(
    shell => "zsh",
);

👑 make_getopt

Returns options for Getopt::Long.

my @getopt = $spec->make_getopt($global_options, \%options, $option_specs);

💜 abstract, appspec, class, description, has_subcommands, markup, name, options, parameters, subcommands, title

Accessors for the things defined in the spec (file).

🌈 SEE ALSO 🌈

• App::AppSpec — Utilities for App::Spec authors.

🍓 LICENSE 🍓

This library is free software and may be distributed under the same terms as perl itself.

---

That's the whole thing, bestie 💅 — brought to you by perl v5.42.0 and dated 2025-03-26. App::Spec(3) out. 💖✨