Extending App::Rad - Plugins!

   use App::Rad  qw(My::Module);

will load the "App::Rad::Plugin::My::Module" plugin for you!

Developers are strongly encouraged to publish their App::Rad plugins under the "App::Rad::Plugin" namespace. But, if your plugin start with a name other than that, you can fully qualify the name by using an unary plus sign:

  use App::Rad  qw(
          My::Module
          +Fully::Qualified::Plugin::Name
  );

Note that plugins are loaded in the order in which they appear.

Please refer to the actual plugin documentation for specific usage. And check out App::Rad::Plugin if you want to create your own plugins.

run()

help

You can also display specific embedded help for your commands, either explicitly registering them with "$c->register()" or "$c->register_commands()" inside "$c->setup()" (see respective sections below) or with the Help() attribute:

    use App::Rad;
    App::Rad->run();
    
    sub mycmd 
    :Help(display a nice welcome message) 
    {
        return "Welcome!";
    }

the associated help text would go like this:

    [user@host]$ ./myapp.pl
    Usage: myapp.pl command [arguments]

    Available Commands:
        help    show syntax and available commands
        mycmd   display a nice welcome message

include [command_name] -perl_params 'your subroutine code'

Let's say you have your simple 'myapp.pl' program that uses App::Rad sitting on your system quietly. One day, perhaps during your sysadmin's tasks, you create a really amazing one-liner to solve a really hairy problem, and want to keep it for posterity (reusability is always a good thing!).

For instance, to change a CSV file in place, adding a column on position #2 containing the line number, you might do something like this (this is merely illustrative, it's not actually the best way to do it):

    $ perl -i -paF, -le 'splice @F,1,0,$.; $_=join ",",@F' somesheet.csv

And you just found out that you might use this other times. What do you do? App::Rad to the rescue!

In the one-liner above, just switch 'perl' to 'myapp.pl include SUBNAME' and remove the trailing parameters (somesheet.csv):

    $ myapp.pl include addcsvcol -i -paF, -le 'splice @F,1,0,$.; $_=join ",",@F'

That's it! Now myapp.pl has the 'addcsvcol' command (granted, not the best name) and you can call it directly whenever you want:

    $ myapp.pl addcsvcol somesheet.csv

App::Rad not only transforms and adjusts your one-liner so it can be used inside your program, but also automatically formats it with Perl::Tidy (if you have it). This is what the one-liner above would look like inside your program:

    sub addcsvcol {
        my $c = shift;
    
        local ($^I) = "";
        local ($/)  = "\n";
        local ($\)  = "\n";
      LINE: while ( defined( $_ = <ARGV> ) ) {
            chomp $_;
            our (@F) = split( /,/, $_, 0 );
            splice @F, 1, 0, $.;
            $_ = join( ',', @F );
        }
        continue {
            die "-p destination: $!\n" unless print $_;
        }
    }

With so many arguments (-i, -p, -a -F,, -l -e), this is about as bad as it gets. And still one might find this way easier to document and mantain than a crude one-liner stored in your ~/.bash_history or similar.

Note: If you don't supply a name for your command, App::Rad will make one up for you (cmd1, cmd2, ...). But don't do that, as you'll have a hard time figuring out what that specific command does.

Another Note: App::Rad tries to adjust the command to its interface, but please keep in mind this module is still in its early stages so it's not guaranteed to work every time. *PLEASE* let me know via email or RT bug request if your one-liner was not correctly translated into an App::Rad command. Thanks!

exclude command_name

Note that built-in commands such as 'help' cannot be removed via exclude. They have to be added to your excluded list inside setup().

The Controller

Reading arguments

@ARGV

Perl's @ARGV array has all the arguments passed to your command, without the command name (use "$c->cmd" for this) and without any processing (even if you explicitly use "$c->getopt", which will change $c->argv instead, see below). Since the command itself won't be in the @ARGV parameters, you can use it in each command as if they were stand-alone programs.

$c->options

App::Rad lets you automatically retrieve any POSIX syntax command line options (getopt-style) passed to your command via the $c->options method. This method returns a hash reference with keys as given parameters and values as... well... values. The 'options' method automatically supports two simple argument structures:

Extended (long) option. Translates "--parameter or --parameter=value" into "$c->options->{parameter}". If no value is supplied, it will be set to 1.

Single-letter option. Translates "-p" into "$c->options->{p}".

Single-letter options can be nested together, so "-abc" will be parsed into "$c->options->{a}", "$c->options->{b}" and "$c->options{c}", while "--abc" will be parsed into "$c->options->{abc}". We could, for instance, create a dice-rolling command like this:

    sub roll {
        my $c = shift;

        my $value = 0;
        for ( 1..$c->options->{'times'} ) {
            $value += ( int(rand ($c->options->{'faces'}) + 1));
        }
        return $value;
    }

