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