.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "elvish-edit" "7" "Dec 07, 2021" "Elvish 0.17.0~rc4" "Miscellaneous Information Manual"
.hy
.PP
.PP
The \f[C]edit:\f[R] 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.
.PP
\f[I]This document is incomplete.\f[R]
.SH Overview
.SS Modes and Submodules
.PP
The Elvish editor has different \f[B]modes\f[R], 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[R] lets you modify the
current command.
The \f[B]completion mode\f[R] (triggered by Tab by default) shows you
all candidates for completion, and you can use arrow keys to navigate
those candidates.
.PP
Each mode has its own submodule under \f[C]edit:\f[R].
For instance, builtin functions and configuration variables for the
completion mode can be found in the \f[C]edit:completion:\f[R] module.
.PP
The primary modes supported now are \f[C]insert\f[R], \f[C]command\f[R],
\f[C]completion\f[R], \f[C]navigation\f[R], \f[C]history\f[R],
\f[C]histlist\f[R], \f[C]location\f[R], and \f[C]lastcmd\f[R].
The last 4 are \[lq]listing modes\[rq], and their particularity is
documented below.
.SS 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[R] with \f[C]rprompt\f[R].
.PP
To customize the prompt, assign a function to \f[C]edit:prompt\f[R].
The function may write value outputs or byte outputs:
.IP \[bu] 2
Value outputs may be either strings or \f[C]styled\f[R] values; they are
joiend with no spaces in between.
.IP \[bu] 2
Byte outputs are output as-is, including any newlines.
Any SGR escape
sequences (https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters)
included in the byte outputs will be parsed, but any other escape
sequences or control character will be removed.
.PP
If you mix value and byte outputs, the order in which they appear is
non-deterministic.
.PP
Prefer using \f[C]styled\f[R] to output styled text; the support for SGR
escape sequences is mostly for compatibility with external cross-shell
prompts.
.PP
The default prompt and rprompt are equivalent to:
.IP
.nf
\f[C]
edit:prompt = { tilde-abbr $pwd; put \[aq]> \[aq] }
edit:rprompt = (constantly (styled (whoami)\[at](hostname) inverse))
\f[R]
.fi
.PP
More prompt functions:
.IP
.nf
\f[C]
\[ti]> edit:prompt = { tilde-abbr $pwd; styled \[aq]> \[aq] green }
\[ti]> # \[dq]>\[dq] is now green
\[ti]> edit:prompt = { echo \[aq]$\[aq] }
$
# Cursor will be on the next line as \[ga]echo\[ga] outputs a trailing newline
\f[R]
.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[R]: it still shows the old stale prompt content, but
transforms it using a \f[B]stale transformer\f[R].
The default stale transformer applies reverse-video to the whole prompt.
.PP
The threshold is customizable with
\f[C]$edit:prompt-stale-threshold\f[R]; it specifies the threshold in
seconds.
.PP
The transformer is customizable with
\f[C]$edit:prompt-stale-transform\f[R].
It is a function; the function is called with one argument, a
\f[C]styled\f[R] text, and the output is interpreted in the same way as
prompt functions.
Some examples are:
.IP
.nf
\f[C]
# The following effectively disables marking of stale prompt.
edit:prompt-stale-transform = [x]{ put $x }
# Show stale prompts in inverse; equivalent to the default.
edit:prompt-stale-transform = [x]{ styled $x inverse }
# Gray out stale prompts.
edit:prompt-stale-transform = [x]{ styled $x bright-black }
\f[R]
.fi
.PP
To see the transformer in action, try the following example (assuming
default \f[C]$edit:prompt-stale-transform\f[R]):
.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[R]
.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 occasions when the prompt should get updated can be controlled with
\f[C]$edit:-prompt-eagerness\f[R]:
.IP \[bu] 2
The prompt is always updated when the editor becomes active \[en] when
Elvish starts, or a command finishes execution, or when the user presses
Enter.
.IP \[bu] 2
If \f[C]$edit:-prompt-eagerness\f[R] >= 5, it is updated when the
working directory changes.
.IP \[bu] 2
If \f[C]$edit:-prompt-eagerness\f[R] >= 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[R] to
\f[C]$true\f[R]:
.IP
.nf
\f[C]
edit:rprompt-persistent = $true
\f[R]
.fi
.SS Keybindings
.PP
Each mode has its own keybinding, accessible as the \f[C]binding\f[R]
variable in its module.
For instance, the binding table for insert mode is
\f[C]$edit:insert:binding\f[R].
To see current bindings, simply print the binding table:
\f[C]pprint $edit:insert:binding\f[R] (replace \f[C]insert\f[R] with any
other mode).
.PP
The global key binding table, \f[C]$edit:global-binding\f[R] is
consulted when a key is not handled by the active mode.
.PP
A binding tables is simply a map that maps keys to functions.
For instance, to bind \f[C]Alt-x\f[R] in insert mode to exit Elvish,
simply do:
.IP
.nf
\f[C]
edit:insert:binding[Alt-x] = { exit }
\f[R]
.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[R]
.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[R].
Since this will break Elvish\[cq]s internal tracking of the terminal
state, you should also do a full redraw with
\f[C]edit:redraw &full=$true\f[R].
For instance, the following binds Ctrl-L to clearing the terminal:
.IP
.nf
\f[C]
edit:insert:binding[Ctrl-L] = { clear > /dev/tty; edit:redraw &full=$true }
\f[R]
.fi
.PP
(The same functionality is already available as a builtin,
\f[C]edit:clear\f[R].)
.PP
Bound functions have their inputs redirected to /dev/null.
.SS Format of Keys
.PP
Key modifiers and names are case sensitive.
This includes single character key names such as \f[C]x\f[R] and
\f[C]Y\f[R] as well as function key names such as \f[C]Enter\f[R].
.PP
Key names have zero or more modifiers from the following symbols:
.IP
.nf
\f[C]
    A  Alt
    C  Ctrl
    M  Meta
    S  Shift
