068623e1c8
For the "completions" option type, the documentation states that | and \ need to be escaped as \| and \\. The same parser is for other option types that are lists-of-tuples: range-specs and line-specs, so they need escaping too. Document that. Only their last element can contain arbitrary data, so range-specs and line-specs could work without escaping if we tweaked the parser.
398 lines
14 KiB
Plaintext
398 lines
14 KiB
Plaintext
= Options
|
|
|
|
== Description
|
|
|
|
Kakoune can store named and typed values that can be used both to
|
|
customize the core editor behaviour, and to store data used by extension
|
|
scripts.
|
|
|
|
[[set-option]]
|
|
Options can be modified using the `set-option` command:
|
|
|
|
--------------------------------------------
|
|
set-option [-add|-remove] <scope> <name> <values>...
|
|
--------------------------------------------
|
|
|
|
<scope> can be *global*, *buffer*, *window* or *current* (See
|
|
<<scopes#,`:doc scopes`>>). *current* relates to the narrowest scope in
|
|
which the option is already set.
|
|
|
|
When the option is a list or a map, multiple <values> can be given as
|
|
separate arguments, or can be omitted altogether in order to empty the
|
|
option.
|
|
|
|
If `-add` or `-remove` is specified, the new value is respectively *added*
|
|
to or *removed* from the current one instead of replacing it (the exact
|
|
outcome depends on the type, see below).
|
|
|
|
[[unset-option]]
|
|
Options values can be unset in a specific scope with the `unset-option`
|
|
command:
|
|
|
|
---------------------------
|
|
unset-option <scope> <name>
|
|
---------------------------
|
|
|
|
Unsetting an option will make it fallback to the value of its parent scope,
|
|
hence options cannot be unset from the *global* scope.
|
|
|
|
[[declare-option]]
|
|
New options can be declared using the `declare-option` command:
|
|
|
|
---------------------------------------------------
|
|
declare-option [-hidden] <type> <name> [<value>...]
|
|
---------------------------------------------------
|
|
|
|
If `-hidden` is specified, the option will not be displayed in completion
|
|
suggestions.
|
|
|
|
[[update-option]]
|
|
Certain option type can be *updated*, usually to match potential changes
|
|
in the buffer they relate to. This can be triggered by the `update-option`
|
|
command:
|
|
|
|
----------------------------
|
|
update-option <scope> <name>
|
|
----------------------------
|
|
|
|
== Types
|
|
|
|
All options have a type, which defines how they are translated to/from
|
|
text and their set of valid values.
|
|
|
|
Some types are usable for user defined options while some other types
|
|
are exclusively available to built-in options.
|
|
|
|
*int*::
|
|
an integer number.
|
|
|
|
`set -add` performs a math addition. +
|
|
`set -remove` performs a math substraction. +
|
|
|
|
*bool*::
|
|
a boolean value, yes/true or no/false
|
|
|
|
*str*::
|
|
a string, some freeform text
|
|
|
|
*regex*::
|
|
as a string but the set commands will complain if the entered text
|
|
is not a valid regex
|
|
|
|
*coord*::
|
|
a line, column pair (separated by a comma)
|
|
Cannot be used with `declare-option`
|
|
|
|
*<type>-list*::
|
|
a list, elements are specified as separate arguments to the command.
|
|
|
|
`set -add` appends the new element to the list. +
|
|
`set -remove` removes each given element from the list. +
|
|
|
|
Only `int-list` and `str-list` options can be created with
|
|
`declare-option`.
|
|
|
|
*range-specs*::
|
|
a timestamp (like `%val{timestamp}`,
|
|
see <<expansions#value-expansions,`:doc expansions value-expansions`>>)
|
|
followed by a list of range descriptors.
|
|
|
|
Each range descriptor must use the syntax `a.b,c.d|string` or
|
|
`a.b+length|string`, with:
|
|
|
|
* _a_ is the line containing the first character
|
|
|
|
* _b_ is the number of bytes from the start of the line to the
|
|
first byte of the first character
|
|
|
|
* _c_ is the line containing the last character
|
|
|
|
* _d_ is the number of bytes from the start of the line to the
|
|
first byte of the last character
|
|
|
|
* _length_ is the length of the range in bytes, if 0 the range
|
|
is empty, but still valid.
|
|
|
|
* _string_ is an arbitrary string which is associated with
|
|
the range. Any `|` or `\` characters must be escaped as `\|` or `\\`.
|
|
|
|
All numeric fields are 1-based.
|
|
|
|
When the command `update-option` is used on an option of this type,
|
|
its ranges get updated according to all the buffer modifications
|
|
that happened since its timestamp.
|
|
|
|
`set -add` appends the new pairs to the list. +
|
|
`set -remove` removes the given pairs from the list. +
|
|
|
|
See <<highlighters#specs-highlighters,`:doc highlighters specs-highlighters`>>)
|
|
|
|
*line-specs*::
|
|
a list of a line number and a corresponding flag (`<line>|<flag
|
|
text>`), except for the first element which is just the timestamp
|
|
of the buffer. When `update-option` is used on an option of this
|
|
type, its lines get updated according to all the buffer modifications
|
|
that happened since its timestamp.
|
|
See <<highlighters#specs-highlighters,`:doc highlighters specs-highlighters`>>)
|
|
|
|
`set -add` appends the new specs to the list. +
|
|
`set -remove` removes the given specs from the list. +
|
|
|
|
Any `|` or `\` characters that occur within `<flag text>` must be
|
|
escaped as `\|` or `\\`.
|
|
|
|
*completions*::
|
|
a list of `<text>|<select cmd>|<menu text>` candidates,
|
|
except for the first element which follows the
|
|
`<line>.<column>[+<length>]@<timestamp>` format to define where the
|
|
completion apply in the buffer.
|
|
Any `|` or `\` characters that occur within the `<text>`,
|
|
`<select cmd>`, or `<menu text>` fields should be escaped as `\|`
|
|
or `\\`.
|
|
|
|
Select commands are arbitrary Kakoune commands that will be executed
|
|
each time the element is selected in the menu. The common use case is
|
|
to display element specific documentation.
|
|
|
|
Markup can be used in the menu text.
|
|
(see <<faces#markup-strings,`:doc faces markup-strings`>>)
|
|
|
|
`set -add` adds given completions to the list. +
|
|
`set -remove` removes given completions from the list. +
|
|
|
|
*enum(value1|value2|...)*::
|
|
an enum, taking one of the given values
|
|
Cannot be used with `declare-option`
|
|
|
|
*flags(value1|value2|...)*::
|
|
a set of flags, taking a combination of the given values joined by a
|
|
'|' character.
|
|
|
|
`set -add` adds the given flags to the combination. +
|
|
`set -remove` removes the given flags to the combination. +
|
|
|
|
Cannot be used with `declare-option`
|
|
|
|
*<type>-to-<type>-map*::
|
|
a list of `key=value` pairs.
|
|
|
|
`set -add` adds the given pair to the hashmap or replace an already
|
|
existing key. +
|
|
`set -remove` removes the given pair from the hashmap, if only the
|
|
key is provided it removes that entry regardless of the associated
|
|
value. +
|
|
|
|
Only `str-to-str-map` options can be created with `declare-option`.
|
|
|
|
== Builtin options
|
|
|
|
*tabstop* `int`::
|
|
_default_ 8 +
|
|
width of a tab character
|
|
|
|
*indentwidth* `int`::
|
|
_default_ 4 +
|
|
width (in spaces) used for indentation, 0 means a tab character
|
|
|
|
*scrolloff* `coord`::
|
|
_default_ 0,0 +
|
|
number of lines, columns to keep visible around the cursor when
|
|
scrolling
|
|
|
|
*eolformat* `enum(lf|crlf)`::
|
|
_default_ lf +
|
|
the format of end of lines when writing a buffer, this is autodetected
|
|
on load; values of this option assigned to the `window` scope are
|
|
ignored
|
|
|
|
*BOM* `enum(none|utf8)`::
|
|
_default_ none +
|
|
define if the file should be written with a unicode byte order mark;
|
|
values of this option assigned to the `window` scope are ignored
|
|
|
|
*readonly* `bool`::
|
|
_default_ false +
|
|
prevent modifications from being saved to disk, all buffers if set
|
|
to `true` in the `global` scope, or current buffer if set in the
|
|
`buffer` scope; values of this option assigned to the `window`
|
|
scope are ignored
|
|
|
|
*incsearch* `bool`::
|
|
_default_ true +
|
|
execute search as it is typed
|
|
|
|
*aligntab* `bool`::
|
|
_default_ false +
|
|
use tabs for alignment command
|
|
|
|
*autoinfo* `flags(command|onkey|normal)`::
|
|
_default_ command|onkey +
|
|
display automatic information box in the enabled contexts
|
|
|
|
*autocomplete* `flags(insert|prompt)`::
|
|
_default_ insert|prompt +
|
|
automatically display possible completions in the enabled modes.
|
|
|
|
*ignored_files* `regex`::
|
|
filenames matching this regex won't be considered as candidates
|
|
on filename completion (except if the text being completed already
|
|
matches it)
|
|
|
|
*disabled_hooks* `regex`::
|
|
hooks whose group matches this regex won't be executed. For example
|
|
indentation hooks can be disabled with `.*-indent`.
|
|
(See <<hooks#disabling-hooks,`:doc hooks`>>)
|
|
|
|
*filetype* `str`::
|
|
arbitrary string defining the type of the file. Filetype dependent
|
|
actions should hook on this option changing for activation/deactivation
|
|
|
|
*path* `str-list`::
|
|
_default_ ./ %/ /usr/include +
|
|
directories to search for *gf* command and filenames completion
|
|
`%/` represents the current buffer directory
|
|
|
|
*completers* `completer-list`::
|
|
_default_ filename word=all +
|
|
completion engines to use for insert mode completion (they are tried
|
|
in order until one generates candidates). Existing completers are:
|
|
|
|
*word=all*, *word=buffer*:::
|
|
which complete using words in all buffers (*word=all*)
|
|
or only the current one (*word=buffer*)
|
|
|
|
*filename*:::
|
|
which tries to detect when a filename is being entered and
|
|
provides completion based on local filesystem
|
|
|
|
*line=all*, *line=buffer*:::
|
|
which complete using lines in all buffers (*line=all*)
|
|
or only the current one (*line=buffer*)
|
|
|
|
*option=<opt-name>*:::
|
|
where *opt-name* is an option of type 'completions' whose
|
|
contents will be used
|
|
|
|
*static_words* `str-list`::
|
|
list of words that are always added to completion candidates
|
|
when completing words in insert mode
|
|
|
|
*extra_word_chars* `codepoint-list`::
|
|
a list of all additional codepoints that should be considered
|
|
part of a word, for the purposes of the `w`, `b`, and `e` commands
|
|
(See <<keys#movement,`:doc keys movement`>>).
|
|
If this option is empty, Kakoune pretends it contains an
|
|
underscore, otherwise the value is used as-is.
|
|
This must be set on the buffer, not the window,
|
|
for word completion to offer words containing these codepoints.
|
|
|
|
*matching_pairs* `codepoint-list`::
|
|
_default_ ( ) { } [ ] < > +
|
|
a list of codepoints that are to be treated as matching pairs
|
|
for the *m* command.
|
|
|
|
*autoreload* `enum(yes|no|ask)`::
|
|
_default_ ask +
|
|
auto reload the buffers when an external modification is detected
|
|
|
|
*writemethod* `enum(overwrite|replace)`::
|
|
_default_ overwrite +
|
|
method used to write buffers to file, `overwrite` will open the
|
|
existing file and write on top of the previous data, `replace`
|
|
will open a temporary file next to the target file, write it and
|
|
then rename it to the target file.
|
|
|
|
*debug* `flags(hooks|shell|profile|keys|commands)`::
|
|
dump various debug information in the '\*debug*' buffer
|
|
|
|
*idle_timeout* `int`::
|
|
_default_ 50 +
|
|
timeout, in milliseconds, with no user input that will trigger the
|
|
*PromptIdle*, *InsertIdle* and *NormalIdle* hooks, and autocompletion.
|
|
|
|
*fs_check_timeout* `int`::
|
|
_default_ 500 +
|
|
timeout, in milliseconds, between checks in normal mode of modifications
|
|
of the file associated with the current buffer on the filesystem.
|
|
|
|
*modelinefmt* `string`::
|
|
A format string used to generate the mode line, that string is
|
|
first expanded as a command line would be (expanding '%...{...}'
|
|
strings), then markup tags are applied (see
|
|
<<faces#markup-strings,`:doc faces markup-strings`>>)
|
|
Two special atoms are available as markup:
|
|
|
|
*`{{mode_info}}`*:::
|
|
Information about the current mode, such as `insert 3 sel` or
|
|
`prompt`. The faces used are StatusLineMode, StatusLineInfo,
|
|
and StatusLineValue.
|
|
|
|
*`{{context_info}}`*:::
|
|
Information such as `[+][recording (@)][no-hooks][new file][fifo]`,
|
|
in face Information.
|
|
|
|
The default value is '%val{bufname} %val{cursor_line}:%val{cursor_char_column} {{context_info}} {{mode_info}} - %val{client}@[%val{session}]'
|
|
|
|
*ui_options* `str-to-str-map`::
|
|
a list of `key=value` pairs that are forwarded to the user
|
|
interface implementation. The NCurses UI support the following options:
|
|
|
|
*terminal_set_title*:::
|
|
if *yes* or *true*, the terminal emulator title will
|
|
be changed
|
|
|
|
*terminal_status_on_top*:::
|
|
if *yes*, or *true* the status line will be placed
|
|
at the top of the terminal rather than at the bottom
|
|
|
|
*terminal_assistant*:::
|
|
specify the nice assistant displayed in info boxes,
|
|
can be *clippy* (the default), *cat*, *dilbert* or *none*
|
|
|
|
*terminal_enable_mouse*:::
|
|
boolean option that enables mouse support
|
|
|
|
*terminal_shift_function_key*:::
|
|
Function key from which shifted function key start, if the
|
|
terminal sends F13 for <s-F1>, this should be set to 12.
|
|
|
|
*terminal_padding_char*:::
|
|
character used to indicate the area out of the displayed buffer
|
|
(defaults to '~')
|
|
|
|
*terminal_padding_fill*:::
|
|
if *yes* or *true*, fill the padding area with the padding character
|
|
instead of displaying a single character at the beginning of the
|
|
padding line (defaults to *false*)
|
|
|
|
*terminal_synchronized*:::
|
|
if *yes* or *true*, emit synchronized output escape sequences and
|
|
reduce terminal output with sequences that could trigger flickering
|
|
if unsynchronized (defaults to *false*)
|
|
|
|
[[startup-info]]
|
|
*startup_info_version* `int`::
|
|
_default_ 0 +
|
|
Controls which messages will be displayed in the startup info box, only messages
|
|
relating to a Kakoune version greater than this value will be displayed. Versions
|
|
are written as a single number: Like `20180413` for version `2018.04.13`
|
|
|
|
== Current values
|
|
|
|
The current value for an option can be viewed using
|
|
<<expansions#option-expansions, `:doc expansions option-expansions`>>.
|
|
|
|
For example, the current value of the `BOM` option can be displayed in the
|
|
status line using the `echo` command:
|
|
|
|
--------------
|
|
echo %opt{BOM}
|
|
--------------
|
|
|
|
The current values for all options can be dumped to the *\*debug*\* buffer using
|
|
the following command:
|
|
|
|
-------------
|
|
debug options
|
|
-------------
|