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 . SOURCE Source repository is at . SEE ALSO Perinci::Result::Format, a more heavyweight version of this module. Perinci::CmdLine::Lite uses this module to format enveloped result. AUTHOR perlancar 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 . 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 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.