NAME

App::Rad::Plugin::ReadLine - App::Rad::Plugin::ReadLine a Term::UI ->shell for Rad Apps

VERSION

version 0.002

SYNOPSIS

To run your app as a shell, you can either...

call ->shell from an action ...

start shell mode straight away from a sub-command

#see ./example/01-myapp

#! /usr/bin/perl
#...
use App::Rad qw[ ReadLine ];
App::Rad->run();
sub turtles :Help('do it in the shell'){
    my $c = shift;
    $c->shell({
        GreetWithCommand => '',  # use what App::Rad decides is the default
        ShellPrompt => 'c/,,\\'  # ascii turtle for the prompt
    });
}

#end of listing

#running ./example/01-myapp demo turtles exit

Usage: ./example/01-myapp command [arguments]

Available Commands:
    help   	show syntax and available commands
    turtles	do it in the shell

#.

->shell takes the same options as ->shell_options

arguments to &shell are all optional, in the hope I can play nice with other plugins that implement a &shell method

... or call ->shell_options in setup and (optionally) specify a sub-command name

#see ./example/02-registered

#! /usr/bin/perl
#...
use App::Rad qw[ ReadLine ];
App::Rad->run();
sub setup {
    my $c = shift;
    $c->register_commands(
        'serious', 'business'
        #...other commands here 
    );
    $c->shell_options( 'interactive' );    # all args optional, with sensible defaults
}

sub serious  :Help('Important functionality - not to be joked about') {};
sub business :Help('You gotta do what you gotta do.') {};
#...

#end of listing

#running ./example/02-registered demo interactive

## 02-registered exited with 255

If you call ->shell_options you will get an extra sub-command that starts a shell for you.

You can do both...

... allowing you to have a shell for App-wide commands, and another (sub) shell with different commands:

#see ./example/03-subshell-app

#! /usr/bin/perl
#...
use App::Rad qw[ ReadLine ];
App::Rad->run();
sub setup {
    my $c = shift;
    $c->register_commands( qw[ demo critter_shell ] );
    $c->register( something => sub {
            #...
        }, 'helpful things'
    );
    $c->register( status => sub {
            #...
        }, 'show current status'
    );
    $c->shell_options;
}
sub critter_shell : Help('a sub-shell'){
    my $c=shift;
    # set up commands to be visible in critter_shell, they will
    # not be available from the command line

    $c->unregister_command( $_ ) for qw[ something status demo critter_shell ];
    $c->register( critterfy     => sub {
            "A critter has been configured for the current user\n" # boring;
        }, 'setup critter instance for user with given id');
    $c->register( decritterfy   => sub {}, 'remove a critter, for the user with given id' );

    $c->shell({ ShellPrompt => 'critters> ' });
}

#end of listing

#running ./example/03-subshell-app demo shell something status critter_shell critterfy exit

## 03-subshell-app exited with 255

Commands with arguments

The arguments to your your commands are done in an I could be the shell for all you know way ...

[./yourapp] sub_name

works just fine, you can see it going on in the subs above.

[./yourapp] subname --switch ordinal options 

seems to result in the correct things in $c-options>, $c-argv> and @ARGV

You can import App::Rad::Plugin::ReadLine::Demo qw[ getopt ] into your app as an action, and run it a couple of times to see the arguments being interpreted

shell_options( [ \%options ], [ $command_name, [ $command_help ]])

All arguments are optional:

->shell_options( "name", "help" )
->shell_options( { GreetWithCommand => 'help' } )
->shell_options( { DefaultCommand   => 'exit' }, 'subshell' )
->shell_options;

\%options's keys are:

GreetWithCommand => run this App::Rad command when the shell starts

GreetWithSub => run this sub-ref (as a method on $c) when the shell starts

DefaultCommand => if the user doesn't enter a command, they entered this. '' will use App::Rad's default command.

ShellPrompt => what to prompt the user with, defautl is "$0 "

[$command_name, [ $command_help ]]:

$command_name is the name of the sub-comamnd name

$command_help is the help to pass

... both are passed to $c->register, along with \&shell

BUGS

If you found a bug feel free to report it via http://rt.cpan.org/ (you could use App::rtpaste if you wanted to)

It's fairly likely that App::Rad apps expect more (or less) interfeering with than this module provides ... it's sad but true.

If you're complaining about how poor a job I've done please include as may of the following as you can:

• What you expected it to do

• What it did

• How you made it do that

  (a test case, or your app would be idea)

• How you made it stop doing that

  (ie a patch to fix it, or a work around...)

BUGS

Please report any bugs or feature requests to bug-app-rad-plugin-readline@rt.cpan.org or through the web interface at: http://rt.cpan.org/Public/Dist/Display.html?Name=App-Rad-Plugin-ReadLine

AUTHOR

FOOLISH <FOOLISH@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by FOOLISH.

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::Rad::Plugin::ReadLine

perl -MCPAN -e shell
install App::Rad::Plugin::ReadLine