view release on metacpan or  search on metacpan

lib/Perinci/CmdLine/Manual/FAQ.pod  view on Meta::CPAN

So which one should you choose? PC:Lite is the sane default choice, unless you
need features that are currently not supported by PC:Lite, in which case you can
consider using PC:Classic. If you really need fast startup, you can opt for
PC:Inline. But note that when the backend function's Rinci metadata changes, you
will need to rebuild the script because the metadata is embedded in the script
(while in PC:Lite and PC:Classic, the script simply request the Rinci metadata
during runtime).

=head2 What Classic features are currently still missing in Lite?

=over

=item * More sophisticated formatting

Instead of L<Perinci::Result::Format> (especially for 'text*' formats which use
L<Data::Format::Pretty::Console> and L<Text::ANSITable>), to keep dependencies
minimal and formatting quick, PC::Lite uses the following simple rules that work
for a significant portion of common data structures:

1) if result is undef, print nothing.

2) if result is scalar, print it (with newline automatically added).

3) if result is an array of scalars (check at most 5 first rows), print it one
line for each element.

4) if result is a hash of scalars (check at most 5 keys), print a two column
table, first column is key and second column is value. Keys will be sorted.

5) if result is an array of hashes of scalars (check at most 5 elements), print
as table.

6) if result is an array of arrays of scalars (check at most 5 elements), print
as table.

7) otherwise print as JSON (after cleaning it with L<Data::Clean::JSON>).

YAML and the other formats are not supported.

Table is printed using the more lightweight and much faster
L<Text::Table::Tiny>.

PC::Classic supports more sophisticated formatting, can keep colored and
full-width Unicode characters stay aligned in a table.

=item * Support for extra protocols

Instead of L<Perinci::Access>, PC::Lite uses the more lightweight alternative
L<Perinci::Access::Lite> which does not support some URL schemes (riap+tcp,
riap+unix, riap+pipe). http/https and local are supported though.

=item * Extra stuffs that Perinci::Sub::Wrapper adds

PC::Classic uses function wrapper to automatically adds argument validation,
dependency checking, and so on. However, this adds too much overhead so PC:Lite
avoids it and do some of the stuffs by itself to avoid the overhead.

PC:Lite does argument validation, as well as dependency checking. But there are
other stuffs that Perinci::Sub::Wrapper adds that are not available, including:
result validation, validation of input stream (streaming argument) as well as
output stream (streaming result).

=item * Color themes

=item * Undo

=item * I18N

=item * The following environment variables

 PERINCI_CMDLINE_COLOR_THEME
 PERINCI_CMDLINE_SERVER
 COLOR
 UTF8

=back

=head2 What is Perinci::CmdLine::Any then?

This is a module that allows you to select PC::Classic or PC::Lite. So your
scripts do not need to be modified when user wants to switch between the two.

=head2 How does Perinci::CmdLine compare with other CLI-app frameworks?

The main difference is that Perinci::CmdLine accesses your code through L<Riap>
protocol, not directly. This means that aside from local Perl code,
Perinci::CmdLine can also provide CLI for code in remote hosts/languages. For a
very rough demo, download and run this PHP Riap::TCP server
https://github.com/sharyanto/php-Phinci/blob/master/demo/phi-tcpserve-terbilang.php
on your system. After that, try running:

 % peri-run riap+tcp://localhost:9090/terbilang --help
 % peri-run riap+tcp://localhost:9090/terbilang 1234

Everything from help message, calling, argument checking, tab completion works
for remote code as well as local Perl code.

=head2 But my application is OO? But I want an OO framework?

This framework is currently function-centric. There are already several OO-based
command-line frameworks on CPAN.

=head1 GENERATING DOCUMENTATION

=head2 How do I add examples using Rinci metadata?

In your Rinci function metadata, add the C<examples> property, e.g.:

 # myapp script
 use Perinci::CmdLine::Any;
 our %SPEC;
 $SPEC{myadd} = {
     v => 1.1,
     args => {
         num1 => {summary=>'First number' , schema='float*', req=>1, pos=>0},
         num2 => {summary=>'Second number', schema='float*', req=>1, pos=>1},
         round => {
             summary=>'Round to nearest integer',
             schema =>'bool*',
             cmdline_aliases=>{r=>{}},
         },