NAME
TableDataRole::Spec::Basic - Basic interface for all TableData::* modules
VERSION
This document describes version 0.2.3 of TableDataRole::Spec::Basic (from Perl distribution TableData), released on 2023-04-19.
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
-------- ----------- -------
instantiating new(%args)
iterating rows has_next_item()
has_next_row() Alias for has_next_item()
get_next_item()
get_next_row_arrayref() Alias for get_next_item()
get_next_row_hashref()
reset_iterator()
iterating rows (alt) each_item()
each_row_arrayref() Alias for each_item()
each_row_hashref()
getting all rows get_all_items()
get_all_rows_arrayref() Alias for get_all_items()
get_all_rows_hashref()
getting column information get_column_names()
get_column_count()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; # boolMust 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.
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.
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 -lIf 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.