Name

Pretty::Table, a simple Raku module to make it quick and easy to represent tabular data in visually appealing ASCII tables.

Pretty::Table is a port of the Python library PTable.

Disclaimer: This module is still a work in progress. Although some basic features are implemented, they still require further testing.

Synopsis

Example 1:

use Pretty::Table;

my $table = Pretty::Table.new:
    title => "Australian Cities",
    field-names => ["City name", "Area", "Population", "Annual Rainfall"],
    sort-by => 'Area',
    align => %('City name' => 'l'),
;

given $table {
    .add-row: ["Adelaide",  1295,  1158259,  600.5 ];
    .add-row: ["Brisbane",  5905,  1857594,  1146.4];
    .add-row: ["Darwin",    112,   120900,   1714.7];
    .add-row: ["Hobart",    1357,  205556,   619.5 ];
    .add-row: ["Sydney",    2058,  4336374,  1214.8];
    .add-row: ["Melbourne", 1566,  3806092,  646.9 ];
    .add-row: ["Perth",     5386,  1554769,  869.4 ];
}

say $table;

Output:

+—————————————————————————————————————————————————+
|                Australian Cities                |
+———————————+——————+————————————+—————————————————+
| City name | Area | Population | Annual Rainfall |
+———————————+——————+————————————+—————————————————+
| Darwin    | 112  |   120900   |      1714.7     |
| Adelaide  | 1295 |  1158259   |      600.5      |
| Hobart    | 1357 |   205556   |      619.5      |
| Melbourne | 1566 |  3806092   |      646.9      |
| Sydney    | 2058 |  4336374   |      1214.8     |
| Perth     | 5386 |  1554769   |      869.4      |
| Brisbane  | 5905 |  1857594   |      1146.4     |
+———————————+——————+————————————+—————————————————+

Example 2:

use Pretty::Table;

my $table = Pretty::Table.new;

given $table {
    .add-column('Planet', ['Earth', 'Mercury', 'Venus', 'Mars', 'Jupiter', 'Saturn', 'Uranus', 'Neptune']);
    .add-column('Position', [3, 1, 2, 4, 5, 6, 7, 8])
    .add-column('Known Satellites', [1, 0, 0, 2, 79, 82, 27, 14]);
    .add-column('Orbital period (days)', [365.256, 87.969, 224.701, 686.971, 4332.59, 10_759.22, 30_688.5, 60_182.0]);
    .add-column('Surface gravity (m/s)', [9.806, 3.7, 8.87, 3.721, 24.79, 10.44, 8.69, 11.15]);
}

$table.title('Planets in the Solar System');
$table.align(%(:Planet<l>));
$table.float-format(%('Orbital period (days)' => '-10.3f', 'Surface gravity (m/s)' => '-5.3f'));
$table.sort-by('Position');
$table.junction-char('*');

put $table;

Output:

*————————————————————————————————————————————————————————————————————*
|                    Planets in the Solar System                     |
*—————————*——————————*———————————————————————*———————————————————————*
| Planet  | Position | Orbital period (days) | Surface gravity (m/s) |
*—————————*——————————*———————————————————————*———————————————————————*
| Mercury |    1     |       87.969          |         3.700         |
| Venus   |    2     |       224.701         |         8.870         |
| Earth   |    3     |       365.256         |         9.806         |
| Mars    |    4     |       686.971         |         3.721         |
| Jupiter |    5     |       4332.590        |         24.790        |
| Saturn  |    6     |       10759.220       |         10.440        |
| Uranus  |    7     |       30688.500       |         8.690         |
| Neptune |    8     |       60182.000       |         11.150        |
*—————————*——————————*———————————————————————*———————————————————————*

Installation

Using zef:

zef install Pretty::Table

From source:

$ git clone 
$ cd raku-pretty-table
$ zef install .

Quickstart

Pretty::Table supports two kinds of usage:

As a module

use Pretty::Table;
my $x = Pretty::Table.new;

Read the section Getter and Setter Methods to find about the public attributes and their respective methods. For the tutorial, run p6doc Pretty::Table::Tutorial.

As a command-line tool

pt --csv somefile.csv

Run pt to get the full usage message.

Methods

Getter and Setter Methods

NOTE: These methods's names are the same as their respective attributes. To set a specific attribute during the instantiation of a Pretty::Table object, use its method's name. For instance, to set title, Pretty::Table.new(title => "Table's title"). Thus, all methods listed here have an associated attribute that can be set during object construction.

multi method field-names

multi method field-names() returns Array

Return a list of field names.

multi method field-names

multi method field-names(
    @values
) returns Nil

Set a list of field names.

multi method align

multi method align() returns Hash

Return how the alignment of fields is controlled.

multi method align

multi method align(
    $val
) returns Nil

Set how the alignment of fields is controlled. Either an alignment string (l, c, or r) or a hash of field-to-alignment pairs.

multi method valign

multi method valign() returns Hash

Return how the vertical alignment of fields is controlled.

multi method valign

multi method valign(
    $val
) returns Nil

Set how the vertical alignment of fields is controlled. Either an alignment string (t, m, or b) or a hash of field-to-alignment pairs.