\f[R]
.fi
.PP
Modifiers, if present, end with either a \f[C]-\f[R] or \f[C]+\f[R];
e.g., \f[C]S-F1\f[R], \f[C]Ctrl-X\f[R] or \f[C]Alt+Enter\f[R].
You can stack modifiers; e.g., \f[C]C+A-X\f[R].
.PP
The key name may be a simple character such as \f[C]x\f[R] or a function
key from these symbols:
.IP
.nf
\f[C]
    F1  F2  F3  F4  F5  F6  F7  F8  F9  F10  F11  F12
    Up  Down  Right  Left
    Home  Insert  Delete  End  PageUp  PageDown
    Tab  Enter  Backspace
\f[R]
.fi
.PP
\f[B]Note:\f[R] \f[C]Tab\f[R] is an alias for \f[C]\[dq]\[rs]t\[dq]\f[R]
(aka \f[C]Ctrl-I\f[R]), \f[C]Enter\f[R] for \f[C]\[dq]\[rs]n\[dq]\f[R]
(aka \f[C]Ctrl-J\f[R]), and \f[C]Backspace\f[R] for
\f[C]\[dq]\[rs]x7F\[dq]\f[R] (aka \f[C]Ctrl-?\f[R]).
.PP
\f[B]Note:\f[R] The \f[C]Shift\f[R] modifier is only applicable to
function keys such as \f[C]F1\f[R].
You cannot write \f[C]Shift-m\f[R] as a synonym for \f[C]M\f[R].
.PP
\f[B]TODO:\f[R] Document the behavior of the \f[C]Shift\f[R] modifier.
.SS Listing Modes
.PP
The modes \f[C]histlist\f[R], \f[C]loc\f[R] and \f[C]lastcmd\f[R] are
all \f[B]listing modes\f[R]: 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[R] binding
table (\f[C]listing\f[R] is not a \[lq]real\[rq] mode but an
\[lq]abstract\[rq] mode).
These modes still have their own binding tables like
\f[C]$edit:histlist:binding\f[R], and bindings there have higher
precedence over those in the shared \f[C]$edit:listing:binding\f[R]
table.
.PP
Moreover, there are a lot of builtin functions in the
\f[C]edit:listing\f[R] module like \f[C]edit:listing:down\f[R] (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[R] 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[R]:
.IP
.nf
\f[C]
edit:insert:binding[Alt-l] = { edit:location:start }
\f[R]
.fi
.PP
One tricky case is the history mode.
You can press \[u25B2]\[uFE0E] 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[R] and
\f[C]$edit:history:binding[Up]\f[R].
.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[Ctrl-P] =  { edit:history:start }
edit:history:binding[Ctrl-P] = { edit:history:up }
\f[R]
.fi
.SS Filter DSL
.PP
The completion, history listing, location and navigation modes all
support filtering the items to show using a filter DSL.
It uses a small subset of Elvish\[cq]s expression syntax, and can be any
of the following:
.IP \[bu] 2
A literal string (barewords and single-quoted or double-quoted strings
all work) matches items containing the string.
If the string is all lower case, the match is done case-insensitively;
otherwise the match is case-sensitive.
.IP \[bu] 2
A list \f[C][re $string]\f[R] matches items matching the regular
expression \f[C]$string\f[R].
The \f[C]$string\f[R] must be a literal string.
.IP \[bu] 2
A list \f[C][and $expr...]\f[R] matches items matching all of the
\f[C]$expr\f[R]s.
.IP \[bu] 2
A list \f[C][or $expr...]\f[R] matches items matching any of the
\f[C]$expr\f[R]s.
.PP
If the filter contains multiple expressions, they are ANDed, as if
surrounded by an implicit \f[C][and ...]\f[R].
.SS 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[R]Tab) and indices (e.g.
\f[C]echo $edit:insert:binding[\f[R]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[R]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[R] variable.
When Elvish is completing an argument of command \f[C]$x\f[R], it will
call the value stored in \f[C]$edit:completion:arg-completer[$x]\f[R],
with all the existing arguments, plus the command name in the front.
.PP
For example, if the user types \f[C]man 1\f[R]Tab, Elvish will call:
.IP
.nf
\f[C]
$edit:completion:arg-completer[man] man 1
\f[R]
.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[R]SpaceTab, Elvish will call:
.IP
.nf
\f[C]
$edit:completion:arg-completer[man] man 1 \[dq]\[dq]
\f[R]
.fi
.PP
The output of this call becomes candidates.
There are several ways of outputting candidates:
.IP \[bu] 2
Writing byte output, e.g.
\[lq]echo cand1; echo cand2\[rq].
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 \[en] e.g.
package names, usernames, but \f[B]not\f[R] file names, etc..
.IP \[bu] 2
Write strings to value output, e.g.
\[lq]put cand1 cand2\[rq].
Each string output becomes a candidate.
.IP \[bu] 2
Use the \f[C]edit:complex-candidate\f[R] command, e.g.:
.RS 2
.IP
.nf
\f[C]
edit:complex-candidate &code-suffix=\[aq]\[aq] &display=$stem\[aq] (\[aq]$description\[aq])\[aq]  $stem
\f[R]
.fi
.PP
See \f[C]edit:complex-candidate\f[R] for the full description of the
arguments is accepts.
.RE
.PP
After receiving your candidates, Elvish will match your candidates
against what the user has typed.
Hence, normally you don\[cq]t need to (and shouldn\[cq]t) do any
matching yourself.
.PP
That means that in many cases you can (and should) simply ignore the
last argument to your completer.
However, they can be useful for deciding what \f[B]kind\f[R] of things
to complete.
For instance, if you are to write a completer for \f[C]ls\f[R], you want
to see whether the last argument starts with \f[C]-\f[R] 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[R] command.
It only supports completing the \f[C]install\f[R] and \f[C]remove\f[R]
command and package names after that:
.IP
.nf
\f[C]
all-packages = [(apt-cache search \[aq]\[aq] | eawk [0 1 \[at]rest]{ put $1 })]

edit:completion:arg-completer[apt] = [\[at]args]{
    n = (count $args)
    if (== $n 2) {
        # apt x<Tab> -- complete a subcommand name
        put install uninstall
    } elif (== $n 3) {
        put $\[at]all-packages
    }
}
\f[R]
.fi
.PP
Here is another slightly more complex example for the \f[C]git\f[R]
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=\[dq]%(refname:strip=2)\[dq] | eawk [0 1 \[at]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] = [\[at]args]{
    n = (count $args)
    if (== $n 2) {
        put $\[at]common-git-commands
    } elif (>= $n 3) {
        all-git-branches
    }
}
\f[R]
.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[R] of the completion.
For instance, in \f[C]echo x\f[R]Tab, the seed is \f[C]x\f[R].
.PP
Elvish first indexes the matcher table \[en]
\f[C]$edit:completion:matcher\f[R] \[en] with the completion type to
find a \f[B]matcher\f[R].
The \f[B]completion type\f[R] is currently one of \f[C]variable\f[R],
\f[C]index\f[R], \f[C]command\f[R], \f[C]redir\f[R] or
\f[C]argument\f[R].
If the \f[C]$edit:completion:matcher\f[R] lacks the suitable key,
\f[C]$edit:completion:matcher[\[aq]\[aq]]\f[R] is used.
.PP
Elvish then calls the matcher with one argument \[en] the seed, and
feeds the \f[I]text\f[R] 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[R]
.fi
.PP
Elvish provides three builtin matchers, \f[C]edit:match-prefix\f[R],
\f[C]edit:match-substr\f[R] and \f[C]edit:match-subseq\f[R].
In addition to conforming to the matcher protocol, they accept two
options \f[C]&ignore-case\f[R] and \f[C]&smart-case\f[R].
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[R]
.fi
.PP
The default value of \f[C]$edit:completion:matcher\f[R] is
\f[C][&\[aq]\[aq]=$edit:match-prefix\[ti]]\f[R], hence that candidates
for all completion types are matched by prefix.
.SS Hooks
.PP
Hooks are functions that are executed at certain points in time.
In Elvish this functionality is provided by variables that are a list of
functions.
.PP
\f[B]NOTE\f[R]: Hook variables may be initialized with a non-empty list,
and you may have modules that add their own hooks.
In general you should append to a hook variable rather than assign a
list of functions to it.
That is, rather than doing
\f[C]set edit:some-hook = [ []{ put \[aq]I ran\[aq] } ]\f[R] you should
do
\f[C]set edit:some-hook = [ $\[at]hook-var []{ put \[aq]I ran\[aq] } ]\f[R].
.PP
These are the editor/REPL hooks:
.IP \[bu] 2
\f[C]$edit:before-readline\f[R] (https://elv.sh/ref/edit.html#editbefore-readline):
The functions are called before the editor runs.
Each function is called with no arguments.
.IP \[bu] 2
\f[C]$edit:after-readline\f[R] (https://elv.sh/ref/edit.html#editafter-readline):
The functions are called after the editor accepts a command for
execution.
Each function is called with a sole argument: the line just read.
.IP \[bu] 2
\f[C]$edit:after-command\f[R] (https://elv.sh/ref/edit.html#editafter-command):
The functions are called after the shell executes the command you
entered (typically by pressing the \f[C]Enter\f[R] key).
Each function is called with a sole argument: a map that provides
information about the executed command.
This hook is also called after your interactive RC file is executed and
before the first prompt is output.
.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 }]
edit:after-command = [[m]{ echo \[aq]command took \[aq]$m[duration]\[aq] seconds\[aq] }]
\f[R]
.fi
.PP
Given the above hooks\&...
.IP "1." 3
Every time you accept a chunk of code (normally by pressing Enter)
\f[C]just read\f[R] is printed.
.IP "2." 3
At the very beginning of an Elvish session, or after a chunk of code is
handled, \f[C]going to read\f[R] is printed.
.IP "3." 3
After each non empty chunk of code is accepted and executed the string
\[lq]command took \&... seconds\[ga] is output.
.SS Word types
.PP
The editor supports operating on entire \[lq]words\[rq].
As intuitive as the concept of \[lq]word\[rq] is, there is actually no
single definition for the concept.
The editor supports the following three definitions of words:
.IP \[bu] 2
A \f[B]big word\f[R], or simply \f[B]word\f[R], is a sequence of
non-whitespace characters.
This definition corresponds to the concept of \[lq]WORD\[rq] in vi.
.IP \[bu] 2
A \f[B]small word\f[R] is a sequence of alphanumerical characters
(\[lq]alnum small word\[rq]), or a sequence of non-alphanumerical,
non-whitespace characters (\[lq]punctuation small word\[rq]).
This definition corresponds to the concept of \[lq]word\[rq] in vi and
zsh.
.IP \[bu] 2
An \f[B]alphanumerical word\f[R] is a sequence of alphanumerical
characters.
This definition corresponds to the concept of \[lq]word\[rq] in bash.
.PP
Whitespace characters are those with the Unicode
Whitespace (https://en.wikipedia.org/wiki/Whitespace_character#Unicode)
property.
Alphanumerical characters are those in the Unicode Letter or Number
category.
.PP
A \f[B]word boundary\f[R] is an imaginary zero-length boundary around a
word.
.PP
To see the difference between these definitions, consider the following
string: \f[C]abc++ /* xyz\f[R]:
.IP \[bu] 2
It contains three (big) words: \f[C]abc++\f[R], \f[C]/*\f[R] and
\f[C]xyz\f[R].
.IP \[bu] 2
It contains four small words, \f[C]abc\f[R], \f[C]++\f[R], \f[C]/*\f[R]
and \f[C]xyz\f[R].
Among them, \f[C]abc\f[R] and \f[C]xyz\f[R] are alnum small words, while
\f[C]++\f[R] and \f[C]/*\f[R] are punctuation small words.
.IP \[bu] 2
It contains two alnum words, \f[C]abc\f[R] and \f[C]xyz\f[R].
.SH Variables
.PP
.SS $edit:abbr {#edit:abbr}
.PP
A map from (simple) abbreviations to their expansions.
.PP
An abbreviation is replaced by its expansion when it is typed in full
and consecutively, without being interrupted by the use of other editing
functionalities, such as cursor movements.
.PP
If more than one abbreviations would match, the longest one is used.
.PP
Examples:
.IP
.nf
\f[C]
edit:abbr[\[aq]||\[aq]] = \[aq]| less\[aq]
edit:abbr[\[aq]>dn\[aq]] = \[aq]2>/dev/null\[aq]
\f[R]
.fi
.PP
With the definitions above, typing \f[C]||\f[R] anywhere expands to
\f[C]| less\f[R], and typing \f[C]>dn\f[R] anywhere expands to
\f[C]2>/dev/null\f[R].
However, typing a \f[C]|\f[R], moving the cursor left, and typing
another \f[C]|\f[R] does \f[B]not\f[R] expand to \f[C]| less\f[R], since
the abbreviation \f[C]||\f[R] was not typed consecutively.
.PP
See also \f[C]edit:small-word-abbr\f[R].
.PP
.SS $edit:add-cmd-filters {#edit:add-cmd-filters}
.PP
List of filters to run before adding a command to history.
.PP
A filter is a function that takes a command as argument and outputs a
boolean value.
If any of the filters outputs \f[C]$false\f[R], the command is not saved
to history, and the rest of the filters are not run.
The default value of this list contains a filter which ignores command
starts with space.
.PP
.SS $edit:after-command {#edit:after-command}
.PP
A list of functions to call after each interactive command completes.
There is one pre-defined function used to populate the
\f[C]$edit:command-duration\f[R] variable.
Each function is called with a single
map (https://elv.sh/ref/language.html#map) argument containing the
following keys:
.IP \[bu] 2
\f[C]src\f[R]: Information about the source that was executed, same as
what \f[C]src\f[R] would output inside the code.
.IP \[bu] 2
\f[C]duration\f[R]: A floating-point
number (https://elv.sh/ref/language.html#number) representing the
command execution duration in seconds.
.IP \[bu] 2
\f[C]error\f[R]: An exception object if the command terminated with an
exception, else \f[C]$nil\f[R].
.PP
See also \f[C]edit:command-duration\f[R].
.PP
.SS $edit:after-readline {#edit:after-readline}
.PP
A list of functions to call after each readline cycle.
Each function is called with a single string argument containing the
code that has been read.
.PP
.SS $edit:before-readline {#edit:before-readline}
.PP
A list of functions to call before each readline cycle.
Each function is called without any arguments.
.PP
.SS $edit:command-duration {#edit:command-duration}
.PP
Duration, in seconds, of the most recent interactive command.
This can be useful in your prompt to provide feedback on how long a
command took to run.
The initial value of this variable is the time to evaluate your
\f[C]\[ti]/.elvish/rc.elv\f[R] script before printing the first prompt.
.PP
See also \f[C]edit:after-command\f[R].
.PP
.SS $edit:command:binding {#edit:command:binding}
.PP
Key bindings for command mode.
This is currently a very small subset of Vi command mode bindings.
.PP
See also \f[C]edit:command:start\f[R].
.PP
.SS $edit:completion:arg-completer {#edit:completion:arg-completer}
.PP
A map containing argument completers.
.PP
.SS $edit:completion:binding {#edit:completion:binding}
.PP
Keybinding for the completion mode.
.PP
.SS $edit:completion:matcher {#edit:completion:matcher}
.PP
A map mapping from context names to matcher functions.
See the Matcher section.
.PP
.SS $edit:current-command {#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[R] has been invoked.
.PP
This API is subject to change.
.PP
.SS $edit:-dot {#edit:-dot}
.PP
Contains the current position of the cursor, as a byte position within
\f[C]$edit:current-command\f[R].
.PP
.SS $edit:exceptions {#edit:exceptions}
.PP
A list of exceptions thrown from callbacks such as prompts.
Useful for examining tracebacks and other metadata.
.PP
.SS $edit:global-binding {#edit:global-binding}
.PP
Global keybindings, consulted for keys not handled by mode-specific
bindings.
.PP
See Keybindings.
.PP
.SS $edit:history:binding {#edit:history:binding}
.PP
Binding table for the history mode.
.PP
.SS $edit:-instant:binding {#edit:-instant:binding}
.PP
Binding for the instant mode.
.PP
.SS $edit:location:hidden {#edit:location:hidden}
.PP
A list of directories to hide in the location addon.
.PP
.SS $edit:location:pinned {#edit:location:pinned}
.PP
A list of directories to always show at the top of the list of the
location addon.
.PP
.SS $edit:location:workspaces {#edit:location:workspaces}
.PP
A map mapping types of workspaces to their patterns.
.PP
.SS $edit:max-height {#edit:max-height}
.PP
Maximum height the editor is allowed to use, defaults to \f[C]+Inf\f[R].
.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.
.PP
.SS $edit:navigation:binding {#edit:navigation:binding}
.PP
Keybinding for the navigation mode.
.PP
.SS $edit:navigation:width-ratio {#edit:navigation:width-ratio}
.PP
A list of 3 integers, used for specifying the width ratio of the 3
columns in navigation mode.
.PP
.SS $edit:prompt {#edit:prompt}
.PP
See Prompts.
.PP
.SS $edit:-prompt-eagerness {#edit:-prompt-eagerness}
.PP
See Prompt Eagerness.
.PP
.SS $edit:prompt-stale-threshold {#edit:prompt-stale-threshold}
.PP
See Stale Prompt.
.PP
.SS $edit:prompt-stale-transformer. {#edit:prompt-stale-transformer.}
.PP
See Stale Prompt.
.PP
.SS $edit:rprompt {#edit:rprompt}
.PP
See Prompts.
.PP
.SS $edit:-rprompt-eagerness {#edit:-rprompt-eagerness}
.PP
See Prompt Eagerness.
.PP
.SS $edit:rprompt-persistent {#edit:rprompt-persistent}
.PP
See RPrompt Persistency.
.PP
.SS $edit:rprompt-stale-threshold {#edit:rprompt-stale-threshold}
.PP
See Stale Prompt.
.PP
.SS $edit:rprompt-stale-transformer. {#edit:rprompt-stale-transformer.}
.PP
See Stale Prompt.
.PP
.SS $edit:selected-file {#edit:selected-file}
.PP
Name of the currently selected file in navigation mode.
$nil if not in navigation mode.
.PP
.SS $edit:small-word-abbr {#edit:small-word-abbr}
.PP
A map from small-word abbreviations and their expansions.
.PP
A small-word abbreviation is replaced by its expansion after it is typed
in full and consecutively, and followed by another character (the
\f[I]trigger\f[R] character).
Furthermore, the expansion requires the following conditions to be
satisfied:
.IP \[bu] 2
The end of the abbreviation must be adjacent to a small-word boundary,
i.e.
the last character of the abbreviation and the trigger character must be
from two different small-word categories.
.IP \[bu] 2
The start of the abbreviation must also be adjacent to a small-word
boundary, unless it appears at the beginning of the code buffer.
.IP \[bu] 2
The cursor must be at the end of the buffer.
.PP
If more than one abbreviations would match, the longest one is used.
.PP
As an example, with the following configuration:
.IP
.nf
\f[C]
edit:small-word-abbr[\[aq]gcm\[aq]] = \[aq]git checkout master\[aq]
\f[R]
.fi
.PP
In the following scenarios, the \f[C]gcm\f[R] abbreviation is expanded:
.IP \[bu] 2
With an empty buffer, typing \f[C]gcm\f[R] and a space or semicolon;
.IP \[bu] 2
When the buffer ends with a space, typing \f[C]gcm\f[R] and a space or
semicolon.
.PP
The space or semicolon after \f[C]gcm\f[R] is preserved in both cases.
.PP
In the following scenarios, the \f[C]gcm\f[R] abbreviation is
\f[B]not\f[R] expanded:
.IP \[bu] 2
With an empty buffer, typing \f[C]Xgcm\f[R] and a space or semicolon
(start of abbreviation is not adjacent to a small-word boundary);
.IP \[bu] 2
When the buffer ends with \f[C]X\f[R], typing \f[C]gcm\f[R] and a space
or semicolon (end of abbreviation is not adjacent to a small-word
boundary);
.IP \[bu] 2
When the buffer is non-empty, move the cursor to the beginning, and
typing \f[C]gcm\f[R] and a space (cursor not at the end of the buffer).
.PP
This example shows the case where the abbreviation consists of a single
small word of alphanumerical characters, but that doesn\[cq]t have to be
the case.
For example, with the following configuration:
.IP
.nf
\f[C]
edit:small-word-abbr[\[aq]>dn\[aq]] = \[aq] 2>/dev/null\[aq]
\f[R]
.fi
.PP
The abbreviation \f[C]>dn\f[R] starts with a punctuation character, and
ends with an alphanumerical character.
This means that it is expanded when it borders a whitespace or
alphanumerical character to the left, and a whitespace or punctuation to
the right; for example, typing \f[C]ls>dn;\f[R] will expand it.
.PP
Some extra examples of small-word abbreviations:
.IP
.nf
\f[C]
edit:small-word-abbr[\[aq]gcp\[aq]] = \[aq]git cherry-pick -x\[aq]
edit:small-word-abbr[\[aq]ll\[aq]] = \[aq]ls -ltr\[aq]
\f[R]
.fi
.PP
If both a simple abbreviation and a small-word abbreviation can be
expanded, the simple abbreviation has priority.
.PP
See also \f[C]edit:abbr\f[R].
.SH Functions
.PP
.SS edit:add-var {#edit:add-var}
.IP
.nf
\f[C]
edit:add-var $name $value
\f[R]
.fi
.PP
Declares a new variable in the REPL.
The new variable becomes available during the next REPL cycle.
.PP
Equivalent to running \f[C]var $name = $value\f[R] at the REPL, but
\f[C]$name\f[R] can be dynamic.
.PP
Example:
.IP
.nf
\f[C]
\[ti]> edit:add-var foo bar
\[ti]> put $foo
\[u25B6] bar
\f[R]
.fi
.PP
.SS edit:add-vars {#edit:add-vars}
.IP
.nf
\f[C]
edit:add-vars $map
\f[R]
.fi
.PP
Takes a map from strings to arbitrary values.
Equivalent to calling \f[C]edit:add-var\f[R] for each key-value pair in
the map.
.PP
.SS edit:binding-table {#edit:binding-table}
.PP
Converts a normal map into a binding map.
.PP
.SS edit:clear {#edit:clear}
.IP
.nf
\f[C]
edit:clear
\f[R]
.fi
.PP
Clears the screen.
.PP
This command should be used in place of the external \f[C]clear\f[R]
command to clear the screen.
.PP
.SS edit:close-mode {#edit:close-mode}
.PP
Closes the current active mode.
.PP
.SS edit:command-history {#edit:command-history}
.IP
.nf
\f[C]
edit:command-history &cmd-only=$false &dedup=$false &newest-first
\f[R]
.fi
.PP
Outputs the command history.
.PP
By default, each entry is represented as a map, with an \f[C]id\f[R] key
key for the sequence number of the command, and a \f[C]cmd\f[R] key for
the text of the command.
If \f[C]&cmd-only\f[R] is \f[C]$true\f[R], only the text of each command
is output.
.PP
All entries are output by default.
If \f[C]&dedup\f[R] is \f[C]$true\f[R], only the most recent instance of
each command (when comparing just the \f[C]cmd\f[R] key) is output.
.PP
Commands are are output in oldest to newest order by default.
If \f[C]&newest-first\f[R] is \f[C]$true\f[R] the output is in newest to
oldest order instead.
.PP
As an example, either of the following extracts the text of the most
recent command:
.IP
.nf
\f[C]
edit:command-history | put [(all)][-1][cmd]
edit:command-history &cmd-only &newest-first | take 1
\f[R]
.fi
.PP
See also \f[C]builtin:dir-history\f[R].
.PP
.SS edit:command:start {#edit:command:start}
.PP
Enter command mode.
This mode is intended to emulate Vi\[cq]s command mode, but it is very
incomplete right now.
.PP
See also \f[C]edit:command:binding\f[R].
.PP
.SS edit:complete-filename {#edit:complete-filename}
.IP
.nf
\f[C]
edit:complete-filename $args...
\f[R]
.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[R] objects.
.PP
This function is the default handler for any commands without explicit
handlers in \f[C]$edit:completion:arg-completer\f[R].
See Argument Completer.
.PP
Example:
.IP
.nf
\f[C]
\[ti]> edit:complete-filename \[aq]\[aq]
\[u25B6] (edit:complex-candidate Applications &code-suffix=/ &style=\[aq]01;34\[aq])
\[u25B6] (edit:complex-candidate Books &code-suffix=/ &style=\[aq]01;34\[aq])
\[u25B6] (edit:complex-candidate Desktop &code-suffix=/ &style=\[aq]01;34\[aq])
\[u25B6] (edit:complex-candidate Docsafe &code-suffix=/ &style=\[aq]01;34\[aq])
\[u25B6] (edit:complex-candidate Documents &code-suffix=/ &style=\[aq]01;34\[aq])
\&...
\[ti]> edit:complete-filename .elvish/
\[u25B6] (edit:complex-candidate .elvish/aliases &code-suffix=/ &style=\[aq]01;34\[aq])
\[u25B6] (edit:complex-candidate .elvish/db &code-suffix=\[aq] \[aq] &style=\[aq]\[aq])
\[u25B6] (edit:complex-candidate .elvish/epm-installed &code-suffix=\[aq] \[aq] &style=\[aq]\[aq])
\[u25B6] (edit:complex-candidate .elvish/lib &code-suffix=/ &style=\[aq]01;34\[aq])
\[u25B6] (edit:complex-candidate .elvish/rc.elv &code-suffix=\[aq] \[aq] &style=\[aq]\[aq])
\f[R]
.fi
.PP
.SS edit:complete-getopt {#edit:complete-getopt}
.IP
.nf
\f[C]
edit:complete-getopt $args $opt-specs $arg-handlers
\f[R]
.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[R] 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]$opt-specs\f[R] 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[R] starts with a dash, but not otherwise.
Each map can contain the following keys (at least one of \f[C]short\f[R]
or \f[C]long\f[R] needs to be specified):
.RS 2
.IP \[bu] 2
\f[C]short\f[R] contains the one-letter short option, if any, without
the dash.
.IP \[bu] 2
\f[C]long\f[R] contains the long option name, if any, without the
initial two dashes.
.IP \[bu] 2
\f[C]arg-optional\f[R], if set to \f[C]$true\f[R], specifies that the
option receives an optional argument.
.IP \[bu] 2
\f[C]arg-required\f[R], if set to \f[C]$true\f[R], specifies that the
option receives a mandatory argument.
Only one of \f[C]arg-optional\f[R] or \f[C]arg-required\f[R] can be set
to \f[C]$true\f[R].
.IP \[bu] 2
\f[C]desc\f[R] can be set to a human-readable description of the option
which will be displayed in the completion menu.
.IP \[bu] 2
\f[C]completer\f[R] can be set to a function to generate possible
completions for the option argument.
The function receives as argument the element at that position and
return zero or more candidates.
.RE
.IP \[bu] 2
\f[C]$arg-handlers\f[R] 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[R],
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[R].
If the last element of the list is the string \f[C]...\f[R], then the
last handler is reused for all following arguments.
.PP
Example:
.IP
.nf
\f[C]
\[ti]> fn complete {|\[at]args|
     opt-specs = [ [&short=a &long=all &desc=\[dq]Show all\[dq]]
                   [&short=n &desc=\[dq]Set name\[dq] &arg-required=$true
                    &completer= {|_| put name1 name2 }] ]
     arg-handlers = [ {|_| put first1 first2 }
                      {|_| put second1 second2 } ... ]
     edit:complete-getopt $args $opt-specs $arg-handlers
   }
\[ti]> complete \[aq]\[aq]
\[u25B6] first1
\[u25B6] first2
\[ti]> complete \[aq]-\[aq]
\[u25B6] (edit:complex-candidate -a &display=\[aq]-a (Show all)\[aq])
\[u25B6] (edit:complex-candidate --all &display=\[aq]--all (Show all)\[aq])
\[u25B6] (edit:complex-candidate -n &display=\[aq]-n (Set name)\[aq])
\[ti]> complete -n \[aq]\[aq]
\[u25B6] name1
\[u25B6] name2
\[ti]> complete -a \[aq]\[aq]
\[u25B6] first1
\[u25B6] first2
\[ti]> complete arg1 \[aq]\[aq]
\[u25B6] second1
\[u25B6] second2
\[ti]> complete arg1 arg2 \[aq]\[aq]
\[u25B6] second1
\[u25B6] second2
\f[R]
.fi
.PP
.SS edit:completion:close {#edit:completion:close}
.PP
Closes the completion mode UI.
.PP
.SS edit:completion:smart-start {#edit:completion:smart-start}
.PP
Starts the completion mode.
However, if all the candidates share a non-empty prefix and that prefix
starts with the seed, inserts the prefix instead.
.PP
.SS edit:completion:start {#edit:completion:start}
.PP
Start the completion mode.
.PP
.SS edit:complex-candidate {#edit:complex-candidate}
.IP
.nf
\f[C]
edit:complex-candidate $stem &display=\[aq]\[aq] &code-suffix=\[aq]\[aq]
\f[R]
.fi
.PP
Builds a complex candidate.
This is mainly useful in argument completers.
.PP
The \f[C]&display\f[R] option controls how the candidate is shown in the
UI.
It can be a string or a styled text.
If it is empty, \f[C]$stem\f[R] is used.
.PP
The \f[C]&code-suffix\f[R] option affects how the candidate is inserted
into the code when it is accepted.
By default, a quoted version of \f[C]$stem\f[R] is inserted.
If \f[C]$code-suffix\f[R] is non-empty, it is added to that text, and
the suffix is not quoted.
.PP
.SS edit:-dump-buf {#edit:-dump-buf}
.PP
Dumps the current UI buffer as HTML.
This command is used to generate \[lq]ttyshots\[rq] on the
website (https://elv.sh).
.PP
Example:
.IP
.nf
\f[C]
ttyshot = \[ti]/a.html
edit:insert:binding[Ctrl-X] = { edit:-dump-buf > $tty }
\f[R]
.fi
.PP
.SS edit:end-of-history {#edit:end-of-history}
.PP
Adds a notification saying \[lq]End of history\[rq].
.PP
.SS edit:history:down {#edit:history:down}
.PP
Walks to the next entry in history mode.
.PP
.SS edit:history:down-or-quit {#edit:history:down-or-quit}
.PP
Walks to the next entry in history mode, or quit the history mode if
already at the newest entry.
.PP
.SS edit:history:fast-forward {#edit:history:fast-forward}
.PP
Import command history entries that happened after the current session
started.
.PP
.SS edit:history:start {#edit:history:start}
.PP
Starts the history mode.
.PP
.SS edit:history:up {#edit:history:up}
.PP
Walks to the previous entry in history mode.
.PP
.SS edit:insert-at-dot {#edit:insert-at-dot}
.IP
.nf
\f[C]
edit:insert-at-dot $text
\f[R]
.fi
.PP
Inserts the given text at the dot, moving the dot after the newly
inserted text.
.PP
.SS edit:insert-last-word {#edit:insert-last-word}
.PP
Inserts the last word of the last command.
.PP
.SS edit:insert-raw {#edit:insert-raw}
.PP
Requests the next terminal input to be inserted uninterpreted.
.PP
.SS edit:-instant:start {#edit:-instant:start}
.PP
Starts the instant mode.
In instant mode, any text entered at the command line is evaluated
immediately, with the output displayed.
.PP
\f[B]WARNING\f[R]: Beware of unintended consequences when using
destructive commands.
For example, if you type \f[C]sudo rm -rf /tmp/*\f[R] in the instant
mode, Elvish will attempt to evaluate \f[C]sudo rm -rf /\f[R] when you
typed that far.
.PP
.SS edit:key {#edit:key}
.IP
.nf
\f[C]
edit:key $string
\f[R]
.fi
.PP
Parses a string into a key.
.PP
.SS edit:kill-alnum-word-left {#edit:kill-alnum-word-left}
.PP
Deletes the the last alnum word to the left of the dot.
.PP
.SS edit:kill-alnum-word-right {#edit:kill-alnum-word-right}
.PP
Deletes the the first alnum word to the right of the dot.
.PP
.SS edit:kill-line-left {#edit:kill-line-left}
.PP
Deletes the text between the dot and the start of the current line.
.PP
.SS edit:kill-line-right {#edit:kill-line-right}
.PP
Deletes the text between the dot and the end of the current line.
.PP
.SS edit:kill-rune-left {#edit:kill-rune-left}
.PP
Kills one rune right of the dot.
Does nothing if the dot is at the end of the buffer.
.PP
.SS edit:kill-small-word-left {#edit:kill-small-word-left}
.PP
Deletes the the last small word to the left of the dot.
.PP
.SS edit:kill-small-word-right {#edit:kill-small-word-right}
.PP
Deletes the the first small word to the right of the dot.
.PP
.SS edit:kill-word-left {#edit:kill-word-left}
.PP
Deletes the the last word to the left of the dot.
.PP
.SS edit:kill-word-right {#edit:kill-word-right}
.PP
Deletes the the first word to the right of the dot.
.PP
.SS edit:listing:accept {#edit:listing:accept}
.PP
Accepts the current selected listing item.
.PP
.SS edit:listing:down {#edit:listing:down}
.PP
Moves the cursor down in listing mode.
.PP
.SS edit:listing:down-cycle {#edit:listing:down-cycle}
.PP
Moves the cursor down in listing mode, or to the first item if the last
item is currently selected.
.PP
.SS edit:listing:left {#edit:listing:left}
.PP
Moves the cursor left in listing mode.
.PP
.SS edit:listing:page-down {#edit:listing:page-down}
.PP
Moves the cursor down one page.
.PP
.SS edit:listing:page-up {#edit:listing:page-up}
.PP
Moves the cursor up one page.
.PP
.SS edit:listing:right {#edit:listing:right}
.PP
Moves the cursor right in listing mode.
.PP
.SS edit:listing:start-custom {#edit:listing:start-custom}
.PP
Starts a custom listing addon.
.PP
.SS edit:listing:up {#edit:listing:up}
.PP
Moves the cursor up in listing mode.
.PP
.SS edit:listing:up-cycle {#edit:listing:up-cycle}
.PP
Moves the cursor up in listing mode, or to the last item if the first
item is currently selected.
.PP
.SS edit:match-prefix {#edit:match-prefix}
.IP
.nf
\f[C]
edit:match-prefix $seed $inputs?
\f[R]
.fi
.PP
For each input, outputs whether the input has $seed as a prefix.
Uses the result of \f[C]to-string\f[R] for non-string inputs.
.PP
Roughly equivalent to the following Elvish function, but more efficient:
.IP
.nf
\f[C]
use str
fn match-prefix {|seed \[at]input|
  each {|x| str:has-prefix (to-string $x) $seed } $\[at]input
}
\f[R]
.fi
.PP
.SS edit:match-subseq {#edit:match-subseq}
.IP
.nf
\f[C]
edit:match-subseq $seed $inputs?
\f[R]
.fi
.PP
For each input, outputs whether the input has $seed as a
subsequence (https://en.wikipedia.org/wiki/Subsequence).
Uses the result of \f[C]to-string\f[R] for non-string inputs.
.PP
.SS edit:match-substr {#edit:match-substr}
.IP
.nf
\f[C]
edit:match-substr $seed $inputs?
\f[R]
.fi
.PP
For each input, outputs whether the input has $seed as a substring.
Uses the result of \f[C]to-string\f[R] for non-string inputs.
.PP
Roughly equivalent to the following Elvish function, but more efficient:
.IP
.nf
\f[C]
use str
fn match-substr {|seed \[at]input|
  each {|x| str:has-contains (to-string $x) $seed } $\[at]input
}
\f[R]
.fi
.PP
.SS edit:move-dot-down {#edit:move-dot-down}
.PP
Moves the dot down one line, trying to preserve the visual horizontal
position.
Does nothing if dot is already on the last line of the buffer.
.PP
.SS edit:move-dot-eol {#edit:move-dot-eol}
.PP
Moves the dot to the end of the current line.
.PP
.SS edit:move-dot-left {#edit:move-dot-left}
.PP
Moves the dot left one rune.
Does nothing if the dot is at the beginning of the buffer.
.PP
.SS edit:move-dot-left-alnum-word {#edit:move-dot-left-alnum-word}
.PP
Moves the dot to the beginning of the last alnum word to the left of the
dot.
.PP
.SS edit:move-dot-left-small-word {#edit:move-dot-left-small-word}
.PP
Moves the dot to the beginning of the last small word to the left of the
dot.
.PP
.SS edit:move-dot-left-word {#edit:move-dot-left-word}
.PP
Moves the dot to the beginning of the last word to the left of the dot.
.PP
.SS edit:move-dot-right {#edit:move-dot-right}
.PP
Moves the dot right one rune.
Does nothing if the dot is at the end of the buffer.
.PP
.SS edit:move-dot-right-alnum-word {#edit:move-dot-right-alnum-word}
.PP
Moves the dot to the beginning of the first alnum word to the right of
the dot.
.PP
.SS edit:move-dot-right-small-word {#edit:move-dot-right-small-word}
.PP
Moves the dot to the beginning of the first small word to the right of
the dot.
.PP
.SS edit:move-dot-right-word {#edit:move-dot-right-word}
.PP
Moves the dot to the beginning of the first word to the right of the
dot.
.PP
.SS edit:move-dot-sol {#edit:move-dot-sol}
.PP
Moves the dot to the start of the current line.
.PP
.SS edit:move-dot-up {#edit:move-dot-up}
.PP
Moves the dot up one line, trying to preserve the visual horizontal
position.
Does nothing if dot is already on the first line of the buffer.
.PP
.SS edit:navigation:insert-selected {#edit:navigation:insert-selected}
.PP
Inserts the selected filename.
.PP
.SS edit:navigation:insert-selected-and-quit {#edit:navigation:insert-selected-and-quit}
.PP
Inserts the selected filename and closes the navigation addon.
.PP
.SS edit:navigation:start {#edit:navigation:start}
.PP
Start the navigation mode.
.PP
.SS edit:navigation:trigger-filter {#edit:navigation:trigger-filter}
.PP
Toggles the filtering status of the navigation addon.
.PP
.SS edit:navigation:trigger-shown-hidden {#edit:navigation:trigger-shown-hidden}
.PP
Toggles whether the navigation addon should be showing hidden files.
.PP
.SS edit:notify {#edit:notify}
.IP
.nf
\f[C]
edit:notify $message
\f[R]
.fi
.PP
Prints a notification message.
.PP
If called while the editor is active, this will print the message above
the editor, and redraw the editor.
.PP
If called while the editor is inactive, the message will be queued, and
shown once the editor becomes active.
.PP
.SS edit:redraw {#edit:redraw}
.IP
.nf
\f[C]
edit:redraw &full=$false
\f[R]
.fi
.PP
Triggers a redraw.
.PP
The \f[C]&full\f[R] option controls whether to do a full redraw.
By default, all redraws performed by the line editor are incremental
redraws, updating only the part of the screen that has changed from the
last redraw.
A full redraw updates the entire command line.
.PP
.SS edit:replace-input {#edit:replace-input}
.IP
.nf
\f[C]
edit:replace-input $text
\f[R]
.fi
.PP
Equivalent to assigning \f[C]$text\f[R] to
\f[C]$edit:current-command\f[R].
.PP
.SS edit:return-eof {#edit:return-eof}
.PP
Causes the Elvish REPL to terminate.
If called from a key binding, takes effect after the key binding
returns.
.PP
.SS edit:return-line {#edit:return-line}
.PP
Causes the Elvish REPL to end the current read iteration and evaluate
the code it just read.
If called from a key binding, takes effect after the key binding
returns.
.PP
.SS edit:smart-enter {#edit:smart-enter}
.PP
Inserts a literal newline if the current code is not syntactically
complete Elvish code.
Accepts the current line otherwise.
.PP
.SS edit:transpose-alnum-word {#edit:transpose-alnum-word}
.PP
Swaps the alnum words to the left and right of the dot.
If the dot is at the beginning of the buffer, it swaps the first two
alnum words, and if the dot is at the end, it swaps the last two.
.PP
.SS edit:transpose-rune {#edit:transpose-rune}
.PP
Swaps the runes to the left and right of the dot.
If the dot is at the beginning of the buffer, swaps the first two runes,
and if the dot is at the end, it swaps the last two.
.PP
.SS edit:transpose-small-word {#edit:transpose-small-word}
.PP
Swaps the small words to the left and right of the dot.
If the dot is at the beginning of the buffer, it swaps the first two
small words, and if the dot is at the end, it swaps the last two.
.PP
.SS edit:transpose-word {#edit:transpose-word}
.PP
Swaps the words to the left and right of the dot.
If the dot is at the beginning of the buffer, swaps the first two words,
and the dot is at the end, it swaps the last two.
.PP
.SS edit:wordify {#edit:wordify}
.IP
.nf
\f[C]
edit:wordify $code
\f[R]
.fi
.PP
Breaks Elvish code into words.