NAME
Data::Format::Pretty::Console - Pretty-print data structure for console
output
VERSION
This document describes version 0.392 of Data::Format::Pretty::Console
(from Perl distribution Data-Format-Pretty-Console), released on
2023-08-07.
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.
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'}]]"). This will be fed to Text::ANSITable's
"formats" column style.
* table_column_types => [{COLNAME=>TYPE, ...}, ...]
Specify types for columns. Each table format specification is a
hashref {COLNAME=>TYPE, COLNAME2=>TYPE2, ...}. It will be applied to
a table if the table has all the columns. TYPE is type name
according to Sah schema. This will be fed to Text::ANSITable's
"type" column style to give hints on how to format the column.
Sometimes this is the simpler alternative to "table_column_formats".
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_TYPES => ARRAY (JSON)
To set "table_column_types" 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.
HOMEPAGE
Please visit the project's homepage at
<https://metacpan.org/release/Data-Format-Pretty-Console>.
SOURCE
Source repository is at
<https://github.com/perlancar/perl-Data-Format-Pretty-Console>.
SEE ALSO
Modules used for formatting: Text::ANSITable, YAML.
Data::Format::Pretty
AUTHOR
perlancar <perlancar@cpan.org>
CONTRIBUTOR
Steven Haryanto <stevenharyanto@gmail.com>
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, 2021, 2017, 2016, 2015, 2014, 2013,
2012, 2011, 2010 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=Data-Format-Pretty-Co
nsole>
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.