• p-search

  p-search is an Emacs tool to find things. It combines concepts from information retrievial and Bayesian search theory to assist a user in finding documents.

  Documentation: https://p-search.org/documentation/

  [[./documents/screenshot.png]]

• Important Changes

  • 2025-05-31: Package names beginning with psx- have been renamed to p-search-x-

• Installation

  https://p-search.org/documentation/Installation.html

  p-search is installable via MELPA under the name p-search. You can also install it as follows:

  Using Quelpa:

  +begin_src lisp

  (quelpa '(p-search :repo "zkry/p-search" :fetcher github))

  +end_src

  Using Straight:

  +begin_src lisp

  (use-package p-search :straight (:host github :repo "zkry/p-search"))

  +end_src

  Using Elpaca:

  +begin_src lisp

  (use-package p-search :elpaca (:host github :repo "https://github.com/zkry/p-search.git"))

  +end_src

• Usage

  https://p-search.org/documentation/Getting-Started.html

  A search session can be initiated with the =p-search= command. The command will set up the session to search for files either in the projects directory (see [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Projects.html][project.el]]) if a project exists or the current directory. Execute =p-search= with the prefix ~C-u~ to instantiate an empty session.

** The p-search buffer

The p-search session is composed of three main sections: Candidate Generators, Priors, and Search Results.

[[./documents/p-search-demo-1.png]]

*** Candidate Generators

Candidate generators are the parts of the search session that
enumerate all possible search candidates.  A search candidate is
an entity with a set of key/value properties, ='content= and ='name=
being mandetory.  Other properties may exist which will allow you
to use additional prior functions.  In the p-search session run
=p-search-add-candidate-generator= (~C~)to add a new candidate generator.

You can delete a prior with the command =p-search-kill-entry-at-point=.

*** Priors

The Priors section is the part where you add search criteria to
your session.  Run =p-search-add-prior= (~P~) to add a prior function.

First you must select the type of prior you want to add.  Then you
will have to configure the prior.  It will first prompt you for
any fields that are mandetory.

After that, a new transient menu will appear, allowing you
configure the prior.  Each prior function will have its own set of
inputs and options, but each one will let you set its *importance*
and whether the *complement* should be taken.

You can delete a prior with the command =p-search-kill-entry-at-point= (~k~).

Running =p-search-explain-dwm= (~x~) with the point on a prior
will display an explanation of the prior, showing a list of the
results it has generated.

*** Calculation

Each candidate document is given a score from each prior function
depending on how well the prior function matches.

So for example, suppose you have a text query search.  The query
will rank each document on a scale from 0 to 1.  This score is
then modified by the importance.  If you assign a high importance,
then the probabilities will be pushed to the extremes. A low
importance pushes the probabilities to 0.5, thus lowering its impact.

So for example, if a text search query marked a document as highly
relevant, 0.7, but was given a low importance, its probability may
be modified to 0.55, thus lowering its impact.  On the other hand,
if a text query matches poorly giving a score of 0.3 but its
importance is low, then its probability will be raised to perhaps
0.45.

+begin_src

[CANDIDATE GENERATOR] | | [PRIOR_X] [PRIOR_Y] | |-- DOC_A -> importance_X(Score_X_A) ✖ importance_Y(Score_Y_A) | |-- DOC_B -> importance_X(Score_X_B) ✖ importance_Y(Score_Y_B) ... | --- DOC_C -> importance_X(Score_X_C) ✖ importance_Y(Score_Y_C)

+end_src

*** Text Search

Text search is a prominent component in p-search.  While text
search functions the same way as other prior functions (resulting
in a score of 0 to 1), the mecahnisms behind it are more complex.

You can create a text query by selecting "text query" in the
transient menu when running =p-search-add-prior=.

You will then be prompted for your query. Depending on the query
you write, one or more processes will be created to perform the search.

