The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

NAME

Perinci::CmdLine::Inline - Generate inline Perinci::CmdLine CLI script

VERSION

This document describes version 0.554 of Perinci::CmdLine::Inline (from Perl distribution Perinci-CmdLine-Inline), released on 2022-01-16.

SYNOPSIS

% gen-inline-pericmd-script /Perinci/Examples/gen_array -o gen-array

% ./gen-array
ERROR 400: Missing required argument(s): len

% ./gen-array --help
... help message printed ...

% ./gen-array 3
2
3
1

% ./gen-array 3 --json
[200,"OK",[3,1,2],{}]

DESCRIPTION

COMPILATION DATA KEYS

A hash structure, $cd, is constructed and passed around between routines during the generation process. It contains the following keys:

  • module_srcs => hash

    Generated script's module source codes. To reduce startup overhead and dependency, these modules' source codes are included in the generated script using the datapack technique (see Module::DataPack).

    Among the modules are Getopt::Long::EvenLess to parse command-line options, Text::Table::Sprintf to produce text table output, and also a few generated modules to modularize the generated script's structure.

  • vars => hash

    Generated script's global variables. Keys are variable names (including the sigils) and values are initial variable values (undef means unitialized).

  • sub_srcs => hash

    Generated script's subroutine source codes. Keys are subroutines' names and values are subroutines' source codes.

ENVIRONMENT (GENERATED SCRIPTS)

These are environment variables observed by the generated scripts.

PERINCI_CMDLINE_INLINE_DEBUG_DIE

Bool. If set to true, then will rethrow exception instead of converting it into enveloped result. This makes debugging easier.

FUNCTIONS

gen_inline_pericmd_script

Usage:

gen_inline_pericmd_script(%args) -> [$status_code, $reason, $payload, \%result_meta]

Generate inline Perinci::CmdLine CLI script.

The goal of this module is to let you create a CLI script from a Riap function/metadata. This is like what Perinci::CmdLine::Lite or Perinci::CmdLine::Classic does, except that the generated CLI script will have the functionalities inlined so it only need core Perl modules and not any of the Perinci::CmdLine::* or other modules to run (excluding what modules the Riap function itself requires).

It's useful if you want a CLI script that is even more lightweight (in terms of startup overhead or dependencies) than the one using Perinci::CmdLine::Lite.

So to reiterate, the goal of this module is to create a Perinci::CmdLine-based script which only requires core modules, and has as little startup overhead as possible.

Currently it only supports a subset of features compared to other Perinci::CmdLine::* implementations:

