NAME
Perinci::CmdLine - Rinci/Riap-based command-line application framework
VERSION
This document describes version 1.24 of Perinci::CmdLine (from Perl
distribution Perinci-CmdLine), released on 2014-08-27.
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.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/perlancar/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
perlancar <perlancar@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2014 by perlancar@cpan.org.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.