A minibuffer is a complicated monster, and usually we get by copying snippets from existing code to write our minibuffer read calls. It should however be possible to document the workings of the beast in a systematic way, and dispell the mystery, so here we go.

1. minibuffer.read

The workhorse of minibuffer interaction is a coroutine called minibuffer.read. That it is a coroutine should not be intimidating to the novice — you need not necessarily understand how coroutines work in order to use them in the most common ways — only that the yield keyword is used to call them.

There are a dozen or more procedures in Conkeror with names that start with "minibuffer.read", for example minibuffer.read_file, and minibuffer.read_yes_or_no. However, most of these are simply wrappers around minibuffer.read itself, so that is the place to begin.

Minibuffer.read's behavior is controlled by keyword options. Because of the number of these options, keywords have a clear advantage over positional parameters because it results in a shortened call form, and each argument is labeled by its keyword, which makes the form easier to read than it would be otherwise. A note about keyword usage: anywhere you would give a value of boolean true for a keyword, you can simply give the keyword name with no value.

1.1. keyword options

$prompt

The prompt string.

$initial_value

The initial input text.

$select

When given and true, the initial input will be selected.

$keymap

Gives the keymap to use for the minibuffer interaction. Defaults to minibuffer_keymap. Typically if you wanted to add key bindings to a particular minibuffer prompt, you would make a keymap that inherits from minibuffer_keymap, and pass that keymap as the value for $keymap to minibuffer.read.

$history

When given, a string key name, under which the minibuffer history for this call to read will be accessed and saved.

$validator

When given, should be a function of two arguments. The first is the input string, and the second is a reference to the minibuffer. Normal exit from the minibuffer will not be permitted unless the validator function returns a true value.

$completer

So glad you asked. See below.

$match_required

When true, normal exit from the minibuffer will only be allowed when an item found in the completions is chosen.

$default_completion

When present, it must be a string found in the completions. This entry will be selected in the completions list when the input is empty. This option is only used in conjunction with $match_required.

$auto_complete

boolean or string. string values are labels that will be resolved to booleans by traversing minibuffer_auto_complete_preferences and minibuffer_auto_complete_default, which see.

When true, the completions display will pop open as soon as there are completions to display for the input. For example, you type "f" and there is a completion "foo", the completions display would pop open without you hitting tab.

$auto_complete_initial

When true, auto-completion is performed immediately when the minibuffer input is opened. Valid only when $auto_complete is also given.

$auto_complete_conservative

Normally, empty input (such as after deleting all text, or if $auto_complete_initial is given, immediately when the prompt is opened) results in a completions display of all available completions. When this option is given, empty input results in no completions. Valid only when $auto_complete is also given.

$auto_complete_delay

Delay (in milliseconds) after the most recent key-stroke before auto-completing. Defaults to value of the user variable default_minibuffer_auto_complete_delay. There is rarely any need to give this keyword.

$enable_icons

When given, space will be made in the completions display for an icon on each row. The icons are gotten from the get_icon method of the completer.

$space_completes

When true, space can be used as a completion key in addition to tab. Useful for minibuffer interactions where space never appears as a character in the allowed input. Often useful in combination with prefix_completer.

1.2. Completers

1.2.1. prefix_completer

Constructs a completer that completes based on prefix. The completion data and the procedures to interpret the items for display in the UI are given by the following keywords.

$completions

Gives either an array of items to select among, or a function for obtaining such an array, which we will come back to in a moment. The simplest case is an array of strings. You can also have an array of other types of objects, and then provide $get_string and optionally $get_description and/or $get_value.

This can also be given as a function, and it's a little bit subtle how it works, so here goes: it should be a function of one argument. The object passed to the function is itself a function, which should be called for each completion item. You could think of it as "add item".

$get_string

A procedure that takes a completion item as its argument and returns the string representation that will actually be completed upon. The default for this keyword is an identity procedure (a procedure that returns its argument unchanged).

$get_description

A procedure that takes a completion item as its argument and returns a string description, normally displayed in the column to the right of the completions. Generally used to provide extra information about the item. The default is a procedure that always returns the empty string.

$get_icon

When given, this is a procedure that takes a completion item as its argument and returns the string url of an icon to display in the completions pane for this item. Used only in combination with the minibuffer.read keyword $enable_icons.

$get_value

When given, this is a procedure that transforms the final chosen item from the completions to another value to return to the caller of minibuffer.read. Used only in combination with the minibuffer.read keyword $match_required.

1.2.2. all_word_completer

An all_word_completer allows you to match completions by typing any number of substrings, separated by spaces. The input is allowed to match either the item itself (rather its string representation) or its description.

Takes the same keyword arguments as prefix_completer.

2. readers derived from minibuffer.read

2.1. minibuffer.read_command

2.2. minibuffer.read_user_variable

2.3. minibuffer.read_preference

2.4. minibuffer.read_viewable_mime_type

2.5. minibuffer.read_explicit_option

2.6. minibuffer.read_yes_or_no

2.7. minibuffer.read_file

2.8. minibuffer.read_file_path

2.9. minibuffer.read_existing_file

2.10. minibuffer.read_directory_path

2.11. minibuffer.read_existing_directory_path

2.12. read_file_check_overwrite

3. other readers

3.1. read_single_character_option