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
Your app as a shell. Type commands with arguments
Available Commands:
business You gotta do what you gotta do.
demo
exit exit the ./example/02-registered shell
help show syntax and available commands
interactive run ./example/02-registered in interactive mode
serious Important functionality - not to be joked about
[./example/02-registered] exit#.
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
Your app as a shell. Type commands with arguments
Available Commands:
critter_shell a sub-shell
demo
exit exit the ./example/03-subshell-app shell
help show syntax and available commands
something helpful things
status show current status
[./example/03-subshell-app] something
Helpful things going on: ... done
[./example/03-subshell-app] status
Deadlines: met
Financial: under budget
Customers: happy
Pigs : saddled up and ready for flight
[./example/03-subshell-app] critter_shell
Your app as a shell. Type commands with arguments
Available Commands:
critterfy setup critter instance for user with given id
decritterfy remove a critter, for the user with given id
exit exit the ./example/03-subshell-app shell
help show syntax and available commands
critters> critterfy
A critter has been configured for the current user
critters> exit
[./example/03-subshell-app] exit#.
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_nameworks 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.