1= Options 2 3== Description 4 5Kakoune can store named and typed values that can be used both to 6customize the core editor behaviour, and to store data used by extension 7scripts. 8 9[[set-option]] 10Options can be modified using the `set-option` command: 11 12-------------------------------------------- 13set-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 18which the option is already set. 19 20When the option is a list or a map, multiple <values> can be given as 21separate arguments, or can be omitted altogether in order to empty the 22option. 23 24If `-add` or `-remove` is specified, the new value is respectively *added* 25to or *removed* from the current one instead of replacing it (the exact 26outcome depends on the type, see below). 27 28[[unset-option]] 29Options values can be unset in a specific scope with the `unset-option` 30command: 31 32--------------------------- 33unset-option <scope> <name> 34--------------------------- 35 36Unsetting an option will make it fallback to the value of its parent scope, 37hence options cannot be unset from the *global* scope. 38 39[[declare-option]] 40New options can be declared using the `declare-option` command: 41 42--------------------------------------------------- 43declare-option [-hidden] <type> <name> [<value>...] 44--------------------------------------------------- 45 46If `-hidden` is specified, the option will not be displayed in completion 47suggestions. 48 49[[update-option]] 50Certain option type can be *updated*, usually to match potential changes 51in the buffer they relate to. This can be triggered by the `update-option` 52command: 53 54---------------------------- 55update-option <scope> <name> 56---------------------------- 57 58== Types 59 60All options have a type, which defines how they are translated to/from 61text and their set of valid values. 62 63Some types are usable for user defined options while some other types 64are 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. 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*completions*:: 142 a list of `<text>|<select cmd>|<menu text>` candidates, 143 except for the first element which follows the 144 `<line>.<column>[+<length>]@<timestamp>` format to define where the 145 completion apply in the buffer. 146 Any `|` or `\` characters that occur within the `<text>`, 147 `<select cmd>`, or `<menu text>` fields should be escaped as `\|` 148 or `\\`. 149 150 Select commands are arbitrary Kakoune commands that will be executed 151 each time the element is selected in the menu. The common use case is 152 to display element specific documentation. 153 154 Markup can be used in the menu text. 155 (see <<faces#markup-strings,`:doc faces markup-strings`>>) 156 157 `set -add` adds given completions to the list. + 158 `set -remove` removes given completions from the list. + 159 160*enum(value1|value2|...)*:: 161 an enum, taking one of the given values 162 Cannot be used with `declare-option` 163 164*flags(value1|value2|...)*:: 165 a set of flags, taking a combination of the given values joined by a 166 '|' character. 167 168 `set -add` adds the given flags to the combination. + 169 `set -remove` removes the given flags to the combination. + 170 171 Cannot be used with `declare-option` 172 173*<type>-to-<type>-map*:: 174 a list of `key=value` pairs. 175 176 `set -add` adds the given pair to the hashmap or replace an already 177 existing key. + 178 `set -remove` removes the given pair from the hashmap, if only the 179 key is provided it removes that entry regardless of the associated 180 value. + 181 182 Only `str-to-str-map` options can be created with `declare-option`. 183 184== Builtin options 185 186*tabstop* `int`:: 187 _default_ 8 + 188 width of a tab character 189 190*indentwidth* `int`:: 191 _default_ 4 + 192 width (in spaces) used for indentation, 0 means a tab character 193 194*scrolloff* `coord`:: 195 _default_ 0,0 + 196 number of lines, columns to keep visible around the cursor when 197 scrolling 198 199*eolformat* `enum(lf|crlf)`:: 200 _default_ lf + 201 the format of end of lines when writing a buffer, this is autodetected 202 on load; values of this option assigned to the `window` scope are 203 ignored 204 205*BOM* `enum(none|utf8)`:: 206 _default_ none + 207 define if the file should be written with a unicode byte order mark; 208 values of this option assigned to the `window` scope are ignored 209 210*readonly* `bool`:: 211 _default_ false + 212 prevent modifications from being saved to disk, all buffers if set 213 to `true` in the `global` scope, or current buffer if set in the 214 `buffer` scope; values of this option assigned to the `window` 215 scope are ignored 216 217*incsearch* `bool`:: 218 _default_ true + 219 execute search as it is typed 220 221*aligntab* `bool`:: 222 _default_ false + 223 use tabs for alignment command 224 225*autoinfo* `flags(command|onkey|normal)`:: 226 _default_ command|onkey + 227 display automatic information box in the enabled contexts 228 229*autocomplete* `flags(insert|prompt)`:: 230 _default_ insert|prompt + 231 automatically display possible completions in the enabled modes. 232 233*ignored_files* `regex`:: 234 filenames matching this regex won't be considered as candidates 235 on filename completion (except if the text being completed already 236 matches it) 237 238*disabled_hooks* `regex`:: 239 hooks whose group matches this regex won't be executed. For example 240 indentation hooks can be disabled with `.*-indent`. 241 (See <<hooks#disabling-hooks,`:doc hooks`>>) 242 243*filetype* `str`:: 244 arbitrary string defining the type of the file. Filetype dependent 245 actions should hook on this option changing for activation/deactivation 246 247*path* `str-list`:: 248 _default_ ./ %/ /usr/include + 249 directories to search for *gf* command and filenames completion 250 `%/` represents the current buffer directory 251 252*completers* `completer-list`:: 253 _default_ filename word=all + 254 completion engines to use for insert mode completion (they are tried 255 in order until one generates candidates). Existing completers are: 256 257 *word=all*, *word=buffer*::: 258 which complete using words in all buffers (*word=all*) 259 or only the current one (*word=buffer*) 260 261 *filename*::: 262 which tries to detect when a filename is being entered and 263 provides completion based on local filesystem 264 265 *line=all*, *line=buffer*::: 266 which complete using lines in all buffers (*line=all*) 267 or only the current one (*line=buffer*) 268 269 *option=<opt-name>*::: 270 where *opt-name* is an option of type 'completions' whose 271 contents will be used 272 273*static_words* `str-list`:: 274 list of words that are always added to completion candidates 275 when completing words in insert mode 276 277*extra_word_chars* `codepoint-list`:: 278 a list of all additional codepoints that should be considered 279 part of a word, for the purposes of the `w`, `b`, and `e` commands 280 (See <<keys#movement,`:doc keys movement`>>). 281 If this option is empty, Kakoune pretends it contains an 282 underscore, otherwise the value is used as-is. 283 This must be set on the buffer, not the window, 284 for word completion to offer words containing these codepoints. 285 286*matching_pairs* `codepoint-list`:: 287 _default_ ( ) { } [ ] < > + 288 a list of codepoints that are to be treated as matching pairs 289 for the *m* command. 290 291*autoreload* `enum(yes|no|ask)`:: 292 _default_ ask + 293 auto reload the buffers when an external modification is detected 294 295*writemethod* `enum(overwrite|replace)`:: 296 _default_ overwrite + 297 method used to write buffers to file, `overwrite` will open the 298 existing file and write on top of the previous data, `replace` 299 will open a temporary file next to the target file, write it and 300 then rename it to the target file. 301 302*debug* `flags(hooks|shell|profile|keys|commands)`:: 303 dump various debug information in the '\*debug*' buffer 304 305*idle_timeout* `int`:: 306 _default_ 50 + 307 timeout, in milliseconds, with no user input that will trigger the 308 *PromptIdle*, *InsertIdle* and *NormalIdle* hooks, and autocompletion. 309 310*fs_check_timeout* `int`:: 311 _default_ 500 + 312 timeout, in milliseconds, between checks in normal mode of modifications 313 of the file associated with the current buffer on the filesystem. 314 315*modelinefmt* `string`:: 316 A format string used to generate the mode line, that string is 317 first expanded as a command line would be (expanding '%...{...}' 318 strings), then markup tags are applied (see 319 <<faces#markup-strings,`:doc faces markup-strings`>>) 320 Two special atoms are available as markup: 321 322 *`{{mode_info}}`*::: 323 Information about the current mode, such as `insert 3 sel` or 324 `prompt`. The faces used are StatusLineMode, StatusLineInfo, 325 and StatusLineValue. 326 327 *`{{context_info}}`*::: 328 Information such as `[+][recording (@)][no-hooks][new file][fifo]`, 329 in face Information. 330 331 The default value is '%val{bufname} %val{cursor_line}:%val{cursor_char_column} {{context_info}} {{mode_info}} - %val{client}@[%val{session}]' 332 333*ui_options* `str-to-str-map`:: 334 a list of `key=value` pairs that are forwarded to the user 335 interface implementation. The NCurses UI support the following options: 336 337 *terminal_set_title*::: 338 if *yes* or *true*, the terminal emulator title will 339 be changed 340 341 *terminal_status_on_top*::: 342 if *yes*, or *true* the status line will be placed 343 at the top of the terminal rather than at the bottom 344 345 *terminal_assistant*::: 346 specify the nice assistant displayed in info boxes, 347 can be *clippy* (the default), *cat*, *dilbert* or *none* 348 349 *terminal_enable_mouse*::: 350 boolean option that enables mouse support 351 352 *terminal_shift_function_key*::: 353 Function key from which shifted function key start, if the 354 terminal sends F13 for <s-F1>, this should be set to 12. 355 356 *terminal_padding_char*::: 357 character used to indicate the area out of the displayed buffer 358 (defaults to '~') 359 360 *terminal_padding_fill*::: 361 if *yes* or *true*, fill the padding area with the padding character 362 instead of displaying a single character at the beginning of the 363 padding line (defaults to *false*) 364 365 *terminal_synchronized*::: 366 if *yes* or *true*, emit synchronized output escape sequences and 367 reduce terminal output with sequences that could trigger flickering 368 if unsynchronized (defaults to *false*) 369 370[[startup-info]] 371*startup_info_version* `int`:: 372 _default_ 0 + 373 Controls which messages will be displayed in the startup info box, only messages 374 relating to a Kakoune version greater than this value will be displayed. Versions 375 are written as a single number: Like `20180413` for version `2018.04.13` 376 377== Current values 378 379The current value for an option can be viewed using 380<<expansions#option-expansions, `:doc expansions option-expansions`>>. 381 382For example, the current value of the `BOM` option can be displayed in the 383status line using the `echo` command: 384 385-------------- 386echo %opt{BOM} 387-------------- 388 389The current values for all options can be dumped to the *\*debug*\* buffer using 390the following command: 391 392------------- 393debug options 394------------- 395