A candidate generator needs a function to generate documents. Documents are just sets of key-value pairs. This section will cover creating documents.
There are only three properties that a candidate document must have in p-search: content, name, and id. The ID of a document is special in that it is used to determine the action to run when a document is selected. You generally shouldn’t create these by hand but instead rely on the function p-search-documentize. This function takes the documents ID and returns the full document using predefined rules. You can define such rules via the p-search-def-property function.
This function defines property property-symbol on document type id-type, using the function function on the second element of the ID.
Returns a document alist by finding all properties defined for doc-id and wrapping them in thunks to be lazily evaluated. doc-id should be a list where the first element is the document’s type, and the second element is the data which identifies the document, used as the argument to the property functions.
For example, if we make the following definition of a document type called “base”,
(p-search-def-property 'base name #'car) (p-search-def-property 'base 'content #'cdr)
then calling (p-search-documentize (base (cons "My Title" "my
content..."))) will result in a document with id of (base
(cons "My Title" "my content...")), title of "My Title"
and content of "my content...".
If we wanted to make a candidate generator for Wikipedia entries, we could make the following definition:
(p-search-def-property
'wikipedia
'name
#'identity)
(p-search-def-property
'wikipedia
'content
(lambda (wikipedia-entry-name)
(url-retrieve-synchronously
(concat "https://en.wikipedia.org/wiki/" wikipedia-entry-name))))
;; We can now create wikipedia entries with the following
(p-search-documentize '(wikipedia "Mountain_pigeon"))
⇒
((id . (wikipedia "Mountain_pigeon"))
(name . "Mountain_pigeon")
(content . "<html>..."))
Similar to p-search-def-property, this function defines a candidate result function for a given type. This is how you define actions when selecting a search result. For a file, you may want to call find-file, while for a buffer, you may want to call display-buffer.
The function p-search-goto-document is the main one you should define. For example, ‘file’ type documents have an ID in the form (file filename). The function is defined as follows:
(p-search-def-function 'file 'p-search-goto-document #'find-file-other-window)
Going off of the Wikipedia example above, we may want to define the p-search-goto-document as follows:
(p-search-def-function 'wikipedia 'p-search-goto-document
(lambda (wikipedia-entry-name)
(browse-url (concat "https://en.wikipedia.org/wiki/" wikipedia-entry-name))))