The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Perinci-Result-Format-Lite-0.288
River stage three • 17 direct dependents • 718 total dependents
++
/ Perinci::Result::Format::Lite

NAME

Perinci::Result::Format::Lite - Format enveloped result

VERSION

This document describes version 0.288 of Perinci::Result::Format::Lite (from Perl distribution Perinci-Result-Format-Lite), released on 2023-07-29.

SYNOPSIS

DESCRIPTION

This module formats enveloped result structure to "pretty text" if it can do so, e.g. the structure can be represented as a 2-dimensional table. Otherwise, it falls back to JSON or Perl. The table formats supported include CSV, TSV, LTSV, or HTML. More table formats (e.g. Org, Markdown) are supported via Text::Table::Any when you set "FORMAT_PRETTY_TABLE_BACKEND".

This module is a more lightweight version of Perinci::Result::Format but the long-term goal is to reunite the two formatting modules back to a modular/pluggable module.

SUPPORTED RESULT METADATA PROPERTIES/ATTRIBUTES

The enveloped result specification specifies various properties/attributes that can be used as formatting hints. Below are the list of properties/attributes supported by this module, including those that are not in the specification:

  • table.html_class

    Str. Used when formatting result as HTML table.

  • table.fields

    Array of str. Define fields in order. Used when formatting result as text table. Fields that are not defined in this array will be displayed after the defined fields (or hidden, if you set table.hide_unknown_fields).

  • table.hide_unknown_fields

    Bool. If set to true, then unknown fields (those not defined in table.fields) will not be shown. Used when formatting result as text table.

  • table.field_orders

    Array of str. Like table.fields, but with higher precedence.

  • table.field_labels

    Array of str. Define labels for each field (each element correspond to the field of the same element as defined in table.fields). Used when formatting result as text table. Will show this in header for fields instead the actual field name.

  • table.field_units

    Array of str. Define units for each field (each element correspond to the field of the same element as defined in table.fields). Used when formatting result as text table. Will show this along with field name/label. For example if a field's unit is defined as `cm` and field name is `length`, then the field header will show as `length (cm)`.

  • table.field_formats

    Array of str. Define format for each field (each element correspond to the field of the same element as defined in table.fields). Used when formatting result as text table. Known formats: `iso8601_datetime`, `iso8601_date`, `datetime`, `date`, `boolstr`, `filesize`, `sci2dec`, `percent`, `number`.

  • table.field_format_code

    Coderef. Will be called with argument of field name. Expected to return format name (see table.field_formats). Used when formatting result as text table. This option can be used when you want to dynamically determine a suitable format based on field name.

  • table.default_field_format

    Str. Instead of defining format for each field using `table.field_formats`, you can also specify default format for all fields.

  • table.field_aligns

    Array of str. Define alignment for each field (each element correspond to the field of the same element as defined in table.fields). Used when formatting result as text table. Known alignment value for each field: `number` (special rule to align on decimal point or `E`), `right`, `middle`|`center`, `right`.

  • table.field_align_code

    Coderef. Will be called with argument of field name. Expected to return alignment name (see table.field_aligns). Used when formatting result as text table. This option can be used when you want to dynamically determine a suitable alignment based on field name.

  • table.default_field_align

    Str. Instead of defining alignment for each field using `table.field_aligns`, you can also specify default alignment for all fields.

FUNCTIONS

format($res, $format[ , $is_naked=0, $cleanse=1 ]) => str

ENVIRONMENT

FORMAT_PRETTY_TABLE_BACKEND

Str, optional. If this is set, will render text table using Text::Table::Any (with backend set to the value of this environment variable) instead of the default Text::Table::Sprintf. This is useful if you want to output text table in a different format, for example to generate Org tables (make sure Text::Table::Org backend is already installed):

 % FORMAT_PRETTY_TABLE_BACKEND=Text::Table::Org lcpan rdeps Getopt::Lucid

For convenience, a default is chosen for you under certain condition. When inside Emacs (environment INSIDE_EMACS is set), Text::Table::Org is used as default.

FORMAT_PRETTY_TABLE_BACKEND_OPTS

Str, JSON-encoding expected. This setting is to accompany "FORMAT_PRETTY_TABLE_BACKEND", to be passed to Text::Table::Any::table()'s backend_opts argument. It should be a hash encoded in JSON, e.g.:

 # keep table aligned in the presence of wide Unicode characters
 % FORMAT_PRETTY_TABLE_BACKEND=Text::Table::More FORMAT_PRETTY_TABLE_BACKEND_OPTS='{"wide_char":1}' tabledata locale::JP::City::MIC --page

FORMAT_PRETTY_TABLE_COLUMN_ORDERS => array (json)

Set the default of table_column_orders in format_options in result metadata, similar to what's implemented in Perinci::Result::Format and Data::Format::Pretty::Console.

COLOR => bool

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Perinci-Result-Format-Lite.

SOURCE

Source repository is at https://github.com/perlancar/perl-Perinci-Result-Format-Lite.

SEE ALSO

Perinci::Result::Format, a more heavyweight version of this module.

Perinci::CmdLine::Lite uses this module to format enveloped result.

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, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

This software is copyright (c) 2023, 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-Result-Format-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.