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:

Text::Query::ParseAdvanced
Text::Query::ParseSimple
The following builders are provided:

Text::Query::BuildAdvancedString
Text::Query::BuildSimpleString
The following solver is provided:

Text::Query::SolveSimpleString
Text::Query::SolveAdvancedString
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

new ([QSTRING] [OPTIONS])

        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

configure ([OPTIONS])

        Set the `parse', `build', `optimize' or `solve' packages.
        See the `CONSTRUCTOR' description for explanations.

prepare (QSTRING [OPTIONS])

        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.

match ([TARGET])

Calls the match method of the solver (-solve).

matchscalar ([TARGET])

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)