#+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 to match and display (also known as "multiple column
  display" like =helm-find-files=).
- 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.
