Role::TinyCommons::Collection::SelectItems - The search_items() interface
This document describes version 0.005 of Role::TinyCommons::Collection::SelectItems (from Perl distribution Role-TinyCommons-Collection), released on 2021-05-03.
In your class:
package YourClass; use Role::Tiny::With; with 'Role::TinyCommons::Collection::SelectItems'; sub new { ... } sub select_items { ... } ... 1;
In the code of your class user:
use YourClass; my $obj = YourClass->new(...); # basic select my @results = $obj->select_items("age.min" => 20); die "There are no items matching that criteria" unless @results; # ordering # paging ## only return the first 5 results my @results = $obj->select_items("age.min" => 20, result_limit => 5); ## return the next 5 results (one-based indexing) my @results = $obj->select_items("age.min" => 20, result_limit => 5, result_start => 6);
search_items() is an interface to search (select) items in a collection based on some criteria. Some options are provided. The implementor is given flexibility to support additional options, but the basic modes of selecting must be supported.
search_items()
To do exact matching and return a single result, there is the Role::TinyCommons::Collection::FindItem interface.
Usage:
my @results = $obj->select_items(%args);
Search collection based on some criteria. Must return 0 or more results as list. Need not return the items themselves, but can (and should preferrably) return only the item ID's or some other unique attribute of the items, unless the "detail" mode is enabled, in which must return the items themselves. All matching items must be returned unless "result_limit" and "result_start" options are specified, in which case only a subset of results is returned.
Arguments:
To specify per-attribute criteria, the ATTR.OPERATOR is recommended. For example age.min specifies minimum age, while name.is specifies name to match exactly.
ATTR.OPERATOR
age.min
name.is
detail
Type: bool.
This argument should be supported for collections that have structured items.
result_limit
Type: uint. If specified, only at most this number of results should be returned. result_limit and result_start work like LIMIT clause in SQL SELECT statement.
This argument is optional to implement; if unimplemented should still return results intead of returning an error.
result_start
Type: posint (positive integer). If specified, return from the n'th result. Default if unspecified is 1, meaning to return from the first result. result_limit and result_start work like LIMIT clause in SQL SELECT statement.
This argument is optional to implement.
ignore_case
Type: bool. If set to true, must enable case-insensitive matching. Otherwise, matching should be case-sensitive.
This argument is optional to implement. It should be supported if stringwise comparison is used.
Implementor is free to add more options.
my $has_matching_item = $obj->has_matching_item(%args);
Equivalent to:
my @results = $obj->select_items(result_limit => 1, %args); return @results ? 1:0;
Name is chosen to not conflict with "has_item" in Role::TinyCommons::Collection::FindItem from Role::TinyCommons::Collection::FindItem.
my $item = $obj->select_first(%args);
Return undef (if not found) or the result (if found). Can be ambiguous if item can be undef. Equivalent to:
undef
my @results = $obj->select_items(result_limit => 1, %args); return @results ? $results[0] : undef;
Please visit the project's homepage at https://metacpan.org/release/Role-TinyCommons-Collection.
Source repository is at https://github.com/perlancar/perl-Role-TinyCommons-Collection.
Please report any bugs or feature requests on the bugtracker website https://github.com/perlancar/perl-Role-TinyCommons-Collection/issues
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.
Role::TinyCommons::Collection::FindItem
perlancar <perlancar@cpan.org>
This software is copyright (c) 2021 by 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.
To install Role::TinyCommons::Collection, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Role::TinyCommons::Collection
CPAN shell
perl -MCPAN -e shell install Role::TinyCommons::Collection
For more information on module installation, please visit the detailed CPAN module installation guide.