Text::Tabulate(3)

NAME
Text::Tabulate - a pretty text data tabulator that minimises the width of tables.

SYNOPSIS
        use Text::Tabulate;

        $tab = new Text::Tabulate (<options>);

        $tab->configure(<options>);

        @out = $tab->format(@lines);

        @out = $tab->common(@lines);

        @out = tabulate ( { tab => '???', ...}, @lines);

        @out = tabulate ( $tab, $pad, $gutter, $adjust, @lines);

DESCRIPTION
This perl module takes an array of line text data, each line separated by some string matching a given regular expression, and returns a minimal width text table with each column aligned.

FUNCTIONS
    "new"

            my $tab = new Text::Tabulate( -tab => 'tab', ...);

    Create an Text::Tabulate object. All CONFIGURATION OPTIONS are accepted, with or without a leading -.

    "configure"

            my $tab = new Text::Tabulate();
            $tab->configure(-tab => 'tab', gutter => '|', ...);

    This function chages the configuration settings of a Text::Tablulate object. All CONFIGURATION OPTIONS are accepted, with or without a leading -.

    "format"

            my $tab = new Text::Tabulate(...);
            @out = $tab->format (@lines);

    Format the table data (@lines) according to the Text::Tabulate object.

    "common"

            my $tab = new Text::Tabulate();
            $tab->configure(-tab => 'tab', cf => 2, ditto => '?');
            @out = $tab->common(@lines);

    This function returns an array of lines identical to the input except that any repeated common value in the first column is removed in subsequent lines and replaced by the string $ditto. If $max is positive, then only that number of columns are considered; otherwise all column are considered.

    The array of lines, @lines, is assumed to be an array of sigle table rows.

    "tabulate"

            @out = tabulate ( { tab => '???', ...}, @lines);
            @out = tabulate ( $tab, $pad, $gutter, $adjust, @lines);

    This function returns an array of formated lines identical to the input except that tab separated columns have been aligned with the padding chacater.

    It can be involked in two ways; either with an hashed array of arguments followed by an array of lines or by 4 parameters (tab, pad, gutter, adjust) followed by an array of lines.

    Suggested usage:

            perl -MText::Tablutate -e'tabulate {gutter=>"|",}'

    "filter"

            Text::Tabulate::filter(@ARGV)

    Act as a UNIX filter taking input from either STDIN or files specified as function arguments, and sending the resulting formtted table to STDOUT. Additional arguments will modify the behavour.

            perl -MText::Tablutate -e'filter(@ARGV)' <options> [files]

    This function is involked if the Text::Tabulate module is run as a perl script.

            perl Text/Tabulate.pm <options> [input-files]

    The function options are

    -s|--stanza
        Treat each paragraph as a individual table.

    -h|--html
        Format each table as HTML.

    The other options correspond to the configuration options of the module.

    -t|--tab <tab>
        Set the tab string. See module configuation options.

    -e|--eol <end-of-line-reg-ex>
        Set the regular expression denoting an end of a table row. See module configuation options.

    -p|--pad <pad>
        Set the pad character. See module configuation options.

    -g|--gutter <gutter>
        Set the gutter string. See module configuation options.

    -I|--Ignore <reg-ex>
        Ignore lines that match this regular expression. See module configuation options.

    -a|--adjust <string>
        Justify columns according to this string. See module configuation options.

    -T|--top <string>
        Set the top border characters. See module configuation options.

    -B|--top <string>
        Set the bottom border characters. See module configuation options.

    -l|--left <string>
        Set the left border string. See module configuation options.

    -r|--right <string>
        Set the right border string. See module configuation options.

    -c|--cf <number>
        This specifies if repeated values in the first few fields should be replaced by the empty string. See module configuation options.

    -d|--ditto <number>
        This specified the string that replaces common values (see cf above). See module configuation options.

CONFIGURATION OPTIONS
The module configuration options are:

tab This specified a regular expression denoting the original table separator. The default is <TAB>.

eol This specified a regular expression denoting the end of table lines. The default is '(\n)|(\r\n)|(\r)' to match most text formats. These end of line strings are replaced after the table is formating.

pad This specified the character used to pad the fields in the final representation of the table. The default is a space.

gutter
    This specifies the string places between columns in the final representation. The default is the empty string.

adjust
    This is a string specifying the justification of each field in the final representation. Each character of this string should be 'r', 'l' or 'c'. The default is left justification for all fields.

ignore
    This regular expresion specifies lines that should be ignored. The default is not to ignore any line.

cf  This specifies if repeated values in the first few fields should be replaced by the empty string. The default is not to do this.

ditto
    This specified the string that replaces common values (see cf above).

top This specified the characters to be placed at the top of the table as a border. If it is one character, then this is used as every character on the top border. If there are more than one character then the first is used for the first column, the second character for the second column, etc.. The default is empty (i.e. no top border).

bottom
    This specified the characters to be placed at the bottom of the table as a border. If it is one character, then this is used as every character on the bottom border. If there are more than one character then the first is used for the first column, the second character for the second column, etc.. The default is empty (i.e. no bottom border).

left
    This specifies the strings to be placed as a border on the left of the table. The default is nothing.

right
    This specifies the strings to be placed as a border on the right of the table. The default is nothing.

joint
    This specifies the string used to join the rows of the table when the format and tabulate functions are called in a scalar context. This is most useful when the table input is split on newlines and a scaler return is required that includes newlines. Very similar to left but depends on the context. The default is nothing.

EXAMPLE
        use Text::Tabulate;
        my $tab = new Text::Tabulate();
        $tab->configure(-tab => "\t", gutter => '|');

        my @lines = <>:
        @out = $tab->format (@lines);
        print @out;

VERSION
This is version 1.0 of Text::Tabulate, released 1 July 2007.

AUTHOR
        Anthony Fletcher

COPYRIGHT
Copyright (c) 1998-2007 Anthony Fletcher. All rights reserved. This module is free software; you can redistribute them and/or modify them under the same terms as Perl itself.

This code is supplied as-is - use at your own risk.

POD ERRORS
Hey! The above document had some coding errors, which are explained below:

Around line 32:
    You can't have =items (as at line 75) unless the first thing after the =over is an =item

Around line 756:
    You forgot a '=back' before '=head1'

Around line 844:
    =back without =over