Crate xapian_rs

xapian-rs

xapian-rs provides a set of low-level, mostly-ergonomic Rust bindings for the Xapian search library.

The bindings are provided by a mix of auto-generation (via autocxx) and manual generation (via cxx). When necessary, small C++ shims are implemented to work around incompatibilities between these tools and the Xapian codebase.

Status / Stability

xapian-rs is currently immature, untested and incomplete. During the 0.x version series, no stability guarantees are provided for the API, and it may change or break at any time. A small, limited real-world use case has been implemented in pantry, which exercises an interesting but small subset of the capabilities of Xapian:

• Indexing
• Searching
• Faceting

Some functionality is not provided at this time, including (but not limited to):

• KeyMaker

Design

Where possible, xapian-rs tries to provide simple and ergonomic interactions with idiomatic Rust code. However, Xapian is a C++ codebase which uses C++ idioms, and this does have some consequences on the current design (as do limitations of the autocxx and cxx):

• Xapian primarily uses exceptions for error handling. autocxx does not currently support catching exceptions (though cxx does). In the current version, any Xapian exception will trigger a panic in Rust code. This will improve as the library evolves.
• Xapian uses C++ strings very heavily. C++ strings provide no encoding guarantees, while Rust strings are guaranteed to be valid UTF-8. These bindings currently handle this in a way that is inconsistent (though at times convenient). This will become more well-defined as the library evolves.
• Several Xapian types are exposed in a way that allows implementation via Rust traits. At present, these traits are generally implemented via &self references, and therefore interior mutability is often needed to implement interesting functionality.
• Some of these traits intentionally leak memory when passed to FFI today. This will improve as the library evolves.

Examples

Several examples are provided in the examples directory. The tests directory’s integration tests are also useful.

Structs

Database

A read-only Xapian database

DbFlags

Various flags to modify writable database behavior

DocId

A newtype wrapper representing a valid (non-zero) Xapian document ID

Document

A document in a Xapian database

ESet

An ESet represents a set of terms that may be useful for expanding the current query

Enquire

The primary interface to retrieve information from Xapian.

Expansion

An individual expansion term from an ESet, with access to position and frequency information

MSet

A list of search results with associated metadata

Match

An individual match item from the iterator yielded by MSet::matches

NumberRangeProcessor

Handle a numeric range

Position

A newtype wrapper representing a valid document position

Query

A parsed query, ready for use in a search

QueryParser

A type for building Query objects from strings

RSet

An RSet is used to hold documents marked as explicitly relevant to the current search

RangeProcessorFlags

A bitflag representation of flags supported by a RangeProcessor

Slot

A newtype wrapper representing a valid Xapian slot number (aka valueno)

Stem

An instance of a Stemming algorithm

StringRangeProcessor

Handle a string range (effectively a no-op, relying on lexical sorting)

Term

An individual term, with access to position and frequency information

TermGenerator

An instance of a Xapian TermGenerator, which can be used to index text with optional stemming

WritableDatabase

A Xapian database that can be read or written to

Enums

DbAction

A flag indicating how to handle the database already existing (or not)

DbBackend

The type of backend to use for the database

Operator

An Operator can be used to compose queries in novel ways

StemStrategy

A strategy to apply to a Stem instance

Traits

ExpandDecider

An ExpandDecider can be used to reject terms from an ESet

FieldProcessor

A FieldProcessor can be used to customize the handling of query fields

FromValue

A trait representing the ability to be loaded from a Xapian document value.

MatchDecider

A MatchDecider can be used to reject documents from an MSet

MatchSpy

A MatchSpy can be used to accumulate information seen during the match.

RangeProcessor

A RangeProcessor can be used to customize how a crate::QueryParser expands range-based queries

Stopper

Determines whether a given term matches a stopword. Stopwords are not typically indexed or included in parsed queries.

ToValue

A trait representing the ability to be stored as a Xapian document value. Useful for features such as faceting and other forms of advanced field-level filtering.