This library is heavily inspired by Emacs’ minibuffer and Helm. It only deals with the backend side of things, it does not handle any display.
You can start by just creating an instance of prompter:source
(make-instance 'prompter:source
:name "Test"
:constructor '("foo" "bar"))
And passing it to the keyword argument :sources
of prompt (NOTE: prompt is a function from nyxt)
(prompt :prompt "Test prompt"
:sources (make-instance 'prompter:source
:name "Test"
:constructor '("foo" "bar")))
If you have, for example, objects that are not strings then you may need to implement the method prompter:object-attributes
which returns a list of attributes. An example:
(defmethod prompter:object-attributes ((object project) (source prompter:source))
`(("Name" ,(name object))
("Purpose" , (purpose object) nil other props)
))
The first element is the key and the second element is the value. The key has to be a string and the value can be either a string or a function that asynchronously runs and returns a string.
The attributes after the value are for application specific purposes, like format strings or code for element display, the calling code can freely use those to store arbitrary data.
The key objects are prompters
, sources
and suggestions
.
A prompt
is an interface for user interactions that holds one or more
sources
, and each of those are populated by suggestions
.
Other central concepts include:
prompt
current-suggestion
- A single
suggestion
, if any.
source
marks
- A list of
suggestions
, whenenable-marks-p
is non-nil. actions
- A list of functions that run on
suggestions
.actions-on-return
- Meant to be called over
marks
(orcurrent-suggestion
, whenenable-marks-p
is nil) when successfully returningprompt
. By default, it’s theidentity
function. actions-on-marks
- On
marks
change (event-driven). actions-on-current-suggestion
- On
current-suggestion
change (event-driven).
Example: Find below a graphical visualization of a single prompt with sources 1
and 2, and suggestions A, B, C and D. Marks
is the list composed by
Suggestions A and C. The current-suggestion
is Suggestion B.
Remarks:
When prompt
has multiple sources
, while current-suggestion
is always
defined for prompt
, it is empty for all but one of its sources
.
Marks
is a concept related to source
not prompt
, unlike that of
current-suggestion
. Thus, from the point of view of a prompt
’s object, the
marks
are the union of the marks
of each of the prompt
’s =source=s.
Non-exhaustive list of features:
- Asynchronous suggestion computation.
- Multiple sources.
- Multiple return actions.
- Customizable matching and sorting.
- Multiple attributes per suggestion.
- Customizable initialization and cleanup functions.
- Notifications sent when suggestion list is updated.
- Per-source history.
- Resumable prompters.
- Marks actions (event-driven on marks change).
- Current suggestion actions (event-driven on current suggestion change).
- Automatically return the prompt when narrowed down to a single suggestion.