Tested with Nyxt 2 Pre-release 7.

Upcoming versions can be built from source.
Customizing the prompt buffer

Customizing the prompt buffer

By Pierre Neidhardt

For an introduction to the prompt buffer features and background story, see our other article.

In this article, we will review the API of the prompt buffer and see how the user can leverage this to write a custom prompt buffer.

API and customization

Invocation

A prompt buffer is invoked with the prompt command. For instance, in set-url we can find:

The only required parameters are :prompt and the :sources.

Sources

Much of the prompt configuration actually happens in the sources themselves.

A source is just a class that inherits from prompter:source. For instance the aforementioned global-history-source could be defined with

The required slots are prompter:name and prompter:constructor. The latter provides a list of initial suggestions. If a list, the suggestions are immediately available. If a function, the initial suggestions are computed asynchronously, which is useful to avoid delaying the prompt display in case the initial suggestions take time to compute.

Actions

Actions are provided as a list of commands via the prompter:actions slot. The above source has one action by default. It's possible to locally extend sources when invoking a prompt. For instance, in set-url we have

Then actions is passed to the various source instantiations as in:

An action is either a well-named command, as with buffer-load, or a locally-defined command like in the previous snippet.

Some more details are needed here:

Attributes

Suggestion values are arbitrary objects: strings, numbers, URLs, structures… For compound structures, it's interesting to display the various parts of the objects (for instance, display the slots of a class).

This is where the prompter:object-attributes method comes into play. The global-history-source above lists suggestions of the history-entry type. To display something more meaninful than a bunch of

in the prompt buffer, we can specialize the aforementioned method:

Now the suggestions are printed as

https://example.org                   Example Domain
https://nyxt.atlas.engineer           Nyxt
...

and all columns are automatically aligned for you!

Filters (suggestion processing)

Whenever the user inputs a character in the prompt buffer, the suggestions of all sources are processed.

The prompter is said to be ready when all its sources are ready, that is, when the preprocessor, the filter and the postprocessor have terminated for a given user input.

Suggestion objects

Internally, when the prompter filters and sorts suggestions, it wraps the list of initial values (arbitrary objects) into suggestion objects.

It could be defined as follows:

This is useful to store information through the processing pipeline described in the previous section. For instance, the filter can calculate and store the score of each suggestion, in the score slot, which in turn is readily available to the filter-postprocessor for sorting and whatnot.

Conclusion

We hope this inspires you to write awesome configurations and, why not, extensions for Nyxt!

Thanks for reading :-)