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.