The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Command-Do-0.120011
++
/ Command::Do

NAME

Command::Do - Command-Line Applications Made Simple

VERSION

version 0.120011

SYNOPSIS

A simple script with option and argument parsing.

    use Command::Do;

    # default command (execute runs on-load)
    execute command sub {
        my ($self, $opts, $args) = @_;
        printf "You sunk my %s\n", $opts->{vessel} || 'Battleship';
    };

    # example usage
    $ ./yourcmd

A simple script with option/argument parsing and input validation.

    use Command::Do -less;

    field vessel => {
        required => 1,
        filters  => ['trim','strip','titlecase'],
        default  => 'Battleship'
    };

    # default command (execute runs on-load)
    execute command sub {
        my ($self, $opts, $args) = @_;
        printf "You sunk my %s\n", $self->vessel;
    };

    # example usage
    $ ./yourcmd --vessel Yacht

A simple script with option/argument parsing, input validation, and sub-commands.

    use Command::Do -less;

    field vessel => {
        required => 1,
        filters  => ['trim','strip','titlecase'],
        default  => 'Battleship'
    };

    command move => sub {
        my ($self, $opts, $args) = @_;
        printf "Relocating your %s\n", $self->vessel;
    };

    command engage => sub {
        my ($self, $opts, $args) = @_;
        printf "Your %s has engaged enemy aircrafts\n", $self->vessel;
    };

    # default command (execute runs on-load)
    execute command sub {
        my ($self, $opts, $args) = @_;
        printf "You sunk my %s\n", $self->vessel;
    };

    # example usage
    $ ./yourcmd engage
    $ ./yourcmd move --vessel 'Cruise Ship'
    $ ./yourcmd --vessel=Battleship

A simple script with option/argument parsing, validation, sub-commands and documentation. Let your documentation determine which options and arguments your program expects.

    package YourCmd;

    use Command::Do -less;

    field name => {
        required  => 1,
        filters   => ['trim', 'strip', 'titlecase'],
        min_alpha => 4,
    };

    field x => {
        filters => ['trim', 'strip', 'numeric'],
        default => 0
    };

    field y => {
        filters => ['trim', 'strip', 'numeric'],
        default => 0
    };

    command new => sub {
        my ($self, $opts, $args) = @_;
        $self->validate('name')
            or $self->render_errors;

        # create new ship
    };

    command evade => sub {
        my ($self, $opts, $args) = @_;
        $self->validate('name', 'y', 'x')
            or $self->render_errors;

        # move ship to different coordinates
        # e.g. using $opts->{speed} which defaults to 10
    };

    command submerge => sub {
        my ($self, $opts, $args) = @_;
        $self->validate('name', 'x', 'y')
            or $self->render_errors;

        # cause ship to be under water
    };

    # roll your own output rendering
    sub render_errors {
        my ($self) = @_;
        print STDERR $self->errors_to_string, "\n";
        exit(1);
    }

    1;

    # The DATA section will be render to STDOUT automatically unless the default
    # command or a sub-command matched the execution

    __DATA__

    Battleship Script.

    Usage:
        yourcmd new <name>
        yourcmd evade <name> <x> <y> [--speed=<kn>]
        yourcmd submerge <name> <x> <y>

    Options:
        --speed=<kn>  Speed in knots [default: 10].

As depicted, you can opt in or out of most all features. Please see Validation::Class for more information on creating field definitions for validation, and see Docopt for more information on the usage-text format and parser specification.

DESCRIPTION

Command::Do is a simple toolkit for building simple or sophisticated command-line applications with ease. It includes very little magic, executes quickly, and is useful when creating, validating, executing, and organizing command-line applications and actions. Command::Do inherits most of its functionality from Validation::Class which allows you to focus on describing your command-line arguments and how they should be validated. Command::Do also uses Docopt and Smart::Options for parsing additional command-line options and arguments. Command::Do is very unassuming as thus flexible. It does not impose a particular application configuration and its dependencies are trivial and easily fat-packed. Command::Do simply provides you with the tools to create simple or sophisticated command-line interfaces, all wrapped-up in a nice DSL.

The name Command::Do is meant to convey the idea, command-and-do, i.e., write a command and do something! Leave the parsing, routing, validating, exception handling and execution to the framework. Command::Do inherits the following methods from Validation::Class, (command, execute, usages, build, directive, document, field, filter, message, method, mixin, profile and prototype) and implements the following new ones.

METHODS

command

The command function/method is used to register a coderef by name which may be automatically invoked by the execute method if it's name matches the first argument to the execute method. The command method can be passed a coderef, or a name and coderef. The coderef, when executed will be passed an instance of the current class, a hashref of command-line options, and an arrayref of extra command-line arguments. If passed a coderef without an associated name, that routine will be registered as the default routine to be executed by default if/when no other named routines match.

    # sub-command to be execute when <name> matches the first argument
    command name => sub {
        my ($self, $options, $arguments) = @_;
        ...
    };

    # default command to be execute unless a sub-command matches the request
    # the default command is passed an additional argument, the usages-text
    # which can be print to the console
    command name => sub {
        my ($self, $options, $arguments, $usages_text) = @_;
        ...
    };

execute

The execute function/method is used to process the command-line request by parsing the options and arguments and finding a matching pattern, action and/or routine and executing it. The execute method can take a list of arguments but defaults to using @ARGV. This method can also be used as a function to initiate the parsing and execution process from within a script.

    # instantiate and execute from anywhere, using execute as a function
    # will cause the code to execute whenever/wherever loaded
    my $self = YourCmd->new;
    $self->execute;

usages

The usages function/method is used to register the Docopt compatible command-line interface specification. This specification will be parsed for instructions, e.g. default-values, constraints, execution patterns, options and more.

    usages q{
    yourcmd. does stuff.

    Usage:
        run         causes the console to run
        jump        causes the console to jump
        play        causes the console to play

    Options:
        -h --hours  [default: 8]
    };

If the usages text is not registered using this function, Command::Do will examine the DATA section for instructions.

    __DATA__
    yourcmd. does stuff.

    Usage:
        run         causes the console to run
        jump        causes the console to jump
        play        causes the console to play

    Options:
        -h --hours  [default: 8]

AUTHOR

Al Newkirk <anewkirk@ana.io>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Al Newkirk.

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