NAME Perinci::CmdLine - Rinci/Riap-based command-line application framework VERSION version 0.38 SYNOPSIS In your command-line script: #!/usr/bin/perl use Perinci::CmdLine; Perinci::CmdLine->new(url => 'Your::Module', ...)->run; See also the peri-run script which provides a command-line interface for Perinci::CmdLine. DESCRIPTION Perinci::CmdLine is a command-line application framework. It access functions using Riap protocol (Perinci::Access) so you get transparent remote access. It utilizes Rinci metadata in the code so the amount of plumbing that you have to do is quite minimal. What you'll get: * Command-line parsing (currently using Getopt::Long, with some tweaks) * Help message (utilizing information from metadata) * Tab completion for bash (including completion from remote code) This module uses Log::Any and Log::Any::App for logging. This module uses Moo for OO. ATTRIBUTES program_name => STR (default from $0) 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). summary => STR If unset, will be retrieved from function metadata when needed. 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". It can also contain these keys: "summary" (will be retrieved from function metadata if unset), "tags" (for categorizing subcommands). 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 --list) 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. exit => BOOL (default 1) If set to 0, instead of exiting with exit(), run() will return the exit code instead. custom_completer => CODEREF Will be passed to Perinci::BashComplete's "bash_complete_riap_func_arg". See its documentation for more details. custom_arg_completer => CODEREF | {ARGNAME=>CODEREF, ...} Will be passed to Perinci::BashComplete. See its documentation for more details. dash_to_underscore => BOOL (optional, default 1) If set to 1, subcommand like a-b-c will be converted to a_b_c. This is for convenience when typing in command line. undo => BOOL (optional, default 0) UNFINISHED. If set to 1, --undo and --undo-dir will be added to command-line options. --undo is used to perform undo: -undo and -undo_data will be passed to subroutine, an error will be thrown if subroutine does not have "undo" features. --undo-dir is used to set location of undo data (default "~/.undo"; undo directory will be created if not exists; each subroutine will have its own subdir here). METHODS new(%opts) => OBJ Create an instance. run() -> INT The main routine. Its job is to parse command-line options in @ARGV and determine which action method to run. Action is run_command() (for calling function) or one of actions for common options like run_help (--help), run_list (--list). After that exit with appropriate exit code. (If "exit" attribute is set to false, will return with exit code instead of directly calling exit().) run_command() -> INT Called by run() after run() decides that a command should be run. Requires $self->{_subcommand} to be set by run(). Call function specified in command and exit with appropriate exit code (0 if envelope status code is 200, or code-300). FAQ How does Perinci::CmdLine compare with other CLI-app frameworks? Perinci::CmdLine is part of a more general metadata and wrapping framework (Perinci::* modules family). Aside from a command-line application, your metadata is also usable for other purposes, like providing access over HTTP/TCP, documentation. Sub::Spec::CmdLine is not OO. Configuration file support is missing (coming soon, most probably based on Config::Ini::OnDrugs). Also lacking is more documentation and more plugins. Why is nonscalar arguments parsed as YAML instead of JSON/etc? I think YAML is nicer in command-line because quotes are optional in a few places: $ cmd --array '[a, b, c]' --hash '{foo: bar}' versus: $ cmd --array '["a","b","c"]' --hash '{"foo":"bar"}' Though YAML requires spaces in some places where JSON does not. A flag to parse as JSON can be added upon request. SEE ALSO Perinci, Rinci, Riap. Other CPAN modules to write command-line applications: App::Cmd, App::Rad, MooseX::Getopt. AUTHOR Steven Haryanto COPYRIGHT AND LICENSE This software is copyright (c) 2012 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.