NAME

Perinci::CmdLine - Rinci/Riap-based command-line application framework

VERSION

This document describes version 1.17 of Perinci::CmdLine (from Perl distribution Perinci-CmdLine), released on 2014-08-22.

SYNOPSIS

See Perinci::CmdLine::Manual::Examples.

DESCRIPTION

See Perinci::CmdLine::Manual.

REQUEST KEYS

See also Perinci::CmdLine::Base. Extra stuffs put by this module to the $r hash/stash.

• format_options => hash

ATTRIBUTES

All the attributes of Perinci::CmdLine::Base, plus:

log_any_app => BOOL (default: 1)

Whether to load Log::Any::App (enable logging output) by default. See "LOGGING" for more details.

use_utf8 => BOOL

From SHARYANTO::Role::TermAttrs (please see its docs for more details). There are several other attributes added by the role.

undo => BOOL (optional, default 0)

Whether to enable undo/redo functionality. Some things to note if you intend to use undo:

• These common command-line options will be recognized

  --undo, --redo, --history, --clear-history.

• Transactions will be used

  use_tx=>1 will be passed to Perinci::Access, which will cause it to initialize the transaction manager. Riap requests begin_tx and commit_tx will enclose the call request to function.

• Called function will need to support transaction and undo

  Function which does not meet qualifications will refuse to be called.

  Exception is when subcommand is specified with undo=>0, where transaction will not be used for that subcommand. For an example of disabling transaction for some subcommands, see bin/u-trash in the distribution.

undo_dir => STR (optional, default ~/.<program_name>/.undo)

Where to put undo data. This is actually the transaction manager's data dir.

METHODS

All the methods of Perinci::CmdLine::Base, plus:

RESULT METADATA

All those supported by Perinci::CmdLine::Base, plus:

property: is_stream => BOOL

XXX should perhaps be defined as standard in Rinci::function.

If set to 1, signify that result is a stream. Result must be a glob, or an object that responds to getline() and eof() (like a Perl IO::Handle object), or an array/tied array. Format must currently be text (streaming YAML might be supported in the future). Items of result will be displayed to output as soon as it is retrieved, and unlike non-streams, it can be infinite.

An example function:

 $SPEC{cat_file} = { ... };
 sub cat_file {
     my %args = @_;
     open my($fh), "<", $args{path} or return [500, "Can't open file: $!"];
     [200, "OK", $fh, {is_stream=>1}];
 }

another example:

 use Tie::Simple;
 $SPEC{uc_file} = { ... };
 sub uc_file {
     my %args = @_;
     open my($fh), "<", $args{path} or return [500, "Can't open file: $!"];
     my @ary;
     tie @ary, "Tie::Simple", undef,
         SHIFT     => sub { eof($fh) ? undef : uc(~~<$fh> // "") },
         FETCHSIZE => sub { eof($fh) ? 0 : 1 };
     [200, "OK", \@ary, {is_stream=>1}];
 }

See also Data::Unixish and App::dux which deals with streams.

attribute: cmdline.display_result => BOOL

If you don't want to display function output (for example, function output is a detailed data structure which might not be important for end users), you can set cmdline.display_result result metadata to false. Example:

 $SPEC{foo} = { ... };
 sub foo {
     ...
     [200, "OK", $data, {"cmdline.display_result"=>0}];
 }

attribute: cmdline.page_result => BOOL

If you want to filter the result through pager (currently defaults to $ENV{PAGER} or less -FRSX), you can set cmdline.page_result in result metadata to true.

For example:

 $SPEC{doc} = { ... };
 sub doc {
     ...
     [200, "OK", $doc, {"cmdline.page_result"=>1}];
 }

attribute: cmdline.pager => STR

Instruct Perinci::CmdLine to use specified pager instead of $ENV{PAGER} or the default less or more.

ENVIRONMENT

All the environment variables that Perinci::CmdLine::Base supports, plus:

PERINCI_CMDLINE_COLOR_THEME => STR

Can be used to set color_theme.

PROGRESS => BOOL

Explicitly turn the progress bar on/off.

PAGER => STR

Like in other programs, can be set to select the pager program (when cmdline.page_result result metadata is active). Can also be set to '' or 0 to explicitly disable paging even though cmd.page_result result metadata is active.

COLOR => INT

Please see SHARYANTO::Role::TermAttrs.

UTF8 => BOOL

Please see SHARYANTO::Role::TermAttrs.

SEE ALSO

Perinci, Rinci, Riap.

Perinci::CmdLine::Base.

Perinci::CmdLine::Lite.

Other CPAN modules to write command-line applications: App::Cmd, App::Rad, MooseX::Getopt.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Perinci-CmdLine.

SOURCE

Source repository is at https://github.com/sharyanto/perl-Perinci-CmdLine.

BUGS

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

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.

cpanm Perinci::CmdLine

perl -MCPAN -e shell
install Perinci::CmdLine