diff options
Diffstat (limited to 'src/nvim/options.lua')
| -rw-r--r-- | src/nvim/options.lua | 215 |
1 files changed, 159 insertions, 56 deletions
diff --git a/src/nvim/options.lua b/src/nvim/options.lua index 5173240384..932d8f8d0e 100644 --- a/src/nvim/options.lua +++ b/src/nvim/options.lua @@ -1,3 +1,5 @@ +-- vim: tw=80 + --- @class vim.option_meta --- @field full_name string --- @field desc? string @@ -747,7 +749,7 @@ return { applying 'breakindent', even if the resulting text should normally be narrower. This prevents text indented almost to the right window border - occupying lot of vertical space when broken. + occupying lots of vertical space when broken. (default: 20) shift:{n} After applying 'breakindent', the wrapped line's beginning will be shifted by the given number of @@ -761,9 +763,9 @@ return { list:{n} Adds an additional indent for lines that match a numbered or bulleted list (using the 'formatlistpat' setting). - list:-1 Uses the length of a match with 'formatlistpat' - for indentation. (default: 0) + list:-1 Uses the width of a match with 'formatlistpat' for + indentation. column:{n} Indent at column {n}. Will overrule the other sub-options. Note: an additional indent may be added for the 'showbreak' setting. @@ -996,9 +998,10 @@ return { The key used in Command-line Mode to open the command-line window. Only non-printable keys are allowed. The key can be specified as a single character, but it is difficult to - type. The preferred way is to use the <> notation. Examples: >vim - exe "set cedit=\\<C-Y>" - exe "set cedit=\\<Esc>" + type. The preferred way is to use |key-notation| (e.g. <Up>, <C-F>) or + a letter preceded with a caret (e.g. `^F` is CTRL-F). Examples: >vim + set cedit=^Y + set cedit=<Esc> < |Nvi| also has this option, but it only uses the first character. See |cmdwin|. ]=], @@ -1058,6 +1061,17 @@ return { v:fname_in name of the input file v:fname_out name of the output file Note that v:fname_in and v:fname_out will never be the same. + + The advantage of using a function call without arguments is that it is + faster, see |expr-option-function|. + + If the 'charconvert' expression starts with s: or |<SID>|, then it is + replaced with the script ID (|local-function|). Example: >vim + set charconvert=s:MyConvert() + set charconvert=<SID>SomeConvert() + < Otherwise the expression is evaluated in the context of the script + where the option was set, thus script-local items are available. + This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. ]=], @@ -1217,11 +1231,10 @@ return { used. The command-line will cover the last line of the screen when shown. - WARNING: `cmdheight=0` is considered experimental. Expect some - unwanted behaviour. Some 'shortmess' flags and similar - mechanism might fail to take effect, causing unwanted hit-enter - prompts. Some informative messages, both from Nvim itself and - plugins, will not be displayed. + WARNING: `cmdheight=0` is EXPERIMENTAL. Expect some unwanted behaviour. + Some 'shortmess' flags and similar mechanism might fail to take effect, + causing unwanted hit-enter prompts. Some informative messages, both + from Nvim itself and plugins, will not be displayed. ]=], full_name = 'cmdheight', redraw = { 'all_windows' }, @@ -1310,7 +1323,6 @@ return { ]=], full_name = 'comments', list = 'onecomma', - redraw = { 'curswant' }, scope = { 'buffer' }, short_desc = N_('patterns that can start a comment line'), tags = { 'E524', 'E525' }, @@ -1324,11 +1336,10 @@ return { defaults = { if_true = '' }, desc = [=[ A template for a comment. The "%s" in the value is replaced with the - comment text. For example, C uses "/*%s*/". Used for |commenting| and to - add markers for folding, see |fold-marker|. + comment text, and should be padded with a space when possible. + Used for |commenting| and to add markers for folding, see |fold-marker|. ]=], full_name = 'commentstring', - redraw = { 'curswant' }, scope = { 'buffer' }, short_desc = N_('template for comments; used for fold marker'), tags = { 'E537' }, @@ -1417,6 +1428,26 @@ return { varname = 'p_cfu', }, { + abbreviation = 'cia', + cb = 'did_set_completeitemalign', + defaults = { if_true = 'abbr,kind,menu' }, + deny_duplicates = true, + desc = [=[ + A comma-separated list of |complete-items| that controls the alignment + and display order of items in the popup menu during Insert mode + completion. The supported values are abbr, kind, and menu. These + options allow to customize how the completion items are shown in the + popup menu. Note: must always contain those three values in any + order. + ]=], + full_name = 'completeitemalign', + list = 'onecomma', + scope = { 'global' }, + short_desc = N_('Insert mode completion item align order'), + type = 'string', + varname = 'p_cia', + }, + { abbreviation = 'cot', cb = 'did_set_completeopt', defaults = { if_true = 'menu,preview' }, @@ -1443,6 +1474,10 @@ return { completion in the preview window. Only works in combination with "menu" or "menuone". + popup Show extra information about the currently selected + completion in a popup window. Only works in combination + with "menu" or "menuone". Overrides "preview". + noinsert Do not insert any text for a match until the user selects a match from the menu. Only works in combination with "menu" or "menuone". No effect if "longest" is present. @@ -1451,14 +1486,18 @@ return { select one from the menu. Only works in combination with "menu" or "menuone". - popup Show extra information about the currently selected - completion in a popup window. Only works in combination - with "menu" or "menuone". Overrides "preview". + fuzzy Enable |fuzzy-matching| for completion candidates. This + allows for more flexible and intuitive matching, where + characters can be skipped and matches can be found even + if the exact sequence is not typed. Only makes a + difference how completion candidates are reduced from the + list of alternatives, but not how the candidates are + collected (using different completion types). ]=], expand_cb = 'expand_set_completeopt', full_name = 'completeopt', list = 'onecomma', - scope = { 'global' }, + scope = { 'global', 'buffer' }, short_desc = N_('options for Insert mode completion'), type = 'string', varname = 'p_cot', @@ -1956,7 +1995,6 @@ return { < ]=], full_name = 'define', - redraw = { 'curswant' }, scope = { 'global', 'buffer' }, short_desc = N_('pattern to be used to find a macro definition'), type = 'string', @@ -2310,9 +2348,12 @@ return { desc = [=[ When on all Unicode emoji characters are considered to be full width. This excludes "text emoji" characters, which are normally displayed as - single width. Unfortunately there is no good specification for this - and it has been determined on trial-and-error basis. Use the - |setcellwidths()| function to change the behavior. + single width. However, such "text emoji" are treated as full-width + emoji if they are followed by the U+FE0F variant selector. + + Unfortunately there is no good specification for this and it has been + determined on trial-and-error basis. Use the |setcellwidths()| + function to change the behavior. ]=], full_name = 'emoji', redraw = { 'all_windows', 'ui_option' }, @@ -2792,14 +2833,14 @@ return { /* vim: set filetype=idl : */ < |FileType| |filetypes| When a dot appears in the value then this separates two filetype - names. Example: >c + names, it should therefore not be used for a filetype. Example: >c /* vim: set filetype=c.doxygen : */ < This will use the "c" filetype first, then the "doxygen" filetype. This works both for filetype plugins and for syntax files. More than one dot may appear. This option is not copied to another buffer, independent of the 's' or 'S' flag in 'cpoptions'. - Only normal file name characters can be used, `/\*?[|<>` are illegal. + Only alphanumeric characters, '-' and '_' can be used. ]=], full_name = 'filetype', noglob = true, @@ -3215,6 +3256,9 @@ return { < This will invoke the mylang#Format() function in the autoload/mylang.vim file in 'runtimepath'. |autoload| + The advantage of using a function call without arguments is that it is + faster, see |expr-option-function|. + The expression is also evaluated when 'textwidth' is set and adding text beyond that limit. This happens under the same conditions as when internal formatting is used. Make sure the cursor is kept in the @@ -4149,11 +4193,14 @@ return { If the expression starts with s: or |<SID>|, then it is replaced with the script ID (|local-function|). Example: >vim - setlocal includeexpr=s:MyIncludeExpr(v:fname) - setlocal includeexpr=<SID>SomeIncludeExpr(v:fname) + setlocal includeexpr=s:MyIncludeExpr() + setlocal includeexpr=<SID>SomeIncludeExpr() < Otherwise, the expression is evaluated in the context of the script where the option was set, thus script-local items are available. + It is more efficient if the value is just a function call without + arguments, see |expr-option-function|. + The expression will be evaluated in the |sandbox| when set from a modeline, see |sandbox-option|. This option cannot be set in a modeline when 'modelineexpr' is off. @@ -4221,7 +4268,7 @@ return { in Insert mode as specified with the 'indentkeys' option. When this option is not empty, it overrules the 'cindent' and 'smartindent' indenting. When 'lisp' is set, this option is - is only used when 'lispoptions' contains "expr:1". + only used when 'lispoptions' contains "expr:1". The expression is evaluated with |v:lnum| set to the line number for which the indent is to be computed. The cursor is also in this line when the expression is evaluated (but it may be moved around). @@ -4233,6 +4280,9 @@ return { < Otherwise, the expression is evaluated in the context of the script where the option was set, thus script-local items are available. + The advantage of using a function call without arguments is that it is + faster, see |expr-option-function|. + The expression must return the number of spaces worth of indent. It can return "-1" to keep the current indent (this means 'autoindent' is used for the indent). @@ -4487,7 +4537,7 @@ return { { abbreviation = 'jop', cb = 'did_set_jumpoptions', - defaults = { if_true = '' }, + defaults = { if_true = 'clean' }, deny_duplicates = true, desc = [=[ List of words that change the behavior of the |jumplist|. @@ -4500,6 +4550,9 @@ return { view When moving through the jumplist, |changelist|, |alternate-file| or using |mark-motions| try to restore the |mark-view| in which the action occurred. + + clean Remove unloaded buffers from the jumplist. + EXPERIMENTAL: this flag may change in the future. ]=], expand_cb = 'expand_set_jumpoptions', full_name = 'jumpoptions', @@ -4519,7 +4572,7 @@ return { Setting this option to a valid keymap name has the side effect of setting 'iminsert' to one, so that the keymap becomes effective. 'imsearch' is also set to one, unless it was -1 - Only normal file name characters can be used, `/\*?[|<>` are illegal. + Only alphanumeric characters, '.', '-' and '_' can be used. ]=], full_name = 'keymap', normal_fname_chars = true, @@ -4612,7 +4665,7 @@ return { part can be in one of two forms: 1. A list of pairs. Each pair is a "from" character immediately followed by the "to" character. Examples: "aA", "aAbBcC". - 2. A list of "from" characters, a semi-colon and a list of "to" + 2. A list of "from" characters, a semicolon and a list of "to" characters. Example: "abc;ABC" Example: "aA,fgh;FGH,cCdDeE" Special characters need to be preceded with a backslash. These are @@ -4725,7 +4778,7 @@ return { update use |:redraw|. This may occasionally cause display errors. It is only meant to be set temporarily when performing an operation where redrawing may cause - flickering or cause a slow down. + flickering or cause a slowdown. ]=], full_name = 'lazyredraw', scope = { 'global' }, @@ -4868,6 +4921,9 @@ return { between tabs and spaces and for trailing blanks. Further changed by the 'listchars' option. + When 'listchars' does not contain "tab" field, tabs are shown as "^I" + or "<09>", like how unprintable characters are displayed. + The cursor is displayed at the start of the space a Tab character occupies, not at the end as usual in Normal mode. To get this cursor position while displaying Tabs with spaces, use: >vim @@ -5703,6 +5759,20 @@ return { (without "unsigned" it would become "9-2019"). Using CTRL-X on "0" or CTRL-A on "18446744073709551615" (2^64 - 1) has no effect, overflow is prevented. + blank If included, treat numbers as signed or unsigned based on + preceding whitespace. If a number with a leading dash has its + dash immediately preceded by a non-whitespace character (i.e., + not a tab or a " "), the negative sign won't be considered as + part of the number. For example: + Using CTRL-A on "14" in "Carbon-14" results in "Carbon-15" + (without "blank" it would become "Carbon-13"). + Using CTRL-X on "8" in "Carbon -8" results in "Carbon -9" + (because -8 is preceded by whitespace. If "unsigned" was + set, it would result in "Carbon -7"). + If this format is included, overflow is prevented as if + "unsigned" were set. If both this format and "unsigned" are + included, "unsigned" will take precedence. + Numbers which simply begin with a digit in the range 1-9 are always considered decimal. This also happens for numbers that are not recognized as octal or hex. @@ -5984,7 +6054,7 @@ return { set path+= < To use an environment variable, you probably need to replace the separator. Here is an example to append $INCL, in which directory - names are separated with a semi-colon: >vim + names are separated with a semicolon: >vim let &path = &path .. "," .. substitute($INCL, ';', ',', 'g') < Replace the ';' with a ':' or whatever separator is used. Note that this doesn't work when $INCL contains a comma or white space. @@ -6582,6 +6652,9 @@ return { top are deleted if new lines exceed this limit. Minimum is 1, maximum is 100000. Only in |terminal| buffers. + + Note: Lines that are not visible and kept in scrollback are not + reflown when the terminal buffer is resized horizontally. ]=], full_name = 'scrollback', redraw = { 'current_buffer' }, @@ -7300,7 +7373,7 @@ return { defaults = { if_true = 'ltToOCF' }, desc = [=[ This option helps to avoid all the |hit-enter| prompts caused by file - messages, for example with CTRL-G, and to avoid some other messages. + messages, for example with CTRL-G, and to avoid some other messages. It is a list of flags: flag meaning when present ~ l use "999L, 888B" instead of "999 lines, 888 bytes" *shm-l* @@ -7317,8 +7390,8 @@ return { message; also for quickfix message (e.g., ":cn") s don't give "search hit BOTTOM, continuing at TOP" or *shm-s* "search hit TOP, continuing at BOTTOM" messages; when using - the search count do not show "W" after the count message (see - S below) + the search count do not show "W" before the count message + (see |shm-S| below) t truncate file message at the start if it is too long *shm-t* to fit on the command-line, "<" will appear in the left most column; ignored in Ex mode @@ -7340,7 +7413,11 @@ return { `:silent` was used for the command; note that this also affects messages from 'autoread' reloading S do not show search count message when searching, e.g. *shm-S* - "[1/5]" + "[1/5]". When the "S" flag is not present (e.g. search count + is shown), the "search hit BOTTOM, continuing at TOP" and + "search hit TOP, continuing at BOTTOM" messages are only + indicated by a "W" (Mnemonic: Wrapped) letter before the + search count statistics. This gives you the opportunity to avoid that a change between buffers requires you to hit <Enter>, but still gives as useful a message as @@ -7889,7 +7966,7 @@ return { minus two. timeout:{millisec} Limit the time searching for suggestions to - {millisec} milli seconds. Applies to the following + {millisec} milliseconds. Applies to the following methods. When omitted the limit is 5000. When negative there is no limit. @@ -7909,9 +7986,11 @@ return { The file is used for all languages. expr:{expr} Evaluate expression {expr}. Use a function to avoid - trouble with spaces. |v:val| holds the badly spelled - word. The expression must evaluate to a List of - Lists, each with a suggestion and a score. + trouble with spaces. Best is to call a function + without arguments, see |expr-option-function|. + |v:val| holds the badly spelled word. The expression + must evaluate to a List of Lists, each with a + suggestion and a score. Example: [['the', 33], ['that', 44]] ~ Set 'verbose' and use |z=| to see the scores that the @@ -7997,7 +8076,8 @@ return { non-blank of the line. When off the cursor is kept in the same column (if possible). This applies to the commands: - CTRL-D, CTRL-U, CTRL-B, CTRL-F, "G", "H", "M", "L", "gg" - - "d", "<<" and ">>" with a linewise operator + - "d", "<<", "==" and ">>" with a linewise operator + (|operator-resulting-pos|) - "%" with a count - buffer changing commands (CTRL-^, :bnext, :bNext, etc.) - Ex commands that only have a line number, e.g., ":25" or ":+". @@ -8017,7 +8097,6 @@ return { cb = 'did_set_statuscolumn', defaults = { if_true = '' }, desc = [=[ - EXPERIMENTAL When non-empty, this option determines the content of the area to the side of a window, normally containing the fold, sign and number columns. The format of this option is like that of 'statusline'. @@ -8025,8 +8104,7 @@ return { Some of the items from the 'statusline' format are different for 'statuscolumn': - %l line number of currently drawn line - %r relative line number of currently drawn line + %l line number column for currently drawn line %s sign column for currently drawn line %C fold column for currently drawn line @@ -8053,11 +8131,8 @@ return { handler should be written with this in mind. Examples: >vim - " Relative number with bar separator and click handlers: - set statuscolumn=%@SignCb@%s%=%T%@NumCb@%r│%T - - " Right aligned relative cursor line number: - let &stc='%=%{v:relnum?v:relnum:v:lnum} ' + " Line number with bar separator and click handlers: + set statuscolumn=%@SignCb@%s%=%T%@NumCb@%l│%T " Line numbers in hexadecimal for non wrapped part of lines: let &stc='%=%{v:virtnum>0?"":printf("%x",v:lnum)} ' @@ -8468,7 +8543,7 @@ return { Syntax autocommand event is triggered with the value as argument. This option is not copied to another buffer, independent of the 's' or 'S' flag in 'cpoptions'. - Only normal file name characters can be used, `/\*?[|<>` are illegal. + Only alphanumeric characters, '.', '-' and '_' can be used. ]=], full_name = 'syntax', noglob = true, @@ -8479,6 +8554,30 @@ return { varname = 'p_syn', }, { + abbreviation = 'tcl', + cb = 'did_set_tabclose', + defaults = { if_true = '' }, + deny_duplicates = true, + desc = [=[ + This option controls the behavior when closing tab pages (e.g., using + |:tabclose|). When empty Vim goes to the next (right) tab page. + + Possible values (comma-separated list): + left If included, go to the previous tab page instead of + the next one. + uselast If included, go to the previously used tab page if + possible. This option takes precedence over the + others. + ]=], + expand_cb = 'expand_set_tabclose', + full_name = 'tabclose', + list = 'onecomma', + scope = { 'global' }, + short_desc = N_('which tab page to focus when closing a tab'), + type = 'string', + varname = 'p_tcl', + }, + { abbreviation = 'tal', cb = 'did_set_tabline', defaults = { if_true = '' }, @@ -8970,7 +9069,7 @@ return { desc = [=[ When on, the title of the window will be set to the value of 'titlestring' (if it is not empty), or to: - filename [+=-] (path) - NVIM + filename [+=-] (path) - Nvim Where: filename the name of the file being edited - indicates the file cannot be modified, 'ma' off @@ -8978,11 +9077,11 @@ return { = indicates the file is read-only =+ indicates the file is read-only and modified (path) is the path of the file being edited - - NVIM the server name |v:servername| or "NVIM" + - Nvim the server name |v:servername| or "Nvim" ]=], full_name = 'title', scope = { 'global' }, - short_desc = N_('Vim set the title of the window'), + short_desc = N_('set the title of the window'), type = 'boolean', varname = 'p_title', }, @@ -9579,7 +9678,12 @@ return { Some keys will not work, such as CTRL-C, <CR> and Enter. <Esc> can be used, but hitting it twice in a row will still exit command-line as a failsafe measure. - Although 'wc' is a number option, you can set it to a special key: >vim + Although 'wc' is a number option, it can be specified as a number, a + single character, a |key-notation| (e.g. <Up>, <C-F>) or a letter + preceded with a caret (e.g. `^F` is CTRL-F): >vim + :set wc=27 + :set wc=X + :set wc=^I set wc=<Tab> < ]=], @@ -9895,7 +9999,6 @@ return { ]=], full_name = 'winfixbuf', pv_name = 'p_wfb', - redraw = { 'current_window' }, scope = { 'window' }, short_desc = N_('pin a window to a specific buffer'), type = 'boolean', |