/ 
TableData-0.2.4
River stage one • 4 direct dependents • 5 total dependents
/ TableDataRole::Spec::Basic

NAME

TableDataRole::Spec::Basic - Basic interface for all TableData::* modules

VERSION

This document describes version 0.2.4 of TableDataRole::Spec::Basic (from Perl distribution TableData), released on 2023-08-27.

DESCRIPTION

TableData::* modules let you iterate rows using a resettable iterator interface (Role::TinyCommons::Iterator::Resettable). They also let you get information about the columns.

category                     method name                note                        modifies iterator?
--------                     -----------                -------                     ------------------
instantiating                new(%args)                                             N/A

iterating rows               has_next_item()                                        no
                             has_next_row()             Alias for has_next_item()   no
                             get_next_item()                                        yes (moves forward 1 position)
                             get_next_row_arrayref()    Alias for get_next_item()   yes (moves forward 1 position)
                             get_next_row_hashref()                                 yes *moves forward 1 position)
                             reset_iterator()                                       yes (resets)

iterating rows (alt)         each_item()                                            yes (resets)
                             each_row_arrayref()        Alias for each_item()       yes (resets)
                             each_row_hashref()                                     yes (resets)

getting all rows             get_all_items()                                        yes (resets)
                             get_all_rows_arrayref()    Alias for get_all_items()   yes (resets)
                             get_all_rows_hashref()                                 yes (resets)

getting row count            get_item_count()                                       yes (resets) / no (for some implementations)
                             get_row_count()            Alias for get_item_count()  yes (resets) / no (for some implementations)

getting column information   get_column_names()                                     no
                             get_column_count()                                     no

REQUIRED METHODS

new

Usage:

my $table = TableData::Foo->new([ %args ]);

Constructor. Must accept a pair of argument names and values.

has_next_item

Usage:

$table->has_next_item; # bool

Must return true if table has next row when iterating, false otherwise.

From Role::TinyCommons::Iterator::Resettable.

reset_iterator

Usage:

$table->reset_iterator;

Reset iterator so that the next "get_next_item" retrieves the first row.

From Role::TinyCommons::Iterator::Resettable.

get_iterator_pos

Usage:

$table->get_iterator_pos;

Get iterator position.

From Role::TinyCommons::Iterator::Resettable.

get_next_item

Usage:

my $row_arrayref = $table->get_next_item;

Must return the next row as arrayref. See also "get_next_row_hashref".

get_next_row_hashref

Usage:

my $row_hashref = $table->get_next_row_hashref;

Must return the next row as arrayref. See also "get_next_row_arrayref" (a.k.a. "get_next_item").

get_column_count

Usage:

my $n = $table->get_column_count;

Must return the number of columns of the table.

All tables must have finite number of columns.

Should not reset iterator.

get_column_names

Usage:

my @colnames = $table->get_column_names;
my $colnames = $table->get_column_names;

Must return a list (or arrayref) containing the names of columns, ordered. For ease of use, when in list context the method must return a list, and in scalar context must return an arrayref.

Should not reset iterator.

PROVIDED METHODS

get_item_count

Usage:

my $count = $table->get_item_count;

Return the number of data rows in the table. Resets the row iterator (see "get_row_arrayref" and "reset_iterator").

A table with infinite data rows can return -1.

The default implementation will call "reset_iterator", call "has_next_item" and "get_next_item" repeatedly until there is no more row, then return the counted number of rows. If your source data is already in an array or some other form where the count is easily known, you can replace the implementation with a more efficient one.

get_row_count

Alias for "get_item_count".

has_next_row

Alias for "has_next_item".

get_next_row_arrayref

Alias for "get_next_item".

get_all_items

Usage:

my @rows = $table->get_all_items;

Return all rows as a list of arrayrefs. Resets the row iterator. Basically shortcut for:

my @rows;
$table->reset_iterator;
while ($table->has_next_item) {
    push @rows, $table->get_next_item;
}
@rows;

You can provide a more efficient implementation if your source data allows it.

A table with infinite data rows can throw an exception if this method is called.

get_all_rows_arrayref

Alias for "get_all_items".

get_all_rows_hashref

Usage:

my @rows = $table->get_all_rows_hashref;

Return all rows as a list of hashrefs. Resets the row iterator. Basically shortcut for:

my @rows;
$table->reset_iterator;
while ($table->has_next_item) {
    push @rows, $table->get_next_row_hashref;
}
@rows;

You can provide a more efficient implementation if your source data allows it.

A table with infinite data rows can throw an exception if this method is called.

each_item

Usage:

$table->each_item($coderef);

Call $coderef for each row. If $coderef returns false, will immediately return false and skip the rest of the rows. Otherwise, will return true. Basically:

$table->reset_iterator;
my $index = 0;
while ($table->has_next_item) {
    my $row = $table->get_next_item;
    my $res = $coderef->($row, $table, $index);
    return 0 unless $res;
    $index++;
}
return 1;

See also "each_row_hashref".

each_row_arrayref

Alias for "each_item".

each_row_hashref

Usage:

$table->each_row_hashref($coderef);

Call $coderef for each row. If $coderef returns false, will immediately return false and skip the rest of the rows. Otherwise, will return true. Basically:

$table->reset_iterator;
my $index = 0;
while ($table->has_next_item) {
    my $row = $table->get_next_row_hashref;
    my $res = $coderef->($row, $table, $index);
    return 0 unless $res;
    $index++;
}
return 1;

See also "each_row_arrayref" (a.k.a. "each_item").

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/TableData.

SOURCE

Source repository is at https://github.com/perlancar/perl-TableData.

SEE ALSO

AUTHOR

perlancar <perlancar@cpan.org>

CONTRIBUTING

To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

% prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

This software is copyright (c) 2023, 2022, 2021, 2020 by perlancar <perlancar@cpan.org>.

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

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=TableData

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.