.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "App::Rad 3pm" .TH App::Rad 3pm "2022-10-13" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" App::Rad \- Rapid (and easy!) creation of command line applications .SH "VERSION" .IX Header "VERSION" Version 1.04 .SH "SYNOPSIS" .IX Header "SYNOPSIS" This is your smallest working application (let's call it \fImyapp.pl\fR) .PP .Vb 2 \& use App::Rad; \& App::Rad\->run(); .Ve .PP That's it, your program already works and you can use it directly via the command line (try it!) .PP .Vb 2 \& [user@host]$ ./myapp.pl \& Usage: myapp.pl command [arguments] \& \& Available Commands: \& help show syntax and available commands .Ve .PP Next, start creating your own functions (e.g.) inside \fImyapp.pl\fR: .PP .Vb 3 \& sub hello { \& return "Hello, World!"; \& } .Ve .PP And now your simple command line program \fImyapp.pl\fR has a 'hello' command! .PP .Vb 2 \& [user@host]$ ./myapp.pl \& Usage: myapp.pl command [arguments] \& \& Available Commands: \& hello \& help show syntax and available commands \& \& \& [user@host]$ ./myapp.pl hello \& Hello, World! .Ve .PP You could easily add a customized help message for your command through the '\fBHelp()\fR' attribute: .PP .Vb 5 \& sub hello \& :Help(give a nice compliment) \& { \& return "Hello, World!"; \& } .Ve .PP And then, as expected: .PP .Vb 2 \& [user@host]$ ./myapp.pl \& Usage: myapp.pl command [arguments] \& \& Available Commands: \& hello give a nice compliment \& help show syntax and available commands .Ve .PP App::Rad also lets you expand your applications, providing a lot of flexibility for every command, with embedded help, argument and options parsing, configuration file, default behavior, and much more: .PP .Vb 2 \& use App::Rad; \& App::Rad\->run(); \& \& sub setup { \& my $c = shift; \& \& $c\->register_commands( { \& foo => \*(Aqexpand your foo!\*(Aq, \& bar => \*(Aqhave a drink! arguments: \-\-drink=DRINK\*(Aq, \& }); \& } \& \& sub foo { \& my $c = shift; \& $c\->load_config(\*(Aqmyapp.conf\*(Aq); \& \& return \*(Aqfoo expanded to \*(Aq . baz() * $c\->config\->{\*(Aqmyfoo\*(Aq}; \& } \& \& # note that \*(Aqbaz\*(Aq was not registered as a command, \& # so it can\*(Aqt be called from the outside. \& sub baz { rand(10) } \& \& sub bar { \& my $c = shift; \& if ( $c\->options\->{\*(Aqdrink\*(Aq} ) { \& return \*(Aqyou asked for a \*(Aq . $c\->options\->{\*(Aqdrink\*(Aq}; \& } \& else { \& return \*(Aqyou need to ask for a drink\*(Aq; \& } \& } .Ve .PP You can try on the command line: .PP .Vb 2 \& [user@host]$ ./myapp.pl \& Usage: myapp.pl command [arguments] \& \& Available Commands: \& bar have a drink! arguments: \-\-drink=DRINK \& foo expand your foo! \& help show syntax and available commands \& \& \& [user@host]$ ./myapp.pl bar \-\-drink=martini \& you asked for a martini .Ve .SH "WARNING" .IX Header "WARNING" This module is very young, likely to change in strange ways and to have some bugs (please report if you find any!). I will try to keep the \s-1API\s0 stable, but even that is subject to change (let me know if you find anything annoying or have a wishlist). You have been warned! .SH "DESCRIPTION" .IX Header "DESCRIPTION" App::Rad aims to be a simple yet powerful framework for developing your command-line applications. It can easily transform your Perl \fIone-liners\fR into reusable subroutines than can be called directly by the user of your program. .PP It also tries to provide a handy interface for your common command-line tasks. \fBIf you have a feature request to easen out your tasks even more, please drop me an email or a \s-1RT\s0 feature request.\fR .SS "Extending App::Rad \- Plugins!" .IX Subsection "Extending App::Rad - Plugins!" App::Rad plugins can be loaded by naming them as arguments to the \f(CW\*(C`use App::Rad\*(C'\fR statement. Just ommit the \f(CW\*(C`App::Rad::Plugin\*(C'\fR prefix from the plugin name. For example: .PP .Vb 1 \& use App::Rad qw(My::Module); .Ve .PP will load the \f(CW\*(C`App::Rad::Plugin::My::Module\*(C'\fR plugin for you! .PP Developers are \fBstrongly\fR encouraged to publish their App::Rad plugins under the \f(CW\*(C`App::Rad::Plugin\*(C'\fR namespace. But, if your plugin start with a name other than that, you can fully qualify the name by using an unary plus sign: .PP .Vb 4 \& use App::Rad qw( \& My::Module \& +Fully::Qualified::Plugin::Name \& ); .Ve .PP Note that plugins are loaded in the order in which they appear. .PP \&\fBPlease refer to the actual plugin documentation for specific usage\fR. And check out App::Rad::Plugin if you want to create your own plugins. .SH "INSTANTIATION" .IX Header "INSTANTIATION" These are the main execution calls for the application. In your App::Rad programs, the \fB*ONLY*\fR thing your script needs to actually (and actively) call is one of the instantiation (or dispatcher) methods. Leave all the rest to your subs. Currently, the only available dispatcher is \fBrun()\fR: .SS "\fBrun()\fP" .IX Subsection "run()" You'll be able to access all of your program's commands directly through the command line, as shown in the synopsis. .SH "BUILT-IN COMMANDS" .IX Header "BUILT-IN COMMANDS" This module comes with the following default commands. You are free to override them as you see fit. .SS "help" .IX Subsection "help" Shows help information for your program. This built-in function displays the program name and all available commands (including the ones you added yourself) if a user types the 'help' command, or no command at all, or any command that does not exist (as they'd fall into the 'default' control function which (by default) calls 'help'). .PP You can also display specific embedded help for your commands, either explicitly registering them with \f(CW\*(C`$c\->register()\*(C'\fR or \f(CW\*(C`$c\->register_commands()\*(C'\fR inside \f(CW\*(C`$c\->setup()\*(C'\fR (see respective sections below) or with the \fBHelp()\fR attribute: .PP .Vb 2 \& use App::Rad; \& App::Rad\->run(); \& \& sub mycmd \& :Help(display a nice welcome message) \& { \& return "Welcome!"; \& } .Ve .PP the associated help text would go like this: .PP .Vb 2 \& [user@host]$ ./myapp.pl \& Usage: myapp.pl command [arguments] \& \& Available Commands: \& help show syntax and available commands \& mycmd display a nice welcome message .Ve .SH "OTHER BUILT IN COMMANDS (OPT-IN)" .IX Header "OTHER BUILT IN COMMANDS (OPT-IN)" The 'include' and 'exclude' commands below let the user include and exclude commands to your program and, as this might be dangerous when the user is not yourself, you have to opt-in on them: .PP .Vb 2 \& use App::Rad qw(include); # add the \*(Aqinclude\*(Aq command \& use App::Rad qw(exclude); # add the \*(Aqexclude\*(Aq command .Ve .PP though you'll probably want to set them both: .PP .Vb 1 \& use App::Rad qw(include exclude); .Ve .SS "include \fI[command_name]\fP \fI\-perl_params\fP \fI'your subroutine code'\fP" .IX Subsection "include [command_name] -perl_params 'your subroutine code'" Includes the given subroutine into your program on-the-fly, just as you would writing it directly into your program. .PP Let's say you have your simple \fI'myapp.pl'\fR program that uses App::Rad sitting on your system quietly. One day, perhaps during your sysadmin's tasks, you create a really amazing one-liner to solve a really hairy problem, and want to keep it for posterity (reusability is always a good thing!). .PP For instance, to change a \s-1CSV\s0 file in place, adding a column on position #2 containing the line number, you might do something like this (this is merely illustrative, it's not actually the best way to do it): .PP .Vb 1 \& $ perl \-i \-paF, \-le \*(Aqsplice @F,1,0,$.; $_=join ",",@F\*(Aq somesheet.csv .Ve .PP And you just found out that you might use this other times. What do you do? App::Rad to the rescue! .PP In the one-liner above, just switch \fI'perl'\fR to \fI'myapp.pl include \s-1SUBNAME\s0'\fR and remove the trailing parameters (\fIsomesheet.csv\fR): .PP .Vb 1 \& $ myapp.pl include addcsvcol \-i \-paF, \-le \*(Aqsplice @F,1,0,$.; $_=join ",",@F\*(Aq .Ve .PP That's it! Now myapp.pl has the 'addcsvcol' command (granted, not the best name) and you can call it directly whenever you want: .PP .Vb 1 \& $ myapp.pl addcsvcol somesheet.csv .Ve .PP App::Rad not only transforms and adjusts your one-liner so it can be used inside your program, but also automatically formats it with Perl::Tidy (if you have it). This is what the one-liner above would look like inside your program: .PP .Vb 2 \& sub addcsvcol { \& my $c = shift; \& \& local ($^I) = ""; \& local ($/) = "\en"; \& local ($\e) = "\en"; \& LINE: while ( defined( $_ = ) ) { \& chomp $_; \& our (@F) = split( /,/, $_, 0 ); \& splice @F, 1, 0, $.; \& $_ = join( \*(Aq,\*(Aq, @F ); \& } \& continue { \& die "\-p destination: $!\en" unless print $_; \& } \& } .Ve .PP With so many arguments (\-i, \-p, \-a \-F,, \-l \-e), this is about as bad as it gets. And still one might find this way easier to document and mantain than a crude one-liner stored in your ~/.bash_history or similar. .PP \&\fBNote:\fR If you don't supply a name for your command, App::Rad will make one up for you (cmd1, cmd2, ...). But don't do that, as you'll have a hard time figuring out what that specific command does. .PP \&\fBAnother Note: App::Rad tries to adjust the command to its interface, but please keep in mind this module is still in its early stages so it's not guaranteed to work every time. *PLEASE* let me know via email or \s-1RT\s0 bug request if your one-liner was not correctly translated into an App::Rad command. Thanks!\fR .SS "exclude \fIcommand_name\fP" .IX Subsection "exclude command_name" Removes the requested function from your program. Note that this will delete the actual code from your program, so be *extra* careful. It is strongly recommended that you do not use this command and either remove the subroutine yourself or add the function to your excluded list inside \fI\f(BIsetup()\fI\fR. .PP Note that built-in commands such as 'help' cannot be removed via \fIexclude\fR. They have to be added to your excluded list inside \fI\f(BIsetup()\fI\fR. .SH "ROLLING YOUR OWN COMMANDS" .IX Header "ROLLING YOUR OWN COMMANDS" Creating a new command is as easy as writing any sub inside your program. Some names (\*(L"setup\*(R", \*(L"default\*(R", \*(L"invalid\*(R", \*(L"pre_process\*(R", \*(L"post_process\*(R" and \*(L"teardown\*(R") are reserved for special purposes (see the \fIControl Functions\fR section of this document). App::Rad provides a nice interface for reading command line input and writing formatted output: .SS "The Controller" .IX Subsection "The Controller" Every command (sub) you create receives the controller object "\f(CW$c\fR\*(L" (sometimes referred as \*(R"\f(CW$self\fR" in other projects) as an argument. The controller is the main interface to App::Rad and has several methods to easen your command manipulation and execution tasks. .SS "Reading arguments" .IX Subsection "Reading arguments" When someone types in a command, she may pass some arguments to it. Those arguments can be accessed in four different ways, depending on what you want. This way it's up to you to control which and how many arguments (if at all) you want to receive and/or use. They are: .PP \fI\f(CI@ARGV\fI\fR .IX Subsection "@ARGV" .PP Perl's \f(CW@ARGV\fR array has all the arguments passed to your command, without the command name (use \f(CW\*(C`$c\->cmd\*(C'\fR for this) and without any processing (even if you explicitly use \f(CW\*(C`$c\->getopt\*(C'\fR, which will change \f(CW$c\fR\->argv instead, see below). Since the command itself won't be in the \f(CW@ARGV\fR parameters, you can use it in each command as if they were stand-alone programs. .PP \fI\f(CI$c\fI\->options\fR .IX Subsection "$c->options" .PP App::Rad lets you automatically retrieve any \s-1POSIX\s0 syntax command line options (\fIgetopt-style\fR) passed to your command via the \f(CW$c\fR\->options method. This method returns a hash reference with keys as given parameters and values as... well... values. The 'options' method automatically supports two simple argument structures: .PP Extended (long) option. Translates \f(CW\*(C`\-\-parameter or \-\-parameter=value\*(C'\fR into \f(CW\*(C`$c\->options\->{parameter}\*(C'\fR. If no value is supplied, it will be set to 1. .PP Single-letter option. Translates \f(CW\*(C`\-p\*(C'\fR into \f(CW\*(C`$c\->options\->{p}\*(C'\fR. .PP Single-letter options can be nested together, so \f(CW\*(C`\-abc\*(C'\fR will be parsed into \f(CW\*(C`$c\->options\->{a}\*(C'\fR, \f(CW\*(C`$c\->options\->{b}\*(C'\fR and \f(CW\*(C`$c\->options{c}\*(C'\fR, while \f(CW\*(C`\-\-abc\*(C'\fR will be parsed into \f(CW\*(C`$c\->options\->{abc}\*(C'\fR. We could, for instance, create a dice-rolling command like this: .PP .Vb 2 \& sub roll { \& my $c = shift; \& \& my $value = 0; \& for ( 1..$c\->options\->{\*(Aqtimes\*(Aq} ) { \& $value += ( int(rand ($c\->options\->{\*(Aqfaces\*(Aq}) + 1)); \& } \& return $value; \& } .Ve .PP And now you can call your 'roll' command like: .PP .Vb 1 \& [user@host]$ ./myapp.pl roll \-\-faces=6 \-\-times=2 .Ve .PP Note that App::Rad does not control which arguments can or cannot be passed: they are all parsed into \f(CW\*(C`$c\->options\*(C'\fR and it's up to you to use whichever you want. For a more advanced use and control, see the \f(CW\*(C`$c\->getopt\*(C'\fR method below. .PP Also note that single-letter options will be set to 1. However, if a user types them more than once, the value will be incremented accordingly. For example, if a user calls your program like so: .PP .Vb 1 \& [user@host]$ ./myapp.pl some_command \-vvv .Ve .PP or .PP .Vb 1 \& [user@host]$ ./myapp.pl some_command \-v \-v \-v .Ve .PP then, in both cases, \f(CW\*(C`$c\->options\->{v}\*(C'\fR will be set to 3. This will let you easily keep track of how many times any given option was chosen, and still let you just check for definedness if you don't care about that. .PP \fI\f(CI$c\fI\->argv\fR .IX Subsection "$c->argv" .PP The array reference \f(CW\*(C`$c\->argv\*(C'\fR contains every argument passed to your command that have \fBnot\fR been parsed into \f(CW\*(C`$c\->options\*(C'\fR. This is usually a list of every provided argument that didn't start with a dash (\-), unless you've called \f(CW\*(C`$c\->getopt\*(C'\fR and used something like 'param=s' (again, see below). .PP \fI\f(CI$c\fI\->getopt (Advanced Getopt usage)\fR .IX Subsection "$c->getopt (Advanced Getopt usage)" .PP App::Rad is also smoothly integrated with Getopt::Long, so you can have even more flexibility and power while parsing your command's arguments, such as aliases and types. Call the \f(CW\*(C`$c\->getopt()\*(C'\fR method anytime inside your commands (or just once in your \*(L"pre_process\*(R" function to always have the same interface) passing a simple array with your options, and refer back to \f(CW$c\fR\->options to see them. For instance: .PP .Vb 2 \& sub roll { \& my $c = shift; \& \& $c\->getopt( \*(Aqfaces|f=i\*(Aq, \*(Aqtimes|t=i\*(Aq ) \& or $c\->execute(\*(Aqusage\*(Aq) and return undef; \& \& # and now you have $c\->options\->{\*(Aqfaces\*(Aq} \& # and $c\->options\->{\*(Aqtimes\*(Aq} just like above. \& } .Ve .PP This becomes very handy for complex or feature-rich commands. Please refer to the Getopt::Long module for more usage examples. .PP \&\fBSo, in order to manipulate and use any arguments, remember:\fR .IP "\(bu" 6 The given command name does not appear in the argument list; .IP "\(bu" 6 All given arguments are in \f(CW@ARGV\fR .IP "\(bu" 6 Automatically processed arguments are in \f(CW\*(C`$c\->options\*(C'\fR .IP "\(bu" 6 Non-processed arguments (the ones \f(CW\*(C`$c\->options\*(C'\fR didn't catch) are in \f(CW$c\fR\->argv .IP "\(bu" 6 You can use \f(CW\*(C`$c\->getopt\*(C'\fR to have \f(CW\*(C`Getopt::Long\*(C'\fR parse your arguments (it will \fBnot\fR change \f(CW@ARGV\fR) .ie n .SS "Sharing Data: ""$c\->stash""" .el .SS "Sharing Data: \f(CW$c\->stash\fP" .IX Subsection "Sharing Data: $c->stash" The \*(L"stash\*(R" is a universal hash for storing data among your Commands: .PP .Vb 3 \& $c\->stash\->{foo} = \*(Aqbar\*(Aq; \& $c\->stash\->{herculoids} = [ qw(igoo tundro zok gloop gleep) ]; \& $c\->stash\->{application} = { name => \*(AqMy Application\*(Aq }; .Ve .PP You can use it for more granularity and control over your program. For instance, you can email the output of a command if (and only if) something happened: .PP .Vb 3 \& sub command { \& my $c = shift; \& my $ret = do_something(); \& \& if ( $ret =~ /critical error/ ) { \& $c\->stash\->{mail} = 1; \& } \& return $ret; \& } \& \& sub post_process { \& my $c = shift; \& \& if ( $c\->stash\->{mail} ) { \& # send email alert... \& } \& else { \& print $c\->output . "\en"; \& } \& } .Ve .SS "Returning output" .IX Subsection "Returning output" Once you're through, return whatever you want to give as output for your command: .PP .Vb 3 \& my $ret = "Here\*(Aqs the list: "; \& $ret .= join \*(Aq, \*(Aq, 1..5; \& return $ret; \& \& # this prints "Here\*(Aqs the list: 1, 2, 3, 4, 5" .Ve .PP App::Rad lets you post-process the returned value of every command, so refrain from printing to \s-1STDOUT\s0 directly whenever possible as it will give much more power to your programs. See the \fI\f(BIpost_process()\fI\fR control function further below in this document. .SH "HELPER METHODS" .IX Header "HELPER METHODS" App::Rad's controller comes with several methods to help you manage your application easily. \fBIf you can think of any other useful command that is not here, please drop me a line or \s-1RT\s0 request\fR. .ie n .SS "$c\->execute( \fI\s-1COMMAND_NAME\s0\fP )" .el .SS "\f(CW$c\fP\->execute( \fI\s-1COMMAND_NAME\s0\fP )" .IX Subsection "$c->execute( COMMAND_NAME )" Runs the given command. If no command is given, runs the one stored in \f(CW\*(C`$c\->cmd\*(C'\fR. If the command does not exist, the 'default' command is ran instead. Each \fI\f(BIexecute()\fI\fR call also invokes pre_process and post_process, so you can easily manipulate income and outcome of every command. .ie n .SS "$c\->cmd" .el .SS "\f(CW$c\fP\->cmd" .IX Subsection "$c->cmd" Returns a string containing the name of the command (that is, the first argument of your program), that will be called right after pre_process. .PP \fI\f(CI$c\fI\->command\fR .IX Subsection "$c->command" .PP Alias for \f(CW\*(C`$c\->cmd\*(C'\fR. This longer form is discouraged and may be removed in future versions, as one may confuse it with the \f(CW\*(C`$c\->commands()\*(C'\fR method, explained below. You have been warned. .ie n .SS "$c\->\fBcommands()\fP" .el .SS "\f(CW$c\fP\->\fBcommands()\fP" .IX Subsection "$c->commands()" Returns a list of available commands (\fIfunctions\fR) inside your program .ie n .SS "$c\->is_command ( \fI\s-1COMMAND_NAME\s0\fP )" .el .SS "\f(CW$c\fP\->is_command ( \fI\s-1COMMAND_NAME\s0\fP )" .IX Subsection "$c->is_command ( COMMAND_NAME )" Returns 1 (true) if the given \fI\s-1COMMAND_NAME\s0\fR is available, 0 (false) otherwise. .ie n .SS "$c\->\fBcreate_command_name()\fP" .el .SS "\f(CW$c\fP\->\fBcreate_command_name()\fP" .IX Subsection "$c->create_command_name()" Returns a valid name for a command (i.e. a name slot that's not been used by your program). This goes in the form of 'cmd1', 'cmd2', etc., so don't use unless you absolutely have to. App::Rad, for instance, uses this whenever you try to \fIinclude\fR (see below) a new command but do not supply a name for it. .ie n .SS "$c\->load_config( \fI\s-1FILE\s0 (\s-1FILE2, FILE3, ...\s0)\fP )" .el .SS "\f(CW$c\fP\->load_config( \fI\s-1FILE\s0 (\s-1FILE2, FILE3, ...\s0)\fP )" .IX Subsection "$c->load_config( FILE (FILE2, FILE3, ...) )" This method lets you easily load into your program one or more configuration files written like this: .PP .Vb 5 \& # comments and blank lines are discarded \& key1 value1 \& key2:value2 \& key3=value3 \& key5 # stand\-alone attribute (and inline\-comment) .Ve .ie n .SS "$c\->config" .el .SS "\f(CW$c\fP\->config" .IX Subsection "$c->config" Returns a hash reference with any loaded config values (see \f(CW\*(C`$c\->load_config()\*(C'\fR above). .ie n .SS "$c\->register ( \fI\s-1NAME\s0\fP, \fI\s-1CODEREF\s0\fP [, \fI\s-1INLINE_HELP\s0\fP ])" .el .SS "\f(CW$c\fP\->register ( \fI\s-1NAME\s0\fP, \fI\s-1CODEREF\s0\fP [, \fI\s-1INLINE_HELP\s0\fP ])" .IX Subsection "$c->register ( NAME, CODEREF [, INLINE_HELP ])" Registers a coderef as a callable command. Note that you don't have to call this in order to register a sub inside your program as a command, \fBrun()\fR will already do this for you \- and if you don't want some subroutines to be issued as commands you can always use \f(CW\*(C`$c\->register_commands()\*(C'\fR (note the plural) inside \fBsetup()\fR. This is just an interface to dinamically include commands in your programs. The function returns the command name in case of success, undef otherwise. .PP It is also very useful for creating aliases for your commands: .PP .Vb 3 \& sub setup { \& my $c = shift; \& $c\->register_commands(); \& \& $c\->register(\*(Aqmyalias\*(Aq, \e&command); \& } \& \& sub command { return "Hi!" } .Ve .PP and, on the command line: .PP .Vb 2 \& [user@host]$ ./myapp.pl command \& Hi! \& \& [user@host]@ ./myapp.pl myalias \& Hi! .Ve .PP The last parameter is optional and lets you add inline help to your command: .PP .Vb 1 \& $c\->register(\*(Aqcmd_name\*(Aq, \e&cmd_func, \*(Aqdisplay secret of life\*(Aq); .Ve .PP \fI\f(CI$c\fI\->register_command ( \fI\s-1NAME\s0\fI, \fI\s-1CODEREF\s0\fI [, \fI\s-1INLINE_HELP\s0\fI ] )\fR .IX Subsection "$c->register_command ( NAME, CODEREF [, INLINE_HELP ] )" .PP Longer alias for \f(CW\*(C`$c\->register()\*(C'\fR. It's use is disencouraged as one may confuse it with \f(CW\*(C`register_commands\*(C'\fR (note the plural) below. Plus you type more :) As such, this method may be removed in future versions. You have been warned! .ie n .SS "$c\->\fBregister_commands()\fP" .el .SS "\f(CW$c\fP\->\fBregister_commands()\fP" .IX Subsection "$c->register_commands()" This method, usually called during \fBsetup()\fR, tells App::Rad to register subroutines as valid commands. If called without any parameters, it will register \fBall\fR subroutines in your main program as valid commands (note that the default behavior of App::Rad is to ignore subroutines starting with an underscore '_'). You can easily change this behavior using some of the options below: .PP \fIAdding single commands\fR .IX Subsection "Adding single commands" .PP .Vb 1 \& $c\->register_commands( qw/foo bar baz/ ); .Ve .PP The code above will register \fBonly\fR the subs \f(CW\*(C`foo\*(C'\fR, \f(CW\*(C`bar\*(C'\fR and \f(CW\*(C`baz\*(C'\fR as commands. Other subroutines will \fBnot\fR be valid commands, so they can be used as internal subs for your program. You can change this behavior with the bundled options \- see 'Adding several commands' and 'Putting it all together' below. .PP \fIAdding single commands (with inline help)\fR .IX Subsection "Adding single commands (with inline help)" .PP .Vb 6 \& $c\->register_commands( \& { \& dos2unix => \*(Aqconvert text files from DOS to Unix format\*(Aq, \& unix2dos => \*(Aqconvert text files from Unix to DOS format\*(Aq, \& } \& ); .Ve .PP You can pass a hash reference containing commands as keys and a small help string as their values. The code above will register \fBonly\fR the subs \f(CW\*(C`dos2unix\*(C'\fR and \f(CW\*(C`unix2dos\*(C'\fR, and the default help for your program will become something like this: .PP .Vb 2 \& [user@host]$ ./myapp.pl \& Usage: myapp.pl command [arguments] \& \& Available Commands: \& dos2unix convert text files from DOS to Unix format \& help show syntax and available commands \& unix2dos convert text files from Unix to DOS format .Ve .PP \fIAdding several commands\fR .IX Subsection "Adding several commands" .PP You can pass a hash reference as an argument, letting you choose which subroutines to add as commands. The following keys may be used (note the dash preceding each key): .IP "\(bu" 4 \&\f(CW\*(C`\-ignore_prefix\*(C'\fR: subroutine names starting with the given string won't be added as commands .IP "\(bu" 4 \&\f(CW\*(C`\-ignore_suffix\*(C'\fR: subroutine names ending with the given string won't be added as commands .IP "\(bu" 4 \&\f(CW\*(C`\-ignore_regexp\*(C'\fR: subroutine names matching the given regular expression (as a string) won't be added as commands .PP For example: .PP .Vb 2 \& use App::Rad; \& App::Rad\->run(); \& \& sub setup { \& my $c = shift; \& $c\->register_commands( { \-ignore_prefix => \*(Aq_\*(Aq } ); \& } \& \& sub foo {} # will become a command \& sub bar {} # will become a command \& sub _baz {} # will *NOT* become a command .Ve .PP This way you can easily segregate between commands and helper functions, making your code even more reusable without jeopardizing the command line interface (As of version 1.04, ignoring commands with underscore '_' prefixes is also the default App::Rad behavior). .PP \fIPutting it all together\fR .IX Subsection "Putting it all together" .PP You can combine some of the options above to have even more flexibility: .PP .Vb 5 \& $c\->register_commands( \& \*(Aqfoo\*(Aq, \& { \-ignore_suffix => \*(Aqfoo\*(Aq }, \& { bar => \*(Aqall your command line are belong to us\*(Aq }, \& ); .Ve .PP The code above will register as commands all subs with names \fBnot\fR ending in 'foo', but it \fBwill\fR register the 'foo' sub as well. It will also give the 'bar' command the help string. This behavior is handy for registering several commands and having a few exceptions, or to add your commands and only have inline help for a few of them (as you see fit). .PP You don't have to worry about the order of your elements passed, App::Rad will figure them out for you in a \s-1DWIM\s0 fashion. .PP .Vb 6 \& # this does the same as the code above \& $c\->register_commands( \& { bar => \*(Aqall your command line are belong to us\*(Aq }, \& \*(Aqfoo\*(Aq, \& { \-ignore_suffix => \*(Aqfoo\*(Aq }, \& ); .Ve .PP You can even bundle the hash reference to include your \f(CW\*(C`cmd => help\*(C'\fR and special keys: .PP .Vb 8 \& # this behaves the same way as the code above: \& $c\->register_commands( \& \*(Aqfoo\*(Aq, \& { \& \-ignore_suffix => \*(Aqfoo\*(Aq, \& bar => \*(Aqall your command line are belong to us\*(Aq, \& } \& ); .Ve .ie n .SS "$c\->unregister_command ( \fI\s-1NAME\s0\fP )" .el .SS "\f(CW$c\fP\->unregister_command ( \fI\s-1NAME\s0\fP )" .IX Subsection "$c->unregister_command ( NAME )" Longer alias for \f(CW\*(C`$c\->unregister()\*(C'\fR. The use of the shorter form is encouraged, and this alias may be removed in future versions. You have been warned. .PP \fI\f(CI$c\fI\->unregister ( \fI\s-1NAME\s0\fI )\fR .IX Subsection "$c->unregister ( NAME )" .PP Unregisters a given command name so it's not available anymore. Note that the subroutine will still be there to be called from inside your program \- it just won't be accessible via command line anymore. .ie n .SS "$c\->debug( \fI\s-1MESSAGE\s0\fP )" .el .SS "\f(CW$c\fP\->debug( \fI\s-1MESSAGE\s0\fP )" .IX Subsection "$c->debug( MESSAGE )" Will print the given message on screen only if the debug flag is enabled: .PP .Vb 1 \& use App::Rad qw( debug ); .Ve .PP Note that, if debug is enabled, App::Rad itself will print several debug messages stating its current flow, so you can easily find out where everything is happening. .ie n .SS "$c\->\fBplugins()\fP" .el .SS "\f(CW$c\fP\->\fBplugins()\fP" .IX Subsection "$c->plugins()" Returns a list of all loaded plugins, in the order in which they were loaded. .ie n .SS "$c\->load_plugin( \fI\s-1PLUGIN NAME\s0\fP )" .el .SS "\f(CW$c\fP\->load_plugin( \fI\s-1PLUGIN NAME\s0\fP )" .IX Subsection "$c->load_plugin( PLUGIN NAME )" This method will dinamically load the given plugin. The plugin needs to be under the \f(CW\*(C`App::Rad::Plugin\*(C'\fR namespace, and the name should be relative to this path (i.e. \f(CW$c\fR\->load_plugin('MyPlugin') will try to load 'App::Rad::Plugin::MyPlugin'). If you want to load a plugin by its fully qualified name, you need to prepend a plus sign to the name ('+Fully::Qualified::Plugin::Name'). \fBThis is an internal method\fR and you really should refrain from using it. Instead, plugins should be loaded as parameters to the \f(CW\*(C`use App::Rad\*(C'\fR statement, as explained above. .SH "CONTROL FUNCTIONS (to possibly override)" .IX Header "CONTROL FUNCTIONS (to possibly override)" App::Rad implements some control functions which are expected to be overridden by implementing them in your program. They are as follows: .SS "\fBsetup()\fP" .IX Subsection "setup()" This function is responsible for setting up what your program can and cannot do, plus everything you need to set before actually running any command (connecting to a database or host, check and validate things, download a document, whatever). Note that, if you override \fBsetup()\fR, you \fB*must*\fR call \f(CW\*(C`$c\->register_commands()\*(C'\fR or at least \f(CW\*(C`$c\->register()\*(C'\fR so your subs are classified as valid commands (check \f(CW$c\fR\->\fBregister_commands()\fR above for more information). .PP Another interesting thing you can do with setup is to manipulate the command list. For instance, you may want to be able to use the \f(CW\*(C`include\*(C'\fR and \f(CW\*(C`exclude\*(C'\fR commands, but not let them available for all users. So instead of writing: .PP .Vb 2 \& use App::Rad qw(include exclude); \& App::Rad\->run(); .Ve .PP you can write something like this: .PP .Vb 2 \& use App::Rad; \& App::Rad\->run(); \& \& sub setup { \& my $c = shift; \& $c\->register_commands(); \& \& # EUID is \*(Aqroot\*(Aq \& if ( $> == 0 ) { \& $c\->register(\*(Aqinclude\*(Aq, \e&App::Rad::include); \& $c\->register(\*(Aqexclude\*(Aq, \e&App::Rad::exclude); \& } \& } .Ve .PP to get something like this: .PP .Vb 2 \& [user@host]$ myapp.pl help \& Usage: myapp.pl command [arguments] \& \& Available Commands: \& help \& \& [user@host]$ sudo myapp.pl help \& Usage: myapp.pl command [arguments] \& \& Available Commands: \& exclude \& help \& include .Ve .SS "\fBdefault()\fP" .IX Subsection "default()" If no command is given to your application, it will fall in here. Please note that invalid (non-existant) command will fall here too, but you can change this behavior with the \fBinvalid()\fR function below (although usually you don't want to). .PP Default's default (grin) is just an alias for the help command. .PP .Vb 2 \& sub default { \& my $c = shift; \& \& # will fall here if the given \& # command isn\*(Aqt valid. \& } .Ve .PP You are free (and encouraged) to change the default behavior to whatever you want. This is rather useful for when your program will only do one thing, and as such it receives only parameters instead of command names. In those cases, use the "\f(CW\*(C`default()\*(C'\fR" sub as your main program's sub and parse the parameters with \f(CW\*(C`$c\->argv\*(C'\fR and \f(CW\*(C`$c\->getopt\*(C'\fR as you would in any other command. .SS "\fBinvalid()\fP" .IX Subsection "invalid()" This is a special function to provide even more flexibility while creating your command line applications. This is called when the user requests a command that does not exist. The built-in \f(CW\*(C`invalid()\*(C'\fR will simply redirect itself to \f(CW\*(C`default()\*(C'\fR (see above), so usually you just have to worry about this when you want to differentiate between \*(L"no command given\*(R" (with or without getopt-like arguments) and \*(L"invalid command given\*(R" (with or without getopt-like arguments). .SS "\fBteardown()\fP" .IX Subsection "teardown()" If implemented, this function is called automatically after your application runs. It can be used to clean up after your operations, removing temporary files, disconnecting a database connection established in the setup function, logging, sending data over a network, or even storing state information via Storable or whatever. .SS "\fBpre_process()\fP" .IX Subsection "pre_process()" If implemented, this function is called automatically right before the actual wanted command is called. This way you have an optional pre-run hook, which permits functionality to be added, such as preventing some commands to be run from a specific uid (e.g. \fIroot\fR): .PP .Vb 2 \& sub pre_process { \& my $c = shift; \& \& if ( $c\->cmd eq \*(Aqsome_command\*(Aq and $> != 0 ) { \& $c\->cmd = \*(Aqdefault\*(Aq; # or some standard error message \& } \& } .Ve .SS "\fBpost_process()\fP" .IX Subsection "post_process()" If implemented, this function is called automatically right after the requested function returned. It receives the Controller object right after a given command has been executed (and hopefully with some output returned), so you can manipulate it at will. In fact, the default \*(L"post_process\*(R" function is as goes: .PP .Vb 2 \& sub post_process { \& my $c = shift; \& \& if ( $c\->output() ) { \& print $c\->output() . "\en"; \& } \& } .Ve .PP You can override this function to include a default header/footer for your programs (either a label or perhaps a \*(L"Content-type: \*(R" string), parse the output in any ways you see fit (\s-1CPAN\s0 is your friend, as usual), etc. .SH "IMPORTANT NOTE ON PRINTING INSIDE YOUR COMMANDS" .IX Header "IMPORTANT NOTE ON PRINTING INSIDE YOUR COMMANDS" \&\fBThe \fBpost_process()\fB function above is why your application should *NEVER* print to \s-1STDOUT\s0\fR. Using \fIprint\fR (or \fIsay\fR, in 5.10) to send output to \s-1STDOUT\s0 is exclusively the domain of the \fBpost_process()\fR function. Breaking this rule is a common source of errors. If you want your functions to be interactive (for instance) and print everything themselves, you should disable post-processing in \fBsetup()\fR, or create an empty post_process function or make your functions return \fIundef\fR (so \fI\f(BIpost_process()\fI\fR will only add a blank line to the output). .SH "DIAGNOSTICS" .IX Header "DIAGNOSTICS" If you see a '1' printed on the screen after a command is issued, it's probably because that command is returning a \*(L"true\*(R" value instead of an output string. If you don't want to return the command output for post processing(you'll loose some nice features, though) you can return undef or make \fBpost_process()\fR empty. .SH "CONFIGURATION AND ENVIRONMENT" .IX Header "CONFIGURATION AND ENVIRONMENT" App::Rad requires no configuration files or environment variables. .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" App::Rad depends only on 5.8 core modules (Carp for errors, Getopt::Long for \*(L"$c\->getopt\*(R", Attribute::Handlers for \*(L"help\*(R" and O/B::Deparse for the \*(L"include\*(R" command). .PP If you have Perl::Tidy installed, the \*(L"include\*(R" command will tidy up your code before inclusion. .PP The test suite depends on Test::More, FindBin and File::Temp, also core modules. .SH "INCOMPATIBILITIES" .IX Header "INCOMPATIBILITIES" None reported. .SH "BUGS AND LIMITATIONS" .IX Header "BUGS AND LIMITATIONS" Please report any bugs or feature requests to \&\f(CW\*(C`bug\-app\-easy at rt.cpan.org\*(C'\fR, or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. .SH "SUPPORT" .IX Header "SUPPORT" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc App::Rad .Ve .PP Although this Module comes without any warraties whatsoever (see \s-1DISCLAIMER\s0 below), I try really hard to provide some quality assurance for the users. This means I not only try to close all reported bugs in the minimum amount of time but I also try to find some on my own. .PP This version of App::Rad comes with 183 tests and I keep my eye constantly on \s-1CPAN\s0 Testers to ensure it passes all of them, in all platforms. You can send me your own App::Rad tests if you feel I'm missing something and I'll hapilly add them to the distribution. .PP Since I take user's feedback very seriously, I really hope you send me any wishlist/TODO you'd like App::Rad to have (please try to send them via \s-1RT\s0 so other people can give their own suggestions). .PP You can also look for information at: .IP "\(bu" 4 \&\s-1RT: CPAN\s0's request tracker .Sp .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 Search \s-1CPAN\s0 .Sp .SS "\s-1IRC\s0" .IX Subsection "IRC" .Vb 1 \& #app\-rad on irc.perl.org .Ve .SH "TODO" .IX Header "TODO" This is a small list of features I plan to add in the near future (in no particular order). Feel free to contribute with your wishlist and comentaries! .IP "\(bu" 4 Shell-like environment .IP "\(bu" 4 Loadable commands (in an external container file) .IP "\(bu" 4 Modularized commands (similar to App::Cmd::Commands ?) .IP "\(bu" 4 app-starter .IP "\(bu" 4 command inclusion by prefix, suffix and regexp (feature request by fco) .IP "\(bu" 4 command inclusion and exclusion also by attributes .IP "\(bu" 4 some extra integration, maybe IPC::Cmd and IO::Prompt .SH "AUTHOR" .IX Header "AUTHOR" Breno G. de Oliveira, \f(CW\*(C`\*(C'\fR .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" (in alphabetical order) .PP Ben Hengst .PP Fernando Correa .PP Flavio Glock .PP Thanks to everyone for contributing! Please let me know if I've skipped your name by accident. .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" This module was inspired by Kenichi Ishigaki's presentation \fI\*(L"Web is not the only one that requires frameworks\*(R"\fR during YAPC::Asia::2008 and the modules it exposed (mainly App::Cmd and App::CLI). .PP Also, many thanks to CGI::App(now Titanium)'s Mark Stosberg and all the Catalyst developers, as some of App::Rad's functionality was taken from those (web) frameworks. .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright 2008 Breno G. de Oliveira \f(CW\*(C`\*(C'\fR. All rights reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic. .SH "DISCLAIMER OF WARRANTY" .IX Header "DISCLAIMER OF WARRANTY" \&\s-1BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE \*(L"AS IS\*(R" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.\s0 .PP \&\s-1IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE\s0 (\s-1INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE\s0), \s-1EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.\s0