diff options
Diffstat (limited to 'runtime/lua/vim/_meta/options.lua')
| -rw-r--r-- | runtime/lua/vim/_meta/options.lua | 195 |
1 files changed, 145 insertions, 50 deletions
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index 428b7c4d4f..ce3ff4f861 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -544,7 +544,7 @@ vim.wo.bri = vim.wo.breakindent --- 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 @@ -558,9 +558,9 @@ vim.wo.bri = vim.wo.breakindent --- 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. @@ -731,11 +731,12 @@ vim.go.cd = vim.go.cdpath --- 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: +--- 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 ---- exe "set cedit=\\<C-Y>" ---- exe "set cedit=\\<Esc>" +--- set cedit=^Y +--- set cedit=<Esc> --- ``` --- `Nvi` also has this option, but it only uses the first character. --- See `cmdwin`. @@ -785,6 +786,20 @@ vim.bo.channel = vim.o.channel --- 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. --- @@ -899,11 +914,10 @@ vim.go.cb = vim.go.clipboard --- 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. --- --- @type integer vim.o.cmdheight = 1 @@ -974,8 +988,8 @@ vim.bo.comments = vim.o.comments vim.bo.com = vim.bo.comments --- 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`. --- --- @type string vim.o.commentstring = "" @@ -1040,6 +1054,19 @@ vim.o.cfu = vim.o.completefunc vim.bo.completefunc = vim.o.completefunc vim.bo.cfu = vim.bo.completefunc +--- 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. +--- +--- @type string +vim.o.completeitemalign = "abbr,kind,menu" +vim.o.cia = vim.o.completeitemalign +vim.go.completeitemalign = vim.o.completeitemalign +vim.go.cia = vim.go.completeitemalign + --- A comma-separated list of options for Insert mode completion --- `ins-completion`. The supported values are: --- @@ -1061,6 +1088,10 @@ vim.bo.cfu = vim.bo.completefunc --- 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. @@ -1069,13 +1100,19 @@ vim.bo.cfu = vim.bo.completefunc --- 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). --- --- @type string vim.o.completeopt = "menu,preview" vim.o.cot = vim.o.completeopt +vim.bo.completeopt = vim.o.completeopt +vim.bo.cot = vim.bo.completeopt vim.go.completeopt = vim.o.completeopt vim.go.cot = vim.go.completeopt @@ -1805,9 +1842,12 @@ vim.go.ead = vim.go.eadirection --- 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. --- --- @type boolean vim.o.emoji = true @@ -2177,7 +2217,7 @@ vim.go.fic = vim.go.fileignorecase --- ``` --- `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. @@ -2185,7 +2225,7 @@ vim.go.fic = vim.go.fileignorecase --- 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. --- --- @type string vim.o.filetype = "" @@ -2500,6 +2540,9 @@ vim.wo.fdt = vim.wo.foldtext --- 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 @@ -3265,12 +3308,15 @@ vim.go.inc = vim.go.include --- 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. @@ -3330,7 +3376,7 @@ vim.go.is = vim.go.incsearch --- 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). @@ -3345,6 +3391,9 @@ vim.go.is = vim.go.incsearch --- 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). @@ -3541,8 +3590,11 @@ vim.go.js = vim.go.joinspaces --- |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. +--- --- @type string -vim.o.jumpoptions = "" +vim.o.jumpoptions = "clean" vim.o.jop = vim.o.jumpoptions vim.go.jumpoptions = vim.o.jumpoptions vim.go.jop = vim.go.jumpoptions @@ -3551,7 +3603,7 @@ vim.go.jop = vim.go.jumpoptions --- 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. --- --- @type string vim.o.keymap = "" @@ -3628,7 +3680,7 @@ vim.go.kp = vim.go.keywordprg --- 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 @@ -3720,7 +3772,7 @@ vim.go.ls = vim.go.laststatus --- 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. --- --- @type boolean vim.o.lazyredraw = false @@ -3820,6 +3872,9 @@ vim.go.lw = vim.go.lispwords --- 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: @@ -4533,6 +4588,20 @@ vim.go.mouset = vim.go.mousetime --- (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. @@ -4757,7 +4826,7 @@ vim.go.pm = vim.go.patchmode --- ``` --- 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: +--- names are separated with a semicolon: --- --- ```vim --- let &path = &path .. "," .. substitute($INCL, ';', ',', 'g') @@ -5200,6 +5269,9 @@ vim.wo.scr = vim.wo.scroll --- 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. +--- --- @type integer vim.o.scrollback = -1 vim.o.scbk = vim.o.scrollback @@ -5764,7 +5836,7 @@ vim.bo.shiftwidth = vim.o.shiftwidth vim.bo.sw = vim.bo.shiftwidth --- 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* @@ -5781,8 +5853,8 @@ vim.bo.sw = vim.bo.shiftwidth --- 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 @@ -5804,7 +5876,11 @@ vim.bo.sw = vim.bo.shiftwidth --- `: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 @@ -6249,7 +6325,7 @@ vim.bo.spo = vim.bo.spelloptions --- 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. --- @@ -6269,9 +6345,11 @@ vim.bo.spo = vim.bo.spelloptions --- 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 @@ -6338,7 +6416,8 @@ vim.go.spr = vim.go.splitright --- 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 ":+". @@ -6351,7 +6430,6 @@ vim.o.sol = vim.o.startofline vim.go.startofline = vim.o.startofline vim.go.sol = vim.go.startofline ---- 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'. @@ -6359,8 +6437,7 @@ vim.go.sol = vim.go.startofline --- 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 --- @@ -6389,11 +6466,8 @@ vim.go.sol = vim.go.startofline --- 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)} ' @@ -6799,7 +6873,7 @@ vim.bo.smc = vim.bo.synmaxcol --- 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. --- --- @type string vim.o.syntax = "" @@ -6807,6 +6881,22 @@ vim.o.syn = vim.o.syntax vim.bo.syntax = vim.o.syntax vim.bo.syn = vim.bo.syntax +--- 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. +--- +--- @type string +vim.o.tabclose = "" +vim.o.tcl = vim.o.tabclose +vim.go.tabclose = vim.o.tabclose +vim.go.tcl = vim.go.tabclose + --- When non-empty, this option determines the content of the tab pages --- line at the top of the Vim window. When empty Vim will use a default --- tab pages line. See `setting-tabline` for more info. @@ -7178,7 +7268,7 @@ vim.go.tm = vim.go.timeoutlen --- 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 @@ -7186,7 +7276,7 @@ vim.go.tm = vim.go.timeoutlen --- = 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" --- --- @type boolean vim.o.title = false @@ -7607,9 +7697,14 @@ vim.go.ww = vim.go.whichwrap --- 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: +--- 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> --- ``` --- |