NAME
Perinci::CmdLine::Manual::FAQ - FAQs
VERSION
This document describes version 1.02 of Perinci::CmdLine::Manual::FAQ (from Perl distribution Perinci-CmdLine-Lite), released on 2015-03-30.
NOMENCLATURE
[PC::Classic] denotes that the answer applies to Perinci::CmdLine::Classic only and not Perinci::CmdLine::Lite. [PC::Lite] denotes that the answer is specific to Perinci::CmdLine::Lite. [PC::Any] denotes that the answer is specific to Perinci::CmdLine::Any.
GENERAL
Why are there two frameworks Perinci::CmdLine::Classic and Perinci::CmdLine::Lite?
There used to be a single flavor Perinci::CmdLine. As it grows in features, the startup overhead also grows. So another project is started, Perinci::CmdLine::Lite (hereby called PC::Lite) that focuses on keeping startup overhead low to avoid making tab completion noticeably slow. It also tries to reduce the number of dependencies. Later, the original Perinci::CmdLine is renamed to Perinci::CmdLine::Classic (hereby called PC::Classic). However, some PC::Classic features are still missing in PC::Lite.
PC::Lite stays lightweight by avoiding the use of libraries that have large dependencies or add too much to startup overhead. This includes replacing Perinci::Access with Perinci::Access::Lite for metadata access, currently not using Data::Sah for validator generation, avoiding Text::ANSITable for formatting results, and replacing Log::Any::App (which uses the relatively heavy Log::Log4perl) with Log::Any::Adapter::ScreenColoredLevel for logging.
PC::Lite tries to start under 0.04-0.05s to make shell tab completion convenient. On the other hand, PC::Classic application can spend between 0.20-0.50s before displaying output, due to various abovementioned overheads: loading more libraries, validator code generation, etc.
Implementation-wise, the two share a lot of common code in the form of their base class, Perinci::CmdLine::Base. The interface is also 99% the same.
It is possible that in the future the two versions will merge again.
What Classic features are currently still missing in Lite?
More sophisticated formatting
Instead of Perinci::Result::Format (especially for 'text*' formats which use Data::Format::Pretty::Console and 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 Data::Clean::JSON).
YAML and the other formats are not supported.
Table is printed using the more lightweight and much faster Text::Table::Tiny.
PC::Classic supports more sophisticated formatting, can keep colored and full-width Unicode characters stay aligned in a table.
Support for extra protocols
Instead of Perinci::Access, PC::Lite uses the more lightweight alternative Perinci::Access::Lite which does not support some URL schemes (riap+tcp, riap+unix, riap+pipe). http/https and local are supported though.
Automatic validation of schemas
Perinci::Access automatically wraps subroutines with Perinci::Sub::Wrapper, which generates schema validation code using Data::Sah. This adds too much startup overhead, so currently PC::Lite avoids it. Some minimal/rudimentary validation is done instead.
Color themes
Undo
More advanced logging
Only logging to screen is currently supported by PC::Lite, using Log::Any::Adapter::ScreenColoredLevel. PC::Classic, using Log::Any::App can log to files, directories, syslog, and other outputs.
I18N
The following environment variables
PERINCI_CMDLINE_COLOR_THEME PERINCI_CMDLINE_SERVER COLOR UTF8
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.
How does Perinci::CmdLine compare with other CLI-app frameworks?
The main difference is that Perinci::CmdLine accesses your code through 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 1234Everything from help message, calling, argument checking, tab completion works for remote code as well as local Perl code.
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.
SEE ALSO
HOMEPAGE
Please visit the project's homepage at https://metacpan.org/release/Perinci-CmdLine-Lite.
SOURCE
Source repository is at https://github.com/sharyanto/perl-Perinci-CmdLine-Lite.
BUGS
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Perinci-CmdLine-Lite
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) 2015 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.