package Perinci::CmdLine::Manual::FAQ; # just to make podweaver happy

# DATE
# VERSION

1;
# ABSTRACT: FAQs

__END__

=pod

=encoding UTF-8

=head1 NAME

Perinci::CmdLine::Manual::FAQ - FAQs

=head1 VERSION

This document describes version 0.94 of Perinci::CmdLine::Manual::FAQ (from Perl distribution Perinci-CmdLine-Lite), released on 2015-03-18.

=head1 NOMENCLATURE

C<[PC::Classic]> denotes that the answer applies to L<Perinci::CmdLine::Classic>
only and not L<Perinci::CmdLine::Lite>. C<[PC::Lite]> denotes that the answer is
specific to Perinci::CmdLine::Lite. C<[PC::Any]> denotes that the answer is
specific to L<Perinci::CmdLine::Any>.

=head1 GENERAL

=head2 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,
L<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 L<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
L<Perinci::Access> with L<Perinci::Access::Lite> for metadata access, currently
not using L<Data::Sah> for validator generation, avoiding L<Text::ANSITable> for
formatting results, and replacing L<Log::Any::App> (which uses the relatively
heavy L<Log::Log4perl>) with L<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, L<Perinci::CmdLine::Base>. The interface is also 99% the same.

It is possible that in the future the two versions will merge again.

=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 * Automatic validation of schemas

Perinci::Access automatically wraps subroutines with L<Perinci::Sub::Wrapper>,
which generates schema validation code using L<Data::Sah>. This adds too much
startup overhead, so currently PC::Lite avoids it. Some minimal/rudimentary
validation is done instead.

=item * Color themes

=item * Undo

=item * More advanced logging

Only logging to screen is currently supported by PC::Lite, using
L<Log::Any::Adapter::ScreenColoredLevel>. PC::Classic, using L<Log::Any::App>
can log to files, directories, syslog, and other outputs.

=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 SEE ALSO

L<Perinci::CmdLine::Manual>

=head1 HOMEPAGE

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

=head1 SOURCE

Source repository is at L<https://github.com/perlancar/perl-Perinci-CmdLine-Lite>.

=head1 BUGS

Please report any bugs or feature requests on the bugtracker website L<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.

=head1 AUTHOR

perlancar <perlancar@cpan.org>

=head1 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.

=cut
