The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Text-Matrix-1.00
River stage one • 1 direct dependent • 1 total dependent
++
/ Text::Matrix

NAME

Text::Matrix - Text table layout for matrices of short regular data.

SYNOPSIS

    use Text::Matrix;

    my $rows    = [ 'Row A', 'Row B', 'Row C', 'Row D' ];
    my $columns = [ 'Column 1', 'Column 2', 'Column 3' ];
    my $data    =
            [
                [ qw/Y Y Y/ ],
                [ qw/Y - Y/ ],
                [ qw/- Y -/ ],
                [ qw/- - -/ ],
            ];

    #  Standard OO form;
    my $matrix = Text::Matrix->new(
        rows    => $rows,
        columns => $columns,
        data    => $data,
        );
    print "Output:\n", $matrix->matrix();

    #Output:
    #      Column 1
    #      | Column 2
    #      | | Column 3
    #      | | |
    #      v v v
    #
    #Row A Y Y Y
    #Row B Y - Y
    #Row C - Y -
    #Row D - - -

    #  Anonymous chain form:
    print "Output:\n", Text::Matrix->columns( $columns )->rows( $rows )->
        data( $data )->matrix();

    #  Shorter but equivilent:
    print "Output:\n", Text::Matrix->matrix( $rows, $columns, $data );

    #  Paging by column width:
    $rows    = [ map { "Row $_" } ( 'A'..'D' ) ];
    $columns = [ map { "Column $_" } ( 1..20 ) ];
    $data    = [ ( [ ( 'Y' ) x @{$columns} ] ) x @{$rows} ];
    print "Output:\n<", ( '-' x 38 ), ">\n",
        Text::Matrix->max_width( 40 )->matrix( $rows, $columns, $data );

    #Output:
    #<-------------------------------------->
    #      Column 1
    #      | Column 2
    #      | | Column 3
    #      | | | Column 4
    #      | | | | Column 5
    #      | | | | | Column 6
    #      | | | | | | Column 7
    #      | | | | | | | Column 8
    #      | | | | | | | | Column 9
    #      | | | | | | | | | Column 10
    #      | | | | | | | | | | Column 11
    #      | | | | | | | | | | | Column 12
    #      | | | | | | | | | | | | Column 13
    #      | | | | | | | | | | | | |
    #      v v v v v v v v v v v v v
    #
    #Row A Y Y Y Y Y Y Y Y Y Y Y Y Y
    #Row B Y Y Y Y Y Y Y Y Y Y Y Y Y
    #Row C Y Y Y Y Y Y Y Y Y Y Y Y Y
    #Row D Y Y Y Y Y Y Y Y Y Y Y Y Y
    #
    #      Column 14
    #      | Column 15
    #      | | Column 16
    #      | | | Column 17
    #      | | | | Column 18
    #      | | | | | Column 19
    #      | | | | | | Column 20
    #      | | | | | | |
    #      v v v v v v v
    #
    #Row A Y Y Y Y Y Y Y
    #Row B Y Y Y Y Y Y Y
    #Row C Y Y Y Y Y Y Y
    #Row D Y Y Y Y Y Y Y

    #  Just want the body?
    my $sections = Text::Matrix->new(
        rows    => $rows,
        columns => $columns,
        data    => $data,
        )->body();
    print "Output:\n", @{$sections};

    #Output:
    #Row A Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y
    #Row B Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y
    #Row C Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y
    #Row D Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y

    #  Multi-character data with a map function.
    $matrix = Text::Matrix->new(
        rows    => [ qw/1 2/ ],
        columns => [ qw/A B/ ],
        data    =>
            [
                [ qw/A1 B1/ ],
                [ qw/A2 B2/ ],
            ],
        mapper  => sub { reverse( $_ ) },
        );
    print "Output:\n", $matrix->matrix();

    #Output:
    #  A
    #  |  B
    #  |  |
    #  v  v
    #
    #1 1A 1B
    #2 2A 2B

DESCRIPTION

Text::Matrix is a specialist table display module for display of matrices of single-character (such as Y/N for yes/no) or short multi-character data against row and column labels that are sufficiently longer that conventional table layouts distort the layout of the data.

The core aim is to base the layout on the tabular data concisely and formated regularly to reflect the terseness of the underlying data, without being forced to compensate for the longer length of the labels for the columns and rows.

Text::Matrix will also optionally split the matrix into several sections based on width of the generated matrix, suitable for display in situations where you don't want external line-wrapping to confuse the layout. (Display on an xterm, cut-n-paste into an email, etc.)

CONSTRUCTOR

$matrix = Text::Matrix->new( %options )

Creates and returns a new Text::Matrix object with the given options.

The options are just a wrapper around calling the method of the same name, so any of the non-output methods listed below can be used as an option.

OUTPUT METHODS

