NAME

Contentment::Index - Provides categorization and indexing features

SYNOPSIS

  # Get a list of the available indexes
  my @indexes = Contentment::Index->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;

      }
      
  }

DESCRIPTION

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.

HOW DOES IT WORK?

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.

INDEXERS

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::Index what indexes are available. See Contentment::Index::Indexer for details on implementing one.

INDEXES

By using the indexes() or index() method of Contentment::Index, 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.

TERMS

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::Index::Term for the methods a term provides.

METHODS

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

@indexes = Contentment::Index->indexes

@indexes = Contentment::Index->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 = Contentment::Index->indexes($REVERSIBLE | $SUBTERMS);

$index = Contentment::Index->index($name)

Search for an index by name.

@terms = Contentment::Index->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 = Contentment::Index->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.

HOOKS

Contentment::Index::begin

The hook runs when the plugin is first initialized. The handlers are passed no arguments. It is intended that plugins with indexers can use this hook to call register_index().

HOOK HANDLERS

Contentment::Index::begin

This handler runs via the "Contentment::begin" hook and calls the "Contentment::Index::begin" hook.

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@cpan.org>

LICENSE AND COPYRIGHT

Copyright 2005 Andrew Sterling Hanenkamp <hanenkamp@cpan.org>. 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.