As mentioned earlier, each search candidate document has a
property ='content=.  The text search is performed on this field.
As you can probably immagine, having to search each document on a
single Emacs Lisp thread is slow, so each candidate generator
function can have a quicker method to perform the search.  This is
why you see the search tool like =:grep= or =:rg= on the FILESYSTEM
candidate generator.  When performing a text query on documents
coming from this, it will rely on this tool to perform the search.

For the text query, each search term is space separated.  So if
you type =teacher student school= it will perform three separate
searches for the three terms.  Each term will generate its own
score for each document and they will then be combined to form a
final score.  You can use quotes to group words to search
something as a whole, thus ="teacher student school"= will perform
one search with the words in a sequence.

Unquoted terms will be processed into multiple variants and
searched in parallel.  So for example =teacherStudentSchool= will
search both "teacherstudentschool" (case insensitive), but also
"teacher_student_school", "teacher-student-school" (with a lower
score), and the sepearate terms "teacher", "student", and "school"
(given even a lower score).

You can boost a term with =^= so that =teacher student^ school= will
give a boost to student.  You can also specify a numeric boost, as
in =teacher student^2 school^3=.

You can search for terms that occur near to one another with the
=(term1 term2 ...)~= syntax.  Depending on the value of
=p-search-default-near-line-length=, the items will be required to
be within a certain number of lines from one another.

** Observation :PROPERTIES: :ID: 360EC6A5-F76A-45E9-9797-F2992CE64FEC :END:

p-search will only show you the first =p-search-top-n= values of the search results. If you are not seeing relevant results you may want to consider adding search criteria. You can also run the command =p-search-observe= to lower the probability of a particular result. Doing so will lower the probability of the item by multiplying it by 0.3. With prefix =C-u p-search-observe=, you can specify the probability. After you perform the observation the probabilities will be recalculated and the results will update.

Running =p-search-explain-dwm= (~x~) with the point on a result will display an explanation of the result, showing why it was given the score it got.

** Saving Sessions

p-search contains a number of mechanims to speed up your searching process. On the one hand, you can programatically create a command and call various p-search functions to instantiate a session to your liking. On the other, simply bookmarking the session using the command =bookmark-set= (usually bound =C-x r m=) will let you save the session, candidate generators and priors, to quickly access in the future.

Another way to configure the behavior of p-search is by setting the variable =p-search-default-command-behavior=. By setitng it's value globally you can configure how the command =p-search= behaves. You can also set the variable via a ".dir-locals.el" file, like as follows, to have directory-local settings:

+begin_src lisp

((p-search-mode . ((p-search-default-command-behavior . (:candidate-generator p-search-candidate-generator-filesystem :args ((base-directory . "~/dev/go/delve/cmd")))))))

+end_src

You can run the command =p-search-show-session-preset= to see the current session represented as a Lisp object. By passing this data structure to the function =p-search-setup-buffer=, you can programatically create the p-search session that you want.

** Extensions

p-search was designed to be extensible, both in what you can search on and how the search is performed. Add =(require 'p-search-x-info)= to load a p-search extension whilch lets you search on info files.

[[./documents/psx-info-demo.gif]]

This package adds a new candidate generator for info files. The above example shows a search with two different info files.

p-search is meant to be more like a search-engine creator, rather than a search-engine for for a specifc use case. Suppose you found yourself searching the Emacs documentation often and you wanted to create a search command for this. Doing so with p-search is easy.

+begin_src lisp

(defun my/search-emacs (search-query) (interactive "sSearchs Term: ") (p-search-setup-buffer `(:group ((:prior-template p-search-prior-query :args ((query-string . ,search-query) (importance . medium))) (:candidate-generator p-search-x-info-candidate-generator :args ((info-node . emacs))) (:candidate-generator p-search-x-info-candidate-generator :args ((info-node . elisp)))))))

+end_src

The above command will search both the emacs and elisp info manuals. If you're trying to create a search command yourself and are not sure what you should pass into the =p-search-setup-buffer=, you can run the command =p-search-show-session-preset= on a p-search buffer with your desired setup to see the data representation of the search.