kakoune/doc/pages/options.asciidoc
Maxime Coste 64f1c31401 Refactor parsing of keys and introduce a builtin key parser mode
By setting the ncurses_builtin_key_parser ui_option to true, we
can disable ncurses parsing of key strokes to get less portable
parsing but support for more complex modifiers.
2018-12-09 21:35:22 +11:00

313 lines
11 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] <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.
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).
[[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.
`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 <<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`, 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
<<highlighters#specs-highlighters,`: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 <<highlighters#specs-highlighters,`:doc highlighters specs-highlighters`>>)
`set -add` appends the new spec to the list
*completions*::
a 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 (see
<<faces#markup-strings,`:doc faces markup-strings`>>) can be used in the
menu text.
`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
*auto_complete* `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*:::
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
<<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:
*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]]
*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`