.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" 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" '' '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 turned on, 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. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" 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 "Xapian 3pm" .TH Xapian 3pm "2012-05-09" "perl v5.14.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" Search::Xapian \- Perl XS frontend to the Xapian C++ search library. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Search::Xapian; \& \& my $db = Search::Xapian::Database\->new( \*(Aq[DATABASE DIR]\*(Aq ); \& my $enq = $db\->enquire( \*(Aq[QUERY TERM]\*(Aq ); \& \& printf "Running query \*(Aq%s\*(Aq\en", $enq\->get_query()\->get_description(); \& \& my @matches = $enq\->matches(0, 10); \& \& print scalar(@matches) . " results found\en"; \& \& foreach my $match ( @matches ) { \& my $doc = $match\->get_document(); \& printf "ID %d %d%% [ %s ]\en", $match\->get_docid(), $match\->get_percent(), $doc\->get_data(); \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module wraps most methods of most Xapian classes. The missing classes and methods should be added in the future. It also provides a simplified, more 'perlish' interface to some common operations, as demonstrated above. .PP There are some gaps in the \s-1POD\s0 documentation for wrapped classes, but you can read the Xapian \*(C+ \s-1API\s0 documentation at for details of these. Alternatively, take a look at the code in the examples and tests. .PP If you want to use Search::Xapian and the threads module together, make sure you're using Search::Xapian >= 1.0.4.0 and Perl >= 5.8.7. As of 1.0.4.0, Search::Xapian uses \s-1CLONE_SKIP\s0 to make sure that the perl wrapper objects aren't copied to new threads \- without this the underlying \*(C+ objects can get destroyed more than once. .PP If you encounter problems, or have any comments, suggestions, patches, etc please email the Xapian-discuss mailing list (details of which can be found at ). .SS "\s-1EXPORT\s0" .IX Subsection "EXPORT" None by default. .SH ":db" .IX Header ":db" .IP "\s-1DB_OPEN\s0" 4 .IX Item "DB_OPEN" Open a database, fail if database doesn't exist. .IP "\s-1DB_CREATE\s0" 4 .IX Item "DB_CREATE" Create a new database, fail if database exists. .IP "\s-1DB_CREATE_OR_OPEN\s0" 4 .IX Item "DB_CREATE_OR_OPEN" Open an existing database, without destroying data, or create a new database if one doesn't already exist. .IP "\s-1DB_CREATE_OR_OVERWRITE\s0" 4 .IX Item "DB_CREATE_OR_OVERWRITE" Overwrite database if it exists. .SH ":ops" .IX Header ":ops" .IP "\s-1OP_AND\s0" 4 .IX Item "OP_AND" Match if both subqueries are satisfied. .IP "\s-1OP_OR\s0" 4 .IX Item "OP_OR" Match if either subquery is satisfied. .IP "\s-1OP_AND_NOT\s0" 4 .IX Item "OP_AND_NOT" Match if left but not right subquery is satisfied. .IP "\s-1OP_XOR\s0" 4 .IX Item "OP_XOR" Match if left or right, but not both queries are satisfied. .IP "\s-1OP_AND_MAYBE\s0" 4 .IX Item "OP_AND_MAYBE" Match if left is satisfied, but use weights from both. .IP "\s-1OP_FILTER\s0" 4 .IX Item "OP_FILTER" Like \s-1OP_AND\s0, but only weight using the left query. .IP "\s-1OP_NEAR\s0" 4 .IX Item "OP_NEAR" Match if the words are near each other. The window should be specified, as a parameter to \f(CW\*(C`Search::Xapian::Query::Query\*(C'\fR, but it defaults to the number of terms in the list. .IP "\s-1OP_PHRASE\s0" 4 .IX Item "OP_PHRASE" Match as a phrase (All words in order). .IP "\s-1OP_ELITE_SET\s0" 4 .IX Item "OP_ELITE_SET" Select an elite set from the subqueries, and perform a query with these combined as an \s-1OR\s0 query. .IP "\s-1OP_VALUE_RANGE\s0" 4 .IX Item "OP_VALUE_RANGE" Filter by a range test on a document value. .SH ":qpflags" .IX Header ":qpflags" .IP "\s-1FLAG_DEFAULT\s0" 4 .IX Item "FLAG_DEFAULT" This gives the QueryParser default flag settings, allowing you to easily add flags to the default ones. .IP "\s-1FLAG_BOOLEAN\s0" 4 .IX Item "FLAG_BOOLEAN" Support \s-1AND\s0, \s-1OR\s0, etc and bracketed subexpressions. .IP "\s-1FLAG_LOVEHATE\s0" 4 .IX Item "FLAG_LOVEHATE" Support + and \-. .IP "\s-1FLAG_PHRASE\s0" 4 .IX Item "FLAG_PHRASE" Support quoted phrases. .IP "\s-1FLAG_BOOLEAN_ANY_CASE\s0" 4 .IX Item "FLAG_BOOLEAN_ANY_CASE" Support \s-1AND\s0, \s-1OR\s0, etc even if they aren't in \s-1ALLCAPS\s0. .IP "\s-1FLAG_WILDCARD\s0" 4 .IX Item "FLAG_WILDCARD" Support right truncation (e.g. Xap*). .IP "\s-1FLAG_PURE_NOT\s0" 4 .IX Item "FLAG_PURE_NOT" Allow queries such as '\s-1NOT\s0 apples'. .Sp These require the use of a list of all documents in the database which is potentially expensive, so this feature isn't enabled by default. .IP "\s-1FLAG_PARTIAL\s0" 4 .IX Item "FLAG_PARTIAL" Enable partial matching. .Sp Partial matching causes the parser to treat the query as a \&\*(L"partially entered\*(R" search. This will automatically treat the final word as a wildcarded match, unless it is followed by whitespace, to produce more stable results from interactive searches. .IP "\s-1FLAG_SPELLING_CORRECTION\s0" 4 .IX Item "FLAG_SPELLING_CORRECTION" .PD 0 .IP "\s-1FLAG_SYNONYM\s0" 4 .IX Item "FLAG_SYNONYM" .IP "\s-1FLAG_AUTO_SYNONYMS\s0" 4 .IX Item "FLAG_AUTO_SYNONYMS" .IP "\s-1FLAG_AUTO_MULTIWORD_SYNONYMS\s0" 4 .IX Item "FLAG_AUTO_MULTIWORD_SYNONYMS" .PD .SH ":qpstem" .IX Header ":qpstem" .IP "\s-1STEM_ALL\s0" 4 .IX Item "STEM_ALL" Stem all terms. .IP "\s-1STEM_NONE\s0" 4 .IX Item "STEM_NONE" Don't stem any terms. .IP "\s-1STEM_SOME\s0" 4 .IX Item "STEM_SOME" Stem some terms, in a manner compatible with Omega (capitalised words and those in phrases aren't stemmed). .SH ":enq_order" .IX Header ":enq_order" .IP "\s-1ENQ_ASCENDING\s0" 4 .IX Item "ENQ_ASCENDING" docids sort in ascending order (default) .IP "\s-1ENQ_DESCENDING\s0" 4 .IX Item "ENQ_DESCENDING" docids sort in descending order .IP "\s-1ENQ_DONT_CARE\s0" 4 .IX Item "ENQ_DONT_CARE" docids sort in whatever order is most efficient for the backend .SH ":standard" .IX Header ":standard" Standard is db + ops + qpflags + qpstem .SH "Version functions" .IX Header "Version functions" .IP "major_version" 4 .IX Item "major_version" Returns the major version of the Xapian \*(C+ library being used. E.g. for Xapian 1.0.9 this would return 1. .IP "minor_version" 4 .IX Item "minor_version" Returns the minor version of the Xapian \*(C+ library being used. E.g. for Xapian 1.0.9 this would return 0. .IP "revision" 4 .IX Item "revision" Returns the revision of the Xapian \*(C+ library being used. E.g. for Xapian 1.0.9 this would return 9. In a stable release series, Xapian libraries with the same minor and major versions are usually \s-1ABI\s0 compatible, so this often won't match the third component of \f(CW$Search::Xapian::VERSION\fR (which is the version of the Search::Xapian \s-1XS\s0 wrappers). .SH "Numeric encoding functions" .IX Header "Numeric encoding functions" .IP "sortable_serialise \s-1NUMBER\s0" 4 .IX Item "sortable_serialise NUMBER" Convert a floating point number to a string, preserving sort order. .Sp This method converts a floating point number to a string, suitable for using as a value for numeric range restriction, or for use as a sort key. .Sp The conversion is platform independent. .Sp The conversion attempts to ensure that, for any pair of values supplied to the conversion algorithm, the result of comparing the original values (with a numeric comparison operator) will be the same as the result of comparing the resulting values (with a string comparison operator). On platforms which represent doubles with the precisions specified by \s-1IEEE_754\s0, this will be the case: if the representation of doubles is more precise, it is possible that two very close doubles will be mapped to the same string, so will compare equal. .Sp Note also that both zero and \-zero will be converted to the same representation: since these compare equal, this satisfies the comparison constraint, but it's worth knowing this if you wish to use the encoding in some situation where this distinction matters. .Sp Handling of NaN isn't (currently) guaranteed to be sensible. .IP "sortable_unserialise \s-1SERIALISED_NUMBER\s0" 4 .IX Item "sortable_unserialise SERIALISED_NUMBER" Convert a string encoded using sortable_serialise back to a floating point number. .Sp This expects the input to be a string produced by \fIsortable_serialise()\fR. If the input is not such a string, the value returned is undefined (but no error will be thrown). .Sp The result of the conversion will be exactly the value which was supplied to \fIsortable_serialise()\fR when making the string on platforms which represent doubles with the precisions specified by \s-1IEEE_754\s0, but may be a different (nearby) value on other platforms. .SH "TODO" .IX Header "TODO" .IP "Error Handling" 4 .IX Item "Error Handling" Error handling for all methods liable to generate them. .IP "Documentation" 4 .IX Item "Documentation" Add \s-1POD\s0 documentation for all classes, where possible just adapted from Xapian docs. .IP "Unwrapped classes" 4 .IX Item "Unwrapped classes" The following Xapian classes are not yet wrapped: Error (and subclasses), ErrorHandler, standard ExpandDecider subclasses (user-defined ones works), user-defined weight classes. .Sp We don't yet wrap Xapian::Query::MatchAll, Xapian::Query::MatchNothing, or Xapian::BAD_VALUENO. .IP "Unwrapped methods" 4 .IX Item "Unwrapped methods" The following methods are not yet wrapped: Enquire::get_eset(...) with more than two arguments, Query ctor optional \*(L"parameter\*(R" parameter, Remote::open(...), static \fIStem::get_available_languages()\fR. .Sp We wrap \fIMSet::swap()\fR and MSet::operator[](), but not \fIESet::swap()\fR, ESet::operator[](). Is swap actually useful? Should we instead tie MSet and ESet to allow them to just be used as lists? .SH "CREDITS" .IX Header "CREDITS" Thanks to Tye McQueen for explaining the finer points of how best to write \s-1XS\s0 frontends to \*(C+ libraries, James Aylett for clarifying the less obvious aspects of the Xapian \s-1API\s0, Tim Brody for patches wrapping ::QueryParser and ::Stopper and especially Olly Betts for contributing advice, bugfixes, and wrapper code for the more obscure classes. .SH "AUTHOR" .IX Header "AUTHOR" Alex Bowley .PP Please report any bugs/suggestions to or use the Xapian bug tracker . Please do \&\s-1NOT\s0 use the \s-1CPAN\s0 bug tracker or mail any of the authors individually. .SH "SEE ALSO" .IX Header "SEE ALSO" Search::Xapian::BM25Weight, Search::Xapian::BoolWeight, Search::Xapian::Database, Search::Xapian::Document, Search::Xapian::Enquire, Search::Xapian::MultiValueSorter, Search::Xapian::PositionIterator, Search::Xapian::PostingIterator, Search::Xapian::QueryParser, Search::Xapian::Stem, Search::Xapian::TermGenerator, Search::Xapian::TermIterator, Search::Xapian::TradWeight, Search::Xapian::ValueIterator, Search::Xapian::Weight, Search::Xapian::WritableDatabase, and .