App::Rad::Plugin::ReadLine - App::Rad::Plugin::ReadLine a Term::UI ->shell for Rad Apps
version 0.003
To run your app as a shell, you can either...
->shell
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
->shell_options
arguments to &shell are all optional, in the hope I can play nice with other plugins that implement a &shell method
&shell
#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.') {}; #...
#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.
... 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> ' }); }
#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
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
$c-
@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
App::Rad::Plugin::ReadLine::Demo qw[ getopt ]
All arguments are optional:
->shell_options( "name", "help" ) ->shell_options( { GreetWithCommand => 'help' } ) ->shell_options( { DefaultCommand => 'exit' }, 'subshell' ) ->shell_options;
\%options
GreetWithCommand => run this App::Rad command when the shell starts
GreetWithCommand
GreetWithSub => run this sub-ref (as a method on $c) when the shell starts
GreetWithSub
DefaultCommand => if the user doesn't enter a command, they entered this. '' will use App::Rad's default command.
DefaultCommand
ShellPrompt => what to prompt the user with, defautl is "$0 "
ShellPrompt
[$command_name, [ $command_help ]]
$command_name is the name of the sub-comamnd name
$command_name
$command_help is the help to pass
$command_help
... both are passed to $c->register, along with \&shell
$c->register
\&shell
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.
App::Rad
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...)
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
FOOLISH <FOOLISH@cpan.org>
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.
To install App::Rad::Plugin::ReadLine, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Rad::Plugin::ReadLine
CPAN shell
perl -MCPAN -e shell install App::Rad::Plugin::ReadLine
For more information on module installation, please visit the detailed CPAN module installation guide.