NAME

App::Commando - Flexible library to build command-line apps

VERSION

version 0.012

SYNOPSIS

    use App::Commando;

    my $program = App::Commando::program('example');
    $program->version('0.42');

    my $cmd_hello = $program->command('hello');
    $cmd_hello->syntax('hello TARGET');
    $cmd_hello->option('world', '-w', '--world', 'Say hello to the World');
    $cmd_hello->option('universe', '-u', '--universe', 'Say hello to the Universe');
    $cmd_hello->action(sub {
        my ($argv, $config) = @_;

        # Get the first argument or set the default value
        my $target = $argv->[0] || 'Everyone';
        $target = "World" if $config->{world};
        $target = "Universe" if $config->{universe};

        print "Hello, $target!\n";
    });

    my $cmd_bye = $program->command('bye');
    $cmd_bye->action(sub {
        print "Goodbye!\n";
    });

    $program->go;

DESCRIPTION

App::Commando is a lightweight library for building command-line applications, based on Ruby's Mercenary.

USAGE

App::Commando

App::Commando::program($name)

Creates a new instance of App::Commando::Program. Arguments:

$name

Program name.

Example:

    my $program = App::Commando::program('example');

Program

App::Commando::Program extends App::Commando::Command, so it inherits all its methods.

new($name)

Creates a new instance of App::Commando::Program. Arguments:

$name

Program name.

Example:

    my $program = App::Commando::Program->new('example');

Command

new($name, $parent)

Creates a new instance of App::Commando::Command. Arguments:

$name

New command name.

$parent

Parent command (optional).

Example:

    my $cmd = App::Commando::Command->new('foo');
    my $sub_cmd = App::Commando::Command->new('bar', $cmd);

version($version)

Gets or sets the version of the command. Arguments:

$version

New version to set (optional).

Example:

    $cmd->version('1.2.3');
    print $cmd->version;        # '1.2.3'

syntax($syntax)

Gets or sets command syntax. Arguments:

$syntax

The syntax to set for the command (optional).

Example:

    $cmd->syntax('foo <SUBCOMMAND> [OPTIONS]');
    print $cmd->syntax;         # 'foo <SUBCOMMAND> [OPTIONS]'

description($description)

Gets or sets command description. Arguments:

$description

The description to set for the command (optional).

Example:

    $cmd->description('Does whatever.');
    print $cmd->description;    # 'Does whatever.'

default_command($command_name)

Gets or sets the default subcommand to execute when no command name is passed to the program. Arguments:

$default_command

The name of the subcommand to be set as the default (optional).

Example:

    $cmd->default_command('bar');
    $cmd->default_command;      # An instance of App::Commando::Command

option($config_key, ...)

Adds a new option to the command. Arguments:

$config_key

The configuration key that this option corresponds to.

The remaining arguments are optional, and are processed based on their content:

• If the argument starts with a single dash (e.g., '-x'), it is assumed to be the short switch for the option.

• If the argument starts with a double dash (e.g., '--xyzzy'), it is assumed to be the long switch for the option.

• If the argument is formatted like a Getopt::Long option specification (e.g., '=s'), it is passed as the specification to Getopt::Long when command-line arguments are parsed. See "Summary of Option Specifications" in Getopt::Long for more information.

• Otherwise, the argument is assumed to be the option description (e.g., 'Enables xyzzy mode').

Example:

    $cmd->option('xyzzy', '-x', '--xyzzy', 'Enables xyzzy mode');

alias($command_name)

Adds an alias for this command, allowing the command to be executed using a different name. Arguments:

$command_name

The alias for this command.

Example:

    $cmd->alias('other');

action($code)

Adds a code block to be run when the command is called. Arguments:

$code

The code block to be executed.

The code block is passed two arguments:

$argv

An array reference containing non-switch arguments from the command-line.

$config

A hash reference containing configuration options that were passed using switches.

Example:

    $cmd->action(sub {
        my ($argv, $config) = @_;

        if ($config->{xyzzy}) {
            # ...
        }
    });

command($command_name)

Adds a new subcommand to this command. Arguments:

$command_name

The name of the new subcommand.

Example:

    my $sub_cmd = $cmd->command('bar');

ACKNOWLEDGEMENTS

The design of this library is based on Mercenary, written by Parker Moore.

SEE ALSO

• Getopt::Long

• https://github.com/jekyll/mercenary - Mercenary GitHub repository

SUPPORT

Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at https://github.com/odyniec/p5-App-Commando/issues. You will be notified automatically of any progress on your issue.

Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license.

https://github.com/odyniec/p5-App-Commando

  git clone https://github.com/odyniec/p5-App-Commando.git

AUTHOR

Michal Wojciechowski <odyniec@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Michal Wojciechowski.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm App::Commando

perl -MCPAN -e shell
install App::Commando