kakoune

Fork of kakoune, an acceptable text editor
git clone git://git.laack.co/kakoune.git
Log | Files | Refs

options.asciidoc (15297B)


      1 = Options
      2 
      3 == Description
      4 
      5 Kakoune can store named and typed values that can be used both to
      6 customize the core editor behaviour, and to store data used by extension
      7 scripts.
      8 
      9 [[set-option]]
     10 Options can be modified using the `set-option` command:
     11 
     12 --------------------------------------------
     13 set-option [-add|-remove] <scope> <name> <values>...
     14 --------------------------------------------
     15 
     16 <scope> can be *global*, *buffer*, *window* or *current* (See
     17 <<scopes#,`:doc scopes`>>). *current* relates to the narrowest scope in
     18 which the option is already set.
     19 
     20 When the option is a list or a map, multiple <values> can be given as
     21 separate arguments, or can be omitted altogether in order to empty the
     22 option.
     23 
     24 If `-add` or `-remove` is specified, the new value is respectively *added*
     25 to or *removed* from the current one instead of replacing it (the exact
     26 outcome depends on the type, see below).
     27 
     28 [[unset-option]]
     29 Option values can be unset in a specific scope with the `unset-option`
     30 command:
     31 
     32 ---------------------------
     33 unset-option <scope> <name>
     34 ---------------------------
     35 
     36 Unsetting an option will make it fallback to the value of its parent scope,
     37 hence options cannot be unset from the *global* scope.
     38 
     39 [[declare-option]]
     40 New options can be declared using the `declare-option` command:
     41 
     42 ---------------------------------------------------
     43 declare-option [-hidden] <type> <name> [<value>...]
     44 ---------------------------------------------------
     45 
     46 If `-hidden` is specified, the option will not be displayed in completion
     47 suggestions.
     48 
     49 [[update-option]]
     50 Certain option type can be *updated*, usually to match potential changes
     51 in the buffer they relate to. This can be triggered by the `update-option`
     52 command:
     53 
     54 ----------------------------
     55 update-option <scope> <name>
     56 ----------------------------
     57 
     58 == Types
     59 
     60 All options have a type, which defines how they are translated to/from
     61 text and their set of valid values.
     62 
     63 Some types are usable for user defined options while some other types
     64 are exclusively available to built-in options.
     65 
     66 *int*::
     67     an integer number.
     68 
     69     `set -add` performs a math addition. +
     70     `set -remove` performs a math substraction. +
     71 
     72 *bool*::
     73     a boolean value, yes/true or no/false
     74 
     75 *str*::
     76     a string, some freeform text
     77 
     78 *regex*::
     79     as a string but the set commands will complain if the entered text
     80     is not a valid regex
     81 
     82 *coord*::
     83     a line, column pair (separated by a comma)
     84     Cannot be used with `declare-option`
     85 
     86 *<type>-list*::
     87     a list, elements are specified as separate arguments to the command.
     88 
     89     `set -add` appends the new element to the list. +
     90     `set -remove` removes each given element from the list. +
     91 
     92     Only `int-list` and `str-list` options can be created with
     93     `declare-option`.
     94 
     95 *range-specs*::
     96     a timestamp (like `%val{timestamp}`,
     97     see <<expansions#value-expansions,`:doc expansions value-expansions`>>)
     98     followed by a list of range descriptors.
     99 
    100     Each range descriptor must use the syntax `a.b,c.d|string` or
    101     `a.b+length|string`, with:
    102 
    103         * _a_ is the line containing the first character
    104 
    105         * _b_ is the number of bytes from the start of the line to the
    106         first byte of the first character
    107 
    108         * _c_ is the line containing the last character
    109 
    110         * _d_ is the number of bytes from the start of the line to the
    111           first byte of the last character
    112 
    113         * _length_ is the length of the range in bytes, if 0 the range
    114           is empty, but still valid.
    115 
    116         * _string_ is an arbitrary string which is associated with
    117           the range. Any `|` or `\` characters must be escaped as `\|` or `\\`.
    118 
    119     All numeric fields are 1-based.
    120 
    121     When the command `update-option` is used on an option of this type,
    122     its ranges get updated according to all the buffer modifications
    123     that happened since its timestamp.
    124 
    125     `set -add` appends the new pairs to the list. +
    126     `set -remove` removes the given pairs from the list. +
    127 
    128     See <<highlighters#specs-highlighters,`:doc highlighters specs-highlighters`>>)
    129 
    130 *line-specs*::
    131     a list of a line number and a corresponding flag (`<line>|<flag
    132     text>`), except for the first element which is just the timestamp
    133     of the buffer. When `update-option` is used on an option of this
    134     type, its lines get updated according to all the buffer modifications
    135     that happened since its timestamp.
    136     See <<highlighters#specs-highlighters,`:doc highlighters specs-highlighters`>>)
    137 
    138     `set -add` appends the new specs to the list. +
    139     `set -remove` removes the given specs from the list. +
    140 
    141     Any `|` or `\` characters that occur within `<flag text>` must be
    142     escaped as `\|` or `\\`.
    143 
    144 *completions*::
    145     a list of `<text>|<select cmd>|<menu text>` candidates,
    146     except for the first element which follows the
    147     `<line>.<column>[+<length>]@<timestamp>` format to define where the
    148     completion apply in the buffer.
    149     Any `|` or `\` characters that occur within the `<text>`,
    150     `<select cmd>`, or `<menu text>` fields should be escaped as `\|`
    151     or `\\`.
    152 
    153     Options of this type are are meant to be added to the `completers`
    154     option to provide insert mode completion. Candidates are shown if the
    155     text typed by the user (between `<line>.<column>` and the cursor) is a
    156     subsequence of `<text>`.
    157 
    158     For each remaining candidate, the completion menu displays
    159     `<text>`, followed by `<menu text>`, which is a Markup string (see
    160     <<faces#markup-strings,`:doc faces markup-strings`>>).
    161 
    162     As the user selects items from the completion menu, the text they typed
    163     will be replaced with `<text>`, and the Kakoune command in
    164     `<select cmd>` is executed. The common use case is to display element
    165     specific documentation.
    166 
    167     `set -add` adds given completions to the list. +
    168     `set -remove` removes given completions from the list. +
    169 
    170 *enum(value1|value2|...)*::
    171     an enum, taking one of the given values
    172     Cannot be used with `declare-option`
    173 
    174 *flags(value1|value2|...)*::
    175     a set of flags, taking a combination of the given values joined by a
    176     '|' character.
    177 
    178     `set -add` adds the given flags to the combination. +
    179     `set -remove` removes the given flags to the combination. +
    180 
    181     Cannot be used with `declare-option`
    182 
    183 *<type>-to-<type>-map*::
    184     a list of `key=value` pairs.
    185 
    186     `set -add` adds the given pair to the hashmap or replace an already
    187     existing key. +
    188     `set -remove` removes the given pair from the hashmap, if only the
    189     key is provided it removes that entry regardless of the associated
    190     value. +
    191 
    192     Only `str-to-str-map` options can be created with `declare-option`.
    193 
    194 == Builtin options
    195 
    196 *tabstop* `int`::
    197     _default_ 8 +
    198     width of a tab character
    199 
    200 *indentwidth* `int`::
    201     _default_ 4 +
    202     width (in spaces) used for indentation, 0 means a tab character
    203 
    204 *scrolloff* `coord`::
    205     _default_ 0,0 +
    206     number of lines, columns to keep visible around the cursor when
    207     scrolling
    208 
    209 *eolformat* `enum(lf|crlf)`::
    210     _default_ lf +
    211     the format of end of lines when writing a buffer, this is autodetected
    212     on load; values of this option assigned to the `window` scope are
    213     ignored
    214 
    215 *finaleol* `enum(present|missing|ifnotempty)`::
    216     _default_ present +
    217     Whether to drop the end-of-line of the last line the buffer when writing
    218     to the filesystem, this is autodetected on load; values of this option
    219     assigned to the `window` scope are ignored.
    220 
    221     When set to `ifnotempty` the final end-of-line will only be written if
    222     the buffer has a single empty line.
    223 
    224 
    225 *BOM* `enum(none|utf8)`::
    226     _default_ none +
    227     define if the file should be written with a unicode byte order mark;
    228     values of this option assigned to the `window` scope are ignored
    229 
    230 *readonly* `bool`::
    231     _default_ false +
    232     prevent modifications from being saved to disk, all buffers if set
    233     to `true` in the `global` scope, or current buffer if set in the
    234     `buffer` scope; values of this option assigned to the `window`
    235     scope are ignored
    236 
    237 *incsearch* `bool`::
    238     _default_ true +
    239     execute search as it is typed
    240 
    241 *aligntab* `bool`::
    242     _default_ false +
    243     use tabs for alignment command
    244 
    245 *autoinfo* `flags(command|onkey|normal)`::
    246     _default_ command|onkey +
    247     display automatic information box in the enabled contexts
    248 
    249 *autocomplete* `flags(insert|prompt)`::
    250     _default_ insert|prompt +
    251     automatically display possible completions in the enabled modes.
    252 
    253 *ignored_files* `regex`::
    254     filenames matching this regex won't be considered as candidates
    255     on filename completion (except if the text being completed already
    256     matches it)
    257 
    258 *disabled_hooks* `regex`::
    259     hooks whose group matches this regex won't be executed. For example
    260     indentation hooks can be disabled with `.*-indent`.
    261     (See <<hooks#disabling-hooks,`:doc hooks`>>)
    262 
    263 *filetype* `str`::
    264     arbitrary string defining the type of the file. Filetype dependent
    265     actions should hook on this option changing for activation/deactivation
    266 
    267 *path* `str-list`::
    268     _default_ ./ %/ /usr/include +
    269     directories to search for *gf* command and filenames completion
    270     `%/` represents the current buffer directory
    271 
    272 *completers* `completer-list`::
    273     _default_ filename word=all +
    274     completion engines to use for insert mode completion (they are tried
    275     in order until one generates candidates). Existing completers are:
    276 
    277     *word=all*, *word=buffer*:::
    278         which complete using words in all buffers (*word=all*)
    279         or only the current one (*word=buffer*)
    280 
    281     *filename*:::
    282         which tries to detect when a filename is being entered and
    283         provides completion based on local filesystem
    284 
    285     *line=all*, *line=buffer*:::
    286         which complete using lines in all buffers (*line=all*)
    287         or only the current one (*line=buffer*)
    288 
    289     *option=<opt-name>*:::
    290         where *opt-name* is an option of type 'completions' whose
    291         contents will be used
    292 
    293 *static_words* `str-list`::
    294     list of words that are always added to completion candidates
    295     when completing words in insert mode
    296 
    297 *extra_word_chars* `codepoint-list`::
    298     _default_ _ +
    299     a list of all additional codepoints that should be considered
    300     part of a word for the purposes of the `w`, `b`, and `e` commands
    301     (See <<keys#movement,`:doc keys movement`>>),
    302     the `word=buffer` and `word=all` completers
    303     (See `completers` above),
    304     "word" objects
    305     (See <<keys#object-selection,`:doc keys object-selection`>>), etc.
    306     This must be set on the buffer, not the window,
    307     for word completion to offer words containing these codepoints.
    308 
    309 *matching_pairs* `codepoint-list`::
    310     _default_ ( ) { } [ ] < > +
    311     a list of codepoints that are to be treated as matching pairs
    312     for the *m* command.
    313 
    314 *autoreload* `enum(yes|no|ask)`::
    315     _default_ ask +
    316     auto reload the buffers when an external modification is detected
    317 
    318 *writemethod* `enum(overwrite|replace)`::
    319     _default_ overwrite +
    320     method used to write buffers to file, `overwrite` will open the
    321     existing file and write on top of the previous data, `replace`
    322     will open a temporary file next to the target file, write it and
    323     then rename it to the target file.
    324 
    325 *debug* `flags(hooks|shell|profile|keys|commands)`::
    326     dump various debug information in the `\*debug*` buffer
    327 
    328 *idle_timeout* `int`::
    329     _default_ 50 +
    330     timeout, in milliseconds, with no user input that will trigger the
    331     *PromptIdle*, *InsertIdle* and *NormalIdle* hooks, and autocompletion.
    332 
    333 *fs_check_timeout* `int`::
    334     _default_ 500 +
    335     timeout, in milliseconds, between checks in normal mode of modifications
    336     of the file associated with the current buffer on the filesystem.
    337 
    338 *modelinefmt* `string`::
    339     A format string used to generate the mode line, that string is
    340     first expanded as a command line would be (expanding '%...{...}'
    341     strings), then markup tags are applied (see
    342     <<faces#markup-strings,`:doc faces markup-strings`>>)
    343     Two special atoms are available as markup:
    344 
    345         *`{{mode_info}}`*:::
    346             Information about the current mode, such as `insert 3 sel` or
    347             `prompt`. The faces used are StatusLineMode, StatusLineInfo,
    348             and StatusLineValue.
    349 
    350         *`{{context_info}}`*:::
    351             Information such as `[+][recording (@)][no-hooks][new file][fifo]`,
    352             in face Information.
    353 
    354     The default value is '%val{bufname} %val{cursor_line}:%val{cursor_char_column} {{context_info}} {{mode_info}} - %val{client}@[%val{session}]'
    355 
    356 *ui_options* `str-to-str-map`::
    357     a list of `key=value` pairs that are forwarded to the user
    358     interface implementation. The Terminal UI supports the following options:
    359 
    360         *terminal_set_title*:::
    361             if *yes* or *true*, the terminal emulator title will
    362             be changed
    363 
    364         *terminal_title*:::
    365             if set, the terminal title will be set to this string
    366             else it will be derived from the modeline.
    367 
    368         *terminal_status_on_top*:::
    369             if *yes*, or *true* the status line will be placed
    370             at the top of the terminal rather than at the bottom
    371 
    372         *terminal_assistant*:::
    373             specify the nice assistant displayed in info boxes,
    374             can be *clippy* (the default), *cat*, *dilbert* or *none*
    375 
    376         *terminal_enable_mouse*:::
    377             boolean option that enables mouse support
    378 
    379         *terminal_shift_function_key*:::
    380             Function key from which shifted function key start, if the
    381             terminal sends F13 for <s-F1>, this should be set to 12.
    382 
    383         *terminal_padding_char*:::
    384             character used to indicate the area out of the displayed buffer
    385             (defaults to '~')
    386 
    387         *terminal_padding_fill*:::
    388             if *yes* or *true*, fill the padding area with the padding character
    389             instead of displaying a single character at the beginning of the
    390             padding line (defaults to *false*)
    391 
    392         *terminal_synchronized*:::
    393             if *yes* or *true*, emit synchronized output escape sequences and
    394             reduce terminal output with sequences that could trigger flickering
    395             if unsynchronized (defaults to *false*)
    396 
    397         *terminal_info_max_width*:::
    398             set the maximum allowable width of an info box. set to zero for
    399             no limit.
    400 
    401         *terminal_cursor_native*:::
    402             if *yes* or *true*, use native terminal cursor visibility control
    403             instead of Kakoune's cursor management (defaults to *false*)
    404 
    405 [[startup-info]]
    406 *startup_info_version* `int`::
    407     _default_ 0 +
    408     Controls which messages will be displayed in the startup info box, only messages
    409     relating to a Kakoune version greater than this value will be displayed. Versions
    410     are written as a single number: Like `20180413` for version `2018.04.13`
    411 
    412 == Current values
    413 
    414 The current value for an option can be viewed using
    415 <<expansions#option-expansions, `:doc expansions option-expansions`>>.
    416 
    417 For example, the current value of the `BOM` option can be displayed in the
    418 status line using the `echo` command:
    419 
    420 --------------
    421 echo %opt{BOM}
    422 --------------
    423 
    424 The current values for all options can be dumped to the `\*debug*` buffer using
    425 the following command:
    426 
    427 -------------
    428 debug options
    429 -------------