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