First we will cover how you can create your own candidate generator. By now you should hopefully have a good idea about what candidate generators are.
In order for a candidate generator to be created, it needs to be added to the variable p-search-candidate-generators. Items in this list are of type p-search-candidate-generator-p. The p-search-candidate-generator is a cl-defstruct which you can create with the function p-search-candidate-generator-create. So to add a new candidate generator, you will need to create the generator object and add it to the list of known generators.
Create a candidate generator with the keyword properties. The following properties are available:
The ID symbol of the candidate generator. This should be the symbol that you store the candidate generator in. This is required in order to create candidate generators from preset structures.
The name that the user will see when selecting a candidate generator to add. This name will also appear in the p-search buffer when added. An all-caps name has been the convention, but it’s not important.
An alist specification of the generators inputs. Inputs are the required arguments, as opposed to options. Each item in the alist will be prompted for on creation of a default is not specified.
See Input/Options Specification for a full description on input/options specifications.
Similar to the :input-spec parameter, the :options-spec specifies the optional parameters that a user may specify. See Input/Options Specification for a full description on input/options specifications.
This slot provides the main functionality for the candidate generator. The function should accept one argument: the alist of arguments for inputs and options. The arguments’ keys will match that of the input and options spec. The function should return a list of document alists. This is required for the candidate generator to function.
This should be a function taking in the combined input/options alist, and return a string giving a short description of what the candidate generator is to be displayed in various places. For example, the FILESYSTEM candidate generator returns the string “FS:” plus the directory being searched on.
This function, when provided, should accept three parameters: the arguments of the candidate generator, the term being searched on, and the callback to call after the terms are counted.
The arguments are the combined inputs/outputs, similar to the other functions. The term is an Emacs regular expression form as data (see Regular Expressions in GNU Emacs Lisp Reference Manual). The callback should be called with one argument: a hashmap of document ID to term count.
This is an optional argument and if this function isn’t provided, p-search will search the contents using Elisp. The main usage of this function is to give p-search a faster way to search rather than Elisp.
This function can be defined in order to define a custom string to show when the candidate generator’s section is folded. The function should take one argument, a cons pair of candidate generator and its arguments, and should return a string to be displayed when the candidate generator is folded.
In summary, to make a new candidate generator, make a candidate generator object and store it in a defconst, then add it to the p-search-candidate-generators list. The candidate generator you create should at a minimum have a name, id, input/options specs and a function to generate documents.