NAME Perinci::CmdLine::Base - Base class for Perinci::CmdLine{,::Lite} VERSION This document describes version 0.02 of Perinci::CmdLine::Base (from Perl distribution Perinci-CmdLine-Base), released on 2014-07-17. REQUEST KEYS The various values in the $r hash/stash. * action => str Selected action to use. Usually set from the common options. * format => str Selected format to use. Usually set from the common option "--format". * parse_argv_res => array Enveloped result of "parse_argv()". * skip_parse_subcommand_argv => bool Checked by "parse_argv()". Can be set to 1, e.g. in common option handler for "--help" or "--version" to skip parsing @ARGV for per-subcommand options. * args => hash Also taken from "parse_arg()" result. * meta => hash Result of "get_meta()". * dry_run => bool Whether to pass "-dry_run" special argument to function. * res => array Enveloped result of "action_ACTION()". * fres => str Result from "hook_format_result()". ATTRIBUTES actions => array Contains a list of known actions and their metadata. Keys should be action names, values should be metadata. Metadata is a hash containing these keys: * default_log => BOOL (optional) Whether to enable logging by default (Log::Any::App) when "LOG" environment variable is not set. To speed up program startup, logging is by default turned off for simple actions like "help", "list", "version". * use_utf8 => BOOL (optional) Whether to issue "binmode(STDOUT, ":utf8")". See "UTF8 OUTPUT" for more details. common_opts => hash A hash of common options, which are command-line options that are not associated with any subcommand. Each option is itself a specification hash containing these keys: * category (str) Optional, for grouping options in help/usage message, defaults to "Common options". * getopt (str) Required, for Getopt::Long specification. * handler (code) Required, for Getopt::Long specification. * usage (str) Optional, displayed in usage line in help/usage text. * summary (str) Optional, displayed in description of the option in help/usage text. * show_in_usage (bool or code, default: 1) A flag, can be set to 0 if we want to skip showing this option in usage in --help, to save some space. The default is to show all, except --subcommand when we are executing a subcommand (obviously). * show_in_options (bool or code, default: 1) A flag, can be set to 0 if we want to skip showing this option in options in --help. The default is to 0 for --help and --version in compact help. Or --subcommands, if we are executing a subcommand (obviously). * order (int) Optional, for ordering. Lower number means higher precedence, defaults to 1. A partial example from the default set by the framework: { help => { category => 'Common options', getopt => 'help|h|?', usage => '--help (or -h, -?)', handler => sub { ... }, order => 0, show_in_options => sub { $ENV{VERBOSE} }, }, format => { category => 'Common options', getopt => 'format=s', summary => 'Choose output format, e.g. json, text', handler => sub { ... }, }, undo => { category => 'Undo options', getopt => 'undo', ... }, ... } The default contains: help (getopt "help|h|?"), version (getopt "version|v"), action (getopt "action"), format (getopt "format=s"), format_options (getopt "format-options=s"), json*, yaml*, perl*. If there are more than one subcommands, this will also be added: list (getopt "list|l"). If dry-run is supported by function, there will also be: dry_run (getopt "dry-run"). If undo is turned on, there will also be: undo (getopt "undo"), redo (getopt "redo"), history (getopt "history"), clear_history (getopt "clear-history"). *) Currently only added if you say "use Perinci::CmdLine 1.04". Sometimes you do not want some options, e.g. to remove "format" and "format_options": delete $cmd->common_opts->{format}; delete $cmd->common_opts->{format_options}; $cmd->run; Sometimes you want to rename some command-line options, e.g. to change version to use capital "-V" instead of "-v": $cmd->common_opts->{version}{getopt} = 'version|V'; Sometimes you want to add subcommands as common options instead. For example: $cmd->common_opts->{halt} = { category => 'Server options', getopt => 'halt', summary => 'Halt the server', handler => sub { $cmd->{_subcommand_name} = 'shutdown'; }, }; This will make: % cmd --halt equivalent to executing the 'shutdown' subcommand: % cmd shutdown custom_arg_completer => code | hash => {of=>code} Will be passed to Perinci::Sub::Complete's "complete_cli_arg()". See its documentation for more details. custom_completer => code Will be passed to Perinci::Sub::Complete's "complete_cli_arg()". See its documentation for more details. default_subcommand => str Set subcommand to this if user does not specify which to use (either via first command-line argument or "--cmd" option). See also: "get_subcommand_from_arg". get_subcommand_from_arg => int (default: 1) The default is 1, which is to get subcommand from the first command-line argument except when there is "default_subcommand" defined. Other valid values are: 0 (not getting from first command-line argument), 2 (get from first command-line argument even though there is "default_subcommand" defined). description => str exit => bool (default: 1) formats => array Available output formats. pass_cmdline_object => bool (default: 0) Whether to pass special argument "-cmdline" containing the cmdline object to function. This can be overriden using the "pass_cmdline_object" on a per-subcommand basis. Passing the cmdline object can be useful, e.g. to call run_help(), etc. program_name => str Default is from PERINCI_CMDLINE_PROGRAM_NAME environment or from $0. subcommands => hash | code subcommands => {NAME => {ARGUMENT=>...}, ...} | CODEREF Should be a hash of subcommand specifications or a coderef. Each subcommand specification is also a hash(ref) and should contain these keys: * "url" (str, required) Location of function (accessed via Riap). * "summary" (str, optional) Will be retrieved from function metadata at "url" if unset * "description" (str, optional) Shown in verbose help message, if description from function metadata is unset. * "tags" (array of str, optional) For grouping or categorizing subcommands, e.g. when displaying list of subcommands. * "log_any_app" (bool, optional) Whether to load Log::Any::App, default is true. For subcommands that need fast startup you can try turning this off for said subcommands. See "LOGGING" for more details. * "use_utf8" (bool, optional) Whether to issue "binmode(STDOUT, ":utf8")". See "LOGGING" for more details. * "undo" (bool, optional) Can be set to 0 to disable transaction for this subcommand; this is only relevant when "undo" attribute is set to true. * "show_in_help" (bool, optional, default 1) If you have lots of subcommands, and want to show only some of them in --help message, set this to 0 for subcommands that you do not want to show. * "pass_cmdline_object" (bool, optional, default 0) To override "pass_cmdline_object" attribute on a per-subcommand basis. * "args" (hash, optional) If specified, will send the arguments (as well as arguments specified via the command-line). This can be useful for a function that serves more than one subcommand, e.g.: subcommands => { sub1 => { summary => 'Subcommand one', url => '/some/func', args => {flag=>'one'}, }, sub2 => { summary => 'Subcommand two', url => '/some/func', args => {flag=>'two'}, }, } In the example above, both subcommand "sub1" and "sub2" point to function at "/some/func". But the function can differentiate between the two via the "flag" argument being sent. % cmdprog sub1 --foo 1 --bar 2 % cmdprog sub2 --foo 2 In the first invocation, function will receive arguments "{foo=>1, bar=>2, flag=>'one'}" and for the second: "{foo=>2, flag=>'two'}". Subcommands can also be a coderef, for dynamic list of subcommands. The coderef will be called as a method with hash arguments. It can be called in two cases. First, if called without argument "name" (usually when doing --subcommands) it must return a hashref of subcommand specifications. If called with argument "name" it must return subcommand specification for subcommand with the requested name only. summary => str tags => array of str url => str Required if you only want to run one function. URL should point to a function entity. Alternatively you can provide multiple functions from which the user can select using the first argument (see subcommands). METHODS $cmd->run() => ENVRES Will parse command-line arguments with "parse_argv()", select/set subcommand, call hooks, run the appropriate "run_ACTION()" method, and finally format and display the result. The "run_ACTION()" methods will be passed $r and is supposed to return an enveloped result. The result will then be put in "$r-"{res}>. If "exit" attribute is true, will exit with the action's envelope result status. If status is 200, exit code is 0. Otherwise exit code is status minus 300. So, a response "[501, "Not implemented"]" will result in exit code of 201. If "exit" attribute is false, will simply return the action result ("$r-"{res}>). $cmd->do_completion() => ENVRES Called by run(). $cmd->parse_argv() => ENVRES Called by run(). $cmd->get_meta($url) => ENVRES Called by parse_argv() or do_completion(). Subclass has to implement this. HOOKS All hooks will receive the argument $r, a per-request hash/stash. The list below is by order of calling. $cmd->hook_before_run($r) Called at the start of "run()". Can be used to set some initial values of other $r keys. Or setup the logger. $cmd->hook_after_parse_argv($r) Called after "run()" calls "parse_argv()" and before it checks the result. "$r-"{parse_argv_res}> will contain the result of "parse_argv()". The hook gets a chance to, e.g. fill missing arguments from other source. $cmd->hook_format_result($r) The hook is supposed to format result in "$res-"{res}> (an array). $cmd->hook_display_result($r) The hook is supposed to display the formatted result (stored in "$r-"{fres}>) to STDOUT. But in the case of streaming output, this hook can also set it up. $cmd->hook_after_run($r) Called at the end of "run()", right before it exits (if "exit" attribute is true) or returns "$r-"{res}>. The hook has a chance to modify exit code or result. METADATA PROPERTY ATTRIBUTE This module observes the following Rinci metadata property attributes: x.perinci.cmdline.default_format => STR Set default output format (if user does not specify via --format command-line option). RESULT_METADATA This module interprets the following result metadata property/attribute: attribute: cmdline.exit_code => INT Instruct Perinci::CmdLine to use this exit code, instead of using (function status - 300). ENVIRONMENT * PERINCI_CMDLINE_PROGRAM_NAME => STR Can be used to set CLI program name. HOMEPAGE Please visit the project's homepage at . SOURCE Source repository is at . BUGS Please report any bugs or feature requests on the bugtracker website When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. AUTHOR Steven Haryanto COPYRIGHT AND LICENSE This software is copyright (c) 2014 by Steven Haryanto. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.