As an alternative to this module, if you are looking to reduce dependencies, you might also want to try using depak to fatpack/datapack your Perinci::CmdLine::Lite-based script.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

  • actions => any

    Currently does nothing, provided only for compatibility with Perinci::CmdLine::Base.

  • allow_prereq => array[str]

    A list of modules that can be depended upon.

    By default, Perinci::CmdLine::Inline will strive to make the script freestanding and require only core Perl modules. A dependency to a non-core module will cause failure (unless pack_deps option is set to false). However, you can pass a list of modules that is allowed here.

  • code_add_extra_log_outputs => str

  • code_after_enable_logging => str

  • code_after_end => str

    Put at the very end of generated script.

  • code_after_shebang => str

    Put at the very beginning of generated script, after the shebang line.

  • code_before_enable_logging => str

  • code_before_parse_cmdline_options => str

  • common_opts => any

    Currently does nothing, provided only for compatibility with Perinci::CmdLine::Base.

  • completion => any

    Currently does nothing, provided only for compatibility with Perinci::CmdLine::Base.

  • config_dirs => array[str]

    Where to search for configuration files.

  • config_filename => str|hash|array[str|hash]

    Configuration file name(s).

  • default_format => any

    Currently does nothing, provided only for compatibility with Perinci::CmdLine::Base.

  • default_subcommand => str

  • description => any

    Currently does nothing, provided only for compatibility with Perinci::CmdLine::Base.

  • env_name => str

    Name of environment variable name that sets default options.

  • exit => any

    Currently does nothing, provided only for compatibility with Perinci::CmdLine::Base.

  • extra_urls_for_version => array[riap::url]

    More URLs to show version for --version.

    Currently not implemented in Perinci::CmdLine::Inline.

  • formats => any

    Currently does nothing, provided only for compatibility with Perinci::CmdLine::Base.

  • get_subcommand_from_arg => any

    Currently does nothing, provided only for compatibility with Perinci::CmdLine::Base.

  • include => array[perl::modname]

    Include extra modules.

  • log => bool (default: 0)

    Whether to enable logging.

  • meta => hash

    An alternative to specifying `url`.

  • meta_is_normalized => bool

  • output_file => filename

    Set output file, defaults to stdout.

  • overwrite => bool

  • pack_deps => bool (default: 1)

    Whether to pack dependencies into the script.

    By default, Perinci::CmdLine::Inline will use datapacking technique (i.e. embed dependencies into DATA section and load it on-demand using require() hook) to make the script freestanding. However, in some situation this is unwanted, e.g. when we want to produce a script that can be packaged as a Debian package (Debian policy forbids embedding convenience copy of code, https://www.debian.org/doc/debian-policy/ch-source.html#s-embeddedfiles ).

  • pass_cmdline_object => bool (default: 0)

    Whether to pass Perinci::CmdLine::Inline object.

  • pod => bool (default: 1)

    Whether to generate POD for the script.

  • read_config => bool (default: 1)

    Whether the CLI script should read configuration files.

  • read_env => bool

    Whether CLI script should read environment variable that sets default options.

  • riap_client => any

    Currently does nothing, provided only for compatibility with Perinci::CmdLine::Base.

  • riap_client_args => any

    Currently does nothing, provided only for compatibility with Perinci::CmdLine::Base.

  • riap_version => any

    Currently does nothing, provided only for compatibility with Perinci::CmdLine::Base.

  • script_name => str

    Currently does nothing, provided only for compatibility with Perinci::CmdLine::Base.

  • script_summary => str

    Currently does nothing, provided only for compatibility with Perinci::CmdLine::Base.

  • script_version => str

    Script version (otherwise will use version from url metadata).

  • script_version_from_main_version => bool

    Use script's $main::VERSION for the version.

  • shebang => str

    Set shebang line.

  • skip_format => bool (default: 0)

    Assume that function returns raw text that need no formatting, do not offer --format, --json, --naked-res.

  • stripper => bool (default: 0)

    Whether to strip code using Perl::Stripper.

  • sub_name => str

  • subcommands => hash

  • tags => any

    Currently does nothing, provided only for compatibility with Perinci::CmdLine::Base.

  • url => riap::url

    Program URL.

  • use_cleanser => bool (default: 1)

    Whether to use data cleanser routine first before producing JSON.

    When a function returns result, and the user wants to display the result as JSON, the result might need to be cleansed first (e.g. using Data::Clean) before it can be encoded to JSON, for example it might contain Perl objects or scalar references or other stuffs. If you are sure that your function does not produce those kinds of data, you can set this to false to produce a more lightweight script.

  • use_utf8 => bool (default: 0)

    Whether to set utf8 flag on output.

  • validate_args => bool (default: 1)

    Whether the CLI script should validate arguments using schemas.

  • with_debug => bool

    Generate script with debugging outputs.

Returns an enveloped result (an array).

First element ($status_code) is an integer containing HTTP-like status code (200 means OK, 4xx caller error, 5xx function error). Second element ($reason) is a string containing error message, or something like "OK" if status is 200. Third element ($payload) is the actual result, but usually not present when enveloped result is an error response ($status_code is not 2xx). Fourth element (%result_meta) is called result metadata and is optional, a hash that contains extra information, much like how HTTP response headers provide additional metadata.

Return value: (any)

FAQ

What about tab completion?

Use App::GenPericmdCompleterScript to generate a separate completion script. If you use Dist::Zilla, see also Dist::Zilla::Plugin::GenPericmdScript which lets you generate script (and its completion script) during build.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Perinci-CmdLine-Inline.

SOURCE

Source repository is at https://github.com/perlancar/perl-Perinci-CmdLine-Inline.

SEE ALSO

Perinci::CmdLine, Perinci::CmdLine::Any, Perinci::CmdLine::Lite, Perinci::CmdLine::Classic

App::GenPericmdScript

AUTHOR

perlancar <perlancar@cpan.org>

CONTRIBUTING

To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

% prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla plugin and/or Pod::Weaver::Plugin. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

This software is copyright (c) 2022, 2021, 2020, 2018, 2017, 2016, 2015 by perlancar <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.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Perinci-CmdLine-Inline

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.