diff options
Diffstat (limited to 'runtime/doc/eval.txt')
| -rw-r--r-- | runtime/doc/eval.txt | 367 |
1 files changed, 185 insertions, 182 deletions
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 49c955da47..48c1a78e88 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1,4 +1,4 @@ -*eval.txt* For Vim version 8.0. Last change: 2017 Feb 17 +*eval.txt* For Vim version 8.0. Last change: 2017 Mar 04 VIM REFERENCE MANUAL by Bram Moolenaar @@ -2623,9 +2623,9 @@ atan2({expr1}, {expr2}) *atan2()* < 2.356194 {only available when compiled with the |+float| feature} -balloon_show({msg}) *balloon_show()* - Show {msg} inside the balloon. - Example: > +balloon_show({msg}) *balloon_show()* + Show {msg} inside the balloon. + Example: > func GetBalloonContent() " initiate getting the content return '' @@ -2633,7 +2633,7 @@ balloon_show({msg}) *balloon_show()* set balloonexpr=GetBalloonContent() func BalloonCallback(result) - call balloon_show(a:result) + call balloon_show(a:result) endfunc < The intended use is that fetching the content of the balloon @@ -2641,7 +2641,10 @@ balloon_show({msg}) *balloon_show()* asynchronous method, in which a callback invokes balloon_show(). The 'balloonexpr' itself can return an empty string or a placeholder. - {only available when compiled with the +beval feature} + + When showing a balloon is not possible nothing happens, no + error message. + {only available when compiled with the +balloon_eval feature} *browse()* browse({save}, {title}, {initdir}, {default}) @@ -2837,176 +2840,6 @@ ceil({expr}) *ceil()* < 4.0 {only available when compiled with the |+float| feature} -changenr() *changenr()* - Return the number of the most recent change. This is the same - number as what is displayed with |:undolist| and can be used - with the |:undo| command. - When a change was made it is the number of that change. After - redo it is the number of the redone change. After undo it is - one less than the number of the undone change. - -char2nr({expr}[, {utf8}]) *char2nr()* - Return number value of the first char in {expr}. Examples: > - char2nr(" ") returns 32 - char2nr("ABC") returns 65 -< When {utf8} is omitted or zero, the current 'encoding' is used. - Example for "utf-8": > - char2nr("á") returns 225 - char2nr("á"[0]) returns 195 -< With {utf8} set to 1, always treat as utf-8 characters. - A combining character is a separate character. - |nr2char()| does the opposite. - -cindent({lnum}) *cindent()* - Get the amount of indent for line {lnum} according the C - indenting rules, as with 'cindent'. - The indent is counted in spaces, the value of 'tabstop' is - relevant. {lnum} is used just like in |getline()|. - When {lnum} is invalid or Vim was not compiled the |+cindent| - feature, -1 is returned. - See |C-indenting|. - -clearmatches() *clearmatches()* - Clears all matches previously defined by |matchadd()| and the - |:match| commands. - - *col()* -col({expr}) The result is a Number, which is the byte index of the column - position given with {expr}. The accepted positions are: - . the cursor position - $ the end of the cursor line (the result is the - number of bytes in the cursor line plus one) - 'x position of mark x (if the mark is not set, 0 is - returned) - v In Visual mode: the start of the Visual area (the - cursor is the end). When not in Visual mode - returns the cursor position. Differs from |'<| in - that it's updated right away. - Additionally {expr} can be [lnum, col]: a |List| with the line - and column number. Most useful when the column is "$", to get - the last column of a specific line. When "lnum" or "col" is - out of range then col() returns zero. - To get the line number use |line()|. To get both use - |getpos()|. - For the screen column position use |virtcol()|. - Note that only marks in the current file can be used. - Examples: > - col(".") column of cursor - col("$") length of cursor line plus one - col("'t") column of mark t - col("'" . markname) column of mark markname -< The first column is 1. 0 is returned for an error. - For an uppercase mark the column may actually be in another - buffer. - For the cursor position, when 'virtualedit' is active, the - column is one higher if the cursor is after the end of the - line. This can be used to obtain the column in Insert mode: > - :imap <F2> <C-O>:let save_ve = &ve<CR> - \<C-O>:set ve=all<CR> - \<C-O>:echo col(".") . "\n" <Bar> - \let &ve = save_ve<CR> -< - -complete({startcol}, {matches}) *complete()* *E785* - Set the matches for Insert mode completion. - Can only be used in Insert mode. You need to use a mapping - with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O - or with an expression mapping. - {startcol} is the byte offset in the line where the completed - text start. The text up to the cursor is the original text - that will be replaced by the matches. Use col('.') for an - empty string. "col('.') - 1" will replace one character by a - match. - {matches} must be a |List|. Each |List| item is one match. - See |complete-items| for the kind of items that are possible. - Note that the after calling this function you need to avoid - inserting anything that would cause completion to stop. - The match can be selected with CTRL-N and CTRL-P as usual with - Insert mode completion. The popup menu will appear if - specified, see |ins-completion-menu|. - Example: > - inoremap <F5> <C-R>=ListMonths()<CR> - - func! ListMonths() - call complete(col('.'), ['January', 'February', 'March', - \ 'April', 'May', 'June', 'July', 'August', 'September', - \ 'October', 'November', 'December']) - return '' - endfunc -< This isn't very useful, but it shows how it works. Note that - an empty string is returned to avoid a zero being inserted. - -complete_add({expr}) *complete_add()* - Add {expr} to the list of matches. Only to be used by the - function specified with the 'completefunc' option. - Returns 0 for failure (empty string or out of memory), - 1 when the match was added, 2 when the match was already in - the list. - See |complete-functions| for an explanation of {expr}. It is - the same as one item in the list that 'omnifunc' would return. - -complete_check() *complete_check()* - Check for a key typed while looking for completion matches. - This is to be used when looking for matches takes some time. - Returns |TRUE| when searching for matches is to be aborted, - zero otherwise. - Only to be used by the function specified with the - 'completefunc' option. - - *confirm()* -confirm({msg} [, {choices} [, {default} [, {type}]]]) - Confirm() offers the user a dialog, from which a choice can be - made. It returns the number of the choice. For the first - choice this is 1. - Note: confirm() is only supported when compiled with dialog - support, see |+dialog_con| and |+dialog_gui|. - - {msg} is displayed in a |dialog| with {choices} as the - alternatives. When {choices} is missing or empty, "&OK" is - used (and translated). - {msg} is a String, use '\n' to include a newline. Only on - some systems the string is wrapped when it doesn't fit. - - {choices} is a String, with the individual choices separated - by '\n', e.g. > - confirm("Save changes?", "&Yes\n&No\n&Cancel") -< The letter after the '&' is the shortcut key for that choice. - Thus you can type 'c' to select "Cancel". The shortcut does - not need to be the first letter: > - confirm("file has been modified", "&Save\nSave &All") -< For the console, the first letter of each choice is used as - the default shortcut key. - - The optional {default} argument is the number of the choice - that is made if the user hits <CR>. Use 1 to make the first - choice the default one. Use 0 to not set a default. If - {default} is omitted, 1 is used. - - The optional {type} argument gives the type of dialog. This - is only used for the icon of the GTK, Mac, Motif and Win32 - GUI. It can be one of these values: "Error", "Question", - "Info", "Warning" or "Generic". Only the first character is - relevant. When {type} is omitted, "Generic" is used. - - If the user aborts the dialog by pressing <Esc>, CTRL-C, - or another valid interrupt key, confirm() returns 0. - - An example: > - :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2) - :if choice == 0 - : echo "make up your mind!" - :elseif choice == 3 - : echo "tasteful" - :else - : echo "I prefer bananas myself." - :endif -< In a GUI dialog, buttons are used. The layout of the buttons - depends on the 'v' flag in 'guioptions'. If it is included, - the buttons are always put vertically. Otherwise, confirm() - tries to put the buttons in one horizontal line. If they - don't fit, a vertical layout is used anyway. For some systems - the horizontal layout is always used. - ch_canread({handle}) *ch_canread()* Return non-zero when there is something to read from {handle}. {handle} can be a Channel or a Job that has a Channel. @@ -3196,6 +3029,176 @@ ch_status({handle} [, {options}]) *ch_status()* "err". For example, to get the error status: > ch_status(job, {"part": "err"}) < +changenr() *changenr()* + Return the number of the most recent change. This is the same + number as what is displayed with |:undolist| and can be used + with the |:undo| command. + When a change was made it is the number of that change. After + redo it is the number of the redone change. After undo it is + one less than the number of the undone change. + +char2nr({expr}[, {utf8}]) *char2nr()* + Return number value of the first char in {expr}. Examples: > + char2nr(" ") returns 32 + char2nr("ABC") returns 65 +< When {utf8} is omitted or zero, the current 'encoding' is used. + Example for "utf-8": > + char2nr("á") returns 225 + char2nr("á"[0]) returns 195 +< With {utf8} set to 1, always treat as utf-8 characters. + A combining character is a separate character. + |nr2char()| does the opposite. + +cindent({lnum}) *cindent()* + Get the amount of indent for line {lnum} according the C + indenting rules, as with 'cindent'. + The indent is counted in spaces, the value of 'tabstop' is + relevant. {lnum} is used just like in |getline()|. + When {lnum} is invalid or Vim was not compiled the |+cindent| + feature, -1 is returned. + See |C-indenting|. + +clearmatches() *clearmatches()* + Clears all matches previously defined by |matchadd()| and the + |:match| commands. + + *col()* +col({expr}) The result is a Number, which is the byte index of the column + position given with {expr}. The accepted positions are: + . the cursor position + $ the end of the cursor line (the result is the + number of bytes in the cursor line plus one) + 'x position of mark x (if the mark is not set, 0 is + returned) + v In Visual mode: the start of the Visual area (the + cursor is the end). When not in Visual mode + returns the cursor position. Differs from |'<| in + that it's updated right away. + Additionally {expr} can be [lnum, col]: a |List| with the line + and column number. Most useful when the column is "$", to get + the last column of a specific line. When "lnum" or "col" is + out of range then col() returns zero. + To get the line number use |line()|. To get both use + |getpos()|. + For the screen column position use |virtcol()|. + Note that only marks in the current file can be used. + Examples: > + col(".") column of cursor + col("$") length of cursor line plus one + col("'t") column of mark t + col("'" . markname) column of mark markname +< The first column is 1. 0 is returned for an error. + For an uppercase mark the column may actually be in another + buffer. + For the cursor position, when 'virtualedit' is active, the + column is one higher if the cursor is after the end of the + line. This can be used to obtain the column in Insert mode: > + :imap <F2> <C-O>:let save_ve = &ve<CR> + \<C-O>:set ve=all<CR> + \<C-O>:echo col(".") . "\n" <Bar> + \let &ve = save_ve<CR> +< + +complete({startcol}, {matches}) *complete()* *E785* + Set the matches for Insert mode completion. + Can only be used in Insert mode. You need to use a mapping + with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O + or with an expression mapping. + {startcol} is the byte offset in the line where the completed + text start. The text up to the cursor is the original text + that will be replaced by the matches. Use col('.') for an + empty string. "col('.') - 1" will replace one character by a + match. + {matches} must be a |List|. Each |List| item is one match. + See |complete-items| for the kind of items that are possible. + Note that the after calling this function you need to avoid + inserting anything that would cause completion to stop. + The match can be selected with CTRL-N and CTRL-P as usual with + Insert mode completion. The popup menu will appear if + specified, see |ins-completion-menu|. + Example: > + inoremap <F5> <C-R>=ListMonths()<CR> + + func! ListMonths() + call complete(col('.'), ['January', 'February', 'March', + \ 'April', 'May', 'June', 'July', 'August', 'September', + \ 'October', 'November', 'December']) + return '' + endfunc +< This isn't very useful, but it shows how it works. Note that + an empty string is returned to avoid a zero being inserted. + +complete_add({expr}) *complete_add()* + Add {expr} to the list of matches. Only to be used by the + function specified with the 'completefunc' option. + Returns 0 for failure (empty string or out of memory), + 1 when the match was added, 2 when the match was already in + the list. + See |complete-functions| for an explanation of {expr}. It is + the same as one item in the list that 'omnifunc' would return. + +complete_check() *complete_check()* + Check for a key typed while looking for completion matches. + This is to be used when looking for matches takes some time. + Returns |TRUE| when searching for matches is to be aborted, + zero otherwise. + Only to be used by the function specified with the + 'completefunc' option. + + *confirm()* +confirm({msg} [, {choices} [, {default} [, {type}]]]) + Confirm() offers the user a dialog, from which a choice can be + made. It returns the number of the choice. For the first + choice this is 1. + Note: confirm() is only supported when compiled with dialog + support, see |+dialog_con| and |+dialog_gui|. + + {msg} is displayed in a |dialog| with {choices} as the + alternatives. When {choices} is missing or empty, "&OK" is + used (and translated). + {msg} is a String, use '\n' to include a newline. Only on + some systems the string is wrapped when it doesn't fit. + + {choices} is a String, with the individual choices separated + by '\n', e.g. > + confirm("Save changes?", "&Yes\n&No\n&Cancel") +< The letter after the '&' is the shortcut key for that choice. + Thus you can type 'c' to select "Cancel". The shortcut does + not need to be the first letter: > + confirm("file has been modified", "&Save\nSave &All") +< For the console, the first letter of each choice is used as + the default shortcut key. + + The optional {default} argument is the number of the choice + that is made if the user hits <CR>. Use 1 to make the first + choice the default one. Use 0 to not set a default. If + {default} is omitted, 1 is used. + + The optional {type} argument gives the type of dialog. This + is only used for the icon of the GTK, Mac, Motif and Win32 + GUI. It can be one of these values: "Error", "Question", + "Info", "Warning" or "Generic". Only the first character is + relevant. When {type} is omitted, "Generic" is used. + + If the user aborts the dialog by pressing <Esc>, CTRL-C, + or another valid interrupt key, confirm() returns 0. + + An example: > + :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2) + :if choice == 0 + : echo "make up your mind!" + :elseif choice == 3 + : echo "tasteful" + :else + : echo "I prefer bananas myself." + :endif +< In a GUI dialog, buttons are used. The layout of the buttons + depends on the 'v' flag in 'guioptions'. If it is included, + the buttons are always put vertically. Otherwise, confirm() + tries to put the buttons in one horizontal line. If they + don't fit, a vertical layout is used anyway. For some systems + the horizontal layout is always used. + *copy()* copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't different from using {expr} directly. @@ -3452,7 +3455,7 @@ execute({command} [, {silent}]) *execute()* "" no `:silent` used "silent" `:silent` used "silent!" `:silent!` used - The default is 'silent'. Note that with "silent!", unlike + The default is "silent". Note that with "silent!", unlike `:redir`, error messages are dropped. When using an external command the screen may be messed up, use `system()` instead. *E930* @@ -4054,10 +4057,10 @@ get({dict}, {key} [, {default}]) get({func}, {what}) Get an item with from Funcref {func}. Possible values for {what} are: - 'name' The function name - 'func' The function - 'dict' The dictionary - 'args' The list with arguments + "name" The function name + "func" The function + "dict" The dictionary + "args" The list with arguments *getbufinfo()* getbufinfo([{expr}]) @@ -7735,7 +7738,7 @@ taglist({expr}) *taglist()* may appear, they give the name of the entity the tag is contained in. - The ex-command 'cmd' can be either an ex search pattern, a + The ex-command "cmd" can be either an ex search pattern, a line number or a line number followed by a byte number. If there are no matching tags, then an empty list is returned. |