aboutsummaryrefslogtreecommitdiff
path: root/lib/List/Breakdown.pm
diff options
context:
space:
mode:
Diffstat (limited to 'lib/List/Breakdown.pm')
-rw-r--r--lib/List/Breakdown.pm128
1 files changed, 65 insertions, 63 deletions
diff --git a/lib/List/Breakdown.pm b/lib/List/Breakdown.pm
index 291a329..653af62 100644
--- a/lib/List/Breakdown.pm
+++ b/lib/List/Breakdown.pm
@@ -96,7 +96,7 @@ __END__
=for stopwords
sublists Unhandled tradename licensable MERCHANTABILITY hashrefs CPAN AnnoCPAN
-syntaxes
+syntaxes perldoc
=head1 NAME
@@ -106,19 +106,6 @@ List::Breakdown - Build sublist structures matching conditions
Version 0.17
-=head1 DESCRIPTION
-
-This module "breaks down" a list--filtering elements from a list into a
-specified bucket layout. It may be useful in situations where you have a big
-list of things to generate reports on, or to otherwise filter into several
-sublists.
-
-It differs from the excellent C<List::Categorize> in the use of subroutine
-references for each category and in not requiring only one final category for
-any given item; an item can end up in the result set for more than one filter.
-
-You could maybe think of this as a multi-C<grep> that returns named results.
-
=head1 SYNOPSIS
use List::Breakdown 'breakdown';
@@ -151,33 +138,53 @@ This puts the following structure in C<%filtered>:
has_ba => ['bar', 'baz'],
)
+=head1 DESCRIPTION
+
+This module assists you in making a I<breakdown> of a list, copying and
+filtering its items into a structured bucket layout according to your
+specifications. Think of it as a syntax for L<C<grep>|perlfunc/"grep BLOCK
+LIST"> that returns named and structured results from one list.
+
+It differs from the excellent L<List::Categorize|List::Categorize> in the use
+of references to define each category, and in not requiring only one final
+category for any given item; an item can end up in the result set for more than
+one filter.
+
+If you want to divide or I<partition> your list so that each item can only
+appear in one category, you may want either
+L<List::MoreUtils|List::MoreUtils/"Partitioning"> or possibly
+L<Set::Partition|Set::Partition> instead.
+
=head1 SUBROUTINES/METHODS
-=head2 B<breakdown(\%spec, @items)>
+=head2 C<breakdown(\%spec, @items)>
-Exportable subroutine; given a hash reference structure and a list of items,
-apply each of the subroutines or regular expressions given as values of the
-hash reference, returning a new hash in the same structure with the tests
-replaced with the items for which the subroutine returns true, in the same way
-as C<grep>.
+This is the only exportable subroutine. Given a hash reference structure and a
+list of items, it applies each of the referenced values as tests, returning a
+new hash in the same structure with the references replaced with the matching
+items, in the same way as L<C<grep>|perlfunc/"grep BLOCK LIST">.
-There are two shortcut syntaxes:
+There are two shortcut syntaxes for a value in the C<\%spec> structure:
=over 4
-=item *
+=item * C<ARRAY>
-If a value in the C<spec> structure is an C<ARRAY> reference with two items, it
-will be interpreted as defining bounds C<[lower,upper)> for matched values.
-C<undef> can be used to denote negative or positive infinity.
+If the referenced array has exactly two items, it will be interpreted as
+defining numeric bounds C<[lower,upper)> for its values. C<undef> can be used
+to denote negative or positive infinity. Any other number of items is a fatal
+error.
-=item *
+=item * C<Regexp>
-If it's a C<Regexp> reference, it will be interpreted as a pattern to match
-against all of the items, and will return the items that match.
+This will be interpreted as a pattern for the list items to match.
=back
+Additionally, if the value is a C<HASH> reference, it can be used to make a
+sub-part of the structure, as demonstrated in the C<length> key of the example
+C<\%spec> given in L<SYNOPSIS|/SYNOPSIS>.
+
=head1 EXAMPLES
=head2 Collecting troublesome records
@@ -193,18 +200,15 @@ imperfect Perl parser:
"RETURNING CUSTOMER Aaron Carter 2016-05-01"
);
-You could have a bucket structure like this, which catches certain error types
-you've seen before for review:
+You could have a bucket structure like this, using the B<pattern syntax>, which
+catches certain error types you've seen before for review:
my %buckets = (
bad_whitespace => qr/ [\r\t] /msx,
apostrophes => qr/ ' /msx,
double_apostrophes => qr/ '' /msx,
not_ascii => qr/ [^[:ascii:]] /msx
- );
-
-Notice that you don't have to wrap a quoted regular expression to match in a
-C<sub> subroutine reference, as a convenience shortcut.
+ };
Applying the bucket structure like so:
@@ -229,12 +233,12 @@ The result set would look like this:
);
Notice that some of the lines appear in more than one list, and that the
-C<not_ascii> bucket is empty because none of the items matched it.
+C<not_ascii> bucket is empty, because none of the items matched it.
=head2 Monitoring system check results
-Suppose you ran a list of checks with your monitoring system, and you have a
-list of hashrefs describing each check and its outcome:
+Suppose you ran a list of checks with your monitoring system, and now you have
+a list of C<HASH> references with keys describing each check and its outcome:
my @checks = (
{
@@ -255,8 +259,8 @@ list of hashrefs describing each check and its outcome:
}
);
-You would like to break the list down by status. Using C<List::Breakdown>, you
-would lay out your buckets like so:
+You would like to break the list down by status. You would lay out your buckets
+like so, using the B<subroutine syntax>:
my %buckets = (
ok => sub { $_->{status} eq 'OK' },
@@ -271,9 +275,6 @@ And apply them like so:
my %results = breakdown \%buckets, @checks;
-You can then apply C<%buckets> to any other list you may need to check in the
-same way to get the same structure.
-
For our sample data above, this would yield the following structure in
C<%results>:
@@ -305,19 +306,19 @@ C<%results>:
}
)
-Note the extra level of hash referencing beneath the C<problem> key.
+Note the extra level of C<HASH> references beneath the C<problem> key.
=head2 Grouping numbers by size
-Suppose you have a list of stray numbers from your volcanic activity reporting
-system, some of which might be merely worrisome and some an emergency, and they
-need to be filtered to know where to send them:
+Suppose you have a list of numbers from your volcanic activity reporting
+system, some of which might be merely worrisome, and some others an emergency,
+and they need to be filtered to know where to send them:
my @numbers = ( 1, 32, 3718.4, 0x56, 0777, 3.14, -5, 1.2e5 );
-You could filter them into buckets like this, using the interval syntax; an
-array reference with exactly two elements; lower bound (inclusive) first, upper
-bound (exclusive) second:
+You could filter them into buckets like this, using the B<interval syntax>: an
+C<ARRAY> reference with exactly two elements: lower bound (inclusive) first,
+upper bound (exclusive) second:
my $filters = {
negative => [ undef, 0 ],
@@ -354,20 +355,21 @@ Tom Ryder C<< <tom@sanctum.geek.nz> >>
=over 4
-=item HASH reference expected for first argument
+=item C<HASH reference expected for first argument>
-The first argument that B<breakdown()> saw wasn't the hash reference it expects.
+The first argument that C<breakdown()> saw wasn't the hash reference it expects.
That's the only format a spec is allowed to have.
-=item Reference expected for '%s'
+=item C<Reference expected for '%s'>
The value for the named key in the spec was not a reference, and one was
expected.
-=item Unhandled ref type %s for '%s'
+=item C<Unhandled ref type %s for '%s'>
The value for the named key in the spec is of a type that makes no sense to
-this module. Legal reference types are C<HASH>, C<CODE>, and C<Regexp>.
+this module. Legal reference types are C<ARRAY>, C<CODE>, C<HASH>, and
+C<Regexp>.
=back
@@ -381,15 +383,15 @@ Perl 5.6.0 or newer
=item *
-C<base>
+L<base|base>
=item *
-C<Carp>
+L<Carp|Carp>
=item *
-C<Exporter>
+L<Exporter|Exporter>
=back
@@ -408,7 +410,7 @@ requests to C<tom@sanctum.geek.nz>.
=head1 SUPPORT
-You can find documentation for this module with the C<perldoc> command.
+You can find documentation for this module with the B<perldoc> command.
perldoc List::Breakdown
@@ -418,19 +420,19 @@ You can also look for information at:
=item * RT: CPAN's request tracker (report bugs here)
-<http://rt.cpan.org/NoAuth/Bugs.html?Dist=List-Breakdown>
+L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=List-Breakdown>
=item * AnnoCPAN: Annotated CPAN documentation
-<http://annocpan.org/dist/List-Breakdown>
+L<http://annocpan.org/dist/List-Breakdown>
=item * CPAN Ratings
-<http://cpanratings.perl.org/d/List-Breakdown>
+L<http://cpanratings.perl.org/d/List-Breakdown>
=item * Search CPAN
-<http://search.cpan.org/dist/List-Breakdown/>
+L<http://search.cpan.org/dist/List-Breakdown/>
=back
@@ -442,7 +444,7 @@ This program is free software; you can redistribute it and/or modify it under
the terms of the Artistic License (2.0). You may obtain a copy of the full
license at:
-<http://www.perlfoundation.org/artistic_license_2_0>
+L<http://www.perlfoundation.org/artistic_license_2_0>
Any use, modification, and distribution of the Standard or Modified Versions is
governed by this Artistic License. By using, modifying or distributing the