.\" Automatically generated by Pandoc 2.2.1
.\"
.TH "elvish\-edit" "7" "Feb 08, 2019" "Elvish 0.12" "Miscellaneous Information Manual"
.hy
.PP
The \f[C]edit:\f[] module is the interface to the Elvish editor.
.PP
Function usages are given in the same format as in the reference for the
builtin module (/ref/builtin.html).
.PP
\f[I]This document is incomplete.\f[]
.SH Overview
.SS Modes and Submodules
.PP
The Elvish editor has different \f[B]modes\f[], and exactly one mode is
active at the same time.
Each mode has its own UI and keybindings.
For instance, the default \f[B]insert mode\f[] lets you modify the
current command.
The \f[B]completion mode\f[] (triggered by Tab by default) shows you all
candidates for completion, and you can use arrow keys to navigate those
candidates.
.PP
$ttyshot completion\-mode
.PP
Each mode has its own submodule under \f[C]edit:\f[].
For instance, builtin functions and configuration variables for the
completion mode can be found in the \f[C]edit:completion:\f[] module.
.PP
The primary modes supported now are \f[C]insert\f[],
\f[C]completion\f[], \f[C]navigation\f[], \f[C]history\f[],
\f[C]histlist\f[], \f[C]location\f[], and \f[C]lastcmd\f[].
The last 4 are "listing modes", and their particularity is documented
below.
.SH Prompts
.PP
Elvish has two prompts: the (normal) left\-hand prompt and the
right\-side prompt (rprompt).
Most of this section only documents the left\-hand prompt, but API for
rprompt is the same other than the variable name: just replace
\f[C]prompt\f[] with \f[C]rprompt\f[].
.PP
To customize the prompt, assign a function to \f[C]edit:prompt\f[].
The function may write value outputs or byte outputs.
Value outputs may be either strings or \f[C]edit:styled\f[] values; they
are joiend with no spaces in between.
Byte outputs are output as\-is, including any newlines, but control
characters will be escaped: you should use \f[C]edit:styled\f[] to
output styled text.
If you mix value and byte outputs, the order in which they appear is
non\-deterministic.
.PP
The default prompt and rprompt are equivalent to:
.IP
.nf
\f[C]
edit:prompt\ =\ {\ tilde\-abbr\ $pwd;\ put\ \[aq]>\ \[aq]\ }
edit:rprompt\ =\ (constantly\ (edit:styled\ (whoami)\@(hostname)\ inverse))
\f[]
.fi
.PP
More prompt functions:
.IP
.nf
\f[C]
~>\ edit:prompt\ =\ {\ tilde\-abbr\ $pwd;\ edit:styled\ \[aq]>\ \[aq]\ green\ }
~>\ #\ ">"\ is\ now\ green
~>\ edit:prompt\ =\ {\ echo\ \[aq]$\[aq]\ }
$
#\ Cursor\ will\ be\ on\ the\ next\ line\ as\ `echo`\ outputs\ a\ trailing\ newline
\f[]
.fi
.SS Stale Prompt
.PP
Elvish never waits for the prompt function to finish.
Instead, the prompt function is always executed on a separate thread,
and Elvish updates the screen when the function finishes.
.PP
However, this can be misleading when the function is slow: this means
that the prompt on the screen may not contain the latest information.
To deal with this, if the prompt function does not finish within a
certain threshold \- by default 0.2 seconds, Elvish marks the prompt as
\f[B]stale\f[]: it still shows the old stale prompt content, but
transforms it using a \f[B]stale transformer\f[].
The default stale transformer applies reverse\-video to the whole
prompt.
.PP
The threshold is customizable with
\f[C]$edit:prompt\-stale\-threshold\f[]; it specifies the threshold in
seconds.
.PP
The transformer is customizable with
\f[C]$edit:prompt\-stale\-transform\f[].
It is a function; the function is called with no arguments, and
\f[C]styled\f[] values as inputs, and the output is interpreted in the
same way as prompt functions.
Since \f[C]styled\f[] values can be used as outputs in prompt functions,
a function that simply passes all the input values through as outputs is
a valid stale transformer.
.PP
As an example, try running following code:
.IP
.nf
\f[C]
n\ =\ 0
edit:prompt\ =\ {\ sleep\ 2;\ put\ $n;\ n\ =\ (+\ $n\ 1);\ put\ \[aq]:\ \[aq]\ }
edit:\-prompt\-eagerness\ =\ 10\ #\ update\ prompt\ on\ each\ keystroke
edit:prompt\-stale\-threshold\ =\ 0.5
\f[]
.fi
.PP
And then start typing.
Type one character; the prompt becomes inverse after 0.5 second: this is
when Elvish starts to consider the prompt as stale.
The prompt will return normal after 2 seconds, and the counter in the
prompt is updated: this is when the prompt function finishes.
.PP
Another thing you will notice is that, if you type a few characters
quickly (in less than 2 seconds, to be precise), the prompt is only
updated twice.
This is because Elvish never does two prompt updates in parallel: prompt
updates are serialized.
If a prompt update is required when the prompt function is still
running, Elvish simply queues another update.
If an update is already queued, Elvish does not queue another update.
The reason why exactly two updates happen in this case, and how this
algorithm ensures freshness of the prompt is left as an exercise to the
reader.
.SS Prompt Eagerness
.PP
The occassions when the prompt should get updated can be controlled with
\f[C]$edit:\-prompt\-eagerness\f[]:
.IP \[bu] 2
The prompt is always updated when the editor becomes active \-\- when
Elvish starts, or a command finishes execution, or when the user presses
Enter.
.IP \[bu] 2
If \f[C]$edit\-prompt\-eagerness\f[] >= 5, it is updated when the
working directory changes.
.IP \[bu] 2
If \f[C]$edit\-prompt\-eagerness\f[] >= 10, it is updated on each
keystroke.
.PP
The default value is 5.
.SS RPrompt Persistency
.PP
By default, the rprompt is only shown while the editor is active: as
soon as you press Enter, it is erased.
If you want to keep it, simply set \f[C]$edit:rprompt\-persistent\f[] to
\f[C]$true\f[]:
.IP
.nf
\f[C]
edit:rprompt\-persistent\ =\ $true
\f[]
.fi
.SH Keybindings
.PP
Each mode has its own keybinding, accessible as the \f[C]binding\f[]
variable in its module.
For instance, the binding table for insert mode is
\f[C]$edit:insert:binding\f[].
To see current bindings, simply print the binding table:
\f[C]pprint\ $edit:insert:binding\f[] (replace \f[C]insert\f[] with any
other mode).
.PP
A binding tables is simply a map that maps keys to functions.
For instance, to bind \f[C]Alt\-x\f[] in insert mode to exit Elvish,
simply do:
.IP
.nf
\f[C]
edit:insert:binding[Alt\-x]\ =\ {\ exit\ }
\f[]
.fi
.PP
Outputs from a bound function always appear above the Elvish prompt.
You can see this by doing the following:
.IP
.nf
\f[C]
edit:insert:binding[Alt\-x]\ =\ {\ echo\ \[aq]output\ from\ a\ bound\ function!\[aq]\ }
\f[]
.fi
.PP
and press Alt\-x in insert mode.
It allows you to put debugging outputs in bound functions without
messing up the terminal.
.PP
Internally, this is implemented by connecting their output to a pipe.
This does the correct thing in most cases, but if you are sure you want
to do something to the terminal, redirect the output to
\f[C]/dev/tty\f[].
For instance, the following binds Ctrl\-L to clearing the terminal:
.IP
.nf
\f[C]
edit:insert:binding[Ctrl\-L]\ =\ {\ clear\ >\ /dev/tty\ }
\f[]
.fi
.PP
Bound functions have their inputs redirected to /dev/null.
.SS Format of Keys
.PP
TBD
.SS Listing Modes
.PP
The modes \f[C]histlist\f[], \f[C]loc\f[] and \f[C]lastcmd\f[] are all
\f[B]listing modes\f[]: They all show a list, and you can filter items
and accept items.
.PP
Because they are very similar, you may want to change their bindings at
the same time.
This is made possible by the \f[C]$edit:listing:binding\f[] binding
table (\f[C]listing\f[] is not a "real" mode but an "abstract" mode).
These modes still have their own binding tables like
\f[C]$edit:histlist:binding\f[], and bindings there have highter
precedence over those in the shared \f[C]$edit:listing:binding\f[]
table.
.PP
Moreover, there are a lot of builtin functions in the
\f[C]edit:listing\f[] module like \f[C]edit:listing:down\f[] (for moving
down selection).
They always apply to whichever listing mode is active.
.SS Caveat: Bindings to Start Modes
.PP
Note that keybindings to \f[B]start\f[] modes live in the binding table
of the insert mode, not the target mode.
For instance, if you want to be able to use Alt\-l to start location
mode, you should modify \f[C]$edit:insert:binding[Alt\-l]\f[]:
.IP
.nf
\f[C]
edit:insert:binding[Alt\-l]\ =\ {\ edit:location:start\ }
\f[]
.fi
.PP
One tricky case is the history mode.
You can press ▲︎ to start searching for history, and continue pressing
it to search further.
However, when the first press happens, the editor is in insert mode,
while with subsequent presses, the editor is in history mode.
Hence this binding actually relies on two entries,
\f[C]$edit:insert:binding[Up]\f[] and
\f[C]$edit:history:binding[Up]\f[].
.PP
So for instance if you want to be able to use Ctrl\-P for this, you need
to modify both bindings:
.IP
.nf
\f[C]
edit:insert:binding[Up]\ =\ {\ edit:history:start\ }
edit:history:binding[Up]\ =\ {\ edit:history:up\ }
\f[]
.fi
.SH Completion API
.SS Argument Completer
.PP
There are two types of completions in Elvish: completion for internal
data and completion for command arguments.
The former includes completion for variable names (e.g.
\f[C]echo\ $\f[]Tab) and indicies (e.g.
\f[C]echo\ $edit:insert:binding[\f[]Tab).
These are the completions that Elvish can provide itself because they
only depend on the internal state of Elvish.
.PP
The latter, in turn, is what happens when you type e.g.
\f[C]cat\f[]Tab.
Elvish cannot provide completions for them without full knowledge of the
command.
.PP
Command argument completions are programmable via the
\f[C]$edit:completion:arg\-completer\f[] variable.
When Elvish is completing an argument of command \f[C]$x\f[], it will
call the value stored in \f[C]$edit:completion:arg\-completer[$x]\f[],
with all the existing arguments, plus the command name in the front.
.PP
For example, if the user types \f[C]man\ 1\f[]Tab, Elvish will call:
.IP
.nf
\f[C]
$edit:completion:arg\-completer[man]\ man\ 1
\f[]
.fi
.PP
If the user is starting a new argument when hitting Tab, Elvish will
call the completer with a trailing empty string.
For instance, if you do \f[C]man\ 1\f[]SpaceTab, Elvish will call:
.IP
.nf
\f[C]
$edit:completion:arg\-completer[man]\ man\ 1\ ""
\f[]
.fi
.PP
The output of this call becomes candidates.
There are several ways of outputting candidates:
.IP \[bu] 2
Writing byte output, e.g.
"echo cand1; echo cand2".
Each line becomes a candidate.
This has the drawback that you cannot put newlines in candidates.
Only use this if you are sure that you candidates will not contain
newlines \-\- e.g.
package names, usernames, but \f[B]not\f[] file names, etc..
.IP \[bu] 2
Write strings to value output, e.g.
"put cand1 cand2".
Each string output becomes a candidate.
.IP \[bu] 2
Use the \f[C]edit:complex\-candidate\f[] command:
.RS 2
.IP
.nf
\f[C]
edit:complex\-candidate\ &code\-suffix=\[aq]\[aq]\ &display\-suffix=\[aq]\[aq]\ &style=\[aq]\[aq]\ $stem
\f[]
.fi
.PP
\f[B]TODO\f[]: Document this.
.RE
.PP
After receiving your candidates, Elvish will match your candidates
against what the user has typed.
Hence, normally you don\[aq]t need to (and shouldn\[aq]t) do any
matching yourself.
.PP
That means that in many cases you can (and should) simpy ignore the last
argument to your completer.
However, they can be useful for deciding what \f[B]kind\f[] of things to
complete.
For instance, if you are to write a completer for \f[C]ls\f[], you want
to see whether the last argument starts with \f[C]\-\f[] or not: if it
does, complete an option; and if not, complete a filename.
.PP
Here is a very basic example of configuring a completer for the
\f[C]apt\f[] command.
It only supports completing the \f[C]install\f[] and \f[C]remove\f[]
command and package names after that:
.IP
.nf
\f[C]
all\-packages\ =\ [(apt\-cache\ search\ \[aq]\[aq]\ |\ eawk\ [0\ 1\ \@rest]{\ put\ $1\ })]

edit:completion:arg\-completer[apt]\ =\ [\@args]{
\ \ \ \ n\ =\ (count\ $args)
\ \ \ \ if\ (==\ $n\ 2)\ {
\ \ \ \ \ \ \ \ #\ apt\ x<Tab>\ \-\-\ complete\ a\ subcommand\ name
\ \ \ \ \ \ \ \ put\ install\ uninstall
\ \ \ \ }\ elif\ (==\ $n\ 3)\ {
\ \ \ \ \ \ \ \ put\ $\@all\-packages
\ \ \ \ }
}
\f[]
.fi
.PP
Here is another slightly more complex example for the \f[C]git\f[]
command.
It supports completing some common subcommands and then branch names
after that:
.IP
.nf
\f[C]
fn\ all\-git\-branches\ {
\ \ \ \ #\ Note:\ this\ assumes\ a\ recent\ version\ of\ git\ that\ supports\ the\ format
\ \ \ \ #\ string\ used.
\ \ \ \ git\ branch\ \-a\ \-\-format="%(refname:strip=2)"\ |\ eawk\ [0\ 1\ \@rest]{\ put\ $1\ }
}

common\-git\-commands\ =\ [
\ \ add\ branch\ checkout\ clone\ commit\ diff\ init\ log\ merge
\ \ pull\ push\ rebase\ reset\ revert\ show\ stash\ status
]

edit:arg\-completer[git]\ =\ [\@args]{
\ \ \ \ n\ =\ (count\ $args)
\ \ \ \ if\ (==\ $n\ 2)\ {
\ \ \ \ \ \ \ \ put\ $\@common\-git\-commands
\ \ \ \ }\ elif\ (>=\ $n\ 3)\ {
\ \ \ \ \ \ \ \ all\-git\-branches
\ \ \ \ }
}
\f[]
.fi
.SS Matcher
.PP
As stated above, after the completer outputs candidates, Elvish matches
them with them with what the user has typed.
For clarity, the part of the user input that is relevant to tab
completion is called for the \f[B]seed\f[] of the completion.
For instance, in \f[C]echo\ x\f[]Tab, the seed is \f[C]x\f[].
.PP
Elvish first indexes the matcher table \-\-
\f[C]$edit:completion:matcher\f[] \-\- with the completion type to find
a \f[B]matcher\f[].
The \f[B]completion type\f[] is currently one of \f[C]variable\f[],
\f[C]index\f[], \f[C]command\f[], \f[C]redir\f[] or \f[C]argument\f[].
If the \f[C]$edit:completion:matcher\f[] lacks the suitable key,
\f[C]$edit:completion:matcher[\[aq]\[aq]]\f[] is used.
.PP
Elvish then calls the matcher with one argument \-\- the seed, and feeds
the \f[I]text\f[] of all candidates to the input.
The mather must output an identical number of booleans, indicating
whether the candidate should be kept.
.PP
As an example, the following code configures a prefix matcher for all
completion types:
.IP
.nf
\f[C]
edit:completion:matcher[\[aq]\[aq]]\ =\ [seed]{\ each\ [cand]{\ has\-prefix\ $cand\ $seed\ }\ }
\f[]
.fi
.PP
Elvish provides three builtin matchers, \f[C]edit:match\-prefix\f[],
\f[C]edit:match\-substr\f[] and \f[C]edit:match\-subseq\f[].
In addition to conforming to the matcher protocol, they accept two
options \f[C]&ignore\-case\f[] and \f[C]&smart\-case\f[].
For example, if you want completion of arguments to use prefix matching
and ignore case, use:
.IP
.nf
\f[C]
edit:completion:matcher[argument]\ =\ [seed]{\ edit:match\-prefix\ $seed\ &ignore\-case=$true\ }
\f[]
.fi
.PP
The default value of \f[C]$edit:completion:matcher\f[] is
\f[C][&\[aq]\[aq]=$edit:match\-prefix~]\f[], hence that candidates for
all completion types are matched by prefix.
.SH Hooks
.PP
Hooks are functions that are executed at certain points in time.
In Elvish, this functionality is provided by lists of functions.
.PP
There are current two hooks:
.IP \[bu] 2
\f[C]$edit:before\-readline\f[], whose elements are called before the
editor reads code, with no arguments.
.IP \[bu] 2
\f[C]$edit:after\-readline\f[], whose elements are called, after the
editor reads code, with a sole element \-\- the line just read.
.PP
Example usage:
.IP
.nf
\f[C]
edit:before\-readline\ =\ [{\ echo\ \[aq]going\ to\ read\[aq]\ }]
edit:after\-readline\ =\ [[line]{\ echo\ \[aq]just\ read\ \[aq]$line\ }]
\f[]
.fi
.PP
Then every time you accept a chunk of code (and thus leaving the
editor), \f[C]just\ read\f[] followed by the code is printed; and at the
very beginning of an Elvish session, or after a chunk of code is
executed, \f[C]going\ to\ read\f[] is printed.
.SH Functions and Variables
.PP
Functions and variables who name start with \f[C]\-\f[] are
experimental, will have their names or behaviors changed in the near
future.
Others are more stable (unless noted explicitly) but are also subject to
change before the 1.0 release.
.SS edit:\-dump\-buf
.PP
Dump the content of onscreen buffer as HTML.
This command is used to generate "ttyshots" on the homepage (/).
.PP
Example:
.IP
.nf
\f[C]
ttyshot\ =\ ~/a.html
edit:insert:binding[Ctrl\-X]\ =\ {\ edit:\-dump\-buf\ >\ $tty\ }
\f[]
.fi
.SS edit:complete\-filename
.IP
.nf
\f[C]
edit:complete\-filename\ \@args
\f[]
.fi
.PP
Produces a list of filenames found in the directory of the last
argument.
All other arguments are ignored.
If the last argument does not contain a path (either absolute or
relative to the current directory), then the current directory is used.
Relevant files are output as \f[C]edit:complex\-candidate\f[] objects.
.PP
This function is the default handler for any commands without explicit
handlers in \f[C]$edit:completion:arg\-completer\f[].
See Argument Completer.
.PP
Example:
.IP
.nf
\f[C]
~>\ edit:complete\-filename\ \[aq]\[aq]
▶\ (edit:complex\-candidate\ Applications\ &code\-suffix=/\ &display\-suffix=\[aq]\[aq]\ &style=\[aq]01;34\[aq])
▶\ (edit:complex\-candidate\ Books\ &code\-suffix=/\ &display\-suffix=\[aq]\[aq]\ &style=\[aq]01;34\[aq])
▶\ (edit:complex\-candidate\ Desktop\ &code\-suffix=/\ &display\-suffix=\[aq]\[aq]\ &style=\[aq]01;34\[aq])
▶\ (edit:complex\-candidate\ Docsafe\ &code\-suffix=/\ &display\-suffix=\[aq]\[aq]\ &style=\[aq]01;34\[aq])
▶\ (edit:complex\-candidate\ Documents\ &code\-suffix=/\ &display\-suffix=\[aq]\[aq]\ &style=\[aq]01;34\[aq])
\&...
~>\ edit:complete\-filename\ .elvish/
▶\ (edit:complex\-candidate\ .elvish/aliases\ &code\-suffix=/\ &display\-suffix=\[aq]\[aq]\ &style=\[aq]01;34\[aq])
▶\ (edit:complex\-candidate\ .elvish/db\ &code\-suffix=\[aq]\ \[aq]\ &display\-suffix=\[aq]\[aq]\ &style=\[aq]\[aq])
▶\ (edit:complex\-candidate\ .elvish/epm\-installed\ &code\-suffix=\[aq]\ \[aq]\ &display\-suffix=\[aq]\[aq]\ &style=\[aq]\[aq])
▶\ (edit:complex\-candidate\ .elvish/lib\ &code\-suffix=/\ &display\-suffix=\[aq]\[aq]\ &style=\[aq]01;34\[aq])
▶\ (edit:complex\-candidate\ .elvish/rc.elv\ &code\-suffix=\[aq]\ \[aq]\ &display\-suffix=\[aq]\[aq]\ &style=\[aq]\[aq])
\f[]
.fi
.SS edit:complete\-getopt
.IP
.nf
\f[C]
edit:complete\-getopt\ $args\ $opts\ $handlers
\f[]
.fi
.PP
Produces completions according to a specification of accepted
command\-line options (both short and long options are handled),
positional handler functions for each command position, and the current
arguments in the command line.
The arguments are as follows:
.IP \[bu] 2
\f[C]$args\f[] is an array containing the current arguments in the
command line (without the command itself).
These are the arguments as passed to the Argument Completer function.
.IP \[bu] 2
\f[C]$opts\f[] is an array of maps, each one containing the definition
of one possible command\-line option.
Matching options will be provided as completions when the last element
of \f[C]$args\f[] starts with a dash, but not otherwise.
Each map can contain the following keys (at least one of \f[C]short\f[]
or \f[C]long\f[] needs to be specified):
.RS 2
.IP \[bu] 2
\f[C]short\f[] contains the one\-letter short option, if any, without
the dash.
.IP \[bu] 2
\f[C]long\f[] contains the long option name, if any, without the initial
two dashes.
.IP \[bu] 2
\f[C]arg\-optional\f[], if set to \f[C]$true\f[], specifies that the
option receives an optional argument.
.IP \[bu] 2
\f[C]arg\-mandatory\f[], if set to \f[C]$true\f[], specifies that the
option receives a mandatory argument.
Only one of \f[C]arg\-optional\f[] or \f[C]arg\-mandatory\f[] can be set
to \f[C]$true\f[].
.IP \[bu] 2
\f[C]desc\f[] can be set to a human\-readable description of the option
which will be displayed in the completion menu.
.RE
.IP \[bu] 2
\f[C]$handlers\f[] is an array of functions, each one returning the
possible completions for that position in the arguments.
Each function receives as argument the last element of \f[C]$args\f[],
and should return zero or more possible values for the completions at
that point.
The returned values can be plain strings or the output of
\f[C]edit:complex\-candidate\f[].
If the last element of the list is the string \f[C]\&...\f[], then the
last handler is reused for all following arguments.
.PP
Example:
.IP
.nf
\f[C]
~>\ for\ args\ [\ [\[aq]\[aq]]\ [\[aq]\-\[aq]]\ [\[aq]\-a\[aq]\ \[aq]\[aq]]\ [\ arg1\ \[aq]\[aq]\ ]\ [\ arg1\ arg2\ \[aq]\[aq]]]\ {
\ \ \ \ \ echo\ "args\ =\ "(to\-string\ $args)
\ \ \ \ \ edit:complete\-getopt\ $args\ [\ [&short=a\ &long=all\ &desc="Show\ all"]\ ]\ [\ [_]{\ put\ first1\ first2\ }\ [_]{\ put\ second1\ second2\ }\ ...\ ]
\ \ \ }
args\ =\ [\[aq]\[aq]]
▶\ first1
▶\ first2
args\ =\ [\-]
▶\ (edit:complex\-candidate\ \-a\ &code\-suffix=\[aq]\[aq]\ &display\-suffix=\[aq]\ (Show\ all)\[aq]\ &style=\[aq]\[aq])
▶\ (edit:complex\-candidate\ \-\-all\ &code\-suffix=\[aq]\[aq]\ &display\-suffix=\[aq]\ (Show\ all)\[aq]\ &style=\[aq]\[aq])
args\ =\ [\-a\ \[aq]\[aq]]
▶\ first1
▶\ first2
args\ =\ [arg1\ \[aq]\[aq]]
▶\ second1
▶\ second2
args\ =\ [arg1\ arg2\ \[aq]\[aq]]
▶\ second1
▶\ second2
\f[]
.fi
.SS edit:styled
.IP
.nf
\f[C]
edit:styled\ $text\ $styles
\f[]
.fi
.PP
Construct an abstract styled text.
The \f[C]$text\f[] argument can be an arbitrary string, while the
\f[C]$styles\f[] argument is a list or semicolon\-delimited string of
the following styles:
.IP \[bu] 2
Text styles: \f[C]bold\f[], \f[C]dim\f[], \f[C]italic\f[],
\f[C]underlined\f[], \f[C]blink\f[], \f[C]inverse\f[].
.IP \[bu] 2
Text colors: \f[C]black\f[], \f[C]red\f[], \f[C]green\f[],
\f[C]yellow\f[], \f[C]blue\f[], \f[C]magenta\f[], \f[C]cyan\f[],
\f[C]lightgray\f[], and their corresponding light colors: \f[C]gray\f[],
\f[C]lightred\f[], \f[C]lightgreen\f[], \f[C]lightyellow\f[],
\f[C]lightblue\f[], \f[C]lightmagenta\f[], \f[C]lightcyan\f[] and
\f[C]white\f[].
.IP \[bu] 2
Background colors: any of the text colors with a \f[C]bg\-\f[] prefix
(e.g.
\f[C]bg\-red\f[] for red background), plus \f[C]bg\-default\f[] for
default background color.
.IP \[bu] 2
An ANSI SGR
parameter (https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_.28Select_Graphic_Rendition.29_parameters)
code (e.g.
\f[C]1\f[] for bold), subject to terminal support.
.PP
Note that the result of \f[C]edit:styled\f[] is an abstract data
structure, not an ANSI sequence.
However, it stringifies to an ANSI sequence, so you rarely have to
convert it.
To force a conversion, use \f[C]to\-string\f[]:
.IP
.nf
\f[C]
~>\ edit:styled\ haha\ green
▶\ (edit:styled\ haha\ [green])
~>\ echo\ (edit:styled\ haha\ green)\ #\ output\ is\ green
haha
~>\ to\-string\ (edit:styled\ haha\ green)
▶\ "\\e[32mhaha\\e[m"
\f[]
.fi
.PP
The forced conversion is useful when e.g.
assigning to \f[C]$value\-out\-indicator\f[]:
.IP
.nf
\f[C]
~>\ value\-out\-indicator\ =\ (to\-string\ (edit:styled\ \[aq]>\ \[aq]\ green))
~>\ put\ lorem\ ipsum\ #\ leading\ \[aq]>\ \[aq]\ is\ green
>\ lorem
>\ ipsum
\f[]
.fi
.PP
The styled text can be inspected by indexing:
.IP
.nf
\f[C]
~>\ s\ =\ (edit:styled\ haha\ green)
~>\ put\ $s[text]\ $s[styles]
▶\ haha
▶\ [green]
\f[]
.fi
.SS $edit:current\-command
.PP
Contains the content of the current input.
Setting the variable will cause the cursor to move to the very end, as
if \f[C]edit\-dot\ =\ (count\ $edit:current\-command)\f[] has been
invoked.
.PP
This API is subject to change.
.SS $edit:\-dot
.PP
Contains the current position of the curosr, as a byte position within
\f[C]$edit:current\-command\f[].
.SS $edit:max\-height
.PP
Maximum height the editor is allowed to use, defaults to \f[C]+Inf\f[].
.PP
By default, the height of the editor is only restricted by the terminal
height.
Some modes like location mode can use a lot of lines; as a result, it
can often occupy the entire terminal, and push up your scrollback
buffer.
Change this variable to a finite number to restrict the height of the
editor.
.SS $edit:completion:matcher
.PP
See the Matcher section.
.SS $edit:prompt
.PP
See Prompts.
.SS $edit:\-prompt\-eagerness
.PP
See Prompt Eagerness.
.SS $edit:prompt\-stale\-threshold
.PP
See Stale Prompt.
.SS $edit:prompt\-stale\-transformer
.PP
See Stale Prompt.
.SS $edit:rprompt
.PP
See Prompts.
.SS $edit:\-rprompt\-eagerness
.PP
See Prompt Eagerness.
.SS $edit:rprompt\-persistent
.PP
See RPrompt Persistency.
.SS $edit:rprompt\-stale\-threshold
.PP
See Stale Prompt.
.SS $edit:rprompt\-stale\-transformer
.PP
See Stale Prompt.