multi method max-width

multi method max-width() returns Pretty::Table::Constrains::NonNeg

Return the maximum width of fields.

multi method max-width

multi method max-width(
    $val where { ... }
) returns Nil

Set the maximum width of fields.

multi method min-width

multi method min-width() returns Hash

Return the minimum width of fields.

multi method min-width

multi method min-width(
    $val where { ... }
) returns Nil

Set the minimum width of fields.

multi method min-table-width

multi method min-table-width() returns Pretty::Table::Constrains::NonNeg

Return the minimum desired table width, in characters.

multi method min-table-width

multi method min-table-width(
    $val where { ... }
) returns Mu

Set the minimum desired table width, in characters.

multi method max-table-width

multi method max-table-width() returns Mu

Return the maximum desired table width, in characters.

multi method max-table-width

multi method max-table-width(
    $val where { ... }
) returns Mu

Set the minimum desired table width, in characters.

multi method fields

multi method fields() returns Array

Return the list of field names to include in displays.

multi method fields

multi method fields(
    @values
) returns Mu

Return the list of field names to include in displays.

multi method title

multi method title() returns Str

Return the table title (if existent).

multi method title

multi method title(
    Str $val
) returns Mu

Set the table title.

multi method start

multi method start() returns Pretty::Table::Constrains::NonNeg

Return the start index of the range of rows to print.

multi method start

multi method start(
    $val where { ... }
) returns Mu

Set the start index of the range of rows to print.

multi method end

multi method end() returns Mu

Return the end index of the range of rows to print.

multi method end

multi method end(
    $val
) returns Mu

Set the end index of the range of rows to print.

multi method sort-by

multi method sort-by() returns Mu

Return the name of field by which to sort rows.

multi method sort-by

multi method sort-by(
    Str $val where { ... }
) returns Mu

Set the name of field by which to sort rows.

multi method reverse-sort

multi method reverse-sort() returns Bool

Return the direction of sorting, ascending (False) vs descending (True).

multi method reverse-sort

multi method reverse-sort(
    Bool $val
) returns Nil

