internal package Foswiki::Search

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

Perl Module:

Child packagesChild packages

• Foswiki::Search::InfoCache - Support package; cache of topic info. When information about search hits is compiled for output, this cache is used to avoid recovering the same info about the same topic more than once.
• Foswiki::Search::Node - Refactoring mid-step that contains a set of SEARCH tokens and options.
• Foswiki::Search::Parser - Parse SEARCH token strings into Foswiki::Search::Node objects.
• Foswiki::Search::ResultSet - This class implements the ResultSet API - its basically a Sorted Aggregate Iterator for foswiki 1.1 * NOTE: does not implement the unique function - by its nature, the data is unique, and it would be a non-trivial drain on memory in this context

internal package Foswiki::Search

This module implements all the search functionality.

ClassMethod new ($session)

Constructor for the singleton Search engine object.

ObjectMethod finish()

Break circular references.

Note to developers; please undef all fields in the object explicitly, whether they are references or not. That way this method is "golden documentation" of the live fields in the object.

ObjectMethod metacache

returns the metacache.

ObjectMethod parseSearch($searchString, $params) → Foswiki::*::Node

parses the search string and builds the appropriate nodes (uses $param->{type} to work out which parser

TODO: make parser register themselves with their type, so that we could plug in anything.

StaticMethod _isSetTrue( $value, $default ) → $boolean

Returns 1 if $value is actually set to true, and 0 otherwise.

If the value is undef, then $default is returned. If $default is not specified it is taken as 0.

ObjectMethod searchWeb (...)

Search one or more webs according to the parameters.

If _callback is set, that means the caller wants results as soon as they are ready. =_callback_ should be set to a reference to a function which takes _cbdata as the first parameter and remaining parameters the same as 'print'.

If _callback is set, the result is always undef. Otherwise the result is a string containing the rendered search results.

The function will throw Error::Simple if it encounters any problems with the syntax of the search string.

Note: If format is set, template will be ignored.

Note: For legacy, if regex is defined, it will force type='regex'

If type="word" it will be changed to type="keyword" with wordboundaries=1. This will be used for searching with scope="text" only, because scope="topic" will do a Perl search on topic names.

SMELL: If template is defined bookview will not work

SMELL: it seems that if you define _callback then you are responsible for converting the TML to HTML yourself!

FIXME: callback cannot work with format parameter (consider format='| $topic |'

ObjectMethod loadTemplates (...)

this code was extracted from searchWeb, and should probably be private.

formatResults

the implementation of

TODO: rewrite to take a resultset, a set of params? and a hash of sub's to enable evaluations of things like '$include(blah)' in format strings.

have a default set of replacements like $lt, $nop, $percnt, $dollar etc, and then the hash of subs can take care of %MACRO{}% specific complex to evaluate replacements..

(that way we don't pre-evaluate and then subst)

ObjectMethod formatResult

• $text can be undefined.
• $searchOptions is an options hash to pass on to the summary parser
• $nonTomKeys is a hash of key -> sub($key,$item) where $item is not assumed to be a topic object.
• tomKeys is a hash of {'$key' => sub($key,$item,$params) } where $item is a tom object (initially a Foswiki::Meta, but I'd like to be more generic) and $params is whatever is in trailing ()

TODO: i don't really know what we'll need to do about order of processing. TODO: at minimum, the keys need to be sorted by length so that $datatime is processed before $date TODO: need to cater for $summary(params) style too

StaticMethod displayFormField( $meta, $args, $newline ) → $text

Parse the arguments to a $formfield specification and extract the relevant formfield from the given meta data.

• args string containing name of form field
• $newline - replacement text for newlines within the form field, if not defined defaults to <br />

In addition to the name of a field args can be appended with a commas followed by a string format (\d+)([,\s*]\.\.\.)?). This supports the formatted search function $formfield and is used to shorten the returned string or a hyphenated string.