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, when enable-marks-p is non-nil.

  actions

  A list of functions that run on suggestions.

  actions-on-return

  Meant to be called over marks (or current-suggestion, when enable-marks-p is nil) when successfully returning prompt. By default, it’s the identity 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.