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.