Text::Query(3)

NAME
Text::Query - Query processing framework

SYNOPSIS
    use Text::Query;
    # Constructor
    $query = Text::Query->new([QSTRING] [OPTIONS]);
    # Methods
    $query->prepare(QSTRING [OPTIONS]);
    $query->match([TARGET]);
    $query->matchscalar([TARGET]);

DESCRIPTION
This module provides an object that matches a data source against a query expression.

Query expressions are compiled into an internal form when a new object is created or the `prepare' method is called; they are not recompiled on each match.

The class provided by this module uses four packages to process the query. The query parser parses the question and calls a query expression builder (internal form of the question). The optimizer is then called to reduce the complexity of the expression. The solver applies the expression on a data source.

The following parsers are provided:

The following builders are provided:

The following solver is provided:

EXAMPLES
  use Text::Query;
  my $q=new Text::Query('hello and world',
                        -parse => 'Text::Query::ParseAdvanced',
                        -solve => 'Text::Query::SolveAdvancedString',
                        -build => 'Text::Query::BuildAdvancedString');
  die "bad query expression" if not defined $q;
  print if $q->match;
  ...
  $q->prepare('goodbye or adios or ta ta',
              -litspace => 1,
              -case => 1);
  #requires single space between the two ta's
  if($q->match($line)) {
  #doesn't match "Goodbye"
  ...
  $q->prepare('"and" or "or"');
  #quoting operators for literal match
  ...
  $q->prepare('\\bintegrate\\b', -regexp => 1);
  #won't match "disintegrated"

CONSTRUCTOR
This is the constructor for a new Text::Query object. If a `QSTRING' is given it will be compiled to internal form.

`OPTIONS' are passed in a hash like fashion, using key and value pairs. Possible options are:

-parse - Package name of the parser. Default is Text::Query::ParseSimple.

-build - Package name of the builder. Default is Text::Query::Build.

-optimize - Package name of the optimizer. Default is Text::Query::Optimize.

-solve - Package name of the solver. Default is Text::Query::Solve.

-mode - Name of predefined group of packages to use. Options are
           currently `simple_text' and `advanced_text'.

These options are handled by the `configure' method.

All other options are passed to the parser `prepare' function. See the corresponding manual pages for a description.

If `QSTRING' is undefined, the prepare function is not called.

The constructor will croak if a `QSTRING' was supplied and had illegal syntax.

METHODS
Set the `parse', `build', `optimize' or `solve' packages. See the `CONSTRUCTOR' description for explanations. Compiles the query expression in `QSTRING' to internal form and sets any options (same as in the constructor). `prepare' may be used to change the query expression and options for an existing query object. If `OPTIONS' are omitted, any options set by a previous call to `prepare' are persistent.

The optimizer (-optimize) is called with the result of the parser (-parse). The parser uses the builder (-build) to construct the internal form.

This method returns a reference to the query object if the syntax of the expression was legal, or croak if not. Calls the match method of the solver (-solve). Calls the matchscalar method of the solver (-solve).

SEE ALSO
Text::Query::ParseAdvanced(3), Text::Query::ParseSimple(3), Text::Query::BuildSimpleString(3), Text::Query::BuildAdvanedString(3), Text::Query::SolveSimpleString(3), Text::Query::SolveAdvancedString(3),

Text::Query::Build(3), Text::Query::Parse(3), Text::Query::Solve(3), Text::Query::Optimize(3)

AUTHORS
Eric Bohlman (ebohlman@netcom.com)

Loic Dachary (loic@senga.org)