view release on metacpan or  search on metacpan

lib/Docbook/Table.pm  view on Meta::CPAN

#!/usr/bin/perl -w


package Docbook::Table;

require v5.6.0;
use strict;
use warnings;
use Carp;

our $VERSION = '1.00';

=head1 NAME

Docbook::Table -- create Docbook tables from Perl data structures

=head1 SYNOPSIS

    use Docbook::Table;
    my $t = Docbook::Table->new();
    $t->title("Pet names");
    $t->headings("Pet type", "Pet name");

    my %pets = (
        dog     => "Rover",
        cat     => "Garfield",
        bird    => "Tweetie"
    );

    $t->body(\%pets);
    $t->generate;

    $t->sort(\&backwards);

=head1 DESCRIPTION

This module generates Docbook SGML/XML tables from Perl data structures.
Its main purpose is to simplify automatic document generation.

=head2 Starting your table

    use Docbook::Table;
    my $t = Docbook::Table->new();

=begin testing

BEGIN {
    use lib "./lib";
    use_ok('Docbook::Table');
    use vars qw($t);
}
$t = Docbook::Table->new();
isa_ok($t, 'Docbook::Table');

=end testing

=cut

sub new {
    my $self = {};
    $self->{calling_package} = (caller)[0];
    bless $self;
    return $self;
}

=head2 Specifying the title

Docbook tables must have a title.  You can set the title by passing a
string to the title() method.

    $t->title("This is the title");

=for testing
$t->title("foo");
is($t->{title}, "foo", "Setting title");

=cut

sub title {
    my ($self, $title) = @_;
    $self->{title} = $title;
}

=head2 Specifying the headings

Simply pass a list of headings to the headings() method.

    $t->headings(@headings);

Note that the number of columns (a required attribute of the C<tgroup>
element) is generated by counting the number of elements in the list
passed to headings().

=for testing
is($t->headings(), undef, "Set headings fails for empty list");
$t->headings(qw(foo bar baz));
is(ref($t->{headings}), "ARRAY", "Setting headings");
is($t->{headings}[0], "foo", "Setting headings");

=cut

sub headings {
    my ($self, @headings) = @_;
    unless (@headings) {
        carp "No headings specified";
        return undef;
    }
    $self->{headings} = \@headings;
}

=head2 Specifying the body

Accepted data types for the body of the table are:

=over 4

=item Simple hash

Used to generate a simple 2-column table.  

=item List of lists