The Perl and Raku Conference 2025: Greenville, South Carolina - June 27-29 Learn more

 / 
App-Rad-Plugin-ReadLine-0.002
River stage zero No dependents
/ App::Rad::Plugin::ReadLine

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.