And now you can call your 'roll' command like:

    [user@host]$ ./myapp.pl roll --faces=6 --times=2

Note that App::Rad does not control which arguments can or cannot be passed: they are all parsed into "$c->options" and it's up to you to use whichever you want. For a more advanced use and control, see the "$c->getopt" method below.

Also note that single-letter options will be set to 1. However, if a user types them more than once, the value will be incremented accordingly. For example, if a user calls your program like so:

   [user@host]$ ./myapp.pl some_command -vvv

or

   [user@host]$ ./myapp.pl some_command -v -v -v

then, in both cases, "$c->options->{v}" will be set to 3. This will let you easily keep track of how many times any given option was chosen, and still let you just check for definedness if you don't care about that.

$c->argv

The array reference "$c->argv" contains every argument passed to your command that have not been parsed into "$c->options". This is usually a list of every provided argument that didn't start with a dash (-), unless you've called "$c->getopt" and used something like 'param=s' (again, see below).

$c->getopt (Advanced Getopt usage)

App::Rad is also smoothly integrated with Getopt::Long, so you can have even more flexibility and power while parsing your command's arguments, such as aliases and types. Call the "$c->getopt()" method anytime inside your commands (or just once in your "pre_process" function to always have the same interface) passing a simple array with your options, and refer back to $c->options to see them. For instance:

    sub roll {
        my $c = shift;

        $c->getopt( 'faces|f=i', 'times|t=i' )
            or $c->execute('usage') and return undef;

        # and now you have $c->options->{'faces'} 
        # and $c->options->{'times'} just like above.
    }

This becomes very handy for complex or feature-rich commands. Please refer to the Getopt::Long module for more usage examples.

So, in order to manipulate and use any arguments, remember:

