4 “Term Search” Tool

If languages is a list of symbols, results will only be returned from TEI documents for which instance-language would have produced one of the symbols in the languages list. If it is a single symbol satisfying language-symbol/c, it is treated like (list languages). Otherwise, if languages is 'any (the default), documents in all languages will be searched. Use 'any rather than listing all currently-supported languages so that, when support for additional languages is added to this library, they will be included automatically.

If book/article is 'book or 'article, only results from TEI documents that would have returned the same symbol from instance-book/article will be returned. If book/article is 'any (the default), all TEI documents will be searched.

If ricoeur-only? is non-false (the default), results will only be returned from passages by Paul Ricœur. Otherwise, results from passages by editors etc. will also be included. See segment-by-ricoeur? for more details.

If exact? is #false (the default), term-search will try to find matches for lexical variants of term. The precise details of how lexical variants are matched are unspecified and depend on the specific search backend used by the corpus object. If exact? is non-false, lexical variants are ignored and only exact matches for term are returned.

A search backend specifies both the underlying search implementation to be used for functions like term-search and the strategy by which the implementation should be initialized. The actual initialization is handled either by a corpus object or by direct use of initialize-search-backend.

If the search backend is a list beginning with 'eager, the search implementation is initialized synchronously, which is especially useful for debugging. Otherwise, the search implementation is initialized in a background thread, which can provide a substantial improvement in startup time.

Values satisfying (postgresql-data-source/c) can be used as search backends.

Aside from checking that the data-source value is well-formed and contains sufficient arguments, the primary purpose of (postgresql-data-source/c) is to prevent mutation. Mutators like set-data-source-args! raise exceptions when applied to values protected by (postgresql-data-source/c). In addition, the first time (postgresql-data-source/c) encounters a given data-source value, the contract copies it (to prevent it from being mutated through another reference) and coerces any strings in the data-source-args field to immutable strings. Therefore, values protected by (postgresql-data-source/c) may not be eq? or even equal? to their originals.

4.1 Search Results

A document search result value will always contain at least one search result.

The function document-search-results-count is equivalent to (compose1 length document-search-results-results), but document-search-results-count (and the corresponding match pattern with document-search-results) is cached for efficiency of repeated calls

A search result’s excerpt may be (nothing) if there were too many results for the search term from that TEI document to return excerpts for all of them.

The trimmed-string-px part of the contract on the result of search-result-excerpt guaranties that, if the returned excerpt is not (nothing), the contained string will be non-empty and will neither start nor end with whitespace.

See also search-result-<? and search-result->?.

Sorting search results with search-result-<? will put them in the order in which they appeared in the original TEI document.

It is an error to use search-result-<? or search-result->? on search results that did not come from the same document search result value.

4.2 Searching Without a Corpus Object

A searchable document set is recognized by the predicate searchable-document-set? and can be created using initialize-search-backend, which takes a search backend, just like corpus%, and an instance set of TEI documents to be searched. (In fact, corpus% implements term-search by creating a searchable document set internally.)

As with creating an instance of corpus%, creating a new searchable document set with initialize-search-backend involves an appreciable amount of overhead, so creating redundant values should be avoided.