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
    <https://metacpan.org/release/Perinci-CmdLine-Base>.

SOURCE
    Source repository is at
    <https://github.com/sharyanto/perl-Perinci-CmdLine-Base>.

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=Perinci-CmdLine-Base>

    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 <stevenharyanto@gmail.com>

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.

