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.