These methods all produce some part of the final output, unlike other Text::Matrix methods, these return the output rather than an instance of Text::Matrix. This means that if you're chaining methods, these must be the final stage of any chain they exist in.

$text = $matrix->matrix()
$text = $matrix->matrix( $rows, $columns, $data )
$text = Text::Matrix->matrix( $rows, $columns, $data )

Returns the text of the matrix as a string, this is what you call when you've finished configuring your matrix and want the output.

As a short-cut you can optionally specify the rows, columns and data as arguments.

You can also call matrix() as a class-method to get directly to the output without messing around with constructing a Text::Matrix object.

$sections = $matrix->body()

Returns an arrayref of body sections of the matrix layout.

The body is the row labels and the data matrix for the columns in that section.

$sections = $matrix->head()

Returns an arrayref of head sections of the matrix layout.

A head section is the column labels for the columns in that section.

$sections = $matrix->foot()

Returns an arrayref of foot sections of the matrix layout.

A foot section currently only consists of newlines to space multiple sections legibly.

METHODS

Unless otherwise noted, all methods return undef on failure and a Text::Matrix instance on success, this means that any method can be used as a constructor, and the methods can be chained if you wish to set several parameters.

$matrix->columns( $columns )
$matrix->cols( $columns )

Sets the column labels of the matrix to the given arrayref.

$matrix->rows( $rows )

Sets the row labels of the matrix to the given arrayref.

$matrix->data( $data )

Sets the data for the matrix.

$data may be an arrayref of arrayrefs with a value for each row and then column in the same order as supplied to $matrix->rows() and $matrix->columns():

    my $matrix = Text::Matrix->new(
        rows    => [ qw/1 2/ ],
        columns => [ qw/A B/ ],
        data    =>
            [
                [ qw/A1 B1/ ],
                [ qw/A2 B2/ ],
            ],
        );

$data may also be a hashref of hashrefs, keyed first by row label then by column label:

    #  Same as above.
    my $matrix = Text::Matrix->new(
        rows    => [ qw/1 2/ ],
        columns => [ qw/A B/ ],
        data    =>
            {
                1 =>
                    {
                        A => 'A1',
                        B => 'B1',
                    },
                2 =>
                    {
                        A => 'A2',
                        B => 'B2',
                    },
            },
        );

You can also combine the two as a hashref of arrayrefs or arrayref of hashrefs.

    #  Still the same as above...
    my $matrix = Text::Matrix->new(
        rows    => [ qw/1 2/ ],
        columns => [ qw/A B/ ],
        data    =>
            [
                {
                    A => 'A1',
                    B => 'B1',
                },
                {
                    A => 'A2',
                    B => 'B2',
                },
            ],
        );

    #  or...
    my $matrix = Text::Matrix->new(
        rows    => [ qw/1 2/ ],
        columns => [ qw/A B/ ],
        data    =>
            {
                1 => [ qw/A1 B1/ ],
                2 => [ qw/A2 B2/ ],
            },
        );

    #  or even this if you're insane...
    my $matrix = Text::Matrix->new(
        rows    => [ qw/1 2/ ],
        columns => [ qw/A B/ ],
        data    =>
            {
                1 => [ qw/A1 B1/ ],
                2 =>
                    {
                        A => 'A2',
                        B => 'B2',
                    },
            },
        );
$matrix->max_width( $max_width )
$matrix->max_width( undef )

Sets the maximum width, in characters, for the matrix layout.

If the matrix would exceeds this width, it will be split into multiple sections.

Setting $max_width to undef will return to the default behaviour of unlimited width.

$matrix->spacer( $spacer )
$matrix->spacer( undef )

Sets the spacer to use between matrix values.

By default a single space character is placed between values for a clear layout. If space is at a premium you can use the empty string '' as a spacer to remove spacing between values.

You could also supply multiple characters or some other string if you wished.

Setting $spacer to undef will return to the default value of ' '.

$matrix->mapper( $subref )

Sets a subroutine reference to run over each data value, substituting the returned value for the purposes of layout and output.

The data value is accessible as both $_ and $_[ 0 ].

This is a convenience function in case you're sourcing your data from DBI or something external and don't want to mess with running a map across a multi-dimensional data-structure:

    my $matrix = Text::Matrix->new(
        rows    => [ qw/1 2/ ],
        columns => [ qw/A B/ ],
        data    =>
            [
                [ qw/A1 B1/ ],
                [ qw/A2 B2/ ],
            ],
        mapper  => sub { reverse( $_ ) },
        );

SEE ALSO

Text::Table, Text::TabularDisplay, Data::ShowTable.

AUTHOR

Sam Graham, <libtext-matrix-perl BLAHBLAH illusori.co.uk>

BUGS

Please report any bugs or feature requests to bug-text-matrix at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Text-Matrix. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Text::Matrix

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2010 Sam Graham.

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