• The given command name does not appear in the argument list;
• All given arguments are in @ARGV
• Automatically processed arguments are in "$c->options"
• Non-processed arguments (the ones "$c->options" didn't catch) are in $c->argv
• You can use "$c->getopt" to have "Getopt::Long" parse your arguments (it will not change @ARGV)

Sharing Data: "$c->stash"

    $c->stash->{foo} = 'bar';
    $c->stash->{herculoids} = [ qw(igoo tundro zok gloop gleep) ];
    $c->stash->{application} = { name => 'My Application' };

You can use it for more granularity and control over your program. For instance, you can email the output of a command if (and only if) something happened:

    sub command {
        my $c = shift;
        my $ret = do_something();

        if ( $ret =~ /critical error/ ) {
            $c->stash->{mail} = 1;
        }
        return $ret;
    }

    sub post_process {
        my $c = shift;

        if ( $c->stash->{mail} ) {
            # send email alert...
        }
        else {
            print $c->output . "\n";
        }
    }

Returning output

    my $ret = "Here's the list: ";
    $ret .= join ', ', 1..5;
    return $ret;
    
    # this prints "Here's the list: 1, 2, 3, 4, 5"

App::Rad lets you post-process the returned value of every command, so refrain from printing to STDOUT directly whenever possible as it will give much more power to your programs. See the post_process() control function further below in this document.

$c->execute( COMMAND_NAME )

$c->cmd

$c->command

Alias for "$c->cmd". This longer form is discouraged and may be removed in future versions, as one may confuse it with the "$c->commands()" method, explained below. You have been warned.

$c->commands()

$c->is_command ( COMMAND_NAME )

$c->create_command_name()

$c->load_config( FILE (FILE2, FILE3, ...) )

    # comments and blank lines are discarded
    key1 value1
    key2:value2
    key3=value3
    key5           # stand-alone attribute (and inline-comment)

$c->config

$c->register ( NAME, CODEREF [, INLINE_HELP ])

It is also very useful for creating aliases for your commands:

    sub setup {
        my $c = shift;
        $c->register_commands();

        $c->register('myalias', \&command);
    }

    sub command { return "Hi!" }

and, on the command line:

    [user@host]$ ./myapp.pl command
    Hi!

    [user@host]@ ./myapp.pl myalias
    Hi!

The last parameter is optional and lets you add inline help to your command:

    $c->register('cmd_name', \&cmd_func, 'display secret of life');

$c->register_command ( NAME, CODEREF [, INLINE_HELP ] )

Longer alias for "$c->register()". It's use is disencouraged as one may confuse it with "register_commands" (note the plural) below. Plus you type more :) As such, this method may be removed in future versions. You have been warned!

$c->register_commands()

Adding single commands

    $c->register_commands( qw/foo bar baz/ );

The code above will register only the subs "foo", "bar" and "baz" as commands. Other subroutines will not be valid commands, so they can be used as internal subs for your program. You can change this behavior with the bundled options - see 'Adding several commands' and 'Putting it all together' below.

Adding single commands (with inline help)

    $c->register_commands(
            {
                dos2unix => 'convert text files from DOS to Unix format',
                unix2dos => 'convert text files from Unix to DOS format',
            }
    );

You can pass a hash reference containing commands as keys and a small help string as their values. The code above will register only the subs "dos2unix" and "unix2dos", and the default help for your program will become something like this:

    [user@host]$ ./myapp.pl
    Usage: myapp.pl command [arguments]
    
    Available Commands:
        dos2unix    convert text files from DOS to Unix format
        help        show syntax and available commands
        unix2dos    convert text files from Unix to DOS format

Adding several commands

You can pass a hash reference as an argument, letting you choose which subroutines to add as commands. The following keys may be used (note the dash preceding each key):

• "-ignore_prefix": subroutine names starting with the given string won't be added as commands
• "-ignore_suffix": subroutine names ending with the given string won't be added as commands
• "-ignore_regexp": subroutine names matching the given regular expression (as a string) won't be added as commands

For example:

    use App::Rad;
    App::Rad->run();

    sub setup { 
        my $c = shift; 
        $c->register_commands( { -ignore_prefix => '_' } );
    }

    sub foo  {}  # will become a command
    sub bar  {}  # will become a command
    sub _baz {}  # will *NOT* become a command

This way you can easily segregate between commands and helper functions, making your code even more reusable without jeopardizing the command line interface (As of version 1.04, ignoring commands with underscore '_' prefixes is also the default App::Rad behavior).

Putting it all together

You can combine some of the options above to have even more flexibility:

    $c->register_commands(
            'foo',
            { -ignore_suffix => 'foo' },
            { bar => 'all your command line are belong to us' },
    );

The code above will register as commands all subs with names not ending in 'foo', but it will register the 'foo' sub as well. It will also give the 'bar' command the help string. This behavior is handy for registering several commands and having a few exceptions, or to add your commands and only have inline help for a few of them (as you see fit).

You don't have to worry about the order of your elements passed, App::Rad will figure them out for you in a DWIM fashion.

    # this does the same as the code above
    $c->register_commands(
            { bar => 'all your command line are belong to us' },
            'foo',
            { -ignore_suffix => 'foo' },
    );

You can even bundle the hash reference to include your "cmd => help" and special keys:

    # this behaves the same way as the code above:
    $c->register_commands(
        'foo',
        { 
            -ignore_suffix => 'foo',
            bar => 'all your command line are belong to us',
        }
    );

$c->unregister_command ( NAME )

$c->unregister ( NAME )

Unregisters a given command name so it's not available anymore. Note that the subroutine will still be there to be called from inside your program - it just won't be accessible via command line anymore.

$c->debug( MESSAGE )

    use App::Rad  qw( debug );

Note that, if debug is enabled, App::Rad itself will print several debug messages stating its current flow, so you can easily find out where everything is happening.

$c->plugins()

$c->load_plugin( PLUGIN NAME )

setup()

Another interesting thing you can do with setup is to manipulate the command list. For instance, you may want to be able to use the "include" and "exclude" commands, but not let them available for all users. So instead of writing:

    use App::Rad qw(include exclude);
    App::Rad->run();

you can write something like this:

    use App::Rad;
    App::Rad->run();

    sub setup {
        my $c = shift;
        $c->register_commands();

        # EUID is 'root'
        if ( $> == 0 ) {
            $c->register('include', \&App::Rad::include);
            $c->register('exclude', \&App::Rad::exclude);
        }
    }

to get something like this:

    [user@host]$ myapp.pl help
    Usage: myapp.pl command [arguments]

    Available Commands:
       help

    [user@host]$ sudo myapp.pl help
    Usage: myapp.pl command [arguments]

    Available Commands:
       exclude
       help
       include

default()

Default's default (grin) is just an alias for the help command.

    sub default {
        my $c = shift;

        # will fall here if the given
        # command isn't valid.
    }

You are free (and encouraged) to change the default behavior to whatever you want. This is rather useful for when your program will only do one thing, and as such it receives only parameters instead of command names. In those cases, use the ""default()"" sub as your main program's sub and parse the parameters with "$c->argv" and "$c->getopt" as you would in any other command.

invalid()

teardown()

pre_process()

    sub pre_process {
        my $c = shift;

        if ( $c->cmd eq 'some_command' and $> != 0 ) {
            $c->cmd = 'default'; # or some standard error message
        }
    }

post_process()

    sub post_process {
        my $c = shift;

        if ( $c->output() ) {
            print $c->output() . "\n";
        }
    }

You can override this function to include a default header/footer for your programs (either a label or perhaps a "Content-type: " string), parse the output in any ways you see fit (CPAN is your friend, as usual), etc.

IRC

   #app-rad  on irc.perl.org