Laurent Dami

NAME

List::Categorize::Multi - A clone of List-Categorize with support for multiple subcategories.

SYNOPSIS

  use List::Categorize::Multi 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 hash.
      $_ = 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

This module is a clone of List::Categorize, with the same application programming interface, but with one additional feature : the ability to create multi-level categories. The result is a tree, labeled by categories, where intermediate nodes contain references to subtrees, and leaf nodes contain arrayrefs of elements belonging to that category.

EXPORTS

categorize

  my %tree = categorize { ... } @list;

This is the single exported function, and is exported by default.

The first argument is a coderef or a block, which will be applied to each element in @list, while aliasing $_ to the current list element ($_ can even be modified within the block).

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 always returns one single value, then the module behaves exactly like List::Categorize. If it returns an empty list, or a list containing an undef, the corresponding element is not placed in the resulting tree (again just like List::Categorize).

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).

AUTHOR

Laurent Dami, <dami at cpan.org>, with ideas and code copied from Bill Odom, <wnodom at cpan.org>.

SUPPORT

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

    perldoc List::Categorize

You can also look for information at:

COPYRIGHT & LICENSE

Copyright (c) 2013 Laurent Dami

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0