Contentment::Catalog - Provides categorization and indexing features


  # Get a list of the available indexes
  my @indexes = $context->catalog->indexes;

  for my $index (@indexes) {

      # Get a list of avilable terms
      my @terms = $index->terms;

      for my $term (@terms) {

          # Get a list of generators
          my @generators = $index->generators;



One frequently controversial component of a CMS is the categorization system. Contentment attempts to avoid this problem by providing a framework for building categorization systems so that any controversy just leads to the replacement of whatever system someone doesn't like.

That is, rather than create some all encompassing categorization system or some dead-simple one that your grandma who thinks the boogey-man is going to jump out of the her CD-ROM drive can use, you can have either or both or neither depending upon your need. Thus, instead of providing a category or taxonomy system, Contentment provides the indexing system, which allows you to implement whatever category system you prefer.


Instead of trying codify how you content should be classified, this system merely codifies how a classification system works. This is done via three basic classes of objects: an Indexer, an Index, and a Term.


If you just want to use the system and you really don't care how the guts work, skip to the next section, "INDEXES".

Any implementation of a categorization system starts with an indexer. The index basically tells Contentment::Catalog what indexes are available. See Contentment::Indexer for details on implementing one.


By using the indexes() or index() method of Contentment::Catalog, you fetch all available indexes or a single named index, respectively. The purpose of the index is to describe a set of terms. The way terms are described depends on the type of index.


A term is a textual string name, which may have synonyms or other properties. It may have subterms. Primarily, a term will refer to zero or more generators.

Please see Contentment::Term for the methods a term provides.


    Register the indexer plugin, $indexer. The object given must conform to the interface documented in Contentment::Indexer.

    @indexes = $catalog->indexes

    @indexes = $catalog->indexes(@features)

    Retrieves all indexes known to the system and returns it in @indexes (which might be empty if none are registered).

    If the optional @features argument is passed, only indexes having all of the features specified will be returned:

      # Fetch all the indexes that are reversible and have subterms
      my @revsub_indexes = $context->catalog->indexes($REVERSIBLE | $SUBTERMS);

    $named_index = $catalog->index($name)

    Search for an index by name.

    @terms = $catalog->search_terms(@strings)

    Given a set of strings, this method should return an array of terms that match any of the given strings.

    If there are no matches, the method should return an empty list.

    @generators = $catalog->search(@strings)

    Given a set of strings, this method should return an array of generators linked to terms matched by any of the given strings.

    If there are no matches, the method should return an empty list.


$catalog = $context->catalog

Returns an instance of the Contentment catalog object.



The hook runs when the plugin is first initialized. The handlers are passed the context as the single argument. It is intended that plugins with indexers can use this hook to call register_indexer():

  sub my_index_registrar {
      my $ctx = shift;



This handler runs via the "Contentment::begin" hook and calls the "Contentment::Catalog::begin" hook. It also configures the context object.


Andrew Sterling Hanenkamp, <>


Copyright 2005 Andrew Sterling Hanenkamp <>. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

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.

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 105:

You can't have =items (as at line 125) unless the first thing after the =over is an =item

Around line 114:

Unknown directive: =index