/ 
Perinci-CmdLine-Lite-0.13
River stage three • 338 direct dependents • 520 total dependents
/ Perinci::CmdLine::Lite

NAME

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

VERSION

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

SYNOPSIS

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

DESCRIPTION

Perinci::CmdLine::Lite (hereby P::C::Lite) is a lightweight (low startup overhead, minimal dependencies) alternative to Perinci::CmdLine (hereby P::C). It offers a subset of functionality and a compatible API. Unless you use the unsupported features of P::C, P::C::Lite is a drop-in replacement for P::C (also see Perinci::CmdLine::Any for automatic fallback).

P::C::Lite stays lightweight by avoiding the use of libraries that have large dependencies or add too much to startup overhead. This includes Perinci::Access for metadata access, Data::Sah for validator generation, Text::ANSITable for formatting results, and Log::Any::App (which uses Log::Log4perl) for logging.

I first developed P::C::Lite mainly for CLI applications that utilize shell tab completion as their main feature, e.g. App::PMUtils, App::ProgUtils, App::GitUtils.

Below is summary of the differences between P::C::Lite and P::C:

  • P::C::Lite starts much faster

    The target is under 0.05s to make shell tab completion convenient. On the other hand, P::C can start between 0.2-0.5s.

  • P::C::Lite uses simpler 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, P::C::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.

  • No remote URL support in P::C::Lite

    Instead of using Perinci::Access, P::C::Lite accesses Perl packages on the filesystem directly. This means only code on the filesystem is available. (But I plan to write another subclass P::C::Lite::HTTP that uses HTTP::Tiny or HTTP::Tiny::UNIX for Riap::HTTP support).

  • No automatic validation from schema in P::C::Lite

    Since code wrapping and schema code generation done by Perinci::Sub::Wrapper and Data::Sah (which are called automatically by Perinci::Access) adds too much startup overhead.

  • P::C::Lite does not support color themes

  • P::C::Lite does not support undo

  • P::C::Lite does not currently support logging

    Something more lightweight than Log::Any::App will be considered. But for now, if you want to view logging and your function uses Log::Any, you can do something like this:

    % DEBUG=1 PERL5OPT=-MLog::Any::App app.pl

  • P::C::Lite does not support progress indicator

  • P::C::Lite does not support I18N

  • P::C::Lite does not yet support these Rinci function metadata properties

    x.perinci.cmdline.default_format

  • P::C::Lite does not yet support these Rinci function argument specification properties

    cmdline_src

  • P::C::Lite does not yet support these Rinci result metadata properties/attributes

    is_stream
cmdline.display_result
cmdline.page_result
cmdline.pager

  • P::C::Lite does not yet support these environment variables

    PERINCI_CMDLINE_COLOR_THEME
PERINCI_CMDLINE_SERVER
PROGRESS
PAGER
COLOR
UTF8

DEBUG, VERBOSE, QUIET, TRACE, and so on

  • In passing command-line object to functions, P::C::Lite object is passed

    Some functions might expect a Perinci::CmdLine instance.

ATTRIBUTES

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

METHODS

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

ENVIRONMENT

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

SEE ALSO

Perinci::CmdLine, Perinci::CmdLine::Manual

Perinci::CmdLine::Any

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

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.