5.2 Creating Mappings

A mapping is a way to add information to candidate documents, or generate multiple candidates from a single one.

Like candidate generators, in order to create a mapping you should create a new mapping object and add it to the list p-search-candidate-mappings.

Function: p-search-candidate-mapping-create

Create a new mapping with the given keyword arguments. The following properties are available:

:id symbol

The ID symbol of the mapping. This should be the symbol that you store the mapping in. This is required in order to create mappings from preset structures.

:required-property-list prop-list

The list of properties that a document must have in order for the mapping to be used on it. This should be a list of property symbols. These are the properties that you define using p-search-def-property.

:name string

The name for the mapping that will be showed to the end user.

:input-spec spec-alist

The specification for the required inputs arguments.

:options-spec spec-alist

The specification for the options arguments.

:function mapping-function

The function which performs the mapping. This function should take two arguments, the combined input/options arguments and the document to be mapped. The function should return either the newly modified document, a list of documents, nil (meaning nothing could be done), or :remove (meaning the file document should be removed).

Function: p-search-def-field id-symbol type-symbol &rest properties-plist

Defined a new field type in p-search. Before fields are added to documetns, they should be defined with this function in order to denote their type. The id-symbol should be a unique identifier for the field type. type-symbol should be either 'text, 'category, or 'date. If the type is text, then the :weight property can be added as a numeric weight to be given to text that matches that field. The count of a match is multiplied by the weight.

Currently, the following fields are predefined and you can add them in your mapping without defining them: title (text), author (text), keywords (category), creation-date (category), modification-date (date), language (category), file-type (category).

You shouldn’t work with documents as Lisp objects, but rather use the following functions to interface with them:

Function: p-search-document-property document prop-sym

Return a specified property of the document. Properties are defined with the p-search-def-property and are normally thunked so as to not fetch all the results at once. This function calls any thunk and returns the appropriate value.

Function: p-search-document-extend document &optional new-id new-fields new-props

Take an existing document and return a new document extended with various properties. A new ID should normally be a list where the first element is the mapped document type, the second is the old ID and the third is the identifier. For example, a “narrowed” document mapping could take the form (narrow (file "~/Dowloads/file.txt") (1291 . 3012)) to mean “take another document and narrow it to 1291 and 3012” (such a mapping doesn’t currently exist).

The new-fields argument should be an alist of any new fields to be added to the document. The fields will be appended to the document and previously added fields will never be overwritten.

The new-props argument should be a an alist of any new properties to give the document. Properties given here, unlike fields, will overwrite the previous value.