1f02a1f7e2
Except for the FAQ, it could be fixed, but it does not have to be as formal as the rest of the docs.
265 lines
8.7 KiB
Plaintext
265 lines
8.7 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 <scope> <name> <value>
|
|
---------------------------------
|
|
|
|
<scope> can be *global*, *buffer*, *window* or *current* (See
|
|
<<scopes#,`:doc scopes`>>). *current* relate to the narrowest scope in
|
|
which the option is already set.
|
|
|
|
[[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 mode,
|
|
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
|
|
|
|
*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 comma)
|
|
|
|
*<type>-list*::
|
|
a list, elements are separated by a colon (:) if an element needs
|
|
to contain a colon, it can be escaped with a backslash
|
|
|
|
*range-specs*::
|
|
a `:` separated list of a pair of a buffer range (`<begin
|
|
line>.<begin column>,<end line>.<end column>` or `<begin line>.<begin
|
|
column>+<length>`) and a string (separated by `|`), except for the
|
|
first element which is just the timestamp of the buffer. When the
|
|
`update-option` is used on an option of this type, its ranges gets
|
|
updated according to all the buffer modifications that happened
|
|
since its timestamp.
|
|
|
|
*line-specs*::
|
|
a `:` separated 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 the `update-option` is used on
|
|
an option of this type, its lines gets updated according to all the
|
|
buffer modifications that happened since its timestamp.
|
|
|
|
*completions*::
|
|
a `:` separated list of `<text>|<docstring>|<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. Markup can be used in the menu text.
|
|
|
|
*enum(value1|value2|...)*::
|
|
an enum, taking one of the given values
|
|
|
|
*flags(value1|value2|...)*::
|
|
a set of flags, taking a combination of the given values joined by a
|
|
'|' character
|
|
|
|
== 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
|
|
|
|
*autoshowcompl* `bool`::
|
|
_default_ true +
|
|
automatically display possible completions when editing a prompt
|
|
|
|
*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`
|
|
|
|
*filetype* `str`::
|
|
arbitrary string defining the type of the file filetype dependant
|
|
actions should hook on this option changing for activation/deactivation
|
|
|
|
*path* `str-list`::
|
|
_default_ ./:/usr/include +
|
|
directories to search for gf command
|
|
|
|
*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*:::
|
|
which complete using lines in current 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
|
|
as word character.
|
|
|
|
*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
|
|
|
|
*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_checkout_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 <<expansions#,`:doc expansions`>>)
|
|
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`::
|
|
colon separated list of key=value pairs that are forwarded to the user
|
|
interface implementation. The NCurses UI support the following options:
|
|
|
|
*ncurses_set_title*:::
|
|
if *yes* or *true*, the terminal emulator title will
|
|
be changed
|
|
|
|
*ncurses_status_on_top*:::
|
|
if *yes*, or *true* the status line will be placed
|
|
at the top of the terminal rather than at the bottom
|
|
|
|
*ncurses_assistant*:::
|
|
specify the nice assistant displayed in info boxes,
|
|
can be *clippy* (the default), *cat*, *dilbert* or *none*
|
|
|
|
*ncurses_enable_mouse*:::
|
|
boolean option that enables mouse support
|
|
|
|
*ncurses_change_colors*:::
|
|
boolean option that can disable color palette changing if the
|
|
terminfo enables it but the terminal does not support it.
|
|
|
|
*ncurses_wheel_down_button*, *ncurses_wheel_up_button*:::
|
|
specify which button send for wheel down/up events
|