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.
Options can be modified using the set-option
command:
set-option [-add] <scope> <name> <values>...
<scope> can be global, buffer, window or current
(See :doc scopes
). current relates to the narrowest
scope in which the option is already set.
Multiple <values> can be given as separate arguments when the
option is a list or map.
If -add
is specified, the new value is added to the current one
instead of replacing it (the exact outcome depends on the type, see
below).
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.
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.
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
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 Only int-list
and
str-list
options can be created with declare-option
.
range-specs
a timestamp (like %val{timestamp}
, see
: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
, where 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 and string is an arbitrary string
which is associated with the range. All numeric fields are 1-based. 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. See
:doc highlighters specs-highlighters
)
set -add
appends the new pair to the list
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 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. See
:doc highlighters specs-highlighters
)
set -add
appends the new spec to the list
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.
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 a new completion to 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 new flag to the combination Cannot be
used with declare-option
<type>-to-<type>-map
a list of key=value
pairs. set -add
adds the new pair to the hashmap
or replace an already existing key. 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
: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
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
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_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
: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:
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
ncurses_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.
ncurses_builtin_key_parser
Bypass ncurses key parser and use an internal one.
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
: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