6acc18373d
Some plugins (*cough* kak-lsp) and help texts tend to have immensely long content in a single line. This generates info boxes that span the entire terminal width. This is made especially worse on widescreen monitors or at small text size. This grants user control over how wide these boxes are. I deliberately avoid pushing this change to `kak-lsp` because it's not the only plugin that this could help--see the `hook` help text for an example of this problem in vanilla Kakoune. I would also suggest that since this is a rendering concern, it be handled by the terminal rendering logic.
409 lines
14 KiB
Plaintext
409 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]]
|
|
Option 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 `\\`.
|
|
|
|
Options of this type are are meant to be added to the `completers`
|
|
option to provide insert mode completion. Candidates are shown if the
|
|
text typed by the user (between `<line>.<column>` and the cursor) is a
|
|
subsequence of `<text>`.
|
|
|
|
For each remaining candidate, the completion menu displays
|
|
`<text>`, followed by `<menu text>`, which is a Markup string (see
|
|
<<faces#markup-strings,`:doc faces markup-strings`>>).
|
|
|
|
As the user selects items from the completion menu, the text they typed
|
|
will be replaced with `<text>`, and the Kakoune command in
|
|
`<select cmd>` is executed. The common use case is to display element
|
|
specific documentation.
|
|
|
|
`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 supports 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*)
|
|
|
|
*terminal_info_max_width*:::
|
|
set the maximum allowable width of an info box. set to zero for
|
|
no limit.
|
|
|
|
[[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
|
|
-------------
|