+TITLE: Prompter

This library is heavily inspired by Emacs' minibuffer and [[https://emacs-helm.github.io/helm/][Helm]]. It only deals with the backend side of things, it does not handle any display.

• Class overview

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.

[[file:example.png]]

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.

• Features

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.