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_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.