.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Text::Query 3"
.TH Text::Query 3 2024-07-13 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Text::Query \- Query processing framework
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&    use Text::Query;
\&    
\&    # Constructor
\&    $query = Text::Query\->new([QSTRING] [OPTIONS]);
\&
\&    # Methods
\&    $query\->prepare(QSTRING [OPTIONS]);
\&    $query\->match([TARGET]);
\&    $query\->matchscalar([TARGET]);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module provides an object that matches a data source
against a query expression.
.PP
Query expressions are compiled into an internal form when a new object is created 
or the \f(CW\*(C`prepare\*(C'\fR method is 
called; they are not recompiled on each match.
.PP
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.
.PP
The following parsers are provided:
.IP Text::Query::ParseAdvanced 4
.IX Item "Text::Query::ParseAdvanced"
.PD 0
.IP Text::Query::ParseSimple 4
.IX Item "Text::Query::ParseSimple"
.PD
.PP
The following builders are provided:
.IP Text::Query::BuildAdvancedString 4
.IX Item "Text::Query::BuildAdvancedString"
.PD 0
.IP Text::Query::BuildSimpleString 4
.IX Item "Text::Query::BuildSimpleString"
.PD
.PP
The following solver is provided:
.IP Text::Query::SolveSimpleString 4
.IX Item "Text::Query::SolveSimpleString"
.PD 0
.IP Text::Query::SolveAdvancedString 4
.IX Item "Text::Query::SolveAdvancedString"
.PD
.SH EXAMPLES
.IX Header "EXAMPLES"
.Vb 10
\&  use Text::Query;
\&  my $q=new Text::Query(\*(Aqhello and world\*(Aq,
\&                        \-parse => \*(AqText::Query::ParseAdvanced\*(Aq,
\&                        \-solve => \*(AqText::Query::SolveAdvancedString\*(Aq,
\&                        \-build => \*(AqText::Query::BuildAdvancedString\*(Aq);
\&  die "bad query expression" if not defined $q;
\&  print if $q\->match;
\&  ...
\&  $q\->prepare(\*(Aqgoodbye or adios or ta ta\*(Aq,
\&              \-litspace => 1,
\&              \-case => 1);
\&  #requires single space between the two ta\*(Aqs
\&  if($q\->match($line)) {
\&  #doesn\*(Aqt match "Goodbye"
\&  ...
\&  $q\->prepare(\*(Aq"and" or "or"\*(Aq);
\&  #quoting operators for literal match
\&  ...
\&  $q\->prepare(\*(Aq\e\ebintegrate\e\eb\*(Aq, \-regexp => 1);
\&  #won\*(Aqt match "disintegrated"
.Ve
.SH CONSTRUCTOR
.IX Header "CONSTRUCTOR"
.IP "new ([QSTRING] [OPTIONS])" 4
.IX Item "new ([QSTRING] [OPTIONS])"
This is the constructor for a new Text::Query object.  If a \f(CW\*(C`QSTRING\*(C'\fR is 
given it will be compiled to internal form.
.Sp
\&\f(CW\*(C`OPTIONS\*(C'\fR are passed in a hash like fashion, using key and value pairs.
Possible options are:
.Sp
\&\fB\-parse\fR \- Package name of the parser. Default is Text::Query::ParseSimple.
.Sp
\&\fB\-build\fR \- Package name of the builder. Default is Text::Query::Build.
.Sp
\&\fB\-optimize\fR \- Package name of the optimizer. Default is Text::Query::Optimize.
.Sp
\&\fB\-solve\fR \- Package name of the solver. Default is Text::Query::Solve.
.Sp
\&\fB\-mode\fR \- Name of predefined group of packages to use.  Options are
           currently \f(CW\*(C`simple_text\*(C'\fR and \f(CW\*(C`advanced_text\*(C'\fR.
.Sp
These options are handled by the \f(CW\*(C`configure\*(C'\fR method.
.Sp
All other options are passed to the parser \f(CW\*(C`prepare\*(C'\fR function.
See the corresponding manual pages for a description.
.Sp
If \f(CW\*(C`QSTRING\*(C'\fR is undefined, the prepare function is not called.
.Sp
The constructor will croak if a \f(CW\*(C`QSTRING\*(C'\fR was supplied and had 
illegal syntax.
.SH METHODS
.IX Header "METHODS"
.IP "configure ([OPTIONS])" 4
.IX Item "configure ([OPTIONS])"
Set the \f(CW\*(C`parse\*(C'\fR, \f(CW\*(C`build\*(C'\fR, \f(CW\*(C`optimize\*(C'\fR or \f(CW\*(C`solve\*(C'\fR packages. See the
\&\f(CW\*(C`CONSTRUCTOR\*(C'\fR description for explanations.
.IP "prepare (QSTRING [OPTIONS])" 4
.IX Item "prepare (QSTRING [OPTIONS])"
Compiles the query expression in \f(CW\*(C`QSTRING\*(C'\fR to internal form and sets any 
options (same as in the constructor).  \f(CW\*(C`prepare\*(C'\fR may be used to change 
the query expression and options for an existing query object.  If 
\&\f(CW\*(C`OPTIONS\*(C'\fR are omitted, any options set by a previous call to 
\&\f(CW\*(C`prepare\*(C'\fR are persistent.
.Sp
The optimizer (\-optimize) is called with the result of the parser (\-parse).
The parser uses the builder (\-build) to construct the internal form.
.Sp
This method returns a reference to the query object if the syntax of the 
expression was legal, or croak if not.
.IP "match ([TARGET])" 4
.IX Item "match ([TARGET])"
Calls the match method of the solver (\-solve).
.IP "matchscalar ([TARGET])" 4
.IX Item "matchscalar ([TARGET])"
Calls the matchscalar method of the solver (\-solve).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBText::Query::ParseAdvanced\fR\|(3),
\&\fBText::Query::ParseSimple\fR\|(3),
\&\fBText::Query::BuildSimpleString\fR\|(3),
\&\fBText::Query::BuildAdvanedString\fR\|(3),
\&\fBText::Query::SolveSimpleString\fR\|(3),
\&\fBText::Query::SolveAdvancedString\fR\|(3),
.PP
\&\fBText::Query::Build\fR\|(3),
\&\fBText::Query::Parse\fR\|(3),
\&\fBText::Query::Solve\fR\|(3),
\&\fBText::Query::Optimize\fR\|(3)
.SH MAINTENANCE
.IX Header "MAINTENANCE"
.IP https://github.com/jonjensen/Text\-Query 4
.IX Item "https://github.com/jonjensen/Text-Query"
.PD 0
.IP https://rt.cpan.org//Dist/Display.html?Queue=Text\-Query 4
.IX Item "https://rt.cpan.org//Dist/Display.html?Queue=Text-Query"
.PD
.SH AUTHORS
.IX Header "AUTHORS"
Eric Bohlman (ebohlman@netcom.com)
.PP
Loic Dachary (loic@senga.org)
.PP
Jon Jensen, jon@endpoint.com