path: root/doc/pages/options.asciidoc

= 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_title*:::
            if set, the terminal title will be set to this string
            else it will be derived from the modeline.

        *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
-------------