PerlDoc

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

internal package Foswiki::Query::Node is a Foswiki::Infix::Node

A Node object is a single node in a query (either a tree node or a leaf node). A tree of node objects represents a query over the Foswiki database.

Fields are given by name, and values by strings or numbers.

A query object implements the evaluate method as its general contract with the rest of the world. This method is a "reference implementation" - it does a brute force evaluation of the expression represented by the node in a given data domain. It is expected that smarter store implementations will analyse the parse tree and derive as many optimisations as possible, minimising fallback to this brute force evaluation.

The reference implementation of evaluation uses the getField method in the {Store}{QueryAlgorithm} to get data from the store. This further decouples the query object from the detail of the store implementation.

See Foswiki::Store::QueryAlgorithms for a full spec of the interface to query algorithms.

PUBLIC %aliases

A hash mapping short aliases for META: entry names. For example, this hash maps 'form' to 'META:FORM'. Published because extensions (search implementations) have made use of it in the past, though not part of the offical API.

This hash is maintained by Foswiki::Meta and is strictly read-only

PUBLIC %isArrayType

Maps META: entry type names to true if the type is an array type (such as FIELD, ATTACHMENT or PREFERENCE). Published because extensions (search implementations) have made use of it in the past, though not part of the offical API. The type name should be given without the leading 'META:'

This hash is maintained by Foswiki::Meta and is strictly read-only

ObjectMethod evaluate(...) → $result

Evaluate this node by invoking the evaluate method of the attached operator. The return result is either an array ref (for many results) or a scalar (for a single result)

This is the reference evaluator for queries. However it may not be the only engine that evaluates them; external engines, such as SQL, might be delegated the responsibility of evaluating queries in a search context.

Name resolution depends on the context in which the name is used. A name on the LHS of the dot and where operators may only be a form name, or a META: name, referred to as a "restricted name". A name anywhere else can be a META: name, a field name, or one of the shortcuts (such as "web", "name" etc). Fields and forms are looked up by calling the getField and getForm methods in the query engine respectively.

ObjectMethod evaluatesToConstant(%opts)

Support for expression optimisation/hoisting.

Determine if this node evaluates to a constant or not. "Constant" is defined as "anything that doesn't involve actually looking in searched topics". This function takes the same parameters (%domain) as evaluate(). Note that no reference to the tom or data web or topic will be made, so you can simply pass an arbitrary Foswiki::Meta.

ObjectMethod simplify(%opts)

Simplify the query by spotting constant expressions and evaluating them, replacing the constant expression with an atomic value in the expression tree. This function takes the same parameters (%domain) as evaluate(). Note that no reference to the tom or data web or topic will be made, so you can simply pass an arbitrary Foswiki::Meta.

ObjectMethod tokens() → []

Provided for compatibility with Foswiki::Search::Node

ObjectMethod isEmpty() → $boolean

Provided for compatibility with Foswiki::Search::Node