NAME

List::Categorize - Categorize list items into a tree of named sublists

VERSION

This documentation describes List::Categorize version 0.04.

SYNOPSIS

    use List::Categorize qw(categorize);

    my %odds_and_evens = categorize { $_ % 2 ? 'ODD' : 'EVEN' } (1..9);

    # %odds_and_evens now contains
    # ( ODD => [ 1, 3, 5, 7, 9 ], EVEN => [ 2, 4, 6, 8 ] )

    my %capitalized = categorize {

        # Transform the element before placing it in the tree.
        $_ = ucfirst $_;

        # Use the first letter of the element as the first-level category,
        # then the first 2 letters as a second-level category
        substr($_, 0, 1), substr($_, 0, 2);

    } qw( apple banana antelope bear canteloupe coyote ananas );

    # %capitalized now contains
    # (
    #   A => { An => ['Antelope', 'Ananas'], Ap => ['Apple'], },
    #   B => { Ba => ['Banana'],             Be => ['Bear'],  },
    #   C => { Ca => ['Canteloupe'],         Co => ['Coyote'] },
    # )

DESCRIPTION

A simple module that creates a tree by applying a specified rule to each element of a provided list.

EXPORT

Nothing by default.

SUBROUTINES

categorize BLOCK LIST

    my %tree = categorize { $_ > 10 ? 'Big' : 'Little' } @list;

categorize creates a tree by running BLOCK for each element in LIST. The block should return a list of "categories" for the current element, i.e a list of scalar values corresponding to the sequence of subtrees under which this element will be placed. If the block returns an empty list, or a list containing an undef, the corresponding element is not placed in the resulting tree.

The resulting tree contains a key for each top-level category. Values are either references to subtrees, or references to arrayrefs of elements (depending on the depth of the categorization).

Within the block, $_ refers to the current list element. Elements can be modified before they're placed in the target tree by modifying the $_ variable:

    my %tree = categorize { $_ = uc $_; 'List' } qw( one two three );

    # %tree now contains ( List => [ 'ONE', 'TWO', 'THREE' ] )

NOTE: The categorizer should return a list of strings, or undef. Other values are reserved for future use, and may cause unpredictable results in the current version. When using multi-level categorization, the categorizer should always return the same number of keys.

SEE ALSO

"part" in List::MoreUtils

Previous versions of this module only handled one-level categorization, while multi-level categorization was implemented in List::Categorize::Multi. Now both modules have been merged into List::Categorize, therefore List::Categorize::Multi is deprecated.

AUTHOR

Bill Odom, <wnodom at cpan.org> (original author), Laurent Dami, <dami at cpan.org> (added the multi-level categorization)

BUGS

None known.

Please report any bugs or feature requests to bug-list-categorize at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=List-Categorize.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc List::Categorize

You can also look for information at:

RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=List-Categorize

AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/List-Categorize

CPAN Ratings

http://cpanratings.perl.org/d/List-Categorize

Search MetaCPAN

https://metacpan.org/module/List::Categorize

Github repository

https://github.com/damil/List-Categorize

COPYRIGHT & LICENSE

Copyright (c) 2009 Bill Odom, 2017 Laurent Dami.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses at http://www.perlfoundation.org/artistic_license_2_0, and http://www.gnu.org/licenses/gpl-2.0.html.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

cpanm List::Categorize

perl -MCPAN -e shell
install List::Categorize