/ 
Contentment-0.011_031
River stage zero No dependents
/ Contentment::Index::Index

NAME

Contentment::Index::Index - Interface for Index plugin indexes

SYNOPSIS

package Contentment::MyPlugin::Index;

use Contentment::Index qw( :features );

# This may or may not be useful depending on the index, but we use it here
# for simplicity.
use base qw( Class::Singleton );

sub name {
    return "Contentment::MyPlugin::Index";
}

sub title {
    return "My Index";
}

sub description {
    return "It sure is a nice one.";
}

sub features {
    return $SEARCH | $LIST_TERMS;
}

sub search {
    my $self = shift;
    
    return
       map  { [ 1, $_ ] }
       grep { defined $_ }
       map  { Contentment::MyPlugin::Term->find($_) } @_;
}

sub terms {
    my $self = shift;

    return Contentment::MyPlugin::Term->list($_);
}

DESCRIPTION

An index describes an individual collection of terms. Every index must define a few methods. The index may define other methods, depending upon the value returned by the features() method.

GENERAL METHODS

Every index must define these methods:

$name = $index->name

Returns the name of the index. This should be a unique identifier for the index.

$title = $index->title

Returns a pretty name for the index.

$description = $index->description

Returns a short description of the index.

$features = $index->features

Returns a scalar value describing the features of the index and the terms the index returns. The scalar is a bit field used with numeric constants defined by Contentment::Index (and exported via the ":features" tag).

Here is a short description of each of the features. Sections following and the method sections of Contentment::Index::Term describe the individual methods that must be defined to implement each feature.

$FEATURELESS

This is the contant value indicating that the index has no features. This is pretty useless since a featureless index isn't capable of doing anything.

$SEARCH

This is probably the most basic and common feature. A searchable index allows for a simple text search to attempt to find one or more terms in an index. A search is usually aggregated across many or all available searchable indexes.

$LIST_TERMS

Indexes with this feature are able to return a list of all possible terms.

$FREEFORM_TERMS

Indexes with this feature are able to create new terms on the fly given a string name.

$SUBTERMS

An index with subterms means that a term may have a parent and may be a container terms as children.

Term links allow for showing terms related to a given term. This allows for "see also" relationships.

$SYNONYMS

Synonyms are names that alias to the same term. This way multiple strings may be used to refer to the same term.

$QUANTITATIVE

A quantitative index is one that indexes upon numbers, dates, or other quantitative elements. The index presents metadata to describe the possible ranges and types of quantities that are applicable.

$REVERSE

A reversible index is one for which terms may be looked up by generator.

$SCORE

A scored index is one for which a match need not be a boolean fact, either matched or not. Rather a scored index is one for which each match may be scored in a range.

$EDIT

An edittable index is one that provides a standard interface for adding and removing generators to and from terms.

SEARCH METHODS

These methods must be defined by any index with the $SEARCH feature.

@terms = $index->search(@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.

TERM LIST METHODS

These methods must be defined by any index with the $LIST_TERMS feature.

@terms = $index->terms

This returns a list of term objects implementing the interface described by Contentment::Index::Term.

FREEFORM METHODS

These methods must be defined by any index with the $FREEFORM_TERMS feature.

$term = $index->create_term($string, $generator)

Given a string term name and a reference to a generator, the method returns a term object implementing the interface described by Contentment::Index::Term.

SUBTERM METHODS

No additional methods must be defined by an index with the $SUBTERMS feature.

No additional methods must be defined by an index with the $TERM_LINKS feature.

SYNONYM METHODS

No additional methods must be defined by an index with the $SYNONYMS feature.

QUANTITATIVE METHODS

Quantitative terms come in one of the following string formats:

"=$value"

The term represents quantities that exactly match $value.

"<$value"

The term represents quantities that are less than $value.

">$value"

The term represents quantities that are greater than $value.

"<=$value"

The term represents quantities that are less than or equal to $value.

">=$value"

The term represents quantities that are greater than or equal to $value.

"($min-$max)"

The term represents quantities that are between $min and $max, but do not include $min and $max

"[$min-$max)"

The term represents quantities that are between $min and $max or equal to $min, but not those equal to $max.

"($min-$max]"

The term represents quantities that are between $min and $max or equal to $max, but not those equal to $min.

"[$min-$max]"

The term represents quantities that are between $min and $max or equal to $min or $max.

An index with the $QUANTITATIVE feature must define the following methods.

$type = $index->quantitative_type

This method returns the type of quantitative terms used by this index. The must be one of the following values, which are exported via the ":types" tag of Contentment::Index:

$INTEGER

The quantities are integers, i.e., each value is a string of decimal digits.

$FLOAT

The quantities are floats, i.e., they will be in a decimal point format.

$DATETIME

The quantites are date/time values specified in ISO8601 format.

REVERSIBLE METHODS

An index with the $REVERSE feature must define the following methods:

@terms = $index->for_generator($generator)

Given a generator, this method will return the terms that are directly associated that generator.

SCORED METHODS

An index with the $SCORE feature does not need to define any additional index methods.

EDIT METHODS

An index with the $EDIT feature does not need to define any additional index methods.

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.