NAME

CLI::Application - (not yet) extensible CLI application framework

SYNOPSIS

        use CLI::Application;

        my $app = new CLI::Application(
                name => 'test',
                version => '0.01',
                options => [
                        [ [ qw( t test ) ], 'Test option.' ],
                        [ [ qw( a any ) ], 'Option with any argument.', 1 ],
                        [ [ qw( f foobar ) ], 'Option with argument foo or bar.', [qw(foo bar)] ],
                ],
                plugins => [ qw( RC::YAML ) ],
        );

        sub list : Command('Show list of items.') : Fallback {
                my ($app) = @_;
                # list items ...
        }

        sub add : Command('Add item.') {
                my ($app) = @_;
                print "TEST!\n" if($options->{test});
                # add item
                add_item($app->arguments);
        }

        sub remove : Command('Remove item.') {
                my ($app) = @_;
                my $any = $app->option('any');
                for my $item_id ($app->arguments) {
                        remove_item($item_id);
                }
        }

DESCRIPTION

CLI::Application is another framework for writing command line applications. It provides automatic parsing of and validating of command line options, generating of usage texts based on your option definitions and dispatching to commands based on code attributes, similar to Catalyst. In future, support for plugins will be added, so additional functionality can be imported easily.

METHODS

new(application setup hash)

The constructor takes a hash with all the data the framework needs to get your application started. The contents are explained below.

name

The name of your application

version

The version of your application

options

A list of the options your application understands. Each option is an array of two to four elements. The first element is another array of strings which are used as the option names. Single character strings will be used as short options (like '-f'), longer strings will be long arguments (e.g. '--file'). It's a good idea to always provide both, but that's up to you. If more than one string is given and the option is set on command line, the option is available to you (using the option method) with any of the strings. The second element is a short description of your option. This will be used automatically generated usage and help texts. The third argument is optional. If it is true, CLI::Application will expect the option to have an argument and will die with a usage message if it is missing. If the value is just a true scalar, any argument is allowed. If it is a regular expression, that expression will be applied on the argument, and the argument is considered invalid if the expression doesn't match. If the value is an array reference, the argument must be one of the referenced arrays elements to be valid. If the value is a code reference, the referenced code will be called with the argument as argument, and it should return a boolean to indicate if the argument is valid or not. If the fourth element of the option array is given and the argument of the option is invalid, the value will be added to the error message printed to the user.

plugins

Names of plugins to load. See CLI::Application::Plugin to learn how to write/use plugins.

prepare(arguments)

Prepare the application for runtime. The argument will typically be @ARGV, but may be any list of values. The elements of this list will be used for parsing options and arguments and detecting the command to later.

dispatch(command)

Dispatch to a command. If no command is given as argument, the action will be taken from the argument list given to the prepare method. If no action is found, the fallback command will be called, if available. If this fails too, CLI::Application will die with an error.

option(option, argument)

This is the getter/setter for options.

arguments

Returns a list of arguments.

action(action)

Getter/setter for the command that CLI::Application is going to execute. Use this after a call to prepare to find out what CLI::Application thinks is the action the user wants to execute, or to overwrite it. See dispatch.

name

Returns the application name.

usage(message)

Return a usage text containing action and option descriptions. Any arguments will be prepended.

COMMANDS

Commands are simple functions that have the 'Command' label. That label may/should have a string as argument that describes the action in short. That text will be used in the usage text. Command functions will be called with the CLI::Application object as argument, so you can get options and arguments from it in the function.

The command to execute is determined from the command line arguments given to prepare. The first argument that is not an option or option argument will be used as the name of the command to execute. If there is no function with the name and with the Command label, CLI::Application will die with an error. If no non-option argument is found, the function with the label 'Fallback' will be used, if found. Only one function should have that label, otherwise the last function labeled with 'Fallback' will be used (in order of definition).

        # This will be called if the command argument is 'list' or if no other
        # command is found. In the second form, no other non-option arguments are
        # possible, because there would be no way to tell them apart from command
        # names.
        # $ my-app -o some-option list <more arguments>
        # $ my-app -o some-option
        sub list : Command('Print list of something.') : Fallback {
                my ($app) = @_;
                print "List goes here...\n";
        }

        # This will be called only if there is an command argument and if it equals
        # 'add'.
        # $ my-app -o some-option add <more arguments>
        sub add : Command('Add something.') {
                my ($app) = @_;
                print "Adding something...\n";
        }

TODO

• Add support for plugins.

• Write plugin for automatic configuration file detection and parsing.

BUGS

Please report bugs in the CPAN bug tracker.

COPYRIGHT

Copyright (C) 2008 by Jonas Kramer. Published under the terms of the Artistic License 2.0.