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
• Custom RangeProcessor implementations

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
• 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
• 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
• NativeRangeProcessor
  A newtype wrapper for the three primary built-in RangeProcessors.
• 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.
• 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.