NAME

Command::Do - The power of the Sun in the palm of your hand

VERSION

version 0.08

SYNOPSIS

in yourcmd:

    use YourCmd;
    YourCmd->run;

in lib/YourCmd.pm

    package YourCmd;
    
    use Command::Do;
    
    fld name => {
        required => 1,
        alias    => 'n',
        optspec  => '=s'
    };
    
    mth run => {
        
        input => ['name'],
        using => sub {
            
            exit print "You sure have a nice name, ", shift->name, "\n";
            
        }
        
    };

and, finally, at the command line:

    $ yourcmd --name "Handsome"
    You sure have a nice name, Handsome

DESCRIPTION

Command::Do is an extremely easy method for creating, validating, executing, and organizing command-line applications. Command::Do inherits most of its functionality from the ever-awesome Validation::Class and Getopt::Long.

Command::Do is both simple, effective and anti-complicated. It is very unassumming and flexible. It does not impose a particular application configuration and its dependencies are trivial.

... sometimes you need an all-in-one command script:

    package yourcmd;
    use Command::Do;
    
    mixin all  => {
        filters => [qw/trim strip/]
    };
    
    field file => {
        mixin   => 'all',
        optspec => 's@', # 100% Getopt::Long Compliant
        alias   => ['f'] # directive is attached to the option spec
    }; 
    
    # self-validating routines
    method run => {
    
        input => ['file'],
        using => sub {
            
            # because the opt_spec is s@, file is always an array
            exit print join "\n", @{shift->file};
                       
        }
        
    };
    
    yourcmd->run;

... sometimes you need a suite of commands:

    package yourcmd;
    use Command::Do;
    set
    {
        # each command is independent and can invoke sub-classes
        classes => 1, # loads and registers yourcmd::*
        
    };
    
    # pass args to children
    Getopt::Long::Configure(qw(pass_through));
    
    # the child command
    fld command => {
    
        required   => 1,
        min_length => 2,
        filters    => ['trim', 'strip', sub { $_[0] =~ s/\W/\_/g; $_[0] }]
    
    };
    
    # happens at instantiation
    build sub {
        
        my $self = shift;
        
        $self->command(shift @ARGV);
        
        return $self;
        
    };
    
    sub run {
    
        my $self = shift;
        
        my $command = $self->command;
        
        die $self->error_to_string("\n") unless $command;
        
        # invokes child command using the class method ...
        # see Validation::Class
        
        my $subcmd = $self->class($command); # load lib/YourCmd/SubCmd.pm
        
        return $subcmd->run;
        
    };
    
    yourcmd->run;

Please note: Command::Do is very minimalistic and tries to remain unassuming, each class field (see Validation::Class) that is to be used as a command line option must have an optspec directive defined. The optspec directive should be a valid Getopt::Long option specification minus a name and aliases which are deduced from the field name and alias directive.

    package MyCommand;
    use Command::Do;
    
    field verbose => {
        optspec => '', # sets flag, same as '!'
        alias   => 'v'
    };
    
    # this is the equivalent to the following Getopt::Long statement
    # GetOptions('verbose|v!' => \$variable);

Furthermore, in addition to being a class that represents a command that does stuff, Command::Do is also described as follows:

    com-man-do: A soldier specially trained to carry out raids.
    
    In English, the term commando means a specific kind of individual soldier or
    military unit. In contemporary usage, commando usually means elite light
    infantry and/or special operations forces units, specializing in amphibious
    landings, parachuting, rappelling and similar techniques, to conduct and
    effect attacks. (per wikipedia)

... which is how I like to think about the command-line scripts I author.

AUTHOR

Al Newkirk <awncorp@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by awncorp.

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