Contentment::Index - Interface for Index plugin indexes
package Contentment::MyPlugin::Index; use Contentment::Catalog 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($_); }
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.
features()
Every index must define these methods:
Returns the name of the index. This should be a unique identifier for the index.
Returns a pretty name for the index.
Returns a short description of the index.
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::Catalog (and exported via the ":features" tag).
Here is a short description of each of the features. Sections following and the method sections of Contentment::Term describe the individual methods that must be defined to implement each feature.
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.
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.
Indexes with this feature are able to return a list of all possible terms.
Indexes with this feature are able to create new terms on the fly given a string name.
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 are names that alias to the same term. This way multiple strings may be used to refer to the same term.
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.
A reversible index is one for which terms may be looked up by generator.
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.
An edittable index is one that provides a standard interface for adding and removing generators to and from terms.
These methods must be defined by any index with the $SEARCH feature.
$SEARCH
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.
These methods must be defined by any index with the $LIST_TERMS feature.
$LIST_TERMS
This returns a list of term objects implementing the interface described by Contentment::Term.
These methods must be defined by any index with the $FREEFORM_TERMS feature.
$FREEFORM_TERMS
Given a string term name and a reference to a generator, the method returns a term object implementing the interface described by Contentment::Term.
No additional methods must be defined by an index with the $SUBTERMS feature.
$SUBTERMS
No additional methods must be defined by an index with the $TERM_LINKS feature.
$TERM_LINKS
No additional methods must be defined by an index with the $SYNONYMS feature.
$SYNONYMS
Quantitative terms come in one of the following string formats:
The term represents quantities that exactly match $value.
$value
The term represents quantities that are less than $value.
The term represents quantities that are greater than $value.
The term represents quantities that are less than or equal to $value.
The term represents quantities that are greater than or equal to $value.
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.
The term represents quantities that are between $min and $max or equal to $max, but not those equal to $min.
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.
$QUANTITATIVE
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::Catalog:
The quantities are integers, i.e., each value is a string of decimal digits.
The quantities are floats, i.e., they will be in a decimal point format.
The quantites are date/time values specified in ISO8601 format.
An index with the $REVERSE feature must define the following methods:
$REVERSE
Given a generator, this method will return the terms that are directly associated that generator.
An index with the $SCORE feature does not need to define any additional index methods.
$SCORE
An index with the $EDIT feature does not need to define any additional index methods.
$EDIT
Andrew Sterling Hanenkamp, <hanenkamp@cpan.org>
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.
To install Contentment, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Contentment
CPAN shell
perl -MCPAN -e shell install Contentment
For more information on module installation, please visit the detailed CPAN module installation guide.