NAME
    Data::Format::Pretty::Console - Pretty-print data structure for console
    output

VERSION
    version 0.30

SYNOPSIS
    In your program:

     use Data::Format::Pretty::Console qw(format_pretty);
     ...
     print format_pretty($result);

    Some example output:

    Scalar, format_pretty("foo"):

     foo

    List, format_pretty([1..21]):

     .------------------------------------------------------.
     |  1 |  3 |  5 |  7 |  9 | 11 | 13 | 15 | 17 | 19 | 21 |
     |  2 |  4 |  6 |  8 | 10 | 12 | 14 | 16 | 18 | 20 |    |
     '----+----+----+----+----+----+----+----+----+----+----'

    The same list, when program output is being piped (that is, (-t STDOUT)
    is false):

     1
     2
     3
     4
     5
     6
     7
     8
     9
     10
     11
     12
     14
     15
     16
     17
     18
     19
     20
     21

    Hash,
    format_pretty({foo=>"data",bar=>"format",baz=>"pretty",qux=>"console"}):

     +-----+---------+
     | bar | format  |
     | baz | pretty  |
     | foo | data    |
     | qux | console |
     '-----+---------'

    2-dimensional array, format_pretty([ [1, 2, ""], [28, "bar", 3], ["foo",
    3, undef] ]):

     +---------+---------+---------+
     |       1 |       2 |         |
     |      28 | bar     |       3 |
     | foo     |       3 |         |
     '---------+---------+---------'

    An array of hashrefs, such as commonly found if you use DBI's
    fetchrow_hashref() and friends, format_pretty([ {a=>1, b=>2}, {b=>2,
    c=>3}, {c=>4} ]):

     .-----------.
     | a | b | c |
     +---+---+---+
     | 1 | 2 |   |
     |   | 2 | 3 |
     |   |   | 4 |
     '---+---+---'

    Some more complex data, format_pretty({summary => "Blah...", users =>
    [{name=>"budi", domains=>["foo.com", "bar.com"], quota=>"1000"},
    {name=>"arif", domains=>["baz.com"], quota=>"2000"}], verified => 0}):

     summary:
     Blah...

     users:
     .---------------------------------.
     | domains          | name | quota |
     +------------------+------+-------+
     | foo.com, bar.com | budi |  1000 |
     | baz.com          | arif |  2000 |
     '------------------+------+-------'

     verified:
     0

    Structures which can't be handled yet will simply be output as YAML,
    format_pretty({a {b=>1}}):

     ---
     a:
       b: 1

DESCRIPTION
    This module is meant to output data structure in a "pretty" or "nice"
    format, suitable for console programs. The idea of this module is that
    for you to just merrily dump data structure to the console, and this
    module will figure out how to best display your data to the end-user.

    Currently this module tries to display the data mostly as a nice text
    table (or a series of text tables), and failing that, display it as
    YAML.

    This module takes piping into consideration, and will output a simpler,
    more suitable format when your user pipes your program's output into
    some other program.

    Most of the time, you don't have to configure anything, but some options
    are provided to tweak the output.

    This module uses Log::Any for logging.

FUNCTIONS
  format_pretty($data, \%opts)
    Return formatted data structure. Options:

    *   interactive => BOOL (optional, default undef)

        If set, will override interactive terminal detection (-t STDOUT).
        Simpler formatting will be done if terminal is non-interactive (e.g.
        when output is piped). Using this option will force simpler/full
        formatting.

    *   list_max_columns => INT

        When displaying list as columns, specify maximum number of columns.
        This can be used to force fewer columns (for example, single column)
        instead of using the whole available terminal width.

    *   table_column_orders => [[COLNAME1, COLNAME2], ...]

        Specify column orders when drawing a table. If a table has all the
        columns, then the column names will be ordered according to the
        specification. For example, when table_column_orders is [[qw/foo bar
        baz/]], this table's columns will not be reordered because it
        doesn't have all the mentioned columns:

         |foo|quux|

        But this table will:

         |apple|bar|baz|foo|quux|

        into:

         |apple|foo|bar|baz|quux|

    *   table_column_formats => [{COLNAME=>FMT, ...}, ...]

        Specify formats for columns. Each table format specification is a
        hashref {COLNAME=>FMT, COLNAME2=>FMT2, ...}. It will be applied to a
        table if the table has all the columns. FMT is a format
        specification according to Data::Unixish::Apply, it's basically
        either a name of a dux function (e.g. "date") or an array of
        function name + arguments (e.g. "[['date', [align =>
        {align=>'middle'}]]").

ENVIRONMENT
    *   INTERACTIVE => BOOL

        To set default for "interactive" option (overrides automatic
        detection).

    *   FORMAT_PRETTY_LIST_MAX_COLUMNS => INT

        To set "list_max_columns" option.

    *   FORMAT_PRETTY_TABLE_COLUMN_FORMATS => ARRAY (JSON)

        To set "table_column_formats" option, interpreted as JSON.

    *   FORMAT_PRETTY_TABLE_COLUMN_ORDERS => ARRAY (JSON)

        To set "table_column_orders" option, interpreted as JSON.

    *   COLUMNS => INT

        To override terminal width detection.

TODO
    *   when displaying list in columns, option to fill column-wise instead
        of row-wise

        This is like 'ls -x' (our default) vs 'ls'.

        Probably set via "list_fill_by_columns" option.

SEE ALSO
    Modules used for formatting: Text::ANSITable, YAML.

    Data::Format::Pretty

AUTHOR
    Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2013 by Steven Haryanto.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.