.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Lucy::Search::QueryParser 3pm"
.TH Lucy::Search::QueryParser 3pm "2017-08-02" "perl v5.26.0" "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"
Lucy::Search::QueryParser \- Transform a string into a Query object.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&    my $query_parser = Lucy::Search::QueryParser\->new(
\&        schema => $searcher\->get_schema,
\&        fields => [\*(Aqbody\*(Aq],
\&    );
\&    my $query = $query_parser\->parse( $query_string );
\&    my $hits  = $searcher\->hits( query => $query );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
QueryParser accepts search strings as input and produces
Lucy::Search::Query objects, suitable for feeding into
IndexSearcher and other
Searcher subclasses.
.PP
The following syntactical constructs are recognized by QueryParser:
.PP
.Vb 6
\&    * Boolean operators \*(AqAND\*(Aq, \*(AqOR\*(Aq, and \*(AqAND NOT\*(Aq.
\&    * Prepented +plus and \-minus, indicating that the labeled entity
\&      should be either required or forbidden \-\- be it a single word, a
\&      phrase, or a parenthetical group.
\&    * Logical groups, delimited by parentheses.
\&    * Phrases, delimited by double quotes.
.Ve
.PP
Additionally, the following syntax can be enabled via \fIset_heed_colons()\fR:
.PP
.Vb 3
\&    * Field\-specific constructs, in the form of \*(Aqfieldname:termtext\*(Aq or
\&      \*(Aqfieldname:(foo bar)\*(Aq.  (The field specified by \*(Aqfieldname:\*(Aq will be
\&      used instead of the QueryParser\*(Aqs default fields).
.Ve
.SH "CONSTRUCTORS"
.IX Header "CONSTRUCTORS"
.SS "new( \fI[labeled params]\fP )"
.IX Subsection "new( [labeled params] )"
.Vb 6
\&    my $query_parser = Lucy::Search::QueryParser\->new(
\&        schema         => $searcher\->get_schema,    # required
\&        analyzer       => $analyzer,                # overrides schema
\&        fields         => [\*(Aqbodytext\*(Aq],             # default: indexed fields
\&        default_boolop => \*(AqAND\*(Aq,                    # default: \*(AqOR\*(Aq
\&    );
.Ve
.PP
Constructor.
.IP "\(bu" 4
\&\fBschema\fR \- A Schema.
.IP "\(bu" 4
\&\fBanalyzer\fR \- An Analyzer.
Ordinarily, the analyzers specified by each field's definition will be
used, but if \f(CW\*(C`analyzer\*(C'\fR is supplied, it will override and be used for
all fields.  This can lead to mismatches between what is in the index
and what is being searched for, so use caution.
.IP "\(bu" 4
\&\fBfields\fR \- The names of the fields which will be searched against.
Defaults to those fields which are defined as indexed in the supplied
Schema.
.IP "\(bu" 4
\&\fBdefault_boolop\fR \- Two possible values: '\s-1AND\s0' and '\s-1OR\s0'.  The default
is '\s-1OR\s0', which means: return documents which match any of the query
terms.  If you want only documents which match all of the query terms,
set this to '\s-1AND\s0'.
.SH "METHODS"
.IX Header "METHODS"
.SS "parse(query_string)"
.IX Subsection "parse(query_string)"
Build a Query object from the contents of a query string.  At present,
implemented internally by calling \fItree()\fR, \fIexpand()\fR, and \fIprune()\fR.
.IP "\(bu" 4
\&\fBquery_string\fR \- The string to be parsed.  May be undef.
.PP
Returns: a Query.
.SS "tree(query_string)"
.IX Subsection "tree(query_string)"
Parse the logical structure of a query string, building a tree
comprised of Query objects.  Leaf nodes in the tree will most often be
LeafQuery objects but might be MatchAllQuery or NoMatchQuery objects as
well.  Internal nodes will be objects which subclass PolyQuery:
ANDQuery, ORQuery, NOTQuery, and RequiredOptionalQuery.
.PP
The output of \fItree()\fR is an intermediate form which must be passed
through \fIexpand()\fR before being used to feed a search.
.IP "\(bu" 4
\&\fBquery_string\fR \- The string to be parsed.
.PP
Returns: a Query.
.SS "expand(query)"
.IX Subsection "expand(query)"
Walk the hierarchy of a Query tree, descending through all PolyQuery
nodes and calling \fIexpand_leaf()\fR on any LeafQuery nodes encountered.
.IP "\(bu" 4
\&\fBquery\fR \- A Query object.
.PP
Returns: A Query \*(-- usually the same one that was supplied after
in-place modification, but possibly another.
.SS "expand_leaf(query)"
.IX Subsection "expand_leaf(query)"
Convert a LeafQuery into either a TermQuery, a PhraseQuery, or an
ORQuery joining multiple TermQueries/PhraseQueries to accommodate
multiple fields.  LeafQuery text will be passed through the relevant
Analyzer for each field.  Quoted text will be transformed into
PhraseQuery objects.  Unquoted text will be converted to either a
TermQuery or a PhraseQuery depending on how many tokens are generated.
.IP "\(bu" 4
\&\fBquery\fR \- A Query.  Only LeafQuery objects will be processed; others
will be passed through.
.PP
Returns: A Query.
.SS "prune(query)"
.IX Subsection "prune(query)"
Prevent certain Query structures from returning too many results.
Query objects built via \fItree()\fR and \fIexpand()\fR can generate \*(L"return the
world\*(R" result sets, such as in the case of
\&\f(CW\*(C`NOT a_term_not_in_the_index\*(C'\fR; \fIprune()\fR walks the hierarchy
and eliminates such branches.
.PP
.Vb 3
\&     \*(AqNOT foo\*(Aq               => [NOMATCH]
\&     \*(Aqfoo OR NOT bar\*(Aq        => \*(Aqfoo\*(Aq
\&     \*(Aqfoo OR (\-bar AND \-baz) => \*(Aqfoo\*(Aq
.Ve
.PP
\&\fIprune()\fR also eliminates some double-negative constructs \*(-- even though
such constructs may not actually return the world:
.PP
.Vb 1
\&     \*(Aqfoo AND \-(\-bar)\*(Aq      => \*(Aqfoo\*(Aq
.Ve
.PP
In this example, safety is taking precedence over logical consistency.
If you want logical consistency instead, call \fItree()\fR then \fIexpand()\fR,
skipping \fIprune()\fR.
.IP "\(bu" 4
\&\fBquery\fR \- A Query.
.PP
Returns: a Query; in most cases, the supplied Query after in-place
modification.
.SS "set_heed_colons(heed_colons)"
.IX Subsection "set_heed_colons(heed_colons)"
Enable/disable parsing of \f(CW\*(C`fieldname:foo\*(C'\fR constructs.
.SS "make_term_query( \fI[labeled params]\fP )"
.IX Subsection "make_term_query( [labeled params] )"
Factory method creating a TermQuery.
.IP "\(bu" 4
\&\fBfield\fR \- Field name.
.IP "\(bu" 4
\&\fBterm\fR \- Term text.
.PP
Returns: A Query.
.SS "make_phrase_query( \fI[labeled params]\fP )"
.IX Subsection "make_phrase_query( [labeled params] )"
Factory method creating a PhraseQuery.
.IP "\(bu" 4
\&\fBfield\fR \- Field that the phrase must occur in.
.IP "\(bu" 4
\&\fBterms\fR \- Ordered array of terms that must match.
.PP
Returns: A Query.
.SS "make_and_query(children)"
.IX Subsection "make_and_query(children)"
Factory method creating an ANDQuery.
.IP "\(bu" 4
\&\fBchildren\fR \- Array of child Queries.
.PP
Returns: A Query.
.SS "make_or_query(children)"
.IX Subsection "make_or_query(children)"
Factory method creating an ORQuery.
.IP "\(bu" 4
\&\fBchildren\fR \- Array of child Queries.
.PP
Returns: A Query.
.SS "make_not_query(negated_query)"
.IX Subsection "make_not_query(negated_query)"
Factory method creating a NOTQuery.
.IP "\(bu" 4
\&\fBnegated_query\fR \- Query to be inverted.
.PP
Returns: A Query.
.SS "make_req_opt_query( \fI[labeled params]\fP )"
.IX Subsection "make_req_opt_query( [labeled params] )"
Factory method creating a RequiredOptionalQuery.
.IP "\(bu" 4
\&\fBrequired_query\fR \- Query must must match.
.IP "\(bu" 4
\&\fBoptional_query\fR \- Query which should match.
.PP
Returns: A Query.
.SH "INHERITANCE"
.IX Header "INHERITANCE"
Lucy::Search::QueryParser isa Lucy::Object::Obj.