NAME

Text::Yeti::Table - Render a table like "docker ps" does

VERSION

version 0.3.0

SYNOPSIS

use Text::Yeti::Table qw(render_table);

render_table( $list, $spec );

DESCRIPTION

Text::Yeti::Table renders a table of data into text. Given a table (which is an arrayref of hashrefs) and a specification, it creates output such as below.

CONTAINER ID   IMAGE                   CREATED       STATUS               NAME           
632495650e4e   alpine:latest           5 days ago    Exited 5 days ago    zealous_galileo
6459c004a7b4   postgres:9.6.1-alpine   23 days ago   Up 23 days           hardcore_sammet
63a4c1b60c9f   f348af3681e0            2 weeks ago   Exited 12 days ago   elastic_ride   

The specification can be as simple as:

[ 'key1', 'key2', 'key3' ]

For complex values, a function can be given for the text conversion.

[ 'name', 'id', 'node', 'address', [ 'tags', sub {"@{$_[0]}"} ] ]

Usually headers are computed from keys, but that can be overriden.

[ 'ServiceName', 'ServiceID', 'Node', [ 'Datacenter', undef, 'DC' ] ]

EXAMPLE

The following code illustrates a full example:

my @items = (
    {   ContainerId => '632495650e4e',
        Image       => 'alpine:latest',
        Created     => { unit => 'days', amount => 5 },
        ExitedAt    => { unit => 'days', amount => 5 },
        Name        => '/zealous_galileo',
    },
    {   ContainerId => '6459c004a7b4',
        Image       => 'postgres:9.6.1-alpine',
        Created     => { unit => 'days', amount => 23 },
        StartedAt   => { unit => 'days', amount => 23 },
        Running     => true,
        Name        => '/hardcore_sammet',
    },
    {   ContainerId => '63a4c1b60c9f',
        Image       => 'f348af3681e0',
        Created     => { unit => 'weeks', amount => 2 },
        ExitedAt    => { unit => 'days', amount => 12 },
        Name        => '/elastic_ride',
    },
);

sub status_of {
    my ( $running, $item ) = ( shift, shift );
    $running
      ? "Up $item->{StartedAt}{amount} $item->{StartedAt}{unit}"
      : "Exited $item->{ExitedAt}{amount} $item->{ExitedAt}{unit} ago";
}

my @spec = (
    'ContainerId',
    'Image',
    [ 'Created', sub {"$_[0]->{amount} $_[0]->{unit} ago"} ],
    [   'Running', \&status_of, 'STATUS' ],
    [ 'Name', sub { substr( shift, 1 ) } ],
);

render_table( \@items, \@spec );

The corresponding output is the table in "DESCRIPTION".

FUNCTIONS

Text::Yeti::Table implements the following functions, which can be imported individually.

render_table

render_table( \@items, $spec );
render_table( \@items, $spec, $io );

The $spec is an arrayref whose entries can be:

• a string (like 'key'), which is equivalent to

  ['key']

• an arrayref, with up to 3 entries

  ['key', $to_s, $header]

  $to_s is a function to convert the value under 'key' to text. By default, it stringifies the value, except for undef which becomes "<none>".

  $header is the header for the corresponding column. By default, it is computed from the key, as in the examples below:

  "image"       -> "IMAGE"
  "ContainerID" -> "CONTAINER ID"

• a hashref, with keys

  k => 'key',       required
  s => $to_s,
  h => $header,
  x => $exclude,

  where

  $to_s is a function to convert the value under k to text. By default, undef becomes '<none>', and everything else is stringfied.

  $header is the header for the corresponding column. If not given, it is computed from the key as above.

  $exclude is a coderef which given all the values of a column (as an arrayref) should return true if the column should be excluded or false if the column is to be kept. As an example,

  use List::Util 'all';
  (x => sub { all { $_ eq '<none>' } @{$_[0]} })

  will exclude the corresponding column if all values collapse to '<none>'.

The $io is a handle. By default, output goes to STDOUT.

AUTHOR

Adriano Ferreira <ferreira@cpan.org>

CONTRIBUTOR

Adriano Ferreira <a.r.ferreira@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017-2018 by Adriano Ferreira.

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

cpanm Text::Yeti::Table

perl -MCPAN -e shell
install Text::Yeti::Table