Set the direction of sorting (ascending (False) vs descending (True).

multi method sort-key

multi method sort-key() returns Callable

Return the sorting key function, applied to data points before sorting.

multi method sort-key

multi method sort-key(
    &val
) returns Nil

Set the sorting key function, applied to data points before sorting.

multi method header

multi method header() returns Bool

Return whether the table has a heading showing the field names.

multi method header

multi method header(
    Bool $val
) returns Nil

Set whether the table has a heading showing the field names.

multi method header-style

multi method header-style() returns Pretty::Table::Constrains::HeaderStyle

Return style to apply to field names in header ("cap", "title", "upper", or "lower").

multi method header-style

multi method header-style(
    $val where { ... }
) returns Mu

Set style to apply to field names in header ("cap", "title", "upper", or "lower").

multi method border

multi method border() returns Bool

Return whether a border is printed around table.

multi method border

multi method border(
    Bool $val
) returns Mu

Set whether a border is printed around table.

multi method hrules

multi method hrules() returns Pretty::Table::Constrains::HorizontalRule

Return how horizontal rules are printed after rows.

multi method hrules

multi method hrules(
    $val where { ... }
) returns Mu

Set how horizontal rules are printed after rows. Allowed values: FRAME, ALL, HEADER, NONE

multi method vrules

multi method vrules() returns Pretty::Table::Constrains::VerticalRule

Return how vertical rules are printed between columns.

multi method vrules

multi method vrules(
    $val where { ... }
) returns Mu

Set how vertical rules are printed between columns. Allowed values: FRAME, ALL, NONE

multi method int-format

multi method int-format() returns Mu

Return how the integer data is formatted.

multi method int-format

multi method int-format(
    $val
) returns Nil

Set how the integer data is formatted. The value can either be a string or a hash of field-to-format pairs.

multi method float-format

multi method float-format() returns Mu

Return how the integer data is formatted.

multi method float-format

multi method float-format(
    $val
) returns Nil

Set how the integer data is formatted. The value can either be a string or a hash of field-to-format pairs.

multi method padding-width

multi method padding-width() returns Pretty::Table::Constrains::NonNeg

Return the number of empty spaces between a column's edge and its content.

multi method padding-width

multi method padding-width(
    $val where { ... }
) returns Nil

Set the number of empty spaces between a column's edge and its content.

multi method left-padding-width

multi method left-padding-width() returns Pretty::Table::Constrains::NonNeg

Return the number of empty spaces between a column's left edge and its content.

multi method left-padding-width

multi method left-padding-width(
    $val where { ... }
) returns Nil

Set the number of empty spaces between a column's left edge and its content.

multi method right-padding-width

multi method right-padding-width() returns Pretty::Table::Constrains::NonNeg

Return the number of empty spaces between a column's right edge and its content.

multi method right-padding-width

multi method right-padding-width(
    $val where { ... }
) returns Nil

Set the number of empty spaces between a column's right edge and its content.

multi method vertical-char

multi method vertical-char() returns Pretty::Table::Constrains::Char

Return character used when printing table borders to draw vertical lines.

multi method vertical-char

multi method vertical-char(
    $val where { ... }
) returns Nil

Return character used when printing table borders to draw vertical lines.

multi method horizontal-char

multi method horizontal-char() returns Pretty::Table::Constrains::Char

Return character used when printing table borders to draw horizontal lines.

multi method horizontal-char

multi method horizontal-char(
    $val where { ... }
) returns Nil

Return character used when printing table borders to draw horizontal lines.

multi method junction-char

multi method junction-char() returns Pretty::Table::Constrains::Char

Return character used when printing table borders to draw line junctions.

multi method junction-char

multi method junction-char(
    $val where { ... }
) returns Nil

Return character used when printing table borders to draw line junctions.

multi method format

multi method format() returns Bool

Return whether or not HTML tables are formatted to match styling options.

multi method format

multi method format(
    Bool $val
) returns Nil

Set whether or not HTML tables are formatted to match styling options.

multi method print-empty

multi method print-empty() returns Bool

Return whether or not empty tables produce a header and frame or just an empty string.

multi method print-empty

multi method print-empty(
    Bool $val
) returns Nil

Set whether or not empty tables produce a header and frame or just an empty string.

multi method old-sort-slice

multi method old-sort-slice() returns Bool

Return whether to slice rows before sorting in the "old style".

multi method old-sort-slice

multi method old-sort-slice(
    Bool $val
) returns Nil

Return whether to slice rows before sorting in the "old style".

Style of Table

method set-style

method set-style(
    TableStyle $style
) returns Nil

Set the style to be used for the table. Allowed values: DEFAULT: Show header and border, hrules and vrules are FRAME and ALL respectively, paddings are 1, vert. char is |, hor. char is -, and junction char is +. MSWORD-FRIENDLY: Show header and border, hrules is NONE, paddings are 1, and vert. char is | PLAIN-COLUMNS: Show header and hide border, hrules is NONE, padding is 1, left padding is 0, and right padding is 8 RANDOM: random style

Data Input Methods

method add-row

method add-row(
    @row
) returns Nil

Add a row to the table.

class Mu $

Row of data, should be a list with as many elements as the table has fields.

method del-row

method del-row(
    Int $row-index
) returns Nil

Delete a row from the table.

class Mu $

Index of the row to delete (0-based index).

method add-column

method add-column(
    Str $fieldname,
    @column,
    $align where { ... } = "c",
    $valign where { ... } = "m"
) returns Nil

Add a column to the table.

class Mu $

Name of the field to contain the new column of data.

class Mu $

Column of data, should be a list with as many elements as the table has rows.

class Mu $

Desired alignment for this column - "l" (left), "c" (center), and "r" (right).

class Mu $

Desired vertical alignment for new columns - "t" (top), "m" (middle), and "b" (bottom).

method clear-rows

method clear-rows() returns Nil

Delete all rows from the table but keep the current field names.

method clear

method clear() returns Nil

Delete all rows and field names from the table, maintaining nothing but styling options.

Plain Text String methods

method get-string

method get-string(
    Str :$title = Str,
    :$start where { ... } = Pretty::Table::Constrains::NonNeg,
    :$end where { ... } = Pretty::Table::Constrains::NonNeg,
    :@fields,
    Bool :$header = Bool,
    Bool :$border = Bool,
    :$hrules where { ... } = Pretty::Table::Constrains::HorizontalRule,
    :$vrules where { ... } = Pretty::Table::Constrains::VerticalRule,
    Str :$int-format = Str,
    Str :$float-format = Str,
    :$padding-width where { ... } = Pretty::Table::Constrains::NonNeg,
    :$left-padding-width where { ... } = Pretty::Table::Constrains::NonNeg,
    :$right-padding-width where { ... } = Pretty::Table::Constrains::NonNeg,
    :$vertical-char where { ... } = Pretty::Table::Constrains::Char,
    :$horizontal-char where { ... } = Pretty::Table::Constrains::Char,
    :$junction-char where { ... } = Pretty::Table::Constrains::Char,
    Str :$sort-by = Str,
    :&sort-key,
    Bool :$reverse-sort = Bool,
    Bool :$old-sort-slice = Bool,
    Bool :$print-empty = Bool
) returns Str

Return string representation of table in current state.

class Mu $

See method title

class Mu $

See method start

class Mu $

See method end

class Mu $

See method fields

class Mu $

See method header

class Mu $

See method border

class Mu $

See method hrules

class Mu $

See method vrules

class Mu $

See method int-format

class Mu $

See method float-format

class Mu $

See method padding-width

class Mu $

See method left-padding-width

class Mu $

See method right-padding-width

class Mu $

See method vertical-char

class Mu $

See method horizontal-char

class Mu $

See method junction-char

class Mu $

See method sort-by

class Mu $

See method sort-key

class Mu $

See method reverse-sort

class Mu $

see method old-sort-slice

class Mu $

See method print-empty

Miscellaneous Methods

method row-count

method row-count() returns Int

Return the number of rows.

method col-count

method col-count() returns Int

Return the number of columns.