zeertzjq | e2c0f81 | 2025-07-06 20:26:56 +0200 | [diff] [blame] | 1 | *builtin.txt* For Vim version 9.1. Last change: 2025 Jul 06 |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2 | |
| 3 | |
| 4 | VIM REFERENCE MANUAL by Bram Moolenaar |
| 5 | |
| 6 | |
| 7 | Builtin functions *builtin-functions* |
| 8 | |
Bram Moolenaar | f269eab | 2022-10-03 18:04:35 +0100 | [diff] [blame] | 9 | Note: Expression evaluation can be disabled at compile time, the builtin |
| 10 | functions are not available then. See |+eval| and |no-eval-feature|. |
| 11 | |
| 12 | For functions grouped by what they are used for see |function-list|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 13 | |
| 14 | 1. Overview |builtin-function-list| |
| 15 | 2. Details |builtin-function-details| |
| 16 | 3. Feature list |feature-list| |
| 17 | 4. Matching a pattern in a String |string-match| |
| 18 | |
| 19 | ============================================================================== |
| 20 | 1. Overview *builtin-function-list* |
| 21 | |
| 22 | Use CTRL-] on the function name to jump to the full explanation. |
| 23 | |
| 24 | USAGE RESULT DESCRIPTION ~ |
| 25 | |
| 26 | abs({expr}) Float or Number absolute value of {expr} |
| 27 | acos({expr}) Float arc cosine of {expr} |
| 28 | add({object}, {item}) List/Blob append {item} to {object} |
| 29 | and({expr}, {expr}) Number bitwise AND |
| 30 | append({lnum}, {text}) Number append {text} below line {lnum} |
errael | f0837ba | 2024-06-24 12:27:01 -0700 | [diff] [blame] | 31 | appendbufline({buf}, {lnum}, {text}) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 32 | Number append {text} below line {lnum} |
errael | f0837ba | 2024-06-24 12:27:01 -0700 | [diff] [blame] | 33 | in buffer {buf} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 34 | argc([{winid}]) Number number of files in the argument list |
| 35 | argidx() Number current index in the argument list |
| 36 | arglistid([{winnr} [, {tabnr}]]) Number argument list id |
| 37 | argv({nr} [, {winid}]) String {nr} entry of the argument list |
| 38 | argv([-1, {winid}]) List the argument list |
| 39 | asin({expr}) Float arc sine of {expr} |
| 40 | assert_beeps({cmd}) Number assert {cmd} causes a beep |
| 41 | assert_equal({exp}, {act} [, {msg}]) |
| 42 | Number assert {exp} is equal to {act} |
| 43 | assert_equalfile({fname-one}, {fname-two} [, {msg}]) |
| 44 | Number assert file contents are equal |
| 45 | assert_exception({error} [, {msg}]) |
| 46 | Number assert {error} is in v:exception |
| 47 | assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]]) |
| 48 | Number assert {cmd} fails |
| 49 | assert_false({actual} [, {msg}]) |
| 50 | Number assert {actual} is false |
| 51 | assert_inrange({lower}, {upper}, {actual} [, {msg}]) |
| 52 | Number assert {actual} is inside the range |
| 53 | assert_match({pat}, {text} [, {msg}]) |
| 54 | Number assert {pat} matches {text} |
| 55 | assert_nobeep({cmd}) Number assert {cmd} does not cause a beep |
| 56 | assert_notequal({exp}, {act} [, {msg}]) |
| 57 | Number assert {exp} is not equal {act} |
| 58 | assert_notmatch({pat}, {text} [, {msg}]) |
| 59 | Number assert {pat} not matches {text} |
| 60 | assert_report({msg}) Number report a test failure |
| 61 | assert_true({actual} [, {msg}]) Number assert {actual} is true |
| 62 | atan({expr}) Float arc tangent of {expr} |
| 63 | atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2} |
Yegappan Lakshmanan | 1755a91 | 2022-05-19 10:31:47 +0100 | [diff] [blame] | 64 | autocmd_add({acmds}) Bool add a list of autocmds and groups |
| 65 | autocmd_delete({acmds}) Bool delete a list of autocmds and groups |
| 66 | autocmd_get([{opts}]) List return a list of autocmds |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 67 | balloon_gettext() String current text in the balloon |
| 68 | balloon_show({expr}) none show {expr} inside the balloon |
| 69 | balloon_split({msg}) List split {msg} as used for a balloon |
h-east | e80f345 | 2025-01-02 10:40:29 +0100 | [diff] [blame] | 70 | base64_decode({string}) Blob base64 decode {string} characters |
| 71 | base64_encode({blob}) String base64 encode the bytes in {blob} |
Christ van Willegen | ce0ef91 | 2024-06-20 23:41:59 +0200 | [diff] [blame] | 72 | bindtextdomain({package}, {path}) |
Christ van Willegen | 8252ef1 | 2024-07-11 21:36:21 +0200 | [diff] [blame] | 73 | Bool bind text domain to specified path |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 74 | blob2list({blob}) List convert {blob} into a list of numbers |
Yegappan Lakshmanan | 166b175 | 2025-01-17 11:48:12 +0100 | [diff] [blame] | 75 | blob2str({blob} [, {options}]) List convert {blob} into a list of strings |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 76 | browse({save}, {title}, {initdir}, {default}) |
| 77 | String put up a file requester |
| 78 | browsedir({title}, {initdir}) String put up a directory requester |
| 79 | bufadd({name}) Number add a buffer to the buffer list |
| 80 | bufexists({buf}) Number |TRUE| if buffer {buf} exists |
| 81 | buflisted({buf}) Number |TRUE| if buffer {buf} is listed |
| 82 | bufload({buf}) Number load buffer {buf} if not loaded yet |
| 83 | bufloaded({buf}) Number |TRUE| if buffer {buf} is loaded |
| 84 | bufname([{buf}]) String Name of the buffer {buf} |
| 85 | bufnr([{buf} [, {create}]]) Number Number of the buffer {buf} |
| 86 | bufwinid({buf}) Number window ID of buffer {buf} |
| 87 | bufwinnr({buf}) Number window number of buffer {buf} |
| 88 | byte2line({byte}) Number line number at byte count {byte} |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 89 | byteidx({expr}, {nr} [, {utf16}]) |
| 90 | Number byte index of {nr}'th char in {expr} |
| 91 | byteidxcomp({expr}, {nr} [, {utf16}]) |
| 92 | Number byte index of {nr}'th char in {expr} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 93 | call({func}, {arglist} [, {dict}]) |
| 94 | any call {func} with arguments {arglist} |
| 95 | ceil({expr}) Float round {expr} up |
| 96 | ch_canread({handle}) Number check if there is something to read |
| 97 | ch_close({handle}) none close {handle} |
| 98 | ch_close_in({handle}) none close in part of {handle} |
| 99 | ch_evalexpr({handle}, {expr} [, {options}]) |
| 100 | any evaluate {expr} on JSON {handle} |
| 101 | ch_evalraw({handle}, {string} [, {options}]) |
| 102 | any evaluate {string} on raw {handle} |
| 103 | ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what} |
| 104 | ch_getjob({channel}) Job get the Job of {channel} |
| 105 | ch_info({handle}) String info about channel {handle} |
| 106 | ch_log({msg} [, {handle}]) none write {msg} in the channel log file |
| 107 | ch_logfile({fname} [, {mode}]) none start logging channel activity |
| 108 | ch_open({address} [, {options}]) |
| 109 | Channel open a channel to {address} |
| 110 | ch_read({handle} [, {options}]) String read from {handle} |
| 111 | ch_readblob({handle} [, {options}]) |
| 112 | Blob read Blob from {handle} |
| 113 | ch_readraw({handle} [, {options}]) |
| 114 | String read raw from {handle} |
| 115 | ch_sendexpr({handle}, {expr} [, {options}]) |
| 116 | any send {expr} over JSON {handle} |
| 117 | ch_sendraw({handle}, {expr} [, {options}]) |
| 118 | any send {expr} over raw {handle} |
| 119 | ch_setoptions({handle}, {options}) |
| 120 | none set options for {handle} |
| 121 | ch_status({handle} [, {options}]) |
| 122 | String status of channel {handle} |
| 123 | changenr() Number current change number |
| 124 | char2nr({expr} [, {utf8}]) Number ASCII/UTF-8 value of first char in {expr} |
| 125 | charclass({string}) Number character class of {string} |
Yegappan Lakshmanan | 4c8d2f0 | 2022-11-12 16:07:47 +0000 | [diff] [blame] | 126 | charcol({expr} [, {winid}]) Number column number of cursor or mark |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 127 | charidx({string}, {idx} [, {countcc} [, {utf16}]]) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 128 | Number char index of byte {idx} in {string} |
| 129 | chdir({dir}) String change current working directory |
| 130 | cindent({lnum}) Number C indent for line {lnum} |
| 131 | clearmatches([{win}]) none clear all matches |
Girish Palya | 92f68e2 | 2025-04-21 11:12:41 +0200 | [diff] [blame] | 132 | cmdcomplete_info() Dict get current cmdline completion |
| 133 | information |
Yegappan Lakshmanan | 4c8d2f0 | 2022-11-12 16:07:47 +0000 | [diff] [blame] | 134 | col({expr} [, {winid}]) Number column byte index of cursor or mark |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 135 | complete({startcol}, {matches}) none set Insert mode completion |
| 136 | complete_add({expr}) Number add completion match |
| 137 | complete_check() Number check for key typed during completion |
| 138 | complete_info([{what}]) Dict get current completion information |
glepnir | bcd5995 | 2025-04-24 21:48:35 +0200 | [diff] [blame] | 139 | complete_match([{lnum}, {col}]) List get completion column and trigger text |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 140 | confirm({msg} [, {choices} [, {default} [, {type}]]]) |
| 141 | Number number of choice picked by user |
| 142 | copy({expr}) any make a shallow copy of {expr} |
| 143 | cos({expr}) Float cosine of {expr} |
| 144 | cosh({expr}) Float hyperbolic cosine of {expr} |
| 145 | count({comp}, {expr} [, {ic} [, {start}]]) |
| 146 | Number count how many {expr} are in {comp} |
| 147 | cscope_connection([{num}, {dbpath} [, {prepend}]]) |
| 148 | Number checks existence of cscope connection |
| 149 | cursor({lnum}, {col} [, {off}]) |
| 150 | Number move cursor to {lnum}, {col}, {off} |
| 151 | cursor({list}) Number move cursor to position in {list} |
| 152 | debugbreak({pid}) Number interrupt process being debugged |
| 153 | deepcopy({expr} [, {noref}]) any make a full copy of {expr} |
| 154 | delete({fname} [, {flags}]) Number delete the file or directory {fname} |
| 155 | deletebufline({buf}, {first} [, {last}]) |
| 156 | Number delete lines from buffer {buf} |
| 157 | did_filetype() Number |TRUE| if FileType autocmd event used |
Yegappan Lakshmanan | fa37835 | 2024-02-01 22:05:27 +0100 | [diff] [blame] | 158 | diff({fromlist}, {tolist} [, {options}]) |
| 159 | List diff two Lists of strings |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 160 | diff_filler({lnum}) Number diff filler lines about {lnum} |
| 161 | diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col} |
| 162 | digraph_get({chars}) String get the |digraph| of {chars} |
| 163 | digraph_getlist([{listall}]) List get all |digraph|s |
Christian Brabandt | fbc37f1 | 2024-06-18 20:50:58 +0200 | [diff] [blame] | 164 | digraph_set({chars}, {digraph}) Bool register |digraph| |
| 165 | digraph_setlist({digraphlist}) Bool register multiple |digraph|s |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 166 | echoraw({expr}) none output {expr} as-is |
| 167 | empty({expr}) Number |TRUE| if {expr} is empty |
| 168 | environ() Dict return environment variables |
Sean Dewar | b0efa49 | 2023-07-08 10:35:19 +0100 | [diff] [blame] | 169 | err_teapot([{expr}]) none give E418, or E503 if {expr} is |TRUE| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 170 | escape({string}, {chars}) String escape {chars} in {string} with '\' |
| 171 | eval({string}) any evaluate {string} into its value |
| 172 | eventhandler() Number |TRUE| if inside an event handler |
| 173 | executable({expr}) Number 1 if executable {expr} exists |
| 174 | execute({command}) String execute {command} and get the output |
| 175 | exepath({expr}) String full path of the command {expr} |
| 176 | exists({expr}) Number |TRUE| if {expr} exists |
| 177 | exists_compiled({expr}) Number |TRUE| if {expr} exists at compile time |
| 178 | exp({expr}) Float exponential of {expr} |
| 179 | expand({expr} [, {nosuf} [, {list}]]) |
| 180 | any expand special keywords in {expr} |
Yegappan Lakshmanan | 2b74b68 | 2022-04-03 21:30:32 +0100 | [diff] [blame] | 181 | expandcmd({string} [, {options}]) |
| 182 | String expand {string} like with `:edit` |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 183 | extend({expr1}, {expr2} [, {expr3}]) |
| 184 | List/Dict insert items of {expr2} into {expr1} |
| 185 | extendnew({expr1}, {expr2} [, {expr3}]) |
| 186 | List/Dict like |extend()| but creates a new |
| 187 | List or Dictionary |
| 188 | feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer |
Shougo Matsushita | 60c8743 | 2024-06-03 22:59:27 +0200 | [diff] [blame] | 189 | filecopy({from}, {to}) Number |TRUE| if copying file {from} to {to} |
| 190 | worked |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 191 | filereadable({file}) Number |TRUE| if {file} is a readable file |
| 192 | filewritable({file}) Number |TRUE| if {file} is a writable file |
| 193 | filter({expr1}, {expr2}) List/Dict/Blob/String |
| 194 | remove items from {expr1} where |
| 195 | {expr2} is 0 |
| 196 | finddir({name} [, {path} [, {count}]]) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 197 | findfile({name} [, {path} [, {count}]]) |
Christian Brabandt | 17ad852 | 2025-05-09 00:03:20 +0200 | [diff] [blame] | 198 | String/List find dir/file {name} in {path} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 199 | flatten({list} [, {maxdepth}]) List flatten {list} up to {maxdepth} levels |
| 200 | flattennew({list} [, {maxdepth}]) |
| 201 | List flatten a copy of {list} |
| 202 | float2nr({expr}) Number convert Float {expr} to a Number |
| 203 | floor({expr}) Float round {expr} down |
| 204 | fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2} |
| 205 | fnameescape({fname}) String escape special characters in {fname} |
| 206 | fnamemodify({fname}, {mods}) String modify file name |
| 207 | foldclosed({lnum}) Number first line of fold at {lnum} if closed |
| 208 | foldclosedend({lnum}) Number last line of fold at {lnum} if closed |
| 209 | foldlevel({lnum}) Number fold level at {lnum} |
| 210 | foldtext() String line displayed for closed fold |
| 211 | foldtextresult({lnum}) String text for closed fold at {lnum} |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 212 | foreach({expr1}, {expr2}) List/Tuple/Dict/Blob/String |
Ernie Rael | e79e207 | 2024-01-13 11:47:33 +0100 | [diff] [blame] | 213 | for each item in {expr1} call {expr2} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 214 | foreground() Number bring the Vim window to the foreground |
Bram Moolenaar | aa53414 | 2022-09-15 21:46:02 +0100 | [diff] [blame] | 215 | fullcommand({name} [, {vim9}]) String get full command from {name} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 216 | funcref({name} [, {arglist}] [, {dict}]) |
| 217 | Funcref reference to function {name} |
| 218 | function({name} [, {arglist}] [, {dict}]) |
| 219 | Funcref named reference to function {name} |
| 220 | garbagecollect([{atexit}]) none free memory, breaking cyclic references |
| 221 | get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def} |
| 222 | get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def} |
| 223 | get({func}, {what}) any get property of funcref/partial {func} |
| 224 | getbufinfo([{buf}]) List information about buffers |
| 225 | getbufline({buf}, {lnum} [, {end}]) |
| 226 | List lines {lnum} to {end} of buffer {buf} |
Bram Moolenaar | ce30ccc | 2022-11-21 19:57:04 +0000 | [diff] [blame] | 227 | getbufoneline({buf}, {lnum}) String line {lnum} of buffer {buf} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 228 | getbufvar({buf}, {varname} [, {def}]) |
| 229 | any variable {varname} in buffer {buf} |
mikoto2000 | 1083cae | 2024-11-11 21:24:14 +0100 | [diff] [blame] | 230 | getcellpixels() List get character cell pixel size |
Kota Kato | 66bb9ae | 2023-01-17 18:31:56 +0000 | [diff] [blame] | 231 | getcellwidths() List get character cell width overrides |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 232 | getchangelist([{buf}]) List list of change list items |
zeertzjq | e0a2ab3 | 2025-02-02 09:14:35 +0100 | [diff] [blame] | 233 | getchar([{expr} [, {opts}]]) Number or String |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 234 | get one character from the user |
| 235 | getcharmod() Number modifiers for the last typed character |
| 236 | getcharpos({expr}) List position of cursor, mark, etc. |
| 237 | getcharsearch() Dict last character search |
zeertzjq | e0a2ab3 | 2025-02-02 09:14:35 +0100 | [diff] [blame] | 238 | getcharstr([{expr} [, {opts}]]) String get one character from the user |
Ruslan Russkikh | 0407d62 | 2024-10-08 22:21:05 +0200 | [diff] [blame] | 239 | getcmdcomplpat() String return the completion pattern of the |
| 240 | current command-line completion |
Hirohito Higashi | 96b3ef2 | 2025-07-05 15:31:23 +0200 | [diff] [blame] | 241 | getcmdcompltype() String return the type of the current |
| 242 | command-line completion |
Shougo Matsushita | 6908428 | 2024-09-23 20:34:47 +0200 | [diff] [blame] | 243 | getcmdline() String return the current command-line input |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 244 | getcmdpos() Number return cursor position in command-line |
Shougo Matsushita | 6908428 | 2024-09-23 20:34:47 +0200 | [diff] [blame] | 245 | getcmdprompt() String return the current command-line prompt |
Shougo Matsushita | 79d599b | 2022-05-07 12:48:29 +0100 | [diff] [blame] | 246 | getcmdscreenpos() Number return cursor screen position in |
| 247 | command-line |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 248 | getcmdtype() String return current command-line type |
| 249 | getcmdwintype() String return current command-line window type |
| 250 | getcompletion({pat}, {type} [, {filtered}]) |
| 251 | List list of cmdline completion matches |
Hirohito Higashi | 96b3ef2 | 2025-07-05 15:31:23 +0200 | [diff] [blame] | 252 | getcompletiontype({pat}) String return the type of the command-line |
| 253 | completion using {pat} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 254 | getcurpos([{winnr}]) List position of the cursor |
| 255 | getcursorcharpos([{winnr}]) List character position of the cursor |
| 256 | getcwd([{winnr} [, {tabnr}]]) String get the current working directory |
| 257 | getenv({name}) String return environment variable |
| 258 | getfontname([{name}]) String name of font being used |
| 259 | getfperm({fname}) String file permissions of file {fname} |
| 260 | getfsize({fname}) Number size in bytes of file {fname} |
| 261 | getftime({fname}) Number last modification time of file |
| 262 | getftype({fname}) String description of type of file {fname} |
| 263 | getimstatus() Number |TRUE| if the IME status is active |
| 264 | getjumplist([{winnr} [, {tabnr}]]) |
| 265 | List list of jump list items |
| 266 | getline({lnum}) String line {lnum} of current buffer |
| 267 | getline({lnum}, {end}) List lines {lnum} to {end} of current buffer |
| 268 | getloclist({nr}) List list of location list items |
| 269 | getloclist({nr}, {what}) Dict get specific location list properties |
| 270 | getmarklist([{buf}]) List list of global/local marks |
| 271 | getmatches([{win}]) List list of current matches |
| 272 | getmousepos() Dict last known mouse position |
Bram Moolenaar | 24dc19c | 2022-11-14 19:49:15 +0000 | [diff] [blame] | 273 | getmouseshape() String current mouse shape name |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 274 | getpid() Number process ID of Vim |
| 275 | getpos({expr}) List position of cursor, mark, etc. |
| 276 | getqflist() List list of quickfix items |
| 277 | getqflist({what}) Dict get specific quickfix list properties |
| 278 | getreg([{regname} [, 1 [, {list}]]]) |
| 279 | String or List contents of a register |
| 280 | getreginfo([{regname}]) Dict information about a register |
Shougo Matsushita | 19b7188 | 2024-02-28 22:48:12 +0100 | [diff] [blame] | 281 | getregion({pos1}, {pos2} [, {opts}]) |
Shougo Matsushita | 3f905ab | 2024-02-21 00:02:45 +0100 | [diff] [blame] | 282 | List get the text from {pos1} to {pos2} |
Shougo Matsushita | b4757e6 | 2024-05-07 20:49:24 +0200 | [diff] [blame] | 283 | getregionpos({pos1}, {pos2} [, {opts}]) |
| 284 | List get a list of positions for a region |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 285 | getregtype([{regname}]) String type of a register |
Yegappan Lakshmanan | 520f6ef | 2022-08-25 17:40:40 +0100 | [diff] [blame] | 286 | getscriptinfo([{opts}]) List list of sourced scripts |
ichizok | 663d18d | 2025-01-02 18:06:00 +0100 | [diff] [blame] | 287 | getstacktrace() List get current stack trace of Vim scripts |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 288 | gettabinfo([{expr}]) List list of tab pages |
| 289 | gettabvar({nr}, {varname} [, {def}]) |
| 290 | any variable {varname} in tab {nr} or {def} |
| 291 | gettabwinvar({tabnr}, {winnr}, {name} [, {def}]) |
| 292 | any {name} in {winnr} in tab page {tabnr} |
| 293 | gettagstack([{nr}]) Dict get the tag stack of window {nr} |
h-east | 52e7cc2 | 2024-07-28 17:03:29 +0200 | [diff] [blame] | 294 | gettext({text} [, {package}]) String lookup translation of {text} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 295 | getwininfo([{winid}]) List list of info about each window |
Bram Moolenaar | 938ae28 | 2023-02-20 20:44:55 +0000 | [diff] [blame] | 296 | getwinpos([{timeout}]) List X and Y coord in pixels of Vim window |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 297 | getwinposx() Number X coord in pixels of the Vim window |
| 298 | getwinposy() Number Y coord in pixels of the Vim window |
| 299 | getwinvar({nr}, {varname} [, {def}]) |
| 300 | any variable {varname} in window {nr} |
| 301 | glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) |
| 302 | any expand file wildcards in {expr} |
| 303 | glob2regpat({expr}) String convert a glob pat into a search pat |
| 304 | globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]]) |
| 305 | String do glob({expr}) for all dirs in {path} |
| 306 | has({feature} [, {check}]) Number |TRUE| if feature {feature} supported |
| 307 | has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key} |
| 308 | haslocaldir([{winnr} [, {tabnr}]]) |
| 309 | Number |TRUE| if the window executed |:lcd| |
| 310 | or |:tcd| |
| 311 | hasmapto({what} [, {mode} [, {abbr}]]) |
| 312 | Number |TRUE| if mapping to {what} exists |
| 313 | histadd({history}, {item}) Number add an item to a history |
| 314 | histdel({history} [, {item}]) Number remove an item from a history |
| 315 | histget({history} [, {index}]) String get the item {index} from a history |
| 316 | histnr({history}) Number highest index of a history |
| 317 | hlID({name}) Number syntax ID of highlight group {name} |
| 318 | hlexists({name}) Number |TRUE| if highlight group {name} exists |
| 319 | hlget([{name} [, {resolve}]]) List get highlight group attributes |
| 320 | hlset({list}) Number set highlight group attributes |
| 321 | hostname() String name of the machine Vim is running on |
| 322 | iconv({expr}, {from}, {to}) String convert encoding of {expr} |
Ernie Rael | 0512425 | 2024-07-11 22:10:45 +0200 | [diff] [blame] | 323 | id({item}) String get unique identity string of item |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 324 | indent({lnum}) Number indent of line {lnum} |
| 325 | index({object}, {expr} [, {start} [, {ic}]]) |
| 326 | Number index in {object} where {expr} appears |
Yegappan Lakshmanan | b218655 | 2022-08-13 13:09:20 +0100 | [diff] [blame] | 327 | indexof({object}, {expr} [, {opts}]]) |
| 328 | Number index in {object} where {expr} is true |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 329 | input({prompt} [, {text} [, {completion}]]) |
| 330 | String get input from the user |
Bram Moolenaar | b529cfb | 2022-07-25 15:42:07 +0100 | [diff] [blame] | 331 | inputdialog({prompt} [, {text} [, {cancelreturn}]]) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 332 | String like input() but in a GUI dialog |
| 333 | inputlist({textlist}) Number let the user pick from a choice list |
| 334 | inputrestore() Number restore typeahead |
| 335 | inputsave() Number save and clear typeahead |
| 336 | inputsecret({prompt} [, {text}]) String like input() but hiding the text |
| 337 | insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}] |
LemonBoy | afe0466 | 2023-08-23 21:08:11 +0200 | [diff] [blame] | 338 | instanceof({object}, {class}) Number |TRUE| if {object} is an instance of {class} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 339 | interrupt() none interrupt script execution |
| 340 | invert({expr}) Number bitwise invert |
LemonBoy | dca1d40 | 2022-04-28 15:26:33 +0100 | [diff] [blame] | 341 | isabsolutepath({path}) Number |TRUE| if {path} is an absolute path |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 342 | isdirectory({directory}) Number |TRUE| if {directory} is a directory |
| 343 | isinf({expr}) Number determine if {expr} is infinity value |
| 344 | (positive or negative) |
| 345 | islocked({expr}) Number |TRUE| if {expr} is locked |
| 346 | isnan({expr}) Number |TRUE| if {expr} is NaN |
| 347 | items({dict}) List key-value pairs in {dict} |
| 348 | job_getchannel({job}) Channel get the channel handle for {job} |
| 349 | job_info([{job}]) Dict get information about {job} |
| 350 | job_setoptions({job}, {options}) none set options for {job} |
| 351 | job_start({command} [, {options}]) |
| 352 | Job start a job |
| 353 | job_status({job}) String get the status of {job} |
| 354 | job_stop({job} [, {how}]) Number stop {job} |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 355 | join({expr} [, {sep}]) String join items in {expr} into one String |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 356 | js_decode({string}) any decode JS style JSON |
| 357 | js_encode({expr}) String encode JS style JSON |
| 358 | json_decode({string}) any decode JSON |
| 359 | json_encode({expr}) String encode JSON |
| 360 | keys({dict}) List keys in {dict} |
zeertzjq | cdc8393 | 2022-09-12 13:38:41 +0100 | [diff] [blame] | 361 | keytrans({string}) String translate internal keycodes to a form |
| 362 | that can be used by |:map| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 363 | len({expr}) Number the length of {expr} |
| 364 | libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg} |
| 365 | libcallnr({lib}, {func}, {arg}) Number idem, but return a Number |
| 366 | line({expr} [, {winid}]) Number line nr of cursor, last line or mark |
| 367 | line2byte({lnum}) Number byte count of line {lnum} |
| 368 | lispindent({lnum}) Number Lisp indent for line {lnum} |
| 369 | list2blob({list}) Blob turn {list} of numbers into a Blob |
| 370 | list2str({list} [, {utf8}]) String turn {list} of numbers into a String |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 371 | list2tuple({list}) Tuple turn {list} of items into a tuple |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 372 | listener_add({callback} [, {buf}]) |
| 373 | Number add a callback to listen to changes |
| 374 | listener_flush([{buf}]) none invoke listener callbacks |
| 375 | listener_remove({id}) none remove a listener callback |
| 376 | localtime() Number current time |
| 377 | log({expr}) Float natural logarithm (base e) of {expr} |
| 378 | log10({expr}) Float logarithm of Float {expr} to base 10 |
| 379 | luaeval({expr} [, {expr}]) any evaluate |Lua| expression |
| 380 | map({expr1}, {expr2}) List/Dict/Blob/String |
| 381 | change each item in {expr1} to {expr2} |
| 382 | maparg({name} [, {mode} [, {abbr} [, {dict}]]]) |
| 383 | String or Dict |
| 384 | rhs of mapping {name} in mode {mode} |
| 385 | mapcheck({name} [, {mode} [, {abbr}]]) |
| 386 | String check for mappings matching {name} |
Ernie Rael | 0966120 | 2022-04-25 14:40:44 +0100 | [diff] [blame] | 387 | maplist([{abbr}]) List list of all mappings, a dict for each |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 388 | mapnew({expr1}, {expr2}) List/Dict/Blob/String |
| 389 | like |map()| but creates a new List or |
| 390 | Dictionary |
| 391 | mapset({mode}, {abbr}, {dict}) none restore mapping from |maparg()| result |
| 392 | match({expr}, {pat} [, {start} [, {count}]]) |
| 393 | Number position where {pat} matches in {expr} |
| 394 | matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]]) |
| 395 | Number highlight {pattern} with {group} |
| 396 | matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) |
| 397 | Number highlight positions with {group} |
| 398 | matcharg({nr}) List arguments of |:match| |
Yegappan Lakshmanan | f93b1c8 | 2024-01-04 22:28:46 +0100 | [diff] [blame] | 399 | matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}) |
| 400 | List all the {pat} matches in buffer {buf} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 401 | matchdelete({id} [, {win}]) Number delete match identified by {id} |
| 402 | matchend({expr}, {pat} [, {start} [, {count}]]) |
| 403 | Number position where {pat} ends in {expr} |
| 404 | matchfuzzy({list}, {str} [, {dict}]) |
| 405 | List fuzzy match {str} in {list} |
| 406 | matchfuzzypos({list}, {str} [, {dict}]) |
| 407 | List fuzzy match {str} in {list} |
| 408 | matchlist({expr}, {pat} [, {start} [, {count}]]) |
| 409 | List match and submatches of {pat} in {expr} |
| 410 | matchstr({expr}, {pat} [, {start} [, {count}]]) |
| 411 | String {count}'th match of {pat} in {expr} |
Yegappan Lakshmanan | f93b1c8 | 2024-01-04 22:28:46 +0100 | [diff] [blame] | 412 | matchstrlist({list}, {pat} [, {dict}) |
| 413 | List all the {pat} matches in {list} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 414 | matchstrpos({expr}, {pat} [, {start} [, {count}]]) |
| 415 | List {count}'th match of {pat} in {expr} |
| 416 | max({expr}) Number maximum value of items in {expr} |
| 417 | menu_info({name} [, {mode}]) Dict get menu item information |
| 418 | min({expr}) Number minimum value of items in {expr} |
Bram Moolenaar | 938ae28 | 2023-02-20 20:44:55 +0000 | [diff] [blame] | 419 | mkdir({name} [, {flags} [, {prot}]]) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 420 | Number create directory {name} |
Doug Kearns | 9cd9e75 | 2024-04-07 17:42:17 +0200 | [diff] [blame] | 421 | mode([{expr}]) String current editing mode |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 422 | mzeval({expr}) any evaluate |MzScheme| expression |
| 423 | nextnonblank({lnum}) Number line nr of non-blank line >= {lnum} |
Christ van Willegen | c078675 | 2025-02-01 15:42:16 +0100 | [diff] [blame] | 424 | ngettext({single}, {plural}, {number}[, {domain}]) |
| 425 | String translate text based on {number} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 426 | nr2char({expr} [, {utf8}]) String single char with ASCII/UTF-8 value {expr} |
| 427 | or({expr}, {expr}) Number bitwise OR |
| 428 | pathshorten({expr} [, {len}]) String shorten directory names in a path |
| 429 | perleval({expr}) any evaluate |Perl| expression |
| 430 | popup_atcursor({what}, {options}) Number create popup window near the cursor |
| 431 | popup_beval({what}, {options}) Number create popup window for 'ballooneval' |
| 432 | popup_clear() none close all popup windows |
| 433 | popup_close({id} [, {result}]) none close popup window {id} |
| 434 | popup_create({what}, {options}) Number create a popup window |
| 435 | popup_dialog({what}, {options}) Number create a popup window used as a dialog |
| 436 | popup_filter_menu({id}, {key}) Number filter for a menu popup window |
| 437 | popup_filter_yesno({id}, {key}) Number filter for a dialog popup window |
Bram Moolenaar | bdc09a1 | 2022-10-07 14:31:45 +0100 | [diff] [blame] | 438 | popup_findecho() Number get window ID of popup for `:echowin` |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 439 | popup_findinfo() Number get window ID of info popup window |
| 440 | popup_findpreview() Number get window ID of preview popup window |
| 441 | popup_getoptions({id}) Dict get options of popup window {id} |
| 442 | popup_getpos({id}) Dict get position of popup window {id} |
| 443 | popup_hide({id}) none hide popup menu {id} |
| 444 | popup_list() List get a list of window IDs of all popups |
| 445 | popup_locate({row}, {col}) Number get window ID of popup at position |
| 446 | popup_menu({what}, {options}) Number create a popup window used as a menu |
| 447 | popup_move({id}, {options}) none set position of popup window {id} |
| 448 | popup_notification({what}, {options}) |
| 449 | Number create a notification popup window |
Christian Brabandt | fbc37f1 | 2024-06-18 20:50:58 +0200 | [diff] [blame] | 450 | popup_setbuf({id}, {buf}) Bool set the buffer for the popup window {id} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 451 | popup_setoptions({id}, {options}) |
| 452 | none set options for popup window {id} |
| 453 | popup_settext({id}, {text}) none set the text of popup window {id} |
| 454 | popup_show({id}) none unhide popup window {id} |
| 455 | pow({x}, {y}) Float {x} to the power of {y} |
| 456 | prevnonblank({lnum}) Number line nr of non-blank line <= {lnum} |
| 457 | printf({fmt}, {expr1}...) String format text |
| 458 | prompt_getprompt({buf}) String get prompt text |
| 459 | prompt_setcallback({buf}, {expr}) none set prompt callback function |
| 460 | prompt_setinterrupt({buf}, {text}) none set prompt interrupt function |
| 461 | prompt_setprompt({buf}, {text}) none set prompt text |
| 462 | prop_add({lnum}, {col}, {props}) none add one text property |
| 463 | prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...]) |
| 464 | none add multiple text properties |
| 465 | prop_clear({lnum} [, {lnum-end} [, {props}]]) |
| 466 | none remove all text properties |
| 467 | prop_find({props} [, {direction}]) |
| 468 | Dict search for a text property |
| 469 | prop_list({lnum} [, {props}]) List text properties in {lnum} |
| 470 | prop_remove({props} [, {lnum} [, {lnum-end}]]) |
| 471 | Number remove a text property |
| 472 | prop_type_add({name}, {props}) none define a new property type |
| 473 | prop_type_change({name}, {props}) |
| 474 | none change an existing property type |
| 475 | prop_type_delete({name} [, {props}]) |
| 476 | none delete a property type |
| 477 | prop_type_get({name} [, {props}]) |
| 478 | Dict get property type values |
| 479 | prop_type_list([{props}]) List get list of property types |
| 480 | pum_getpos() Dict position and size of pum if visible |
| 481 | pumvisible() Number whether popup menu is visible |
zeertzjq | 7c51528 | 2024-11-10 20:26:12 +0100 | [diff] [blame] | 482 | py3eval({expr} [, {locals}]) any evaluate |python3| expression |
| 483 | pyeval({expr} [, {locals}]) any evaluate |Python| expression |
| 484 | pyxeval({expr} [, {locals}]) any evaluate |python_x| expression |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 485 | rand([{expr}]) Number get pseudo-random number |
| 486 | range({expr} [, {max} [, {stride}]]) |
| 487 | List items from {expr} to {max} |
K.Takata | 11df3ae | 2022-10-19 14:02:40 +0100 | [diff] [blame] | 488 | readblob({fname} [, {offset} [, {size}]]) |
| 489 | Blob read a |Blob| from {fname} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 490 | readdir({dir} [, {expr} [, {dict}]]) |
| 491 | List file names in {dir} selected by {expr} |
| 492 | readdirex({dir} [, {expr} [, {dict}]]) |
| 493 | List file info in {dir} selected by {expr} |
| 494 | readfile({fname} [, {type} [, {max}]]) |
| 495 | List get list of lines from file {fname} |
| 496 | reduce({object}, {func} [, {initial}]) |
| 497 | any reduce {object} using {func} |
| 498 | reg_executing() String get the executing register name |
| 499 | reg_recording() String get the recording register name |
| 500 | reltime([{start} [, {end}]]) List get time value |
| 501 | reltimefloat({time}) Float turn the time value into a Float |
| 502 | reltimestr({time}) String turn time value into a String |
| 503 | remote_expr({server}, {string} [, {idvar} [, {timeout}]]) |
| 504 | String send expression |
| 505 | remote_foreground({server}) Number bring Vim server to the foreground |
| 506 | remote_peek({serverid} [, {retvar}]) |
| 507 | Number check for reply string |
| 508 | remote_read({serverid} [, {timeout}]) |
| 509 | String read reply string |
| 510 | remote_send({server}, {string} [, {idvar}]) |
| 511 | String send key sequence |
| 512 | remote_startserver({name}) none become server {name} |
| 513 | remove({list}, {idx} [, {end}]) any/List |
| 514 | remove items {idx}-{end} from {list} |
| 515 | remove({blob}, {idx} [, {end}]) Number/Blob |
| 516 | remove bytes {idx}-{end} from {blob} |
| 517 | remove({dict}, {key}) any remove entry {key} from {dict} |
| 518 | rename({from}, {to}) Number rename (move) file from {from} to {to} |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 519 | repeat({expr}, {count}) List/Tuple/Blob/String |
Bakudankun | 375141e | 2022-09-09 18:46:47 +0100 | [diff] [blame] | 520 | repeat {expr} {count} times |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 521 | resolve({filename}) String get filename a shortcut points to |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 522 | reverse({obj}) List/Tuple/Blob/String |
Yegappan Lakshmanan | 03ff1c2 | 2023-05-06 14:08:21 +0100 | [diff] [blame] | 523 | reverse {obj} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 524 | round({expr}) Float round off {expr} |
| 525 | rubyeval({expr}) any evaluate |Ruby| expression |
| 526 | screenattr({row}, {col}) Number attribute at screen position |
| 527 | screenchar({row}, {col}) Number character at screen position |
| 528 | screenchars({row}, {col}) List List of characters at screen position |
| 529 | screencol() Number current cursor column |
| 530 | screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character |
| 531 | screenrow() Number current cursor row |
| 532 | screenstring({row}, {col}) String characters at screen position |
| 533 | search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) |
| 534 | Number search for {pattern} |
| 535 | searchcount([{options}]) Dict get or update search stats |
| 536 | searchdecl({name} [, {global} [, {thisblock}]]) |
| 537 | Number search for variable declaration |
| 538 | searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]]) |
| 539 | Number search for other end of start/end pair |
| 540 | searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]]) |
| 541 | List search for other end of start/end pair |
| 542 | searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) |
| 543 | List search for {pattern} |
| 544 | server2client({clientid}, {string}) |
| 545 | Number send reply string |
| 546 | serverlist() String get a list of available servers |
errael | f0837ba | 2024-06-24 12:27:01 -0700 | [diff] [blame] | 547 | setbufline({buf}, {lnum}, {text}) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 548 | Number set line {lnum} to {text} in buffer |
errael | f0837ba | 2024-06-24 12:27:01 -0700 | [diff] [blame] | 549 | {buf} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 550 | setbufvar({buf}, {varname}, {val}) |
| 551 | none set {varname} in buffer {buf} to {val} |
| 552 | setcellwidths({list}) none set character cell width overrides |
| 553 | setcharpos({expr}, {list}) Number set the {expr} position to {list} |
| 554 | setcharsearch({dict}) Dict set character search from {dict} |
Shougo Matsushita | 07ea5f1 | 2022-08-27 12:22:25 +0100 | [diff] [blame] | 555 | setcmdline({str} [, {pos}]) Number set command-line |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 556 | setcmdpos({pos}) Number set cursor position in command-line |
| 557 | setcursorcharpos({list}) Number move cursor to position in {list} |
| 558 | setenv({name}, {val}) none set environment variable |
| 559 | setfperm({fname}, {mode}) Number set {fname} file permissions to {mode} |
| 560 | setline({lnum}, {line}) Number set line {lnum} to {line} |
| 561 | setloclist({nr}, {list} [, {action}]) |
| 562 | Number modify location list using {list} |
| 563 | setloclist({nr}, {list}, {action}, {what}) |
| 564 | Number modify specific location list props |
| 565 | setmatches({list} [, {win}]) Number restore a list of matches |
| 566 | setpos({expr}, {list}) Number set the {expr} position to {list} |
| 567 | setqflist({list} [, {action}]) Number modify quickfix list using {list} |
| 568 | setqflist({list}, {action}, {what}) |
| 569 | Number modify specific quickfix list props |
| 570 | setreg({n}, {v} [, {opt}]) Number set register to value and type |
| 571 | settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val} |
| 572 | settabwinvar({tabnr}, {winnr}, {varname}, {val}) |
| 573 | none set {varname} in window {winnr} in tab |
| 574 | page {tabnr} to {val} |
| 575 | settagstack({nr}, {dict} [, {action}]) |
| 576 | Number modify tag stack using {dict} |
| 577 | setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val} |
| 578 | sha256({string}) String SHA256 checksum of {string} |
| 579 | shellescape({string} [, {special}]) |
| 580 | String escape {string} for use as shell |
| 581 | command argument |
| 582 | shiftwidth([{col}]) Number effective value of 'shiftwidth' |
| 583 | sign_define({name} [, {dict}]) Number define or update a sign |
| 584 | sign_define({list}) List define or update a list of signs |
| 585 | sign_getdefined([{name}]) List get a list of defined signs |
| 586 | sign_getplaced([{buf} [, {dict}]]) |
| 587 | List get a list of placed signs |
| 588 | sign_jump({id}, {group}, {buf}) |
| 589 | Number jump to a sign |
| 590 | sign_place({id}, {group}, {name}, {buf} [, {dict}]) |
| 591 | Number place a sign |
| 592 | sign_placelist({list}) List place a list of signs |
| 593 | sign_undefine([{name}]) Number undefine a sign |
| 594 | sign_undefine({list}) List undefine a list of signs |
| 595 | sign_unplace({group} [, {dict}]) |
| 596 | Number unplace a sign |
| 597 | sign_unplacelist({list}) List unplace a list of signs |
| 598 | simplify({filename}) String simplify filename as much as possible |
| 599 | sin({expr}) Float sine of {expr} |
| 600 | sinh({expr}) Float hyperbolic sine of {expr} |
| 601 | slice({expr}, {start} [, {end}]) String, List or Blob |
| 602 | slice of a String, List or Blob |
Bram Moolenaar | 2007dd4 | 2022-02-23 13:17:47 +0000 | [diff] [blame] | 603 | sort({list} [, {how} [, {dict}]]) |
| 604 | List sort {list}, compare with {how} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 605 | sound_clear() none stop playing all sounds |
| 606 | sound_playevent({name} [, {callback}]) |
| 607 | Number play an event sound |
| 608 | sound_playfile({path} [, {callback}]) |
| 609 | Number play sound file {path} |
| 610 | sound_stop({id}) none stop playing sound {id} |
| 611 | soundfold({word}) String sound-fold {word} |
| 612 | spellbadword() String badly spelled word at cursor |
| 613 | spellsuggest({word} [, {max} [, {capital}]]) |
| 614 | List spelling suggestions |
| 615 | split({expr} [, {pat} [, {keepempty}]]) |
| 616 | List make |List| from {pat} separated {expr} |
| 617 | sqrt({expr}) Float square root of {expr} |
| 618 | srand([{expr}]) List get seed for |rand()| |
| 619 | state([{what}]) String current state of Vim |
Hirohito Higashi | 195fcc9 | 2025-02-01 10:26:58 +0100 | [diff] [blame] | 620 | str2blob({list} [, {options}]) Blob convert list of strings into a Blob |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 621 | str2float({expr} [, {quoted}]) Float convert String to Float |
| 622 | str2list({expr} [, {utf8}]) List convert each character of {expr} to |
| 623 | ASCII/UTF-8 value |
| 624 | str2nr({expr} [, {base} [, {quoted}]]) |
| 625 | Number convert String to Number |
| 626 | strcharlen({expr}) Number character length of the String {expr} |
| 627 | strcharpart({str}, {start} [, {len} [, {skipcc}]]) |
| 628 | String {len} characters of {str} at |
| 629 | character {start} |
| 630 | strchars({expr} [, {skipcc}]) Number character count of the String {expr} |
| 631 | strdisplaywidth({expr} [, {col}]) Number display length of the String {expr} |
| 632 | strftime({format} [, {time}]) String format time with a specified format |
| 633 | strgetchar({str}, {index}) Number get char {index} from {str} |
| 634 | stridx({haystack}, {needle} [, {start}]) |
| 635 | Number index of {needle} in {haystack} |
| 636 | string({expr}) String String representation of {expr} value |
| 637 | strlen({expr}) Number length of the String {expr} |
| 638 | strpart({str}, {start} [, {len} [, {chars}]]) |
| 639 | String {len} bytes/chars of {str} at |
| 640 | byte {start} |
| 641 | strptime({format}, {timestring}) |
| 642 | Number Convert {timestring} to unix timestamp |
| 643 | strridx({haystack}, {needle} [, {start}]) |
| 644 | Number last index of {needle} in {haystack} |
| 645 | strtrans({expr}) String translate string to make it printable |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 646 | strutf16len({string} [, {countcc}]) |
| 647 | Number number of UTF-16 code units in {string} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 648 | strwidth({expr}) Number display cell length of the String {expr} |
| 649 | submatch({nr} [, {list}]) String or List |
| 650 | specific match in ":s" or substitute() |
| 651 | substitute({expr}, {pat}, {sub}, {flags}) |
| 652 | String all {pat} in {expr} replaced with {sub} |
Bram Moolenaar | c216a7a | 2022-12-05 13:50:55 +0000 | [diff] [blame] | 653 | swapfilelist() List swap files found in 'directory' |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 654 | swapinfo({fname}) Dict information about swap file {fname} |
| 655 | swapname({buf}) String swap file of buffer {buf} |
| 656 | synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col} |
| 657 | synIDattr({synID}, {what} [, {mode}]) |
| 658 | String attribute {what} of syntax ID {synID} |
| 659 | synIDtrans({synID}) Number translated syntax ID of {synID} |
| 660 | synconcealed({lnum}, {col}) List info about concealing |
| 661 | synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col} |
| 662 | system({expr} [, {input}]) String output of shell command/filter {expr} |
| 663 | systemlist({expr} [, {input}]) List output of shell command/filter {expr} |
| 664 | tabpagebuflist([{arg}]) List list of buffer numbers in tab page |
| 665 | tabpagenr([{arg}]) Number number of current or last tab page |
| 666 | tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page |
| 667 | tagfiles() List tags files used |
| 668 | taglist({expr} [, {filename}]) List list of tags matching {expr} |
| 669 | tan({expr}) Float tangent of {expr} |
| 670 | tanh({expr}) Float hyperbolic tangent of {expr} |
| 671 | tempname() String name for a temporary file |
| 672 | term_dumpdiff({filename}, {filename} [, {options}]) |
| 673 | Number display difference between two dumps |
| 674 | term_dumpload({filename} [, {options}]) |
| 675 | Number displaying a screen dump |
| 676 | term_dumpwrite({buf}, {filename} [, {options}]) |
| 677 | none dump terminal window contents |
| 678 | term_getaltscreen({buf}) Number get the alternate screen flag |
| 679 | term_getansicolors({buf}) List get ANSI palette in GUI color mode |
| 680 | term_getattr({attr}, {what}) Number get the value of attribute {what} |
| 681 | term_getcursor({buf}) List get the cursor position of a terminal |
| 682 | term_getjob({buf}) Job get the job associated with a terminal |
| 683 | term_getline({buf}, {row}) String get a line of text from a terminal |
| 684 | term_getscrolled({buf}) Number get the scroll count of a terminal |
| 685 | term_getsize({buf}) List get the size of a terminal |
| 686 | term_getstatus({buf}) String get the status of a terminal |
| 687 | term_gettitle({buf}) String get the title of a terminal |
| 688 | term_gettty({buf}, [{input}]) String get the tty name of a terminal |
| 689 | term_list() List get the list of terminal buffers |
| 690 | term_scrape({buf}, {row}) List get row of a terminal screen |
| 691 | term_sendkeys({buf}, {keys}) none send keystrokes to a terminal |
| 692 | term_setansicolors({buf}, {colors}) |
| 693 | none set ANSI palette in GUI color mode |
| 694 | term_setapi({buf}, {expr}) none set |terminal-api| function name prefix |
| 695 | term_setkill({buf}, {how}) none set signal to stop job in terminal |
| 696 | term_setrestore({buf}, {command}) none set command to restore terminal |
| 697 | term_setsize({buf}, {rows}, {cols}) |
| 698 | none set the size of a terminal |
| 699 | term_start({cmd} [, {options}]) Number open a terminal window and run a job |
| 700 | term_wait({buf} [, {time}]) Number wait for screen to be updated |
| 701 | terminalprops() Dict properties of the terminal |
| 702 | test_alloc_fail({id}, {countdown}, {repeat}) |
| 703 | none make memory allocation fail |
| 704 | test_autochdir() none enable 'autochdir' during startup |
| 705 | test_feedinput({string}) none add key sequence to input buffer |
| 706 | test_garbagecollect_now() none free memory right now for testing |
| 707 | test_garbagecollect_soon() none free memory soon for testing |
| 708 | test_getvalue({string}) any get value of an internal variable |
Yegappan Lakshmanan | 06011e1 | 2022-01-30 12:37:29 +0000 | [diff] [blame] | 709 | test_gui_event({event}, {args}) bool generate a GUI event for testing |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 710 | test_ignore_error({expr}) none ignore a specific error |
Christopher Plewright | 20b795e | 2022-12-20 20:01:58 +0000 | [diff] [blame] | 711 | test_mswin_event({event}, {args}) |
| 712 | bool generate MS-Windows event for testing |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 713 | test_null_blob() Blob null value for testing |
| 714 | test_null_channel() Channel null value for testing |
| 715 | test_null_dict() Dict null value for testing |
| 716 | test_null_function() Funcref null value for testing |
| 717 | test_null_job() Job null value for testing |
| 718 | test_null_list() List null value for testing |
| 719 | test_null_partial() Funcref null value for testing |
| 720 | test_null_string() String null value for testing |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 721 | test_null_tuple() Tuple null value for testing |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 722 | test_option_not_set({name}) none reset flag indicating option was set |
| 723 | test_override({expr}, {val}) none test with Vim internal overrides |
| 724 | test_refcount({expr}) Number get the reference count of {expr} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 725 | test_setmouse({row}, {col}) none set the mouse position for testing |
| 726 | test_settime({expr}) none set current time for testing |
Doug Kearns | 9cd9e75 | 2024-04-07 17:42:17 +0200 | [diff] [blame] | 727 | test_srand_seed([{seed}]) none set seed for testing srand() |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 728 | test_unknown() any unknown value for testing |
| 729 | test_void() any void value for testing |
| 730 | timer_info([{id}]) List information about timers |
| 731 | timer_pause({id}, {pause}) none pause or unpause a timer |
| 732 | timer_start({time}, {callback} [, {options}]) |
| 733 | Number create a timer |
| 734 | timer_stop({timer}) none stop a timer |
| 735 | timer_stopall() none stop all timers |
| 736 | tolower({expr}) String the String {expr} switched to lowercase |
| 737 | toupper({expr}) String the String {expr} switched to uppercase |
| 738 | tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr} |
| 739 | to chars in {tostr} |
| 740 | trim({text} [, {mask} [, {dir}]]) |
| 741 | String trim characters in {mask} from {text} |
| 742 | trunc({expr}) Float truncate Float {expr} |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 743 | tuple2list({tuple}) List turn {tuple} of items into a list |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 744 | type({expr}) Number type of value {expr} |
| 745 | typename({expr}) String representation of the type of {expr} |
| 746 | undofile({name}) String undo file name for {name} |
Devin J. Pohly | 5fee111 | 2023-04-23 20:26:59 -0500 | [diff] [blame] | 747 | undotree([{buf}]) List undo file tree for buffer {buf} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 748 | uniq({list} [, {func} [, {dict}]]) |
| 749 | List remove adjacent duplicates from a list |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 750 | utf16idx({string}, {idx} [, {countcc} [, {charidx}]]) |
| 751 | Number UTF-16 index of byte {idx} in {string} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 752 | values({dict}) List values in {dict} |
zeertzjq | 825cf81 | 2023-08-17 22:55:25 +0200 | [diff] [blame] | 753 | virtcol({expr} [, {list} [, {winid}]) |
| 754 | Number or List |
LemonBoy | 0f7a3e1 | 2022-05-26 12:10:37 +0100 | [diff] [blame] | 755 | screen column of cursor or mark |
Bram Moolenaar | 5a6ec10 | 2022-05-27 21:58:00 +0100 | [diff] [blame] | 756 | virtcol2col({winid}, {lnum}, {col}) |
| 757 | Number byte index of a character on screen |
Doug Kearns | 9cd9e75 | 2024-04-07 17:42:17 +0200 | [diff] [blame] | 758 | visualmode([{expr}]) String last visual mode used |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 759 | wildmenumode() Number whether 'wildmenu' mode is active |
| 760 | win_execute({id}, {command} [, {silent}]) |
| 761 | String execute {command} in window {id} |
| 762 | win_findbuf({bufnr}) List find windows containing {bufnr} |
| 763 | win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab} |
| 764 | win_gettype([{nr}]) String type of window {nr} |
| 765 | win_gotoid({expr}) Number go to window with ID {expr} |
| 766 | win_id2tabwin({expr}) List get tab and window nr from window ID |
| 767 | win_id2win({expr}) Number get window nr from window ID |
Daniel Steinberg | ee63031 | 2022-01-10 13:36:34 +0000 | [diff] [blame] | 768 | win_move_separator({nr}) Number move window vertical separator |
| 769 | win_move_statusline({nr}) Number move window status line |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 770 | win_screenpos({nr}) List get screen position of window {nr} |
| 771 | win_splitmove({nr}, {target} [, {options}]) |
| 772 | Number move window {nr} to split of {target} |
| 773 | winbufnr({nr}) Number buffer number of window {nr} |
| 774 | wincol() Number window column of the cursor |
| 775 | windowsversion() String MS-Windows OS version |
| 776 | winheight({nr}) Number height of window {nr} |
| 777 | winlayout([{tabnr}]) List layout of windows in tab {tabnr} |
| 778 | winline() Number window line of the cursor |
| 779 | winnr([{expr}]) Number number of current window |
| 780 | winrestcmd() String returns command to restore window sizes |
| 781 | winrestview({dict}) none restore view of current window |
| 782 | winsaveview() Dict save view of current window |
| 783 | winwidth({nr}) Number width of window {nr} |
| 784 | wordcount() Dict get byte/char/word statistics |
| 785 | writefile({object}, {fname} [, {flags}]) |
| 786 | Number write |Blob| or |List| of lines to file |
| 787 | xor({expr}, {expr}) Number bitwise XOR |
| 788 | |
| 789 | ============================================================================== |
| 790 | 2. Details *builtin-function-details* |
| 791 | |
| 792 | Not all functions are here, some have been moved to a help file covering the |
| 793 | specific functionality. |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 794 | Return type specifies the type for |Vim9-script|, see |vim9-types| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 795 | |
| 796 | abs({expr}) *abs()* |
| 797 | Return the absolute value of {expr}. When {expr} evaluates to |
| 798 | a |Float| abs() returns a |Float|. When {expr} can be |
| 799 | converted to a |Number| abs() returns a |Number|. Otherwise |
| 800 | abs() gives an error message and returns -1. |
| 801 | Examples: > |
| 802 | echo abs(1.456) |
| 803 | < 1.456 > |
| 804 | echo abs(-5.456) |
| 805 | < 5.456 > |
| 806 | echo abs(-4) |
| 807 | < 4 |
| 808 | |
| 809 | Can also be used as a |method|: > |
| 810 | Compute()->abs() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 811 | < |
| 812 | Return type: |Number| or |Float| depending on {expr} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 813 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 814 | |
| 815 | acos({expr}) *acos()* |
| 816 | Return the arc cosine of {expr} measured in radians, as a |
| 817 | |Float| in the range of [0, pi]. |
| 818 | {expr} must evaluate to a |Float| or a |Number| in the range |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 819 | [-1, 1]. Otherwise acos() returns "nan". |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 820 | Examples: > |
| 821 | :echo acos(0) |
| 822 | < 1.570796 > |
| 823 | :echo acos(-0.5) |
| 824 | < 2.094395 |
| 825 | |
| 826 | Can also be used as a |method|: > |
| 827 | Compute()->acos() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 828 | < |
| 829 | Return type: |Float| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 830 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 831 | |
| 832 | add({object}, {expr}) *add()* |
| 833 | Append the item {expr} to |List| or |Blob| {object}. Returns |
| 834 | the resulting |List| or |Blob|. Examples: > |
| 835 | :let alist = add([1, 2, 3], item) |
| 836 | :call add(mylist, "woodstock") |
| 837 | < Note that when {expr} is a |List| it is appended as a single |
| 838 | item. Use |extend()| to concatenate |Lists|. |
| 839 | When {object} is a |Blob| then {expr} must be a number. |
| 840 | Use |insert()| to add an item at another position. |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 841 | Returns 1 if {object} is not a |List| or a |Blob|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 842 | |
| 843 | Can also be used as a |method|: > |
| 844 | mylist->add(val1)->add(val2) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 845 | < |
| 846 | Return type: list<{type}> (depending on the given |List|) or |
| 847 | |Blob| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 848 | |
| 849 | |
| 850 | and({expr}, {expr}) *and()* |
| 851 | Bitwise AND on the two arguments. The arguments are converted |
| 852 | to a number. A List, Dict or Float argument causes an error. |
LemonBoy | 0f7a3e1 | 2022-05-26 12:10:37 +0100 | [diff] [blame] | 853 | Also see `or()` and `xor()`. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 854 | Example: > |
| 855 | :let flag = and(bits, 0x80) |
| 856 | < Can also be used as a |method|: > |
| 857 | :let flag = bits->and(0x80) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 858 | < |
| 859 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 860 | |
| 861 | |
| 862 | append({lnum}, {text}) *append()* |
| 863 | When {text} is a |List|: Append each item of the |List| as a |
| 864 | text line below line {lnum} in the current buffer. |
| 865 | Otherwise append {text} as one text line below line {lnum} in |
| 866 | the current buffer. |
| 867 | Any type of item is accepted and converted to a String. |
| 868 | {lnum} can be zero to insert a line before the first one. |
| 869 | {lnum} is used like with |getline()|. |
| 870 | Returns 1 for failure ({lnum} out of range or out of memory), |
Bram Moolenaar | cd9c8d4 | 2022-11-05 23:46:43 +0000 | [diff] [blame] | 871 | 0 for success. When {text} is an empty list zero is returned, |
| 872 | no matter the value of {lnum}. |
| 873 | In |Vim9| script an invalid argument or negative number |
| 874 | results in an error. Example: > |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 875 | :let failed = append(line('$'), "# THE END") |
| 876 | :let failed = append(0, ["Chapter 1", "the beginning"]) |
| 877 | |
| 878 | < Can also be used as a |method| after a List, the base is |
| 879 | passed as the second argument: > |
| 880 | mylist->append(lnum) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 881 | < |
| 882 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 883 | |
| 884 | |
| 885 | appendbufline({buf}, {lnum}, {text}) *appendbufline()* |
| 886 | Like |append()| but append the text in buffer {buf}. |
| 887 | |
| 888 | This function works only for loaded buffers. First call |
| 889 | |bufload()| if needed. |
| 890 | |
| 891 | For the use of {buf}, see |bufname()|. |
| 892 | |
Bram Moolenaar | 8b6256f | 2021-12-28 11:24:49 +0000 | [diff] [blame] | 893 | {lnum} is the line number to append below. Note that using |
| 894 | |line()| would use the current buffer, not the one appending |
| 895 | to. Use "$" to append at the end of the buffer. Other string |
| 896 | values are not supported. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 897 | |
| 898 | On success 0 is returned, on failure 1 is returned. |
| 899 | In |Vim9| script an error is given for an invalid {lnum}. |
| 900 | |
| 901 | If {buf} is not a valid buffer or {lnum} is not valid, an |
| 902 | error message is given. Example: > |
| 903 | :let failed = appendbufline(13, 0, "# THE START") |
Bram Moolenaar | cd9c8d4 | 2022-11-05 23:46:43 +0000 | [diff] [blame] | 904 | < However, when {text} is an empty list then no error is given |
| 905 | for an invalid {lnum}, since {lnum} isn't actually used. |
| 906 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 907 | Can also be used as a |method| after a List, the base is |
| 908 | passed as the second argument: > |
| 909 | mylist->appendbufline(buf, lnum) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 910 | < |
| 911 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 912 | |
| 913 | |
| 914 | argc([{winid}]) *argc()* |
| 915 | The result is the number of files in the argument list. See |
| 916 | |arglist|. |
| 917 | If {winid} is not supplied, the argument list of the current |
| 918 | window is used. |
| 919 | If {winid} is -1, the global argument list is used. |
| 920 | Otherwise {winid} specifies the window of which the argument |
| 921 | list is used: either the window number or the window ID. |
| 922 | Returns -1 if the {winid} argument is invalid. |
| 923 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 924 | Return type: |Number| |
| 925 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 926 | *argidx()* |
| 927 | argidx() The result is the current index in the argument list. 0 is |
| 928 | the first file. argc() - 1 is the last one. See |arglist|. |
| 929 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 930 | Return type: |Number| |
| 931 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 932 | *arglistid()* |
| 933 | arglistid([{winnr} [, {tabnr}]]) |
| 934 | Return the argument list ID. This is a number which |
| 935 | identifies the argument list being used. Zero is used for the |
| 936 | global argument list. See |arglist|. |
| 937 | Returns -1 if the arguments are invalid. |
| 938 | |
| 939 | Without arguments use the current window. |
| 940 | With {winnr} only use this window in the current tab page. |
| 941 | With {winnr} and {tabnr} use the window in the specified tab |
| 942 | page. |
| 943 | {winnr} can be the window number or the |window-ID|. |
| 944 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 945 | Return type: |Number| |
| 946 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 947 | *argv()* |
| 948 | argv([{nr} [, {winid}]]) |
| 949 | The result is the {nr}th file in the argument list. See |
| 950 | |arglist|. "argv(0)" is the first one. Example: > |
| 951 | :let i = 0 |
| 952 | :while i < argc() |
| 953 | : let f = escape(fnameescape(argv(i)), '.') |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 954 | : exe 'amenu Arg.' .. f .. ' :e ' .. f .. '<CR>' |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 955 | : let i = i + 1 |
| 956 | :endwhile |
| 957 | < Without the {nr} argument, or when {nr} is -1, a |List| with |
| 958 | the whole |arglist| is returned. |
| 959 | |
| 960 | The {winid} argument specifies the window ID, see |argc()|. |
| 961 | For the Vim command line arguments see |v:argv|. |
| 962 | |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 963 | Returns an empty string if {nr}th argument is not present in |
| 964 | the argument list. Returns an empty List if the {winid} |
| 965 | argument is invalid. |
| 966 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 967 | Return type: |String| |
| 968 | |
| 969 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 970 | asin({expr}) *asin()* |
| 971 | Return the arc sine of {expr} measured in radians, as a |Float| |
| 972 | in the range of [-pi/2, pi/2]. |
| 973 | {expr} must evaluate to a |Float| or a |Number| in the range |
| 974 | [-1, 1]. |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 975 | Returns "nan" if {expr} is outside the range [-1, 1]. Returns |
| 976 | 0.0 if {expr} is not a |Float| or a |Number|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 977 | Examples: > |
| 978 | :echo asin(0.8) |
| 979 | < 0.927295 > |
| 980 | :echo asin(-0.5) |
| 981 | < -0.523599 |
| 982 | |
| 983 | Can also be used as a |method|: > |
| 984 | Compute()->asin() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 985 | < |
| 986 | Return type: |Float| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 987 | |
| 988 | assert_ functions are documented here: |assert-functions-details| |
| 989 | |
| 990 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 991 | atan({expr}) *atan()* |
| 992 | Return the principal value of the arc tangent of {expr}, in |
| 993 | the range [-pi/2, +pi/2] radians, as a |Float|. |
| 994 | {expr} must evaluate to a |Float| or a |Number|. |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 995 | Returns 0.0 if {expr} is not a |Float| or a |Number|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 996 | Examples: > |
| 997 | :echo atan(100) |
| 998 | < 1.560797 > |
| 999 | :echo atan(-4.01) |
| 1000 | < -1.326405 |
| 1001 | |
| 1002 | Can also be used as a |method|: > |
| 1003 | Compute()->atan() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1004 | < |
| 1005 | Return type: |Float| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1006 | |
| 1007 | |
| 1008 | atan2({expr1}, {expr2}) *atan2()* |
| 1009 | Return the arc tangent of {expr1} / {expr2}, measured in |
| 1010 | radians, as a |Float| in the range [-pi, pi]. |
| 1011 | {expr1} and {expr2} must evaluate to a |Float| or a |Number|. |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 1012 | Returns 0.0 if {expr1} or {expr2} is not a |Float| or a |
| 1013 | |Number|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1014 | Examples: > |
| 1015 | :echo atan2(-1, 1) |
| 1016 | < -0.785398 > |
| 1017 | :echo atan2(1, -1) |
| 1018 | < 2.356194 |
| 1019 | |
| 1020 | Can also be used as a |method|: > |
| 1021 | Compute()->atan2(1) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1022 | < |
| 1023 | Return type: |Float| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1024 | |
Yegappan Lakshmanan | 1755a91 | 2022-05-19 10:31:47 +0100 | [diff] [blame] | 1025 | |
| 1026 | autocmd_add({acmds}) *autocmd_add()* |
| 1027 | Adds a List of autocmds and autocmd groups. |
| 1028 | |
| 1029 | The {acmds} argument is a List where each item is a Dict with |
| 1030 | the following optional items: |
| 1031 | bufnr buffer number to add a buffer-local autocmd. |
| 1032 | If this item is specified, then the "pattern" |
| 1033 | item is ignored. |
| 1034 | cmd Ex command to execute for this autocmd event |
| 1035 | event autocmd event name. Refer to |autocmd-events|. |
Yegappan Lakshmanan | e0ff3a7 | 2022-05-27 18:05:33 +0100 | [diff] [blame] | 1036 | This can be either a String with a single |
| 1037 | event name or a List of event names. |
Yegappan Lakshmanan | 1755a91 | 2022-05-19 10:31:47 +0100 | [diff] [blame] | 1038 | group autocmd group name. Refer to |autocmd-groups|. |
| 1039 | If this group doesn't exist then it is |
| 1040 | created. If not specified or empty, then the |
| 1041 | default group is used. |
Yegappan Lakshmanan | 971f682 | 2022-05-24 11:40:11 +0100 | [diff] [blame] | 1042 | nested boolean flag, set to v:true to add a nested |
| 1043 | autocmd. Refer to |autocmd-nested|. |
LemonBoy | 0f7a3e1 | 2022-05-26 12:10:37 +0100 | [diff] [blame] | 1044 | once boolean flag, set to v:true to add an autocmd |
Yegappan Lakshmanan | 971f682 | 2022-05-24 11:40:11 +0100 | [diff] [blame] | 1045 | which executes only once. Refer to |
| 1046 | |autocmd-once|. |
Yegappan Lakshmanan | 1755a91 | 2022-05-19 10:31:47 +0100 | [diff] [blame] | 1047 | pattern autocmd pattern string. Refer to |
| 1048 | |autocmd-patterns|. If "bufnr" item is |
Yegappan Lakshmanan | e0ff3a7 | 2022-05-27 18:05:33 +0100 | [diff] [blame] | 1049 | present, then this item is ignored. This can |
| 1050 | be a String with a single pattern or a List of |
| 1051 | patterns. |
Yegappan Lakshmanan | 971f682 | 2022-05-24 11:40:11 +0100 | [diff] [blame] | 1052 | replace boolean flag, set to v:true to remove all the |
| 1053 | commands associated with the specified autocmd |
| 1054 | event and group and add the {cmd}. This is |
| 1055 | useful to avoid adding the same command |
LemonBoy | 0f7a3e1 | 2022-05-26 12:10:37 +0100 | [diff] [blame] | 1056 | multiple times for an autocmd event in a group. |
Yegappan Lakshmanan | 1755a91 | 2022-05-19 10:31:47 +0100 | [diff] [blame] | 1057 | |
| 1058 | Returns v:true on success and v:false on failure. |
| 1059 | Examples: > |
| 1060 | " Create a buffer-local autocmd for buffer 5 |
| 1061 | let acmd = {} |
| 1062 | let acmd.group = 'MyGroup' |
| 1063 | let acmd.event = 'BufEnter' |
| 1064 | let acmd.bufnr = 5 |
| 1065 | let acmd.cmd = 'call BufEnterFunc()' |
| 1066 | call autocmd_add([acmd]) |
Bram Moolenaar | cd9c8d4 | 2022-11-05 23:46:43 +0000 | [diff] [blame] | 1067 | < |
Yegappan Lakshmanan | 1755a91 | 2022-05-19 10:31:47 +0100 | [diff] [blame] | 1068 | Can also be used as a |method|: > |
| 1069 | GetAutocmdList()->autocmd_add() |
| 1070 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1071 | Return type: |vim9-boolean| |
| 1072 | |
| 1073 | |
Yegappan Lakshmanan | 1755a91 | 2022-05-19 10:31:47 +0100 | [diff] [blame] | 1074 | autocmd_delete({acmds}) *autocmd_delete()* |
| 1075 | Deletes a List of autocmds and autocmd groups. |
| 1076 | |
| 1077 | The {acmds} argument is a List where each item is a Dict with |
| 1078 | the following optional items: |
| 1079 | bufnr buffer number to delete a buffer-local autocmd. |
| 1080 | If this item is specified, then the "pattern" |
| 1081 | item is ignored. |
| 1082 | cmd Ex command for this autocmd event |
| 1083 | event autocmd event name. Refer to |autocmd-events|. |
| 1084 | If '*' then all the autocmd events in this |
| 1085 | group are deleted. |
| 1086 | group autocmd group name. Refer to |autocmd-groups|. |
| 1087 | If not specified or empty, then the default |
| 1088 | group is used. |
| 1089 | nested set to v:true for a nested autocmd. |
| 1090 | Refer to |autocmd-nested|. |
| 1091 | once set to v:true for an autocmd which executes |
| 1092 | only once. Refer to |autocmd-once|. |
| 1093 | pattern autocmd pattern string. Refer to |
| 1094 | |autocmd-patterns|. If "bufnr" item is |
| 1095 | present, then this item is ignored. |
| 1096 | |
| 1097 | If only {group} is specified in a {acmds} entry and {event}, |
| 1098 | {pattern} and {cmd} are not specified, then that autocmd group |
| 1099 | is deleted. |
| 1100 | |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 1101 | Returns |v:true| on success and |v:false| on failure. |
Yegappan Lakshmanan | 1755a91 | 2022-05-19 10:31:47 +0100 | [diff] [blame] | 1102 | Examples: > |
| 1103 | " :autocmd! BufLeave *.vim |
| 1104 | let acmd = #{event: 'BufLeave', pattern: '*.vim'} |
| 1105 | call autocmd_delete([acmd]}) |
| 1106 | " :autocmd! MyGroup1 BufLeave |
| 1107 | let acmd = #{group: 'MyGroup1', event: 'BufLeave'} |
| 1108 | call autocmd_delete([acmd]) |
| 1109 | " :autocmd! MyGroup2 BufEnter *.c |
| 1110 | let acmd = #{group: 'MyGroup2', event: 'BufEnter', |
| 1111 | \ pattern: '*.c'} |
| 1112 | " :autocmd! MyGroup2 * *.c |
| 1113 | let acmd = #{group: 'MyGroup2', event: '*', |
| 1114 | \ pattern: '*.c'} |
| 1115 | call autocmd_delete([acmd]) |
| 1116 | " :autocmd! MyGroup3 |
| 1117 | let acmd = #{group: 'MyGroup3'} |
| 1118 | call autocmd_delete([acmd]) |
| 1119 | < |
| 1120 | Can also be used as a |method|: > |
| 1121 | GetAutocmdList()->autocmd_delete() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1122 | < |
| 1123 | Return type: |vim9-boolean| |
| 1124 | |
Yegappan Lakshmanan | 1755a91 | 2022-05-19 10:31:47 +0100 | [diff] [blame] | 1125 | |
| 1126 | autocmd_get([{opts}]) *autocmd_get()* |
| 1127 | Returns a |List| of autocmds. If {opts} is not supplied, then |
| 1128 | returns the autocmds for all the events in all the groups. |
| 1129 | |
| 1130 | The optional {opts} Dict argument supports the following |
| 1131 | items: |
| 1132 | group Autocmd group name. If specified, returns only |
| 1133 | the autocmds defined in this group. If the |
| 1134 | specified group doesn't exist, results in an |
| 1135 | error message. If set to an empty string, |
| 1136 | then the default autocmd group is used. |
| 1137 | event Autocmd event name. If specified, returns only |
| 1138 | the autocmds defined for this event. If set |
| 1139 | to "*", then returns autocmds for all the |
| 1140 | events. If the specified event doesn't exist, |
| 1141 | results in an error message. |
| 1142 | pattern Autocmd pattern. If specified, returns only |
| 1143 | the autocmds defined for this pattern. |
| 1144 | A combination of the above three times can be supplied in |
| 1145 | {opts}. |
| 1146 | |
| 1147 | Each Dict in the returned List contains the following items: |
| 1148 | bufnr For buffer-local autocmds, buffer number where |
| 1149 | the autocmd is defined. |
| 1150 | cmd Command executed for this autocmd. |
| 1151 | event Autocmd event name. |
| 1152 | group Autocmd group name. |
Yegappan Lakshmanan | 971f682 | 2022-05-24 11:40:11 +0100 | [diff] [blame] | 1153 | nested Boolean flag, set to v:true for a nested |
| 1154 | autocmd. See |autocmd-nested|. |
| 1155 | once Boolean flag, set to v:true, if the autocmd |
| 1156 | will be executed only once. See |autocmd-once|. |
Yegappan Lakshmanan | 1755a91 | 2022-05-19 10:31:47 +0100 | [diff] [blame] | 1157 | pattern Autocmd pattern. For a buffer-local |
| 1158 | autocmd, this will be of the form "<buffer=n>". |
| 1159 | If there are multiple commands for an autocmd event in a |
| 1160 | group, then separate items are returned for each command. |
| 1161 | |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 1162 | Returns an empty List if an autocmd with the specified group |
| 1163 | or event or pattern is not found. |
| 1164 | |
Yegappan Lakshmanan | 1755a91 | 2022-05-19 10:31:47 +0100 | [diff] [blame] | 1165 | Examples: > |
| 1166 | " :autocmd MyGroup |
| 1167 | echo autocmd_get(#{group: 'Mygroup'}) |
| 1168 | " :autocmd G BufUnload |
| 1169 | echo autocmd_get(#{group: 'G', event: 'BufUnload'}) |
| 1170 | " :autocmd G * *.ts |
| 1171 | let acmd = #{group: 'G', event: '*', pattern: '*.ts'} |
| 1172 | echo autocmd_get(acmd) |
| 1173 | " :autocmd Syntax |
| 1174 | echo autocmd_get(#{event: 'Syntax'}) |
| 1175 | " :autocmd G BufEnter *.ts |
| 1176 | let acmd = #{group: 'G', event: 'BufEnter', |
| 1177 | \ pattern: '*.ts'} |
| 1178 | echo autocmd_get(acmd) |
| 1179 | < |
| 1180 | Can also be used as a |method|: > |
| 1181 | Getopts()->autocmd_get() |
| 1182 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1183 | Return type: list<dict<any>> |
| 1184 | |
| 1185 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1186 | balloon_gettext() *balloon_gettext()* |
| 1187 | Return the current text in the balloon. Only for the string, |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 1188 | not used for the List. Returns an empty string if balloon |
| 1189 | is not present. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1190 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1191 | Return type: |String| |
| 1192 | |
| 1193 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1194 | balloon_show({expr}) *balloon_show()* |
| 1195 | Show {expr} inside the balloon. For the GUI {expr} is used as |
| 1196 | a string. For a terminal {expr} can be a list, which contains |
| 1197 | the lines of the balloon. If {expr} is not a list it will be |
| 1198 | split with |balloon_split()|. |
| 1199 | If {expr} is an empty string any existing balloon is removed. |
| 1200 | |
| 1201 | Example: > |
| 1202 | func GetBalloonContent() |
| 1203 | " ... initiate getting the content |
| 1204 | return '' |
| 1205 | endfunc |
| 1206 | set balloonexpr=GetBalloonContent() |
| 1207 | |
| 1208 | func BalloonCallback(result) |
| 1209 | call balloon_show(a:result) |
| 1210 | endfunc |
| 1211 | < Can also be used as a |method|: > |
| 1212 | GetText()->balloon_show() |
| 1213 | < |
| 1214 | The intended use is that fetching the content of the balloon |
| 1215 | is initiated from 'balloonexpr'. It will invoke an |
| 1216 | asynchronous method, in which a callback invokes |
| 1217 | balloon_show(). The 'balloonexpr' itself can return an |
Bram Moolenaar | 069a7d5 | 2022-06-27 22:16:08 +0100 | [diff] [blame] | 1218 | empty string or a placeholder, e.g. "loading...". |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1219 | |
Bram Moolenaar | 069a7d5 | 2022-06-27 22:16:08 +0100 | [diff] [blame] | 1220 | When showing a balloon is not possible then nothing happens, |
| 1221 | no error message is given. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1222 | {only available when compiled with the |+balloon_eval| or |
| 1223 | |+balloon_eval_term| feature} |
| 1224 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1225 | Return type: |Number| |
| 1226 | |
| 1227 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1228 | balloon_split({msg}) *balloon_split()* |
| 1229 | Split String {msg} into lines to be displayed in a balloon. |
| 1230 | The splits are made for the current window size and optimize |
| 1231 | to show debugger output. |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 1232 | Returns a |List| with the split lines. Returns an empty List |
| 1233 | on error. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1234 | Can also be used as a |method|: > |
| 1235 | GetText()->balloon_split()->balloon_show() |
| 1236 | |
| 1237 | < {only available when compiled with the |+balloon_eval_term| |
| 1238 | feature} |
| 1239 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1240 | Return type: list<any> or list<string> |
| 1241 | |
h-east | e80f345 | 2025-01-02 10:40:29 +0100 | [diff] [blame] | 1242 | base64_decode({string}) *base64_decode()* |
| 1243 | Return a Blob containing the bytes decoded from the base64 |
| 1244 | encoded characters in {string}. |
| 1245 | |
| 1246 | The {string} argument should contain only base64-encoded |
| 1247 | characters and should have a length that is a multiple of 4. |
| 1248 | |
| 1249 | Returns an empty blob on error. |
| 1250 | |
| 1251 | Examples: > |
| 1252 | " Write the decoded contents to a binary file |
| 1253 | call writefile(base64_decode(s), 'tools.bmp') |
| 1254 | " Decode a base64-encoded string |
Maxim Kim | 6472e58 | 2025-01-15 18:31:05 +0100 | [diff] [blame] | 1255 | echo blob2str(base64_decode(encodedstr)) |
h-east | e80f345 | 2025-01-02 10:40:29 +0100 | [diff] [blame] | 1256 | < |
| 1257 | Can also be used as a |method|: > |
| 1258 | GetEncodedString()->base64_decode() |
| 1259 | < |
| 1260 | Return type: |Blob| |
| 1261 | |
| 1262 | |
| 1263 | base64_encode({blob}) *base64_encode()* |
| 1264 | Return a base64-encoded String representing the bytes in |
| 1265 | {blob}. The base64 alphabet defined in RFC 4648 is used. |
| 1266 | |
| 1267 | Examples: > |
| 1268 | " Encode the contents of a binary file |
| 1269 | echo base64_encode(readblob('somefile.bin')) |
| 1270 | " Encode a string |
Yegappan Lakshmanan | a11b23c | 2025-01-16 19:16:42 +0100 | [diff] [blame] | 1271 | echo base64_encode(str2blob([somestr])) |
h-east | e80f345 | 2025-01-02 10:40:29 +0100 | [diff] [blame] | 1272 | < |
| 1273 | Can also be used as a |method|: > |
| 1274 | GetBinaryData()->base64_encode() |
| 1275 | < |
| 1276 | Return type: |String| |
| 1277 | |
| 1278 | |
Christ van Willegen | ce0ef91 | 2024-06-20 23:41:59 +0200 | [diff] [blame] | 1279 | bindtextdomain({package}, {path}) *bindtextdomain()* |
| 1280 | Bind a specific {package} to a {path} so that the |
| 1281 | |gettext()| function can be used to get language-specific |
| 1282 | translations for a package. {path} is the directory name |
h-east | 52e7cc2 | 2024-07-28 17:03:29 +0200 | [diff] [blame] | 1283 | for the translations. See |package-translation|. |
Christ van Willegen | ce0ef91 | 2024-06-20 23:41:59 +0200 | [diff] [blame] | 1284 | |
Christ van Willegen | 8252ef1 | 2024-07-11 21:36:21 +0200 | [diff] [blame] | 1285 | Returns v:true on success and v:false on failure (out of |
| 1286 | memory). |
| 1287 | |
| 1288 | Return type: |vim9-boolean| |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1289 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1290 | blob2list({blob}) *blob2list()* |
| 1291 | Return a List containing the number value of each byte in Blob |
| 1292 | {blob}. Examples: > |
| 1293 | blob2list(0z0102.0304) returns [1, 2, 3, 4] |
| 1294 | blob2list(0z) returns [] |
| 1295 | < Returns an empty List on error. |list2blob()| does the |
| 1296 | opposite. |
| 1297 | |
| 1298 | Can also be used as a |method|: > |
| 1299 | GetBlob()->blob2list() |
Bram Moolenaar | b529cfb | 2022-07-25 15:42:07 +0100 | [diff] [blame] | 1300 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1301 | Return type: list<any> or list<number> |
| 1302 | |
Yegappan Lakshmanan | 1aefe1d | 2025-01-14 17:29:42 +0100 | [diff] [blame] | 1303 | |
| 1304 | blob2str({blob} [, {options}]) *blob2str()* |
Yegappan Lakshmanan | a11b23c | 2025-01-16 19:16:42 +0100 | [diff] [blame] | 1305 | Return a List of Strings in the current 'encoding' by |
| 1306 | converting the bytes in {blob} into characters. |
| 1307 | |
| 1308 | Each <NL> byte in the blob is interpreted as the end of a |
| 1309 | string and a new list item is added. Each <NUL> byte in the |
| 1310 | blob is converted into a <NL> character. |
Yegappan Lakshmanan | 1aefe1d | 2025-01-14 17:29:42 +0100 | [diff] [blame] | 1311 | |
| 1312 | If {options} is not supplied, the current 'encoding' value is |
| 1313 | used to decode the bytes in {blob}. |
| 1314 | |
| 1315 | The argument {options} is a |Dict| and supports the following |
| 1316 | items: |
| 1317 | encoding Decode the bytes in {blob} using this |
| 1318 | encoding. The value is a |String|. See |
Bakudankun | b3854bf | 2025-02-23 20:29:21 +0100 | [diff] [blame] | 1319 | |encoding-names| for the supported values |
| 1320 | (plus the special value "none"). |
Christian Brabandt | d5afc74 | 2025-03-18 20:55:42 +0100 | [diff] [blame] | 1321 | *E1515* *E1516* |
Bakudankun | b3854bf | 2025-02-23 20:29:21 +0100 | [diff] [blame] | 1322 | When current 'encoding' is "utf-8", an error is given and an |
| 1323 | empty List is returned if an invalid byte sequence is |
| 1324 | encountered in {blob}. To suppress this validation and get |
| 1325 | potentially invalid string, set "encoding" in {options} to |
| 1326 | "none". |
Yegappan Lakshmanan | 1aefe1d | 2025-01-14 17:29:42 +0100 | [diff] [blame] | 1327 | |
Yegappan Lakshmanan | a11b23c | 2025-01-16 19:16:42 +0100 | [diff] [blame] | 1328 | Returns an empty List if blob is empty. |
Yegappan Lakshmanan | 1aefe1d | 2025-01-14 17:29:42 +0100 | [diff] [blame] | 1329 | |
| 1330 | See also |str2blob()| |
| 1331 | |
| 1332 | Examples: > |
Hirohito Higashi | 932a535 | 2025-03-23 10:20:20 +0100 | [diff] [blame] | 1333 | blob2str(0z6162) returns ['ab'] |
| 1334 | blob2str(0zC2ABC2BB) returns ['«»'] |
| 1335 | blob2str(0z610A62) returns ['a', 'b'] |
| 1336 | blob2str(0z610062) returns ['a\nb'] |
| 1337 | blob2str(0zABBB, {'encoding': 'latin1'}) returns ['«»'] |
Yegappan Lakshmanan | 1aefe1d | 2025-01-14 17:29:42 +0100 | [diff] [blame] | 1338 | < |
| 1339 | Can also be used as a |method|: > |
| 1340 | GetBlob()->blob2str() |
| 1341 | < |
Yegappan Lakshmanan | a11b23c | 2025-01-16 19:16:42 +0100 | [diff] [blame] | 1342 | Return type: list<string> |
Yegappan Lakshmanan | 1aefe1d | 2025-01-14 17:29:42 +0100 | [diff] [blame] | 1343 | |
| 1344 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1345 | *browse()* |
| 1346 | browse({save}, {title}, {initdir}, {default}) |
| 1347 | Put up a file requester. This only works when "has("browse")" |
| 1348 | returns |TRUE| (only in some GUI versions). |
| 1349 | The input fields are: |
| 1350 | {save} when |TRUE|, select file to write |
| 1351 | {title} title for the requester |
| 1352 | {initdir} directory to start browsing in |
| 1353 | {default} default file name |
| 1354 | An empty string is returned when the "Cancel" button is hit, |
| 1355 | something went wrong, or browsing is not possible. |
| 1356 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1357 | Return type: |String| |
| 1358 | |
| 1359 | |
| 1360 | browsedir({title}, {initdir}) *browsedir()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1361 | Put up a directory requester. This only works when |
| 1362 | "has("browse")" returns |TRUE| (only in some GUI versions). |
| 1363 | On systems where a directory browser is not supported a file |
| 1364 | browser is used. In that case: select a file in the directory |
| 1365 | to be used. |
| 1366 | The input fields are: |
| 1367 | {title} title for the requester |
| 1368 | {initdir} directory to start browsing in |
| 1369 | When the "Cancel" button is hit, something went wrong, or |
| 1370 | browsing is not possible, an empty string is returned. |
| 1371 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1372 | Return type: |String| |
| 1373 | |
| 1374 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1375 | bufadd({name}) *bufadd()* |
Bram Moolenaar | 2eddbac | 2022-08-25 12:45:21 +0100 | [diff] [blame] | 1376 | Add a buffer to the buffer list with name {name} (must be a |
| 1377 | String). |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1378 | If a buffer for file {name} already exists, return that buffer |
| 1379 | number. Otherwise return the buffer number of the newly |
| 1380 | created buffer. When {name} is an empty string then a new |
| 1381 | buffer is always created. |
| 1382 | The buffer will not have 'buflisted' set and not be loaded |
| 1383 | yet. To add some text to the buffer use this: > |
| 1384 | let bufnr = bufadd('someName') |
| 1385 | call bufload(bufnr) |
| 1386 | call setbufline(bufnr, 1, ['some', 'text']) |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 1387 | < Returns 0 on error. |
| 1388 | Can also be used as a |method|: > |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1389 | let bufnr = 'somename'->bufadd() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1390 | < |
| 1391 | Return type: |Number| |
| 1392 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1393 | |
| 1394 | bufexists({buf}) *bufexists()* |
| 1395 | The result is a Number, which is |TRUE| if a buffer called |
| 1396 | {buf} exists. |
| 1397 | If the {buf} argument is a number, buffer numbers are used. |
| 1398 | Number zero is the alternate buffer for the current window. |
| 1399 | |
| 1400 | If the {buf} argument is a string it must match a buffer name |
| 1401 | exactly. The name can be: |
| 1402 | - Relative to the current directory. |
| 1403 | - A full path. |
| 1404 | - The name of a buffer with 'buftype' set to "nofile". |
| 1405 | - A URL name. |
| 1406 | Unlisted buffers will be found. |
| 1407 | Note that help files are listed by their short name in the |
| 1408 | output of |:buffers|, but bufexists() requires using their |
| 1409 | long name to be able to find them. |
| 1410 | bufexists() may report a buffer exists, but to use the name |
| 1411 | with a |:buffer| command you may need to use |expand()|. Esp |
| 1412 | for MS-Windows 8.3 names in the form "c:\DOCUME~1" |
| 1413 | Use "bufexists(0)" to test for the existence of an alternate |
| 1414 | file name. |
| 1415 | |
| 1416 | Can also be used as a |method|: > |
| 1417 | let exists = 'somename'->bufexists() |
| 1418 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1419 | Return type: |Number| |
| 1420 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1421 | Obsolete name: buffer_exists(). *buffer_exists()* |
| 1422 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1423 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1424 | buflisted({buf}) *buflisted()* |
| 1425 | The result is a Number, which is |TRUE| if a buffer called |
| 1426 | {buf} exists and is listed (has the 'buflisted' option set). |
| 1427 | The {buf} argument is used like with |bufexists()|. |
| 1428 | |
| 1429 | Can also be used as a |method|: > |
| 1430 | let listed = 'somename'->buflisted() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1431 | < |
| 1432 | Return type: |Number| |
| 1433 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1434 | |
| 1435 | bufload({buf}) *bufload()* |
| 1436 | Ensure the buffer {buf} is loaded. When the buffer name |
| 1437 | refers to an existing file then the file is read. Otherwise |
| 1438 | the buffer will be empty. If the buffer was already loaded |
Bram Moolenaar | 2eddbac | 2022-08-25 12:45:21 +0100 | [diff] [blame] | 1439 | then there is no change. If the buffer is not related to a |
Daniel Steinberg | c2bd205 | 2023-08-09 12:10:59 -0400 | [diff] [blame] | 1440 | file then no file is read (e.g., when 'buftype' is "nofile"). |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1441 | If there is an existing swap file for the file of the buffer, |
| 1442 | there will be no dialog, the buffer will be loaded anyway. |
| 1443 | The {buf} argument is used like with |bufexists()|. |
| 1444 | |
| 1445 | Can also be used as a |method|: > |
| 1446 | eval 'somename'->bufload() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1447 | < |
| 1448 | Return type: |Number| |
| 1449 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1450 | |
| 1451 | bufloaded({buf}) *bufloaded()* |
| 1452 | The result is a Number, which is |TRUE| if a buffer called |
| 1453 | {buf} exists and is loaded (shown in a window or hidden). |
| 1454 | The {buf} argument is used like with |bufexists()|. |
| 1455 | |
| 1456 | Can also be used as a |method|: > |
| 1457 | let loaded = 'somename'->bufloaded() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1458 | < |
| 1459 | Return type: |Number| |
| 1460 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1461 | |
| 1462 | bufname([{buf}]) *bufname()* |
| 1463 | The result is the name of a buffer. Mostly as it is displayed |
| 1464 | by the `:ls` command, but not using special names such as |
| 1465 | "[No Name]". |
| 1466 | If {buf} is omitted the current buffer is used. |
| 1467 | If {buf} is a Number, that buffer number's name is given. |
| 1468 | Number zero is the alternate buffer for the current window. |
| 1469 | If {buf} is a String, it is used as a |file-pattern| to match |
| 1470 | with the buffer names. This is always done like 'magic' is |
| 1471 | set and 'cpoptions' is empty. When there is more than one |
| 1472 | match an empty string is returned. |
| 1473 | "" or "%" can be used for the current buffer, "#" for the |
| 1474 | alternate buffer. |
| 1475 | A full match is preferred, otherwise a match at the start, end |
| 1476 | or middle of the buffer name is accepted. If you only want a |
| 1477 | full match then put "^" at the start and "$" at the end of the |
| 1478 | pattern. |
| 1479 | Listed buffers are found first. If there is a single match |
| 1480 | with a listed buffer, that one is returned. Next unlisted |
| 1481 | buffers are searched for. |
| 1482 | If the {buf} is a String, but you want to use it as a buffer |
| 1483 | number, force it to be a Number by adding zero to it: > |
| 1484 | :echo bufname("3" + 0) |
| 1485 | < Can also be used as a |method|: > |
| 1486 | echo bufnr->bufname() |
| 1487 | |
| 1488 | < If the buffer doesn't exist, or doesn't have a name, an empty |
| 1489 | string is returned. > |
| 1490 | bufname("#") alternate buffer name |
| 1491 | bufname(3) name of buffer 3 |
| 1492 | bufname("%") name of current buffer |
| 1493 | bufname("file2") name of buffer where "file2" matches. |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1494 | < |
| 1495 | Return type: |String| |
| 1496 | *buffer_name()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1497 | Obsolete name: buffer_name(). |
| 1498 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1499 | |
| 1500 | bufnr([{buf} [, {create}]]) *bufnr()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1501 | The result is the number of a buffer, as it is displayed by |
| 1502 | the `:ls` command. For the use of {buf}, see |bufname()| |
| 1503 | above. |
| 1504 | |
| 1505 | If the buffer doesn't exist, -1 is returned. Or, if the |
| 1506 | {create} argument is present and TRUE, a new, unlisted, |
| 1507 | buffer is created and its number is returned. Example: > |
| 1508 | let newbuf = bufnr('Scratch001', 1) |
| 1509 | < Using an empty name uses the current buffer. To create a new |
| 1510 | buffer with an empty name use |bufadd()|. |
| 1511 | |
| 1512 | bufnr("$") is the last buffer: > |
| 1513 | :let last_buffer = bufnr("$") |
| 1514 | < The result is a Number, which is the highest buffer number |
| 1515 | of existing buffers. Note that not all buffers with a smaller |
| 1516 | number necessarily exist, because ":bwipeout" may have removed |
| 1517 | them. Use bufexists() to test for the existence of a buffer. |
| 1518 | |
| 1519 | Can also be used as a |method|: > |
| 1520 | echo bufref->bufnr() |
| 1521 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1522 | Return type: |Number| |
| 1523 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1524 | Obsolete name: buffer_number(). *buffer_number()* |
| 1525 | *last_buffer_nr()* |
| 1526 | Obsolete name for bufnr("$"): last_buffer_nr(). |
| 1527 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1528 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1529 | bufwinid({buf}) *bufwinid()* |
| 1530 | The result is a Number, which is the |window-ID| of the first |
| 1531 | window associated with buffer {buf}. For the use of {buf}, |
| 1532 | see |bufname()| above. If buffer {buf} doesn't exist or |
| 1533 | there is no such window, -1 is returned. Example: > |
| 1534 | |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 1535 | echo "A window containing buffer 1 is " .. (bufwinid(1)) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1536 | < |
Bram Moolenaar | 76db9e0 | 2022-11-09 21:21:04 +0000 | [diff] [blame] | 1537 | Only deals with the current tab page. See |win_findbuf()| for |
| 1538 | finding more. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1539 | |
| 1540 | Can also be used as a |method|: > |
| 1541 | FindBuffer()->bufwinid() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1542 | < |
| 1543 | Return type: |Number| |
| 1544 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1545 | |
| 1546 | bufwinnr({buf}) *bufwinnr()* |
| 1547 | Like |bufwinid()| but return the window number instead of the |
| 1548 | |window-ID|. |
| 1549 | If buffer {buf} doesn't exist or there is no such window, -1 |
| 1550 | is returned. Example: > |
| 1551 | |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 1552 | echo "A window containing buffer 1 is " .. (bufwinnr(1)) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1553 | |
| 1554 | < The number can be used with |CTRL-W_w| and ":wincmd w" |
| 1555 | |:wincmd|. |
| 1556 | |
| 1557 | Can also be used as a |method|: > |
| 1558 | FindBuffer()->bufwinnr() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1559 | < |
| 1560 | Return type: |Number| |
| 1561 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1562 | |
| 1563 | byte2line({byte}) *byte2line()* |
| 1564 | Return the line number that contains the character at byte |
| 1565 | count {byte} in the current buffer. This includes the |
| 1566 | end-of-line character, depending on the 'fileformat' option |
| 1567 | for the current buffer. The first character has byte count |
| 1568 | one. |
| 1569 | Also see |line2byte()|, |go| and |:goto|. |
| 1570 | |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 1571 | Returns -1 if the {byte} value is invalid. |
| 1572 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1573 | Can also be used as a |method|: > |
| 1574 | GetOffset()->byte2line() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1575 | < |
| 1576 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1577 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1578 | {not available when compiled without the |+byte_offset| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1579 | feature} |
| 1580 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1581 | |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 1582 | byteidx({expr}, {nr} [, {utf16}]) *byteidx()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1583 | Return byte index of the {nr}'th character in the String |
| 1584 | {expr}. Use zero for the first character, it then returns |
| 1585 | zero. |
| 1586 | If there are no multibyte characters the returned value is |
| 1587 | equal to {nr}. |
| 1588 | Composing characters are not counted separately, their byte |
| 1589 | length is added to the preceding base character. See |
| 1590 | |byteidxcomp()| below for counting composing characters |
| 1591 | separately. |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 1592 | When {utf16} is present and TRUE, {nr} is used as the UTF-16 |
| 1593 | index in the String {expr} instead of as the character index. |
| 1594 | The UTF-16 index is the index in the string when it is encoded |
| 1595 | with 16-bit words. If the specified UTF-16 index is in the |
| 1596 | middle of a character (e.g. in a 4-byte character), then the |
| 1597 | byte index of the first byte in the character is returned. |
| 1598 | Refer to |string-offset-encoding| for more information. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1599 | Example : > |
| 1600 | echo matchstr(str, ".", byteidx(str, 3)) |
| 1601 | < will display the fourth character. Another way to do the |
| 1602 | same: > |
| 1603 | let s = strpart(str, byteidx(str, 3)) |
| 1604 | echo strpart(s, 0, byteidx(s, 1)) |
| 1605 | < Also see |strgetchar()| and |strcharpart()|. |
| 1606 | |
| 1607 | If there are less than {nr} characters -1 is returned. |
| 1608 | If there are exactly {nr} characters the length of the string |
| 1609 | in bytes is returned. |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 1610 | See |charidx()| and |utf16idx()| for getting the character and |
| 1611 | UTF-16 index respectively from the byte index. |
| 1612 | Examples: > |
| 1613 | echo byteidx('a😊😊', 2) returns 5 |
| 1614 | echo byteidx('a😊😊', 2, 1) returns 1 |
| 1615 | echo byteidx('a😊😊', 3, 1) returns 5 |
| 1616 | < |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1617 | Can also be used as a |method|: > |
| 1618 | GetName()->byteidx(idx) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1619 | < |
| 1620 | Return type: |Number| |
| 1621 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1622 | |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 1623 | byteidxcomp({expr}, {nr} [, {utf16}]) *byteidxcomp()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1624 | Like byteidx(), except that a composing character is counted |
| 1625 | as a separate character. Example: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 1626 | let s = 'e' .. nr2char(0x301) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1627 | echo byteidx(s, 1) |
| 1628 | echo byteidxcomp(s, 1) |
| 1629 | echo byteidxcomp(s, 2) |
| 1630 | < The first and third echo result in 3 ('e' plus composing |
| 1631 | character is 3 bytes), the second echo results in 1 ('e' is |
| 1632 | one byte). |
| 1633 | Only works differently from byteidx() when 'encoding' is set |
| 1634 | to a Unicode encoding. |
| 1635 | |
| 1636 | Can also be used as a |method|: > |
| 1637 | GetName()->byteidxcomp(idx) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1638 | < |
| 1639 | Return type: |Number| |
| 1640 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1641 | |
| 1642 | call({func}, {arglist} [, {dict}]) *call()* *E699* |
| 1643 | Call function {func} with the items in |List| {arglist} as |
| 1644 | arguments. |
| 1645 | {func} can either be a |Funcref| or the name of a function. |
| 1646 | a:firstline and a:lastline are set to the cursor line. |
| 1647 | Returns the return value of the called function. |
| 1648 | {dict} is for functions with the "dict" attribute. It will be |
| 1649 | used to set the local variable "self". |Dictionary-function| |
| 1650 | |
| 1651 | Can also be used as a |method|: > |
| 1652 | GetFunc()->call([arg, arg], dict) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1653 | < |
| 1654 | Return type: any, depending on {func} |
| 1655 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1656 | |
| 1657 | ceil({expr}) *ceil()* |
| 1658 | Return the smallest integral value greater than or equal to |
| 1659 | {expr} as a |Float| (round up). |
| 1660 | {expr} must evaluate to a |Float| or a |Number|. |
| 1661 | Examples: > |
| 1662 | echo ceil(1.456) |
| 1663 | < 2.0 > |
| 1664 | echo ceil(-5.456) |
| 1665 | < -5.0 > |
| 1666 | echo ceil(4.0) |
| 1667 | < 4.0 |
| 1668 | |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 1669 | Returns 0.0 if {expr} is not a |Float| or a |Number|. |
| 1670 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1671 | Can also be used as a |method|: > |
| 1672 | Compute()->ceil() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1673 | < |
| 1674 | Return type: |Float| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1675 | |
| 1676 | |
| 1677 | ch_ functions are documented here: |channel-functions-details| |
| 1678 | |
| 1679 | |
| 1680 | changenr() *changenr()* |
| 1681 | Return the number of the most recent change. This is the same |
| 1682 | number as what is displayed with |:undolist| and can be used |
| 1683 | with the |:undo| command. |
| 1684 | When a change was made it is the number of that change. After |
| 1685 | redo it is the number of the redone change. After undo it is |
| 1686 | one less than the number of the undone change. |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 1687 | Returns 0 if the undo list is empty. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1688 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1689 | Return type: |Number| |
| 1690 | |
| 1691 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1692 | char2nr({string} [, {utf8}]) *char2nr()* |
Bram Moolenaar | 2d8ed02 | 2022-05-21 13:08:16 +0100 | [diff] [blame] | 1693 | Return Number value of the first char in {string}. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1694 | Examples: > |
| 1695 | char2nr(" ") returns 32 |
| 1696 | char2nr("ABC") returns 65 |
| 1697 | < When {utf8} is omitted or zero, the current 'encoding' is used. |
| 1698 | Example for "utf-8": > |
| 1699 | char2nr("á") returns 225 |
| 1700 | char2nr("á"[0]) returns 195 |
| 1701 | < When {utf8} is TRUE, always treat as UTF-8 characters. |
| 1702 | A combining character is a separate character. |
| 1703 | |nr2char()| does the opposite. |
| 1704 | To turn a string into a list of character numbers: > |
| 1705 | let str = "ABC" |
| 1706 | let list = map(split(str, '\zs'), {_, val -> char2nr(val)}) |
| 1707 | < Result: [65, 66, 67] |
| 1708 | |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 1709 | Returns 0 if {string} is not a |String|. |
| 1710 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1711 | Can also be used as a |method|: > |
| 1712 | GetChar()->char2nr() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1713 | < |
| 1714 | Return type: |Number| |
| 1715 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1716 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1717 | charclass({string}) *charclass()* |
| 1718 | Return the character class of the first character in {string}. |
| 1719 | The character class is one of: |
| 1720 | 0 blank |
| 1721 | 1 punctuation |
Christian Brabandt | b5e7da1 | 2024-11-01 09:33:00 +0100 | [diff] [blame] | 1722 | 2 word character (depends on 'iskeyword') |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1723 | 3 emoji |
| 1724 | other specific Unicode class |
| 1725 | The class is used in patterns and word motions. |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 1726 | Returns 0 if {string} is not a |String|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1727 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1728 | Return type: |Number| |
| 1729 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1730 | |
Yegappan Lakshmanan | 4c8d2f0 | 2022-11-12 16:07:47 +0000 | [diff] [blame] | 1731 | charcol({expr} [, {winid}]) *charcol()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1732 | Same as |col()| but returns the character index of the column |
| 1733 | position given with {expr} instead of the byte position. |
| 1734 | |
| 1735 | Example: |
| 1736 | With the cursor on '세' in line 5 with text "여보세요": > |
| 1737 | charcol('.') returns 3 |
| 1738 | col('.') returns 7 |
| 1739 | |
| 1740 | < Can also be used as a |method|: > |
| 1741 | GetPos()->col() |
| 1742 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1743 | Return type: |Number| |
| 1744 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1745 | *charidx()* |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 1746 | charidx({string}, {idx} [, {countcc} [, {utf16}]]) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1747 | Return the character index of the byte at {idx} in {string}. |
| 1748 | The index of the first character is zero. |
| 1749 | If there are no multibyte characters the returned value is |
| 1750 | equal to {idx}. |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 1751 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1752 | When {countcc} is omitted or |FALSE|, then composing characters |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 1753 | are not counted separately, their byte length is added to the |
| 1754 | preceding base character. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1755 | When {countcc} is |TRUE|, then composing characters are |
| 1756 | counted as separate characters. |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 1757 | |
| 1758 | When {utf16} is present and TRUE, {idx} is used as the UTF-16 |
| 1759 | index in the String {expr} instead of as the byte index. |
| 1760 | |
Yegappan Lakshmanan | 577922b | 2023-06-08 17:09:45 +0100 | [diff] [blame] | 1761 | Returns -1 if the arguments are invalid or if there are less |
| 1762 | than {idx} bytes. If there are exactly {idx} bytes the length |
| 1763 | of the string in characters is returned. |
| 1764 | |
| 1765 | An error is given and -1 is returned if the first argument is |
| 1766 | not a string, the second argument is not a number or when the |
| 1767 | third argument is present and is not zero or one. |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 1768 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1769 | See |byteidx()| and |byteidxcomp()| for getting the byte index |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 1770 | from the character index and |utf16idx()| for getting the |
| 1771 | UTF-16 index from the character index. |
| 1772 | Refer to |string-offset-encoding| for more information. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1773 | Examples: > |
| 1774 | echo charidx('áb́ć', 3) returns 1 |
| 1775 | echo charidx('áb́ć', 6, 1) returns 4 |
| 1776 | echo charidx('áb́ć', 16) returns -1 |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 1777 | echo charidx('a😊😊', 4, 0, 1) returns 2 |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1778 | < |
| 1779 | Can also be used as a |method|: > |
| 1780 | GetName()->charidx(idx) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1781 | < |
| 1782 | Return type: |Number| |
| 1783 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1784 | |
| 1785 | chdir({dir}) *chdir()* |
| 1786 | Change the current working directory to {dir}. The scope of |
| 1787 | the directory change depends on the directory of the current |
| 1788 | window: |
| 1789 | - If the current window has a window-local directory |
| 1790 | (|:lcd|), then changes the window local directory. |
| 1791 | - Otherwise, if the current tabpage has a local |
| 1792 | directory (|:tcd|) then changes the tabpage local |
| 1793 | directory. |
| 1794 | - Otherwise, changes the global directory. |
| 1795 | {dir} must be a String. |
| 1796 | If successful, returns the previous working directory. Pass |
| 1797 | this to another chdir() to restore the directory. |
| 1798 | On failure, returns an empty string. |
| 1799 | |
| 1800 | Example: > |
| 1801 | let save_dir = chdir(newdir) |
| 1802 | if save_dir != "" |
| 1803 | " ... do some work |
| 1804 | call chdir(save_dir) |
| 1805 | endif |
| 1806 | |
| 1807 | < Can also be used as a |method|: > |
| 1808 | GetDir()->chdir() |
| 1809 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1810 | Return type: |String| |
| 1811 | |
| 1812 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1813 | cindent({lnum}) *cindent()* |
| 1814 | Get the amount of indent for line {lnum} according the C |
| 1815 | indenting rules, as with 'cindent'. |
| 1816 | The indent is counted in spaces, the value of 'tabstop' is |
| 1817 | relevant. {lnum} is used just like in |getline()|. |
Bram Moolenaar | 8e145b8 | 2022-05-21 20:17:31 +0100 | [diff] [blame] | 1818 | When {lnum} is invalid -1 is returned. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1819 | See |C-indenting|. |
| 1820 | |
| 1821 | Can also be used as a |method|: > |
| 1822 | GetLnum()->cindent() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1823 | < |
| 1824 | Return type: |Number| |
| 1825 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1826 | |
| 1827 | clearmatches([{win}]) *clearmatches()* |
| 1828 | Clears all matches previously defined for the current window |
| 1829 | by |matchadd()| and the |:match| commands. |
| 1830 | If {win} is specified, use the window with this number or |
| 1831 | window ID instead of the current window. |
| 1832 | |
| 1833 | Can also be used as a |method|: > |
| 1834 | GetWin()->clearmatches() |
| 1835 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1836 | Return type: |Number| |
| 1837 | |
| 1838 | |
Girish Palya | 5c3d1e3 | 2025-04-22 19:52:16 +0200 | [diff] [blame] | 1839 | cmdcomplete_info() *cmdcomplete_info()* |
Girish Palya | 92f68e2 | 2025-04-21 11:12:41 +0200 | [diff] [blame] | 1840 | Returns a |Dictionary| with information about cmdline |
| 1841 | completion. See |cmdline-completion|. |
| 1842 | The items are: |
| 1843 | cmdline_orig The original command-line string before |
| 1844 | completion began. |
| 1845 | pum_visible |TRUE| if popup menu is visible. |
| 1846 | See |pumvisible()|. |
| 1847 | matches List of all completion candidates. Each item |
| 1848 | is a string. |
| 1849 | selected Selected item index. First index is zero. |
| 1850 | Index is -1 if no item is selected (showing |
| 1851 | typed text only, or the last completion after |
| 1852 | no item is selected when using the <Up> or |
| 1853 | <Down> keys) |
| 1854 | |
| 1855 | Returns an empty |Dictionary| if no completion was attempted, |
| 1856 | if there was only one candidate and it was fully completed, or |
| 1857 | if an error occurred. |
| 1858 | |
| 1859 | Return type: dict<any> |
| 1860 | |
| 1861 | |
Bram Moolenaar | 10e8ff9 | 2023-06-10 21:40:39 +0100 | [diff] [blame] | 1862 | col({expr} [, {winid}]) *col()* |
Yegappan Lakshmanan | 4c8d2f0 | 2022-11-12 16:07:47 +0000 | [diff] [blame] | 1863 | The result is a Number, which is the byte index of the column |
zeertzjq | 02f3eba | 2024-06-12 20:45:24 +0200 | [diff] [blame] | 1864 | position given with {expr}. |
| 1865 | For accepted positions see |getpos()|. |
zeertzjq | d353d27 | 2024-06-13 23:00:25 +0800 | [diff] [blame] | 1866 | When {expr} is "$", it means the end of the cursor line, so |
| 1867 | the result is the number of bytes in the cursor line plus one. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1868 | Additionally {expr} can be [lnum, col]: a |List| with the line |
| 1869 | and column number. Most useful when the column is "$", to get |
| 1870 | the last column of a specific line. When "lnum" or "col" is |
| 1871 | out of range then col() returns zero. |
zeertzjq | 02f3eba | 2024-06-12 20:45:24 +0200 | [diff] [blame] | 1872 | |
Yegappan Lakshmanan | 4c8d2f0 | 2022-11-12 16:07:47 +0000 | [diff] [blame] | 1873 | With the optional {winid} argument the values are obtained for |
| 1874 | that window instead of the current window. |
zeertzjq | 02f3eba | 2024-06-12 20:45:24 +0200 | [diff] [blame] | 1875 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1876 | To get the line number use |line()|. To get both use |
| 1877 | |getpos()|. |
| 1878 | For the screen column position use |virtcol()|. For the |
| 1879 | character position use |charcol()|. |
zeertzjq | 02f3eba | 2024-06-12 20:45:24 +0200 | [diff] [blame] | 1880 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1881 | Note that only marks in the current file can be used. |
zeertzjq | 02f3eba | 2024-06-12 20:45:24 +0200 | [diff] [blame] | 1882 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1883 | Examples: > |
| 1884 | col(".") column of cursor |
| 1885 | col("$") length of cursor line plus one |
| 1886 | col("'t") column of mark t |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 1887 | col("'" .. markname) column of mark markname |
zeertzjq | 02f3eba | 2024-06-12 20:45:24 +0200 | [diff] [blame] | 1888 | < |
| 1889 | The first column is 1. Returns 0 if {expr} is invalid or when |
Yegappan Lakshmanan | 4c8d2f0 | 2022-11-12 16:07:47 +0000 | [diff] [blame] | 1890 | the window with ID {winid} is not found. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1891 | For an uppercase mark the column may actually be in another |
| 1892 | buffer. |
| 1893 | For the cursor position, when 'virtualedit' is active, the |
| 1894 | column is one higher if the cursor is after the end of the |
Bram Moolenaar | 6ebe4f9 | 2022-10-28 20:47:54 +0100 | [diff] [blame] | 1895 | line. Also, when using a <Cmd> mapping the cursor isn't |
| 1896 | moved, this can be used to obtain the column in Insert mode: > |
Bram Moolenaar | 76db9e0 | 2022-11-09 21:21:04 +0000 | [diff] [blame] | 1897 | :imap <F2> <Cmd>echowin col(".")<CR> |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1898 | |
| 1899 | < Can also be used as a |method|: > |
| 1900 | GetPos()->col() |
| 1901 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1902 | Return type: |Number| |
| 1903 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1904 | |
| 1905 | complete({startcol}, {matches}) *complete()* *E785* |
| 1906 | Set the matches for Insert mode completion. |
| 1907 | Can only be used in Insert mode. You need to use a mapping |
| 1908 | with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O |
| 1909 | or with an expression mapping. |
| 1910 | {startcol} is the byte offset in the line where the completed |
| 1911 | text start. The text up to the cursor is the original text |
| 1912 | that will be replaced by the matches. Use col('.') for an |
| 1913 | empty string. "col('.') - 1" will replace one character by a |
| 1914 | match. |
| 1915 | {matches} must be a |List|. Each |List| item is one match. |
| 1916 | See |complete-items| for the kind of items that are possible. |
| 1917 | "longest" in 'completeopt' is ignored. |
| 1918 | Note that the after calling this function you need to avoid |
| 1919 | inserting anything that would cause completion to stop. |
| 1920 | The match can be selected with CTRL-N and CTRL-P as usual with |
| 1921 | Insert mode completion. The popup menu will appear if |
| 1922 | specified, see |ins-completion-menu|. |
| 1923 | Example: > |
| 1924 | inoremap <F5> <C-R>=ListMonths()<CR> |
| 1925 | |
Bram Moolenaar | 10e8ff9 | 2023-06-10 21:40:39 +0100 | [diff] [blame] | 1926 | func ListMonths() |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1927 | call complete(col('.'), ['January', 'February', 'March', |
| 1928 | \ 'April', 'May', 'June', 'July', 'August', 'September', |
| 1929 | \ 'October', 'November', 'December']) |
| 1930 | return '' |
| 1931 | endfunc |
| 1932 | < This isn't very useful, but it shows how it works. Note that |
| 1933 | an empty string is returned to avoid a zero being inserted. |
| 1934 | |
| 1935 | Can also be used as a |method|, the base is passed as the |
| 1936 | second argument: > |
| 1937 | GetMatches()->complete(col('.')) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1938 | < |
| 1939 | Return type: |Number| |
| 1940 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1941 | |
| 1942 | complete_add({expr}) *complete_add()* |
| 1943 | Add {expr} to the list of matches. Only to be used by the |
| 1944 | function specified with the 'completefunc' option. |
| 1945 | Returns 0 for failure (empty string or out of memory), |
| 1946 | 1 when the match was added, 2 when the match was already in |
| 1947 | the list. |
| 1948 | See |complete-functions| for an explanation of {expr}. It is |
| 1949 | the same as one item in the list that 'omnifunc' would return. |
| 1950 | |
| 1951 | Can also be used as a |method|: > |
| 1952 | GetMoreMatches()->complete_add() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1953 | < |
| 1954 | Return type: |Number| |
| 1955 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1956 | |
| 1957 | complete_check() *complete_check()* |
| 1958 | Check for a key typed while looking for completion matches. |
| 1959 | This is to be used when looking for matches takes some time. |
| 1960 | Returns |TRUE| when searching for matches is to be aborted, |
| 1961 | zero otherwise. |
| 1962 | Only to be used by the function specified with the |
| 1963 | 'completefunc' option. |
| 1964 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 1965 | Return type: |Number| |
| 1966 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1967 | |
| 1968 | complete_info([{what}]) *complete_info()* |
| 1969 | Returns a |Dictionary| with information about Insert mode |
| 1970 | completion. See |ins-completion|. |
| 1971 | The items are: |
| 1972 | mode Current completion mode name string. |
| 1973 | See |complete_info_mode| for the values. |
| 1974 | pum_visible |TRUE| if popup menu is visible. |
| 1975 | See |pumvisible()|. |
glepnir | d4088ed | 2024-12-31 10:55:22 +0100 | [diff] [blame] | 1976 | items List of all completion candidates. Each item |
| 1977 | is a dictionary containing the entries "word", |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1978 | "abbr", "menu", "kind", "info" and "user_data". |
| 1979 | See |complete-items|. |
glepnir | d4088ed | 2024-12-31 10:55:22 +0100 | [diff] [blame] | 1980 | matches Same as "items", but only returns items that |
| 1981 | are matching current query. If both "matches" |
| 1982 | and "items" are in "what", the returned list |
| 1983 | will still be named "items", but each item |
| 1984 | will have an additional "match" field. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1985 | selected Selected item index. First index is zero. |
| 1986 | Index is -1 if no item is selected (showing |
| 1987 | typed text only, or the last completion after |
| 1988 | no item is selected when using the <Up> or |
| 1989 | <Down> keys) |
glepnir | 037b028 | 2025-01-16 14:37:44 +0100 | [diff] [blame] | 1990 | completed Return a dictionary containing the entries of |
| 1991 | the currently selected index item. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 1992 | |
| 1993 | *complete_info_mode* |
| 1994 | mode values are: |
| 1995 | "" Not in completion mode |
| 1996 | "keyword" Keyword completion |i_CTRL-X_CTRL-N| |
| 1997 | "ctrl_x" Just pressed CTRL-X |i_CTRL-X| |
| 1998 | "scroll" Scrolling with |i_CTRL-X_CTRL-E| or |
| 1999 | |i_CTRL-X_CTRL-Y| |
| 2000 | "whole_line" Whole lines |i_CTRL-X_CTRL-L| |
| 2001 | "files" File names |i_CTRL-X_CTRL-F| |
| 2002 | "tags" Tags |i_CTRL-X_CTRL-]| |
| 2003 | "path_defines" Definition completion |i_CTRL-X_CTRL-D| |
| 2004 | "path_patterns" Include completion |i_CTRL-X_CTRL-I| |
| 2005 | "dictionary" Dictionary |i_CTRL-X_CTRL-K| |
| 2006 | "thesaurus" Thesaurus |i_CTRL-X_CTRL-T| |
| 2007 | "cmdline" Vim Command line |i_CTRL-X_CTRL-V| |
| 2008 | "function" User defined completion |i_CTRL-X_CTRL-U| |
| 2009 | "omni" Omni completion |i_CTRL-X_CTRL-O| |
| 2010 | "spell" Spelling suggestions |i_CTRL-X_s| |
| 2011 | "eval" |complete()| completion |
glepnir | 49864ae | 2025-05-28 20:39:34 +0200 | [diff] [blame] | 2012 | "register" Words from registers |i_CTRL-X_CTRL-R| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2013 | "unknown" Other internal modes |
| 2014 | |
| 2015 | If the optional {what} list argument is supplied, then only |
| 2016 | the items listed in {what} are returned. Unsupported items in |
| 2017 | {what} are silently ignored. |
| 2018 | |
| 2019 | To get the position and size of the popup menu, see |
| 2020 | |pum_getpos()|. It's also available in |v:event| during the |
| 2021 | |CompleteChanged| event. |
| 2022 | |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 2023 | Returns an empty |Dictionary| on error. |
| 2024 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2025 | Examples: > |
| 2026 | " Get all items |
| 2027 | call complete_info() |
| 2028 | " Get only 'mode' |
| 2029 | call complete_info(['mode']) |
| 2030 | " Get only 'mode' and 'pum_visible' |
| 2031 | call complete_info(['mode', 'pum_visible']) |
| 2032 | |
| 2033 | < Can also be used as a |method|: > |
| 2034 | GetItems()->complete_info() |
| 2035 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2036 | Return type: dict<any> |
| 2037 | |
glepnir | bcd5995 | 2025-04-24 21:48:35 +0200 | [diff] [blame] | 2038 | complete_match([{lnum}, {col}]) *complete_match()* |
glepnir | ffc89e4 | 2025-04-27 14:59:17 +0200 | [diff] [blame] | 2039 | Searches backward from the given position and returns a List |
| 2040 | of matches according to the 'isexpand' option. When no |
| 2041 | arguments are provided, uses the current cursor position. |
| 2042 | |
| 2043 | Each match is represented as a List containing |
glepnir | bcd5995 | 2025-04-24 21:48:35 +0200 | [diff] [blame] | 2044 | [startcol, trigger_text] where: |
| 2045 | - startcol: column position where completion should start, |
| 2046 | or -1 if no trigger position is found. For multi-character |
| 2047 | triggers, returns the column of the first character. |
| 2048 | - trigger_text: the matching trigger string from 'isexpand', |
| 2049 | or empty string if no match was found or when using the |
| 2050 | default 'iskeyword' pattern. |
| 2051 | |
Hirohito Higashi | 8f7256a | 2025-06-07 18:31:42 +0200 | [diff] [blame] | 2052 | When 'isexpand' is empty, uses the 'iskeyword' pattern "\k\+$" |
| 2053 | to find the start of the current keyword. |
glepnir | bcd5995 | 2025-04-24 21:48:35 +0200 | [diff] [blame] | 2054 | |
glepnir | bcd5995 | 2025-04-24 21:48:35 +0200 | [diff] [blame] | 2055 | Examples: > |
| 2056 | set isexpand=.,->,/,/*,abc |
| 2057 | func CustomComplete() |
| 2058 | let res = complete_match() |
| 2059 | if res->len() == 0 | return | endif |
| 2060 | let [col, trigger] = res[0] |
| 2061 | let items = [] |
| 2062 | if trigger == '/*' |
| 2063 | let items = ['/** */'] |
| 2064 | elseif trigger == '/' |
| 2065 | let items = ['/*! */', '// TODO:', '// fixme:'] |
| 2066 | elseif trigger == '.' |
| 2067 | let items = ['length()'] |
| 2068 | elseif trigger =~ '^\->' |
| 2069 | let items = ['map()', 'reduce()'] |
| 2070 | elseif trigger =~ '^\abc' |
| 2071 | let items = ['def', 'ghk'] |
| 2072 | endif |
| 2073 | if items->len() > 0 |
| 2074 | let startcol = trigger =~ '^/' ? col : col + len(trigger) |
| 2075 | call complete(startcol, items) |
| 2076 | endif |
| 2077 | endfunc |
| 2078 | inoremap <Tab> <Cmd>call CustomComplete()<CR> |
| 2079 | < |
| 2080 | Return type: list<list<any>> |
| 2081 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2082 | *confirm()* |
| 2083 | confirm({msg} [, {choices} [, {default} [, {type}]]]) |
| 2084 | confirm() offers the user a dialog, from which a choice can be |
| 2085 | made. It returns the number of the choice. For the first |
| 2086 | choice this is 1. |
| 2087 | Note: confirm() is only supported when compiled with dialog |
glepnir | df46115 | 2024-04-04 22:23:29 +0200 | [diff] [blame] | 2088 | support, see |+dialog_con| |+dialog_con_gui| and |+dialog_gui|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2089 | |
| 2090 | {msg} is displayed in a |dialog| with {choices} as the |
| 2091 | alternatives. When {choices} is missing or empty, "&OK" is |
| 2092 | used (and translated). |
| 2093 | {msg} is a String, use '\n' to include a newline. Only on |
| 2094 | some systems the string is wrapped when it doesn't fit. |
| 2095 | |
| 2096 | {choices} is a String, with the individual choices separated |
| 2097 | by '\n', e.g. > |
| 2098 | confirm("Save changes?", "&Yes\n&No\n&Cancel") |
| 2099 | < The letter after the '&' is the shortcut key for that choice. |
| 2100 | Thus you can type 'c' to select "Cancel". The shortcut does |
| 2101 | not need to be the first letter: > |
| 2102 | confirm("file has been modified", "&Save\nSave &All") |
| 2103 | < For the console, the first letter of each choice is used as |
| 2104 | the default shortcut key. Case is ignored. |
| 2105 | |
| 2106 | The optional {default} argument is the number of the choice |
| 2107 | that is made if the user hits <CR>. Use 1 to make the first |
| 2108 | choice the default one. Use 0 to not set a default. If |
| 2109 | {default} is omitted, 1 is used. |
| 2110 | |
| 2111 | The optional {type} String argument gives the type of dialog. |
| 2112 | This is only used for the icon of the GTK, Mac, Motif and |
| 2113 | Win32 GUI. It can be one of these values: "Error", |
| 2114 | "Question", "Info", "Warning" or "Generic". Only the first |
| 2115 | character is relevant. When {type} is omitted, "Generic" is |
| 2116 | used. |
| 2117 | |
| 2118 | If the user aborts the dialog by pressing <Esc>, CTRL-C, |
| 2119 | or another valid interrupt key, confirm() returns 0. |
| 2120 | |
| 2121 | An example: > |
Bram Moolenaar | 46eea44 | 2022-03-30 10:51:39 +0100 | [diff] [blame] | 2122 | let choice = confirm("What do you want?", |
Bram Moolenaar | 2d8ed02 | 2022-05-21 13:08:16 +0100 | [diff] [blame] | 2123 | \ "&Apples\n&Oranges\n&Bananas", 2) |
Bram Moolenaar | 46eea44 | 2022-03-30 10:51:39 +0100 | [diff] [blame] | 2124 | if choice == 0 |
Bram Moolenaar | 2d8ed02 | 2022-05-21 13:08:16 +0100 | [diff] [blame] | 2125 | echo "make up your mind!" |
Bram Moolenaar | 46eea44 | 2022-03-30 10:51:39 +0100 | [diff] [blame] | 2126 | elseif choice == 3 |
Bram Moolenaar | 2d8ed02 | 2022-05-21 13:08:16 +0100 | [diff] [blame] | 2127 | echo "tasteful" |
Bram Moolenaar | 46eea44 | 2022-03-30 10:51:39 +0100 | [diff] [blame] | 2128 | else |
Bram Moolenaar | 2d8ed02 | 2022-05-21 13:08:16 +0100 | [diff] [blame] | 2129 | echo "I prefer bananas myself." |
Bram Moolenaar | 46eea44 | 2022-03-30 10:51:39 +0100 | [diff] [blame] | 2130 | endif |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2131 | < In a GUI dialog, buttons are used. The layout of the buttons |
| 2132 | depends on the 'v' flag in 'guioptions'. If it is included, |
| 2133 | the buttons are always put vertically. Otherwise, confirm() |
| 2134 | tries to put the buttons in one horizontal line. If they |
| 2135 | don't fit, a vertical layout is used anyway. For some systems |
| 2136 | the horizontal layout is always used. |
| 2137 | |
| 2138 | Can also be used as a |method|in: > |
| 2139 | BuildMessage()->confirm("&Yes\n&No") |
| 2140 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2141 | Return type: |Number| |
| 2142 | |
| 2143 | |
| 2144 | copy({expr}) *copy()* |
| 2145 | Make a copy of {expr}. For Numbers and Strings this isn't |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2146 | different from using {expr} directly. |
| 2147 | When {expr} is a |List| a shallow copy is created. This means |
| 2148 | that the original |List| can be changed without changing the |
| 2149 | copy, and vice versa. But the items are identical, thus |
| 2150 | changing an item changes the contents of both |Lists|. |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 2151 | A |Tuple| or |Dictionary| is copied in a similar way as a |
| 2152 | |List|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2153 | Also see |deepcopy()|. |
| 2154 | Can also be used as a |method|: > |
| 2155 | mylist->copy() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2156 | < |
| 2157 | Return type: any, depending on {expr} |
| 2158 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2159 | |
| 2160 | cos({expr}) *cos()* |
| 2161 | Return the cosine of {expr}, measured in radians, as a |Float|. |
| 2162 | {expr} must evaluate to a |Float| or a |Number|. |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 2163 | Returns 0.0 if {expr} is not a |Float| or a |Number|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2164 | Examples: > |
| 2165 | :echo cos(100) |
| 2166 | < 0.862319 > |
| 2167 | :echo cos(-4.01) |
| 2168 | < -0.646043 |
| 2169 | |
| 2170 | Can also be used as a |method|: > |
| 2171 | Compute()->cos() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2172 | < |
| 2173 | Return type: |Float| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2174 | |
| 2175 | |
| 2176 | cosh({expr}) *cosh()* |
| 2177 | Return the hyperbolic cosine of {expr} as a |Float| in the range |
| 2178 | [1, inf]. |
| 2179 | {expr} must evaluate to a |Float| or a |Number|. |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 2180 | Returns 0.0 if {expr} is not a |Float| or a |Number|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2181 | Examples: > |
| 2182 | :echo cosh(0.5) |
| 2183 | < 1.127626 > |
| 2184 | :echo cosh(-0.5) |
| 2185 | < -1.127626 |
| 2186 | |
| 2187 | Can also be used as a |method|: > |
| 2188 | Compute()->cosh() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2189 | < |
| 2190 | Return type: |Float| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2191 | |
| 2192 | |
Yegappan Lakshmanan | cd39b69 | 2023-10-02 12:50:45 -0700 | [diff] [blame] | 2193 | count({comp}, {expr} [, {ic} [, {start}]]) *count()* *E706* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2194 | Return the number of times an item with value {expr} appears |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 2195 | in |String|, |List|, |Tuple| or |Dictionary| {comp}. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2196 | |
| 2197 | If {start} is given then start with the item with this index. |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 2198 | {start} can only be used with a |List| or a |Tuple|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2199 | |
| 2200 | When {ic} is given and it's |TRUE| then case is ignored. |
| 2201 | |
| 2202 | When {comp} is a string then the number of not overlapping |
| 2203 | occurrences of {expr} is returned. Zero is returned when |
| 2204 | {expr} is an empty string. |
| 2205 | |
| 2206 | Can also be used as a |method|: > |
| 2207 | mylist->count(val) |
| 2208 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2209 | Return type: |Number| |
| 2210 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2211 | *cscope_connection()* |
| 2212 | cscope_connection([{num} , {dbpath} [, {prepend}]]) |
| 2213 | Checks for the existence of a |cscope| connection. If no |
| 2214 | parameters are specified, then the function returns: |
| 2215 | 0, if cscope was not available (not compiled in), or |
| 2216 | if there are no cscope connections; |
| 2217 | 1, if there is at least one cscope connection. |
| 2218 | |
| 2219 | If parameters are specified, then the value of {num} |
| 2220 | determines how existence of a cscope connection is checked: |
| 2221 | |
| 2222 | {num} Description of existence check |
| 2223 | ----- ------------------------------ |
| 2224 | 0 Same as no parameters (e.g., "cscope_connection()"). |
| 2225 | 1 Ignore {prepend}, and use partial string matches for |
| 2226 | {dbpath}. |
| 2227 | 2 Ignore {prepend}, and use exact string matches for |
| 2228 | {dbpath}. |
| 2229 | 3 Use {prepend}, use partial string matches for both |
| 2230 | {dbpath} and {prepend}. |
| 2231 | 4 Use {prepend}, use exact string matches for both |
| 2232 | {dbpath} and {prepend}. |
| 2233 | |
| 2234 | Note: All string comparisons are case sensitive! |
| 2235 | |
| 2236 | Examples. Suppose we had the following (from ":cs show"): > |
| 2237 | |
| 2238 | # pid database name prepend path |
| 2239 | 0 27664 cscope.out /usr/local |
| 2240 | < |
| 2241 | Invocation Return Val ~ |
| 2242 | ---------- ---------- > |
| 2243 | cscope_connection() 1 |
| 2244 | cscope_connection(1, "out") 1 |
| 2245 | cscope_connection(2, "out") 0 |
| 2246 | cscope_connection(3, "out") 0 |
| 2247 | cscope_connection(3, "out", "local") 1 |
| 2248 | cscope_connection(4, "out") 0 |
| 2249 | cscope_connection(4, "out", "local") 0 |
| 2250 | cscope_connection(4, "cscope.out", "/usr/local") 1 |
| 2251 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2252 | Return type: |Number| |
| 2253 | |
| 2254 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2255 | cursor({lnum}, {col} [, {off}]) *cursor()* |
| 2256 | cursor({list}) |
| 2257 | Positions the cursor at the column (byte count) {col} in the |
| 2258 | line {lnum}. The first column is one. |
| 2259 | |
| 2260 | When there is one argument {list} this is used as a |List| |
| 2261 | with two, three or four item: |
| 2262 | [{lnum}, {col}] |
| 2263 | [{lnum}, {col}, {off}] |
| 2264 | [{lnum}, {col}, {off}, {curswant}] |
| 2265 | This is like the return value of |getpos()| or |getcurpos()|, |
| 2266 | but without the first item. |
| 2267 | |
Bram Moolenaar | 10e8ff9 | 2023-06-10 21:40:39 +0100 | [diff] [blame] | 2268 | To position the cursor using {col} as the character count, use |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2269 | |setcursorcharpos()|. |
| 2270 | |
| 2271 | Does not change the jumplist. |
Bram Moolenaar | 7c6cd44 | 2022-10-11 21:54:04 +0100 | [diff] [blame] | 2272 | {lnum} is used like with |getline()|, except that if {lnum} is |
| 2273 | zero, the cursor will stay in the current line. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2274 | If {lnum} is greater than the number of lines in the buffer, |
| 2275 | the cursor will be positioned at the last line in the buffer. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2276 | If {col} is greater than the number of bytes in the line, |
| 2277 | the cursor will be positioned at the last character in the |
| 2278 | line. |
| 2279 | If {col} is zero, the cursor will stay in the current column. |
| 2280 | If {curswant} is given it is used to set the preferred column |
| 2281 | for vertical movement. Otherwise {col} is used. |
| 2282 | |
| 2283 | When 'virtualedit' is used {off} specifies the offset in |
| 2284 | screen columns from the start of the character. E.g., a |
| 2285 | position within a <Tab> or after the last character. |
| 2286 | Returns 0 when the position could be set, -1 otherwise. |
| 2287 | |
| 2288 | Can also be used as a |method|: > |
| 2289 | GetCursorPos()->cursor() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2290 | < |
| 2291 | Return type: |Number| |
| 2292 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2293 | |
| 2294 | debugbreak({pid}) *debugbreak()* |
| 2295 | Specifically used to interrupt a program being debugged. It |
| 2296 | will cause process {pid} to get a SIGTRAP. Behavior for other |
| 2297 | processes is undefined. See |terminal-debugger|. |
| 2298 | {only available on MS-Windows} |
| 2299 | |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 2300 | Returns |TRUE| if successfully interrupted the program. |
| 2301 | Otherwise returns |FALSE|. |
| 2302 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2303 | Can also be used as a |method|: > |
| 2304 | GetPid()->debugbreak() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2305 | < |
| 2306 | Return type: |Number| |
| 2307 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2308 | |
| 2309 | deepcopy({expr} [, {noref}]) *deepcopy()* *E698* |
| 2310 | Make a copy of {expr}. For Numbers and Strings this isn't |
| 2311 | different from using {expr} directly. |
| 2312 | When {expr} is a |List| a full copy is created. This means |
| 2313 | that the original |List| can be changed without changing the |
| 2314 | copy, and vice versa. When an item is a |List| or |
| 2315 | |Dictionary|, a copy for it is made, recursively. Thus |
| 2316 | changing an item in the copy does not change the contents of |
| 2317 | the original |List|. |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 2318 | A |Tuple| or |Dictionary| is copied in a similar way as a |
| 2319 | |List|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2320 | |
| 2321 | When {noref} is omitted or zero a contained |List| or |
| 2322 | |Dictionary| is only copied once. All references point to |
| 2323 | this single copy. With {noref} set to 1 every occurrence of a |
| 2324 | |List| or |Dictionary| results in a new copy. This also means |
| 2325 | that a cyclic reference causes deepcopy() to fail. |
| 2326 | *E724* |
| 2327 | Nesting is possible up to 100 levels. When there is an item |
| 2328 | that refers back to a higher level making a deep copy with |
| 2329 | {noref} set to 1 will fail. |
| 2330 | Also see |copy()|. |
| 2331 | |
| 2332 | Can also be used as a |method|: > |
| 2333 | GetObject()->deepcopy() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2334 | < |
| 2335 | Return type: any, depending on {expr} |
| 2336 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2337 | |
| 2338 | delete({fname} [, {flags}]) *delete()* |
| 2339 | Without {flags} or with {flags} empty: Deletes the file by the |
Bram Moolenaar | cbaff5e | 2022-04-08 17:45:08 +0100 | [diff] [blame] | 2340 | name {fname}. |
| 2341 | |
| 2342 | This also works when {fname} is a symbolic link. The symbolic |
| 2343 | link itself is deleted, not what it points to. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2344 | |
| 2345 | When {flags} is "d": Deletes the directory by the name |
| 2346 | {fname}. This fails when directory {fname} is not empty. |
| 2347 | |
| 2348 | When {flags} is "rf": Deletes the directory by the name |
| 2349 | {fname} and everything in it, recursively. BE CAREFUL! |
| 2350 | Note: on MS-Windows it is not possible to delete a directory |
| 2351 | that is being used. |
| 2352 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2353 | The result is a Number, which is 0/false if the delete |
| 2354 | operation was successful and -1/true when the deletion failed |
| 2355 | or partly failed. |
| 2356 | |
| 2357 | Use |remove()| to delete an item from a |List|. |
| 2358 | To delete a line from the buffer use |:delete| or |
| 2359 | |deletebufline()|. |
| 2360 | |
| 2361 | Can also be used as a |method|: > |
| 2362 | GetName()->delete() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2363 | < |
| 2364 | Return type: |Number| |
| 2365 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2366 | |
| 2367 | deletebufline({buf}, {first} [, {last}]) *deletebufline()* |
| 2368 | Delete lines {first} to {last} (inclusive) from buffer {buf}. |
| 2369 | If {last} is omitted then delete line {first} only. |
| 2370 | On success 0 is returned, on failure 1 is returned. |
| 2371 | |
| 2372 | This function works only for loaded buffers. First call |
| 2373 | |bufload()| if needed. |
| 2374 | |
| 2375 | For the use of {buf}, see |bufname()| above. |
| 2376 | |
| 2377 | {first} and {last} are used like with |getline()|. Note that |
| 2378 | when using |line()| this refers to the current buffer. Use "$" |
| 2379 | to refer to the last line in buffer {buf}. |
| 2380 | |
| 2381 | Can also be used as a |method|: > |
| 2382 | GetBuffer()->deletebufline(1) |
| 2383 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2384 | Return type: |Number| |
| 2385 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2386 | *did_filetype()* |
| 2387 | did_filetype() Returns |TRUE| when autocommands are being executed and the |
| 2388 | FileType event has been triggered at least once. Can be used |
| 2389 | to avoid triggering the FileType event again in the scripts |
| 2390 | that detect the file type. |FileType| |
| 2391 | Returns |FALSE| when `:setf FALLBACK` was used. |
| 2392 | When editing another file, the counter is reset, thus this |
| 2393 | really checks if the FileType event has been triggered for the |
| 2394 | current buffer. This allows an autocommand that starts |
| 2395 | editing another buffer to set 'filetype' and load a syntax |
| 2396 | file. |
| 2397 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2398 | Return type: |Number| |
| 2399 | |
| 2400 | |
Yegappan Lakshmanan | fa37835 | 2024-02-01 22:05:27 +0100 | [diff] [blame] | 2401 | diff({fromlist}, {tolist} [, {options}]) *diff()* |
| 2402 | Returns a String or a List containing the diff between the |
| 2403 | strings in {fromlist} and {tolist}. Uses the Vim internal |
| 2404 | diff library to compute the diff. |
| 2405 | |
| 2406 | *E106* |
| 2407 | The optional "output" item in {options} specifies the returned |
| 2408 | diff format. The following values are supported: |
| 2409 | indices Return a List of the starting and ending |
| 2410 | indices and a count of the strings in each |
| 2411 | diff hunk. |
| 2412 | unified Return the unified diff output as a String. |
| 2413 | This is the default. |
| 2414 | |
| 2415 | If the "output" item in {options} is "indices", then a List is |
| 2416 | returned. Each List item contains a Dict with the following |
| 2417 | items for each diff hunk: |
| 2418 | from_idx start index in {fromlist} for this diff hunk. |
| 2419 | from_count number of strings in {fromlist} that are |
| 2420 | added/removed/modified in this diff hunk. |
| 2421 | to_idx start index in {tolist} for this diff hunk. |
| 2422 | to_count number of strings in {tolist} that are |
| 2423 | added/removed/modified in this diff hunk. |
| 2424 | |
| 2425 | The {options} Dict argument also specifies diff options |
| 2426 | (similar to 'diffopt') and supports the following items: |
Yegappan Lakshmanan | be156a3 | 2024-02-11 17:08:29 +0100 | [diff] [blame] | 2427 | algorithm Dict specifying the diff algorithm to |
| 2428 | use. Supported boolean items are |
| 2429 | "myers", "minimal", "patience" and |
| 2430 | "histogram". |
Yegappan Lakshmanan | a0010a1 | 2024-02-12 20:21:26 +0100 | [diff] [blame] | 2431 | context diff context length. Default is 0. |
Yegappan Lakshmanan | fa37835 | 2024-02-01 22:05:27 +0100 | [diff] [blame] | 2432 | iblank ignore changes where lines are all |
| 2433 | blank. |
| 2434 | icase ignore changes in case of text. |
Yegappan Lakshmanan | be156a3 | 2024-02-11 17:08:29 +0100 | [diff] [blame] | 2435 | indent-heuristic use the indent heuristic for the |
| 2436 | internal diff library. |
Yegappan Lakshmanan | fa37835 | 2024-02-01 22:05:27 +0100 | [diff] [blame] | 2437 | iwhite ignore changes in amount of white |
| 2438 | space. |
| 2439 | iwhiteall ignore all white space changes. |
| 2440 | iwhiteeol ignore white space changes at end of |
| 2441 | line. |
Yegappan Lakshmanan | fa37835 | 2024-02-01 22:05:27 +0100 | [diff] [blame] | 2442 | For more information about these options, refer to 'diffopt'. |
| 2443 | |
Yegappan Lakshmanan | a0010a1 | 2024-02-12 20:21:26 +0100 | [diff] [blame] | 2444 | To compute the unified diff, all the items in {fromlist} are |
| 2445 | concatenated into a string using a newline separator and the |
| 2446 | same for {tolist}. The unified diff output uses line numbers. |
| 2447 | |
Yegappan Lakshmanan | fa37835 | 2024-02-01 22:05:27 +0100 | [diff] [blame] | 2448 | Returns an empty List or String if {fromlist} and {tolist} are |
| 2449 | identical. |
| 2450 | |
Yegappan Lakshmanan | 1af3563 | 2024-02-06 11:03:36 +0100 | [diff] [blame] | 2451 | Examples: > |
Yegappan Lakshmanan | fa37835 | 2024-02-01 22:05:27 +0100 | [diff] [blame] | 2452 | :echo diff(['abc'], ['xxx']) |
| 2453 | @@ -1 +1 @@ |
| 2454 | -abc |
| 2455 | +xxx |
| 2456 | |
| 2457 | :echo diff(['abc'], ['xxx'], {'output': 'indices'}) |
| 2458 | [{'from_idx': 0, 'from_count': 1, 'to_idx': 0, 'to_count': 1}] |
| 2459 | :echo diff(readfile('oldfile'), readfile('newfile')) |
| 2460 | :echo diff(getbufline(5, 1, '$'), getbufline(6, 1, '$')) |
Yegappan Lakshmanan | 1af3563 | 2024-02-06 11:03:36 +0100 | [diff] [blame] | 2461 | < |
Yegappan Lakshmanan | fa37835 | 2024-02-01 22:05:27 +0100 | [diff] [blame] | 2462 | For more examples, refer to |diff-func-examples| |
| 2463 | |
| 2464 | Can also be used as a |method|: > |
| 2465 | GetFromList->diff(to_list) |
| 2466 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2467 | Return type: |String| or list<dict<number>> or list<any> |
| 2468 | depending on {options} |
| 2469 | |
| 2470 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2471 | diff_filler({lnum}) *diff_filler()* |
| 2472 | Returns the number of filler lines above line {lnum}. |
| 2473 | These are the lines that were inserted at this point in |
| 2474 | another diff'ed window. These filler lines are shown in the |
| 2475 | display but don't exist in the buffer. |
| 2476 | {lnum} is used like with |getline()|. Thus "." is the current |
| 2477 | line, "'m" mark m, etc. |
| 2478 | Returns 0 if the current window is not in diff mode. |
| 2479 | |
| 2480 | Can also be used as a |method|: > |
| 2481 | GetLnum()->diff_filler() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2482 | < |
| 2483 | Return type: |Number| |
| 2484 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2485 | |
| 2486 | diff_hlID({lnum}, {col}) *diff_hlID()* |
| 2487 | Returns the highlight ID for diff mode at line {lnum} column |
| 2488 | {col} (byte index). When the current line does not have a |
| 2489 | diff change zero is returned. |
| 2490 | {lnum} is used like with |getline()|. Thus "." is the current |
| 2491 | line, "'m" mark m, etc. |
| 2492 | {col} is 1 for the leftmost column, {lnum} is 1 for the first |
| 2493 | line. |
| 2494 | The highlight ID can be used with |synIDattr()| to obtain |
| 2495 | syntax information about the highlighting. |
| 2496 | |
| 2497 | Can also be used as a |method|: > |
| 2498 | GetLnum()->diff_hlID(col) |
| 2499 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2500 | Return type: |Number| |
| 2501 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2502 | |
| 2503 | digraph_get({chars}) *digraph_get()* *E1214* |
| 2504 | Return the digraph of {chars}. This should be a string with |
| 2505 | exactly two characters. If {chars} are not just two |
| 2506 | characters, or the digraph of {chars} does not exist, an error |
| 2507 | is given and an empty string is returned. |
| 2508 | |
| 2509 | The character will be converted from Unicode to 'encoding' |
| 2510 | when needed. This does require the conversion to be |
| 2511 | available, it might fail. |
| 2512 | |
| 2513 | Also see |digraph_getlist()|. |
| 2514 | |
| 2515 | Examples: > |
| 2516 | " Get a built-in digraph |
| 2517 | :echo digraph_get('00') " Returns '∞' |
| 2518 | |
| 2519 | " Get a user-defined digraph |
| 2520 | :call digraph_set('aa', 'あ') |
| 2521 | :echo digraph_get('aa') " Returns 'あ' |
| 2522 | < |
| 2523 | Can also be used as a |method|: > |
| 2524 | GetChars()->digraph_get() |
| 2525 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2526 | Return type: |String| |
| 2527 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2528 | This function works only when compiled with the |+digraphs| |
| 2529 | feature. If this feature is disabled, this function will |
| 2530 | display an error message. |
| 2531 | |
| 2532 | |
| 2533 | digraph_getlist([{listall}]) *digraph_getlist()* |
| 2534 | Return a list of digraphs. If the {listall} argument is given |
| 2535 | and it is TRUE, return all digraphs, including the default |
| 2536 | digraphs. Otherwise, return only user-defined digraphs. |
| 2537 | |
| 2538 | The characters will be converted from Unicode to 'encoding' |
| 2539 | when needed. This does require the conservation to be |
| 2540 | available, it might fail. |
| 2541 | |
| 2542 | Also see |digraph_get()|. |
| 2543 | |
| 2544 | Examples: > |
| 2545 | " Get user-defined digraphs |
| 2546 | :echo digraph_getlist() |
| 2547 | |
| 2548 | " Get all the digraphs, including default digraphs |
| 2549 | :echo digraph_getlist(1) |
| 2550 | < |
| 2551 | Can also be used as a |method|: > |
| 2552 | GetNumber()->digraph_getlist() |
| 2553 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2554 | Return type: list<list<string>> |
| 2555 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2556 | This function works only when compiled with the |+digraphs| |
| 2557 | feature. If this feature is disabled, this function will |
| 2558 | display an error message. |
| 2559 | |
| 2560 | |
Bram Moolenaar | a2baa73 | 2022-02-04 16:09:54 +0000 | [diff] [blame] | 2561 | digraph_set({chars}, {digraph}) *digraph_set()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2562 | Add digraph {chars} to the list. {chars} must be a string |
| 2563 | with two characters. {digraph} is a string with one UTF-8 |
Bram Moolenaar | a2baa73 | 2022-02-04 16:09:54 +0000 | [diff] [blame] | 2564 | encoded character. *E1215* |
| 2565 | Be careful, composing characters are NOT ignored. This |
| 2566 | function is similar to |:digraphs| command, but useful to add |
| 2567 | digraphs start with a white space. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2568 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2569 | The function returns v:true if |digraph| is registered. If |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2570 | this fails an error message is given and v:false is returned. |
| 2571 | |
| 2572 | If you want to define multiple digraphs at once, you can use |
| 2573 | |digraph_setlist()|. |
| 2574 | |
| 2575 | Example: > |
| 2576 | call digraph_set(' ', 'あ') |
| 2577 | < |
| 2578 | Can be used as a |method|: > |
| 2579 | GetString()->digraph_set('あ') |
| 2580 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2581 | Return type: |vim9-boolean| |
| 2582 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2583 | This function works only when compiled with the |+digraphs| |
| 2584 | feature. If this feature is disabled, this function will |
| 2585 | display an error message. |
| 2586 | |
| 2587 | |
| 2588 | digraph_setlist({digraphlist}) *digraph_setlist()* |
| 2589 | Similar to |digraph_set()| but this function can add multiple |
| 2590 | digraphs at once. {digraphlist} is a list composed of lists, |
| 2591 | where each list contains two strings with {chars} and |
Bram Moolenaar | a2baa73 | 2022-02-04 16:09:54 +0000 | [diff] [blame] | 2592 | {digraph} as in |digraph_set()|. *E1216* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2593 | Example: > |
| 2594 | call digraph_setlist([['aa', 'あ'], ['ii', 'い']]) |
| 2595 | < |
| 2596 | It is similar to the following: > |
| 2597 | for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']] |
| 2598 | call digraph_set(chars, digraph) |
| 2599 | endfor |
| 2600 | < Except that the function returns after the first error, |
| 2601 | following digraphs will not be added. |
| 2602 | |
| 2603 | Can be used as a |method|: > |
| 2604 | GetList()->digraph_setlist() |
| 2605 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2606 | Return type: |vim9-boolean| |
| 2607 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2608 | This function works only when compiled with the |+digraphs| |
| 2609 | feature. If this feature is disabled, this function will |
| 2610 | display an error message. |
| 2611 | |
| 2612 | |
| 2613 | echoraw({string}) *echoraw()* |
| 2614 | Output {string} as-is, including unprintable characters. |
| 2615 | This can be used to output a terminal code. For example, to |
| 2616 | disable modifyOtherKeys: > |
| 2617 | call echoraw(&t_TE) |
| 2618 | < and to enable it again: > |
| 2619 | call echoraw(&t_TI) |
| 2620 | < Use with care, you can mess up the terminal this way. |
| 2621 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2622 | Return type: |Number| |
| 2623 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2624 | |
| 2625 | empty({expr}) *empty()* |
| 2626 | Return the Number 1 if {expr} is empty, zero otherwise. |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 2627 | - A |List|, |Tuple| or |Dictionary| is empty when it does |
| 2628 | not have any items. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2629 | - A |String| is empty when its length is zero. |
| 2630 | - A |Number| and |Float| are empty when their value is zero. |
| 2631 | - |v:false|, |v:none| and |v:null| are empty, |v:true| is not. |
| 2632 | - A |Job| is empty when it failed to start. |
| 2633 | - A |Channel| is empty when it is closed. |
| 2634 | - A |Blob| is empty when its length is zero. |
mityu | 7f0bba2 | 2024-03-29 10:14:41 +0100 | [diff] [blame] | 2635 | - An |Object| is empty, when the empty() method in the object |
| 2636 | (if present) returns true. |object-empty()| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2637 | |
| 2638 | For a long |List| this is much faster than comparing the |
| 2639 | length with zero. |
| 2640 | |
| 2641 | Can also be used as a |method|: > |
| 2642 | mylist->empty() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2643 | < |
| 2644 | Return type: |Number| |
| 2645 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2646 | |
| 2647 | environ() *environ()* |
| 2648 | Return all of environment variables as dictionary. You can |
| 2649 | check if an environment variable exists like this: > |
| 2650 | :echo has_key(environ(), 'HOME') |
| 2651 | < Note that the variable name may be CamelCase; to ignore case |
| 2652 | use this: > |
| 2653 | :echo index(keys(environ()), 'HOME', 0, 1) != -1 |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2654 | < |
| 2655 | Return type: dict<string> |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2656 | |
Bram Moolenaar | 416bd91 | 2023-07-07 23:19:18 +0100 | [diff] [blame] | 2657 | |
| 2658 | err_teapot([{expr}]) *err_teapot()* |
| 2659 | Produce an error with number 418, needed for implementation of |
Christian Brabandt | ee17b6f | 2023-09-09 11:23:50 +0200 | [diff] [blame] | 2660 | RFC 2324. |
Bram Moolenaar | 416bd91 | 2023-07-07 23:19:18 +0100 | [diff] [blame] | 2661 | If {expr} is present and it is TRUE error 503 is given, |
| 2662 | indicating that coffee is temporarily not available. |
| 2663 | If {expr} is present it must be a String. |
| 2664 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2665 | Return type: |Number| |
| 2666 | |
Bram Moolenaar | 416bd91 | 2023-07-07 23:19:18 +0100 | [diff] [blame] | 2667 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2668 | escape({string}, {chars}) *escape()* |
| 2669 | Escape the characters in {chars} that occur in {string} with a |
| 2670 | backslash. Example: > |
| 2671 | :echo escape('c:\program files\vim', ' \') |
| 2672 | < results in: > |
| 2673 | c:\\program\ files\\vim |
| 2674 | < Also see |shellescape()| and |fnameescape()|. |
| 2675 | |
| 2676 | Can also be used as a |method|: > |
| 2677 | GetText()->escape(' \') |
| 2678 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2679 | Return type: |String| |
| 2680 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2681 | *eval()* |
| 2682 | eval({string}) Evaluate {string} and return the result. Especially useful to |
| 2683 | turn the result of |string()| back into the original value. |
| 2684 | This works for Numbers, Floats, Strings, Blobs and composites |
| 2685 | of them. Also works for |Funcref|s that refer to existing |
Aliaksei Budavei | 9574022 | 2024-04-04 23:05:33 +0300 | [diff] [blame] | 2686 | functions. In |Vim9| script, it can be used to obtain |enum| |
| 2687 | values from their fully qualified names. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2688 | |
| 2689 | Can also be used as a |method|: > |
| 2690 | argv->join()->eval() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2691 | < |
| 2692 | Return type: any, depending on {string} |
| 2693 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2694 | |
| 2695 | eventhandler() *eventhandler()* |
| 2696 | Returns 1 when inside an event handler. That is that Vim got |
| 2697 | interrupted while waiting for the user to type a character, |
| 2698 | e.g., when dropping a file on Vim. This means interactive |
| 2699 | commands cannot be used. Otherwise zero is returned. |
| 2700 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2701 | Return type: |Number| |
| 2702 | |
| 2703 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2704 | executable({expr}) *executable()* |
| 2705 | This function checks if an executable with the name {expr} |
| 2706 | exists. {expr} must be the name of the program without any |
| 2707 | arguments. |
zeertzjq | 0cc5dce | 2024-08-08 21:12:15 +0200 | [diff] [blame] | 2708 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2709 | executable() uses the value of $PATH and/or the normal |
zeertzjq | 0cc5dce | 2024-08-08 21:12:15 +0200 | [diff] [blame] | 2710 | searchpath for programs. |
| 2711 | *PATHEXT* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2712 | On MS-Windows the ".exe", ".bat", etc. can optionally be |
| 2713 | included. Then the extensions in $PATHEXT are tried. Thus if |
| 2714 | "foo.exe" does not exist, "foo.exe.bat" can be found. If |
| 2715 | $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot |
| 2716 | by itself can be used in $PATHEXT to try using the name |
| 2717 | without an extension. When 'shell' looks like a Unix shell, |
| 2718 | then the name is also tried without adding an extension. |
| 2719 | On MS-Windows it only checks if the file exists and is not a |
| 2720 | directory, not if it's really executable. |
zeertzjq | 0cc5dce | 2024-08-08 21:12:15 +0200 | [diff] [blame] | 2721 | On MS-Windows an executable in the same directory as the Vim |
| 2722 | executable is always found. Since this directory is added to |
| 2723 | $PATH it should also work to execute it |win32-PATH|. |
| 2724 | *NoDefaultCurrentDirectoryInExePath* |
| 2725 | On MS-Windows an executable in Vim's current working directory |
| 2726 | is also normally found, but this can be disabled by setting |
| 2727 | the $NoDefaultCurrentDirectoryInExePath environment variable. |
| 2728 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2729 | The result is a Number: |
| 2730 | 1 exists |
| 2731 | 0 does not exist |
| 2732 | -1 not implemented on this system |
| 2733 | |exepath()| can be used to get the full path of an executable. |
| 2734 | |
| 2735 | Can also be used as a |method|: > |
| 2736 | GetCommand()->executable() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2737 | < |
| 2738 | Return type: |Number| |
| 2739 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2740 | |
| 2741 | execute({command} [, {silent}]) *execute()* |
| 2742 | Execute an Ex command or commands and return the output as a |
| 2743 | string. |
| 2744 | {command} can be a string or a List. In case of a List the |
| 2745 | lines are executed one by one. |
Bram Moolenaar | b7398fe | 2023-05-14 18:50:25 +0100 | [diff] [blame] | 2746 | This is more or less equivalent to: > |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2747 | redir => var |
| 2748 | {command} |
| 2749 | redir END |
Bram Moolenaar | 71badf9 | 2023-04-22 22:40:14 +0100 | [diff] [blame] | 2750 | < Except that line continuation in {command} is not recognized. |
| 2751 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2752 | The optional {silent} argument can have these values: |
| 2753 | "" no `:silent` used |
| 2754 | "silent" `:silent` used |
| 2755 | "silent!" `:silent!` used |
| 2756 | The default is "silent". Note that with "silent!", unlike |
| 2757 | `:redir`, error messages are dropped. When using an external |
| 2758 | command the screen may be messed up, use `system()` instead. |
| 2759 | *E930* |
| 2760 | It is not possible to use `:redir` anywhere in {command}. |
| 2761 | |
Bram Moolenaar | b7398fe | 2023-05-14 18:50:25 +0100 | [diff] [blame] | 2762 | To get a list of lines use `split()` on the result: > |
Bram Moolenaar | 75ab590 | 2022-04-18 15:36:40 +0100 | [diff] [blame] | 2763 | execute('args')->split("\n") |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2764 | |
| 2765 | < To execute a command in another window than the current one |
| 2766 | use `win_execute()`. |
| 2767 | |
| 2768 | When used recursively the output of the recursive call is not |
| 2769 | included in the output of the higher level call. |
| 2770 | |
| 2771 | Can also be used as a |method|: > |
| 2772 | GetCommand()->execute() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2773 | < |
Marius Gedminas | c98bfb9 | 2024-06-19 19:59:23 +0200 | [diff] [blame] | 2774 | Return type: |String| |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2775 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2776 | |
| 2777 | exepath({expr}) *exepath()* |
| 2778 | If {expr} is an executable and is either an absolute path, a |
| 2779 | relative path or found in $PATH, return the full path. |
| 2780 | Note that the current directory is used when {expr} starts |
| 2781 | with "./", which may be a problem for Vim: > |
| 2782 | echo exepath(v:progpath) |
| 2783 | < If {expr} cannot be found in $PATH or is not executable then |
| 2784 | an empty string is returned. |
| 2785 | |
| 2786 | Can also be used as a |method|: > |
| 2787 | GetCommand()->exepath() |
| 2788 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2789 | Return type: |String| |
| 2790 | |
| 2791 | |
| 2792 | exists({expr}) *exists()* |
| 2793 | The result is a Number, which is |TRUE| if {expr} is defined, |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2794 | zero otherwise. |
| 2795 | |
| 2796 | Note: In a compiled |:def| function the evaluation is done at |
| 2797 | runtime. Use `exists_compiled()` to evaluate the expression |
| 2798 | at compile time. |
| 2799 | |
| 2800 | For checking for a supported feature use |has()|. |
| 2801 | For checking if a file exists use |filereadable()|. |
| 2802 | |
| 2803 | The {expr} argument is a string, which contains one of these: |
Bram Moolenaar | f10911e | 2022-01-29 22:20:48 +0000 | [diff] [blame] | 2804 | varname internal variable (see |
| 2805 | dict.key |internal-variables|). Also works |
| 2806 | list[i] for |curly-braces-names|, |Dictionary| |
Yegappan Lakshmanan | a2ebb6e | 2024-02-25 08:40:10 +0100 | [diff] [blame] | 2807 | import.Func entries, |List| items, class and |
| 2808 | class.Func object methods, imported items, etc. |
| 2809 | object.Func Does not work for local variables in a |
| 2810 | class.varname compiled `:def` function. |
| 2811 | object.varname Also works for a function in |Vim9| |
Bram Moolenaar | 944697a | 2022-02-20 19:48:20 +0000 | [diff] [blame] | 2812 | script, since it can be used as a |
| 2813 | function reference. |
Bram Moolenaar | f10911e | 2022-01-29 22:20:48 +0000 | [diff] [blame] | 2814 | Beware that evaluating an index may |
| 2815 | cause an error message for an invalid |
| 2816 | expression. E.g.: > |
| 2817 | :let l = [1, 2, 3] |
| 2818 | :echo exists("l[5]") |
| 2819 | < 0 > |
| 2820 | :echo exists("l[xx]") |
| 2821 | < E121: Undefined variable: xx |
| 2822 | 0 |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2823 | &option-name Vim option (only checks if it exists, |
| 2824 | not if it really works) |
| 2825 | +option-name Vim option that works. |
| 2826 | $ENVNAME environment variable (could also be |
| 2827 | done by comparing with an empty |
| 2828 | string) |
| 2829 | *funcname built-in function (see |functions|) |
| 2830 | or user defined function (see |
| 2831 | |user-functions|) that is implemented. |
| 2832 | Also works for a variable that is a |
| 2833 | Funcref. |
| 2834 | ?funcname built-in function that could be |
| 2835 | implemented; to be used to check if |
| 2836 | "funcname" is valid |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2837 | :cmdname Ex command: built-in command, user |
| 2838 | command or command modifier |:command|. |
| 2839 | Returns: |
| 2840 | 1 for match with start of a command |
| 2841 | 2 full match with a command |
| 2842 | 3 matches several user commands |
| 2843 | To check for a supported command |
| 2844 | always check the return value to be 2. |
| 2845 | :2match The |:2match| command. |
Bram Moolenaar | b529cfb | 2022-07-25 15:42:07 +0100 | [diff] [blame] | 2846 | :3match The |:3match| command (but you |
| 2847 | probably should not use it, it is |
| 2848 | reserved for internal usage) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2849 | #event autocommand defined for this event |
| 2850 | #event#pattern autocommand defined for this event and |
| 2851 | pattern (the pattern is taken |
| 2852 | literally and compared to the |
| 2853 | autocommand patterns character by |
| 2854 | character) |
| 2855 | #group autocommand group exists |
| 2856 | #group#event autocommand defined for this group and |
| 2857 | event. |
| 2858 | #group#event#pattern |
| 2859 | autocommand defined for this group, |
| 2860 | event and pattern. |
| 2861 | ##event autocommand for this event is |
| 2862 | supported. |
| 2863 | |
| 2864 | Examples: > |
| 2865 | exists("&shortname") |
| 2866 | exists("$HOSTNAME") |
| 2867 | exists("*strftime") |
Bram Moolenaar | 944697a | 2022-02-20 19:48:20 +0000 | [diff] [blame] | 2868 | exists("*s:MyFunc") " only for legacy script |
| 2869 | exists("*MyFunc") |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2870 | exists("bufcount") |
| 2871 | exists(":Make") |
| 2872 | exists("#CursorHold") |
| 2873 | exists("#BufReadPre#*.gz") |
| 2874 | exists("#filetypeindent") |
| 2875 | exists("#filetypeindent#FileType") |
| 2876 | exists("#filetypeindent#FileType#*") |
| 2877 | exists("##ColorScheme") |
| 2878 | < There must be no space between the symbol (&/$/*/#) and the |
| 2879 | name. |
| 2880 | There must be no extra characters after the name, although in |
Bram Moolenaar | 2d8ed02 | 2022-05-21 13:08:16 +0100 | [diff] [blame] | 2881 | a few cases this is ignored. That may become stricter in the |
| 2882 | future, thus don't count on it! |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2883 | Working example: > |
| 2884 | exists(":make") |
| 2885 | < NOT working example: > |
| 2886 | exists(":make install") |
| 2887 | |
| 2888 | < Note that the argument must be a string, not the name of the |
| 2889 | variable itself. For example: > |
| 2890 | exists(bufcount) |
| 2891 | < This doesn't check for existence of the "bufcount" variable, |
| 2892 | but gets the value of "bufcount", and checks if that exists. |
| 2893 | |
| 2894 | Can also be used as a |method|: > |
| 2895 | Varname()->exists() |
| 2896 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2897 | Return type: |String| |
| 2898 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2899 | |
| 2900 | exists_compiled({expr}) *exists_compiled()* |
| 2901 | Like `exists()` but evaluated at compile time. This is useful |
| 2902 | to skip a block where a function is used that would otherwise |
| 2903 | give an error: > |
| 2904 | if exists_compiled('*ThatFunction') |
| 2905 | ThatFunction('works') |
| 2906 | endif |
| 2907 | < If `exists()` were used then a compilation error would be |
| 2908 | given if ThatFunction() is not defined. |
| 2909 | |
| 2910 | {expr} must be a literal string. *E1232* |
| 2911 | Can only be used in a |:def| function. *E1233* |
| 2912 | This does not work to check for arguments or local variables. |
| 2913 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2914 | Return type: |String| |
| 2915 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2916 | |
| 2917 | exp({expr}) *exp()* |
| 2918 | Return the exponential of {expr} as a |Float| in the range |
| 2919 | [0, inf]. |
| 2920 | {expr} must evaluate to a |Float| or a |Number|. |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 2921 | Returns 0.0 if {expr} is not a |Float| or a |Number|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2922 | Examples: > |
| 2923 | :echo exp(2) |
| 2924 | < 7.389056 > |
| 2925 | :echo exp(-1) |
| 2926 | < 0.367879 |
| 2927 | |
| 2928 | Can also be used as a |method|: > |
| 2929 | Compute()->exp() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 2930 | < |
| 2931 | Return type: |Float| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2932 | |
| 2933 | |
| 2934 | expand({string} [, {nosuf} [, {list}]]) *expand()* |
| 2935 | Expand wildcards and the following special keywords in |
| 2936 | {string}. 'wildignorecase' applies. |
| 2937 | |
| 2938 | If {list} is given and it is |TRUE|, a List will be returned. |
| 2939 | Otherwise the result is a String and when there are several |
| 2940 | matches, they are separated by <NL> characters. [Note: in |
| 2941 | version 5.0 a space was used, which caused problems when a |
| 2942 | file name contains a space] |
| 2943 | |
| 2944 | If the expansion fails, the result is an empty string. A name |
| 2945 | for a non-existing file is not included, unless {string} does |
| 2946 | not start with '%', '#' or '<', see below. |
| 2947 | |
Christian Brabandt | ec9c326 | 2024-02-21 20:40:05 +0100 | [diff] [blame] | 2948 | For a |:terminal| window '%' expands to a '!' followed by |
h-east | 53753f6 | 2024-05-05 18:42:31 +0200 | [diff] [blame] | 2949 | the command or shell that is run. |terminal-bufname| |
Christian Brabandt | ec9c326 | 2024-02-21 20:40:05 +0100 | [diff] [blame] | 2950 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2951 | When {string} starts with '%', '#' or '<', the expansion is |
| 2952 | done like for the |cmdline-special| variables with their |
| 2953 | associated modifiers. Here is a short overview: |
| 2954 | |
| 2955 | % current file name |
| 2956 | # alternate file name |
| 2957 | #n alternate file name n |
| 2958 | <cfile> file name under the cursor |
| 2959 | <afile> autocmd file name |
| 2960 | <abuf> autocmd buffer number (as a String!) |
| 2961 | <amatch> autocmd matched name |
| 2962 | <cexpr> C expression under the cursor |
| 2963 | <sfile> sourced script file or function name |
| 2964 | <slnum> sourced script line number or function |
| 2965 | line number |
| 2966 | <sflnum> script file line number, also when in |
| 2967 | a function |
| 2968 | <SID> "<SNR>123_" where "123" is the |
| 2969 | current script ID |<SID>| |
Bram Moolenaar | 75ab590 | 2022-04-18 15:36:40 +0100 | [diff] [blame] | 2970 | <script> sourced script file, or script file |
| 2971 | where the current function was defined |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2972 | <stack> call stack |
| 2973 | <cword> word under the cursor |
| 2974 | <cWORD> WORD under the cursor |
| 2975 | <client> the {clientid} of the last received |
| 2976 | message |server2client()| |
| 2977 | Modifiers: |
| 2978 | :p expand to full path |
| 2979 | :h head (last path component removed) |
| 2980 | :t tail (last path component only) |
| 2981 | :r root (one extension removed) |
| 2982 | :e extension only |
| 2983 | |
| 2984 | Example: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 2985 | :let &tags = expand("%:p:h") .. "/tags" |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2986 | < Note that when expanding a string that starts with '%', '#' or |
| 2987 | '<', any following text is ignored. This does NOT work: > |
| 2988 | :let doesntwork = expand("%:h.bak") |
| 2989 | < Use this: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 2990 | :let doeswork = expand("%:h") .. ".bak" |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 2991 | < Also note that expanding "<cfile>" and others only returns the |
| 2992 | referenced file name without further expansion. If "<cfile>" |
| 2993 | is "~/.cshrc", you need to do another expand() to have the |
| 2994 | "~/" expanded into the path of the home directory: > |
| 2995 | :echo expand(expand("<cfile>")) |
| 2996 | < |
| 2997 | There cannot be white space between the variables and the |
| 2998 | following modifier. The |fnamemodify()| function can be used |
| 2999 | to modify normal file names. |
| 3000 | |
| 3001 | When using '%' or '#', and the current or alternate file name |
| 3002 | is not defined, an empty string is used. Using "%:p" in a |
| 3003 | buffer with no name, results in the current directory, with a |
| 3004 | '/' added. |
Bram Moolenaar | 5754452 | 2022-04-12 12:54:11 +0100 | [diff] [blame] | 3005 | When 'verbose' is set then expanding '%', '#' and <> items |
| 3006 | will result in an error message if the argument cannot be |
| 3007 | expanded. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3008 | |
| 3009 | When {string} does not start with '%', '#' or '<', it is |
| 3010 | expanded like a file name is expanded on the command line. |
| 3011 | 'suffixes' and 'wildignore' are used, unless the optional |
| 3012 | {nosuf} argument is given and it is |TRUE|. |
| 3013 | Names for non-existing files are included. The "**" item can |
| 3014 | be used to search in a directory tree. For example, to find |
| 3015 | all "README" files in the current directory and below: > |
| 3016 | :echo expand("**/README") |
| 3017 | < |
| 3018 | expand() can also be used to expand variables and environment |
| 3019 | variables that are only known in a shell. But this can be |
| 3020 | slow, because a shell may be used to do the expansion. See |
| 3021 | |expr-env-expand|. |
| 3022 | The expanded variable is still handled like a list of file |
| 3023 | names. When an environment variable cannot be expanded, it is |
| 3024 | left unchanged. Thus ":echo expand('$FOOBAR')" results in |
| 3025 | "$FOOBAR". |
| 3026 | |
| 3027 | See |glob()| for finding existing files. See |system()| for |
| 3028 | getting the raw output of an external command. |
| 3029 | |
| 3030 | Can also be used as a |method|: > |
| 3031 | Getpattern()->expand() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3032 | < |
| 3033 | Return type: |String| or list<string> depending on {list} |
| 3034 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3035 | |
Yegappan Lakshmanan | 2b74b68 | 2022-04-03 21:30:32 +0100 | [diff] [blame] | 3036 | expandcmd({string} [, {options}]) *expandcmd()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3037 | Expand special items in String {string} like what is done for |
| 3038 | an Ex command such as `:edit`. This expands special keywords, |
| 3039 | like with |expand()|, and environment variables, anywhere in |
| 3040 | {string}. "~user" and "~/path" are only expanded at the |
| 3041 | start. |
Yegappan Lakshmanan | 2b74b68 | 2022-04-03 21:30:32 +0100 | [diff] [blame] | 3042 | |
| 3043 | The following items are supported in the {options} Dict |
| 3044 | argument: |
| 3045 | errmsg If set to TRUE, error messages are displayed |
| 3046 | if an error is encountered during expansion. |
| 3047 | By default, error messages are not displayed. |
| 3048 | |
Yegappan Lakshmanan | 5018a83 | 2022-04-02 21:12:21 +0100 | [diff] [blame] | 3049 | Returns the expanded string. If an error is encountered |
| 3050 | during expansion, the unmodified {string} is returned. |
Yegappan Lakshmanan | 2b74b68 | 2022-04-03 21:30:32 +0100 | [diff] [blame] | 3051 | |
Yegappan Lakshmanan | 5018a83 | 2022-04-02 21:12:21 +0100 | [diff] [blame] | 3052 | Example: > |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3053 | :echo expandcmd('make %<.o') |
Yegappan Lakshmanan | 2b74b68 | 2022-04-03 21:30:32 +0100 | [diff] [blame] | 3054 | make /path/runtime/doc/builtin.o |
| 3055 | :echo expandcmd('make %<.o', {'errmsg': v:true}) |
| 3056 | < |
Yegappan Lakshmanan | 5018a83 | 2022-04-02 21:12:21 +0100 | [diff] [blame] | 3057 | Can also be used as a |method|: > |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3058 | GetCommand()->expandcmd() |
| 3059 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3060 | Return type: |String| or list<string> depending on {list} |
| 3061 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3062 | extend({expr1}, {expr2} [, {expr3}]) *extend()* |
| 3063 | {expr1} and {expr2} must be both |Lists| or both |
| 3064 | |Dictionaries|. |
| 3065 | |
| 3066 | If they are |Lists|: Append {expr2} to {expr1}. |
| 3067 | If {expr3} is given insert the items of {expr2} before the |
| 3068 | item with index {expr3} in {expr1}. When {expr3} is zero |
| 3069 | insert before the first item. When {expr3} is equal to |
| 3070 | len({expr1}) then {expr2} is appended. |
| 3071 | Examples: > |
| 3072 | :echo sort(extend(mylist, [7, 5])) |
| 3073 | :call extend(mylist, [2, 3], 1) |
| 3074 | < When {expr1} is the same List as {expr2} then the number of |
| 3075 | items copied is equal to the original length of the List. |
| 3076 | E.g., when {expr3} is 1 you get N new copies of the first item |
| 3077 | (where N is the original length of the List). |
| 3078 | Use |add()| to concatenate one item to a list. To concatenate |
| 3079 | two lists into a new list use the + operator: > |
| 3080 | :let newlist = [1, 2, 3] + [4, 5] |
| 3081 | < |
| 3082 | If they are |Dictionaries|: |
| 3083 | Add all entries from {expr2} to {expr1}. |
| 3084 | If a key exists in both {expr1} and {expr2} then {expr3} is |
| 3085 | used to decide what to do: |
| 3086 | {expr3} = "keep": keep the value of {expr1} |
| 3087 | {expr3} = "force": use the value of {expr2} |
| 3088 | {expr3} = "error": give an error message *E737* |
| 3089 | When {expr3} is omitted then "force" is assumed. |
| 3090 | |
| 3091 | {expr1} is changed when {expr2} is not empty. If necessary |
Christian Brabandt | 5647c91 | 2025-02-17 21:33:30 +0100 | [diff] [blame] | 3092 | make a copy of {expr1} first or use |extendnew()| to return a |
| 3093 | new List/Dictionary. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3094 | {expr2} remains unchanged. |
| 3095 | When {expr1} is locked and {expr2} is not empty the operation |
| 3096 | fails. |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 3097 | Returns {expr1}. Returns 0 on error. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3098 | |
| 3099 | Can also be used as a |method|: > |
| 3100 | mylist->extend(otherlist) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3101 | < |
| 3102 | Return type: list<{type}> or dict<{type}> depending on {expr1} |
| 3103 | and {expr2}, in case of error: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3104 | |
| 3105 | |
| 3106 | extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()* |
| 3107 | Like |extend()| but instead of adding items to {expr1} a new |
| 3108 | List or Dictionary is created and returned. {expr1} remains |
Bram Moolenaar | dd60c36 | 2023-02-27 15:49:53 +0000 | [diff] [blame] | 3109 | unchanged. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3110 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3111 | Return type: list<{type}> or dict<{type}> depending on {expr1} |
| 3112 | and {expr2}, in case of error: |Number| |
| 3113 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3114 | |
| 3115 | feedkeys({string} [, {mode}]) *feedkeys()* |
| 3116 | Characters in {string} are queued for processing as if they |
| 3117 | come from a mapping or were typed by the user. |
| 3118 | |
| 3119 | By default the string is added to the end of the typeahead |
| 3120 | buffer, thus if a mapping is still being executed the |
| 3121 | characters come after them. Use the 'i' flag to insert before |
| 3122 | other characters, they will be executed next, before any |
| 3123 | characters from a mapping. |
| 3124 | |
| 3125 | The function does not wait for processing of keys contained in |
| 3126 | {string}. |
| 3127 | |
| 3128 | To include special keys into {string}, use double-quotes |
| 3129 | and "\..." notation |expr-quote|. For example, |
| 3130 | feedkeys("\<CR>") simulates pressing of the <Enter> key. But |
| 3131 | feedkeys('\<CR>') pushes 5 characters. |
| 3132 | A special code that might be useful is <Ignore>, it exits the |
| 3133 | wait for a character without doing anything. *<Ignore>* |
| 3134 | |
| 3135 | {mode} is a String, which can contain these character flags: |
| 3136 | 'm' Remap keys. This is default. If {mode} is absent, |
| 3137 | keys are remapped. |
| 3138 | 'n' Do not remap keys. |
| 3139 | 't' Handle keys as if typed; otherwise they are handled as |
| 3140 | if coming from a mapping. This matters for undo, |
| 3141 | opening folds, etc. |
| 3142 | 'L' Lowlevel input. Only works for Unix or when using the |
| 3143 | GUI. Keys are used as if they were coming from the |
| 3144 | terminal. Other flags are not used. *E980* |
| 3145 | When a CTRL-C interrupts and 't' is included it sets |
| 3146 | the internal "got_int" flag. |
| 3147 | 'i' Insert the string instead of appending (see above). |
| 3148 | 'x' Execute commands until typeahead is empty. This is |
| 3149 | similar to using ":normal!". You can call feedkeys() |
| 3150 | several times without 'x' and then one time with 'x' |
| 3151 | (possibly with an empty {string}) to execute all the |
| 3152 | typeahead. Note that when Vim ends in Insert mode it |
| 3153 | will behave as if <Esc> is typed, to avoid getting |
| 3154 | stuck, waiting for a character to be typed before the |
| 3155 | script continues. |
| 3156 | Note that if you manage to call feedkeys() while |
| 3157 | executing commands, thus calling it recursively, then |
| 3158 | all typeahead will be consumed by the last call. |
Bram Moolenaar | a972522 | 2022-01-16 13:30:33 +0000 | [diff] [blame] | 3159 | 'c' Remove any script context when executing, so that |
| 3160 | legacy script syntax applies, "s:var" does not work, |
Bram Moolenaar | d899e51 | 2022-05-07 21:54:03 +0100 | [diff] [blame] | 3161 | etc. Note that if the string being fed sets a script |
Bram Moolenaar | ce001a3 | 2022-04-27 15:25:03 +0100 | [diff] [blame] | 3162 | context this still applies. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3163 | '!' When used with 'x' will not end Insert mode. Can be |
| 3164 | used in a test when a timer is set to exit Insert mode |
| 3165 | a little later. Useful for testing CursorHoldI. |
| 3166 | |
| 3167 | Return value is always 0. |
| 3168 | |
| 3169 | Can also be used as a |method|: > |
| 3170 | GetInput()->feedkeys() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3171 | < |
Christian Brabandt | 17ad852 | 2025-05-09 00:03:20 +0200 | [diff] [blame] | 3172 | Return type: |Number| |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3173 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3174 | |
Shougo Matsushita | 60c8743 | 2024-06-03 22:59:27 +0200 | [diff] [blame] | 3175 | filecopy({from}, {to}) *filecopy()* |
| 3176 | Copy the file pointed to by the name {from} to {to}. The |
| 3177 | result is a Number, which is |TRUE| if the file was copied |
| 3178 | successfully, and |FALSE| when it failed. |
| 3179 | If a file with name {to} already exists, it will fail. |
| 3180 | Note that it does not handle directories (yet). |
| 3181 | |
| 3182 | This function is not available in the |sandbox|. |
| 3183 | |
| 3184 | Can also be used as a |method|: > |
| 3185 | GetOldName()->filecopy(newname) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3186 | < |
| 3187 | Return type: |Number| |
| 3188 | |
Shougo Matsushita | 60c8743 | 2024-06-03 22:59:27 +0200 | [diff] [blame] | 3189 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3190 | filereadable({file}) *filereadable()* |
| 3191 | The result is a Number, which is |TRUE| when a file with the |
| 3192 | name {file} exists, and can be read. If {file} doesn't exist, |
| 3193 | or is a directory, the result is |FALSE|. {file} is any |
| 3194 | expression, which is used as a String. |
| 3195 | If you don't care about the file being readable you can use |
| 3196 | |glob()|. |
| 3197 | {file} is used as-is, you may want to expand wildcards first: > |
| 3198 | echo filereadable('~/.vimrc') |
| 3199 | 0 |
| 3200 | echo filereadable(expand('~/.vimrc')) |
| 3201 | 1 |
| 3202 | |
| 3203 | < Can also be used as a |method|: > |
| 3204 | GetName()->filereadable() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3205 | < |
| 3206 | Return type: |Number| |
| 3207 | |
| 3208 | *file_readable()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3209 | Obsolete name: file_readable(). |
| 3210 | |
| 3211 | |
| 3212 | filewritable({file}) *filewritable()* |
| 3213 | The result is a Number, which is 1 when a file with the |
| 3214 | name {file} exists, and can be written. If {file} doesn't |
| 3215 | exist, or is not writable, the result is 0. If {file} is a |
| 3216 | directory, and we can write to it, the result is 2. |
| 3217 | |
| 3218 | Can also be used as a |method|: > |
| 3219 | GetName()->filewritable() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3220 | < |
| 3221 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3222 | |
| 3223 | |
| 3224 | filter({expr1}, {expr2}) *filter()* |
| 3225 | {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. |
| 3226 | For each item in {expr1} evaluate {expr2} and when the result |
| 3227 | is zero or false remove the item from the |List| or |
| 3228 | |Dictionary|. Similarly for each byte in a |Blob| and each |
Bram Moolenaar | 2f0936c | 2022-01-08 21:51:59 +0000 | [diff] [blame] | 3229 | character in a |String|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3230 | |
| 3231 | {expr2} must be a |string| or |Funcref|. |
| 3232 | |
| 3233 | If {expr2} is a |string|, inside {expr2} |v:val| has the value |
| 3234 | of the current item. For a |Dictionary| |v:key| has the key |
| 3235 | of the current item and for a |List| |v:key| has the index of |
| 3236 | the current item. For a |Blob| |v:key| has the index of the |
| 3237 | current byte. For a |String| |v:key| has the index of the |
| 3238 | current character. |
| 3239 | Examples: > |
| 3240 | call filter(mylist, 'v:val !~ "OLD"') |
| 3241 | < Removes the items where "OLD" appears. > |
| 3242 | call filter(mydict, 'v:key >= 8') |
| 3243 | < Removes the items with a key below 8. > |
| 3244 | call filter(var, 0) |
| 3245 | < Removes all the items, thus clears the |List| or |Dictionary|. |
| 3246 | |
| 3247 | Note that {expr2} is the result of expression and is then |
| 3248 | used as an expression again. Often it is good to use a |
| 3249 | |literal-string| to avoid having to double backslashes. |
| 3250 | |
| 3251 | If {expr2} is a |Funcref| it must take two arguments: |
| 3252 | 1. the key or the index of the current item. |
| 3253 | 2. the value of the current item. |
| 3254 | The function must return |TRUE| if the item should be kept. |
| 3255 | Example that keeps the odd items of a list: > |
| 3256 | func Odd(idx, val) |
| 3257 | return a:idx % 2 == 1 |
| 3258 | endfunc |
| 3259 | call filter(mylist, function('Odd')) |
Bram Moolenaar | 2f0936c | 2022-01-08 21:51:59 +0000 | [diff] [blame] | 3260 | < It is shorter when using a |lambda|. In |Vim9| syntax: > |
| 3261 | call filter(myList, (idx, val) => idx * val <= 42) |
| 3262 | < In legacy script syntax: > |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3263 | call filter(myList, {idx, val -> idx * val <= 42}) |
| 3264 | < If you do not use "val" you can leave it out: > |
| 3265 | call filter(myList, {idx -> idx % 2 == 1}) |
| 3266 | < |
| 3267 | In |Vim9| script the result must be true, false, zero or one. |
| 3268 | Other values will result in a type error. |
| 3269 | |
| 3270 | For a |List| and a |Dictionary| the operation is done |
| 3271 | in-place. If you want it to remain unmodified make a copy |
| 3272 | first: > |
| 3273 | :let l = filter(copy(mylist), 'v:val =~ "KEEP"') |
| 3274 | |
| 3275 | < Returns {expr1}, the |List| or |Dictionary| that was filtered, |
naohiro ono | 56200ee | 2022-01-01 14:59:44 +0000 | [diff] [blame] | 3276 | or a new |Blob| or |String|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3277 | When an error is encountered while evaluating {expr2} no |
| 3278 | further items in {expr1} are processed. |
| 3279 | When {expr2} is a Funcref errors inside a function are ignored, |
| 3280 | unless it was defined with the "abort" flag. |
| 3281 | |
| 3282 | Can also be used as a |method|: > |
| 3283 | mylist->filter(expr2) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3284 | < |
| 3285 | Return type: |String|, |Blob|, list<{type}> or dict<{type}> |
| 3286 | depending on {expr1} |
| 3287 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3288 | |
| 3289 | finddir({name} [, {path} [, {count}]]) *finddir()* |
| 3290 | Find directory {name} in {path}. Supports both downwards and |
| 3291 | upwards recursive directory searches. See |file-searching| |
| 3292 | for the syntax of {path}. |
| 3293 | |
| 3294 | Returns the path of the first found match. When the found |
| 3295 | directory is below the current directory a relative path is |
| 3296 | returned. Otherwise a full path is returned. |
| 3297 | If {path} is omitted or empty then 'path' is used. |
| 3298 | |
| 3299 | If the optional {count} is given, find {count}'s occurrence of |
| 3300 | {name} in {path} instead of the first one. |
| 3301 | When {count} is negative return all the matches in a |List|. |
| 3302 | |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 3303 | Returns an empty string if the directory is not found. |
| 3304 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3305 | This is quite similar to the ex-command `:find`. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3306 | |
| 3307 | Can also be used as a |method|: > |
| 3308 | GetName()->finddir() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3309 | < |
Christian Brabandt | b753d80 | 2025-04-21 11:31:58 +0200 | [diff] [blame] | 3310 | Return type: list<string> if {count} is negative, |String| |
| 3311 | otherwise |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3312 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3313 | |
| 3314 | findfile({name} [, {path} [, {count}]]) *findfile()* |
| 3315 | Just like |finddir()|, but find a file instead of a directory. |
| 3316 | Uses 'suffixesadd'. |
| 3317 | Example: > |
| 3318 | :echo findfile("tags.vim", ".;") |
| 3319 | < Searches from the directory of the current file upwards until |
| 3320 | it finds the file "tags.vim". |
| 3321 | |
| 3322 | Can also be used as a |method|: > |
| 3323 | GetName()->findfile() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3324 | < |
Christian Brabandt | b753d80 | 2025-04-21 11:31:58 +0200 | [diff] [blame] | 3325 | Return type: list<string> if {count} is negative, |String| |
| 3326 | otherwise |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3327 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3328 | |
| 3329 | flatten({list} [, {maxdepth}]) *flatten()* |
| 3330 | Flatten {list} up to {maxdepth} levels. Without {maxdepth} |
| 3331 | the result is a |List| without nesting, as if {maxdepth} is |
| 3332 | a very large number. |
| 3333 | The {list} is changed in place, use |flattennew()| if you do |
| 3334 | not want that. |
| 3335 | In Vim9 script flatten() cannot be used, you must always use |
Bram Moolenaar | a2baa73 | 2022-02-04 16:09:54 +0000 | [diff] [blame] | 3336 | |flattennew()|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3337 | *E900* |
| 3338 | {maxdepth} means how deep in nested lists changes are made. |
| 3339 | {list} is not modified when {maxdepth} is 0. |
| 3340 | {maxdepth} must be positive number. |
| 3341 | |
| 3342 | If there is an error the number zero is returned. |
| 3343 | |
| 3344 | Example: > |
| 3345 | :echo flatten([1, [2, [3, 4]], 5]) |
| 3346 | < [1, 2, 3, 4, 5] > |
| 3347 | :echo flatten([1, [2, [3, 4]], 5], 1) |
| 3348 | < [1, 2, [3, 4], 5] |
| 3349 | |
| 3350 | Can also be used as a |method|: > |
| 3351 | mylist->flatten() |
| 3352 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3353 | Return type: list<{type}> |
| 3354 | |
| 3355 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3356 | flattennew({list} [, {maxdepth}]) *flattennew()* |
| 3357 | Like |flatten()| but first make a copy of {list}. |
| 3358 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3359 | Return type: list<{type}> |
| 3360 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3361 | |
| 3362 | float2nr({expr}) *float2nr()* |
| 3363 | Convert {expr} to a Number by omitting the part after the |
| 3364 | decimal point. |
Bram Moolenaar | 76db9e0 | 2022-11-09 21:21:04 +0000 | [diff] [blame] | 3365 | {expr} must evaluate to a |Float| or a |Number|. |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 3366 | Returns 0 if {expr} is not a |Float| or a |Number|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3367 | When the value of {expr} is out of range for a |Number| the |
| 3368 | result is truncated to 0x7fffffff or -0x7fffffff (or when |
| 3369 | 64-bit Number support is enabled, 0x7fffffffffffffff or |
| 3370 | -0x7fffffffffffffff). NaN results in -0x80000000 (or when |
| 3371 | 64-bit Number support is enabled, -0x8000000000000000). |
| 3372 | Examples: > |
| 3373 | echo float2nr(3.95) |
| 3374 | < 3 > |
| 3375 | echo float2nr(-23.45) |
| 3376 | < -23 > |
| 3377 | echo float2nr(1.0e100) |
| 3378 | < 2147483647 (or 9223372036854775807) > |
| 3379 | echo float2nr(-1.0e150) |
| 3380 | < -2147483647 (or -9223372036854775807) > |
| 3381 | echo float2nr(1.0e-100) |
| 3382 | < 0 |
| 3383 | |
| 3384 | Can also be used as a |method|: > |
| 3385 | Compute()->float2nr() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3386 | < |
| 3387 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3388 | |
| 3389 | |
| 3390 | floor({expr}) *floor()* |
| 3391 | Return the largest integral value less than or equal to |
| 3392 | {expr} as a |Float| (round down). |
| 3393 | {expr} must evaluate to a |Float| or a |Number|. |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 3394 | Returns 0.0 if {expr} is not a |Float| or a |Number|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3395 | Examples: > |
| 3396 | echo floor(1.856) |
| 3397 | < 1.0 > |
| 3398 | echo floor(-5.456) |
| 3399 | < -6.0 > |
| 3400 | echo floor(4.0) |
| 3401 | < 4.0 |
| 3402 | |
| 3403 | Can also be used as a |method|: > |
| 3404 | Compute()->floor() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3405 | < |
| 3406 | Return type: |Float| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3407 | |
| 3408 | |
| 3409 | fmod({expr1}, {expr2}) *fmod()* |
| 3410 | Return the remainder of {expr1} / {expr2}, even if the |
| 3411 | division is not representable. Returns {expr1} - i * {expr2} |
| 3412 | for some integer i such that if {expr2} is non-zero, the |
| 3413 | result has the same sign as {expr1} and magnitude less than |
| 3414 | the magnitude of {expr2}. If {expr2} is zero, the value |
| 3415 | returned is zero. The value returned is a |Float|. |
| 3416 | {expr1} and {expr2} must evaluate to a |Float| or a |Number|. |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 3417 | Returns 0.0 if {expr1} or {expr2} is not a |Float| or a |
| 3418 | |Number|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3419 | Examples: > |
| 3420 | :echo fmod(12.33, 1.22) |
| 3421 | < 0.13 > |
| 3422 | :echo fmod(-12.33, 1.22) |
| 3423 | < -0.13 |
| 3424 | |
| 3425 | Can also be used as a |method|: > |
| 3426 | Compute()->fmod(1.22) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3427 | < |
| 3428 | Return type: |Float| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3429 | |
| 3430 | |
| 3431 | fnameescape({string}) *fnameescape()* |
| 3432 | Escape {string} for use as file name command argument. All |
| 3433 | characters that have a special meaning, such as '%' and '|' |
| 3434 | are escaped with a backslash. |
| 3435 | For most systems the characters escaped are |
| 3436 | " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash |
| 3437 | appears in a filename, it depends on the value of 'isfname'. |
| 3438 | A leading '+' and '>' is also escaped (special after |:edit| |
| 3439 | and |:write|). And a "-" by itself (special after |:cd|). |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 3440 | Returns an empty string on error. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3441 | Example: > |
| 3442 | :let fname = '+some str%nge|name' |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 3443 | :exe "edit " .. fnameescape(fname) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3444 | < results in executing: > |
| 3445 | edit \+some\ str\%nge\|name |
| 3446 | < |
| 3447 | Can also be used as a |method|: > |
| 3448 | GetName()->fnameescape() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3449 | < |
| 3450 | Return type: |String| |
| 3451 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3452 | |
| 3453 | fnamemodify({fname}, {mods}) *fnamemodify()* |
| 3454 | Modify file name {fname} according to {mods}. {mods} is a |
| 3455 | string of characters like it is used for file names on the |
| 3456 | command line. See |filename-modifiers|. |
| 3457 | Example: > |
| 3458 | :echo fnamemodify("main.c", ":p:h") |
| 3459 | < results in: > |
Bram Moolenaar | d799daa | 2022-06-20 11:17:32 +0100 | [diff] [blame] | 3460 | /home/user/vim/vim/src |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 3461 | < If {mods} is empty or an unsupported modifier is used then |
| 3462 | {fname} is returned. |
Bram Moolenaar | 5ed1153 | 2022-07-06 13:18:11 +0100 | [diff] [blame] | 3463 | When {fname} is empty then with {mods} ":h" returns ".", so |
| 3464 | that `:cd` can be used with it. This is different from |
| 3465 | expand('%:h') without a buffer name, which returns an empty |
| 3466 | string. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3467 | Note: Environment variables don't work in {fname}, use |
| 3468 | |expand()| first then. |
| 3469 | |
| 3470 | Can also be used as a |method|: > |
| 3471 | GetName()->fnamemodify(':p:h') |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3472 | < |
| 3473 | Return type: |String| |
| 3474 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3475 | |
| 3476 | foldclosed({lnum}) *foldclosed()* |
| 3477 | The result is a Number. If the line {lnum} is in a closed |
| 3478 | fold, the result is the number of the first line in that fold. |
| 3479 | If the line {lnum} is not in a closed fold, -1 is returned. |
| 3480 | {lnum} is used like with |getline()|. Thus "." is the current |
| 3481 | line, "'m" mark m, etc. |
| 3482 | |
| 3483 | Can also be used as a |method|: > |
| 3484 | GetLnum()->foldclosed() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3485 | < |
| 3486 | Return type: |Number| |
| 3487 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3488 | |
| 3489 | foldclosedend({lnum}) *foldclosedend()* |
| 3490 | The result is a Number. If the line {lnum} is in a closed |
| 3491 | fold, the result is the number of the last line in that fold. |
| 3492 | If the line {lnum} is not in a closed fold, -1 is returned. |
| 3493 | {lnum} is used like with |getline()|. Thus "." is the current |
| 3494 | line, "'m" mark m, etc. |
| 3495 | |
| 3496 | Can also be used as a |method|: > |
| 3497 | GetLnum()->foldclosedend() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3498 | < |
| 3499 | Return type: |Number| |
| 3500 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3501 | |
| 3502 | foldlevel({lnum}) *foldlevel()* |
| 3503 | The result is a Number, which is the foldlevel of line {lnum} |
| 3504 | in the current buffer. For nested folds the deepest level is |
| 3505 | returned. If there is no fold at line {lnum}, zero is |
| 3506 | returned. It doesn't matter if the folds are open or closed. |
| 3507 | When used while updating folds (from 'foldexpr') -1 is |
| 3508 | returned for lines where folds are still to be updated and the |
| 3509 | foldlevel is unknown. As a special case the level of the |
| 3510 | previous line is usually available. |
| 3511 | {lnum} is used like with |getline()|. Thus "." is the current |
| 3512 | line, "'m" mark m, etc. |
| 3513 | |
| 3514 | Can also be used as a |method|: > |
| 3515 | GetLnum()->foldlevel() |
| 3516 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3517 | Return type: |Number| |
| 3518 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3519 | *foldtext()* |
| 3520 | foldtext() Returns a String, to be displayed for a closed fold. This is |
| 3521 | the default function used for the 'foldtext' option and should |
| 3522 | only be called from evaluating 'foldtext'. It uses the |
| 3523 | |v:foldstart|, |v:foldend| and |v:folddashes| variables. |
| 3524 | The returned string looks like this: > |
| 3525 | +-- 45 lines: abcdef |
| 3526 | < The number of leading dashes depends on the foldlevel. The |
| 3527 | "45" is the number of lines in the fold. "abcdef" is the text |
| 3528 | in the first non-blank line of the fold. Leading white space, |
| 3529 | "//" or "/*" and the text from the 'foldmarker' and |
| 3530 | 'commentstring' options is removed. |
| 3531 | When used to draw the actual foldtext, the rest of the line |
| 3532 | will be filled with the fold char from the 'fillchars' |
| 3533 | setting. |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 3534 | Returns an empty string when there is no fold. |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3535 | |
| 3536 | Return type: |String| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3537 | {not available when compiled without the |+folding| feature} |
| 3538 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3539 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3540 | foldtextresult({lnum}) *foldtextresult()* |
| 3541 | Returns the text that is displayed for the closed fold at line |
| 3542 | {lnum}. Evaluates 'foldtext' in the appropriate context. |
| 3543 | When there is no closed fold at {lnum} an empty string is |
| 3544 | returned. |
| 3545 | {lnum} is used like with |getline()|. Thus "." is the current |
| 3546 | line, "'m" mark m, etc. |
| 3547 | Useful when exporting folded text, e.g., to HTML. |
| 3548 | {not available when compiled without the |+folding| feature} |
| 3549 | |
| 3550 | |
| 3551 | Can also be used as a |method|: > |
| 3552 | GetLnum()->foldtextresult() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3553 | < |
| 3554 | Return type: |String| |
| 3555 | |
Ernie Rael | e79e207 | 2024-01-13 11:47:33 +0100 | [diff] [blame] | 3556 | |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 3557 | foreach({expr1}, {expr2}) *foreach()* *E1525* |
| 3558 | {expr1} must be a |List|, |Tuple|, |String|, |Blob| or |
| 3559 | |Dictionary|. |
Ernie Rael | e79e207 | 2024-01-13 11:47:33 +0100 | [diff] [blame] | 3560 | For each item in {expr1} execute {expr2}. {expr1} is not |
errael | c92b8be | 2024-01-14 10:11:07 -0800 | [diff] [blame] | 3561 | modified; its values may be, as with |:lockvar| 1. |E741| |
Ernie Rael | e79e207 | 2024-01-13 11:47:33 +0100 | [diff] [blame] | 3562 | See |map()| and |filter()| to modify {expr1}. |
| 3563 | |
| 3564 | {expr2} must be a |string| or |Funcref|. |
| 3565 | |
| 3566 | If {expr2} is a |string|, inside {expr2} |v:val| has the value |
| 3567 | of the current item. For a |Dictionary| |v:key| has the key |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 3568 | of the current item and for a |List| or a |Tuple| |v:key| has |
| 3569 | the index of the current item. For a |Blob| |v:key| has the |
| 3570 | index of the current byte. For a |String| |v:key| has the |
| 3571 | index of the current character. |
Ernie Rael | e79e207 | 2024-01-13 11:47:33 +0100 | [diff] [blame] | 3572 | Examples: > |
| 3573 | call foreach(mylist, 'used[v:val] = true') |
| 3574 | < This records the items that are in the {expr1} list. |
| 3575 | |
| 3576 | Note that {expr2} is the result of expression and is then used |
| 3577 | as a command. Often it is good to use a |literal-string| to |
| 3578 | avoid having to double backslashes. |
| 3579 | |
| 3580 | If {expr2} is a |Funcref| it must take two arguments: |
| 3581 | 1. the key or the index of the current item. |
| 3582 | 2. the value of the current item. |
| 3583 | With a legacy script lambda you don't get an error if it only |
| 3584 | accepts one argument, but with a Vim9 lambda you get "E1106: |
| 3585 | One argument too many", the number of arguments must match. |
| 3586 | If the function returns a value, it is ignored. |
| 3587 | |
| 3588 | Returns {expr1} in all cases. |
| 3589 | When an error is encountered while executing {expr2} no |
| 3590 | further items in {expr1} are processed. |
| 3591 | When {expr2} is a Funcref errors inside a function are ignored, |
| 3592 | unless it was defined with the "abort" flag. |
| 3593 | |
| 3594 | Can also be used as a |method|: > |
| 3595 | mylist->foreach(expr2) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3596 | < |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 3597 | Return type: |String|, |Blob|, list<{type}>, tuple<{type}> or |
| 3598 | dict<{type}> depending on {expr1} |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3599 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3600 | *foreground()* |
| 3601 | foreground() Move the Vim window to the foreground. Useful when sent from |
| 3602 | a client to a Vim server. |remote_send()| |
| 3603 | On Win32 systems this might not work, the OS does not always |
| 3604 | allow a window to bring itself to the foreground. Use |
| 3605 | |remote_foreground()| instead. |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3606 | |
| 3607 | Return type: |Number| |
Bram Moolenaar | cbaff5e | 2022-04-08 17:45:08 +0100 | [diff] [blame] | 3608 | {only in the Win32, Motif and GTK GUI versions and the |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3609 | Win32 console version} |
| 3610 | |
Bram Moolenaar | aa53414 | 2022-09-15 21:46:02 +0100 | [diff] [blame] | 3611 | fullcommand({name} [, {vim9}]) *fullcommand()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3612 | Get the full command name from a short abbreviated command |
| 3613 | name; see |20.2| for details on command abbreviations. |
| 3614 | |
| 3615 | The string argument {name} may start with a `:` and can |
| 3616 | include a [range], these are skipped and not returned. |
Bram Moolenaar | aa53414 | 2022-09-15 21:46:02 +0100 | [diff] [blame] | 3617 | Returns an empty string if a command doesn't exist, if it's |
| 3618 | ambiguous (for user-defined commands) or cannot be shortened |
| 3619 | this way. |vim9-no-shorten| |
| 3620 | |
| 3621 | Without the {vim9} argument uses the current script version. |
| 3622 | If {vim9} is present and FALSE then legacy script rules are |
| 3623 | used. When {vim9} is present and TRUE then Vim9 rules are |
| 3624 | used, e.g. "en" is not a short form of "endif". |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3625 | |
| 3626 | For example `fullcommand('s')`, `fullcommand('sub')`, |
| 3627 | `fullcommand(':%substitute')` all return "substitute". |
| 3628 | |
| 3629 | Can also be used as a |method|: > |
| 3630 | GetName()->fullcommand() |
| 3631 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3632 | Return type: |String| |
| 3633 | |
| 3634 | |
| 3635 | funcref({name} [, {arglist}] [, {dict}]) *funcref()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3636 | Just like |function()|, but the returned Funcref will lookup |
| 3637 | the function by reference, not by name. This matters when the |
| 3638 | function {name} is redefined later. |
| 3639 | |
| 3640 | Unlike |function()|, {name} must be an existing user function. |
Bram Moolenaar | 2f0936c | 2022-01-08 21:51:59 +0000 | [diff] [blame] | 3641 | It only works for an autoloaded function if it has already |
| 3642 | been loaded (to avoid mistakenly loading the autoload script |
| 3643 | when only intending to use the function name, use |function()| |
| 3644 | instead). {name} cannot be a builtin function. |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 3645 | Returns 0 on error. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3646 | |
| 3647 | Can also be used as a |method|: > |
| 3648 | GetFuncname()->funcref([arg]) |
| 3649 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3650 | Return type: func(...): any or |Number| on error |
| 3651 | |
Dominique Pelle | e764d1b | 2023-03-12 21:20:59 +0000 | [diff] [blame] | 3652 | *function()* *partial* *E700* *E923* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3653 | function({name} [, {arglist}] [, {dict}]) |
| 3654 | Return a |Funcref| variable that refers to function {name}. |
| 3655 | {name} can be the name of a user defined function or an |
| 3656 | internal function. |
| 3657 | |
| 3658 | {name} can also be a Funcref or a partial. When it is a |
| 3659 | partial the dict stored in it will be used and the {dict} |
| 3660 | argument is not allowed. E.g.: > |
| 3661 | let FuncWithArg = function(dict.Func, [arg]) |
| 3662 | let Broken = function(dict.Func, [arg], dict) |
| 3663 | < |
| 3664 | When using the Funcref the function will be found by {name}, |
| 3665 | also when it was redefined later. Use |funcref()| to keep the |
| 3666 | same function. |
| 3667 | |
| 3668 | When {arglist} or {dict} is present this creates a partial. |
| 3669 | That means the argument list and/or the dictionary is stored in |
| 3670 | the Funcref and will be used when the Funcref is called. |
| 3671 | |
| 3672 | The arguments are passed to the function in front of other |
| 3673 | arguments, but after any argument from |method|. Example: > |
| 3674 | func Callback(arg1, arg2, name) |
| 3675 | ... |
| 3676 | let Partial = function('Callback', ['one', 'two']) |
| 3677 | ... |
| 3678 | call Partial('name') |
| 3679 | < Invokes the function as with: > |
| 3680 | call Callback('one', 'two', 'name') |
| 3681 | |
| 3682 | < With a |method|: > |
| 3683 | func Callback(one, two, three) |
| 3684 | ... |
| 3685 | let Partial = function('Callback', ['two']) |
| 3686 | ... |
| 3687 | eval 'one'->Partial('three') |
| 3688 | < Invokes the function as with: > |
| 3689 | call Callback('one', 'two', 'three') |
| 3690 | |
| 3691 | < The function() call can be nested to add more arguments to the |
| 3692 | Funcref. The extra arguments are appended to the list of |
| 3693 | arguments. Example: > |
| 3694 | func Callback(arg1, arg2, name) |
Bram Moolenaar | 0daafaa | 2022-09-04 17:45:43 +0100 | [diff] [blame] | 3695 | "... |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3696 | let Func = function('Callback', ['one']) |
| 3697 | let Func2 = function(Func, ['two']) |
Bram Moolenaar | 0daafaa | 2022-09-04 17:45:43 +0100 | [diff] [blame] | 3698 | "... |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3699 | call Func2('name') |
| 3700 | < Invokes the function as with: > |
| 3701 | call Callback('one', 'two', 'name') |
| 3702 | |
| 3703 | < The Dictionary is only useful when calling a "dict" function. |
| 3704 | In that case the {dict} is passed in as "self". Example: > |
| 3705 | function Callback() dict |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 3706 | echo "called for " .. self.name |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3707 | endfunction |
Bram Moolenaar | 0daafaa | 2022-09-04 17:45:43 +0100 | [diff] [blame] | 3708 | "... |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3709 | let context = {"name": "example"} |
| 3710 | let Func = function('Callback', context) |
Bram Moolenaar | 0daafaa | 2022-09-04 17:45:43 +0100 | [diff] [blame] | 3711 | "... |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3712 | call Func() " will echo: called for example |
| 3713 | < The use of function() is not needed when there are no extra |
Bram Moolenaar | 0daafaa | 2022-09-04 17:45:43 +0100 | [diff] [blame] | 3714 | arguments, these two are equivalent, if Callback() is defined |
| 3715 | as context.Callback(): > |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3716 | let Func = function('Callback', context) |
| 3717 | let Func = context.Callback |
| 3718 | |
| 3719 | < The argument list and the Dictionary can be combined: > |
| 3720 | function Callback(arg1, count) dict |
Bram Moolenaar | 0daafaa | 2022-09-04 17:45:43 +0100 | [diff] [blame] | 3721 | "... |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3722 | let context = {"name": "example"} |
| 3723 | let Func = function('Callback', ['one'], context) |
Bram Moolenaar | 0daafaa | 2022-09-04 17:45:43 +0100 | [diff] [blame] | 3724 | "... |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3725 | call Func(500) |
| 3726 | < Invokes the function as with: > |
| 3727 | call context.Callback('one', 500) |
| 3728 | < |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 3729 | Returns 0 on error. |
| 3730 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3731 | Can also be used as a |method|: > |
| 3732 | GetFuncname()->function([arg]) |
| 3733 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3734 | < |
| 3735 | Return type: func(...): any or |Number| on error |
| 3736 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3737 | |
| 3738 | garbagecollect([{atexit}]) *garbagecollect()* |
| 3739 | Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs| |
| 3740 | that have circular references. |
| 3741 | |
| 3742 | There is hardly ever a need to invoke this function, as it is |
| 3743 | automatically done when Vim runs out of memory or is waiting |
| 3744 | for the user to press a key after 'updatetime'. Items without |
| 3745 | circular references are always freed when they become unused. |
| 3746 | This is useful if you have deleted a very big |List| and/or |
| 3747 | |Dictionary| with circular references in a script that runs |
| 3748 | for a long time. |
| 3749 | |
| 3750 | When the optional {atexit} argument is one, garbage |
| 3751 | collection will also be done when exiting Vim, if it wasn't |
| 3752 | done before. This is useful when checking for memory leaks. |
| 3753 | |
| 3754 | The garbage collection is not done immediately but only when |
| 3755 | it's safe to perform. This is when waiting for the user to |
| 3756 | type a character. To force garbage collection immediately use |
| 3757 | |test_garbagecollect_now()|. |
| 3758 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3759 | Return type: |String| |
| 3760 | |
| 3761 | |
LemonBoy | 48b7d05 | 2024-07-09 18:24:59 +0200 | [diff] [blame] | 3762 | get({list}, {idx} [, {default}]) *get()* *get()-list* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3763 | Get item {idx} from |List| {list}. When this item is not |
| 3764 | available return {default}. Return zero when {default} is |
| 3765 | omitted. |
| 3766 | Preferably used as a |method|: > |
| 3767 | mylist->get(idx) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3768 | < |
| 3769 | Return type: any, depending on {list} |
| 3770 | |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 3771 | get({tuple}, {idx} [, {default}]) *get()-tuple* |
| 3772 | Get item {idx} from |Tuple| {tuple}. When this item is not |
| 3773 | available return {default}. Return zero when {default} is |
| 3774 | omitted. |
| 3775 | Preferably used as a |method|: > |
| 3776 | mytuple->get(idx) |
| 3777 | < |
| 3778 | Return type: any, depending on {tuple} |
| 3779 | |
LemonBoy | 48b7d05 | 2024-07-09 18:24:59 +0200 | [diff] [blame] | 3780 | get({blob}, {idx} [, {default}]) *get()-blob* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3781 | Get byte {idx} from |Blob| {blob}. When this byte is not |
| 3782 | available return {default}. Return -1 when {default} is |
| 3783 | omitted. |
| 3784 | Preferably used as a |method|: > |
| 3785 | myblob->get(idx) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3786 | < |
| 3787 | Return type: |Number| |
| 3788 | |
LemonBoy | 48b7d05 | 2024-07-09 18:24:59 +0200 | [diff] [blame] | 3789 | get({dict}, {key} [, {default}]) *get()-dict* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3790 | Get item with key {key} from |Dictionary| {dict}. When this |
| 3791 | item is not available return {default}. Return zero when |
| 3792 | {default} is omitted. Useful example: > |
| 3793 | let val = get(g:, 'var_name', 'default') |
| 3794 | < This gets the value of g:var_name if it exists, and uses |
| 3795 | 'default' when it does not exist. |
| 3796 | Preferably used as a |method|: > |
| 3797 | mydict->get(key) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3798 | < |
h-east | 84ac212 | 2024-06-17 18:12:30 +0200 | [diff] [blame] | 3799 | Return type: any, depending on {dict} |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3800 | |
LemonBoy | 48b7d05 | 2024-07-09 18:24:59 +0200 | [diff] [blame] | 3801 | get({func}, {what}) *get()-func* |
| 3802 | Get item {what} from |Funcref| {func}. Possible values for |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3803 | {what} are: |
LemonBoy | 48b7d05 | 2024-07-09 18:24:59 +0200 | [diff] [blame] | 3804 | "name" The function name |
| 3805 | "func" The function |
| 3806 | "dict" The dictionary |
| 3807 | "args" The list with arguments |
| 3808 | "arity" A dictionary with information about the number of |
| 3809 | arguments accepted by the function (minus the |
| 3810 | {arglist}) with the following fields: |
| 3811 | required the number of positional arguments |
| 3812 | optional the number of optional arguments, |
| 3813 | in addition to the required ones |
| 3814 | varargs |TRUE| if the function accepts a |
| 3815 | variable number of arguments |...| |
| 3816 | |
| 3817 | Note: There is no error, if the {arglist} of |
| 3818 | the Funcref contains more arguments than the |
| 3819 | Funcref expects, it's not validated. |
| 3820 | |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 3821 | Returns zero on error. |
LemonBoy | 48b7d05 | 2024-07-09 18:24:59 +0200 | [diff] [blame] | 3822 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3823 | Preferably used as a |method|: > |
| 3824 | myfunc->get(what) |
| 3825 | < |
LemonBoy | 48b7d05 | 2024-07-09 18:24:59 +0200 | [diff] [blame] | 3826 | Return type: any, depending on {func} and {what} |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3827 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3828 | *getbufinfo()* |
| 3829 | getbufinfo([{buf}]) |
| 3830 | getbufinfo([{dict}]) |
| 3831 | Get information about buffers as a List of Dictionaries. |
| 3832 | |
| 3833 | Without an argument information about all the buffers is |
| 3834 | returned. |
| 3835 | |
| 3836 | When the argument is a |Dictionary| only the buffers matching |
| 3837 | the specified criteria are returned. The following keys can |
| 3838 | be specified in {dict}: |
| 3839 | buflisted include only listed buffers. |
| 3840 | bufloaded include only loaded buffers. |
| 3841 | bufmodified include only modified buffers. |
| 3842 | |
| 3843 | Otherwise, {buf} specifies a particular buffer to return |
| 3844 | information for. For the use of {buf}, see |bufname()| |
| 3845 | above. If the buffer is found the returned List has one item. |
| 3846 | Otherwise the result is an empty list. |
| 3847 | |
| 3848 | Each returned List item is a dictionary with the following |
| 3849 | entries: |
| 3850 | bufnr Buffer number. |
| 3851 | changed TRUE if the buffer is modified. |
| 3852 | changedtick Number of changes made to the buffer. |
Sean Dewar | 1fb4103 | 2023-08-16 17:15:05 +0100 | [diff] [blame] | 3853 | command TRUE if the buffer belongs to the |
| 3854 | command-line window |cmdwin|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3855 | hidden TRUE if the buffer is hidden. |
| 3856 | lastused Timestamp in seconds, like |
| 3857 | |localtime()|, when the buffer was |
| 3858 | last used. |
| 3859 | {only with the |+viminfo| feature} |
| 3860 | listed TRUE if the buffer is listed. |
| 3861 | lnum Line number used for the buffer when |
| 3862 | opened in the current window. |
| 3863 | Only valid if the buffer has been |
| 3864 | displayed in the window in the past. |
| 3865 | If you want the line number of the |
| 3866 | last known cursor position in a given |
| 3867 | window, use |line()|: > |
| 3868 | :echo line('.', {winid}) |
| 3869 | < |
| 3870 | linecount Number of lines in the buffer (only |
| 3871 | valid when loaded) |
| 3872 | loaded TRUE if the buffer is loaded. |
| 3873 | name Full path to the file in the buffer. |
| 3874 | signs List of signs placed in the buffer. |
| 3875 | Each list item is a dictionary with |
| 3876 | the following fields: |
| 3877 | id sign identifier |
| 3878 | lnum line number |
| 3879 | name sign name |
| 3880 | variables A reference to the dictionary with |
| 3881 | buffer-local variables. |
| 3882 | windows List of |window-ID|s that display this |
| 3883 | buffer |
| 3884 | popups List of popup |window-ID|s that |
| 3885 | display this buffer |
| 3886 | |
| 3887 | Examples: > |
| 3888 | for buf in getbufinfo() |
| 3889 | echo buf.name |
| 3890 | endfor |
| 3891 | for buf in getbufinfo({'buflisted':1}) |
| 3892 | if buf.changed |
| 3893 | .... |
| 3894 | endif |
| 3895 | endfor |
| 3896 | < |
| 3897 | To get buffer-local options use: > |
| 3898 | getbufvar({bufnr}, '&option_name') |
| 3899 | < |
| 3900 | Can also be used as a |method|: > |
| 3901 | GetBufnr()->getbufinfo() |
| 3902 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3903 | Return type: list<dict<any>> |
| 3904 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3905 | |
| 3906 | *getbufline()* |
| 3907 | getbufline({buf}, {lnum} [, {end}]) |
| 3908 | Return a |List| with the lines starting from {lnum} to {end} |
| 3909 | (inclusive) in the buffer {buf}. If {end} is omitted, a |
Bram Moolenaar | ce30ccc | 2022-11-21 19:57:04 +0000 | [diff] [blame] | 3910 | |List| with only the line {lnum} is returned. See |
| 3911 | `getbufoneline()` for only getting the line. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3912 | |
| 3913 | For the use of {buf}, see |bufname()| above. |
| 3914 | |
| 3915 | For {lnum} and {end} "$" can be used for the last line of the |
| 3916 | buffer. Otherwise a number must be used. |
| 3917 | |
| 3918 | When {lnum} is smaller than 1 or bigger than the number of |
| 3919 | lines in the buffer, an empty |List| is returned. |
| 3920 | |
| 3921 | When {end} is greater than the number of lines in the buffer, |
| 3922 | it is treated as {end} is set to the number of lines in the |
| 3923 | buffer. When {end} is before {lnum} an empty |List| is |
| 3924 | returned. |
| 3925 | |
| 3926 | This function works only for loaded buffers. For unloaded and |
| 3927 | non-existing buffers, an empty |List| is returned. |
| 3928 | |
| 3929 | Example: > |
| 3930 | :let lines = getbufline(bufnr("myfile"), 1, "$") |
| 3931 | |
| 3932 | < Can also be used as a |method|: > |
| 3933 | GetBufnr()->getbufline(lnum) |
Bram Moolenaar | ce30ccc | 2022-11-21 19:57:04 +0000 | [diff] [blame] | 3934 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3935 | Return type: list<string> |
| 3936 | |
Bram Moolenaar | ce30ccc | 2022-11-21 19:57:04 +0000 | [diff] [blame] | 3937 | *getbufoneline()* |
| 3938 | getbufoneline({buf}, {lnum}) |
| 3939 | Just like `getbufline()` but only get one line and return it |
| 3940 | as a string. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3941 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3942 | Return type: |String| |
| 3943 | |
| 3944 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3945 | getbufvar({buf}, {varname} [, {def}]) *getbufvar()* |
| 3946 | The result is the value of option or local buffer variable |
| 3947 | {varname} in buffer {buf}. Note that the name without "b:" |
| 3948 | must be used. |
| 3949 | The {varname} argument is a string. |
| 3950 | When {varname} is empty returns a |Dictionary| with all the |
| 3951 | buffer-local variables. |
| 3952 | When {varname} is equal to "&" returns a |Dictionary| with all |
| 3953 | the buffer-local options. |
| 3954 | Otherwise, when {varname} starts with "&" returns the value of |
| 3955 | a buffer-local option. |
| 3956 | This also works for a global or buffer-local option, but it |
| 3957 | doesn't work for a global variable, window-local variable or |
| 3958 | window-local option. |
| 3959 | For the use of {buf}, see |bufname()| above. |
| 3960 | When the buffer or variable doesn't exist {def} or an empty |
| 3961 | string is returned, there is no error message. |
| 3962 | Examples: > |
| 3963 | :let bufmodified = getbufvar(1, "&mod") |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 3964 | :echo "todo myvar = " .. getbufvar("todo", "myvar") |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3965 | |
| 3966 | < Can also be used as a |method|: > |
| 3967 | GetBufnr()->getbufvar(varname) |
| 3968 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3969 | Return type: any, depending on {varname} |
| 3970 | |
| 3971 | |
mikoto2000 | 1083cae | 2024-11-11 21:24:14 +0100 | [diff] [blame] | 3972 | getcellpixels() *getcellpixels()* |
| 3973 | Returns a |List| of terminal cell pixel size. |
h-east | b534e80 | 2024-12-03 20:37:52 +0100 | [diff] [blame] | 3974 | List format is [xpixel, ypixel]. |
mikoto2000 | a73dfc2 | 2024-11-18 21:12:21 +0100 | [diff] [blame] | 3975 | |
| 3976 | Only works on Unix (terminal and gVim) and Windows (gVim only). |
| 3977 | Returns [] on other systems or on failure. |
| 3978 | Note that there could be variations across different terminals. |
| 3979 | On macOS, system Terminal.app returns sizes in points (before |
| 3980 | Retina scaling), whereas third-party terminals return raw pixel |
| 3981 | sizes (post Retina scaling). |
mikoto2000 | 1083cae | 2024-11-11 21:24:14 +0100 | [diff] [blame] | 3982 | |
mikoto2000 | de094dc | 2024-11-14 22:13:48 +0100 | [diff] [blame] | 3983 | Return type: list<any> |
mikoto2000 | 1083cae | 2024-11-11 21:24:14 +0100 | [diff] [blame] | 3984 | |
| 3985 | |
Kota Kato | 66bb9ae | 2023-01-17 18:31:56 +0000 | [diff] [blame] | 3986 | getcellwidths() *getcellwidths()* |
| 3987 | Returns a |List| of cell widths of character ranges overridden |
| 3988 | by |setcellwidths()|. The format is equal to the argument of |
| 3989 | |setcellwidths()|. If no character ranges have their cell |
| 3990 | widths overridden, an empty List is returned. |
h-east | 84ac212 | 2024-06-17 18:12:30 +0200 | [diff] [blame] | 3991 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 3992 | Return type: list<any> |
Kota Kato | 66bb9ae | 2023-01-17 18:31:56 +0000 | [diff] [blame] | 3993 | |
| 3994 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 3995 | getchangelist([{buf}]) *getchangelist()* |
| 3996 | Returns the |changelist| for the buffer {buf}. For the use |
| 3997 | of {buf}, see |bufname()| above. If buffer {buf} doesn't |
| 3998 | exist, an empty list is returned. |
| 3999 | |
| 4000 | The returned list contains two entries: a list with the change |
| 4001 | locations and the current position in the list. Each |
| 4002 | entry in the change list is a dictionary with the following |
| 4003 | entries: |
| 4004 | col column number |
| 4005 | coladd column offset for 'virtualedit' |
| 4006 | lnum line number |
| 4007 | If buffer {buf} is the current buffer, then the current |
| 4008 | position refers to the position in the list. For other |
| 4009 | buffers, it is set to the length of the list. |
| 4010 | |
| 4011 | Can also be used as a |method|: > |
| 4012 | GetBufnr()->getchangelist() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4013 | < |
| 4014 | Return type: list<any> |
| 4015 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4016 | |
zeertzjq | e0a2ab3 | 2025-02-02 09:14:35 +0100 | [diff] [blame] | 4017 | getchar([{expr} [, {opts}]]) *getchar()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4018 | Get a single character from the user or input stream. |
zeertzjq | e0a2ab3 | 2025-02-02 09:14:35 +0100 | [diff] [blame] | 4019 | If {expr} is omitted or is -1, wait until a character is |
| 4020 | available. |
Doug Kearns | 9cd9e75 | 2024-04-07 17:42:17 +0200 | [diff] [blame] | 4021 | If {expr} is 0, only get a character when one is available. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4022 | Return zero otherwise. |
Doug Kearns | 9cd9e75 | 2024-04-07 17:42:17 +0200 | [diff] [blame] | 4023 | If {expr} is 1, only check if a character is available, it is |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4024 | not consumed. Return zero if no character available. |
zeertzjq | e0a2ab3 | 2025-02-02 09:14:35 +0100 | [diff] [blame] | 4025 | If you prefer always getting a string use |getcharstr()|, or |
| 4026 | specify |FALSE| as "number" in {opts}. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4027 | |
Doug Kearns | 9cd9e75 | 2024-04-07 17:42:17 +0200 | [diff] [blame] | 4028 | Without {expr} and when {expr} is 0 a whole character or |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4029 | special key is returned. If it is a single character, the |
Bram Moolenaar | 2d8ed02 | 2022-05-21 13:08:16 +0100 | [diff] [blame] | 4030 | result is a Number. Use |nr2char()| to convert it to a String. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4031 | Otherwise a String is returned with the encoded character. |
| 4032 | For a special key it's a String with a sequence of bytes |
| 4033 | starting with 0x80 (decimal: 128). This is the same value as |
| 4034 | the String "\<Key>", e.g., "\<Left>". The returned value is |
| 4035 | also a String when a modifier (shift, control, alt) was used |
zeertzjq | e0a2ab3 | 2025-02-02 09:14:35 +0100 | [diff] [blame] | 4036 | that is not included in the character. |keytrans()| can also |
| 4037 | be used to convert a returned String into a readable form. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4038 | |
Doug Kearns | 9cd9e75 | 2024-04-07 17:42:17 +0200 | [diff] [blame] | 4039 | When {expr} is 0 and Esc is typed, there will be a short delay |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4040 | while Vim waits to see if this is the start of an escape |
| 4041 | sequence. |
| 4042 | |
Doug Kearns | 9cd9e75 | 2024-04-07 17:42:17 +0200 | [diff] [blame] | 4043 | When {expr} is 1 only the first byte is returned. For a |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4044 | one-byte character it is the character itself as a number. |
| 4045 | Use nr2char() to convert it to a String. |
| 4046 | |
| 4047 | Use getcharmod() to obtain any additional modifiers. |
| 4048 | |
zeertzjq | e0a2ab3 | 2025-02-02 09:14:35 +0100 | [diff] [blame] | 4049 | The optional argument {opts} is a Dict and supports the |
| 4050 | following items: |
| 4051 | |
zeertzjq | edf0f7d | 2025-02-02 19:01:01 +0100 | [diff] [blame] | 4052 | cursor A String specifying cursor behavior |
| 4053 | when waiting for a character. |
| 4054 | "hide": hide the cursor. |
| 4055 | "keep": keep current cursor unchanged. |
| 4056 | "msg": move cursor to message area. |
| 4057 | (default: "msg") |
| 4058 | |
zeertzjq | e0a2ab3 | 2025-02-02 09:14:35 +0100 | [diff] [blame] | 4059 | number If |TRUE|, return a Number when getting |
| 4060 | a single character. |
| 4061 | If |FALSE|, the return value is always |
| 4062 | converted to a String, and an empty |
| 4063 | String (instead of 0) is returned when |
| 4064 | no character is available. |
| 4065 | (default: |TRUE|) |
| 4066 | |
| 4067 | simplify If |TRUE|, include modifiers in the |
| 4068 | character if possible. E.g., return |
| 4069 | the same value for CTRL-I and <Tab>. |
| 4070 | If |FALSE|, don't include modifiers in |
| 4071 | the character. |
| 4072 | (default: |TRUE|) |
| 4073 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4074 | When the user clicks a mouse button, the mouse event will be |
| 4075 | returned. The position can then be found in |v:mouse_col|, |
| 4076 | |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|. |
| 4077 | |getmousepos()| can also be used. Mouse move events will be |
| 4078 | ignored. |
| 4079 | This example positions the mouse as it would normally happen: > |
| 4080 | let c = getchar() |
| 4081 | if c == "\<LeftMouse>" && v:mouse_win > 0 |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 4082 | exe v:mouse_win .. "wincmd w" |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4083 | exe v:mouse_lnum |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 4084 | exe "normal " .. v:mouse_col .. "|" |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4085 | endif |
| 4086 | < |
| 4087 | When using bracketed paste only the first character is |
| 4088 | returned, the rest of the pasted text is dropped. |
| 4089 | |xterm-bracketed-paste|. |
| 4090 | |
| 4091 | There is no prompt, you will somehow have to make clear to the |
| 4092 | user that a character has to be typed. The screen is not |
| 4093 | redrawn, e.g. when resizing the window. When using a popup |
| 4094 | window it should work better with a |popup-filter|. |
| 4095 | |
| 4096 | There is no mapping for the character. |
| 4097 | Key codes are replaced, thus when the user presses the <Del> |
| 4098 | key you get the code for the <Del> key, not the raw character |
| 4099 | sequence. Examples: > |
| 4100 | getchar() == "\<Del>" |
| 4101 | getchar() == "\<S-Left>" |
| 4102 | < This example redefines "f" to ignore case: > |
| 4103 | :nmap f :call FindChar()<CR> |
| 4104 | :function FindChar() |
| 4105 | : let c = nr2char(getchar()) |
| 4106 | : while col('.') < col('$') - 1 |
| 4107 | : normal l |
| 4108 | : if getline('.')[col('.') - 1] ==? c |
| 4109 | : break |
| 4110 | : endif |
| 4111 | : endwhile |
| 4112 | :endfunction |
| 4113 | < |
| 4114 | You may also receive synthetic characters, such as |
| 4115 | |<CursorHold>|. Often you will want to ignore this and get |
| 4116 | another character: > |
| 4117 | :function GetKey() |
| 4118 | : let c = getchar() |
| 4119 | : while c == "\<CursorHold>" |
| 4120 | : let c = getchar() |
| 4121 | : endwhile |
| 4122 | : return c |
| 4123 | :endfunction |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4124 | < |
| 4125 | Return type: |Number| or |String| |
| 4126 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4127 | |
| 4128 | getcharmod() *getcharmod()* |
| 4129 | The result is a Number which is the state of the modifiers for |
| 4130 | the last obtained character with getchar() or in another way. |
| 4131 | These values are added together: |
| 4132 | 2 shift |
| 4133 | 4 control |
| 4134 | 8 alt (meta) |
| 4135 | 16 meta (when it's different from ALT) |
| 4136 | 32 mouse double click |
| 4137 | 64 mouse triple click |
| 4138 | 96 mouse quadruple click (== 32 + 64) |
Casey Tucker | 92e90a1 | 2024-01-25 22:44:00 +0100 | [diff] [blame] | 4139 | 128 command (Mac) or super (GTK) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4140 | Only the modifiers that have not been included in the |
| 4141 | character itself are obtained. Thus Shift-a results in "A" |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 4142 | without a modifier. Returns 0 if no modifiers are used. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4143 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4144 | Return type: |Number| |
| 4145 | |
| 4146 | |
| 4147 | getcharpos({expr}) *getcharpos()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4148 | Get the position for String {expr}. Same as |getpos()| but the |
| 4149 | column number in the returned List is a character index |
| 4150 | instead of a byte index. |
naohiro ono | 56200ee | 2022-01-01 14:59:44 +0000 | [diff] [blame] | 4151 | If |getpos()| returns a very large column number, equal to |
| 4152 | |v:maxcol|, then getcharpos() will return the character index |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4153 | of the last character. |
| 4154 | |
| 4155 | Example: |
| 4156 | With the cursor on '세' in line 5 with text "여보세요": > |
| 4157 | getcharpos('.') returns [0, 5, 3, 0] |
| 4158 | getpos('.') returns [0, 5, 7, 0] |
| 4159 | < |
| 4160 | Can also be used as a |method|: > |
| 4161 | GetMark()->getcharpos() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4162 | < |
| 4163 | Return type: list<number> |
| 4164 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4165 | |
| 4166 | getcharsearch() *getcharsearch()* |
| 4167 | Return the current character search information as a {dict} |
| 4168 | with the following entries: |
| 4169 | |
| 4170 | char character previously used for a character |
| 4171 | search (|t|, |f|, |T|, or |F|); empty string |
| 4172 | if no character search has been performed |
| 4173 | forward direction of character search; 1 for forward, |
| 4174 | 0 for backward |
| 4175 | until type of character search; 1 for a |t| or |T| |
| 4176 | character search, 0 for an |f| or |F| |
| 4177 | character search |
| 4178 | |
| 4179 | This can be useful to always have |;| and |,| search |
| 4180 | forward/backward regardless of the direction of the previous |
| 4181 | character search: > |
| 4182 | :nnoremap <expr> ; getcharsearch().forward ? ';' : ',' |
| 4183 | :nnoremap <expr> , getcharsearch().forward ? ',' : ';' |
| 4184 | < Also see |setcharsearch()|. |
| 4185 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4186 | Return type: dict<any> |
| 4187 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4188 | |
zeertzjq | e0a2ab3 | 2025-02-02 09:14:35 +0100 | [diff] [blame] | 4189 | getcharstr([{expr} [, {opts}]]) *getcharstr()* |
| 4190 | The same as |getchar()|, except that this always returns a |
| 4191 | String, and "number" isn't allowed in {opts}. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4192 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4193 | Return type: |String| |
| 4194 | |
Ruslan Russkikh | 0407d62 | 2024-10-08 22:21:05 +0200 | [diff] [blame] | 4195 | getcmdcomplpat() *getcmdcomplpat()* |
| 4196 | Return completion pattern of the current command-line. |
| 4197 | Only works when the command line is being edited, thus |
| 4198 | requires use of |c_CTRL-\_e| or |c_CTRL-R_=|. |
| 4199 | Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()|, |
| 4200 | |getcmdprompt()|, |getcmdcompltype()| and |setcmdline()|. |
| 4201 | Returns an empty string when completion is not defined. |
| 4202 | |
| 4203 | Return type: |String| |
| 4204 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4205 | |
Hirohito Higashi | 96b3ef2 | 2025-07-05 15:31:23 +0200 | [diff] [blame] | 4206 | getcmdcompltype() *getcmdcompltype()* |
| 4207 | Return the type of the current command-line completion. |
| 4208 | Only works when the command line is being edited, thus |
| 4209 | requires use of |c_CTRL-\_e| or |c_CTRL-R_=|. |
Bram Moolenaar | 921bde8 | 2022-05-09 19:50:35 +0100 | [diff] [blame] | 4210 | See |:command-completion| for the return string. |
Shougo Matsushita | 6908428 | 2024-09-23 20:34:47 +0200 | [diff] [blame] | 4211 | Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()|, |
Ruslan Russkikh | 0407d62 | 2024-10-08 22:21:05 +0200 | [diff] [blame] | 4212 | |getcmdprompt()|, |getcmdcomplpat()| and |setcmdline()|. |
Shougo Matsushita | 79d599b | 2022-05-07 12:48:29 +0100 | [diff] [blame] | 4213 | Returns an empty string when completion is not defined. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4214 | |
zeertzjq | e2c0f81 | 2025-07-06 20:26:56 +0200 | [diff] [blame] | 4215 | To get the type of the command-line completion for a specified |
| 4216 | string, use |getcompletiontype()|. |
Hirohito Higashi | 96b3ef2 | 2025-07-05 15:31:23 +0200 | [diff] [blame] | 4217 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4218 | Return type: |String| |
| 4219 | |
| 4220 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4221 | getcmdline() *getcmdline()* |
Shougo Matsushita | 6908428 | 2024-09-23 20:34:47 +0200 | [diff] [blame] | 4222 | Return the current command-line input. Only works when the |
| 4223 | command line is being edited, thus requires use of |
| 4224 | |c_CTRL-\_e| or |c_CTRL-R_=|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4225 | Example: > |
| 4226 | :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR> |
Shougo Matsushita | 6908428 | 2024-09-23 20:34:47 +0200 | [diff] [blame] | 4227 | < Also see |getcmdtype()|, |getcmdpos()|, |setcmdpos()|, |
| 4228 | |getcmdprompt()| and |setcmdline()|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4229 | Returns an empty string when entering a password or using |
| 4230 | |inputsecret()|. |
| 4231 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4232 | Return type: |String| |
| 4233 | |
| 4234 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4235 | getcmdpos() *getcmdpos()* |
| 4236 | Return the position of the cursor in the command line as a |
| 4237 | byte count. The first column is 1. |
| 4238 | Only works when editing the command line, thus requires use of |
| 4239 | |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping. |
| 4240 | Returns 0 otherwise. |
Shougo Matsushita | 6908428 | 2024-09-23 20:34:47 +0200 | [diff] [blame] | 4241 | Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()|, |
| 4242 | |getcmdprompt()| and |setcmdline()|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4243 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4244 | Return type: |Number| |
| 4245 | |
| 4246 | |
Shougo Matsushita | 6908428 | 2024-09-23 20:34:47 +0200 | [diff] [blame] | 4247 | getcmdprompt() *getcmdprompt()* |
| 4248 | Return the current command-line prompt when using functions |
| 4249 | like |input()| or |confirm()|. |
| 4250 | Only works when the command line is being edited, thus |
| 4251 | requires use of |c_CTRL-\_e| or |c_CTRL-R_=|. |
| 4252 | Also see |getcmdtype()|, |getcmdline()|, |getcmdpos()|, |
| 4253 | |setcmdpos()| and |setcmdline()|. |
| 4254 | |
| 4255 | Return type: |String| |
| 4256 | |
| 4257 | |
Shougo Matsushita | 79d599b | 2022-05-07 12:48:29 +0100 | [diff] [blame] | 4258 | getcmdscreenpos() *getcmdscreenpos()* |
| 4259 | Return the screen position of the cursor in the command line |
| 4260 | as a byte count. The first column is 1. |
| 4261 | Instead of |getcmdpos()|, it adds the prompt position. |
| 4262 | Only works when editing the command line, thus requires use of |
| 4263 | |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping. |
| 4264 | Returns 0 otherwise. |
Shougo Matsushita | 07ea5f1 | 2022-08-27 12:22:25 +0100 | [diff] [blame] | 4265 | Also see |getcmdpos()|, |setcmdpos()|, |getcmdline()| and |
| 4266 | |setcmdline()|. |
Shougo Matsushita | 79d599b | 2022-05-07 12:48:29 +0100 | [diff] [blame] | 4267 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4268 | Return type: |Number| |
| 4269 | |
| 4270 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4271 | getcmdtype() *getcmdtype()* |
| 4272 | Return the current command-line type. Possible return values |
| 4273 | are: |
| 4274 | : normal Ex command |
| 4275 | > debug mode command |debug-mode| |
| 4276 | / forward search command |
| 4277 | ? backward search command |
| 4278 | @ |input()| command |
| 4279 | - |:insert| or |:append| command |
| 4280 | = |i_CTRL-R_=| |
| 4281 | Only works when editing the command line, thus requires use of |
| 4282 | |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping. |
| 4283 | Returns an empty string otherwise. |
| 4284 | Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|. |
| 4285 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4286 | Return type: |String| |
| 4287 | |
| 4288 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4289 | getcmdwintype() *getcmdwintype()* |
| 4290 | Return the current |command-line-window| type. Possible return |
| 4291 | values are the same as |getcmdtype()|. Returns an empty string |
| 4292 | when not in the command-line window. |
| 4293 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4294 | Return type: |String| |
| 4295 | |
| 4296 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4297 | getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* |
| 4298 | Return a list of command-line completion matches. The String |
| 4299 | {type} argument specifies what for. The following completion |
| 4300 | types are supported: |
| 4301 | |
| 4302 | arglist file names in argument list |
| 4303 | augroup autocmd groups |
| 4304 | buffer buffer names |
Bram Moolenaar | 6e2e2cc | 2022-03-14 19:24:46 +0000 | [diff] [blame] | 4305 | behave |:behave| suboptions |
| 4306 | breakpoint |:breakadd| and |:breakdel| suboptions |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4307 | color color schemes |
| 4308 | command Ex command |
| 4309 | cmdline |cmdline-completion| result |
| 4310 | compiler compilers |
| 4311 | cscope |:cscope| suboptions |
Shougo Matsushita | 92997dd | 2023-08-20 20:55:55 +0200 | [diff] [blame] | 4312 | custom,{func} custom completion, defined via {func} |
| 4313 | customlist,{func} custom completion, defined via {func} |
zeertzjq | 85f36d6 | 2024-10-10 19:14:13 +0200 | [diff] [blame] | 4314 | diff_buffer |:diffget| and |:diffput| completion |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4315 | dir directory names |
LemonBoy | a20bf69 | 2024-07-11 22:35:53 +0200 | [diff] [blame] | 4316 | dir_in_path directory names in |'cdpath'| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4317 | environment environment variable names |
| 4318 | event autocommand events |
| 4319 | expression Vim expression |
| 4320 | file file and directory names |
| 4321 | file_in_path file and directory names in |'path'| |
| 4322 | filetype filetype names |'filetype'| |
Christian Brabandt | a3422aa | 2025-04-23 21:04:24 +0200 | [diff] [blame] | 4323 | filetypecmd |:filetype| suboptions |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4324 | function function name |
| 4325 | help help subjects |
| 4326 | highlight highlight groups |
Bram Moolenaar | 6e2e2cc | 2022-03-14 19:24:46 +0000 | [diff] [blame] | 4327 | history |:history| suboptions |
Doug Kearns | 81642d9 | 2024-01-04 22:37:44 +0100 | [diff] [blame] | 4328 | keymap keyboard mappings |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4329 | locale locale names (as output of locale -a) |
| 4330 | mapclear buffer argument |
| 4331 | mapping mapping name |
| 4332 | menu menus |
| 4333 | messages |:messages| suboptions |
| 4334 | option options |
| 4335 | packadd optional package |pack-add| names |
zeertzjq | 5c8771b | 2023-01-24 12:34:03 +0000 | [diff] [blame] | 4336 | runtime |:runtime| completion |
Yegappan Lakshmanan | 454ce67 | 2022-03-24 11:22:13 +0000 | [diff] [blame] | 4337 | scriptnames sourced script names |:scriptnames| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4338 | shellcmd Shell command |
zeertzjq | 85f36d6 | 2024-10-10 19:14:13 +0200 | [diff] [blame] | 4339 | shellcmdline Shell command line with filename arguments |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4340 | sign |:sign| suboptions |
| 4341 | syntax syntax file names |'syntax'| |
| 4342 | syntime |:syntime| suboptions |
| 4343 | tag tags |
| 4344 | tag_listfiles tags, file names |
| 4345 | user user names |
| 4346 | var user variables |
| 4347 | |
| 4348 | If {pat} is an empty string, then all the matches are |
| 4349 | returned. Otherwise only items matching {pat} are returned. |
| 4350 | See |wildcards| for the use of special characters in {pat}. |
| 4351 | |
| 4352 | If the optional {filtered} flag is set to 1, then 'wildignore' |
| 4353 | is applied to filter the results. Otherwise all the matches |
| 4354 | are returned. The 'wildignorecase' option always applies. |
| 4355 | |
Yegappan Lakshmanan | e7dd0fa | 2022-03-22 16:06:31 +0000 | [diff] [blame] | 4356 | If the 'wildoptions' option contains 'fuzzy', then fuzzy |
| 4357 | matching is used to get the completion matches. Otherwise |
Yegappan Lakshmanan | 454ce67 | 2022-03-24 11:22:13 +0000 | [diff] [blame] | 4358 | regular expression matching is used. Thus this function |
| 4359 | follows the user preference, what happens on the command line. |
| 4360 | If you do not want this you can make 'wildoptions' empty |
| 4361 | before calling getcompletion() and restore it afterwards. |
Yegappan Lakshmanan | e7dd0fa | 2022-03-22 16:06:31 +0000 | [diff] [blame] | 4362 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4363 | If {type} is "cmdline", then the |cmdline-completion| result is |
| 4364 | returned. For example, to complete the possible values after |
| 4365 | a ":call" command: > |
| 4366 | echo getcompletion('call ', 'cmdline') |
| 4367 | < |
| 4368 | If there are no matches, an empty list is returned. An |
| 4369 | invalid value for {type} produces an error. |
| 4370 | |
| 4371 | Can also be used as a |method|: > |
| 4372 | GetPattern()->getcompletion('color') |
| 4373 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4374 | Return type: list<string> |
| 4375 | |
Hirohito Higashi | 96b3ef2 | 2025-07-05 15:31:23 +0200 | [diff] [blame] | 4376 | getcompletiontype({pat}) *getcompletiontype()* |
| 4377 | Return the type of the command-line completion using {pat}. |
| 4378 | When no corresponding completion type is found, an empty |
| 4379 | string is returned. |
| 4380 | To get the current command-line completion type, use |
| 4381 | |getcmdcompltype()|. |
| 4382 | |
| 4383 | Return type: |String| |
| 4384 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4385 | *getcurpos()* |
| 4386 | getcurpos([{winid}]) |
| 4387 | Get the position of the cursor. This is like getpos('.'), but |
| 4388 | includes an extra "curswant" item in the list: |
| 4389 | [0, lnum, col, off, curswant] ~ |
| 4390 | The "curswant" number is the preferred column when moving the |
naohiro ono | 56200ee | 2022-01-01 14:59:44 +0000 | [diff] [blame] | 4391 | cursor vertically. After |$| command it will be a very large |
| 4392 | number equal to |v:maxcol|. Also see |getcursorcharpos()| and |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4393 | |getpos()|. |
| 4394 | The first "bufnum" item is always zero. The byte position of |
| 4395 | the cursor is returned in 'col'. To get the character |
| 4396 | position, use |getcursorcharpos()|. |
| 4397 | |
| 4398 | The optional {winid} argument can specify the window. It can |
| 4399 | be the window number or the |window-ID|. The last known |
| 4400 | cursor position is returned, this may be invalid for the |
| 4401 | current value of the buffer if it is not the current window. |
| 4402 | If {winid} is invalid a list with zeroes is returned. |
| 4403 | |
| 4404 | This can be used to save and restore the cursor position: > |
| 4405 | let save_cursor = getcurpos() |
| 4406 | MoveTheCursorAround |
| 4407 | call setpos('.', save_cursor) |
| 4408 | < Note that this only works within the window. See |
| 4409 | |winrestview()| for restoring more state. |
| 4410 | |
| 4411 | Can also be used as a |method|: > |
| 4412 | GetWinid()->getcurpos() |
| 4413 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4414 | Return type: list<number> |
| 4415 | |
| 4416 | |
| 4417 | getcursorcharpos([{winid}]) *getcursorcharpos()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4418 | Same as |getcurpos()| but the column number in the returned |
| 4419 | List is a character index instead of a byte index. |
| 4420 | |
| 4421 | Example: |
| 4422 | With the cursor on '보' in line 3 with text "여보세요": > |
| 4423 | getcursorcharpos() returns [0, 3, 2, 0, 3] |
| 4424 | getcurpos() returns [0, 3, 4, 0, 3] |
| 4425 | < |
| 4426 | Can also be used as a |method|: > |
| 4427 | GetWinid()->getcursorcharpos() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4428 | < |
| 4429 | Return type: list<number> |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4430 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4431 | |
| 4432 | getcwd([{winnr} [, {tabnr}]]) *getcwd()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4433 | The result is a String, which is the name of the current |
| 4434 | working directory. 'autochdir' is ignored. |
| 4435 | |
| 4436 | With {winnr} return the local current directory of this window |
| 4437 | in the current tab page. {winnr} can be the window number or |
| 4438 | the |window-ID|. |
| 4439 | If {winnr} is -1 return the name of the global working |
| 4440 | directory. See also |haslocaldir()|. |
| 4441 | |
| 4442 | With {winnr} and {tabnr} return the local current directory of |
| 4443 | the window in the specified tab page. If {winnr} is -1 return |
| 4444 | the working directory of the tabpage. |
| 4445 | If {winnr} is zero use the current window, if {tabnr} is zero |
| 4446 | use the current tabpage. |
| 4447 | Without any arguments, return the actual working directory of |
| 4448 | the current window. |
| 4449 | Return an empty string if the arguments are invalid. |
| 4450 | |
| 4451 | Examples: > |
| 4452 | " Get the working directory of the current window |
| 4453 | :echo getcwd() |
| 4454 | :echo getcwd(0) |
| 4455 | :echo getcwd(0, 0) |
| 4456 | " Get the working directory of window 3 in tabpage 2 |
| 4457 | :echo getcwd(3, 2) |
| 4458 | " Get the global working directory |
| 4459 | :echo getcwd(-1) |
| 4460 | " Get the working directory of tabpage 3 |
| 4461 | :echo getcwd(-1, 3) |
| 4462 | " Get the working directory of current tabpage |
| 4463 | :echo getcwd(-1, 0) |
| 4464 | |
| 4465 | < Can also be used as a |method|: > |
| 4466 | GetWinnr()->getcwd() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4467 | < |
| 4468 | Return type: |String| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4469 | |
| 4470 | getenv({name}) *getenv()* |
| 4471 | Return the value of environment variable {name}. The {name} |
| 4472 | argument is a string, without a leading '$'. Example: > |
| 4473 | myHome = getenv('HOME') |
| 4474 | |
| 4475 | < When the variable does not exist |v:null| is returned. That |
| 4476 | is different from a variable set to an empty string, although |
| 4477 | some systems interpret the empty value as the variable being |
| 4478 | deleted. See also |expr-env|. |
| 4479 | |
| 4480 | Can also be used as a |method|: > |
| 4481 | GetVarname()->getenv() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4482 | < |
| 4483 | Return type: |String| or |Number| |
| 4484 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4485 | |
| 4486 | getfontname([{name}]) *getfontname()* |
| 4487 | Without an argument returns the name of the normal font being |
| 4488 | used. Like what is used for the Normal highlight group |
| 4489 | |hl-Normal|. |
| 4490 | With an argument a check is done whether String {name} is a |
| 4491 | valid font name. If not then an empty string is returned. |
| 4492 | Otherwise the actual font name is returned, or {name} if the |
| 4493 | GUI does not support obtaining the real name. |
| 4494 | Only works when the GUI is running, thus not in your vimrc or |
| 4495 | gvimrc file. Use the |GUIEnter| autocommand to use this |
| 4496 | function just after the GUI has started. |
| 4497 | Note that the GTK GUI accepts any font name, thus checking for |
| 4498 | a valid name does not work. |
| 4499 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4500 | Return type: |String| |
| 4501 | |
| 4502 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4503 | getfperm({fname}) *getfperm()* |
| 4504 | The result is a String, which is the read, write, and execute |
| 4505 | permissions of the given file {fname}. |
| 4506 | If {fname} does not exist or its directory cannot be read, an |
| 4507 | empty string is returned. |
| 4508 | The result is of the form "rwxrwxrwx", where each group of |
| 4509 | "rwx" flags represent, in turn, the permissions of the owner |
| 4510 | of the file, the group the file belongs to, and other users. |
| 4511 | If a user does not have a given permission the flag for this |
| 4512 | is replaced with the string "-". Examples: > |
| 4513 | :echo getfperm("/etc/passwd") |
| 4514 | :echo getfperm(expand("~/.vimrc")) |
| 4515 | < This will hopefully (from a security point of view) display |
| 4516 | the string "rw-r--r--" or even "rw-------". |
| 4517 | |
| 4518 | Can also be used as a |method|: > |
| 4519 | GetFilename()->getfperm() |
| 4520 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4521 | Return type: |String| |
| 4522 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4523 | For setting permissions use |setfperm()|. |
| 4524 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4525 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4526 | getfsize({fname}) *getfsize()* |
| 4527 | The result is a Number, which is the size in bytes of the |
| 4528 | given file {fname}. |
| 4529 | If {fname} is a directory, 0 is returned. |
| 4530 | If the file {fname} can't be found, -1 is returned. |
| 4531 | If the size of {fname} is too big to fit in a Number then -2 |
| 4532 | is returned. |
| 4533 | |
| 4534 | Can also be used as a |method|: > |
| 4535 | GetFilename()->getfsize() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4536 | < |
| 4537 | Return type: |Number| |
| 4538 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4539 | |
| 4540 | getftime({fname}) *getftime()* |
| 4541 | The result is a Number, which is the last modification time of |
| 4542 | the given file {fname}. The value is measured as seconds |
| 4543 | since 1st Jan 1970, and may be passed to strftime(). See also |
| 4544 | |localtime()| and |strftime()|. |
| 4545 | If the file {fname} can't be found -1 is returned. |
| 4546 | |
| 4547 | Can also be used as a |method|: > |
| 4548 | GetFilename()->getftime() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4549 | < |
| 4550 | Return type: |Number| |
| 4551 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4552 | |
| 4553 | getftype({fname}) *getftype()* |
| 4554 | The result is a String, which is a description of the kind of |
| 4555 | file of the given file {fname}. |
| 4556 | If {fname} does not exist an empty string is returned. |
| 4557 | Here is a table over different kinds of files and their |
| 4558 | results: |
| 4559 | Normal file "file" |
| 4560 | Directory "dir" |
| 4561 | Symbolic link "link" |
| 4562 | Block device "bdev" |
| 4563 | Character device "cdev" |
| 4564 | Socket "socket" |
| 4565 | FIFO "fifo" |
| 4566 | All other "other" |
| 4567 | Example: > |
| 4568 | getftype("/home") |
| 4569 | < Note that a type such as "link" will only be returned on |
| 4570 | systems that support it. On some systems only "dir" and |
| 4571 | "file" are returned. On MS-Windows a symbolic link to a |
| 4572 | directory returns "dir" instead of "link". |
| 4573 | |
| 4574 | Can also be used as a |method|: > |
| 4575 | GetFilename()->getftype() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4576 | < |
| 4577 | Return type: |String| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4578 | |
| 4579 | getimstatus() *getimstatus()* |
| 4580 | The result is a Number, which is |TRUE| when the IME status is |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 4581 | active and |FALSE| otherwise. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4582 | See 'imstatusfunc'. |
| 4583 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4584 | Return type: |Number| |
| 4585 | |
| 4586 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4587 | getjumplist([{winnr} [, {tabnr}]]) *getjumplist()* |
| 4588 | Returns the |jumplist| for the specified window. |
| 4589 | |
| 4590 | Without arguments use the current window. |
| 4591 | With {winnr} only use this window in the current tab page. |
| 4592 | {winnr} can also be a |window-ID|. |
| 4593 | With {winnr} and {tabnr} use the window in the specified tab |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 4594 | page. If {winnr} or {tabnr} is invalid, an empty list is |
| 4595 | returned. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4596 | |
| 4597 | The returned list contains two entries: a list with the jump |
| 4598 | locations and the last used jump position number in the list. |
| 4599 | Each entry in the jump location list is a dictionary with |
| 4600 | the following entries: |
| 4601 | bufnr buffer number |
| 4602 | col column number |
| 4603 | coladd column offset for 'virtualedit' |
| 4604 | filename filename if available |
| 4605 | lnum line number |
| 4606 | |
| 4607 | Can also be used as a |method|: > |
| 4608 | GetWinnr()->getjumplist() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4609 | < |
| 4610 | Return type: list<any> |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4611 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4612 | *getline()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4613 | getline({lnum} [, {end}]) |
| 4614 | Without {end} the result is a String, which is line {lnum} |
| 4615 | from the current buffer. Example: > |
| 4616 | getline(1) |
| 4617 | < When {lnum} is a String that doesn't start with a |
| 4618 | digit, |line()| is called to translate the String into a Number. |
| 4619 | To get the line under the cursor: > |
| 4620 | getline(".") |
| 4621 | < When {lnum} is a number smaller than 1 or bigger than the |
| 4622 | number of lines in the buffer, an empty string is returned. |
| 4623 | |
| 4624 | When {end} is given the result is a |List| where each item is |
| 4625 | a line from the current buffer in the range {lnum} to {end}, |
| 4626 | including line {end}. |
| 4627 | {end} is used in the same way as {lnum}. |
| 4628 | Non-existing lines are silently omitted. |
| 4629 | When {end} is before {lnum} an empty |List| is returned. |
| 4630 | Example: > |
| 4631 | :let start = line('.') |
| 4632 | :let end = search("^$") - 1 |
| 4633 | :let lines = getline(start, end) |
| 4634 | |
| 4635 | < Can also be used as a |method|: > |
| 4636 | ComputeLnum()->getline() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4637 | < |
| 4638 | Return type: list<string> or |String| depending on {end} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4639 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4640 | To get lines from another buffer see |getbufline()| and |
Bram Moolenaar | ce30ccc | 2022-11-21 19:57:04 +0000 | [diff] [blame] | 4641 | |getbufoneline()| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4642 | |
| 4643 | getloclist({nr} [, {what}]) *getloclist()* |
| 4644 | Returns a |List| with all the entries in the location list for |
| 4645 | window {nr}. {nr} can be the window number or the |window-ID|. |
| 4646 | When {nr} is zero the current window is used. |
| 4647 | |
| 4648 | For a location list window, the displayed location list is |
| 4649 | returned. For an invalid window number {nr}, an empty list is |
| 4650 | returned. Otherwise, same as |getqflist()|. |
| 4651 | |
| 4652 | If the optional {what} dictionary argument is supplied, then |
| 4653 | returns the items listed in {what} as a dictionary. Refer to |
| 4654 | |getqflist()| for the supported items in {what}. |
| 4655 | |
| 4656 | In addition to the items supported by |getqflist()| in {what}, |
| 4657 | the following item is supported by |getloclist()|: |
| 4658 | |
| 4659 | filewinid id of the window used to display files |
| 4660 | from the location list. This field is |
| 4661 | applicable only when called from a |
| 4662 | location list window. See |
| 4663 | |location-list-file-window| for more |
| 4664 | details. |
| 4665 | |
| 4666 | Returns a |Dictionary| with default values if there is no |
| 4667 | location list for the window {nr}. |
| 4668 | Returns an empty Dictionary if window {nr} does not exist. |
| 4669 | |
| 4670 | Examples (See also |getqflist-examples|): > |
| 4671 | :echo getloclist(3, {'all': 0}) |
| 4672 | :echo getloclist(5, {'filewinid': 0}) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4673 | < |
| 4674 | Return type: list<dict<any>> or list<any> |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4675 | |
| 4676 | |
| 4677 | getmarklist([{buf}]) *getmarklist()* |
| 4678 | Without the {buf} argument returns a |List| with information |
| 4679 | about all the global marks. |mark| |
| 4680 | |
| 4681 | If the optional {buf} argument is specified, returns the |
| 4682 | local marks defined in buffer {buf}. For the use of {buf}, |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 4683 | see |bufname()|. If {buf} is invalid, an empty list is |
| 4684 | returned. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4685 | |
| 4686 | Each item in the returned List is a |Dict| with the following: |
| 4687 | mark name of the mark prefixed by "'" |
| 4688 | pos a |List| with the position of the mark: |
| 4689 | [bufnum, lnum, col, off] |
| 4690 | Refer to |getpos()| for more information. |
| 4691 | file file name |
| 4692 | |
| 4693 | Refer to |getpos()| for getting information about a specific |
| 4694 | mark. |
| 4695 | |
| 4696 | Can also be used as a |method|: > |
| 4697 | GetBufnr()->getmarklist() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4698 | < |
| 4699 | Return type: list<dict<any>> or list<any> |
| 4700 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4701 | |
| 4702 | getmatches([{win}]) *getmatches()* |
| 4703 | Returns a |List| with all matches previously defined for the |
| 4704 | current window by |matchadd()| and the |:match| commands. |
| 4705 | |getmatches()| is useful in combination with |setmatches()|, |
| 4706 | as |setmatches()| can restore a list of matches saved by |
| 4707 | |getmatches()|. |
| 4708 | If {win} is specified, use the window with this number or |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 4709 | window ID instead of the current window. If {win} is invalid, |
| 4710 | an empty list is returned. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4711 | Example: > |
| 4712 | :echo getmatches() |
| 4713 | < [{'group': 'MyGroup1', 'pattern': 'TODO', |
| 4714 | 'priority': 10, 'id': 1}, {'group': 'MyGroup2', |
| 4715 | 'pattern': 'FIXME', 'priority': 10, 'id': 2}] > |
| 4716 | :let m = getmatches() |
| 4717 | :call clearmatches() |
| 4718 | :echo getmatches() |
| 4719 | < [] > |
| 4720 | :call setmatches(m) |
| 4721 | :echo getmatches() |
| 4722 | < [{'group': 'MyGroup1', 'pattern': 'TODO', |
| 4723 | 'priority': 10, 'id': 1}, {'group': 'MyGroup2', |
| 4724 | 'pattern': 'FIXME', 'priority': 10, 'id': 2}] > |
| 4725 | :unlet m |
| 4726 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4727 | Return type: list<dict<any>> or list<any> |
| 4728 | |
| 4729 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4730 | getmousepos() *getmousepos()* |
| 4731 | Returns a |Dictionary| with the last known position of the |
| 4732 | mouse. This can be used in a mapping for a mouse click or in |
| 4733 | a filter of a popup window. The items are: |
| 4734 | screenrow screen row |
| 4735 | screencol screen column |
| 4736 | winid Window ID of the click |
| 4737 | winrow row inside "winid" |
| 4738 | wincol column inside "winid" |
| 4739 | line text line inside "winid" |
| 4740 | column text column inside "winid" |
zeertzjq | f5a94d5 | 2023-10-15 10:03:30 +0200 | [diff] [blame] | 4741 | coladd offset (in screen columns) from the |
| 4742 | start of the clicked char |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4743 | All numbers are 1-based. |
| 4744 | |
Hirohito Higashi | 3b9b95d | 2025-06-01 20:22:55 +0200 | [diff] [blame] | 4745 | If not over a window, e.g. when in the command line or within |
| 4746 | |tabpanel|, then only "screenrow" and "screencol" are valid, |
| 4747 | the others are zero. |
Naruhiko Nishino | be5bd4d | 2025-05-14 21:20:28 +0200 | [diff] [blame] | 4748 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4749 | When on the status line below a window or the vertical |
| 4750 | separator right of a window, the "line" and "column" values |
| 4751 | are zero. |
| 4752 | |
| 4753 | When the position is after the text then "column" is the |
| 4754 | length of the text in bytes plus one. |
| 4755 | |
| 4756 | If the mouse is over a popup window then that window is used. |
| 4757 | |
| 4758 | When using |getchar()| the Vim variables |v:mouse_lnum|, |
| 4759 | |v:mouse_col| and |v:mouse_winid| also provide these values. |
| 4760 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4761 | Return type: dict<number> |
| 4762 | |
| 4763 | |
Bram Moolenaar | 24dc19c | 2022-11-14 19:49:15 +0000 | [diff] [blame] | 4764 | getmouseshape() *getmouseshape()* |
| 4765 | Returns the name of the currently showing mouse pointer. |
| 4766 | When the |+mouseshape| feature is not supported or the shape |
| 4767 | is unknown an empty string is returned. |
| 4768 | This function is mainly intended for testing. |
| 4769 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4770 | Return type: |String| |
| 4771 | |
| 4772 | |
| 4773 | getpid() *getpid()* |
| 4774 | Return a Number which is the process ID of the Vim process. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4775 | On Unix and MS-Windows this is a unique number, until Vim |
| 4776 | exits. |
| 4777 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4778 | Return type: |Number| |
| 4779 | |
| 4780 | |
| 4781 | getpos({expr}) *getpos()* |
zeertzjq | 02f3eba | 2024-06-12 20:45:24 +0200 | [diff] [blame] | 4782 | Get the position for String {expr}. |
| 4783 | The accepted values for {expr} are: *E1209* |
| 4784 | . The cursor position. |
| 4785 | $ The last line in the current buffer. |
| 4786 | 'x Position of mark x (if the mark is not set, 0 is |
zeertzjq | d353d27 | 2024-06-13 23:00:25 +0800 | [diff] [blame] | 4787 | returned for all values). |
zeertzjq | 02f3eba | 2024-06-12 20:45:24 +0200 | [diff] [blame] | 4788 | w0 First line visible in current window (one if the |
| 4789 | display isn't updated, e.g. in silent Ex mode). |
| 4790 | w$ Last line visible in current window (this is one |
| 4791 | less than "w0" if no lines are visible). |
| 4792 | v When not in Visual mode, returns the cursor |
| 4793 | position. In Visual mode, returns the other end |
| 4794 | of the Visual area. A good way to think about |
| 4795 | this is that in Visual mode "v" and "." complement |
| 4796 | each other. While "." refers to the cursor |
| 4797 | position, "v" refers to where |v_o| would move the |
| 4798 | cursor. As a result, you can use "v" and "." |
| 4799 | together to work on all of a selection in |
| 4800 | characterwise Visual mode. If the cursor is at |
| 4801 | the end of a characterwise Visual area, "v" refers |
| 4802 | to the start of the same Visual area. And if the |
| 4803 | cursor is at the start of a characterwise Visual |
| 4804 | area, "v" refers to the end of the same Visual |
| 4805 | area. "v" differs from |'<| and |'>| in that it's |
| 4806 | updated right away. |
| 4807 | Note that a mark in another file can be used. The line number |
| 4808 | then applies to another buffer. |
| 4809 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4810 | The result is a |List| with four numbers: |
| 4811 | [bufnum, lnum, col, off] |
| 4812 | "bufnum" is zero, unless a mark like '0 or 'A is used, then it |
| 4813 | is the buffer number of the mark. |
| 4814 | "lnum" and "col" are the position in the buffer. The first |
| 4815 | column is 1. |
| 4816 | The "off" number is zero, unless 'virtualedit' is used. Then |
| 4817 | it is the offset in screen columns from the start of the |
| 4818 | character. E.g., a position within a <Tab> or after the last |
| 4819 | character. |
zeertzjq | 02f3eba | 2024-06-12 20:45:24 +0200 | [diff] [blame] | 4820 | |
| 4821 | For getting the cursor position see |getcurpos()|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4822 | The column number in the returned List is the byte position |
| 4823 | within the line. To get the character position in the line, |
| 4824 | use |getcharpos()|. |
zeertzjq | 02f3eba | 2024-06-12 20:45:24 +0200 | [diff] [blame] | 4825 | |
| 4826 | Note that for '< and '> Visual mode matters: when it is "V" |
| 4827 | (visual line mode) the column of '< is zero and the column of |
| 4828 | '> is a large number equal to |v:maxcol|. |
naohiro ono | 56200ee | 2022-01-01 14:59:44 +0000 | [diff] [blame] | 4829 | A very large column number equal to |v:maxcol| can be returned, |
| 4830 | in which case it means "after the end of the line". |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 4831 | If {expr} is invalid, returns a list with all zeros. |
zeertzjq | 02f3eba | 2024-06-12 20:45:24 +0200 | [diff] [blame] | 4832 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4833 | This can be used to save and restore the position of a mark: > |
| 4834 | let save_a_mark = getpos("'a") |
| 4835 | ... |
| 4836 | call setpos("'a", save_a_mark) |
zeertzjq | d353d27 | 2024-06-13 23:00:25 +0800 | [diff] [blame] | 4837 | < |
| 4838 | Also see |getcharpos()|, |getcurpos()| and |setpos()|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4839 | |
| 4840 | Can also be used as a |method|: > |
| 4841 | GetMark()->getpos() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4842 | < |
| 4843 | Return type: list<number> |
| 4844 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4845 | |
| 4846 | getqflist([{what}]) *getqflist()* |
| 4847 | Returns a |List| with all the current quickfix errors. Each |
| 4848 | list item is a dictionary with these entries: |
| 4849 | bufnr number of buffer that has the file name, use |
| 4850 | bufname() to get the name |
| 4851 | module module name |
| 4852 | lnum line number in the buffer (first line is 1) |
| 4853 | end_lnum |
| 4854 | end of line number if the item is multiline |
| 4855 | col column number (first column is 1) |
| 4856 | end_col end of column number if the item has range |
| 4857 | vcol |TRUE|: "col" is visual column |
| 4858 | |FALSE|: "col" is byte index |
| 4859 | nr error number |
h-east | 84ac212 | 2024-06-17 18:12:30 +0200 | [diff] [blame] | 4860 | pattern search pattern used to locate the error |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4861 | text description of the error |
| 4862 | type type of the error, 'E', '1', etc. |
| 4863 | valid |TRUE|: recognized error message |
h_east | 596a9f2 | 2023-11-21 21:24:23 +0900 | [diff] [blame] | 4864 | user_data |
| 4865 | custom data associated with the item, can be |
Tom Praschan | ca6ac99 | 2023-08-11 23:26:12 +0200 | [diff] [blame] | 4866 | any type. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4867 | |
| 4868 | When there is no error list or it's empty, an empty list is |
| 4869 | returned. Quickfix list entries with a non-existing buffer |
| 4870 | number are returned with "bufnr" set to zero (Note: some |
| 4871 | functions accept buffer number zero for the alternate buffer, |
| 4872 | you may need to explicitly check for zero). |
| 4873 | |
| 4874 | Useful application: Find pattern matches in multiple files and |
| 4875 | do something with them: > |
| 4876 | :vimgrep /theword/jg *.c |
| 4877 | :for d in getqflist() |
| 4878 | : echo bufname(d.bufnr) ':' d.lnum '=' d.text |
| 4879 | :endfor |
| 4880 | < |
| 4881 | If the optional {what} dictionary argument is supplied, then |
| 4882 | returns only the items listed in {what} as a dictionary. The |
| 4883 | following string items are supported in {what}: |
| 4884 | changedtick get the total number of changes made |
| 4885 | to the list |quickfix-changedtick| |
| 4886 | context get the |quickfix-context| |
| 4887 | efm errorformat to use when parsing "lines". If |
| 4888 | not present, then the 'errorformat' option |
| 4889 | value is used. |
| 4890 | id get information for the quickfix list with |
| 4891 | |quickfix-ID|; zero means the id for the |
| 4892 | current list or the list specified by "nr" |
| 4893 | idx get information for the quickfix entry at this |
| 4894 | index in the list specified by 'id' or 'nr'. |
| 4895 | If set to zero, then uses the current entry. |
| 4896 | See |quickfix-index| |
| 4897 | items quickfix list entries |
| 4898 | lines parse a list of lines using 'efm' and return |
| 4899 | the resulting entries. Only a |List| type is |
| 4900 | accepted. The current quickfix list is not |
| 4901 | modified. See |quickfix-parse|. |
| 4902 | nr get information for this quickfix list; zero |
| 4903 | means the current quickfix list and "$" means |
| 4904 | the last quickfix list |
| 4905 | qfbufnr number of the buffer displayed in the quickfix |
| 4906 | window. Returns 0 if the quickfix buffer is |
| 4907 | not present. See |quickfix-buffer|. |
| 4908 | size number of entries in the quickfix list |
| 4909 | title get the list title |quickfix-title| |
| 4910 | winid get the quickfix |window-ID| |
| 4911 | all all of the above quickfix properties |
| 4912 | Non-string items in {what} are ignored. To get the value of a |
| 4913 | particular item, set it to zero. |
| 4914 | If "nr" is not present then the current quickfix list is used. |
| 4915 | If both "nr" and a non-zero "id" are specified, then the list |
| 4916 | specified by "id" is used. |
| 4917 | To get the number of lists in the quickfix stack, set "nr" to |
| 4918 | "$" in {what}. The "nr" value in the returned dictionary |
| 4919 | contains the quickfix stack size. |
| 4920 | When "lines" is specified, all the other items except "efm" |
| 4921 | are ignored. The returned dictionary contains the entry |
| 4922 | "items" with the list of entries. |
| 4923 | |
| 4924 | The returned dictionary contains the following entries: |
| 4925 | changedtick total number of changes made to the |
| 4926 | list |quickfix-changedtick| |
| 4927 | context quickfix list context. See |quickfix-context| |
| 4928 | If not present, set to "". |
| 4929 | id quickfix list ID |quickfix-ID|. If not |
| 4930 | present, set to 0. |
| 4931 | idx index of the quickfix entry in the list. If not |
| 4932 | present, set to 0. |
| 4933 | items quickfix list entries. If not present, set to |
| 4934 | an empty list. |
| 4935 | nr quickfix list number. If not present, set to 0 |
| 4936 | qfbufnr number of the buffer displayed in the quickfix |
| 4937 | window. If not present, set to 0. |
| 4938 | size number of entries in the quickfix list. If not |
| 4939 | present, set to 0. |
| 4940 | title quickfix list title text. If not present, set |
| 4941 | to "". |
| 4942 | winid quickfix |window-ID|. If not present, set to 0 |
| 4943 | |
| 4944 | Examples (See also |getqflist-examples|): > |
| 4945 | :echo getqflist({'all': 1}) |
| 4946 | :echo getqflist({'nr': 2, 'title': 1}) |
| 4947 | :echo getqflist({'lines' : ["F1:10:L10"]}) |
| 4948 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4949 | Return type: list<dict<any>> or list<any> |
| 4950 | |
| 4951 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4952 | getreg([{regname} [, 1 [, {list}]]]) *getreg()* |
| 4953 | The result is a String, which is the contents of register |
| 4954 | {regname}. Example: > |
| 4955 | :let cliptext = getreg('*') |
| 4956 | < When register {regname} was not set the result is an empty |
| 4957 | string. |
Bram Moolenaar | a2baa73 | 2022-02-04 16:09:54 +0000 | [diff] [blame] | 4958 | The {regname} argument must be a string. *E1162* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4959 | |
| 4960 | getreg('=') returns the last evaluated value of the expression |
| 4961 | register. (For use in maps.) |
| 4962 | getreg('=', 1) returns the expression itself, so that it can |
| 4963 | be restored with |setreg()|. For other registers the extra |
| 4964 | argument is ignored, thus you can always give it. |
| 4965 | |
| 4966 | If {list} is present and |TRUE|, the result type is changed |
| 4967 | to |List|. Each list item is one text line. Use it if you care |
| 4968 | about zero bytes possibly present inside register: without |
| 4969 | third argument both NLs and zero bytes are represented as NLs |
| 4970 | (see |NL-used-for-Nul|). |
| 4971 | When the register was not set an empty list is returned. |
| 4972 | |
| 4973 | If {regname} is "", the unnamed register '"' is used. |
| 4974 | If {regname} is not specified, |v:register| is used. |
| 4975 | In |Vim9-script| {regname} must be one character. |
| 4976 | |
| 4977 | Can also be used as a |method|: > |
| 4978 | GetRegname()->getreg() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4979 | < |
Christian Brabandt | 17ad852 | 2025-05-09 00:03:20 +0200 | [diff] [blame] | 4980 | Return type: |String| or list<string> depending on {list} |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 4981 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 4982 | |
| 4983 | getreginfo([{regname}]) *getreginfo()* |
| 4984 | Returns detailed information about register {regname} as a |
| 4985 | Dictionary with the following entries: |
| 4986 | regcontents List of lines contained in register |
| 4987 | {regname}, like |
| 4988 | |getreg|({regname}, 1, 1). |
| 4989 | regtype the type of register {regname}, as in |
| 4990 | |getregtype()|. |
| 4991 | isunnamed Boolean flag, v:true if this register |
| 4992 | is currently pointed to by the unnamed |
| 4993 | register. |
| 4994 | points_to for the unnamed register, gives the |
| 4995 | single letter name of the register |
| 4996 | currently pointed to (see |quotequote|). |
| 4997 | For example, after deleting a line |
| 4998 | with `dd`, this field will be "1", |
| 4999 | which is the register that got the |
| 5000 | deleted text. |
| 5001 | |
| 5002 | The {regname} argument is a string. If {regname} is invalid |
| 5003 | or not set, an empty Dictionary will be returned. |
| 5004 | If {regname} is "" or "@", the unnamed register '"' is used. |
| 5005 | If {regname} is not specified, |v:register| is used. |
| 5006 | The returned Dictionary can be passed to |setreg()|. |
| 5007 | In |Vim9-script| {regname} must be one character. |
| 5008 | |
| 5009 | Can also be used as a |method|: > |
| 5010 | GetRegname()->getreginfo() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5011 | < |
| 5012 | Return type: dict<any> |
| 5013 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5014 | |
Shougo Matsushita | 19b7188 | 2024-02-28 22:48:12 +0100 | [diff] [blame] | 5015 | getregion({pos1}, {pos2} [, {opts}]) *getregion()* |
Shougo Matsushita | 84bf6e6 | 2024-03-06 21:10:18 +0100 | [diff] [blame] | 5016 | Returns the list of strings from {pos1} to {pos2} from a |
Shougo Matsushita | 19b7188 | 2024-02-28 22:48:12 +0100 | [diff] [blame] | 5017 | buffer. |
| 5018 | |
| 5019 | {pos1} and {pos2} must both be |List|s with four numbers. |
Shougo Matsushita | 84bf6e6 | 2024-03-06 21:10:18 +0100 | [diff] [blame] | 5020 | See |getpos()| for the format of the list. It's possible |
| 5021 | to specify positions from a different buffer, but please |
zeertzjq | 0df8f93 | 2024-03-07 21:40:53 +0100 | [diff] [blame] | 5022 | note the limitations at |getregion-notes|. |
Shougo Matsushita | 19b7188 | 2024-02-28 22:48:12 +0100 | [diff] [blame] | 5023 | |
| 5024 | The optional argument {opts} is a Dict and supports the |
| 5025 | following items: |
| 5026 | |
zeertzjq | afc2295 | 2024-05-24 19:07:12 +0200 | [diff] [blame] | 5027 | type Specify the region's selection type. |
| 5028 | See |getregtype()| for possible values, |
zeertzjq | dff55a3 | 2024-05-25 10:25:36 +0200 | [diff] [blame] | 5029 | except that the width can be omitted |
| 5030 | and an empty string cannot be used. |
zeertzjq | afc2295 | 2024-05-24 19:07:12 +0200 | [diff] [blame] | 5031 | (default: "v") |
Shougo Matsushita | 19b7188 | 2024-02-28 22:48:12 +0100 | [diff] [blame] | 5032 | |
zeertzjq | 87410ab | 2024-03-02 06:00:23 +0800 | [diff] [blame] | 5033 | exclusive If |TRUE|, use exclusive selection |
zeertzjq | afc2295 | 2024-05-24 19:07:12 +0200 | [diff] [blame] | 5034 | for the end position. |
zeertzjq | 87410ab | 2024-03-02 06:00:23 +0800 | [diff] [blame] | 5035 | (default: follow 'selection') |
Shougo Matsushita | 19b7188 | 2024-02-28 22:48:12 +0100 | [diff] [blame] | 5036 | |
Shougo Matsushita | 3f905ab | 2024-02-21 00:02:45 +0100 | [diff] [blame] | 5037 | You can get the last selection type by |visualmode()|. |
| 5038 | If Visual mode is active, use |mode()| to get the Visual mode |
| 5039 | (e.g., in a |:vmap|). |
zeertzjq | 87410ab | 2024-03-02 06:00:23 +0800 | [diff] [blame] | 5040 | This function is useful to get text starting and ending in |
| 5041 | different columns, such as a |characterwise-visual| selection. |
Shougo Matsushita | 3f905ab | 2024-02-21 00:02:45 +0100 | [diff] [blame] | 5042 | |
Shougo Matsushita | 84bf6e6 | 2024-03-06 21:10:18 +0100 | [diff] [blame] | 5043 | *getregion-notes* |
Shougo Matsushita | 3f905ab | 2024-02-21 00:02:45 +0100 | [diff] [blame] | 5044 | Note that: |
| 5045 | - Order of {pos1} and {pos2} doesn't matter, it will always |
| 5046 | return content from the upper left position to the lower |
| 5047 | right position. |
zeertzjq | 87410ab | 2024-03-02 06:00:23 +0800 | [diff] [blame] | 5048 | - If 'virtualedit' is enabled and the region is past the end |
| 5049 | of the lines, resulting lines are padded with spaces. |
| 5050 | - If the region is blockwise and it starts or ends in the |
| 5051 | middle of a multi-cell character, it is not included but |
| 5052 | its selected part is substituted with spaces. |
Shougo Matsushita | 84bf6e6 | 2024-03-06 21:10:18 +0100 | [diff] [blame] | 5053 | - If {pos1} and {pos2} are not in the same buffer, an empty |
zeertzjq | 421b597 | 2024-02-22 19:48:06 +0100 | [diff] [blame] | 5054 | list is returned. |
Shougo Matsushita | 84bf6e6 | 2024-03-06 21:10:18 +0100 | [diff] [blame] | 5055 | - {pos1} and {pos2} must belong to a |bufloaded()| buffer. |
zeertzjq | 0df8f93 | 2024-03-07 21:40:53 +0100 | [diff] [blame] | 5056 | - It is evaluated in current window context, which makes a |
| 5057 | difference if the buffer is displayed in a window with |
| 5058 | different 'virtualedit' or 'list' values. |
Christian Brabandt | bfeefc4 | 2025-06-02 19:56:57 +0200 | [diff] [blame] | 5059 | - When specifying an exclusive selection and {pos1} and {pos2} |
| 5060 | are equal, the returned list contains a single character as |
| 5061 | if selection is inclusive, to match the behavior of an empty |
| 5062 | exclusive selection in Visual mode. |
Shougo Matsushita | 3f905ab | 2024-02-21 00:02:45 +0100 | [diff] [blame] | 5063 | |
| 5064 | Examples: > |
| 5065 | :xnoremap <CR> |
Shougo Matsushita | 19b7188 | 2024-02-28 22:48:12 +0100 | [diff] [blame] | 5066 | \ <Cmd>echow getregion( |
| 5067 | \ getpos('v'), getpos('.'), #{ type: mode() })<CR> |
Shougo Matsushita | 3f905ab | 2024-02-21 00:02:45 +0100 | [diff] [blame] | 5068 | < |
| 5069 | Can also be used as a |method|: > |
Shougo Matsushita | 19b7188 | 2024-02-28 22:48:12 +0100 | [diff] [blame] | 5070 | getpos('.')->getregion(getpos("'a")) |
zeertzjq | d4d1207 | 2024-07-16 20:34:16 +0200 | [diff] [blame] | 5071 | < |
| 5072 | Return type: list<string> |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5073 | |
Yee Cheng Chin | d52fb2f | 2024-10-31 09:25:09 +0100 | [diff] [blame] | 5074 | |
Shougo Matsushita | b4757e6 | 2024-05-07 20:49:24 +0200 | [diff] [blame] | 5075 | getregionpos({pos1}, {pos2} [, {opts}]) *getregionpos()* |
| 5076 | Same as |getregion()|, but returns a list of positions |
| 5077 | describing the buffer text segments bound by {pos1} and |
| 5078 | {pos2}. |
| 5079 | The segments are a pair of positions for every line: > |
| 5080 | [[{start_pos}, {end_pos}], ...] |
| 5081 | < |
| 5082 | The position is a |List| with four numbers: |
| 5083 | [bufnum, lnum, col, off] |
| 5084 | "bufnum" is the buffer number. |
| 5085 | "lnum" and "col" are the position in the buffer. The first |
| 5086 | column is 1. |
zeertzjq | c95e64f | 2024-05-20 14:00:31 +0200 | [diff] [blame] | 5087 | If the "off" number of a starting position is non-zero, it is |
| 5088 | the offset in screen columns from the start of the character. |
| 5089 | E.g., a position within a <Tab> or after the last character. |
| 5090 | If the "off" number of an ending position is non-zero, it is |
zeertzjq | 52a6f34 | 2024-05-22 16:42:44 +0200 | [diff] [blame] | 5091 | the offset of the character's first cell not included in the |
| 5092 | selection, otherwise all its cells are included. |
Shougo Matsushita | b4757e6 | 2024-05-07 20:49:24 +0200 | [diff] [blame] | 5093 | |
zeertzjq | 2b09de9 | 2024-05-24 07:48:51 +0200 | [diff] [blame] | 5094 | Apart from the options supported by |getregion()|, {opts} also |
| 5095 | supports the following: |
| 5096 | |
| 5097 | eol If |TRUE|, indicate positions beyond |
| 5098 | the end of a line with "col" values |
| 5099 | one more than the length of the line. |
| 5100 | If |FALSE|, positions are limited |
| 5101 | within their lines, and if a line is |
| 5102 | empty or the selection is entirely |
| 5103 | beyond the end of a line, a "col" |
| 5104 | value of 0 is used for both positions. |
| 5105 | (default: |FALSE|) |
| 5106 | |
Shougo Matsushita | b4757e6 | 2024-05-07 20:49:24 +0200 | [diff] [blame] | 5107 | Can also be used as a |method|: > |
| 5108 | getpos('.')->getregionpos(getpos("'a")) |
| 5109 | < |
Christian Brabandt | 83d7440 | 2025-03-19 21:55:59 +0100 | [diff] [blame] | 5110 | For an example, see the highlight-yank plugin |52.6| |
| 5111 | |
zeertzjq | d4d1207 | 2024-07-16 20:34:16 +0200 | [diff] [blame] | 5112 | Return type: list<list<list<number>>> |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5113 | |
| 5114 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5115 | getregtype([{regname}]) *getregtype()* |
| 5116 | The result is a String, which is type of register {regname}. |
| 5117 | The value will be one of: |
| 5118 | "v" for |characterwise| text |
| 5119 | "V" for |linewise| text |
| 5120 | "<CTRL-V>{width}" for |blockwise-visual| text |
| 5121 | "" for an empty or unknown register |
| 5122 | <CTRL-V> is one character with value 0x16. |
| 5123 | The {regname} argument is a string. If {regname} is "", the |
| 5124 | unnamed register '"' is used. If {regname} is not specified, |
| 5125 | |v:register| is used. |
| 5126 | In |Vim9-script| {regname} must be one character. |
| 5127 | |
| 5128 | Can also be used as a |method|: > |
| 5129 | GetRegname()->getregtype() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5130 | < |
| 5131 | Return type: |String| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5132 | |
Yee Cheng Chin | d52fb2f | 2024-10-31 09:25:09 +0100 | [diff] [blame] | 5133 | |
Bram Moolenaar | 71badf9 | 2023-04-22 22:40:14 +0100 | [diff] [blame] | 5134 | getscriptinfo([{opts}]) *getscriptinfo()* |
Yegappan Lakshmanan | f768c3d | 2022-08-22 13:15:13 +0100 | [diff] [blame] | 5135 | Returns a |List| with information about all the sourced Vim |
Bram Moolenaar | 753885b | 2022-08-24 16:30:36 +0100 | [diff] [blame] | 5136 | scripts in the order they were sourced, like what |
| 5137 | `:scriptnames` shows. |
Yegappan Lakshmanan | f768c3d | 2022-08-22 13:15:13 +0100 | [diff] [blame] | 5138 | |
Yegappan Lakshmanan | 2f892d8 | 2022-08-28 18:52:10 +0100 | [diff] [blame] | 5139 | The optional Dict argument {opts} supports the following |
| 5140 | optional items: |
| 5141 | name Script name match pattern. If specified, |
| 5142 | and "sid" is not specified, information about |
Bram Moolenaar | 71badf9 | 2023-04-22 22:40:14 +0100 | [diff] [blame] | 5143 | scripts with a name that match the pattern |
Yegappan Lakshmanan | 2f892d8 | 2022-08-28 18:52:10 +0100 | [diff] [blame] | 5144 | "name" are returned. |
| 5145 | sid Script ID |<SID>|. If specified, only |
| 5146 | information about the script with ID "sid" is |
| 5147 | returned and "name" is ignored. |
| 5148 | |
Yegappan Lakshmanan | f768c3d | 2022-08-22 13:15:13 +0100 | [diff] [blame] | 5149 | Each item in the returned List is a |Dict| with the following |
| 5150 | items: |
Yegappan Lakshmanan | 2f892d8 | 2022-08-28 18:52:10 +0100 | [diff] [blame] | 5151 | autoload Set to TRUE for a script that was used with |
Bram Moolenaar | 753885b | 2022-08-24 16:30:36 +0100 | [diff] [blame] | 5152 | `import autoload` but was not actually sourced |
| 5153 | yet (see |import-autoload|). |
Yegappan Lakshmanan | 2f892d8 | 2022-08-28 18:52:10 +0100 | [diff] [blame] | 5154 | functions List of script-local function names defined in |
| 5155 | the script. Present only when a particular |
| 5156 | script is specified using the "sid" item in |
| 5157 | {opts}. |
| 5158 | name Vim script file name. |
| 5159 | sid Script ID |<SID>|. |
| 5160 | sourced Script ID of the actually sourced script that |
Bram Moolenaar | fd99945 | 2022-08-24 18:30:14 +0100 | [diff] [blame] | 5161 | this script name links to, if any, otherwise |
| 5162 | zero |
Yegappan Lakshmanan | 2f892d8 | 2022-08-28 18:52:10 +0100 | [diff] [blame] | 5163 | variables A dictionary with the script-local variables. |
Bram Moolenaar | f1dcd14 | 2022-12-31 15:30:45 +0000 | [diff] [blame] | 5164 | Present only when a particular script is |
Yegappan Lakshmanan | 2f892d8 | 2022-08-28 18:52:10 +0100 | [diff] [blame] | 5165 | specified using the "sid" item in {opts}. |
| 5166 | Note that this is a copy, the value of |
| 5167 | script-local variables cannot be changed using |
| 5168 | this dictionary. |
h_east | 5985879 | 2023-10-25 22:47:05 +0900 | [diff] [blame] | 5169 | version Vim script version (|scriptversion|) |
Yegappan Lakshmanan | 520f6ef | 2022-08-25 17:40:40 +0100 | [diff] [blame] | 5170 | |
Yegappan Lakshmanan | 2f892d8 | 2022-08-28 18:52:10 +0100 | [diff] [blame] | 5171 | Examples: > |
| 5172 | :echo getscriptinfo({'name': 'myscript'}) |
zeertzjq | ad4881c | 2024-05-04 15:35:30 +0800 | [diff] [blame] | 5173 | :echo getscriptinfo({'sid': 15})[0].variables |
Yegappan Lakshmanan | 2f892d8 | 2022-08-28 18:52:10 +0100 | [diff] [blame] | 5174 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5175 | Return type: list<dict<any>> |
| 5176 | |
| 5177 | |
ichizok | 663d18d | 2025-01-02 18:06:00 +0100 | [diff] [blame] | 5178 | getstacktrace() *getstacktrace()* |
| 5179 | Returns the current stack trace of Vim scripts. |
| 5180 | Stack trace is a |List|, of which each item is a |Dictionary| |
| 5181 | with the following items: |
zeertzjq | 6655bef | 2025-01-06 18:32:13 +0100 | [diff] [blame] | 5182 | funcref The funcref if the stack is at a function, |
| 5183 | otherwise this item is omitted. |
ichizok | 663d18d | 2025-01-02 18:06:00 +0100 | [diff] [blame] | 5184 | event The string of the event description if the |
zeertzjq | 6655bef | 2025-01-06 18:32:13 +0100 | [diff] [blame] | 5185 | stack is at an autocmd event, otherwise this |
| 5186 | item is omitted. |
| 5187 | lnum The line number in the script on the stack. |
ichizok | 663d18d | 2025-01-02 18:06:00 +0100 | [diff] [blame] | 5188 | filepath The file path of the script on the stack. |
| 5189 | |
| 5190 | Return type: list<dict<any>> |
| 5191 | |
| 5192 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5193 | gettabinfo([{tabnr}]) *gettabinfo()* |
| 5194 | If {tabnr} is not specified, then information about all the |
| 5195 | tab pages is returned as a |List|. Each List item is a |
| 5196 | |Dictionary|. Otherwise, {tabnr} specifies the tab page |
| 5197 | number and information about that one is returned. If the tab |
| 5198 | page does not exist an empty List is returned. |
| 5199 | |
| 5200 | Each List item is a |Dictionary| with the following entries: |
| 5201 | tabnr tab page number. |
| 5202 | variables a reference to the dictionary with |
| 5203 | tabpage-local variables |
| 5204 | windows List of |window-ID|s in the tab page. |
| 5205 | |
| 5206 | Can also be used as a |method|: > |
| 5207 | GetTabnr()->gettabinfo() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5208 | < |
| 5209 | Return type: list<dict<any>> |
| 5210 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5211 | |
| 5212 | gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()* |
| 5213 | Get the value of a tab-local variable {varname} in tab page |
| 5214 | {tabnr}. |t:var| |
| 5215 | Tabs are numbered starting with one. |
| 5216 | The {varname} argument is a string. When {varname} is empty a |
| 5217 | dictionary with all tab-local variables is returned. |
| 5218 | Note that the name without "t:" must be used. |
| 5219 | When the tab or variable doesn't exist {def} or an empty |
| 5220 | string is returned, there is no error message. |
| 5221 | |
| 5222 | Can also be used as a |method|: > |
| 5223 | GetTabnr()->gettabvar(varname) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5224 | < |
| 5225 | Return type: any, depending on {varname} |
| 5226 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5227 | |
| 5228 | gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* |
| 5229 | Get the value of window-local variable {varname} in window |
| 5230 | {winnr} in tab page {tabnr}. |
| 5231 | The {varname} argument is a string. When {varname} is empty a |
| 5232 | dictionary with all window-local variables is returned. |
| 5233 | When {varname} is equal to "&" get the values of all |
| 5234 | window-local options in a |Dictionary|. |
| 5235 | Otherwise, when {varname} starts with "&" get the value of a |
| 5236 | window-local option. |
| 5237 | Note that {varname} must be the name without "w:". |
| 5238 | Tabs are numbered starting with one. For the current tabpage |
| 5239 | use |getwinvar()|. |
| 5240 | {winnr} can be the window number or the |window-ID|. |
| 5241 | When {winnr} is zero the current window is used. |
| 5242 | This also works for a global option, buffer-local option and |
| 5243 | window-local option, but it doesn't work for a global variable |
| 5244 | or buffer-local variable. |
| 5245 | When the tab, window or variable doesn't exist {def} or an |
| 5246 | empty string is returned, there is no error message. |
| 5247 | Examples: > |
| 5248 | :let list_is_on = gettabwinvar(1, 2, '&list') |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 5249 | :echo "myvar = " .. gettabwinvar(3, 1, 'myvar') |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5250 | < |
| 5251 | To obtain all window-local variables use: > |
| 5252 | gettabwinvar({tabnr}, {winnr}, '&') |
| 5253 | |
| 5254 | < Can also be used as a |method|: > |
| 5255 | GetTabnr()->gettabwinvar(winnr, varname) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5256 | < |
| 5257 | Return type: any, depending on {varname} |
| 5258 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5259 | |
| 5260 | gettagstack([{winnr}]) *gettagstack()* |
| 5261 | The result is a Dict, which is the tag stack of window {winnr}. |
| 5262 | {winnr} can be the window number or the |window-ID|. |
| 5263 | When {winnr} is not specified, the current window is used. |
| 5264 | When window {winnr} doesn't exist, an empty Dict is returned. |
| 5265 | |
| 5266 | The returned dictionary contains the following entries: |
| 5267 | curidx Current index in the stack. When at |
| 5268 | top of the stack, set to (length + 1). |
| 5269 | Index of bottom of the stack is 1. |
| 5270 | items List of items in the stack. Each item |
| 5271 | is a dictionary containing the |
| 5272 | entries described below. |
| 5273 | length Number of entries in the stack. |
| 5274 | |
| 5275 | Each item in the stack is a dictionary with the following |
| 5276 | entries: |
| 5277 | bufnr buffer number of the current jump |
| 5278 | from cursor position before the tag jump. |
| 5279 | See |getpos()| for the format of the |
| 5280 | returned list. |
| 5281 | matchnr current matching tag number. Used when |
| 5282 | multiple matching tags are found for a |
| 5283 | name. |
| 5284 | tagname name of the tag |
| 5285 | |
| 5286 | See |tagstack| for more information about the tag stack. |
| 5287 | |
| 5288 | Can also be used as a |method|: > |
| 5289 | GetWinnr()->gettagstack() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5290 | < |
| 5291 | Return type: dict<any> |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5292 | |
| 5293 | |
Christ van Willegen | ce0ef91 | 2024-06-20 23:41:59 +0200 | [diff] [blame] | 5294 | gettext({text} [, {package}]) *gettext()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5295 | Translate String {text} if possible. |
RestorerZ | 9650910 | 2024-07-11 21:14:15 +0200 | [diff] [blame] | 5296 | This is intended for use in Vim scripts. When generating |
| 5297 | message translations the {text} is extracted by `xgettext`, |
| 5298 | the translator can add translated messages into the .po file |
| 5299 | and Vim will lookup the translation when gettext() is called. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5300 | For {text} double quoted strings are preferred, because |
RestorerZ | 9650910 | 2024-07-11 21:14:15 +0200 | [diff] [blame] | 5301 | `xgettext` does not support single quoted escaped text. |
| 5302 | |
Christ van Willegen | ce0ef91 | 2024-06-20 23:41:59 +0200 | [diff] [blame] | 5303 | When the {package} is specified, the translation is looked up |
RestorerZ | 9650910 | 2024-07-11 21:14:15 +0200 | [diff] [blame] | 5304 | for that specific package. This is mainly required for |
| 5305 | third-party Vim scripts. You need to specify a path to the |
| 5306 | translations with the |bindtextdomain()| function before |
| 5307 | using the gettext() function. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5308 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5309 | Return type: |String| |
| 5310 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5311 | |
| 5312 | getwininfo([{winid}]) *getwininfo()* |
| 5313 | Returns information about windows as a |List| with Dictionaries. |
| 5314 | |
| 5315 | If {winid} is given Information about the window with that ID |
| 5316 | is returned, as a |List| with one item. If the window does not |
| 5317 | exist the result is an empty list. |
| 5318 | |
| 5319 | Without {winid} information about all the windows in all the |
| 5320 | tab pages is returned. |
| 5321 | |
| 5322 | Each List item is a |Dictionary| with the following entries: |
| 5323 | botline last complete displayed buffer line |
| 5324 | bufnr number of buffer in the window |
| 5325 | height window height (excluding winbar) |
glepnir | 0a85067 | 2024-11-25 19:39:04 +0100 | [diff] [blame] | 5326 | leftcol first column displayed; only used when |
| 5327 | 'wrap' is off |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5328 | loclist 1 if showing a location list |
| 5329 | {only with the +quickfix feature} |
| 5330 | quickfix 1 if quickfix or location list window |
| 5331 | {only with the +quickfix feature} |
| 5332 | terminal 1 if a terminal window |
| 5333 | {only with the +terminal feature} |
| 5334 | tabnr tab page number |
| 5335 | topline first displayed buffer line |
| 5336 | variables a reference to the dictionary with |
| 5337 | window-local variables |
| 5338 | width window width |
| 5339 | winbar 1 if the window has a toolbar, 0 |
| 5340 | otherwise |
| 5341 | wincol leftmost screen column of the window; |
| 5342 | "col" from |win_screenpos()| |
| 5343 | textoff number of columns occupied by any |
| 5344 | 'foldcolumn', 'signcolumn' and line |
| 5345 | number in front of the text |
| 5346 | winid |window-ID| |
| 5347 | winnr window number |
| 5348 | winrow topmost screen line of the window; |
| 5349 | "row" from |win_screenpos()| |
| 5350 | |
| 5351 | Can also be used as a |method|: > |
| 5352 | GetWinnr()->getwininfo() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5353 | < |
| 5354 | Return type: list<dict<any>> |
| 5355 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5356 | |
| 5357 | getwinpos([{timeout}]) *getwinpos()* |
| 5358 | The result is a |List| with two numbers, the result of |
| 5359 | |getwinposx()| and |getwinposy()| combined: |
| 5360 | [x-pos, y-pos] |
| 5361 | {timeout} can be used to specify how long to wait in msec for |
| 5362 | a response from the terminal. When omitted 100 msec is used. |
| 5363 | Use a longer time for a remote terminal. |
| 5364 | When using a value less than 10 and no response is received |
| 5365 | within that time, a previously reported position is returned, |
| 5366 | if available. This can be used to poll for the position and |
| 5367 | do some work in the meantime: > |
| 5368 | while 1 |
| 5369 | let res = getwinpos(1) |
| 5370 | if res[0] >= 0 |
| 5371 | break |
| 5372 | endif |
| 5373 | " Do some work here |
| 5374 | endwhile |
| 5375 | < |
| 5376 | |
| 5377 | Can also be used as a |method|: > |
| 5378 | GetTimeout()->getwinpos() |
| 5379 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5380 | Return type: list<number> |
| 5381 | |
| 5382 | |
| 5383 | getwinposx() *getwinposx()* |
| 5384 | The result is a Number, which is the X coordinate in pixels of |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5385 | the left hand side of the GUI Vim window. Also works for an |
| 5386 | xterm (uses a timeout of 100 msec). |
lilydjwg | 6e0a18f | 2024-01-29 20:54:28 +0100 | [diff] [blame] | 5387 | The result will be -1 if the information is not available |
| 5388 | (e.g. on the Wayland backend). |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5389 | The value can be used with `:winpos`. |
| 5390 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5391 | Return type: |Number| |
| 5392 | |
| 5393 | |
| 5394 | getwinposy() *getwinposy()* |
| 5395 | The result is a Number, which is the Y coordinate in pixels of |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5396 | the top of the GUI Vim window. Also works for an xterm (uses |
| 5397 | a timeout of 100 msec). |
lilydjwg | 6e0a18f | 2024-01-29 20:54:28 +0100 | [diff] [blame] | 5398 | The result will be -1 if the information is not available |
| 5399 | (e.g. on the Wayland backend). |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5400 | The value can be used with `:winpos`. |
| 5401 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5402 | Return type: |Number| |
| 5403 | |
| 5404 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5405 | getwinvar({winnr}, {varname} [, {def}]) *getwinvar()* |
| 5406 | Like |gettabwinvar()| for the current tabpage. |
| 5407 | Examples: > |
| 5408 | :let list_is_on = getwinvar(2, '&list') |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 5409 | :echo "myvar = " .. getwinvar(1, 'myvar') |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5410 | |
| 5411 | < Can also be used as a |method|: > |
| 5412 | GetWinnr()->getwinvar(varname) |
| 5413 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5414 | Return type: any, depending on {varname} |
| 5415 | |
| 5416 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5417 | glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()* |
| 5418 | Expand the file wildcards in {expr}. See |wildcards| for the |
| 5419 | use of special characters. |
| 5420 | |
| 5421 | Unless the optional {nosuf} argument is given and is |TRUE|, |
| 5422 | the 'suffixes' and 'wildignore' options apply: Names matching |
| 5423 | one of the patterns in 'wildignore' will be skipped and |
| 5424 | 'suffixes' affect the ordering of matches. |
| 5425 | 'wildignorecase' always applies. |
| 5426 | |
| 5427 | When {list} is present and it is |TRUE| the result is a |List| |
| 5428 | with all matching files. The advantage of using a List is, |
| 5429 | you also get filenames containing newlines correctly. |
| 5430 | Otherwise the result is a String and when there are several |
| 5431 | matches, they are separated by <NL> characters. |
| 5432 | |
| 5433 | If the expansion fails, the result is an empty String or List. |
| 5434 | |
| 5435 | You can also use |readdir()| if you need to do complicated |
| 5436 | things, such as limiting the number of matches. |
| 5437 | |
| 5438 | A name for a non-existing file is not included. A symbolic |
| 5439 | link is only included if it points to an existing file. |
| 5440 | However, when the {alllinks} argument is present and it is |
| 5441 | |TRUE| then all symbolic links are included. |
| 5442 | |
| 5443 | For most systems backticks can be used to get files names from |
| 5444 | any external command. Example: > |
| 5445 | :let tagfiles = glob("`find . -name tags -print`") |
| 5446 | :let &tags = substitute(tagfiles, "\n", ",", "g") |
| 5447 | < The result of the program inside the backticks should be one |
| 5448 | item per line. Spaces inside an item are allowed. |
| 5449 | |
| 5450 | See |expand()| for expanding special Vim variables. See |
| 5451 | |system()| for getting the raw output of an external command. |
| 5452 | |
| 5453 | Can also be used as a |method|: > |
| 5454 | GetExpr()->glob() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5455 | < |
| 5456 | Return type: |String| or list<string> or list<any> depending |
| 5457 | on {list} |
| 5458 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5459 | |
h-east | 624bb83 | 2024-11-09 18:37:32 +0100 | [diff] [blame] | 5460 | glob2regpat({string}) *glob2regpat()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5461 | Convert a file pattern, as used by glob(), into a search |
| 5462 | pattern. The result can be used to match with a string that |
| 5463 | is a file name. E.g. > |
| 5464 | if filename =~ glob2regpat('Make*.mak') |
| 5465 | < This is equivalent to: > |
| 5466 | if filename =~ '^Make.*\.mak$' |
| 5467 | < When {string} is an empty string the result is "^$", match an |
| 5468 | empty string. |
| 5469 | Note that the result depends on the system. On MS-Windows |
| 5470 | a backslash usually means a path separator. |
| 5471 | |
| 5472 | Can also be used as a |method|: > |
| 5473 | GetExpr()->glob2regpat() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5474 | < |
| 5475 | Return type: |String| |
| 5476 | |
| 5477 | *globpath()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5478 | globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]]) |
| 5479 | Perform glob() for String {expr} on all directories in {path} |
| 5480 | and concatenate the results. Example: > |
| 5481 | :echo globpath(&rtp, "syntax/c.vim") |
| 5482 | < |
| 5483 | {path} is a comma-separated list of directory names. Each |
| 5484 | directory name is prepended to {expr} and expanded like with |
| 5485 | |glob()|. A path separator is inserted when needed. |
| 5486 | To add a comma inside a directory name escape it with a |
| 5487 | backslash. Note that on MS-Windows a directory may have a |
| 5488 | trailing backslash, remove it if you put a comma after it. |
| 5489 | If the expansion fails for one of the directories, there is no |
| 5490 | error message. |
| 5491 | |
| 5492 | Unless the optional {nosuf} argument is given and is |TRUE|, |
| 5493 | the 'suffixes' and 'wildignore' options apply: Names matching |
| 5494 | one of the patterns in 'wildignore' will be skipped and |
| 5495 | 'suffixes' affect the ordering of matches. |
| 5496 | |
| 5497 | When {list} is present and it is |TRUE| the result is a |List| |
| 5498 | with all matching files. The advantage of using a List is, you |
| 5499 | also get filenames containing newlines correctly. Otherwise |
| 5500 | the result is a String and when there are several matches, |
| 5501 | they are separated by <NL> characters. Example: > |
| 5502 | :echo globpath(&rtp, "syntax/c.vim", 0, 1) |
| 5503 | < |
| 5504 | {alllinks} is used as with |glob()|. |
| 5505 | |
| 5506 | The "**" item can be used to search in a directory tree. |
| 5507 | For example, to find all "README.txt" files in the directories |
| 5508 | in 'runtimepath' and below: > |
| 5509 | :echo globpath(&rtp, "**/README.txt") |
| 5510 | < Upwards search and limiting the depth of "**" is not |
| 5511 | supported, thus using 'path' will not always work properly. |
| 5512 | |
| 5513 | Can also be used as a |method|, the base is passed as the |
| 5514 | second argument: > |
| 5515 | GetExpr()->globpath(&rtp) |
| 5516 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5517 | Return type: |String| or list<string> or list<any> depending |
| 5518 | on {list} |
| 5519 | |
| 5520 | |
| 5521 | has({feature} [, {check}]) *has()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5522 | When {check} is omitted or is zero: The result is a Number, |
| 5523 | which is 1 if the feature {feature} is supported, zero |
| 5524 | otherwise. The {feature} argument is a string, case is |
| 5525 | ignored. See |feature-list| below. |
| 5526 | |
| 5527 | When {check} is present and not zero: The result is a Number, |
| 5528 | which is 1 if the feature {feature} could ever be supported, |
| 5529 | zero otherwise. This is useful to check for a typo in |
| 5530 | {feature} and to detect dead code. Keep in mind that an older |
| 5531 | Vim version will not know about a feature added later and |
| 5532 | features that have been abandoned will not be known by the |
| 5533 | current Vim version. |
| 5534 | |
| 5535 | Also see |exists()| and |exists_compiled()|. |
| 5536 | |
| 5537 | Note that to skip code that has a syntax error when the |
| 5538 | feature is not available, Vim may skip the rest of the line |
| 5539 | and miss a following `endif`. Therefore put the `endif` on a |
| 5540 | separate line: > |
| 5541 | if has('feature') |
| 5542 | let x = this->breaks->without->the->feature |
| 5543 | endif |
| 5544 | < If the `endif` would be moved to the second line as "| endif" it |
| 5545 | would not be found. |
| 5546 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5547 | Return type: |Number| |
| 5548 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5549 | |
| 5550 | has_key({dict}, {key}) *has_key()* |
| 5551 | The result is a Number, which is TRUE if |Dictionary| {dict} |
Bram Moolenaar | e800864 | 2022-08-19 17:15:35 +0100 | [diff] [blame] | 5552 | has an entry with key {key}. FALSE otherwise. |
| 5553 | The {key} argument is a string. In |Vim9| script a number is |
| 5554 | also accepted (and converted to a string) but no other types. |
| 5555 | In legacy script the usual automatic conversion to string is |
| 5556 | done. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5557 | |
| 5558 | Can also be used as a |method|: > |
| 5559 | mydict->has_key(key) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5560 | < |
| 5561 | Return type: |Number| |
| 5562 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5563 | |
| 5564 | haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()* |
| 5565 | The result is a Number: |
| 5566 | 1 when the window has set a local directory via |:lcd| |
| 5567 | 2 when the tab-page has set a local directory via |:tcd| |
| 5568 | 0 otherwise. |
| 5569 | |
| 5570 | Without arguments use the current window. |
| 5571 | With {winnr} use this window in the current tab page. |
| 5572 | With {winnr} and {tabnr} use the window in the specified tab |
| 5573 | page. |
| 5574 | {winnr} can be the window number or the |window-ID|. |
| 5575 | If {winnr} is -1 it is ignored and only the tabpage is used. |
| 5576 | Return 0 if the arguments are invalid. |
| 5577 | Examples: > |
| 5578 | if haslocaldir() == 1 |
| 5579 | " window local directory case |
| 5580 | elseif haslocaldir() == 2 |
| 5581 | " tab-local directory case |
| 5582 | else |
| 5583 | " global directory case |
| 5584 | endif |
| 5585 | |
| 5586 | " current window |
| 5587 | :echo haslocaldir() |
| 5588 | :echo haslocaldir(0) |
| 5589 | :echo haslocaldir(0, 0) |
| 5590 | " window n in current tab page |
| 5591 | :echo haslocaldir(n) |
| 5592 | :echo haslocaldir(n, 0) |
| 5593 | " window n in tab page m |
| 5594 | :echo haslocaldir(n, m) |
| 5595 | " tab page m |
| 5596 | :echo haslocaldir(-1, m) |
| 5597 | < |
| 5598 | Can also be used as a |method|: > |
| 5599 | GetWinnr()->haslocaldir() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5600 | < |
| 5601 | Return type: |Number| |
| 5602 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5603 | |
| 5604 | hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()* |
| 5605 | The result is a Number, which is TRUE if there is a mapping |
| 5606 | that contains {what} in somewhere in the rhs (what it is |
| 5607 | mapped to) and this mapping exists in one of the modes |
| 5608 | indicated by {mode}. |
| 5609 | The arguments {what} and {mode} are strings. |
| 5610 | When {abbr} is there and it is |TRUE| use abbreviations |
| 5611 | instead of mappings. Don't forget to specify Insert and/or |
| 5612 | Command-line mode. |
| 5613 | Both the global mappings and the mappings local to the current |
| 5614 | buffer are checked for a match. |
| 5615 | If no matching mapping is found FALSE is returned. |
| 5616 | The following characters are recognized in {mode}: |
| 5617 | n Normal mode |
| 5618 | v Visual and Select mode |
| 5619 | x Visual mode |
| 5620 | s Select mode |
| 5621 | o Operator-pending mode |
| 5622 | i Insert mode |
| 5623 | l Language-Argument ("r", "f", "t", etc.) |
| 5624 | c Command-line mode |
| 5625 | When {mode} is omitted, "nvo" is used. |
| 5626 | |
| 5627 | This function is useful to check if a mapping already exists |
| 5628 | to a function in a Vim script. Example: > |
| 5629 | :if !hasmapto('\ABCdoit') |
| 5630 | : map <Leader>d \ABCdoit |
| 5631 | :endif |
| 5632 | < This installs the mapping to "\ABCdoit" only if there isn't |
| 5633 | already a mapping to "\ABCdoit". |
| 5634 | |
| 5635 | Can also be used as a |method|: > |
| 5636 | GetRHS()->hasmapto() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5637 | < |
| 5638 | Return type: |Number| |
| 5639 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5640 | |
| 5641 | histadd({history}, {item}) *histadd()* |
| 5642 | Add the String {item} to the history {history} which can be |
| 5643 | one of: *hist-names* |
| 5644 | "cmd" or ":" command line history |
| 5645 | "search" or "/" search pattern history |
| 5646 | "expr" or "=" typed expression history |
| 5647 | "input" or "@" input line history |
| 5648 | "debug" or ">" debug command history |
| 5649 | empty the current or last used history |
| 5650 | The {history} string does not need to be the whole name, one |
| 5651 | character is sufficient. |
| 5652 | If {item} does already exist in the history, it will be |
| 5653 | shifted to become the newest entry. |
| 5654 | The result is a Number: TRUE if the operation was successful, |
| 5655 | otherwise FALSE is returned. |
| 5656 | |
| 5657 | Example: > |
| 5658 | :call histadd("input", strftime("%Y %b %d")) |
| 5659 | :let date=input("Enter date: ") |
| 5660 | < This function is not available in the |sandbox|. |
| 5661 | |
| 5662 | Can also be used as a |method|, the base is passed as the |
| 5663 | second argument: > |
| 5664 | GetHistory()->histadd('search') |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5665 | < |
| 5666 | Return type: |Number| |
| 5667 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5668 | |
| 5669 | histdel({history} [, {item}]) *histdel()* |
| 5670 | Clear {history}, i.e. delete all its entries. See |hist-names| |
| 5671 | for the possible values of {history}. |
| 5672 | |
| 5673 | If the parameter {item} evaluates to a String, it is used as a |
| 5674 | regular expression. All entries matching that expression will |
| 5675 | be removed from the history (if there are any). |
| 5676 | Upper/lowercase must match, unless "\c" is used |/\c|. |
| 5677 | If {item} evaluates to a Number, it will be interpreted as |
| 5678 | an index, see |:history-indexing|. The respective entry will |
| 5679 | be removed if it exists. |
| 5680 | |
| 5681 | The result is TRUE for a successful operation, otherwise FALSE |
| 5682 | is returned. |
| 5683 | |
| 5684 | Examples: |
| 5685 | Clear expression register history: > |
| 5686 | :call histdel("expr") |
| 5687 | < |
| 5688 | Remove all entries starting with "*" from the search history: > |
| 5689 | :call histdel("/", '^\*') |
| 5690 | < |
| 5691 | The following three are equivalent: > |
| 5692 | :call histdel("search", histnr("search")) |
| 5693 | :call histdel("search", -1) |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 5694 | :call histdel("search", '^' .. histget("search", -1) .. '$') |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5695 | < |
| 5696 | To delete the last search pattern and use the last-but-one for |
| 5697 | the "n" command and 'hlsearch': > |
| 5698 | :call histdel("search", -1) |
| 5699 | :let @/ = histget("search", -1) |
| 5700 | < |
| 5701 | Can also be used as a |method|: > |
| 5702 | GetHistory()->histdel() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5703 | < |
| 5704 | Return type: |Number| |
| 5705 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5706 | |
| 5707 | histget({history} [, {index}]) *histget()* |
| 5708 | The result is a String, the entry with Number {index} from |
| 5709 | {history}. See |hist-names| for the possible values of |
| 5710 | {history}, and |:history-indexing| for {index}. If there is |
| 5711 | no such entry, an empty String is returned. When {index} is |
| 5712 | omitted, the most recent item from the history is used. |
| 5713 | |
| 5714 | Examples: |
| 5715 | Redo the second last search from history. > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 5716 | :execute '/' .. histget("search", -2) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5717 | |
| 5718 | < Define an Ex command ":H {num}" that supports re-execution of |
| 5719 | the {num}th entry from the output of |:history|. > |
| 5720 | :command -nargs=1 H execute histget("cmd", 0+<args>) |
| 5721 | < |
| 5722 | Can also be used as a |method|: > |
| 5723 | GetHistory()->histget() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5724 | < |
| 5725 | Return type: |String| |
| 5726 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5727 | |
| 5728 | histnr({history}) *histnr()* |
| 5729 | The result is the Number of the current entry in {history}. |
| 5730 | See |hist-names| for the possible values of {history}. |
| 5731 | If an error occurred, -1 is returned. |
| 5732 | |
| 5733 | Example: > |
| 5734 | :let inp_index = histnr("expr") |
| 5735 | |
| 5736 | < Can also be used as a |method|: > |
| 5737 | GetHistory()->histnr() |
| 5738 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5739 | Return type: |Number| |
| 5740 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5741 | hlexists({name}) *hlexists()* |
| 5742 | The result is a Number, which is TRUE if a highlight group |
| 5743 | called {name} exists. This is when the group has been |
| 5744 | defined in some way. Not necessarily when highlighting has |
| 5745 | been defined for it, it may also have been used for a syntax |
| 5746 | item. |
| 5747 | *highlight_exists()* |
| 5748 | Obsolete name: highlight_exists(). |
| 5749 | |
| 5750 | Can also be used as a |method|: > |
| 5751 | GetName()->hlexists() |
| 5752 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5753 | Return type: |Number| |
| 5754 | |
| 5755 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5756 | hlget([{name} [, {resolve}]]) *hlget()* |
| 5757 | Returns a List of all the highlight group attributes. If the |
| 5758 | optional {name} is specified, then returns a List with only |
| 5759 | the attributes of the specified highlight group. Returns an |
| 5760 | empty List if the highlight group {name} is not present. |
| 5761 | |
| 5762 | If the optional {resolve} argument is set to v:true and the |
| 5763 | highlight group {name} is linked to another group, then the |
| 5764 | link is resolved recursively and the attributes of the |
| 5765 | resolved highlight group are returned. |
| 5766 | |
| 5767 | Each entry in the returned List is a Dictionary with the |
| 5768 | following items: |
| 5769 | cleared boolean flag, set to v:true if the highlight |
| 5770 | group attributes are cleared or not yet |
| 5771 | specified. See |highlight-clear|. |
| 5772 | cterm cterm attributes. See |highlight-cterm|. |
| 5773 | ctermbg cterm background color. |
| 5774 | See |highlight-ctermbg|. |
| 5775 | ctermfg cterm foreground color. |
| 5776 | See |highlight-ctermfg|. |
| 5777 | ctermul cterm underline color. See |highlight-ctermul|. |
| 5778 | default boolean flag, set to v:true if the highlight |
| 5779 | group link is a default link. See |
| 5780 | |highlight-default|. |
| 5781 | font highlight group font. See |highlight-font|. |
| 5782 | gui gui attributes. See |highlight-gui|. |
| 5783 | guibg gui background color. See |highlight-guibg|. |
| 5784 | guifg gui foreground color. See |highlight-guifg|. |
| 5785 | guisp gui special color. See |highlight-guisp|. |
| 5786 | id highlight group ID. |
| 5787 | linksto linked highlight group name. |
| 5788 | See |:highlight-link|. |
| 5789 | name highlight group name. See |group-name|. |
| 5790 | start start terminal keycode. See |highlight-start|. |
| 5791 | stop stop terminal keycode. See |highlight-stop|. |
| 5792 | term term attributes. See |highlight-term|. |
| 5793 | |
| 5794 | The 'term', 'cterm' and 'gui' items in the above Dictionary |
| 5795 | have a dictionary value with the following optional boolean |
| 5796 | items: 'bold', 'standout', 'underline', 'undercurl', 'italic', |
| 5797 | 'reverse', 'inverse' and 'strikethrough'. |
| 5798 | |
| 5799 | Example(s): > |
| 5800 | :echo hlget() |
| 5801 | :echo hlget('ModeMsg') |
| 5802 | :echo hlget('Number', v:true) |
| 5803 | < |
| 5804 | Can also be used as a |method|: > |
| 5805 | GetName()->hlget() |
| 5806 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5807 | Return type: list<dict<any>> |
| 5808 | |
| 5809 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5810 | hlset({list}) *hlset()* |
| 5811 | Creates or modifies the attributes of a List of highlight |
| 5812 | groups. Each item in {list} is a dictionary containing the |
| 5813 | attributes of a highlight group. See |hlget()| for the list of |
| 5814 | supported items in this dictionary. |
| 5815 | |
| 5816 | In addition to the items described in |hlget()|, the following |
| 5817 | additional items are supported in the dictionary: |
| 5818 | |
| 5819 | force boolean flag to force the creation of |
| 5820 | a link for an existing highlight group |
| 5821 | with attributes. |
| 5822 | |
| 5823 | The highlight group is identified using the 'name' item and |
| 5824 | the 'id' item (if supplied) is ignored. If a highlight group |
| 5825 | with a specified name doesn't exist, then it is created. |
| 5826 | Otherwise the attributes of an existing highlight group are |
| 5827 | modified. |
| 5828 | |
| 5829 | If an empty dictionary value is used for the 'term' or 'cterm' |
| 5830 | or 'gui' entries, then the corresponding attributes are |
| 5831 | cleared. If the 'cleared' item is set to v:true, then all the |
| 5832 | attributes of the highlight group are cleared. |
| 5833 | |
| 5834 | The 'linksto' item can be used to link a highlight group to |
| 5835 | another highlight group. See |:highlight-link|. |
| 5836 | |
| 5837 | Returns zero for success, -1 for failure. |
| 5838 | |
| 5839 | Example(s): > |
| 5840 | " add bold attribute to the Visual highlight group |
| 5841 | :call hlset([#{name: 'Visual', |
| 5842 | \ term: #{reverse: 1 , bold: 1}}]) |
| 5843 | :call hlset([#{name: 'Type', guifg: 'DarkGreen'}]) |
| 5844 | :let l = hlget() |
| 5845 | :call hlset(l) |
| 5846 | " clear the Search highlight group |
| 5847 | :call hlset([#{name: 'Search', cleared: v:true}]) |
| 5848 | " clear the 'term' attributes for a highlight group |
| 5849 | :call hlset([#{name: 'Title', term: {}}]) |
| 5850 | " create the MyHlg group linking it to DiffAdd |
| 5851 | :call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}]) |
| 5852 | " remove the MyHlg group link |
| 5853 | :call hlset([#{name: 'MyHlg', linksto: 'NONE'}]) |
| 5854 | " clear the attributes and a link |
| 5855 | :call hlset([#{name: 'MyHlg', cleared: v:true, |
| 5856 | \ linksto: 'NONE'}]) |
| 5857 | < |
| 5858 | Can also be used as a |method|: > |
| 5859 | GetAttrList()->hlset() |
| 5860 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5861 | Return type: |Number| |
| 5862 | |
| 5863 | hlID({name}) *hlID()* |
| 5864 | The result is a Number, which is the ID of the highlight group |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5865 | with name {name}. When the highlight group doesn't exist, |
| 5866 | zero is returned. |
| 5867 | This can be used to retrieve information about the highlight |
| 5868 | group. For example, to get the background color of the |
| 5869 | "Comment" group: > |
| 5870 | :echo synIDattr(synIDtrans(hlID("Comment")), "bg") |
| 5871 | < *highlightID()* |
| 5872 | Obsolete name: highlightID(). |
| 5873 | |
| 5874 | Can also be used as a |method|: > |
| 5875 | GetName()->hlID() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5876 | < |
| 5877 | Return type: |Number| |
| 5878 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5879 | |
| 5880 | hostname() *hostname()* |
| 5881 | The result is a String, which is the name of the machine on |
| 5882 | which Vim is currently running. Machine names greater than |
| 5883 | 256 characters long are truncated. |
| 5884 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5885 | Return type: |String| |
| 5886 | |
| 5887 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5888 | iconv({string}, {from}, {to}) *iconv()* |
| 5889 | The result is a String, which is the text {string} converted |
| 5890 | from encoding {from} to encoding {to}. |
| 5891 | When the conversion completely fails an empty string is |
| 5892 | returned. When some characters could not be converted they |
| 5893 | are replaced with "?". |
| 5894 | The encoding names are whatever the iconv() library function |
| 5895 | can accept, see ":!man 3 iconv". |
| 5896 | Most conversions require Vim to be compiled with the |+iconv| |
| 5897 | feature. Otherwise only UTF-8 to latin1 conversion and back |
| 5898 | can be done. |
| 5899 | This can be used to display messages with special characters, |
| 5900 | no matter what 'encoding' is set to. Write the message in |
| 5901 | UTF-8 and use: > |
| 5902 | echo iconv(utf8_str, "utf-8", &enc) |
| 5903 | < Note that Vim uses UTF-8 for all Unicode encodings, conversion |
| 5904 | from/to UCS-2 is automatically changed to use UTF-8. You |
| 5905 | cannot use UCS-2 in a string anyway, because of the NUL bytes. |
| 5906 | |
| 5907 | Can also be used as a |method|: > |
| 5908 | GetText()->iconv('latin1', 'utf-8') |
| 5909 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5910 | Return type: |String| |
| 5911 | |
| 5912 | |
h-east | 624bb83 | 2024-11-09 18:37:32 +0100 | [diff] [blame] | 5913 | id({item}) *id()* |
Ernie Rael | c8e158b | 2024-07-09 18:39:52 +0200 | [diff] [blame] | 5914 | The result is a unique String associated with the {item} and |
| 5915 | not with the {item}'s contents. It is only valid while the |
| 5916 | {item} exists and is referenced. It is valid only in the |
| 5917 | instance of vim that produces the result. The whole idea is |
| 5918 | that `id({item})` does not change if the contents of {item} |
| 5919 | changes. This is useful as a `key` for creating an identity |
| 5920 | dictionary, rather than one based on equals. |
| 5921 | |
| 5922 | This operation does not reference {item} and there is no |
| 5923 | function to convert the `id` to the {item}. It may be useful to |
| 5924 | have a map of `id` to {item}. The following > |
| 5925 | var referenceMap: dict<any> |
| 5926 | var id = item->id() |
| 5927 | referenceMap[id] = item |
| 5928 | < prevents {item} from being garbage collected and provides a |
| 5929 | way to get the {item} from the `id`. |
| 5930 | |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 5931 | {item} may be a List, Tuple, Dictionary, Object, Job, Channel |
| 5932 | or Blob. If the item is not a permitted type, or it is a null |
Ernie Rael | c8e158b | 2024-07-09 18:39:52 +0200 | [diff] [blame] | 5933 | value, then an empty String is returned. |
| 5934 | |
| 5935 | Can also be used as a |method|: > |
| 5936 | GetItem()->id() |
| 5937 | < |
| 5938 | Return type: |String| |
| 5939 | |
| 5940 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5941 | indent({lnum}) *indent()* |
| 5942 | The result is a Number, which is indent of line {lnum} in the |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5943 | current buffer. The indent is counted in spaces, the value |
| 5944 | of 'tabstop' is relevant. {lnum} is used just like in |
| 5945 | |getline()|. |
| 5946 | When {lnum} is invalid -1 is returned. In |Vim9| script an |
| 5947 | error is given. |
| 5948 | |
| 5949 | Can also be used as a |method|: > |
| 5950 | GetLnum()->indent() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5951 | < |
| 5952 | Return type: |Number| |
| 5953 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5954 | |
| 5955 | index({object}, {expr} [, {start} [, {ic}]]) *index()* |
Yegappan Lakshmanan | b218655 | 2022-08-13 13:09:20 +0100 | [diff] [blame] | 5956 | Find {expr} in {object} and return its index. See |
Yegappan Lakshmanan | 3fbf6cd | 2022-08-13 21:35:13 +0100 | [diff] [blame] | 5957 | |indexof()| for using a lambda to select the item. |
Yegappan Lakshmanan | b218655 | 2022-08-13 13:09:20 +0100 | [diff] [blame] | 5958 | |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 5959 | If {object} is a |List| or a |Tuple| return the lowest index |
| 5960 | where the item has a value equal to {expr}. There is no |
| 5961 | automatic conversion, so the String "4" is different from the |
| 5962 | Number 4. And the number 4 is different from the Float 4.0. |
| 5963 | The value of 'ignorecase' is not used here, case matters as |
| 5964 | indicated by the {ic} argument. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5965 | |
| 5966 | If {object} is |Blob| return the lowest index where the byte |
| 5967 | value is equal to {expr}. |
| 5968 | |
| 5969 | If {start} is given then start looking at the item with index |
| 5970 | {start} (may be negative for an item relative to the end). |
Yegappan Lakshmanan | b218655 | 2022-08-13 13:09:20 +0100 | [diff] [blame] | 5971 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5972 | When {ic} is given and it is |TRUE|, ignore case. Otherwise |
| 5973 | case must match. |
Yegappan Lakshmanan | b218655 | 2022-08-13 13:09:20 +0100 | [diff] [blame] | 5974 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5975 | -1 is returned when {expr} is not found in {object}. |
| 5976 | Example: > |
| 5977 | :let idx = index(words, "the") |
| 5978 | :if index(numbers, 123) >= 0 |
| 5979 | |
| 5980 | < Can also be used as a |method|: > |
| 5981 | GetObject()->index(what) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 5982 | < |
| 5983 | Return type: |Number| |
| 5984 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 5985 | |
Yegappan Lakshmanan | 3fbf6cd | 2022-08-13 21:35:13 +0100 | [diff] [blame] | 5986 | indexof({object}, {expr} [, {opts}]) *indexof()* |
| 5987 | Returns the index of an item in {object} where {expr} is |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 5988 | v:true. {object} must be a |List|, a |Tuple| or a |Blob|. |
Yegappan Lakshmanan | 3fbf6cd | 2022-08-13 21:35:13 +0100 | [diff] [blame] | 5989 | |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 5990 | If {object} is a |List| or a |Tuple|, evaluate {expr} for each |
Christ van Willegen | 92e109f | 2025-03-24 20:12:37 +0100 | [diff] [blame] | 5991 | item in the List or Tuple until the expression is v:true |
| 5992 | and return the index of this item. |
Yegappan Lakshmanan | b218655 | 2022-08-13 13:09:20 +0100 | [diff] [blame] | 5993 | |
| 5994 | If {object} is a |Blob| evaluate {expr} for each byte in the |
Yegappan Lakshmanan | 3fbf6cd | 2022-08-13 21:35:13 +0100 | [diff] [blame] | 5995 | Blob until the expression is v:true and return the index of |
| 5996 | this byte. |
Yegappan Lakshmanan | b218655 | 2022-08-13 13:09:20 +0100 | [diff] [blame] | 5997 | |
| 5998 | {expr} must be a |string| or |Funcref|. |
| 5999 | |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 6000 | If {expr} is a |string|: If {object} is a |List| or a |Tuple|, |
| 6001 | inside {expr} |v:key| has the index of the current List or |
| 6002 | Tuple item and |v:val| has the value of the item. If {object} |
| 6003 | is a |Blob|, inside {expr} |v:key| has the index of the |
| 6004 | current byte and |v:val| has the byte value. |
Yegappan Lakshmanan | b218655 | 2022-08-13 13:09:20 +0100 | [diff] [blame] | 6005 | |
| 6006 | If {expr} is a |Funcref| it must take two arguments: |
| 6007 | 1. the key or the index of the current item. |
| 6008 | 2. the value of the current item. |
| 6009 | The function must return |TRUE| if the item is found and the |
| 6010 | search should stop. |
| 6011 | |
Yegappan Lakshmanan | 3fbf6cd | 2022-08-13 21:35:13 +0100 | [diff] [blame] | 6012 | The optional argument {opts} is a Dict and supports the |
Yegappan Lakshmanan | b218655 | 2022-08-13 13:09:20 +0100 | [diff] [blame] | 6013 | following items: |
Yegappan Lakshmanan | 3fbf6cd | 2022-08-13 21:35:13 +0100 | [diff] [blame] | 6014 | startidx start evaluating {expr} at the item with this |
| 6015 | index; may be negative for an item relative to |
| 6016 | the end |
Yegappan Lakshmanan | b218655 | 2022-08-13 13:09:20 +0100 | [diff] [blame] | 6017 | Returns -1 when {expr} evaluates to v:false for all the items. |
| 6018 | Example: > |
Yegappan Lakshmanan | 3fbf6cd | 2022-08-13 21:35:13 +0100 | [diff] [blame] | 6019 | :let l = [#{n: 10}, #{n: 20}, #{n: 30}] |
| 6020 | :echo indexof(l, "v:val.n == 20") |
| 6021 | :echo indexof(l, {i, v -> v.n == 30}) |
| 6022 | :echo indexof(l, "v:val.n == 20", #{startidx: 1}) |
Yegappan Lakshmanan | b218655 | 2022-08-13 13:09:20 +0100 | [diff] [blame] | 6023 | |
| 6024 | < Can also be used as a |method|: > |
| 6025 | mylist->indexof(expr) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6026 | < |
| 6027 | Return type: |Number| |
| 6028 | |
Yegappan Lakshmanan | b218655 | 2022-08-13 13:09:20 +0100 | [diff] [blame] | 6029 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6030 | input({prompt} [, {text} [, {completion}]]) *input()* |
| 6031 | The result is a String, which is whatever the user typed on |
| 6032 | the command-line. The {prompt} argument is either a prompt |
| 6033 | string, or a blank string (for no prompt). A '\n' can be used |
| 6034 | in the prompt to start a new line. |
| 6035 | The highlighting set with |:echohl| is used for the prompt. |
| 6036 | The input is entered just like a command-line, with the same |
| 6037 | editing commands and mappings. There is a separate history |
| 6038 | for lines typed for input(). |
| 6039 | Example: > |
| 6040 | :if input("Coffee or beer? ") == "beer" |
| 6041 | : echo "Cheers!" |
| 6042 | :endif |
| 6043 | < |
| 6044 | If the optional {text} argument is present and not empty, this |
| 6045 | is used for the default reply, as if the user typed this. |
| 6046 | Example: > |
| 6047 | :let color = input("Color? ", "white") |
| 6048 | |
| 6049 | < The optional {completion} argument specifies the type of |
| 6050 | completion supported for the input. Without it completion is |
| 6051 | not performed. The supported completion types are the same as |
| 6052 | that can be supplied to a user-defined command using the |
| 6053 | "-complete=" argument. Refer to |:command-completion| for |
| 6054 | more information. Example: > |
| 6055 | let fname = input("File: ", "", "file") |
| 6056 | < |
| 6057 | NOTE: This function must not be used in a startup file, for |
| 6058 | the versions that only run in GUI mode (e.g., the Win32 GUI). |
| 6059 | Note: When input() is called from within a mapping it will |
| 6060 | consume remaining characters from that mapping, because a |
| 6061 | mapping is handled like the characters were typed. |
| 6062 | Use |inputsave()| before input() and |inputrestore()| |
| 6063 | after input() to avoid that. Another solution is to avoid |
| 6064 | that further characters follow in the mapping, e.g., by using |
| 6065 | |:execute| or |:normal|. |
| 6066 | |
| 6067 | Example with a mapping: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 6068 | :nmap \x :call GetFoo()<CR>:exe "/" .. Foo<CR> |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6069 | :function GetFoo() |
| 6070 | : call inputsave() |
| 6071 | : let g:Foo = input("enter search pattern: ") |
| 6072 | : call inputrestore() |
| 6073 | :endfunction |
| 6074 | |
| 6075 | < Can also be used as a |method|: > |
| 6076 | GetPrompt()->input() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6077 | < |
| 6078 | Return type: |String| |
| 6079 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6080 | |
| 6081 | inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()* |
| 6082 | Like |input()|, but when the GUI is running and text dialogs |
| 6083 | are supported, a dialog window pops up to input the text. |
| 6084 | Example: > |
| 6085 | :let n = inputdialog("value for shiftwidth", shiftwidth()) |
| 6086 | :if n != "" |
| 6087 | : let &sw = n |
| 6088 | :endif |
| 6089 | < When the dialog is cancelled {cancelreturn} is returned. When |
| 6090 | omitted an empty string is returned. |
| 6091 | Hitting <Enter> works like pressing the OK button. Hitting |
| 6092 | <Esc> works like pressing the Cancel button. |
| 6093 | NOTE: Command-line completion is not supported. |
| 6094 | |
| 6095 | Can also be used as a |method|: > |
| 6096 | GetPrompt()->inputdialog() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6097 | < |
| 6098 | Return type: |String| |
| 6099 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6100 | |
| 6101 | inputlist({textlist}) *inputlist()* |
| 6102 | {textlist} must be a |List| of strings. This |List| is |
| 6103 | displayed, one string per line. The user will be prompted to |
| 6104 | enter a number, which is returned. |
| 6105 | The user can also select an item by clicking on it with the |
| 6106 | mouse, if the mouse is enabled in the command line ('mouse' is |
| 6107 | "a" or includes "c"). For the first string 0 is returned. |
| 6108 | When clicking above the first item a negative number is |
| 6109 | returned. When clicking on the prompt one more than the |
| 6110 | length of {textlist} is returned. |
| 6111 | Make sure {textlist} has less than 'lines' entries, otherwise |
| 6112 | it won't work. It's a good idea to put the entry number at |
| 6113 | the start of the string. And put a prompt in the first item. |
| 6114 | Example: > |
| 6115 | let color = inputlist(['Select color:', '1. red', |
| 6116 | \ '2. green', '3. blue']) |
| 6117 | |
| 6118 | < Can also be used as a |method|: > |
| 6119 | GetChoices()->inputlist() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6120 | < |
| 6121 | Return type: |Number| |
| 6122 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6123 | |
| 6124 | inputrestore() *inputrestore()* |
| 6125 | Restore typeahead that was saved with a previous |inputsave()|. |
| 6126 | Should be called the same number of times inputsave() is |
| 6127 | called. Calling it more often is harmless though. |
| 6128 | Returns TRUE when there is nothing to restore, FALSE otherwise. |
| 6129 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6130 | Return type: |Number| |
| 6131 | |
| 6132 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6133 | inputsave() *inputsave()* |
| 6134 | Preserve typeahead (also from mappings) and clear it, so that |
| 6135 | a following prompt gets input from the user. Should be |
| 6136 | followed by a matching inputrestore() after the prompt. Can |
| 6137 | be used several times, in which case there must be just as |
| 6138 | many inputrestore() calls. |
| 6139 | Returns TRUE when out of memory, FALSE otherwise. |
| 6140 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6141 | Return type: |Number| |
| 6142 | |
| 6143 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6144 | inputsecret({prompt} [, {text}]) *inputsecret()* |
| 6145 | This function acts much like the |input()| function with but |
| 6146 | two exceptions: |
| 6147 | a) the user's response will be displayed as a sequence of |
| 6148 | asterisks ("*") thereby keeping the entry secret, and |
| 6149 | b) the user's response will not be recorded on the input |
| 6150 | |history| stack. |
| 6151 | The result is a String, which is whatever the user actually |
| 6152 | typed on the command-line in response to the issued prompt. |
| 6153 | NOTE: Command-line completion is not supported. |
| 6154 | |
| 6155 | Can also be used as a |method|: > |
| 6156 | GetPrompt()->inputsecret() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6157 | < |
| 6158 | Return type: |String| |
| 6159 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6160 | |
| 6161 | insert({object}, {item} [, {idx}]) *insert()* |
| 6162 | When {object} is a |List| or a |Blob| insert {item} at the start |
| 6163 | of it. |
| 6164 | |
| 6165 | If {idx} is specified insert {item} before the item with index |
| 6166 | {idx}. If {idx} is zero it goes before the first item, just |
| 6167 | like omitting {idx}. A negative {idx} is also possible, see |
| 6168 | |list-index|. -1 inserts just before the last item. |
| 6169 | |
| 6170 | Returns the resulting |List| or |Blob|. Examples: > |
| 6171 | :let mylist = insert([2, 3, 5], 1) |
| 6172 | :call insert(mylist, 4, -1) |
| 6173 | :call insert(mylist, 6, len(mylist)) |
| 6174 | < The last example can be done simpler with |add()|. |
| 6175 | Note that when {item} is a |List| it is inserted as a single |
| 6176 | item. Use |extend()| to concatenate |Lists|. |
| 6177 | |
| 6178 | Can also be used as a |method|: > |
| 6179 | mylist->insert(item) |
Yegappan Lakshmanan | cd39b69 | 2023-10-02 12:50:45 -0700 | [diff] [blame] | 6180 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6181 | Return type: |Number| |
| 6182 | |
| 6183 | |
Yegappan Lakshmanan | cd39b69 | 2023-10-02 12:50:45 -0700 | [diff] [blame] | 6184 | *instanceof()* *E614* *E616* *E693* |
| 6185 | instanceof({object}, {class}) |
| 6186 | The result is a Number, which is |TRUE| when the {object} |
Ernie Rael | 2025af1 | 2023-12-12 16:58:00 +0100 | [diff] [blame] | 6187 | argument is a direct or indirect instance of a |Class|, |
| 6188 | |Interface|, or class |:type| alias specified by {class}. |
| 6189 | If {class} is varargs, the function returns |TRUE| when |
Yegappan Lakshmanan | cd39b69 | 2023-10-02 12:50:45 -0700 | [diff] [blame] | 6190 | {object} is an instance of any of the specified classes. |
LemonBoy | afe0466 | 2023-08-23 21:08:11 +0200 | [diff] [blame] | 6191 | Example: > |
Ernie Rael | 2025af1 | 2023-12-12 16:58:00 +0100 | [diff] [blame] | 6192 | instanceof(animal, Dog, Cat) |
LemonBoy | afe0466 | 2023-08-23 21:08:11 +0200 | [diff] [blame] | 6193 | |
| 6194 | < Can also be used as a |method|: > |
| 6195 | myobj->instanceof(mytype) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6196 | < |
| 6197 | Return type: |Number| |
LemonBoy | afe0466 | 2023-08-23 21:08:11 +0200 | [diff] [blame] | 6198 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6199 | interrupt() *interrupt()* |
| 6200 | Interrupt script execution. It works more or less like the |
| 6201 | user typing CTRL-C, most commands won't execute and control |
| 6202 | returns to the user. This is useful to abort execution |
| 6203 | from lower down, e.g. in an autocommand. Example: > |
| 6204 | :function s:check_typoname(file) |
| 6205 | : if fnamemodify(a:file, ':t') == '[' |
| 6206 | : echomsg 'Maybe typo' |
| 6207 | : call interrupt() |
| 6208 | : endif |
| 6209 | :endfunction |
| 6210 | :au BufWritePre * call s:check_typoname(expand('<amatch>')) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6211 | < |
| 6212 | Return type: void |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6213 | |
| 6214 | invert({expr}) *invert()* |
| 6215 | Bitwise invert. The argument is converted to a number. A |
| 6216 | List, Dict or Float argument causes an error. Example: > |
| 6217 | :let bits = invert(bits) |
| 6218 | < Can also be used as a |method|: > |
| 6219 | :let bits = bits->invert() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6220 | < |
| 6221 | Return type: |Number| |
| 6222 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6223 | |
Bram Moolenaar | 8a3b805 | 2022-06-26 12:21:15 +0100 | [diff] [blame] | 6224 | isabsolutepath({path}) *isabsolutepath()* |
LemonBoy | dca1d40 | 2022-04-28 15:26:33 +0100 | [diff] [blame] | 6225 | The result is a Number, which is |TRUE| when {path} is an |
| 6226 | absolute path. |
Bram Moolenaar | 8a3b805 | 2022-06-26 12:21:15 +0100 | [diff] [blame] | 6227 | On Unix, a path is considered absolute when it starts with '/'. |
LemonBoy | dca1d40 | 2022-04-28 15:26:33 +0100 | [diff] [blame] | 6228 | On MS-Windows, it is considered absolute when it starts with an |
| 6229 | optional drive prefix and is followed by a '\' or '/'. UNC paths |
| 6230 | are always absolute. |
| 6231 | Example: > |
| 6232 | echo isabsolutepath('/usr/share/') " 1 |
| 6233 | echo isabsolutepath('./foobar') " 0 |
| 6234 | echo isabsolutepath('C:\Windows') " 1 |
| 6235 | echo isabsolutepath('foobar') " 0 |
| 6236 | echo isabsolutepath('\\remote\file') " 1 |
Bram Moolenaar | 8a3b805 | 2022-06-26 12:21:15 +0100 | [diff] [blame] | 6237 | < |
LemonBoy | dca1d40 | 2022-04-28 15:26:33 +0100 | [diff] [blame] | 6238 | Can also be used as a |method|: > |
| 6239 | GetName()->isabsolutepath() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6240 | < |
| 6241 | Return type: |Number| |
LemonBoy | dca1d40 | 2022-04-28 15:26:33 +0100 | [diff] [blame] | 6242 | |
| 6243 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6244 | isdirectory({directory}) *isdirectory()* |
| 6245 | The result is a Number, which is |TRUE| when a directory |
| 6246 | with the name {directory} exists. If {directory} doesn't |
| 6247 | exist, or isn't a directory, the result is |FALSE|. {directory} |
| 6248 | is any expression, which is used as a String. |
| 6249 | |
| 6250 | Can also be used as a |method|: > |
| 6251 | GetName()->isdirectory() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6252 | < |
| 6253 | Return type: |Number| |
| 6254 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6255 | |
| 6256 | isinf({expr}) *isinf()* |
| 6257 | Return 1 if {expr} is a positive infinity, or -1 a negative |
| 6258 | infinity, otherwise 0. > |
| 6259 | :echo isinf(1.0 / 0.0) |
| 6260 | < 1 > |
| 6261 | :echo isinf(-1.0 / 0.0) |
| 6262 | < -1 |
| 6263 | |
| 6264 | Can also be used as a |method|: > |
| 6265 | Compute()->isinf() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6266 | < |
| 6267 | Return type: |Number| |
| 6268 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6269 | |
| 6270 | islocked({expr}) *islocked()* *E786* |
| 6271 | The result is a Number, which is |TRUE| when {expr} is the |
| 6272 | name of a locked variable. |
| 6273 | The string argument {expr} must be the name of a variable, |
| 6274 | |List| item or |Dictionary| entry, not the variable itself! |
| 6275 | Example: > |
| 6276 | :let alist = [0, ['a', 'b'], 2, 3] |
| 6277 | :lockvar 1 alist |
| 6278 | :echo islocked('alist') " 1 |
| 6279 | :echo islocked('alist[1]') " 0 |
| 6280 | |
Bram Moolenaar | 9da17d7 | 2022-02-09 21:50:44 +0000 | [diff] [blame] | 6281 | < When {expr} is a variable that does not exist -1 is returned. |
| 6282 | If {expr} uses a range, list or dict index that is out of |
| 6283 | range or does not exist you get an error message. Use |
| 6284 | |exists()| to check for existence. |
| 6285 | In Vim9 script it does not work for local function variables. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6286 | |
| 6287 | Can also be used as a |method|: > |
| 6288 | GetName()->islocked() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6289 | < |
| 6290 | Return type: |Number| |
| 6291 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6292 | |
| 6293 | isnan({expr}) *isnan()* |
| 6294 | Return |TRUE| if {expr} is a float with value NaN. > |
| 6295 | echo isnan(0.0 / 0.0) |
| 6296 | < 1 |
| 6297 | |
| 6298 | Can also be used as a |method|: > |
| 6299 | Compute()->isnan() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6300 | < |
| 6301 | Return type: |Number| |
| 6302 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6303 | |
| 6304 | items({dict}) *items()* |
| 6305 | Return a |List| with all the key-value pairs of {dict}. Each |
| 6306 | |List| item is a list with two items: the key of a {dict} |
| 6307 | entry and the value of this entry. The |List| is in arbitrary |
| 6308 | order. Also see |keys()| and |values()|. |
| 6309 | Example: > |
| 6310 | for [key, value] in items(mydict) |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 6311 | echo key .. ': ' .. value |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6312 | endfor |
Yegappan Lakshmanan | 49cdd62 | 2023-12-24 11:01:23 +0100 | [diff] [blame] | 6313 | < |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 6314 | A |List|, a |Tuple| or a |String| argument is also supported. |
| 6315 | In these cases, items() returns a List with the index and the |
| 6316 | value at the index. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6317 | |
Yegappan Lakshmanan | 49cdd62 | 2023-12-24 11:01:23 +0100 | [diff] [blame] | 6318 | Can also be used as a |method|: > |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6319 | mydict->items() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6320 | < |
| 6321 | Return type: list<list<any>> or list<any> |
| 6322 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6323 | |
| 6324 | job_ functions are documented here: |job-functions-details| |
| 6325 | |
| 6326 | |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 6327 | join({expr} [, {sep}]) *join()* |
| 6328 | Join the items in {expr} together into one String. {expr} can |
| 6329 | be a |List| or a |Tuple|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6330 | When {sep} is specified it is put in between the items. If |
| 6331 | {sep} is omitted a single space is used. |
| 6332 | Note that {sep} is not added at the end. You might want to |
| 6333 | add it there too: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 6334 | let lines = join(mylist, "\n") .. "\n" |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 6335 | < String items are used as-is. |Lists|, |Tuples| and |
| 6336 | |Dictionaries| are converted into a string like with |
| 6337 | |string()|. The opposite function is |split()|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6338 | |
| 6339 | Can also be used as a |method|: > |
| 6340 | mylist->join() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6341 | < |
| 6342 | Return type: |String| |
| 6343 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6344 | |
| 6345 | js_decode({string}) *js_decode()* |
| 6346 | This is similar to |json_decode()| with these differences: |
| 6347 | - Object key names do not have to be in quotes. |
| 6348 | - Strings can be in single quotes. |
| 6349 | - Empty items in an array (between two commas) are allowed and |
| 6350 | result in v:none items. |
| 6351 | |
| 6352 | Can also be used as a |method|: > |
| 6353 | ReadObject()->js_decode() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6354 | < |
| 6355 | Return type: any, depending on {varname} |
| 6356 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6357 | |
| 6358 | js_encode({expr}) *js_encode()* |
| 6359 | This is similar to |json_encode()| with these differences: |
| 6360 | - Object key names are not in quotes. |
| 6361 | - v:none items in an array result in an empty item between |
| 6362 | commas. |
| 6363 | For example, the Vim object: |
| 6364 | [1,v:none,{"one":1},v:none] ~ |
| 6365 | Will be encoded as: |
| 6366 | [1,,{one:1},,] ~ |
| 6367 | While json_encode() would produce: |
| 6368 | [1,null,{"one":1},null] ~ |
| 6369 | This encoding is valid for JavaScript. It is more efficient |
| 6370 | than JSON, especially when using an array with optional items. |
| 6371 | |
| 6372 | Can also be used as a |method|: > |
| 6373 | GetObject()->js_encode() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6374 | < |
| 6375 | Return type: |String| |
| 6376 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6377 | |
Bram Moolenaar | 2f0936c | 2022-01-08 21:51:59 +0000 | [diff] [blame] | 6378 | json_decode({string}) *json_decode()* *E491* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6379 | This parses a JSON formatted string and returns the equivalent |
| 6380 | in Vim values. See |json_encode()| for the relation between |
| 6381 | JSON and Vim values. |
| 6382 | The decoding is permissive: |
| 6383 | - A trailing comma in an array and object is ignored, e.g. |
| 6384 | "[1, 2, ]" is the same as "[1, 2]". |
| 6385 | - Integer keys are accepted in objects, e.g. {1:2} is the |
| 6386 | same as {"1":2}. |
| 6387 | - More floating point numbers are recognized, e.g. "1." for |
| 6388 | "1.0", or "001.2" for "1.2". Special floating point values |
| 6389 | "Infinity", "-Infinity" and "NaN" (capitalization ignored) |
| 6390 | are accepted. |
| 6391 | - Leading zeroes in integer numbers are ignored, e.g. "012" |
| 6392 | for "12" or "-012" for "-12". |
| 6393 | - Capitalization is ignored in literal names null, true or |
| 6394 | false, e.g. "NULL" for "null", "True" for "true". |
| 6395 | - Control characters U+0000 through U+001F which are not |
| 6396 | escaped in strings are accepted, e.g. " " (tab |
| 6397 | character in string) for "\t". |
| 6398 | - An empty JSON expression or made of only spaces is accepted |
| 6399 | and results in v:none. |
| 6400 | - Backslash in an invalid 2-character sequence escape is |
| 6401 | ignored, e.g. "\a" is decoded as "a". |
| 6402 | - A correct surrogate pair in JSON strings should normally be |
| 6403 | a 12 character sequence such as "\uD834\uDD1E", but |
| 6404 | json_decode() silently accepts truncated surrogate pairs |
| 6405 | such as "\uD834" or "\uD834\u" |
| 6406 | *E938* |
| 6407 | A duplicate key in an object, valid in rfc7159, is not |
| 6408 | accepted by json_decode() as the result must be a valid Vim |
| 6409 | type, e.g. this fails: {"a":"b", "a":"c"} |
| 6410 | |
| 6411 | Can also be used as a |method|: > |
| 6412 | ReadObject()->json_decode() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6413 | < |
| 6414 | Return type: any, depending on {varname} |
| 6415 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6416 | |
| 6417 | json_encode({expr}) *json_encode()* |
| 6418 | Encode {expr} as JSON and return this as a string. |
| 6419 | The encoding is specified in: |
| 6420 | https://tools.ietf.org/html/rfc7159.html |
Bram Moolenaar | a2baa73 | 2022-02-04 16:09:54 +0000 | [diff] [blame] | 6421 | Vim values are converted as follows: *E1161* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6422 | |Number| decimal number |
| 6423 | |Float| floating point number |
| 6424 | Float nan "NaN" |
| 6425 | Float inf "Infinity" |
| 6426 | Float -inf "-Infinity" |
| 6427 | |String| in double quotes (possibly null) |
| 6428 | |Funcref| not possible, error |
| 6429 | |List| as an array (possibly null); when |
| 6430 | used recursively: [] |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 6431 | |Tuple| as an array (possibly null); when |
| 6432 | used recursively: [] |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6433 | |Dict| as an object (possibly null); when |
| 6434 | used recursively: {} |
| 6435 | |Blob| as an array of the individual bytes |
| 6436 | v:false "false" |
| 6437 | v:true "true" |
| 6438 | v:none "null" |
| 6439 | v:null "null" |
| 6440 | Note that NaN and Infinity are passed on as values. This is |
| 6441 | missing in the JSON standard, but several implementations do |
| 6442 | allow it. If not then you will get an error. |
Bram Moolenaar | cbaff5e | 2022-04-08 17:45:08 +0100 | [diff] [blame] | 6443 | If a string contains an illegal character then the replacement |
| 6444 | character 0xfffd is used. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6445 | |
| 6446 | Can also be used as a |method|: > |
| 6447 | GetObject()->json_encode() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6448 | < |
| 6449 | Return type: |String| |
| 6450 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6451 | |
| 6452 | keys({dict}) *keys()* |
| 6453 | Return a |List| with all the keys of {dict}. The |List| is in |
| 6454 | arbitrary order. Also see |items()| and |values()|. |
| 6455 | |
| 6456 | Can also be used as a |method|: > |
| 6457 | mydict->keys() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6458 | < |
| 6459 | Return type: list<string> |
| 6460 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6461 | |
zeertzjq | cdc8393 | 2022-09-12 13:38:41 +0100 | [diff] [blame] | 6462 | keytrans({string}) *keytrans()* |
| 6463 | Turn the internal byte representation of keys into a form that |
| 6464 | can be used for |:map|. E.g. > |
| 6465 | :let xx = "\<C-Home>" |
| 6466 | :echo keytrans(xx) |
| 6467 | < <C-Home> |
| 6468 | |
| 6469 | Can also be used as a |method|: > |
| 6470 | "\<C-Home>"->keytrans() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6471 | < |
| 6472 | Return type: |String| |
zeertzjq | cdc8393 | 2022-09-12 13:38:41 +0100 | [diff] [blame] | 6473 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6474 | |
| 6475 | len({expr}) *len()* *E701* |
| 6476 | The result is a Number, which is the length of the argument. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6477 | When {expr} is a String or a Number the length in bytes is |
| 6478 | used, as with |strlen()|. |
| 6479 | When {expr} is a |List| the number of items in the |List| is |
| 6480 | returned. |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 6481 | When {expr} is a |Tuple| the number of items in the |Tuple| is |
| 6482 | returned. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6483 | When {expr} is a |Blob| the number of bytes is returned. |
| 6484 | When {expr} is a |Dictionary| the number of entries in the |
| 6485 | |Dictionary| is returned. |
mityu | 7f0bba2 | 2024-03-29 10:14:41 +0100 | [diff] [blame] | 6486 | When {expr} is an |Object|, invokes the len() method in the |
| 6487 | object (if present) to get the length (|object-len()|). |
| 6488 | Otherwise returns zero. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6489 | |
| 6490 | Can also be used as a |method|: > |
| 6491 | mylist->len() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6492 | < |
| 6493 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6494 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6495 | |
| 6496 | *libcall()* *E364* *E368* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6497 | libcall({libname}, {funcname}, {argument}) |
| 6498 | Call function {funcname} in the run-time library {libname} |
| 6499 | with single argument {argument}. |
| 6500 | This is useful to call functions in a library that you |
| 6501 | especially made to be used with Vim. Since only one argument |
| 6502 | is possible, calling standard library functions is rather |
| 6503 | limited. |
| 6504 | The result is the String returned by the function. If the |
| 6505 | function returns NULL, this will appear as an empty string "" |
| 6506 | to Vim. |
| 6507 | If the function returns a number, use libcallnr()! |
| 6508 | If {argument} is a number, it is passed to the function as an |
| 6509 | int; if {argument} is a string, it is passed as a |
| 6510 | null-terminated string. |
| 6511 | This function will fail in |restricted-mode|. |
| 6512 | |
| 6513 | libcall() allows you to write your own 'plug-in' extensions to |
| 6514 | Vim without having to recompile the program. It is NOT a |
| 6515 | means to call system functions! If you try to do so Vim will |
| 6516 | very probably crash. |
| 6517 | |
| 6518 | For Win32, the functions you write must be placed in a DLL |
| 6519 | and use the normal C calling convention (NOT Pascal which is |
| 6520 | used in Windows System DLLs). The function must take exactly |
| 6521 | one parameter, either a character pointer or a long integer, |
| 6522 | and must return a character pointer or NULL. The character |
| 6523 | pointer returned must point to memory that will remain valid |
| 6524 | after the function has returned (e.g. in static data in the |
| 6525 | DLL). If it points to allocated memory, that memory will |
| 6526 | leak away. Using a static buffer in the function should work, |
| 6527 | it's then freed when the DLL is unloaded. |
| 6528 | |
| 6529 | WARNING: If the function returns a non-valid pointer, Vim may |
| 6530 | crash! This also happens if the function returns a number, |
| 6531 | because Vim thinks it's a pointer. |
| 6532 | For Win32 systems, {libname} should be the filename of the DLL |
| 6533 | without the ".DLL" suffix. A full path is only required if |
| 6534 | the DLL is not in the usual places. |
| 6535 | For Unix: When compiling your own plugins, remember that the |
| 6536 | object code must be compiled as position-independent ('PIC'). |
| 6537 | {only in Win32 and some Unix versions, when the |+libcall| |
| 6538 | feature is present} |
| 6539 | Examples: > |
| 6540 | :echo libcall("libc.so", "getenv", "HOME") |
| 6541 | |
| 6542 | < Can also be used as a |method|, the base is passed as the |
| 6543 | third argument: > |
| 6544 | GetValue()->libcall("libc.so", "getenv") |
| 6545 | < |
| 6546 | *libcallnr()* |
| 6547 | libcallnr({libname}, {funcname}, {argument}) |
| 6548 | Just like |libcall()|, but used for a function that returns an |
| 6549 | int instead of a string. |
| 6550 | {only in Win32 on some Unix versions, when the |+libcall| |
| 6551 | feature is present} |
| 6552 | Examples: > |
| 6553 | :echo libcallnr("/usr/lib/libc.so", "getpid", "") |
| 6554 | :call libcallnr("libc.so", "printf", "Hello World!\n") |
| 6555 | :call libcallnr("libc.so", "sleep", 10) |
| 6556 | < |
| 6557 | Can also be used as a |method|, the base is passed as the |
| 6558 | third argument: > |
| 6559 | GetValue()->libcallnr("libc.so", "printf") |
| 6560 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6561 | Return type: |String| |
| 6562 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6563 | |
| 6564 | line({expr} [, {winid}]) *line()* |
| 6565 | The result is a Number, which is the line number of the file |
| 6566 | position given with {expr}. The {expr} argument is a string. |
zeertzjq | 02f3eba | 2024-06-12 20:45:24 +0200 | [diff] [blame] | 6567 | See |getpos()| for accepted positions. |
| 6568 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6569 | To get the column number use |col()|. To get both use |
| 6570 | |getpos()|. |
zeertzjq | 02f3eba | 2024-06-12 20:45:24 +0200 | [diff] [blame] | 6571 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6572 | With the optional {winid} argument the values are obtained for |
| 6573 | that window instead of the current window. |
zeertzjq | 02f3eba | 2024-06-12 20:45:24 +0200 | [diff] [blame] | 6574 | |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 6575 | Returns 0 for invalid values of {expr} and {winid}. |
zeertzjq | 02f3eba | 2024-06-12 20:45:24 +0200 | [diff] [blame] | 6576 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6577 | Examples: > |
| 6578 | line(".") line number of the cursor |
| 6579 | line(".", winid) idem, in window "winid" |
| 6580 | line("'t") line number of mark t |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 6581 | line("'" .. marker) line number of mark marker |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6582 | < |
| 6583 | To jump to the last known position when opening a file see |
| 6584 | |last-position-jump|. |
| 6585 | |
| 6586 | Can also be used as a |method|: > |
| 6587 | GetValue()->line() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6588 | < |
| 6589 | Return type: |Number| |
| 6590 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6591 | |
| 6592 | line2byte({lnum}) *line2byte()* |
| 6593 | Return the byte count from the start of the buffer for line |
| 6594 | {lnum}. This includes the end-of-line character, depending on |
| 6595 | the 'fileformat' option for the current buffer. The first |
| 6596 | line returns 1. 'encoding' matters, 'fileencoding' is ignored. |
| 6597 | This can also be used to get the byte count for the line just |
| 6598 | below the last line: > |
| 6599 | line2byte(line("$") + 1) |
| 6600 | < This is the buffer size plus one. If 'fileencoding' is empty |
| 6601 | it is the file size plus one. {lnum} is used like with |
| 6602 | |getline()|. When {lnum} is invalid, or the |+byte_offset| |
| 6603 | feature has been disabled at compile time, -1 is returned. |
| 6604 | Also see |byte2line()|, |go| and |:goto|. |
| 6605 | |
| 6606 | Can also be used as a |method|: > |
| 6607 | GetLnum()->line2byte() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6608 | < |
| 6609 | Return type: |Number| |
| 6610 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6611 | |
| 6612 | lispindent({lnum}) *lispindent()* |
| 6613 | Get the amount of indent for line {lnum} according the lisp |
| 6614 | indenting rules, as with 'lisp'. |
| 6615 | The indent is counted in spaces, the value of 'tabstop' is |
| 6616 | relevant. {lnum} is used just like in |getline()|. |
Bram Moolenaar | 8e145b8 | 2022-05-21 20:17:31 +0100 | [diff] [blame] | 6617 | When {lnum} is invalid -1 is returned. In |Vim9| script an |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6618 | error is given. |
| 6619 | |
| 6620 | Can also be used as a |method|: > |
| 6621 | GetLnum()->lispindent() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6622 | < |
| 6623 | Return type: |Number| |
| 6624 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6625 | |
| 6626 | list2blob({list}) *list2blob()* |
| 6627 | Return a Blob concatenating all the number values in {list}. |
| 6628 | Examples: > |
| 6629 | list2blob([1, 2, 3, 4]) returns 0z01020304 |
| 6630 | list2blob([]) returns 0z |
| 6631 | < Returns an empty Blob on error. If one of the numbers is |
| 6632 | negative or more than 255 error *E1239* is given. |
| 6633 | |
| 6634 | |blob2list()| does the opposite. |
| 6635 | |
| 6636 | Can also be used as a |method|: > |
| 6637 | GetList()->list2blob() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6638 | < |
| 6639 | Return type: |Blob| |
| 6640 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6641 | |
| 6642 | list2str({list} [, {utf8}]) *list2str()* |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6643 | Convert each number in {list} to a character string and |
| 6644 | concatenates them all. Examples: > |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6645 | list2str([32]) returns " " |
| 6646 | list2str([65, 66, 67]) returns "ABC" |
| 6647 | < The same can be done (slowly) with: > |
| 6648 | join(map(list, {nr, val -> nr2char(val)}), '') |
| 6649 | < |str2list()| does the opposite. |
| 6650 | |
| 6651 | When {utf8} is omitted or zero, the current 'encoding' is used. |
| 6652 | When {utf8} is TRUE, always return UTF-8 characters. |
| 6653 | With UTF-8 composing characters work as expected: > |
| 6654 | list2str([97, 769]) returns "á" |
| 6655 | < |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 6656 | Returns an empty string on error. |
| 6657 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6658 | Can also be used as a |method|: > |
| 6659 | GetList()->list2str() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6660 | < |
| 6661 | Return type: |String| |
| 6662 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6663 | |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 6664 | list2tuple({list}) *list2tuple()* |
| 6665 | Create a Tuple from a shallow copy of the list items. |
| 6666 | Examples: > |
| 6667 | list2tuple([1, 2, 3]) returns (1, 2, 3) |
| 6668 | < |tuple2list()| does the opposite. |
| 6669 | |
| 6670 | This function doesn't recursively convert all the List items |
| 6671 | in {list} to a Tuple. Note that the items are identical |
| 6672 | between the list and the tuple, changing an item changes the |
| 6673 | contents of both the tuple and the list. |
| 6674 | |
| 6675 | Returns an empty tuple on error. |
| 6676 | |
| 6677 | Can also be used as a |method|: > |
| 6678 | GetList()->list2tuple() |
| 6679 | < |
| 6680 | Return type: tuple<{type}> (depending on the given |List|) |
| 6681 | |
| 6682 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6683 | listener_add({callback} [, {buf}]) *listener_add()* |
| 6684 | Add a callback function that will be invoked when changes have |
| 6685 | been made to buffer {buf}. |
| 6686 | {buf} refers to a buffer name or number. For the accepted |
| 6687 | values, see |bufname()|. When {buf} is omitted the current |
| 6688 | buffer is used. |
| 6689 | Returns a unique ID that can be passed to |listener_remove()|. |
| 6690 | |
| 6691 | The {callback} is invoked with five arguments: |
Bram Moolenaar | 944697a | 2022-02-20 19:48:20 +0000 | [diff] [blame] | 6692 | bufnr the buffer that was changed |
| 6693 | start first changed line number |
| 6694 | end first line number below the change |
| 6695 | added number of lines added, negative if lines were |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6696 | deleted |
Bram Moolenaar | 944697a | 2022-02-20 19:48:20 +0000 | [diff] [blame] | 6697 | changes a List of items with details about the changes |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6698 | |
| 6699 | Example: > |
| 6700 | func Listener(bufnr, start, end, added, changes) |
| 6701 | echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed' |
| 6702 | endfunc |
| 6703 | call listener_add('Listener', bufnr) |
| 6704 | |
Bram Moolenaar | 944697a | 2022-02-20 19:48:20 +0000 | [diff] [blame] | 6705 | < The List cannot be changed. Each item in "changes" is a |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6706 | dictionary with these entries: |
| 6707 | lnum the first line number of the change |
| 6708 | end the first line below the change |
| 6709 | added number of lines added; negative if lines were |
| 6710 | deleted |
| 6711 | col first column in "lnum" that was affected by |
| 6712 | the change; one if unknown or the whole line |
| 6713 | was affected; this is a byte index, first |
| 6714 | character has a value of one. |
Bram Moolenaar | 3c053a1 | 2022-10-16 13:11:12 +0100 | [diff] [blame] | 6715 | When lines are inserted (not when a line is split, e.g. by |
| 6716 | typing CR in Insert mode) the values are: |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6717 | lnum line above which the new line is added |
| 6718 | end equal to "lnum" |
| 6719 | added number of lines inserted |
| 6720 | col 1 |
| 6721 | When lines are deleted the values are: |
| 6722 | lnum the first deleted line |
| 6723 | end the line below the first deleted line, before |
| 6724 | the deletion was done |
| 6725 | added negative, number of lines deleted |
| 6726 | col 1 |
| 6727 | When lines are changed: |
| 6728 | lnum the first changed line |
| 6729 | end the line below the last changed line |
| 6730 | added 0 |
| 6731 | col first column with a change or 1 |
| 6732 | |
| 6733 | The entries are in the order the changes were made, thus the |
| 6734 | most recent change is at the end. The line numbers are valid |
| 6735 | when the callback is invoked, but later changes may make them |
| 6736 | invalid, thus keeping a copy for later might not work. |
| 6737 | |
| 6738 | The {callback} is invoked just before the screen is updated, |
| 6739 | when |listener_flush()| is called or when a change is being |
| 6740 | made that changes the line count in a way it causes a line |
| 6741 | number in the list of changes to become invalid. |
| 6742 | |
| 6743 | The {callback} is invoked with the text locked, see |
| 6744 | |textlock|. If you do need to make changes to the buffer, use |
| 6745 | a timer to do this later |timer_start()|. |
| 6746 | |
| 6747 | The {callback} is not invoked when the buffer is first loaded. |
| 6748 | Use the |BufReadPost| autocmd event to handle the initial text |
| 6749 | of a buffer. |
| 6750 | The {callback} is also not invoked when the buffer is |
| 6751 | unloaded, use the |BufUnload| autocmd event for that. |
| 6752 | |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 6753 | Returns zero if {callback} or {buf} is invalid. |
| 6754 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6755 | Can also be used as a |method|, the base is passed as the |
| 6756 | second argument: > |
| 6757 | GetBuffer()->listener_add(callback) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6758 | < |
| 6759 | Return type: |Number| |
| 6760 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6761 | |
| 6762 | listener_flush([{buf}]) *listener_flush()* |
| 6763 | Invoke listener callbacks for buffer {buf}. If there are no |
| 6764 | pending changes then no callbacks are invoked. |
| 6765 | |
| 6766 | {buf} refers to a buffer name or number. For the accepted |
| 6767 | values, see |bufname()|. When {buf} is omitted the current |
| 6768 | buffer is used. |
| 6769 | |
| 6770 | Can also be used as a |method|: > |
| 6771 | GetBuffer()->listener_flush() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6772 | < |
| 6773 | Return type: |Number| |
| 6774 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6775 | |
| 6776 | listener_remove({id}) *listener_remove()* |
| 6777 | Remove a listener previously added with listener_add(). |
| 6778 | Returns FALSE when {id} could not be found, TRUE when {id} was |
| 6779 | removed. |
| 6780 | |
| 6781 | Can also be used as a |method|: > |
| 6782 | GetListenerId()->listener_remove() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6783 | < |
| 6784 | Return type: |Number| |
| 6785 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6786 | |
| 6787 | localtime() *localtime()* |
| 6788 | Return the current time, measured as seconds since 1st Jan |
| 6789 | 1970. See also |strftime()|, |strptime()| and |getftime()|. |
| 6790 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6791 | Return type: |Number| |
| 6792 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6793 | |
| 6794 | log({expr}) *log()* |
| 6795 | Return the natural logarithm (base e) of {expr} as a |Float|. |
| 6796 | {expr} must evaluate to a |Float| or a |Number| in the range |
| 6797 | (0, inf]. |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 6798 | Returns 0.0 if {expr} is not a |Float| or a |Number|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6799 | Examples: > |
| 6800 | :echo log(10) |
| 6801 | < 2.302585 > |
| 6802 | :echo log(exp(5)) |
| 6803 | < 5.0 |
| 6804 | |
| 6805 | Can also be used as a |method|: > |
| 6806 | Compute()->log() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6807 | < |
| 6808 | Return type: |Float| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6809 | |
| 6810 | |
| 6811 | log10({expr}) *log10()* |
| 6812 | Return the logarithm of Float {expr} to base 10 as a |Float|. |
| 6813 | {expr} must evaluate to a |Float| or a |Number|. |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 6814 | Returns 0.0 if {expr} is not a |Float| or a |Number|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6815 | Examples: > |
| 6816 | :echo log10(1000) |
| 6817 | < 3.0 > |
| 6818 | :echo log10(0.01) |
| 6819 | < -2.0 |
| 6820 | |
| 6821 | Can also be used as a |method|: > |
| 6822 | Compute()->log10() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6823 | < |
| 6824 | Return type: |Float| |
| 6825 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6826 | |
| 6827 | luaeval({expr} [, {expr}]) *luaeval()* |
| 6828 | Evaluate Lua expression {expr} and return its result converted |
| 6829 | to Vim data structures. Second {expr} may hold additional |
| 6830 | argument accessible as _A inside first {expr}. |
| 6831 | Strings are returned as they are. |
| 6832 | Boolean objects are converted to numbers. |
Bram Moolenaar | 73e28dc | 2022-09-17 21:08:33 +0100 | [diff] [blame] | 6833 | Numbers are converted to |Float| values. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6834 | Dictionaries and lists obtained by vim.eval() are returned |
| 6835 | as-is. |
| 6836 | Other objects are returned as zero without any errors. |
| 6837 | See |lua-luaeval| for more details. |
| 6838 | Note that in a `:def` function local variables are not visible |
| 6839 | to {expr}. |
| 6840 | |
| 6841 | Can also be used as a |method|: > |
| 6842 | GetExpr()->luaeval() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6843 | < |
| 6844 | Return type: any, depending on {expr} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6845 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6846 | {only available when compiled with the |+lua| feature} |
| 6847 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6848 | |
| 6849 | map({expr1}, {expr2}) *map()* |
| 6850 | {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. |
Bram Moolenaar | 944697a | 2022-02-20 19:48:20 +0000 | [diff] [blame] | 6851 | When {expr1} is a |List| or |Dictionary|, replace each |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6852 | item in {expr1} with the result of evaluating {expr2}. |
| 6853 | For a |Blob| each byte is replaced. |
| 6854 | For a |String|, each character, including composing |
| 6855 | characters, is replaced. |
| 6856 | If the item type changes you may want to use |mapnew()| to |
| 6857 | create a new List or Dictionary. This is required when using |
| 6858 | Vim9 script. |
| 6859 | |
| 6860 | {expr2} must be a |String| or |Funcref|. |
| 6861 | |
| 6862 | If {expr2} is a |String|, inside {expr2} |v:val| has the value |
| 6863 | of the current item. For a |Dictionary| |v:key| has the key |
| 6864 | of the current item and for a |List| |v:key| has the index of |
| 6865 | the current item. For a |Blob| |v:key| has the index of the |
| 6866 | current byte. For a |String| |v:key| has the index of the |
| 6867 | current character. |
| 6868 | Example: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 6869 | :call map(mylist, '"> " .. v:val .. " <"') |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6870 | < This puts "> " before and " <" after each item in "mylist". |
| 6871 | |
| 6872 | Note that {expr2} is the result of an expression and is then |
| 6873 | used as an expression again. Often it is good to use a |
| 6874 | |literal-string| to avoid having to double backslashes. You |
| 6875 | still have to double ' quotes |
| 6876 | |
| 6877 | If {expr2} is a |Funcref| it is called with two arguments: |
| 6878 | 1. The key or the index of the current item. |
| 6879 | 2. the value of the current item. |
Bram Moolenaar | b59ae59 | 2022-11-23 23:46:31 +0000 | [diff] [blame] | 6880 | With a legacy script lambda you don't get an error if it only |
| 6881 | accepts one argument, but with a Vim9 lambda you get "E1106: |
| 6882 | One argument too many", the number of arguments must match. |
| 6883 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6884 | The function must return the new value of the item. Example |
| 6885 | that changes each value by "key-value": > |
| 6886 | func KeyValue(key, val) |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 6887 | return a:key .. '-' .. a:val |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6888 | endfunc |
| 6889 | call map(myDict, function('KeyValue')) |
| 6890 | < It is shorter when using a |lambda|: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 6891 | call map(myDict, {key, val -> key .. '-' .. val}) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6892 | < If you do not use "val" you can leave it out: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 6893 | call map(myDict, {key -> 'item: ' .. key}) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6894 | < If you do not use "key" you can use a short name: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 6895 | call map(myDict, {_, val -> 'item: ' .. val}) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6896 | < |
| 6897 | The operation is done in-place for a |List| and |Dictionary|. |
| 6898 | If you want it to remain unmodified make a copy first: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 6899 | :let tlist = map(copy(mylist), ' v:val .. "\t"') |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6900 | |
| 6901 | < Returns {expr1}, the |List| or |Dictionary| that was filtered, |
| 6902 | or a new |Blob| or |String|. |
| 6903 | When an error is encountered while evaluating {expr2} no |
| 6904 | further items in {expr1} are processed. |
| 6905 | When {expr2} is a Funcref errors inside a function are ignored, |
| 6906 | unless it was defined with the "abort" flag. |
| 6907 | |
| 6908 | Can also be used as a |method|: > |
| 6909 | mylist->map(expr2) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6910 | < |
| 6911 | Return type: |String|, |Blob|, list<{type}> or dict<{type}> |
| 6912 | depending on {expr1} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6913 | |
| 6914 | |
| 6915 | maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()* |
| 6916 | When {dict} is omitted or zero: Return the rhs of mapping |
| 6917 | {name} in mode {mode}. The returned String has special |
| 6918 | characters translated like in the output of the ":map" command |
Ernie Rael | 0966120 | 2022-04-25 14:40:44 +0100 | [diff] [blame] | 6919 | listing. When {dict} is TRUE a dictionary is returned, see |
| 6920 | below. To get a list of all mappings see |maplist()|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6921 | |
| 6922 | When there is no mapping for {name}, an empty String is |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 6923 | returned if {dict} is FALSE, otherwise returns an empty Dict. |
| 6924 | When the mapping for {name} is empty, then "<Nop>" is |
| 6925 | returned. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6926 | |
| 6927 | The {name} can have special key names, like in the ":map" |
| 6928 | command. |
| 6929 | |
| 6930 | {mode} can be one of these strings: |
| 6931 | "n" Normal |
| 6932 | "v" Visual (including Select) |
| 6933 | "o" Operator-pending |
| 6934 | "i" Insert |
| 6935 | "c" Cmd-line |
| 6936 | "s" Select |
| 6937 | "x" Visual |
| 6938 | "l" langmap |language-mapping| |
| 6939 | "t" Terminal-Job |
| 6940 | "" Normal, Visual and Operator-pending |
| 6941 | When {mode} is omitted, the modes for "" are used. |
| 6942 | |
| 6943 | When {abbr} is there and it is |TRUE| use abbreviations |
| 6944 | instead of mappings. |
| 6945 | |
| 6946 | When {dict} is there and it is |TRUE| return a dictionary |
| 6947 | containing all the information of the mapping with the |
Ernie Rael | 659c240 | 2022-04-24 18:40:28 +0100 | [diff] [blame] | 6948 | following items: *mapping-dict* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6949 | "lhs" The {lhs} of the mapping as it would be typed |
| 6950 | "lhsraw" The {lhs} of the mapping as raw bytes |
| 6951 | "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate |
| 6952 | form, only present when it differs from "lhsraw" |
| 6953 | "rhs" The {rhs} of the mapping as typed. |
| 6954 | "silent" 1 for a |:map-silent| mapping, else 0. |
| 6955 | "noremap" 1 if the {rhs} of the mapping is not remappable. |
| 6956 | "script" 1 if mapping was defined with <script>. |
| 6957 | "expr" 1 for an expression mapping (|:map-<expr>|). |
| 6958 | "buffer" 1 for a buffer local mapping (|:map-local|). |
| 6959 | "mode" Modes for which the mapping is defined. In |
| 6960 | addition to the modes mentioned above, these |
| 6961 | characters will be used: |
| 6962 | " " Normal, Visual and Operator-pending |
| 6963 | "!" Insert and Commandline mode |
| 6964 | (|mapmode-ic|) |
| 6965 | "sid" The script local ID, used for <sid> mappings |
Bram Moolenaar | 71badf9 | 2023-04-22 22:40:14 +0100 | [diff] [blame] | 6966 | (|<SID>|). Negative for special contexts. |
Bram Moolenaar | a9528b3 | 2022-01-18 20:51:35 +0000 | [diff] [blame] | 6967 | "scriptversion" The version of the script. 999999 for |
Bram Moolenaar | 2d8ed02 | 2022-05-21 13:08:16 +0100 | [diff] [blame] | 6968 | |Vim9| script. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6969 | "lnum" The line number in "sid", zero if unknown. |
| 6970 | "nowait" Do not wait for other, longer mappings. |
| 6971 | (|:map-<nowait>|). |
Bram Moolenaar | 921bde8 | 2022-05-09 19:50:35 +0100 | [diff] [blame] | 6972 | "abbr" True if this is an abbreviation |abbreviations|. |
Ernie Rael | d8f5f76 | 2022-05-10 17:50:39 +0100 | [diff] [blame] | 6973 | "mode_bits" Vim's internal binary representation of "mode". |
| 6974 | |mapset()| ignores this; only "mode" is used. |
| 6975 | See |maplist()| for usage examples. The values |
| 6976 | are from src/vim.h and may change in the future. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6977 | |
| 6978 | The dictionary can be used to restore a mapping with |
| 6979 | |mapset()|. |
| 6980 | |
| 6981 | The mappings local to the current buffer are checked first, |
| 6982 | then the global mappings. |
| 6983 | This function can be used to map a key even when it's already |
| 6984 | mapped, and have it do the original mapping too. Sketch: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 6985 | exe 'nnoremap <Tab> ==' .. maparg('<Tab>', 'n') |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6986 | |
| 6987 | < Can also be used as a |method|: > |
| 6988 | GetKey()->maparg('n') |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 6989 | < |
| 6990 | Return type: |String| or dict<any> depending on {dict} |
| 6991 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 6992 | |
| 6993 | mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()* |
| 6994 | Check if there is a mapping that matches with {name} in mode |
| 6995 | {mode}. See |maparg()| for {mode} and special names in |
| 6996 | {name}. |
| 6997 | When {abbr} is there and it is |TRUE| use abbreviations |
| 6998 | instead of mappings. |
| 6999 | A match happens with a mapping that starts with {name} and |
| 7000 | with a mapping which is equal to the start of {name}. |
| 7001 | |
| 7002 | matches mapping "a" "ab" "abc" ~ |
| 7003 | mapcheck("a") yes yes yes |
| 7004 | mapcheck("abc") yes yes yes |
| 7005 | mapcheck("ax") yes no no |
| 7006 | mapcheck("b") no no no |
| 7007 | |
| 7008 | The difference with maparg() is that mapcheck() finds a |
| 7009 | mapping that matches with {name}, while maparg() only finds a |
| 7010 | mapping for {name} exactly. |
| 7011 | When there is no mapping that starts with {name}, an empty |
| 7012 | String is returned. If there is one, the RHS of that mapping |
| 7013 | is returned. If there are several mappings that start with |
| 7014 | {name}, the RHS of one of them is returned. This will be |
| 7015 | "<Nop>" if the RHS is empty. |
| 7016 | The mappings local to the current buffer are checked first, |
| 7017 | then the global mappings. |
| 7018 | This function can be used to check if a mapping can be added |
| 7019 | without being ambiguous. Example: > |
| 7020 | :if mapcheck("_vv") == "" |
| 7021 | : map _vv :set guifont=7x13<CR> |
| 7022 | :endif |
| 7023 | < This avoids adding the "_vv" mapping when there already is a |
| 7024 | mapping for "_v" or for "_vvv". |
| 7025 | |
| 7026 | Can also be used as a |method|: > |
| 7027 | GetKey()->mapcheck('n') |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7028 | < |
| 7029 | Return type: |String| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7030 | |
| 7031 | |
Ernie Rael | 0966120 | 2022-04-25 14:40:44 +0100 | [diff] [blame] | 7032 | maplist([{abbr}]) *maplist()* |
| 7033 | Returns a |List| of all mappings. Each List item is a |Dict|, |
| 7034 | the same as what is returned by |maparg()|, see |
| 7035 | |mapping-dict|. When {abbr} is there and it is |TRUE| use |
| 7036 | abbreviations instead of mappings. |
| 7037 | |
| 7038 | Example to show all mappings with 'MultiMatch' in rhs: > |
| 7039 | vim9script |
| 7040 | echo maplist()->filter( |
| 7041 | (_, m) => match(m.rhs, 'MultiMatch') >= 0) |
Ernie Rael | d8f5f76 | 2022-05-10 17:50:39 +0100 | [diff] [blame] | 7042 | < It can be tricky to find mappings for particular |:map-modes|. |
| 7043 | |mapping-dict|'s "mode_bits" can simplify this. For example, |
| 7044 | the mode_bits for Normal, Insert or Command-line modes are |
| 7045 | 0x19. To find all the mappings available in those modes you |
| 7046 | can do: > |
| 7047 | vim9script |
| 7048 | var saved_maps = [] |
| 7049 | for m in maplist() |
| 7050 | if and(m.mode_bits, 0x19) != 0 |
| 7051 | saved_maps->add(m) |
| 7052 | endif |
| 7053 | endfor |
| 7054 | echo saved_maps->mapnew((_, m) => m.lhs) |
| 7055 | < The values of the mode_bits are defined in Vim's src/vim.h |
| 7056 | file and they can be discovered at runtime using |
| 7057 | |:map-commands| and "maplist()". Example: > |
| 7058 | vim9script |
| 7059 | omap xyzzy <Nop> |
| 7060 | var op_bit = maplist()->filter( |
| 7061 | (_, m) => m.lhs == 'xyzzy')[0].mode_bits |
| 7062 | ounmap xyzzy |
| 7063 | echo printf("Operator-pending mode bit: 0x%x", op_bit) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7064 | < |
| 7065 | Return type: list<dict<any>> |
Ernie Rael | 0966120 | 2022-04-25 14:40:44 +0100 | [diff] [blame] | 7066 | |
| 7067 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7068 | mapnew({expr1}, {expr2}) *mapnew()* |
| 7069 | Like |map()| but instead of replacing items in {expr1} a new |
| 7070 | List or Dictionary is created and returned. {expr1} remains |
| 7071 | unchanged. Items can still be changed by {expr2}, if you |
| 7072 | don't want that use |deepcopy()| first. |
| 7073 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7074 | Return type: |String|, |Blob|, list<{type}> or dict<{type}> |
| 7075 | depending on {expr1} |
| 7076 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7077 | |
| 7078 | mapset({mode}, {abbr}, {dict}) *mapset()* |
Ernie Rael | 51d04d1 | 2022-05-04 15:40:22 +0100 | [diff] [blame] | 7079 | mapset({dict}) |
| 7080 | Restore a mapping from a dictionary, possibly returned by |
| 7081 | |maparg()| or |maplist()|. A buffer mapping, when dict.buffer |
| 7082 | is true, is set on the current buffer; it is up to the caller |
Bram Moolenaar | 2d8ed02 | 2022-05-21 13:08:16 +0100 | [diff] [blame] | 7083 | to ensure that the intended buffer is the current buffer. This |
Ernie Rael | 51d04d1 | 2022-05-04 15:40:22 +0100 | [diff] [blame] | 7084 | feature allows copying mappings from one buffer to another. |
| 7085 | The dict.mode value may restore a single mapping that covers |
| 7086 | more than one mode, like with mode values of '!', ' ', 'nox', |
| 7087 | or 'v'. *E1276* |
| 7088 | |
| 7089 | In the first form, {mode} and {abbr} should be the same as |
| 7090 | for the call to |maparg()|. *E460* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7091 | {mode} is used to define the mode in which the mapping is set, |
| 7092 | not the "mode" entry in {dict}. |
| 7093 | Example for saving and restoring a mapping: > |
| 7094 | let save_map = maparg('K', 'n', 0, 1) |
| 7095 | nnoremap K somethingelse |
| 7096 | ... |
| 7097 | call mapset('n', 0, save_map) |
| 7098 | < Note that if you are going to replace a map in several modes, |
Ernie Rael | 51d04d1 | 2022-05-04 15:40:22 +0100 | [diff] [blame] | 7099 | e.g. with `:map!`, you need to save/restore the mapping for |
| 7100 | all of them, when they might differ. |
| 7101 | |
| 7102 | In the second form, with {dict} as the only argument, mode |
| 7103 | and abbr are taken from the dict. |
| 7104 | Example: > |
| 7105 | vim9script |
| 7106 | var save_maps = maplist()->filter( |
| 7107 | (_, m) => m.lhs == 'K') |
| 7108 | nnoremap K somethingelse |
| 7109 | cnoremap K somethingelse2 |
| 7110 | # ... |
| 7111 | unmap K |
| 7112 | for d in save_maps |
| 7113 | mapset(d) |
| 7114 | endfor |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7115 | < |
| 7116 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7117 | |
| 7118 | |
| 7119 | match({expr}, {pat} [, {start} [, {count}]]) *match()* |
| 7120 | When {expr} is a |List| then this returns the index of the |
| 7121 | first item where {pat} matches. Each item is used as a |
| 7122 | String, |Lists| and |Dictionaries| are used as echoed. |
| 7123 | |
| 7124 | Otherwise, {expr} is used as a String. The result is a |
| 7125 | Number, which gives the index (byte offset) in {expr} where |
| 7126 | {pat} matches. |
| 7127 | |
| 7128 | A match at the first character or |List| item returns zero. |
| 7129 | If there is no match -1 is returned. |
| 7130 | |
| 7131 | For getting submatches see |matchlist()|. |
| 7132 | Example: > |
| 7133 | :echo match("testing", "ing") " results in 4 |
| 7134 | :echo match([1, 'x'], '\a') " results in 1 |
| 7135 | < See |string-match| for how {pat} is used. |
| 7136 | *strpbrk()* |
| 7137 | Vim doesn't have a strpbrk() function. But you can do: > |
| 7138 | :let sepidx = match(line, '[.,;: \t]') |
| 7139 | < *strcasestr()* |
| 7140 | Vim doesn't have a strcasestr() function. But you can add |
| 7141 | "\c" to the pattern to ignore case: > |
| 7142 | :let idx = match(haystack, '\cneedle') |
| 7143 | < |
| 7144 | If {start} is given, the search starts from byte index |
| 7145 | {start} in a String or item {start} in a |List|. |
| 7146 | The result, however, is still the index counted from the |
| 7147 | first character/item. Example: > |
| 7148 | :echo match("testing", "ing", 2) |
| 7149 | < result is again "4". > |
| 7150 | :echo match("testing", "ing", 4) |
| 7151 | < result is again "4". > |
| 7152 | :echo match("testing", "t", 2) |
| 7153 | < result is "3". |
| 7154 | For a String, if {start} > 0 then it is like the string starts |
| 7155 | {start} bytes later, thus "^" will match at {start}. Except |
| 7156 | when {count} is given, then it's like matches before the |
| 7157 | {start} byte are ignored (this is a bit complicated to keep it |
| 7158 | backwards compatible). |
| 7159 | For a String, if {start} < 0, it will be set to 0. For a list |
| 7160 | the index is counted from the end. |
| 7161 | If {start} is out of range ({start} > strlen({expr}) for a |
| 7162 | String or {start} > len({expr}) for a |List|) -1 is returned. |
| 7163 | |
| 7164 | When {count} is given use the {count}'th match. When a match |
| 7165 | is found in a String the search for the next one starts one |
| 7166 | character further. Thus this example results in 1: > |
| 7167 | echo match("testing", "..", 0, 2) |
| 7168 | < In a |List| the search continues in the next item. |
| 7169 | Note that when {count} is added the way {start} works changes, |
| 7170 | see above. |
| 7171 | |
Yegappan Lakshmanan | a35235e | 2024-02-24 10:09:43 +0100 | [diff] [blame] | 7172 | *match-pattern* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7173 | See |pattern| for the patterns that are accepted. |
| 7174 | The 'ignorecase' option is used to set the ignore-caseness of |
| 7175 | the pattern. 'smartcase' is NOT used. The matching is always |
| 7176 | done like 'magic' is set and 'cpoptions' is empty. |
| 7177 | Note that a match at the start is preferred, thus when the |
| 7178 | pattern is using "*" (any number of matches) it tends to find |
| 7179 | zero matches at the start instead of a number of matches |
| 7180 | further down in the text. |
| 7181 | |
| 7182 | Can also be used as a |method|: > |
| 7183 | GetText()->match('word') |
| 7184 | GetList()->match('word') |
| 7185 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7186 | Return type: |Number| |
| 7187 | |
| 7188 | |
Bram Moolenaar | 2f0936c | 2022-01-08 21:51:59 +0000 | [diff] [blame] | 7189 | *matchadd()* *E290* *E798* *E799* *E801* *E957* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7190 | matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]]) |
| 7191 | Defines a pattern to be highlighted in the current window (a |
| 7192 | "match"). It will be highlighted with {group}. Returns an |
| 7193 | identification number (ID), which can be used to delete the |
| 7194 | match using |matchdelete()|. The ID is bound to the window. |
| 7195 | Matching is case sensitive and magic, unless case sensitivity |
| 7196 | or magicness are explicitly overridden in {pattern}. The |
| 7197 | 'magic', 'smartcase' and 'ignorecase' options are not used. |
| 7198 | The "Conceal" value is special, it causes the match to be |
| 7199 | concealed. |
| 7200 | |
| 7201 | The optional {priority} argument assigns a priority to the |
| 7202 | match. A match with a high priority will have its |
| 7203 | highlighting overrule that of a match with a lower priority. |
| 7204 | A priority is specified as an integer (negative numbers are no |
| 7205 | exception). If the {priority} argument is not specified, the |
| 7206 | default priority is 10. The priority of 'hlsearch' is zero, |
| 7207 | hence all matches with a priority greater than zero will |
| 7208 | overrule it. Syntax highlighting (see 'syntax') is a separate |
| 7209 | mechanism, and regardless of the chosen priority a match will |
| 7210 | always overrule syntax highlighting. |
| 7211 | |
| 7212 | The optional {id} argument allows the request for a specific |
| 7213 | match ID. If a specified ID is already taken, an error |
| 7214 | message will appear and the match will not be added. An ID |
| 7215 | is specified as a positive integer (zero excluded). IDs 1, 2 |
| 7216 | and 3 are reserved for |:match|, |:2match| and |:3match|, |
Bram Moolenaar | 2ecbe53 | 2022-07-29 21:36:21 +0100 | [diff] [blame] | 7217 | respectively. 3 is reserved for use by the |matchparen| |
| 7218 | plugin. |
Bram Moolenaar | b529cfb | 2022-07-25 15:42:07 +0100 | [diff] [blame] | 7219 | If the {id} argument is not specified or -1, |matchadd()| |
Bram Moolenaar | 9f573a8 | 2022-09-29 13:50:08 +0100 | [diff] [blame] | 7220 | automatically chooses a free ID, which is at least 1000. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7221 | |
| 7222 | The optional {dict} argument allows for further custom |
| 7223 | values. Currently this is used to specify a match specific |
| 7224 | conceal character that will be shown for |hl-Conceal| |
| 7225 | highlighted matches. The dict can have the following members: |
| 7226 | |
| 7227 | conceal Special character to show instead of the |
| 7228 | match (only for |hl-Conceal| highlighted |
| 7229 | matches, see |:syn-cchar|) |
| 7230 | window Instead of the current window use the |
| 7231 | window with this number or window ID. |
| 7232 | |
| 7233 | The number of matches is not limited, as it is the case with |
| 7234 | the |:match| commands. |
| 7235 | |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 7236 | Returns -1 on error. |
| 7237 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7238 | Example: > |
| 7239 | :highlight MyGroup ctermbg=green guibg=green |
| 7240 | :let m = matchadd("MyGroup", "TODO") |
| 7241 | < Deletion of the pattern: > |
| 7242 | :call matchdelete(m) |
| 7243 | |
| 7244 | < A list of matches defined by |matchadd()| and |:match| are |
| 7245 | available from |getmatches()|. All matches can be deleted in |
| 7246 | one operation by |clearmatches()|. |
| 7247 | |
| 7248 | Can also be used as a |method|: > |
| 7249 | GetGroup()->matchadd('TODO') |
| 7250 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7251 | Return type: |Number| |
| 7252 | |
| 7253 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7254 | *matchaddpos()* |
| 7255 | matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) |
| 7256 | Same as |matchadd()|, but requires a list of positions {pos} |
| 7257 | instead of a pattern. This command is faster than |matchadd()| |
Shane Harper | c1b3984 | 2024-07-17 19:40:40 +0200 | [diff] [blame] | 7258 | because it does not handle regular expressions and it sets |
| 7259 | buffer line boundaries to redraw screen. It is supposed to be |
| 7260 | used when fast match additions and deletions are required, for |
| 7261 | example to highlight matching parentheses. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7262 | |
| 7263 | {pos} is a list of positions. Each position can be one of |
| 7264 | these: |
| 7265 | - A number. This whole line will be highlighted. The first |
| 7266 | line has number 1. |
| 7267 | - A list with one number, e.g., [23]. The whole line with this |
| 7268 | number will be highlighted. |
| 7269 | - A list with two numbers, e.g., [23, 11]. The first number is |
| 7270 | the line number, the second one is the column number (first |
| 7271 | column is 1, the value must correspond to the byte index as |
| 7272 | |col()| would return). The character at this position will |
| 7273 | be highlighted. |
| 7274 | - A list with three numbers, e.g., [23, 11, 3]. As above, but |
| 7275 | the third number gives the length of the highlight in bytes. |
| 7276 | |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 7277 | Returns -1 on error. |
| 7278 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7279 | Example: > |
| 7280 | :highlight MyGroup ctermbg=green guibg=green |
| 7281 | :let m = matchaddpos("MyGroup", [[23, 24], 34]) |
| 7282 | < Deletion of the pattern: > |
| 7283 | :call matchdelete(m) |
| 7284 | |
| 7285 | < Matches added by |matchaddpos()| are returned by |
| 7286 | |getmatches()|. |
| 7287 | |
| 7288 | Can also be used as a |method|: > |
| 7289 | GetGroup()->matchaddpos([23, 11]) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7290 | < |
| 7291 | Return type: |Number| |
| 7292 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7293 | |
| 7294 | matcharg({nr}) *matcharg()* |
| 7295 | Selects the {nr} match item, as set with a |:match|, |
| 7296 | |:2match| or |:3match| command. |
| 7297 | Return a |List| with two elements: |
| 7298 | The name of the highlight group used |
| 7299 | The pattern used. |
| 7300 | When {nr} is not 1, 2 or 3 returns an empty |List|. |
| 7301 | When there is no match item set returns ['', '']. |
| 7302 | This is useful to save and restore a |:match|. |
| 7303 | Highlighting matches using the |:match| commands are limited |
| 7304 | to three matches. |matchadd()| does not have this limitation. |
| 7305 | |
| 7306 | Can also be used as a |method|: > |
| 7307 | GetMatch()->matcharg() |
Yegappan Lakshmanan | f93b1c8 | 2024-01-04 22:28:46 +0100 | [diff] [blame] | 7308 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7309 | Return type: list<string> |
| 7310 | |
Yegappan Lakshmanan | f93b1c8 | 2024-01-04 22:28:46 +0100 | [diff] [blame] | 7311 | *matchbufline()* |
| 7312 | matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}]) |
| 7313 | Returns the |List| of matches in lines from {lnum} to {end} in |
| 7314 | buffer {buf} where {pat} matches. |
| 7315 | |
| 7316 | {lnum} and {end} can either be a line number or the string "$" |
| 7317 | to refer to the last line in {buf}. |
| 7318 | |
| 7319 | The {dict} argument supports following items: |
| 7320 | submatches include submatch information (|/\(|) |
| 7321 | |
| 7322 | For each match, a |Dict| with the following items is returned: |
| 7323 | byteidx starting byte index of the match |
Yegappan Lakshmanan | eb3475d | 2024-01-15 11:08:25 -0800 | [diff] [blame] | 7324 | lnum line number where there is a match |
| 7325 | text matched string |
Yegappan Lakshmanan | f93b1c8 | 2024-01-04 22:28:46 +0100 | [diff] [blame] | 7326 | Note that there can be multiple matches in a single line. |
| 7327 | |
| 7328 | This function works only for loaded buffers. First call |
| 7329 | |bufload()| if needed. |
| 7330 | |
Yegappan Lakshmanan | a35235e | 2024-02-24 10:09:43 +0100 | [diff] [blame] | 7331 | See |match-pattern| for information about the effect of some |
| 7332 | option settings on the pattern. |
| 7333 | |
Yegappan Lakshmanan | f93b1c8 | 2024-01-04 22:28:46 +0100 | [diff] [blame] | 7334 | When {buf} is not a valid buffer, the buffer is not loaded or |
| 7335 | {lnum} or {end} is not valid then an error is given and an |
| 7336 | empty |List| is returned. |
| 7337 | |
| 7338 | Examples: > |
Yegappan Lakshmanan | eb3475d | 2024-01-15 11:08:25 -0800 | [diff] [blame] | 7339 | " Assuming line 3 in buffer 5 contains "a" |
| 7340 | :echo matchbufline(5, '\<\k\+\>', 3, 3) |
| 7341 | [{'lnum': 3, 'byteidx': 0, 'text': 'a'}] |
| 7342 | " Assuming line 4 in buffer 10 contains "tik tok" |
| 7343 | :echo matchbufline(10, '\<\k\+\>', 1, 4) |
| 7344 | [{'lnum': 4, 'byteidx': 0, 'text': 'tik'}, {'lnum': 4, 'byteidx': 4, 'text': 'tok'}] |
Yegappan Lakshmanan | f93b1c8 | 2024-01-04 22:28:46 +0100 | [diff] [blame] | 7345 | < |
| 7346 | If {submatch} is present and is v:true, then submatches like |
Yegappan Lakshmanan | eb3475d | 2024-01-15 11:08:25 -0800 | [diff] [blame] | 7347 | "\1", "\2", etc. are also returned. Example: > |
| 7348 | " Assuming line 2 in buffer 2 contains "acd" |
| 7349 | :echo matchbufline(2, '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 2, 2 |
Yegappan Lakshmanan | f93b1c8 | 2024-01-04 22:28:46 +0100 | [diff] [blame] | 7350 | \ {'submatches': v:true}) |
Yegappan Lakshmanan | eb3475d | 2024-01-15 11:08:25 -0800 | [diff] [blame] | 7351 | [{'lnum': 2, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}] |
Yegappan Lakshmanan | f93b1c8 | 2024-01-04 22:28:46 +0100 | [diff] [blame] | 7352 | < The "submatches" List always contains 9 items. If a submatch |
| 7353 | is not found, then an empty string is returned for that |
| 7354 | submatch. |
| 7355 | |
| 7356 | Can also be used as a |method|: > |
| 7357 | GetBuffer()->matchbufline('mypat', 1, '$') |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7358 | < |
| 7359 | Return type: list<dict<any>> or list<any> |
| 7360 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7361 | |
h-east | 624bb83 | 2024-11-09 18:37:32 +0100 | [diff] [blame] | 7362 | matchdelete({id} [, {win}) *matchdelete()* *E802* *E803* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7363 | Deletes a match with ID {id} previously defined by |matchadd()| |
| 7364 | or one of the |:match| commands. Returns 0 if successful, |
| 7365 | otherwise -1. See example for |matchadd()|. All matches can |
| 7366 | be deleted in one operation by |clearmatches()|. |
| 7367 | If {win} is specified, use the window with this number or |
| 7368 | window ID instead of the current window. |
| 7369 | |
| 7370 | Can also be used as a |method|: > |
| 7371 | GetMatch()->matchdelete() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7372 | < |
| 7373 | Return type: |Number| |
| 7374 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7375 | |
| 7376 | matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()* |
| 7377 | Same as |match()|, but return the index of first character |
| 7378 | after the match. Example: > |
| 7379 | :echo matchend("testing", "ing") |
| 7380 | < results in "7". |
| 7381 | *strspn()* *strcspn()* |
| 7382 | Vim doesn't have a strspn() or strcspn() function, but you can |
| 7383 | do it with matchend(): > |
| 7384 | :let span = matchend(line, '[a-zA-Z]') |
| 7385 | :let span = matchend(line, '[^a-zA-Z]') |
| 7386 | < Except that -1 is returned when there are no matches. |
| 7387 | |
| 7388 | The {start}, if given, has the same meaning as for |match()|. > |
| 7389 | :echo matchend("testing", "ing", 2) |
| 7390 | < results in "7". > |
| 7391 | :echo matchend("testing", "ing", 5) |
| 7392 | < result is "-1". |
| 7393 | When {expr} is a |List| the result is equal to |match()|. |
| 7394 | |
| 7395 | Can also be used as a |method|: > |
| 7396 | GetText()->matchend('word') |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7397 | < |
| 7398 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7399 | |
| 7400 | |
| 7401 | matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()* |
| 7402 | If {list} is a list of strings, then returns a |List| with all |
| 7403 | the strings in {list} that fuzzy match {str}. The strings in |
| 7404 | the returned list are sorted based on the matching score. |
| 7405 | |
| 7406 | The optional {dict} argument always supports the following |
| 7407 | items: |
zeertzjq | 9af2bc0 | 2022-05-11 14:15:37 +0100 | [diff] [blame] | 7408 | matchseq When this item is present return only matches |
| 7409 | that contain the characters in {str} in the |
| 7410 | given sequence. |
Kazuyuki Miyagi | 47f1a55 | 2022-06-17 18:30:03 +0100 | [diff] [blame] | 7411 | limit Maximum number of matches in {list} to be |
| 7412 | returned. Zero means no limit. |
glepnir | 28e40a7 | 2025-03-16 21:24:22 +0100 | [diff] [blame] | 7413 | camelcase Use enhanced camel case scoring making results |
| 7414 | better suited for completion related to |
zeertzjq | c4815c1 | 2025-03-18 20:28:00 +0100 | [diff] [blame] | 7415 | programming languages. Defaults to v:true. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7416 | |
| 7417 | If {list} is a list of dictionaries, then the optional {dict} |
| 7418 | argument supports the following additional items: |
Yasuhiro Matsumoto | 9029a6e | 2022-04-16 12:35:35 +0100 | [diff] [blame] | 7419 | key Key of the item which is fuzzy matched against |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7420 | {str}. The value of this item should be a |
| 7421 | string. |
| 7422 | text_cb |Funcref| that will be called for every item |
| 7423 | in {list} to get the text for fuzzy matching. |
| 7424 | This should accept a dictionary item as the |
| 7425 | argument and return the text for that item to |
| 7426 | use for fuzzy matching. |
| 7427 | |
| 7428 | {str} is treated as a literal string and regular expression |
| 7429 | matching is NOT supported. The maximum supported {str} length |
| 7430 | is 256. |
| 7431 | |
| 7432 | When {str} has multiple words each separated by white space, |
| 7433 | then the list of strings that have all the words is returned. |
| 7434 | |
| 7435 | If there are no matching strings or there is an error, then an |
| 7436 | empty list is returned. If length of {str} is greater than |
| 7437 | 256, then returns an empty list. |
| 7438 | |
Yasuhiro Matsumoto | 9029a6e | 2022-04-16 12:35:35 +0100 | [diff] [blame] | 7439 | When {limit} is given, matchfuzzy() will find up to this |
| 7440 | number of matches in {list} and return them in sorted order. |
| 7441 | |
Bram Moolenaar | 1588bc8 | 2022-03-08 21:35:07 +0000 | [diff] [blame] | 7442 | Refer to |fuzzy-matching| for more information about fuzzy |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7443 | matching strings. |
| 7444 | |
| 7445 | Example: > |
| 7446 | :echo matchfuzzy(["clay", "crow"], "cay") |
| 7447 | < results in ["clay"]. > |
| 7448 | :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl") |
| 7449 | < results in a list of buffer names fuzzy matching "ndl". > |
| 7450 | :echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'}) |
| 7451 | < results in a list of buffer information dicts with buffer |
| 7452 | names fuzzy matching "ndl". > |
| 7453 | :echo getbufinfo()->matchfuzzy("spl", |
| 7454 | \ {'text_cb' : {v -> v.name}}) |
| 7455 | < results in a list of buffer information dicts with buffer |
| 7456 | names fuzzy matching "spl". > |
| 7457 | :echo v:oldfiles->matchfuzzy("test") |
| 7458 | < results in a list of file names fuzzy matching "test". > |
| 7459 | :let l = readfile("buffer.c")->matchfuzzy("str") |
| 7460 | < results in a list of lines in "buffer.c" fuzzy matching "str". > |
| 7461 | :echo ['one two', 'two one']->matchfuzzy('two one') |
| 7462 | < results in ['two one', 'one two']. > |
| 7463 | :echo ['one two', 'two one']->matchfuzzy('two one', |
| 7464 | \ {'matchseq': 1}) |
| 7465 | < results in ['two one']. |
| 7466 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7467 | Return type: list<string> or list<any> |
| 7468 | |
| 7469 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7470 | matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()* |
| 7471 | Same as |matchfuzzy()|, but returns the list of matched |
| 7472 | strings, the list of character positions where characters |
| 7473 | in {str} matches and a list of matching scores. You can |
| 7474 | use |byteidx()| to convert a character position to a byte |
| 7475 | position. |
| 7476 | |
| 7477 | If {str} matches multiple times in a string, then only the |
| 7478 | positions for the best match is returned. |
| 7479 | |
| 7480 | If there are no matching strings or there is an error, then a |
| 7481 | list with three empty list items is returned. |
| 7482 | |
| 7483 | Example: > |
| 7484 | :echo matchfuzzypos(['testing'], 'tsg') |
| 7485 | < results in [['testing'], [[0, 2, 6]], [99]] > |
| 7486 | :echo matchfuzzypos(['clay', 'lacy'], 'la') |
| 7487 | < results in [['lacy', 'clay'], [[0, 1], [1, 2]], [153, 133]] > |
| 7488 | :echo [{'text': 'hello', 'id' : 10}]->matchfuzzypos('ll', {'key' : 'text'}) |
| 7489 | < results in [[{'id': 10, 'text': 'hello'}], [[2, 3]], [127]] |
| 7490 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7491 | Return type: list<list<any>> |
| 7492 | |
| 7493 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7494 | matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()* |
| 7495 | Same as |match()|, but return a |List|. The first item in the |
| 7496 | list is the matched string, same as what matchstr() would |
| 7497 | return. Following items are submatches, like "\1", "\2", etc. |
| 7498 | in |:substitute|. When an optional submatch didn't match an |
| 7499 | empty string is used. Example: > |
| 7500 | echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)') |
| 7501 | < Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', ''] |
| 7502 | When there is no match an empty list is returned. |
| 7503 | |
| 7504 | You can pass in a List, but that is not very useful. |
| 7505 | |
| 7506 | Can also be used as a |method|: > |
| 7507 | GetText()->matchlist('word') |
Yegappan Lakshmanan | f93b1c8 | 2024-01-04 22:28:46 +0100 | [diff] [blame] | 7508 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7509 | Return type: list<string> or list<any> |
| 7510 | |
Yegappan Lakshmanan | f93b1c8 | 2024-01-04 22:28:46 +0100 | [diff] [blame] | 7511 | *matchstrlist()* |
| 7512 | matchstrlist({list}, {pat} [, {dict}]) |
| 7513 | Returns the |List| of matches in {list} where {pat} matches. |
| 7514 | {list} is a |List| of strings. {pat} is matched against each |
| 7515 | string in {list}. |
| 7516 | |
| 7517 | The {dict} argument supports following items: |
| 7518 | submatches include submatch information (|/\(|) |
| 7519 | |
| 7520 | For each match, a |Dict| with the following items is returned: |
| 7521 | byteidx starting byte index of the match. |
| 7522 | idx index in {list} of the match. |
| 7523 | text matched string |
| 7524 | submatches a List of submatches. Present only if |
| 7525 | "submatches" is set to v:true in {dict}. |
| 7526 | |
Yegappan Lakshmanan | a35235e | 2024-02-24 10:09:43 +0100 | [diff] [blame] | 7527 | See |match-pattern| for information about the effect of some |
| 7528 | option settings on the pattern. |
| 7529 | |
Yegappan Lakshmanan | f93b1c8 | 2024-01-04 22:28:46 +0100 | [diff] [blame] | 7530 | Example: > |
Yegappan Lakshmanan | eb3475d | 2024-01-15 11:08:25 -0800 | [diff] [blame] | 7531 | :echo matchstrlist(['tik tok'], '\<\k\+\>') |
| 7532 | [{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}] |
| 7533 | :echo matchstrlist(['a', 'b'], '\<\k\+\>') |
| 7534 | [{'idx': 0, 'byteidx': 0, 'text': 'a'}, {'idx': 1, 'byteidx': 0, 'text': 'b'}] |
Yegappan Lakshmanan | f93b1c8 | 2024-01-04 22:28:46 +0100 | [diff] [blame] | 7535 | < |
| 7536 | If "submatches" is present and is v:true, then submatches like |
| 7537 | "\1", "\2", etc. are also returned. Example: > |
| 7538 | :echo matchstrlist(['acd'], '\(a\)\?\(b\)\?\(c\)\?\(.*\)', |
| 7539 | \ #{submatches: v:true}) |
| 7540 | [{'idx': 0, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}] |
| 7541 | < The "submatches" List always contains 9 items. If a submatch |
| 7542 | is not found, then an empty string is returned for that |
| 7543 | submatch. |
| 7544 | |
| 7545 | Can also be used as a |method|: > |
| 7546 | GetListOfStrings()->matchstrlist('mypat') |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7547 | < |
| 7548 | Return type: list<dict<any>> or list<any> |
| 7549 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7550 | |
| 7551 | matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()* |
| 7552 | Same as |match()|, but return the matched string. Example: > |
| 7553 | :echo matchstr("testing", "ing") |
| 7554 | < results in "ing". |
| 7555 | When there is no match "" is returned. |
| 7556 | The {start}, if given, has the same meaning as for |match()|. > |
| 7557 | :echo matchstr("testing", "ing", 2) |
| 7558 | < results in "ing". > |
| 7559 | :echo matchstr("testing", "ing", 5) |
| 7560 | < result is "". |
| 7561 | When {expr} is a |List| then the matching item is returned. |
| 7562 | The type isn't changed, it's not necessarily a String. |
| 7563 | |
| 7564 | Can also be used as a |method|: > |
| 7565 | GetText()->matchstr('word') |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7566 | < |
| 7567 | Return type: |String| |
| 7568 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7569 | |
| 7570 | matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()* |
| 7571 | Same as |matchstr()|, but return the matched string, the start |
| 7572 | position and the end position of the match. Example: > |
| 7573 | :echo matchstrpos("testing", "ing") |
| 7574 | < results in ["ing", 4, 7]. |
| 7575 | When there is no match ["", -1, -1] is returned. |
| 7576 | The {start}, if given, has the same meaning as for |match()|. > |
| 7577 | :echo matchstrpos("testing", "ing", 2) |
| 7578 | < results in ["ing", 4, 7]. > |
| 7579 | :echo matchstrpos("testing", "ing", 5) |
| 7580 | < result is ["", -1, -1]. |
| 7581 | When {expr} is a |List| then the matching item, the index |
| 7582 | of first item where {pat} matches, the start position and the |
| 7583 | end position of the match are returned. > |
| 7584 | :echo matchstrpos([1, '__x'], '\a') |
| 7585 | < result is ["x", 1, 2, 3]. |
| 7586 | The type isn't changed, it's not necessarily a String. |
| 7587 | |
| 7588 | Can also be used as a |method|: > |
| 7589 | GetText()->matchstrpos('word') |
| 7590 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7591 | Return type: list<any> |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7592 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7593 | |
| 7594 | max({expr}) *max()* |
| 7595 | Return the maximum value of all items in {expr}. Example: > |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7596 | echo max([apples, pears, oranges]) |
| 7597 | |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 7598 | < {expr} can be a |List|, a |Tuple| or a |Dictionary|. For a |
| 7599 | Dictionary, it returns the maximum of all values in the |
| 7600 | Dictionary. If {expr} is neither a List nor a Tuple nor a |
| 7601 | Dictionary, or one of the items in {expr} cannot be used as a |
| 7602 | Number this results in an error. An empty |List|, |Tuple| |
| 7603 | or |Dictionary| results in zero. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7604 | |
| 7605 | Can also be used as a |method|: > |
| 7606 | mylist->max() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7607 | < |
| 7608 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7609 | |
| 7610 | |
| 7611 | menu_info({name} [, {mode}]) *menu_info()* |
| 7612 | Return information about the specified menu {name} in |
| 7613 | mode {mode}. The menu name should be specified without the |
| 7614 | shortcut character ('&'). If {name} is "", then the top-level |
| 7615 | menu names are returned. |
| 7616 | |
| 7617 | {mode} can be one of these strings: |
| 7618 | "n" Normal |
| 7619 | "v" Visual (including Select) |
| 7620 | "o" Operator-pending |
| 7621 | "i" Insert |
| 7622 | "c" Cmd-line |
| 7623 | "s" Select |
| 7624 | "x" Visual |
| 7625 | "t" Terminal-Job |
| 7626 | "" Normal, Visual and Operator-pending |
| 7627 | "!" Insert and Cmd-line |
| 7628 | When {mode} is omitted, the modes for "" are used. |
| 7629 | |
| 7630 | Returns a |Dictionary| containing the following items: |
| 7631 | accel menu item accelerator text |menu-text| |
| 7632 | display display name (name without '&') |
| 7633 | enabled v:true if this menu item is enabled |
| 7634 | Refer to |:menu-enable| |
| 7635 | icon name of the icon file (for toolbar) |
| 7636 | |toolbar-icon| |
| 7637 | iconidx index of a built-in icon |
| 7638 | modes modes for which the menu is defined. In |
| 7639 | addition to the modes mentioned above, these |
| 7640 | characters will be used: |
| 7641 | " " Normal, Visual and Operator-pending |
| 7642 | name menu item name. |
| 7643 | noremenu v:true if the {rhs} of the menu item is not |
| 7644 | remappable else v:false. |
| 7645 | priority menu order priority |menu-priority| |
| 7646 | rhs right-hand-side of the menu item. The returned |
| 7647 | string has special characters translated like |
| 7648 | in the output of the ":menu" command listing. |
| 7649 | When the {rhs} of a menu item is empty, then |
| 7650 | "<Nop>" is returned. |
| 7651 | script v:true if script-local remapping of {rhs} is |
| 7652 | allowed else v:false. See |:menu-script|. |
| 7653 | shortcut shortcut key (character after '&' in |
| 7654 | the menu name) |menu-shortcut| |
| 7655 | silent v:true if the menu item is created |
| 7656 | with <silent> argument |:menu-silent| |
| 7657 | submenus |List| containing the names of |
| 7658 | all the submenus. Present only if the menu |
| 7659 | item has submenus. |
| 7660 | |
| 7661 | Returns an empty dictionary if the menu item is not found. |
| 7662 | |
| 7663 | Examples: > |
| 7664 | :echo menu_info('Edit.Cut') |
| 7665 | :echo menu_info('File.Save', 'n') |
| 7666 | |
| 7667 | " Display the entire menu hierarchy in a buffer |
| 7668 | func ShowMenu(name, pfx) |
| 7669 | let m = menu_info(a:name) |
| 7670 | call append(line('$'), a:pfx .. m.display) |
| 7671 | for child in m->get('submenus', []) |
| 7672 | call ShowMenu(a:name .. '.' .. escape(child, '.'), |
| 7673 | \ a:pfx .. ' ') |
| 7674 | endfor |
| 7675 | endfunc |
| 7676 | new |
| 7677 | for topmenu in menu_info('').submenus |
| 7678 | call ShowMenu(topmenu, '') |
| 7679 | endfor |
| 7680 | < |
| 7681 | Can also be used as a |method|: > |
| 7682 | GetMenuName()->menu_info('v') |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7683 | < |
| 7684 | Return type: dict<any> |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7685 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7686 | min({expr}) *min()* |
| 7687 | Return the minimum value of all items in {expr}. Example: > |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7688 | echo min([apples, pears, oranges]) |
| 7689 | |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 7690 | < {expr} can be a |List|, a |Tuple| or a |Dictionary|. For a |
| 7691 | Dictionary, it returns the minimum of all values in the |
| 7692 | Dictionary. If {expr} is neither a List nor a Tuple nor a |
| 7693 | Dictionary, or one of the items in {expr} cannot be used as a |
| 7694 | Number this results in an error. An empty |List|, |Tuple| or |
| 7695 | |Dictionary| results in zero. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7696 | |
| 7697 | Can also be used as a |method|: > |
| 7698 | mylist->min() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7699 | < |
| 7700 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7701 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7702 | |
| 7703 | mkdir({name} [, {flags} [, {prot}]]) *mkdir()* *E739* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7704 | Create directory {name}. |
| 7705 | |
Bram Moolenaar | 938ae28 | 2023-02-20 20:44:55 +0000 | [diff] [blame] | 7706 | When {flags} is present it must be a string. An empty string |
| 7707 | has no effect. |
Bram Moolenaar | 6f14da1 | 2022-09-07 21:30:44 +0100 | [diff] [blame] | 7708 | |
Christian Brabandt | d6d4e13 | 2024-06-13 21:21:41 +0200 | [diff] [blame] | 7709 | {flags} can contain these character flags: |
| 7710 | "p" intermediate directories will be created as necessary |
| 7711 | "D" {name} will be deleted at the end of the current |
Christian Brabandt | c509c00 | 2024-06-14 20:22:05 +0200 | [diff] [blame] | 7712 | function, but not recursively |:defer| |
Christian Brabandt | d6d4e13 | 2024-06-13 21:21:41 +0200 | [diff] [blame] | 7713 | "R" {name} will be deleted recursively at the end of the |
Christian Brabandt | c509c00 | 2024-06-14 20:22:05 +0200 | [diff] [blame] | 7714 | current function |:defer| |
Bram Moolenaar | 938ae28 | 2023-02-20 20:44:55 +0000 | [diff] [blame] | 7715 | |
Christian Brabandt | d6d4e13 | 2024-06-13 21:21:41 +0200 | [diff] [blame] | 7716 | Note that when {name} has more than one part and "p" is used |
Bram Moolenaar | 6f14da1 | 2022-09-07 21:30:44 +0100 | [diff] [blame] | 7717 | some directories may already exist. Only the first one that |
| 7718 | is created and what it contains is scheduled to be deleted. |
| 7719 | E.g. when using: > |
| 7720 | call mkdir('subdir/tmp/autoload', 'pR') |
| 7721 | < and "subdir" already exists then "subdir/tmp" will be |
| 7722 | scheduled for deletion, like with: > |
| 7723 | defer delete('subdir/tmp', 'rf') |
| 7724 | < Note that if scheduling the defer fails the directory is not |
| 7725 | deleted. This should only happen when out of memory. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7726 | |
| 7727 | If {prot} is given it is used to set the protection bits of |
| 7728 | the new directory. The default is 0o755 (rwxr-xr-x: r/w for |
| 7729 | the user, readable for others). Use 0o700 to make it |
Christian Brabandt | 0a336cc | 2025-03-11 21:14:31 +0100 | [diff] [blame] | 7730 | unreadable for others. This is used for the newly created |
zeertzjq | c1c3b5d | 2025-03-12 21:16:13 +0100 | [diff] [blame] | 7731 | directories. Note: umask is applied to {prot} (on Unix). |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7732 | Example: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 7733 | :call mkdir($HOME .. "/tmp/foo/bar", "p", 0o700) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7734 | |
| 7735 | < This function is not available in the |sandbox|. |
| 7736 | |
| 7737 | There is no error if the directory already exists and the "p" |
| 7738 | flag is passed (since patch 8.0.1708). However, without the |
| 7739 | "p" option the call will fail. |
| 7740 | |
| 7741 | The function result is a Number, which is TRUE if the call was |
| 7742 | successful or FALSE if the directory creation failed or partly |
| 7743 | failed. |
| 7744 | |
| 7745 | Not available on all systems. To check use: > |
| 7746 | :if exists("*mkdir") |
| 7747 | |
| 7748 | < Can also be used as a |method|: > |
| 7749 | GetName()->mkdir() |
| 7750 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7751 | Return type: |Number| |
| 7752 | |
| 7753 | |
| 7754 | mode([{expr}]) *mode()* |
| 7755 | Return a string that indicates the current mode. |
Doug Kearns | 9cd9e75 | 2024-04-07 17:42:17 +0200 | [diff] [blame] | 7756 | If {expr} is supplied and it evaluates to a non-zero Number or |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7757 | a non-empty String (|non-zero-arg|), then the full mode is |
| 7758 | returned, otherwise only the first letter is returned. |
| 7759 | Also see |state()|. |
| 7760 | |
| 7761 | n Normal |
| 7762 | no Operator-pending |
| 7763 | nov Operator-pending (forced characterwise |o_v|) |
| 7764 | noV Operator-pending (forced linewise |o_V|) |
| 7765 | noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|); |
| 7766 | CTRL-V is one character |
| 7767 | niI Normal using |i_CTRL-O| in |Insert-mode| |
| 7768 | niR Normal using |i_CTRL-O| in |Replace-mode| |
| 7769 | niV Normal using |i_CTRL-O| in |Virtual-Replace-mode| |
| 7770 | nt Terminal-Normal (insert goes to Terminal-Job mode) |
| 7771 | v Visual by character |
| 7772 | vs Visual by character using |v_CTRL-O| in Select mode |
| 7773 | V Visual by line |
| 7774 | Vs Visual by line using |v_CTRL-O| in Select mode |
| 7775 | CTRL-V Visual blockwise |
| 7776 | CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode |
| 7777 | s Select by character |
| 7778 | S Select by line |
| 7779 | CTRL-S Select blockwise |
| 7780 | i Insert |
| 7781 | ic Insert mode completion |compl-generic| |
| 7782 | ix Insert mode |i_CTRL-X| completion |
| 7783 | R Replace |R| |
| 7784 | Rc Replace mode completion |compl-generic| |
| 7785 | Rx Replace mode |i_CTRL-X| completion |
| 7786 | Rv Virtual Replace |gR| |
| 7787 | Rvc Virtual Replace mode completion |compl-generic| |
| 7788 | Rvx Virtual Replace mode |i_CTRL-X| completion |
| 7789 | c Command-line editing |
h-east | 71ebf3b | 2023-09-03 17:12:55 +0200 | [diff] [blame] | 7790 | ct Command-line editing via Terminal-Job mode |
zeertzjq | fcaeb3d | 2023-11-28 20:46:29 +0100 | [diff] [blame] | 7791 | cr Command-line editing overstrike mode |c_<Insert>| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7792 | cv Vim Ex mode |gQ| |
zeertzjq | fcaeb3d | 2023-11-28 20:46:29 +0100 | [diff] [blame] | 7793 | cvr Vim Ex mode while in overstrike mode |c_<Insert>| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7794 | ce Normal Ex mode |Q| |
| 7795 | r Hit-enter prompt |
| 7796 | rm The -- more -- prompt |
| 7797 | r? A |:confirm| query of some sort |
| 7798 | ! Shell or external command is executing |
| 7799 | t Terminal-Job mode: keys go to the job |
| 7800 | |
| 7801 | This is useful in the 'statusline' option or when used |
| 7802 | with |remote_expr()| In most other places it always returns |
| 7803 | "c" or "n". |
| 7804 | Note that in the future more modes and more specific modes may |
| 7805 | be added. It's better not to compare the whole string but only |
| 7806 | the leading character(s). |
| 7807 | Also see |visualmode()|. |
| 7808 | |
| 7809 | Can also be used as a |method|: > |
| 7810 | DoFull()->mode() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7811 | < |
| 7812 | Return type: |String| |
| 7813 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7814 | |
| 7815 | mzeval({expr}) *mzeval()* |
| 7816 | Evaluate MzScheme expression {expr} and return its result |
| 7817 | converted to Vim data structures. |
| 7818 | Numbers and strings are returned as they are. |
| 7819 | Pairs (including lists and improper lists) and vectors are |
| 7820 | returned as Vim |Lists|. |
| 7821 | Hash tables are represented as Vim |Dictionary| type with keys |
| 7822 | converted to strings. |
| 7823 | All other types are converted to string with display function. |
| 7824 | Examples: > |
| 7825 | :mz (define l (list 1 2 3)) |
| 7826 | :mz (define h (make-hash)) (hash-set! h "list" l) |
| 7827 | :echo mzeval("l") |
| 7828 | :echo mzeval("h") |
| 7829 | < |
| 7830 | Note that in a `:def` function local variables are not visible |
| 7831 | to {expr}. |
| 7832 | |
| 7833 | Can also be used as a |method|: > |
| 7834 | GetExpr()->mzeval() |
| 7835 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7836 | Return type: any, depending on {expr} |
| 7837 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7838 | {only available when compiled with the |+mzscheme| feature} |
| 7839 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7840 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7841 | nextnonblank({lnum}) *nextnonblank()* |
| 7842 | Return the line number of the first line at or below {lnum} |
| 7843 | that is not blank. Example: > |
| 7844 | if getline(nextnonblank(1)) =~ "Java" |
| 7845 | < When {lnum} is invalid or there is no non-blank line at or |
| 7846 | below it, zero is returned. |
| 7847 | {lnum} is used like with |getline()|. |
| 7848 | See also |prevnonblank()|. |
| 7849 | |
| 7850 | Can also be used as a |method|: > |
| 7851 | GetLnum()->nextnonblank() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7852 | < |
| 7853 | Return type: |Number| |
| 7854 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7855 | |
Christ van Willegen | c078675 | 2025-02-01 15:42:16 +0100 | [diff] [blame] | 7856 | ngettext({single}, {plural}, {number}[, {domain}) *ngettext()* |
| 7857 | Return a string that contains the correct value for a |
| 7858 | message based on the rules for plural form(s) in |
| 7859 | a language. Examples: > |
| 7860 | ngettext("File", "Files", 2) # returns "Files" |
| 7861 | < |
| 7862 | Can be used as a |method|: > |
| 7863 | 1->ngettext("File", "Files") # returns "File" |
| 7864 | < |
| 7865 | See |gettext()| for information on the domain parameter. |
| 7866 | |
| 7867 | Return type: |String| |
| 7868 | |
| 7869 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7870 | nr2char({expr} [, {utf8}]) *nr2char()* |
| 7871 | Return a string with a single character, which has the number |
| 7872 | value {expr}. Examples: > |
| 7873 | nr2char(64) returns "@" |
| 7874 | nr2char(32) returns " " |
| 7875 | < When {utf8} is omitted or zero, the current 'encoding' is used. |
| 7876 | Example for "utf-8": > |
| 7877 | nr2char(300) returns I with bow character |
| 7878 | < When {utf8} is TRUE, always return UTF-8 characters. |
| 7879 | Note that a NUL character in the file is specified with |
| 7880 | nr2char(10), because NULs are represented with newline |
| 7881 | characters. nr2char(0) is a real NUL and terminates the |
| 7882 | string, thus results in an empty string. |
| 7883 | To turn a list of character numbers into a string: > |
| 7884 | let list = [65, 66, 67] |
| 7885 | let str = join(map(list, {_, val -> nr2char(val)}), '') |
| 7886 | < Result: "ABC" |
| 7887 | |
| 7888 | Can also be used as a |method|: > |
| 7889 | GetNumber()->nr2char() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7890 | < |
| 7891 | Return type: |String| |
| 7892 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7893 | |
| 7894 | or({expr}, {expr}) *or()* |
| 7895 | Bitwise OR on the two arguments. The arguments are converted |
| 7896 | to a number. A List, Dict or Float argument causes an error. |
Bram Moolenaar | 5a6ec10 | 2022-05-27 21:58:00 +0100 | [diff] [blame] | 7897 | Also see `and()` and `xor()`. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7898 | Example: > |
| 7899 | :let bits = or(bits, 0x80) |
| 7900 | < Can also be used as a |method|: > |
| 7901 | :let bits = bits->or(0x80) |
| 7902 | |
Bram Moolenaar | 5a6ec10 | 2022-05-27 21:58:00 +0100 | [diff] [blame] | 7903 | < Rationale: The reason this is a function and not using the "|" |
| 7904 | character like many languages, is that Vi has always used "|" |
| 7905 | to separate commands. In many places it would not be clear if |
| 7906 | "|" is an operator or a command separator. |
| 7907 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7908 | Return type: |Number| |
| 7909 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7910 | |
| 7911 | pathshorten({path} [, {len}]) *pathshorten()* |
| 7912 | Shorten directory names in the path {path} and return the |
| 7913 | result. The tail, the file name, is kept as-is. The other |
| 7914 | components in the path are reduced to {len} letters in length. |
| 7915 | If {len} is omitted or smaller than 1 then 1 is used (single |
| 7916 | letters). Leading '~' and '.' characters are kept. Examples: > |
| 7917 | :echo pathshorten('~/.vim/autoload/myfile.vim') |
| 7918 | < ~/.v/a/myfile.vim ~ |
| 7919 | > |
| 7920 | :echo pathshorten('~/.vim/autoload/myfile.vim', 2) |
| 7921 | < ~/.vi/au/myfile.vim ~ |
| 7922 | It doesn't matter if the path exists or not. |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 7923 | Returns an empty string on error. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7924 | |
| 7925 | Can also be used as a |method|: > |
| 7926 | GetDirectories()->pathshorten() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7927 | < |
| 7928 | Return type: |String| |
| 7929 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7930 | |
| 7931 | perleval({expr}) *perleval()* |
| 7932 | Evaluate Perl expression {expr} in scalar context and return |
| 7933 | its result converted to Vim data structures. If value can't be |
| 7934 | converted, it is returned as a string Perl representation. |
| 7935 | Note: If you want an array or hash, {expr} must return a |
| 7936 | reference to it. |
| 7937 | Example: > |
| 7938 | :echo perleval('[1 .. 4]') |
| 7939 | < [1, 2, 3, 4] |
| 7940 | |
| 7941 | Note that in a `:def` function local variables are not visible |
| 7942 | to {expr}. |
| 7943 | |
| 7944 | Can also be used as a |method|: > |
| 7945 | GetExpr()->perleval() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7946 | < |
| 7947 | Return type: any, depending on {expr} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7948 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7949 | {only available when compiled with the |+perl| feature} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7950 | |
| 7951 | |
| 7952 | popup_ functions are documented here: |popup-functions| |
| 7953 | |
| 7954 | |
| 7955 | pow({x}, {y}) *pow()* |
| 7956 | Return the power of {x} to the exponent {y} as a |Float|. |
| 7957 | {x} and {y} must evaluate to a |Float| or a |Number|. |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 7958 | Returns 0.0 if {x} or {y} is not a |Float| or a |Number|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7959 | Examples: > |
| 7960 | :echo pow(3, 3) |
| 7961 | < 27.0 > |
| 7962 | :echo pow(2, 16) |
| 7963 | < 65536.0 > |
| 7964 | :echo pow(32, 0.20) |
| 7965 | < 2.0 |
| 7966 | |
| 7967 | Can also be used as a |method|: > |
| 7968 | Compute()->pow(3) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7969 | < |
| 7970 | Return type: |Number| |
| 7971 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7972 | |
| 7973 | prevnonblank({lnum}) *prevnonblank()* |
| 7974 | Return the line number of the first line at or above {lnum} |
| 7975 | that is not blank. Example: > |
| 7976 | let ind = indent(prevnonblank(v:lnum - 1)) |
| 7977 | < When {lnum} is invalid or there is no non-blank line at or |
| 7978 | above it, zero is returned. |
| 7979 | {lnum} is used like with |getline()|. |
| 7980 | Also see |nextnonblank()|. |
| 7981 | |
| 7982 | Can also be used as a |method|: > |
| 7983 | GetLnum()->prevnonblank() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 7984 | < |
| 7985 | Return type: |Number| |
| 7986 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 7987 | |
| 7988 | printf({fmt}, {expr1} ...) *printf()* |
| 7989 | Return a String with {fmt}, where "%" items are replaced by |
| 7990 | the formatted form of their respective arguments. Example: > |
| 7991 | printf("%4d: E%d %.30s", lnum, errno, msg) |
| 7992 | < May result in: |
| 7993 | " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~ |
| 7994 | |
| 7995 | When used as a |method| the base is passed as the second |
| 7996 | argument: > |
| 7997 | Compute()->printf("result: %d") |
Bram Moolenaar | cbaff5e | 2022-04-08 17:45:08 +0100 | [diff] [blame] | 7998 | < |
| 7999 | You can use `call()` to pass the items as a list. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8000 | |
Bram Moolenaar | cbaff5e | 2022-04-08 17:45:08 +0100 | [diff] [blame] | 8001 | Often used items are: |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8002 | %s string |
| 8003 | %6S string right-aligned in 6 display cells |
| 8004 | %6s string right-aligned in 6 bytes |
| 8005 | %.9s string truncated to 9 bytes |
| 8006 | %c single byte |
| 8007 | %d decimal number |
| 8008 | %5d decimal number padded with spaces to 5 characters |
| 8009 | %x hex number |
| 8010 | %04x hex number padded with zeros to at least 4 characters |
| 8011 | %X hex number using upper case letters |
| 8012 | %o octal number |
| 8013 | %08b binary number padded with zeros to at least 8 chars |
| 8014 | %f floating point number as 12.23, inf, -inf or nan |
| 8015 | %F floating point number as 12.23, INF, -INF or NAN |
| 8016 | %e floating point number as 1.23e3, inf, -inf or nan |
| 8017 | %E floating point number as 1.23E3, INF, -INF or NAN |
| 8018 | %g floating point number, as %f or %e depending on value |
| 8019 | %G floating point number, as %F or %E depending on value |
| 8020 | %% the % character itself |
| 8021 | |
| 8022 | Conversion specifications start with '%' and end with the |
| 8023 | conversion type. All other characters are copied unchanged to |
| 8024 | the result. |
| 8025 | |
| 8026 | The "%" starts a conversion specification. The following |
| 8027 | arguments appear in sequence: |
| 8028 | |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8029 | % [pos-argument] [flags] [field-width] [.precision] type |
| 8030 | |
| 8031 | pos-argument |
| 8032 | At most one positional argument specifier. These |
| 8033 | take the form {n$}, where n is >= 1. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8034 | |
| 8035 | flags |
| 8036 | Zero or more of the following flags: |
| 8037 | |
| 8038 | # The value should be converted to an "alternate |
| 8039 | form". For c, d, and s conversions, this option |
| 8040 | has no effect. For o conversions, the precision |
| 8041 | of the number is increased to force the first |
| 8042 | character of the output string to a zero (except |
| 8043 | if a zero value is printed with an explicit |
| 8044 | precision of zero). |
| 8045 | For b and B conversions, a non-zero result has |
| 8046 | the string "0b" (or "0B" for B conversions) |
| 8047 | prepended to it. |
| 8048 | For x and X conversions, a non-zero result has |
| 8049 | the string "0x" (or "0X" for X conversions) |
| 8050 | prepended to it. |
| 8051 | |
| 8052 | 0 (zero) Zero padding. For all conversions the converted |
| 8053 | value is padded on the left with zeros rather |
| 8054 | than blanks. If a precision is given with a |
| 8055 | numeric conversion (d, b, B, o, x, and X), the 0 |
| 8056 | flag is ignored. |
| 8057 | |
| 8058 | - A negative field width flag; the converted value |
| 8059 | is to be left adjusted on the field boundary. |
| 8060 | The converted value is padded on the right with |
| 8061 | blanks, rather than on the left with blanks or |
| 8062 | zeros. A - overrides a 0 if both are given. |
| 8063 | |
| 8064 | ' ' (space) A blank should be left before a positive |
| 8065 | number produced by a signed conversion (d). |
| 8066 | |
| 8067 | + A sign must always be placed before a number |
| 8068 | produced by a signed conversion. A + overrides |
| 8069 | a space if both are used. |
| 8070 | |
| 8071 | field-width |
| 8072 | An optional decimal digit string specifying a minimum |
| 8073 | field width. If the converted value has fewer bytes |
| 8074 | than the field width, it will be padded with spaces on |
| 8075 | the left (or right, if the left-adjustment flag has |
| 8076 | been given) to fill out the field width. For the S |
| 8077 | conversion the count is in cells. |
| 8078 | |
| 8079 | .precision |
| 8080 | An optional precision, in the form of a period '.' |
| 8081 | followed by an optional digit string. If the digit |
| 8082 | string is omitted, the precision is taken as zero. |
| 8083 | This gives the minimum number of digits to appear for |
| 8084 | d, o, x, and X conversions, the maximum number of |
| 8085 | bytes to be printed from a string for s conversions, |
| 8086 | or the maximum number of cells to be printed from a |
| 8087 | string for S conversions. |
| 8088 | For floating point it is the number of digits after |
| 8089 | the decimal point. |
| 8090 | |
| 8091 | type |
| 8092 | A character that specifies the type of conversion to |
| 8093 | be applied, see below. |
| 8094 | |
| 8095 | A field width or precision, or both, may be indicated by an |
| 8096 | asterisk '*' instead of a digit string. In this case, a |
| 8097 | Number argument supplies the field width or precision. A |
| 8098 | negative field width is treated as a left adjustment flag |
| 8099 | followed by a positive field width; a negative precision is |
| 8100 | treated as though it were missing. Example: > |
| 8101 | :echo printf("%d: %.*s", nr, width, line) |
| 8102 | < This limits the length of the text used from "line" to |
| 8103 | "width" bytes. |
| 8104 | |
Dominique Pellé | 17dca3c | 2023-12-14 20:36:32 +0100 | [diff] [blame] | 8105 | If the argument to be formatted is specified using a |
| 8106 | positional argument specifier, and a '*' is used to indicate |
| 8107 | that a number argument is to be used to specify the width or |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8108 | precision, the argument(s) to be used must also be specified |
| 8109 | using a {n$} positional argument specifier. See |printf-$|. |
| 8110 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8111 | The conversion specifiers and their meanings are: |
| 8112 | |
| 8113 | *printf-d* *printf-b* *printf-B* *printf-o* |
| 8114 | *printf-x* *printf-X* |
| 8115 | dbBoxX The Number argument is converted to signed decimal |
| 8116 | (d), unsigned binary (b and B), unsigned octal (o), or |
| 8117 | unsigned hexadecimal (x and X) notation. The letters |
| 8118 | "abcdef" are used for x conversions; the letters |
| 8119 | "ABCDEF" are used for X conversions. |
| 8120 | The precision, if any, gives the minimum number of |
| 8121 | digits that must appear; if the converted value |
| 8122 | requires fewer digits, it is padded on the left with |
| 8123 | zeros. |
| 8124 | In no case does a non-existent or small field width |
| 8125 | cause truncation of a numeric field; if the result of |
| 8126 | a conversion is wider than the field width, the field |
| 8127 | is expanded to contain the conversion result. |
| 8128 | The 'h' modifier indicates the argument is 16 bits. |
Christ van Willegen | aa90d4f | 2023-09-03 17:22:37 +0200 | [diff] [blame] | 8129 | The 'l' modifier indicates the argument is a long |
| 8130 | integer. The size will be 32 bits or 64 bits |
| 8131 | depending on your platform. |
| 8132 | The "ll" modifier indicates the argument is 64 bits. |
| 8133 | The b and B conversion specifiers never take a width |
| 8134 | modifier and always assume their argument is a 64 bit |
| 8135 | integer. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8136 | Generally, these modifiers are not useful. They are |
| 8137 | ignored when type is known from the argument. |
| 8138 | |
| 8139 | i alias for d |
| 8140 | D alias for ld |
| 8141 | U alias for lu |
| 8142 | O alias for lo |
| 8143 | |
| 8144 | *printf-c* |
| 8145 | c The Number argument is converted to a byte, and the |
| 8146 | resulting character is written. |
| 8147 | |
| 8148 | *printf-s* |
| 8149 | s The text of the String argument is used. If a |
| 8150 | precision is specified, no more bytes than the number |
| 8151 | specified are used. |
| 8152 | If the argument is not a String type, it is |
| 8153 | automatically converted to text with the same format |
| 8154 | as ":echo". |
| 8155 | *printf-S* |
| 8156 | S The text of the String argument is used. If a |
| 8157 | precision is specified, no more display cells than the |
| 8158 | number specified are used. |
| 8159 | |
| 8160 | *printf-f* *E807* |
| 8161 | f F The Float argument is converted into a string of the |
| 8162 | form 123.456. The precision specifies the number of |
| 8163 | digits after the decimal point. When the precision is |
| 8164 | zero the decimal point is omitted. When the precision |
| 8165 | is not specified 6 is used. A really big number |
| 8166 | (out of range or dividing by zero) results in "inf" |
| 8167 | or "-inf" with %f (INF or -INF with %F). |
| 8168 | "0.0 / 0.0" results in "nan" with %f (NAN with %F). |
| 8169 | Example: > |
| 8170 | echo printf("%.2f", 12.115) |
| 8171 | < 12.12 |
| 8172 | Note that roundoff depends on the system libraries. |
| 8173 | Use |round()| when in doubt. |
| 8174 | |
| 8175 | *printf-e* *printf-E* |
| 8176 | e E The Float argument is converted into a string of the |
| 8177 | form 1.234e+03 or 1.234E+03 when using 'E'. The |
| 8178 | precision specifies the number of digits after the |
| 8179 | decimal point, like with 'f'. |
| 8180 | |
| 8181 | *printf-g* *printf-G* |
| 8182 | g G The Float argument is converted like with 'f' if the |
| 8183 | value is between 0.001 (inclusive) and 10000000.0 |
| 8184 | (exclusive). Otherwise 'e' is used for 'g' and 'E' |
| 8185 | for 'G'. When no precision is specified superfluous |
| 8186 | zeroes and '+' signs are removed, except for the zero |
| 8187 | immediately after the decimal point. Thus 10000000.0 |
| 8188 | results in 1.0e7. |
| 8189 | |
| 8190 | *printf-%* |
| 8191 | % A '%' is written. No argument is converted. The |
| 8192 | complete conversion specification is "%%". |
| 8193 | |
| 8194 | When a Number argument is expected a String argument is also |
| 8195 | accepted and automatically converted. |
| 8196 | When a Float or String argument is expected a Number argument |
| 8197 | is also accepted and automatically converted. |
| 8198 | Any other argument type results in an error message. |
| 8199 | |
| 8200 | *E766* *E767* |
| 8201 | The number of {exprN} arguments must exactly match the number |
| 8202 | of "%" items. If there are not sufficient or too many |
| 8203 | arguments an error is given. Up to 18 arguments can be used. |
| 8204 | |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8205 | *printf-$* |
| 8206 | In certain languages, error and informative messages are |
| 8207 | more readable when the order of words is different from the |
Christian Brabandt | ee17b6f | 2023-09-09 11:23:50 +0200 | [diff] [blame] | 8208 | corresponding message in English. To accommodate translations |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8209 | having a different word order, positional arguments may be |
| 8210 | used to indicate this. For instance: > |
| 8211 | |
h_east | 596a9f2 | 2023-11-21 21:24:23 +0900 | [diff] [blame] | 8212 | #, c-format |
| 8213 | msgid "%s returning %s" |
| 8214 | msgstr "waarde %2$s komt terug van %1$s" |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8215 | < |
h_east | 596a9f2 | 2023-11-21 21:24:23 +0900 | [diff] [blame] | 8216 | In this example, the sentence has its 2 string arguments |
| 8217 | reversed in the output. > |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8218 | |
h_east | 596a9f2 | 2023-11-21 21:24:23 +0900 | [diff] [blame] | 8219 | echo printf( |
| 8220 | "In The Netherlands, vim's creator's name is: %1$s %2$s", |
| 8221 | "Bram", "Moolenaar") |
| 8222 | < In The Netherlands, vim's creator's name is: Bram Moolenaar > |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8223 | |
h_east | 596a9f2 | 2023-11-21 21:24:23 +0900 | [diff] [blame] | 8224 | echo printf( |
| 8225 | "In Belgium, vim's creator's name is: %2$s %1$s", |
| 8226 | "Bram", "Moolenaar") |
| 8227 | < In Belgium, vim's creator's name is: Moolenaar Bram |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8228 | |
| 8229 | Width (and precision) can be specified using the '*' specifier. |
| 8230 | In this case, you must specify the field width position in the |
| 8231 | argument list. > |
| 8232 | |
h_east | 596a9f2 | 2023-11-21 21:24:23 +0900 | [diff] [blame] | 8233 | echo printf("%1$*2$.*3$d", 1, 2, 3) |
| 8234 | < 001 > |
| 8235 | echo printf("%2$*3$.*1$d", 1, 2, 3) |
| 8236 | < 2 > |
| 8237 | echo printf("%3$*1$.*2$d", 1, 2, 3) |
| 8238 | < 03 > |
| 8239 | echo printf("%1$*2$.*3$g", 1.4142, 2, 3) |
| 8240 | < 1.414 |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8241 | |
| 8242 | You can mix specifying the width and/or precision directly |
| 8243 | and via positional arguments: > |
| 8244 | |
h_east | 596a9f2 | 2023-11-21 21:24:23 +0900 | [diff] [blame] | 8245 | echo printf("%1$4.*2$f", 1.4142135, 6) |
| 8246 | < 1.414214 > |
| 8247 | echo printf("%1$*2$.4f", 1.4142135, 6) |
| 8248 | < 1.4142 > |
| 8249 | echo printf("%1$*2$.*3$f", 1.4142135, 6, 2) |
| 8250 | < 1.41 |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8251 | |
Christ van Willegen | c35fc03 | 2024-03-14 18:30:41 +0100 | [diff] [blame] | 8252 | You will get an overflow error |E1510|, when the field-width |
Hirohito Higashi | 0ed11ba | 2025-04-18 18:45:31 +0200 | [diff] [blame] | 8253 | or precision will result in a string longer than 1 MiB |
zeertzjq | e9a27ef | 2025-04-18 10:45:45 +0200 | [diff] [blame] | 8254 | (1024*1024 = 1048576) chars. |
Christ van Willegen | c35fc03 | 2024-03-14 18:30:41 +0100 | [diff] [blame] | 8255 | |
Yegappan Lakshmanan | 413f839 | 2023-09-28 22:46:37 +0200 | [diff] [blame] | 8256 | *E1500* |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8257 | You cannot mix positional and non-positional arguments: > |
h_east | 596a9f2 | 2023-11-21 21:24:23 +0900 | [diff] [blame] | 8258 | echo printf("%s%1$s", "One", "Two") |
| 8259 | < E1500: Cannot mix positional and non-positional arguments: |
| 8260 | %s%1$s |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8261 | |
Yegappan Lakshmanan | 413f839 | 2023-09-28 22:46:37 +0200 | [diff] [blame] | 8262 | *E1501* |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8263 | You cannot skip a positional argument in a format string: > |
h_east | 596a9f2 | 2023-11-21 21:24:23 +0900 | [diff] [blame] | 8264 | echo printf("%3$s%1$s", "One", "Two", "Three") |
| 8265 | < E1501: format argument 2 unused in $-style format: |
| 8266 | %3$s%1$s |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8267 | |
Yegappan Lakshmanan | 413f839 | 2023-09-28 22:46:37 +0200 | [diff] [blame] | 8268 | *E1502* |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8269 | You can re-use a [field-width] (or [precision]) argument: > |
h_east | 596a9f2 | 2023-11-21 21:24:23 +0900 | [diff] [blame] | 8270 | echo printf("%1$d at width %2$d is: %01$*2$d", 1, 2) |
| 8271 | < 1 at width 2 is: 01 |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8272 | |
| 8273 | However, you can't use it as a different type: > |
h_east | 596a9f2 | 2023-11-21 21:24:23 +0900 | [diff] [blame] | 8274 | echo printf("%1$d at width %2$ld is: %01$*2$d", 1, 2) |
| 8275 | < E1502: Positional argument 2 used as field width reused as |
| 8276 | different type: long int/int |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8277 | |
Yegappan Lakshmanan | 413f839 | 2023-09-28 22:46:37 +0200 | [diff] [blame] | 8278 | *E1503* |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8279 | When a positional argument is used, but not the correct number |
| 8280 | or arguments is given, an error is raised: > |
h_east | 596a9f2 | 2023-11-21 21:24:23 +0900 | [diff] [blame] | 8281 | echo printf("%1$d at width %2$d is: %01$*2$.*3$d", 1, 2) |
| 8282 | < E1503: Positional argument 3 out of bounds: %1$d at width |
| 8283 | %2$d is: %01$*2$.*3$d |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8284 | |
| 8285 | Only the first error is reported: > |
h_east | 596a9f2 | 2023-11-21 21:24:23 +0900 | [diff] [blame] | 8286 | echo printf("%01$*2$.*3$d %4$d", 1, 2) |
| 8287 | < E1503: Positional argument 3 out of bounds: %01$*2$.*3$d |
| 8288 | %4$d |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8289 | |
Yegappan Lakshmanan | 413f839 | 2023-09-28 22:46:37 +0200 | [diff] [blame] | 8290 | *E1504* |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8291 | A positional argument can be used more than once: > |
h_east | 596a9f2 | 2023-11-21 21:24:23 +0900 | [diff] [blame] | 8292 | echo printf("%1$s %2$s %1$s", "One", "Two") |
| 8293 | < One Two One |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8294 | |
| 8295 | However, you can't use a different type the second time: > |
h_east | 596a9f2 | 2023-11-21 21:24:23 +0900 | [diff] [blame] | 8296 | echo printf("%1$s %2$s %1$d", "One", "Two") |
| 8297 | < E1504: Positional argument 1 type used inconsistently: |
| 8298 | int/string |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8299 | |
Yegappan Lakshmanan | 413f839 | 2023-09-28 22:46:37 +0200 | [diff] [blame] | 8300 | *E1505* |
Christ van Willegen | 0c6181f | 2023-08-13 18:03:14 +0200 | [diff] [blame] | 8301 | Various other errors that lead to a format string being |
| 8302 | wrongly formatted lead to: > |
h_east | 596a9f2 | 2023-11-21 21:24:23 +0900 | [diff] [blame] | 8303 | echo printf("%1$d at width %2$d is: %01$*2$.3$d", 1, 2) |
| 8304 | < E1505: Invalid format specifier: %1$d at width %2$d is: |
| 8305 | %01$*2$.3$d |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8306 | |
Christ van Willegen | ea746f9 | 2023-10-05 20:48:36 +0200 | [diff] [blame] | 8307 | *E1507* |
zeertzjq | 27e12c7 | 2023-10-07 01:34:04 +0800 | [diff] [blame] | 8308 | This internal error indicates that the logic to parse a |
| 8309 | positional format argument ran into a problem that couldn't be |
| 8310 | otherwise reported. Please file a bug against Vim if you run |
| 8311 | into this, copying the exact format string and parameters that |
| 8312 | were used. |
Christ van Willegen | ea746f9 | 2023-10-05 20:48:36 +0200 | [diff] [blame] | 8313 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8314 | Return type: |String| |
| 8315 | |
Christ van Willegen | ea746f9 | 2023-10-05 20:48:36 +0200 | [diff] [blame] | 8316 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8317 | prompt_getprompt({buf}) *prompt_getprompt()* |
| 8318 | Returns the effective prompt text for buffer {buf}. {buf} can |
| 8319 | be a buffer name or number. See |prompt-buffer|. |
| 8320 | |
| 8321 | If the buffer doesn't exist or isn't a prompt buffer, an empty |
| 8322 | string is returned. |
| 8323 | |
| 8324 | Can also be used as a |method|: > |
| 8325 | GetBuffer()->prompt_getprompt() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8326 | < |
| 8327 | Return type: |String| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8328 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8329 | {only available when compiled with the |+channel| feature} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8330 | |
| 8331 | |
| 8332 | prompt_setcallback({buf}, {expr}) *prompt_setcallback()* |
| 8333 | Set prompt callback for buffer {buf} to {expr}. When {expr} |
| 8334 | is an empty string the callback is removed. This has only |
| 8335 | effect if {buf} has 'buftype' set to "prompt". |
| 8336 | |
| 8337 | The callback is invoked when pressing Enter. The current |
| 8338 | buffer will always be the prompt buffer. A new line for a |
| 8339 | prompt is added before invoking the callback, thus the prompt |
| 8340 | for which the callback was invoked will be in the last but one |
| 8341 | line. |
| 8342 | If the callback wants to add text to the buffer, it must |
| 8343 | insert it above the last line, since that is where the current |
| 8344 | prompt is. This can also be done asynchronously. |
| 8345 | The callback is invoked with one argument, which is the text |
| 8346 | that was entered at the prompt. This can be an empty string |
| 8347 | if the user only typed Enter. |
| 8348 | Example: > |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8349 | func s:TextEntered(text) |
| 8350 | if a:text == 'exit' || a:text == 'quit' |
| 8351 | stopinsert |
Bram Moolenaar | b7398fe | 2023-05-14 18:50:25 +0100 | [diff] [blame] | 8352 | " Reset 'modified' to allow the buffer to be closed. |
| 8353 | " We assume there is nothing useful to be saved. |
| 8354 | set nomodified |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8355 | close |
| 8356 | else |
Bram Moolenaar | b7398fe | 2023-05-14 18:50:25 +0100 | [diff] [blame] | 8357 | " Do something useful with "a:text". In this example |
| 8358 | " we just repeat it. |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 8359 | call append(line('$') - 1, 'Entered: "' .. a:text .. '"') |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8360 | endif |
| 8361 | endfunc |
Bram Moolenaar | b7398fe | 2023-05-14 18:50:25 +0100 | [diff] [blame] | 8362 | call prompt_setcallback(bufnr(), function('s:TextEntered')) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8363 | |
| 8364 | < Can also be used as a |method|: > |
| 8365 | GetBuffer()->prompt_setcallback(callback) |
| 8366 | |
| 8367 | < {only available when compiled with the |+channel| feature} |
| 8368 | |
| 8369 | prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()* |
| 8370 | Set a callback for buffer {buf} to {expr}. When {expr} is an |
| 8371 | empty string the callback is removed. This has only effect if |
| 8372 | {buf} has 'buftype' set to "prompt". |
| 8373 | |
| 8374 | This callback will be invoked when pressing CTRL-C in Insert |
| 8375 | mode. Without setting a callback Vim will exit Insert mode, |
| 8376 | as in any buffer. |
| 8377 | |
| 8378 | Can also be used as a |method|: > |
| 8379 | GetBuffer()->prompt_setinterrupt(callback) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8380 | < |
| 8381 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8382 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8383 | {only available when compiled with the |+channel| feature} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8384 | |
| 8385 | prompt_setprompt({buf}, {text}) *prompt_setprompt()* |
| 8386 | Set prompt for buffer {buf} to {text}. You most likely want |
| 8387 | {text} to end in a space. |
| 8388 | The result is only visible if {buf} has 'buftype' set to |
| 8389 | "prompt". Example: > |
| 8390 | call prompt_setprompt(bufnr(), 'command: ') |
| 8391 | < |
| 8392 | Can also be used as a |method|: > |
| 8393 | GetBuffer()->prompt_setprompt('command: ') |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8394 | < |
| 8395 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8396 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8397 | {only available when compiled with the |+channel| feature} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8398 | |
| 8399 | prop_ functions are documented here: |text-prop-functions| |
| 8400 | |
| 8401 | pum_getpos() *pum_getpos()* |
| 8402 | If the popup menu (see |ins-completion-menu|) is not visible, |
| 8403 | returns an empty |Dictionary|, otherwise, returns a |
| 8404 | |Dictionary| with the following keys: |
| 8405 | height nr of items visible |
| 8406 | width screen cells |
| 8407 | row top screen row (0 first row) |
| 8408 | col leftmost screen column (0 first col) |
| 8409 | size total nr of items |
| 8410 | scrollbar |TRUE| if scrollbar is visible |
| 8411 | |
| 8412 | The values are the same as in |v:event| during |
| 8413 | |CompleteChanged|. |
| 8414 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8415 | Return type: dict<any> |
| 8416 | |
| 8417 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8418 | pumvisible() *pumvisible()* |
| 8419 | Returns non-zero when the popup menu is visible, zero |
| 8420 | otherwise. See |ins-completion-menu|. |
| 8421 | This can be used to avoid some things that would remove the |
| 8422 | popup menu. |
| 8423 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8424 | Return type: |Number| |
| 8425 | |
| 8426 | |
zeertzjq | 7c51528 | 2024-11-10 20:26:12 +0100 | [diff] [blame] | 8427 | py3eval({expr} [, {locals}]) *py3eval()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8428 | Evaluate Python expression {expr} and return its result |
| 8429 | converted to Vim data structures. |
Ben Jackson | ea19e78 | 2024-11-06 21:50:05 +0100 | [diff] [blame] | 8430 | If a {locals} |Dictionary| is given, it defines set of local |
| 8431 | variables available in the expression. The keys are variable |
Yegappan Lakshmanan | 038be27 | 2025-03-26 18:46:21 +0100 | [diff] [blame] | 8432 | names and the values are the variable values. |Dictionary|, |
| 8433 | |List| and |Tuple| values are referenced, and may be updated |
| 8434 | by the expression (as if |python-bindeval| was used). |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8435 | Numbers and strings are returned as they are (strings are |
| 8436 | copied though, Unicode strings are additionally converted to |
| 8437 | 'encoding'). |
| 8438 | Lists are represented as Vim |List| type. |
Yegappan Lakshmanan | 038be27 | 2025-03-26 18:46:21 +0100 | [diff] [blame] | 8439 | Tuples are represented as Vim |Tuple| type. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8440 | Dictionaries are represented as Vim |Dictionary| type with |
| 8441 | keys converted to strings. |
| 8442 | Note that in a `:def` function local variables are not visible |
| 8443 | to {expr}. |
| 8444 | |
| 8445 | Can also be used as a |method|: > |
| 8446 | GetExpr()->py3eval() |
Ben Jackson | ea19e78 | 2024-11-06 21:50:05 +0100 | [diff] [blame] | 8447 | 'b",".join(l)'->py3eval({'l': ['a', 'b', 'c']}) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8448 | < |
| 8449 | Return type: any, depending on {expr} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8450 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8451 | {only available when compiled with the |+python3| feature} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8452 | |
| 8453 | *E858* *E859* |
zeertzjq | 7c51528 | 2024-11-10 20:26:12 +0100 | [diff] [blame] | 8454 | pyeval({expr} [, {locals}]) *pyeval()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8455 | Evaluate Python expression {expr} and return its result |
| 8456 | converted to Vim data structures. |
Ben Jackson | ea19e78 | 2024-11-06 21:50:05 +0100 | [diff] [blame] | 8457 | For {locals} see |py3eval()|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8458 | Numbers and strings are returned as they are (strings are |
| 8459 | copied though). |
| 8460 | Lists are represented as Vim |List| type. |
Yegappan Lakshmanan | 038be27 | 2025-03-26 18:46:21 +0100 | [diff] [blame] | 8461 | Tuples are represented as Vim |Tuple| type. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8462 | Dictionaries are represented as Vim |Dictionary| type, |
| 8463 | non-string keys result in error. |
| 8464 | Note that in a `:def` function local variables are not visible |
| 8465 | to {expr}. |
| 8466 | |
| 8467 | Can also be used as a |method|: > |
| 8468 | GetExpr()->pyeval() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8469 | < |
| 8470 | Return type: any, depending on {expr} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8471 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8472 | {only available when compiled with the |+python| feature} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8473 | |
zeertzjq | 7c51528 | 2024-11-10 20:26:12 +0100 | [diff] [blame] | 8474 | pyxeval({expr} [, {locals}]) *pyxeval()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8475 | Evaluate Python expression {expr} and return its result |
| 8476 | converted to Vim data structures. |
Ben Jackson | ea19e78 | 2024-11-06 21:50:05 +0100 | [diff] [blame] | 8477 | For {locals} see |py3eval()|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8478 | Uses Python 2 or 3, see |python_x| and 'pyxversion'. |
| 8479 | See also: |pyeval()|, |py3eval()| |
| 8480 | |
| 8481 | Can also be used as a |method|: > |
h-east | 52e7cc2 | 2024-07-28 17:03:29 +0200 | [diff] [blame] | 8482 | GetExpr()->pyxeval() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8483 | < |
| 8484 | Return type: any, depending on {expr} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8485 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8486 | {only available when compiled with the |+python| or the |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8487 | |+python3| feature} |
| 8488 | |
| 8489 | rand([{expr}]) *rand()* *random* |
| 8490 | Return a pseudo-random Number generated with an xoshiro128** |
| 8491 | algorithm using seed {expr}. The returned number is 32 bits, |
| 8492 | also on 64 bits systems, for consistency. |
| 8493 | {expr} can be initialized by |srand()| and will be updated by |
| 8494 | rand(). If {expr} is omitted, an internal seed value is used |
| 8495 | and updated. |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 8496 | Returns -1 if {expr} is invalid. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8497 | |
| 8498 | Examples: > |
| 8499 | :echo rand() |
| 8500 | :let seed = srand() |
| 8501 | :echo rand(seed) |
| 8502 | :echo rand(seed) % 16 " random number 0 - 15 |
| 8503 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8504 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8505 | |
| 8506 | *E726* *E727* |
| 8507 | range({expr} [, {max} [, {stride}]]) *range()* |
| 8508 | Returns a |List| with Numbers: |
| 8509 | - If only {expr} is specified: [0, 1, ..., {expr} - 1] |
| 8510 | - If {max} is specified: [{expr}, {expr} + 1, ..., {max}] |
| 8511 | - If {stride} is specified: [{expr}, {expr} + {stride}, ..., |
| 8512 | {max}] (increasing {expr} with {stride} each time, not |
| 8513 | producing a value past {max}). |
| 8514 | When the maximum is one before the start the result is an |
| 8515 | empty list. When the maximum is more than one before the |
| 8516 | start this is an error. |
| 8517 | Examples: > |
| 8518 | range(4) " [0, 1, 2, 3] |
| 8519 | range(2, 4) " [2, 3, 4] |
| 8520 | range(2, 9, 3) " [2, 5, 8] |
| 8521 | range(2, -2, -1) " [2, 1, 0, -1, -2] |
| 8522 | range(0) " [] |
| 8523 | range(2, 0) " error! |
| 8524 | < |
| 8525 | Can also be used as a |method|: > |
| 8526 | GetExpr()->range() |
| 8527 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8528 | Return type: list<number> |
| 8529 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8530 | |
K.Takata | 11df3ae | 2022-10-19 14:02:40 +0100 | [diff] [blame] | 8531 | readblob({fname} [, {offset} [, {size}]]) *readblob()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8532 | Read file {fname} in binary mode and return a |Blob|. |
K.Takata | 11df3ae | 2022-10-19 14:02:40 +0100 | [diff] [blame] | 8533 | If {offset} is specified, read the file from the specified |
| 8534 | offset. If it is a negative value, it is used as an offset |
| 8535 | from the end of the file. E.g., to read the last 12 bytes: > |
| 8536 | readblob('file.bin', -12) |
| 8537 | < If {size} is specified, only the specified size will be read. |
| 8538 | E.g. to read the first 100 bytes of a file: > |
| 8539 | readblob('file.bin', 0, 100) |
| 8540 | < If {size} is -1 or omitted, the whole data starting from |
| 8541 | {offset} will be read. |
K.Takata | 4362576 | 2022-10-20 13:28:51 +0100 | [diff] [blame] | 8542 | This can be also used to read the data from a character device |
| 8543 | on Unix when {size} is explicitly set. Only if the device |
| 8544 | supports seeking {offset} can be used. Otherwise it should be |
| 8545 | zero. E.g. to read 10 bytes from a serial console: > |
| 8546 | readblob('/dev/ttyS0', 0, 10) |
| 8547 | < When the file can't be opened an error message is given and |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8548 | the result is an empty |Blob|. |
Bram Moolenaar | 5b2a3d7 | 2022-10-21 11:25:30 +0100 | [diff] [blame] | 8549 | When the offset is beyond the end of the file the result is an |
| 8550 | empty blob. |
| 8551 | When trying to read more bytes than are available the result |
| 8552 | is truncated. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8553 | Also see |readfile()| and |writefile()|. |
| 8554 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8555 | Return type: |Blob| |
| 8556 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8557 | |
| 8558 | readdir({directory} [, {expr} [, {dict}]]) *readdir()* |
| 8559 | Return a list with file and directory names in {directory}. |
| 8560 | You can also use |glob()| if you don't need to do complicated |
| 8561 | things, such as limiting the number of matches. |
| 8562 | The list will be sorted (case sensitive), see the {dict} |
| 8563 | argument below for changing the sort order. |
| 8564 | |
| 8565 | When {expr} is omitted all entries are included. |
| 8566 | When {expr} is given, it is evaluated to check what to do: |
| 8567 | If {expr} results in -1 then no further entries will |
| 8568 | be handled. |
| 8569 | If {expr} results in 0 then this entry will not be |
| 8570 | added to the list. |
| 8571 | If {expr} results in 1 then this entry will be added |
| 8572 | to the list. |
| 8573 | The entries "." and ".." are always excluded. |
| 8574 | Each time {expr} is evaluated |v:val| is set to the entry name. |
| 8575 | When {expr} is a function the name is passed as the argument. |
| 8576 | For example, to get a list of files ending in ".txt": > |
| 8577 | readdir(dirname, {n -> n =~ '.txt$'}) |
| 8578 | < To skip hidden and backup files: > |
| 8579 | readdir(dirname, {n -> n !~ '^\.\|\~$'}) |
Bram Moolenaar | 6f4754b | 2022-01-23 12:07:04 +0000 | [diff] [blame] | 8580 | < *E857* |
| 8581 | The optional {dict} argument allows for further custom |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8582 | values. Currently this is used to specify if and how sorting |
| 8583 | should be performed. The dict can have the following members: |
| 8584 | |
| 8585 | sort How to sort the result returned from the system. |
| 8586 | Valid values are: |
| 8587 | "none" do not sort (fastest method) |
| 8588 | "case" sort case sensitive (byte value of |
| 8589 | each character, technically, using |
| 8590 | strcmp()) (default) |
| 8591 | "icase" sort case insensitive (technically |
| 8592 | using strcasecmp()) |
| 8593 | "collate" sort using the collation order |
| 8594 | of the "POSIX" or "C" |locale| |
| 8595 | (technically using strcoll()) |
| 8596 | Other values are silently ignored. |
| 8597 | |
| 8598 | For example, to get a list of all files in the current |
| 8599 | directory without sorting the individual entries: > |
| 8600 | readdir('.', '1', #{sort: 'none'}) |
| 8601 | < If you want to get a directory tree: > |
| 8602 | function! s:tree(dir) |
| 8603 | return {a:dir : map(readdir(a:dir), |
| 8604 | \ {_, x -> isdirectory(x) ? |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 8605 | \ {x : s:tree(a:dir .. '/' .. x)} : x})} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8606 | endfunction |
| 8607 | echo s:tree(".") |
| 8608 | < |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 8609 | Returns an empty List on error. |
| 8610 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8611 | Can also be used as a |method|: > |
| 8612 | GetDirName()->readdir() |
| 8613 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8614 | Return type: list<string> or list<any> |
| 8615 | |
| 8616 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8617 | readdirex({directory} [, {expr} [, {dict}]]) *readdirex()* |
| 8618 | Extended version of |readdir()|. |
| 8619 | Return a list of Dictionaries with file and directory |
| 8620 | information in {directory}. |
| 8621 | This is useful if you want to get the attributes of file and |
| 8622 | directory at the same time as getting a list of a directory. |
| 8623 | This is much faster than calling |readdir()| then calling |
| 8624 | |getfperm()|, |getfsize()|, |getftime()| and |getftype()| for |
| 8625 | each file and directory especially on MS-Windows. |
| 8626 | The list will by default be sorted by name (case sensitive), |
| 8627 | the sorting can be changed by using the optional {dict} |
| 8628 | argument, see |readdir()|. |
| 8629 | |
| 8630 | The Dictionary for file and directory information has the |
| 8631 | following items: |
| 8632 | group Group name of the entry. (Only on Unix) |
| 8633 | name Name of the entry. |
| 8634 | perm Permissions of the entry. See |getfperm()|. |
| 8635 | size Size of the entry. See |getfsize()|. |
| 8636 | time Timestamp of the entry. See |getftime()|. |
| 8637 | type Type of the entry. |
| 8638 | On Unix, almost same as |getftype()| except: |
| 8639 | Symlink to a dir "linkd" |
| 8640 | Other symlink "link" |
| 8641 | On MS-Windows: |
| 8642 | Normal file "file" |
| 8643 | Directory "dir" |
| 8644 | Junction "junction" |
| 8645 | Symlink to a dir "linkd" |
| 8646 | Other symlink "link" |
| 8647 | Other reparse point "reparse" |
| 8648 | user User name of the entry's owner. (Only on Unix) |
| 8649 | On Unix, if the entry is a symlink, the Dictionary includes |
| 8650 | the information of the target (except the "type" item). |
| 8651 | On MS-Windows, it includes the information of the symlink |
| 8652 | itself because of performance reasons. |
| 8653 | |
| 8654 | When {expr} is omitted all entries are included. |
| 8655 | When {expr} is given, it is evaluated to check what to do: |
| 8656 | If {expr} results in -1 then no further entries will |
| 8657 | be handled. |
| 8658 | If {expr} results in 0 then this entry will not be |
| 8659 | added to the list. |
| 8660 | If {expr} results in 1 then this entry will be added |
| 8661 | to the list. |
| 8662 | The entries "." and ".." are always excluded. |
| 8663 | Each time {expr} is evaluated |v:val| is set to a |Dictionary| |
| 8664 | of the entry. |
| 8665 | When {expr} is a function the entry is passed as the argument. |
| 8666 | For example, to get a list of files ending in ".txt": > |
| 8667 | readdirex(dirname, {e -> e.name =~ '.txt$'}) |
| 8668 | < |
| 8669 | For example, to get a list of all files in the current |
| 8670 | directory without sorting the individual entries: > |
| 8671 | readdirex(dirname, '1', #{sort: 'none'}) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8672 | < |
| 8673 | Can also be used as a |method|: > |
| 8674 | GetDirName()->readdirex() |
| 8675 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8676 | Return type: list<dict<any>> or list<any> |
| 8677 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8678 | |
| 8679 | *readfile()* |
| 8680 | readfile({fname} [, {type} [, {max}]]) |
| 8681 | Read file {fname} and return a |List|, each line of the file |
| 8682 | as an item. Lines are broken at NL characters. Macintosh |
| 8683 | files separated with CR will result in a single long line |
| 8684 | (unless a NL appears somewhere). |
| 8685 | All NUL characters are replaced with a NL character. |
| 8686 | When {type} contains "b" binary mode is used: |
| 8687 | - When the last line ends in a NL an extra empty list item is |
| 8688 | added. |
| 8689 | - No CR characters are removed. |
| 8690 | Otherwise: |
| 8691 | - CR characters that appear before a NL are removed. |
| 8692 | - Whether the last line ends in a NL or not does not matter. |
| 8693 | - When 'encoding' is Unicode any UTF-8 byte order mark is |
| 8694 | removed from the text. |
| 8695 | When {max} is given this specifies the maximum number of lines |
| 8696 | to be read. Useful if you only want to check the first ten |
| 8697 | lines of a file: > |
| 8698 | :for line in readfile(fname, '', 10) |
| 8699 | : if line =~ 'Date' | echo line | endif |
| 8700 | :endfor |
| 8701 | < When {max} is negative -{max} lines from the end of the file |
| 8702 | are returned, or as many as there are. |
| 8703 | When {max} is zero the result is an empty list. |
| 8704 | Note that without {max} the whole file is read into memory. |
| 8705 | Also note that there is no recognition of encoding. Read a |
| 8706 | file into a buffer if you need to. |
| 8707 | Deprecated (use |readblob()| instead): When {type} contains |
| 8708 | "B" a |Blob| is returned with the binary data of the file |
| 8709 | unmodified. |
| 8710 | When the file can't be opened an error message is given and |
| 8711 | the result is an empty list. |
| 8712 | Also see |writefile()|. |
| 8713 | |
| 8714 | Can also be used as a |method|: > |
| 8715 | GetFileName()->readfile() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8716 | < |
| 8717 | Return type: list<string> or list<any> |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8718 | |
| 8719 | reduce({object}, {func} [, {initial}]) *reduce()* *E998* |
| 8720 | {func} is called for every item in {object}, which can be a |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 8721 | |String|, |List|, |Tuple| or a |Blob|. {func} is called with |
| 8722 | two arguments: the result so far and current item. After |
Bram Moolenaar | f10911e | 2022-01-29 22:20:48 +0000 | [diff] [blame] | 8723 | processing all items the result is returned. *E1132* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8724 | |
| 8725 | {initial} is the initial result. When omitted, the first item |
| 8726 | in {object} is used and {func} is first called for the second |
| 8727 | item. If {initial} is not given and {object} is empty no |
| 8728 | result can be computed, an E998 error is given. |
| 8729 | |
| 8730 | Examples: > |
| 8731 | echo reduce([1, 3, 5], { acc, val -> acc + val }) |
| 8732 | echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a') |
| 8733 | echo reduce(0z1122, { acc, val -> 2 * acc + val }) |
| 8734 | echo reduce('xyz', { acc, val -> acc .. ',' .. val }) |
| 8735 | < |
| 8736 | Can also be used as a |method|: > |
| 8737 | echo mylist->reduce({ acc, val -> acc + val }, 0) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8738 | < |
| 8739 | Return type: |String|, |Blob|, list<{type}> or dict<{type}> |
| 8740 | depending on {object} and {func} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8741 | |
| 8742 | |
| 8743 | reg_executing() *reg_executing()* |
| 8744 | Returns the single letter name of the register being executed. |
| 8745 | Returns an empty string when no register is being executed. |
| 8746 | See |@|. |
| 8747 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8748 | Return type: |String| |
| 8749 | |
| 8750 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8751 | reg_recording() *reg_recording()* |
| 8752 | Returns the single letter name of the register being recorded. |
| 8753 | Returns an empty string when not recording. See |q|. |
| 8754 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8755 | Return type: |String| |
| 8756 | |
| 8757 | |
| 8758 | reltime() *reltime()* |
Bram Moolenaar | f269eab | 2022-10-03 18:04:35 +0100 | [diff] [blame] | 8759 | reltime({start}) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8760 | reltime({start}, {end}) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8761 | Return an item that represents a time value. The item is a |
| 8762 | list with items that depend on the system. In Vim 9 script |
Bram Moolenaar | 71badf9 | 2023-04-22 22:40:14 +0100 | [diff] [blame] | 8763 | the type list<any> can be used. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8764 | The item can be passed to |reltimestr()| to convert it to a |
Bram Moolenaar | f269eab | 2022-10-03 18:04:35 +0100 | [diff] [blame] | 8765 | string or |reltimefloat()| to convert to a Float. For |
| 8766 | example, to see the time spent in function Work(): > |
| 8767 | var startTime = reltime() |
| 8768 | Work() |
| 8769 | echo startTime->reltime()->reltimestr() |
| 8770 | < |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 8771 | Without an argument reltime() returns the current time (the |
Lifepillar | 963fd7d | 2024-01-05 17:44:57 +0100 | [diff] [blame] | 8772 | representation is system-dependent, it cannot be used as the |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 8773 | wall-clock time, see |localtime()| for that). |
Lifepillar | 963fd7d | 2024-01-05 17:44:57 +0100 | [diff] [blame] | 8774 | With one argument it returns the time passed since the time |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8775 | specified in the argument. |
| 8776 | With two arguments it returns the time passed between {start} |
| 8777 | and {end}. |
| 8778 | |
| 8779 | The {start} and {end} arguments must be values returned by |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 8780 | reltime(). If there is an error an empty List is returned in |
| 8781 | legacy script, in Vim9 script an error is given. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8782 | |
| 8783 | Can also be used as a |method|: > |
| 8784 | GetStart()->reltime() |
| 8785 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8786 | Return type: list<number> |
| 8787 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8788 | {only available when compiled with the |+reltime| feature} |
| 8789 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8790 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8791 | reltimefloat({time}) *reltimefloat()* |
| 8792 | Return a Float that represents the time value of {time}. |
| 8793 | Example: > |
| 8794 | let start = reltime() |
| 8795 | call MyFunction() |
| 8796 | let seconds = reltimefloat(reltime(start)) |
| 8797 | < See the note of reltimestr() about overhead. |
| 8798 | Also see |profiling|. |
| 8799 | If there is an error 0.0 is returned in legacy script, in Vim9 |
| 8800 | script an error is given. |
| 8801 | |
| 8802 | Can also be used as a |method|: > |
| 8803 | reltime(start)->reltimefloat() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8804 | < |
| 8805 | Return type: |Float| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8806 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8807 | {only available when compiled with the |+reltime| feature} |
| 8808 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8809 | |
| 8810 | reltimestr({time}) *reltimestr()* |
| 8811 | Return a String that represents the time value of {time}. |
| 8812 | This is the number of seconds, a dot and the number of |
| 8813 | microseconds. Example: > |
| 8814 | let start = reltime() |
| 8815 | call MyFunction() |
| 8816 | echo reltimestr(reltime(start)) |
| 8817 | < Note that overhead for the commands will be added to the time. |
Ernie Rael | 076de79 | 2023-03-16 21:43:15 +0000 | [diff] [blame] | 8818 | The accuracy depends on the system. Use reltimefloat() for the |
| 8819 | greatest accuracy which is nanoseconds on some systems. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8820 | Leading spaces are used to make the string align nicely. You |
| 8821 | can use split() to remove it. > |
| 8822 | echo split(reltimestr(reltime(start)))[0] |
| 8823 | < Also see |profiling|. |
| 8824 | If there is an error an empty string is returned in legacy |
| 8825 | script, in Vim9 script an error is given. |
| 8826 | |
| 8827 | Can also be used as a |method|: > |
| 8828 | reltime(start)->reltimestr() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8829 | < |
| 8830 | Return type: |String| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8831 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8832 | {only available when compiled with the |+reltime| feature} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8833 | |
| 8834 | *remote_expr()* *E449* |
| 8835 | remote_expr({server}, {string} [, {idvar} [, {timeout}]]) |
Bram Moolenaar | 944697a | 2022-02-20 19:48:20 +0000 | [diff] [blame] | 8836 | Send the {string} to {server}. The {server} argument is a |
| 8837 | string, also see |{server}|. |
| 8838 | |
| 8839 | The string is sent as an expression and the result is returned |
Christian Brabandt | 1961caf | 2024-10-12 11:57:12 +0200 | [diff] [blame] | 8840 | after evaluation. The result must be a String or a |List| |
| 8841 | other types will be converted to String. A |List| is turned |
| 8842 | into a String by joining the items with a line break in |
| 8843 | between (not at the end), like with join(expr, "\n"). |
Bram Moolenaar | 944697a | 2022-02-20 19:48:20 +0000 | [diff] [blame] | 8844 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8845 | If {idvar} is present and not empty, it is taken as the name |
| 8846 | of a variable and a {serverid} for later use with |
| 8847 | |remote_read()| is stored there. |
Bram Moolenaar | 944697a | 2022-02-20 19:48:20 +0000 | [diff] [blame] | 8848 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8849 | If {timeout} is given the read times out after this many |
| 8850 | seconds. Otherwise a timeout of 600 seconds is used. |
Bram Moolenaar | 944697a | 2022-02-20 19:48:20 +0000 | [diff] [blame] | 8851 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8852 | See also |clientserver| |RemoteReply|. |
| 8853 | This function is not available in the |sandbox|. |
| 8854 | {only available when compiled with the |+clientserver| feature} |
| 8855 | Note: Any errors will cause a local error message to be issued |
| 8856 | and the result will be the empty string. |
| 8857 | |
| 8858 | Variables will be evaluated in the global namespace, |
| 8859 | independent of a function currently being active. Except |
| 8860 | when in debug mode, then local function variables and |
| 8861 | arguments can be evaluated. |
| 8862 | |
| 8863 | Examples: > |
| 8864 | :echo remote_expr("gvim", "2+2") |
| 8865 | :echo remote_expr("gvim1", "b:current_syntax") |
| 8866 | < |
| 8867 | Can also be used as a |method|: > |
| 8868 | ServerName()->remote_expr(expr) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8869 | < |
| 8870 | Return type: |String| or list<{type}> |
| 8871 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8872 | |
| 8873 | remote_foreground({server}) *remote_foreground()* |
| 8874 | Move the Vim server with the name {server} to the foreground. |
Bram Moolenaar | 944697a | 2022-02-20 19:48:20 +0000 | [diff] [blame] | 8875 | The {server} argument is a string, also see |{server}|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8876 | This works like: > |
| 8877 | remote_expr({server}, "foreground()") |
| 8878 | < Except that on Win32 systems the client does the work, to work |
| 8879 | around the problem that the OS doesn't always allow the server |
| 8880 | to bring itself to the foreground. |
| 8881 | Note: This does not restore the window if it was minimized, |
| 8882 | like foreground() does. |
| 8883 | This function is not available in the |sandbox|. |
| 8884 | |
| 8885 | Can also be used as a |method|: > |
| 8886 | ServerName()->remote_foreground() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8887 | < |
| 8888 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8889 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8890 | {only in the Win32, Motif and GTK GUI versions and the |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8891 | Win32 console version} |
| 8892 | |
| 8893 | |
| 8894 | remote_peek({serverid} [, {retvar}]) *remote_peek()* |
| 8895 | Returns a positive number if there are available strings |
| 8896 | from {serverid}. Copies any reply string into the variable |
| 8897 | {retvar} if specified. {retvar} must be a string with the |
| 8898 | name of a variable. |
| 8899 | Returns zero if none are available. |
| 8900 | Returns -1 if something is wrong. |
| 8901 | See also |clientserver|. |
| 8902 | This function is not available in the |sandbox|. |
| 8903 | {only available when compiled with the |+clientserver| feature} |
| 8904 | Examples: > |
Bram Moolenaar | f269eab | 2022-10-03 18:04:35 +0100 | [diff] [blame] | 8905 | :let repl = "" |
| 8906 | :echo "PEEK: " .. remote_peek(id, "repl") .. ": " .. repl |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8907 | |
| 8908 | < Can also be used as a |method|: > |
| 8909 | ServerId()->remote_peek() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8910 | < |
| 8911 | Return type: |Number| |
| 8912 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8913 | |
| 8914 | remote_read({serverid}, [{timeout}]) *remote_read()* |
| 8915 | Return the oldest available reply from {serverid} and consume |
| 8916 | it. Unless a {timeout} in seconds is given, it blocks until a |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 8917 | reply is available. Returns an empty string, if a reply is |
| 8918 | not available or on error. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8919 | See also |clientserver|. |
| 8920 | This function is not available in the |sandbox|. |
| 8921 | {only available when compiled with the |+clientserver| feature} |
| 8922 | Example: > |
| 8923 | :echo remote_read(id) |
| 8924 | |
| 8925 | < Can also be used as a |method|: > |
| 8926 | ServerId()->remote_read() |
| 8927 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8928 | Return type: |String| |
| 8929 | |
| 8930 | |
| 8931 | remote_send({server}, {string} [, {idvar}]) *remote_send()* *E241* |
Bram Moolenaar | 944697a | 2022-02-20 19:48:20 +0000 | [diff] [blame] | 8932 | Send the {string} to {server}. The {server} argument is a |
| 8933 | string, also see |{server}|. |
| 8934 | |
| 8935 | The string is sent as input keys and the function returns |
| 8936 | immediately. At the Vim server the keys are not mapped |
| 8937 | |:map|. |
| 8938 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8939 | If {idvar} is present, it is taken as the name of a variable |
| 8940 | and a {serverid} for later use with remote_read() is stored |
| 8941 | there. |
Bram Moolenaar | 944697a | 2022-02-20 19:48:20 +0000 | [diff] [blame] | 8942 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8943 | See also |clientserver| |RemoteReply|. |
| 8944 | This function is not available in the |sandbox|. |
| 8945 | {only available when compiled with the |+clientserver| feature} |
| 8946 | |
| 8947 | Note: Any errors will be reported in the server and may mess |
| 8948 | up the display. |
| 8949 | Examples: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 8950 | :echo remote_send("gvim", ":DropAndReply " .. file, "serverid") .. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8951 | \ remote_read(serverid) |
| 8952 | |
| 8953 | :autocmd NONE RemoteReply * |
| 8954 | \ echo remote_read(expand("<amatch>")) |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 8955 | :echo remote_send("gvim", ":sleep 10 | echo " .. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8956 | \ 'server2client(expand("<client>"), "HELLO")<CR>') |
| 8957 | < |
| 8958 | Can also be used as a |method|: > |
| 8959 | ServerName()->remote_send(keys) |
| 8960 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8961 | Return type: |String| |
| 8962 | |
| 8963 | |
| 8964 | remote_startserver({name}) *remote_startserver()* *E941* *E942* |
h-east | 17b6951 | 2023-05-01 22:36:56 +0100 | [diff] [blame] | 8965 | Become the server {name}. {name} must be a non-empty string. |
| 8966 | This fails if already running as a server, when |v:servername| |
| 8967 | is not empty. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8968 | |
| 8969 | Can also be used as a |method|: > |
| 8970 | ServerName()->remote_startserver() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8971 | < |
| 8972 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8973 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8974 | {only available when compiled with the |+clientserver| feature} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8975 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8976 | |
| 8977 | remove({list}, {idx}) *remove()* |
| 8978 | remove({list}, {idx}, {end}) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8979 | Without {end}: Remove the item at {idx} from |List| {list} and |
| 8980 | return the item. |
| 8981 | With {end}: Remove items from {idx} to {end} (inclusive) and |
| 8982 | return a |List| with these items. When {idx} points to the same |
| 8983 | item as {end} a list with one item is returned. When {end} |
| 8984 | points to an item before {idx} this is an error. |
| 8985 | See |list-index| for possible values of {idx} and {end}. |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 8986 | Returns zero on error. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8987 | Example: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 8988 | :echo "last item: " .. remove(mylist, -1) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8989 | :call remove(mylist, 0, 9) |
| 8990 | < |
| 8991 | Use |delete()| to remove a file. |
| 8992 | |
| 8993 | Can also be used as a |method|: > |
| 8994 | mylist->remove(idx) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 8995 | < |
| 8996 | Return type: any, depending on {list} |
| 8997 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 8998 | |
Bram Moolenaar | f269eab | 2022-10-03 18:04:35 +0100 | [diff] [blame] | 8999 | remove({blob}, {idx}) |
| 9000 | remove({blob}, {idx}, {end}) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9001 | Without {end}: Remove the byte at {idx} from |Blob| {blob} and |
| 9002 | return the byte. |
| 9003 | With {end}: Remove bytes from {idx} to {end} (inclusive) and |
| 9004 | return a |Blob| with these bytes. When {idx} points to the same |
| 9005 | byte as {end} a |Blob| with one byte is returned. When {end} |
| 9006 | points to a byte before {idx} this is an error. |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 9007 | Returns zero on error. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9008 | Example: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 9009 | :echo "last byte: " .. remove(myblob, -1) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9010 | :call remove(mylist, 0, 9) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9011 | < |
| 9012 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9013 | |
| 9014 | remove({dict}, {key}) |
| 9015 | Remove the entry from {dict} with key {key} and return it. |
| 9016 | Example: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 9017 | :echo "removed " .. remove(dict, "one") |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9018 | < If there is no {key} in {dict} this is an error. |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 9019 | Returns zero on error. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9020 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9021 | Return type: any, depending on {dict} |
| 9022 | |
| 9023 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9024 | rename({from}, {to}) *rename()* |
| 9025 | Rename the file by the name {from} to the name {to}. This |
| 9026 | should also work to move files across file systems. The |
| 9027 | result is a Number, which is 0 if the file was renamed |
| 9028 | successfully, and non-zero when the renaming failed. |
| 9029 | NOTE: If {to} exists it is overwritten without warning. |
| 9030 | This function is not available in the |sandbox|. |
| 9031 | |
| 9032 | Can also be used as a |method|: > |
| 9033 | GetOldName()->rename(newname) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9034 | < |
| 9035 | Return type: |Number| |
| 9036 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9037 | |
| 9038 | repeat({expr}, {count}) *repeat()* |
| 9039 | Repeat {expr} {count} times and return the concatenated |
| 9040 | result. Example: > |
| 9041 | :let separator = repeat('-', 80) |
| 9042 | < When {count} is zero or negative the result is empty. |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 9043 | When {expr} is a |List|, a |Tuple| or a |Blob| the result is |
| 9044 | {expr} concatenated {count} times. Example: > |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9045 | :let longlist = repeat(['a', 'b'], 3) |
| 9046 | < Results in ['a', 'b', 'a', 'b', 'a', 'b']. |
| 9047 | |
| 9048 | Can also be used as a |method|: > |
| 9049 | mylist->repeat(count) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9050 | < |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 9051 | Return type: |String|, |Blob|, list<{type}> or tuple<{type}> |
| 9052 | depending on {expr} |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9053 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9054 | |
| 9055 | resolve({filename}) *resolve()* *E655* |
| 9056 | On MS-Windows, when {filename} is a shortcut (a .lnk file), |
| 9057 | returns the path the shortcut points to in a simplified form. |
| 9058 | When {filename} is a symbolic link or junction point, return |
| 9059 | the full path to the target. If the target of junction is |
| 9060 | removed, return {filename}. |
| 9061 | On Unix, repeat resolving symbolic links in all path |
| 9062 | components of {filename} and return the simplified result. |
| 9063 | To cope with link cycles, resolving of symbolic links is |
| 9064 | stopped after 100 iterations. |
| 9065 | On other systems, return the simplified {filename}. |
| 9066 | The simplification step is done as by |simplify()|. |
| 9067 | resolve() keeps a leading path component specifying the |
| 9068 | current directory (provided the result is still a relative |
| 9069 | path name) and also keeps a trailing path separator. |
| 9070 | |
| 9071 | Can also be used as a |method|: > |
| 9072 | GetName()->resolve() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9073 | < |
| 9074 | Return type: |String| |
| 9075 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9076 | |
| 9077 | reverse({object}) *reverse()* |
Yegappan Lakshmanan | 03ff1c2 | 2023-05-06 14:08:21 +0100 | [diff] [blame] | 9078 | Reverse the order of items in {object}. {object} can be a |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 9079 | |List|, a |Tuple|, a |Blob| or a |String|. For a List and a |
| 9080 | Blob the items are reversed in-place and {object} is returned. |
| 9081 | For a Tuple, a new Tuple is returned. |
Yegappan Lakshmanan | 03ff1c2 | 2023-05-06 14:08:21 +0100 | [diff] [blame] | 9082 | For a String a new String is returned. |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 9083 | Returns zero if {object} is not a List, Tuple, Blob or a |
| 9084 | String. If you want a List or Blob to remain unmodified make |
| 9085 | a copy first: > |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9086 | :let revlist = reverse(copy(mylist)) |
| 9087 | < Can also be used as a |method|: > |
| 9088 | mylist->reverse() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9089 | < |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 9090 | Return type: |String|, |Blob|, list<{type}> or tuple<{type}> |
| 9091 | depending on {object} |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9092 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9093 | |
| 9094 | round({expr}) *round()* |
| 9095 | Round off {expr} to the nearest integral value and return it |
| 9096 | as a |Float|. If {expr} lies halfway between two integral |
| 9097 | values, then use the larger one (away from zero). |
| 9098 | {expr} must evaluate to a |Float| or a |Number|. |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 9099 | Returns 0.0 if {expr} is not a |Float| or a |Number|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9100 | Examples: > |
| 9101 | echo round(0.456) |
| 9102 | < 0.0 > |
| 9103 | echo round(4.5) |
| 9104 | < 5.0 > |
| 9105 | echo round(-4.5) |
| 9106 | < -5.0 |
| 9107 | |
| 9108 | Can also be used as a |method|: > |
| 9109 | Compute()->round() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9110 | < |
| 9111 | Return type: |Float| |
| 9112 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9113 | |
| 9114 | rubyeval({expr}) *rubyeval()* |
| 9115 | Evaluate Ruby expression {expr} and return its result |
| 9116 | converted to Vim data structures. |
| 9117 | Numbers, floats and strings are returned as they are (strings |
| 9118 | are copied though). |
| 9119 | Arrays are represented as Vim |List| type. |
| 9120 | Hashes are represented as Vim |Dictionary| type. |
| 9121 | Other objects are represented as strings resulted from their |
| 9122 | "Object#to_s" method. |
| 9123 | Note that in a `:def` function local variables are not visible |
| 9124 | to {expr}. |
| 9125 | |
| 9126 | Can also be used as a |method|: > |
| 9127 | GetRubyExpr()->rubyeval() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9128 | < |
| 9129 | Return type: any, depending on {expr} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9130 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9131 | {only available when compiled with the |+ruby| feature} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9132 | |
| 9133 | screenattr({row}, {col}) *screenattr()* |
| 9134 | Like |screenchar()|, but return the attribute. This is a rather |
| 9135 | arbitrary number that can only be used to compare to the |
| 9136 | attribute at other positions. |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 9137 | Returns -1 when row or col is out of range. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9138 | |
| 9139 | Can also be used as a |method|: > |
| 9140 | GetRow()->screenattr(col) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9141 | < |
| 9142 | Return type: |Number| |
| 9143 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9144 | |
| 9145 | screenchar({row}, {col}) *screenchar()* |
| 9146 | The result is a Number, which is the character at position |
| 9147 | [row, col] on the screen. This works for every possible |
| 9148 | screen position, also status lines, window separators and the |
| 9149 | command line. The top left position is row one, column one |
| 9150 | The character excludes composing characters. For double-byte |
| 9151 | encodings it may only be the first byte. |
| 9152 | This is mainly to be used for testing. |
| 9153 | Returns -1 when row or col is out of range. |
| 9154 | |
| 9155 | Can also be used as a |method|: > |
| 9156 | GetRow()->screenchar(col) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9157 | < |
| 9158 | Return type: |Number| |
| 9159 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9160 | |
| 9161 | screenchars({row}, {col}) *screenchars()* |
| 9162 | The result is a |List| of Numbers. The first number is the same |
| 9163 | as what |screenchar()| returns. Further numbers are |
| 9164 | composing characters on top of the base character. |
| 9165 | This is mainly to be used for testing. |
| 9166 | Returns an empty List when row or col is out of range. |
| 9167 | |
| 9168 | Can also be used as a |method|: > |
| 9169 | GetRow()->screenchars(col) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9170 | < |
| 9171 | Return type: list<number> or list<any> |
| 9172 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9173 | |
| 9174 | screencol() *screencol()* |
| 9175 | The result is a Number, which is the current screen column of |
| 9176 | the cursor. The leftmost column has number 1. |
| 9177 | This function is mainly used for testing. |
| 9178 | |
| 9179 | Note: Always returns the current screen column, thus if used |
| 9180 | in a command (e.g. ":echo screencol()") it will return the |
| 9181 | column inside the command line, which is 1 when the command is |
| 9182 | executed. To get the cursor position in the file use one of |
| 9183 | the following mappings: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 9184 | nnoremap <expr> GG ":echom " .. screencol() .. "\n" |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9185 | nnoremap <silent> GG :echom screencol()<CR> |
| 9186 | nnoremap GG <Cmd>echom screencol()<CR> |
| 9187 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9188 | Return type: |Number| |
| 9189 | |
| 9190 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9191 | screenpos({winid}, {lnum}, {col}) *screenpos()* |
| 9192 | The result is a Dict with the screen position of the text |
| 9193 | character in window {winid} at buffer line {lnum} and column |
| 9194 | {col}. {col} is a one-based byte index. |
| 9195 | The Dict has these members: |
| 9196 | row screen row |
| 9197 | col first screen column |
| 9198 | endcol last screen column |
| 9199 | curscol cursor screen column |
| 9200 | If the specified position is not visible, all values are zero. |
| 9201 | The "endcol" value differs from "col" when the character |
| 9202 | occupies more than one screen cell. E.g. for a Tab "col" can |
| 9203 | be 1 and "endcol" can be 8. |
| 9204 | The "curscol" value is where the cursor would be placed. For |
| 9205 | a Tab it would be the same as "endcol", while for a double |
| 9206 | width character it would be the same as "col". |
| 9207 | The |conceal| feature is ignored here, the column numbers are |
| 9208 | as if 'conceallevel' is zero. You can set the cursor to the |
| 9209 | right position and use |screencol()| to get the value with |
| 9210 | |conceal| taken into account. |
Bram Moolenaar | 944697a | 2022-02-20 19:48:20 +0000 | [diff] [blame] | 9211 | If the position is in a closed fold the screen position of the |
| 9212 | first character is returned, {col} is not used. |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 9213 | Returns an empty Dict if {winid} is invalid. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9214 | |
| 9215 | Can also be used as a |method|: > |
| 9216 | GetWinid()->screenpos(lnum, col) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9217 | < |
| 9218 | Return type: dict<number> or dict<any> |
| 9219 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9220 | |
| 9221 | screenrow() *screenrow()* |
| 9222 | The result is a Number, which is the current screen row of the |
| 9223 | cursor. The top line has number one. |
| 9224 | This function is mainly used for testing. |
| 9225 | Alternatively you can use |winline()|. |
| 9226 | |
| 9227 | Note: Same restrictions as with |screencol()|. |
| 9228 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9229 | Return type: |Number| |
| 9230 | |
| 9231 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9232 | screenstring({row}, {col}) *screenstring()* |
| 9233 | The result is a String that contains the base character and |
| 9234 | any composing characters at position [row, col] on the screen. |
| 9235 | This is like |screenchars()| but returning a String with the |
| 9236 | characters. |
| 9237 | This is mainly to be used for testing. |
| 9238 | Returns an empty String when row or col is out of range. |
| 9239 | |
| 9240 | Can also be used as a |method|: > |
| 9241 | GetRow()->screenstring(col) |
| 9242 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9243 | Return type: |String| |
| 9244 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9245 | *search()* |
| 9246 | search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) |
| 9247 | Search for regexp pattern {pattern}. The search starts at the |
| 9248 | cursor position (you can use |cursor()| to set it). |
| 9249 | |
| 9250 | When a match has been found its line number is returned. |
| 9251 | If there is no match a 0 is returned and the cursor doesn't |
| 9252 | move. No error message is given. |
Christian Brabandt | 9a660d2 | 2024-03-12 22:03:09 +0100 | [diff] [blame] | 9253 | To get the matched string, use |matchbufline()|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9254 | |
| 9255 | {flags} is a String, which can contain these character flags: |
| 9256 | 'b' search Backward instead of forward |
| 9257 | 'c' accept a match at the Cursor position |
| 9258 | 'e' move to the End of the match |
| 9259 | 'n' do Not move the cursor |
| 9260 | 'p' return number of matching sub-Pattern (see below) |
| 9261 | 's' Set the ' mark at the previous location of the cursor |
| 9262 | 'w' Wrap around the end of the file |
| 9263 | 'W' don't Wrap around the end of the file |
Doug Kearns | 8a27d97 | 2025-01-05 15:56:57 +0100 | [diff] [blame] | 9264 | 'z' start searching at the cursor column instead of Zero |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9265 | If neither 'w' or 'W' is given, the 'wrapscan' option applies. |
| 9266 | |
| 9267 | If the 's' flag is supplied, the ' mark is set, only if the |
| 9268 | cursor is moved. The 's' flag cannot be combined with the 'n' |
| 9269 | flag. |
| 9270 | |
| 9271 | 'ignorecase', 'smartcase' and 'magic' are used. |
| 9272 | |
| 9273 | When the 'z' flag is not given, forward searching always |
| 9274 | starts in column zero and then matches before the cursor are |
| 9275 | skipped. When the 'c' flag is present in 'cpo' the next |
| 9276 | search starts after the match. Without the 'c' flag the next |
Bram Moolenaar | fd99945 | 2022-08-24 18:30:14 +0100 | [diff] [blame] | 9277 | search starts one column after the start of the match. This |
| 9278 | matters for overlapping matches. See |cpo-c|. You can also |
| 9279 | insert "\ze" to change where the match ends, see |/\ze|. |
| 9280 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9281 | When searching backwards and the 'z' flag is given then the |
| 9282 | search starts in column zero, thus no match in the current |
| 9283 | line will be found (unless wrapping around the end of the |
| 9284 | file). |
| 9285 | |
| 9286 | When the {stopline} argument is given then the search stops |
| 9287 | after searching this line. This is useful to restrict the |
| 9288 | search to a range of lines. Examples: > |
| 9289 | let match = search('(', 'b', line("w0")) |
| 9290 | let end = search('END', '', line("w$")) |
| 9291 | < When {stopline} is used and it is not zero this also implies |
| 9292 | that the search does not wrap around the end of the file. |
| 9293 | A zero value is equal to not giving the argument. |
Bram Moolenaar | 2ecbe53 | 2022-07-29 21:36:21 +0100 | [diff] [blame] | 9294 | *E1285* *E1286* *E1287* *E1288* *E1289* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9295 | When the {timeout} argument is given the search stops when |
| 9296 | more than this many milliseconds have passed. Thus when |
| 9297 | {timeout} is 500 the search stops after half a second. |
| 9298 | The value must not be negative. A zero value is like not |
| 9299 | giving the argument. |
Christian Brabandt | d657d3d | 2024-09-10 21:55:49 +0200 | [diff] [blame] | 9300 | |
| 9301 | Note: the timeout is only considered when searching, not |
| 9302 | while evaluating the {skip} expression. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9303 | {only available when compiled with the |+reltime| feature} |
| 9304 | |
| 9305 | If the {skip} expression is given it is evaluated with the |
| 9306 | cursor positioned on the start of a match. If it evaluates to |
| 9307 | non-zero this match is skipped. This can be used, for |
| 9308 | example, to skip a match in a comment or a string. |
| 9309 | {skip} can be a string, which is evaluated as an expression, a |
| 9310 | function reference or a lambda. |
| 9311 | When {skip} is omitted or empty, every match is accepted. |
| 9312 | When evaluating {skip} causes an error the search is aborted |
| 9313 | and -1 returned. |
| 9314 | *search()-sub-match* |
| 9315 | With the 'p' flag the returned value is one more than the |
| 9316 | first sub-match in \(\). One if none of them matched but the |
| 9317 | whole pattern did match. |
| 9318 | To get the column number too use |searchpos()|. |
| 9319 | |
| 9320 | The cursor will be positioned at the match, unless the 'n' |
| 9321 | flag is used. |
| 9322 | |
| 9323 | Example (goes over all files in the argument list): > |
| 9324 | :let n = 1 |
| 9325 | :while n <= argc() " loop over all files in arglist |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 9326 | : exe "argument " .. n |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9327 | : " start at the last char in the file and wrap for the |
| 9328 | : " first search to find match at start of file |
| 9329 | : normal G$ |
| 9330 | : let flags = "w" |
| 9331 | : while search("foo", flags) > 0 |
| 9332 | : s/foo/bar/g |
| 9333 | : let flags = "W" |
| 9334 | : endwhile |
| 9335 | : update " write the file if modified |
| 9336 | : let n = n + 1 |
| 9337 | :endwhile |
| 9338 | < |
| 9339 | Example for using some flags: > |
| 9340 | :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe') |
| 9341 | < This will search for the keywords "if", "else", and "endif" |
| 9342 | under or after the cursor. Because of the 'p' flag, it |
| 9343 | returns 1, 2, or 3 depending on which keyword is found, or 0 |
| 9344 | if the search fails. With the cursor on the first word of the |
| 9345 | line: |
| 9346 | if (foo == 0) | let foo = foo + 1 | endif ~ |
| 9347 | the function returns 1. Without the 'c' flag, the function |
| 9348 | finds the "endif" and returns 3. The same thing happens |
| 9349 | without the 'e' flag if the cursor is on the "f" of "if". |
| 9350 | The 'n' flag tells the function not to move the cursor. |
| 9351 | |
| 9352 | Can also be used as a |method|: > |
| 9353 | GetPattern()->search() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9354 | < |
| 9355 | Return type: |Number| |
| 9356 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9357 | |
| 9358 | searchcount([{options}]) *searchcount()* |
| 9359 | Get or update the last search count, like what is displayed |
| 9360 | without the "S" flag in 'shortmess'. This works even if |
| 9361 | 'shortmess' does contain the "S" flag. |
| 9362 | |
| 9363 | This returns a |Dictionary|. The dictionary is empty if the |
| 9364 | previous pattern was not set and "pattern" was not specified. |
| 9365 | |
| 9366 | key type meaning ~ |
| 9367 | current |Number| current position of match; |
| 9368 | 0 if the cursor position is |
| 9369 | before the first match |
| 9370 | exact_match |Boolean| 1 if "current" is matched on |
| 9371 | "pos", otherwise 0 |
| 9372 | total |Number| total count of matches found |
| 9373 | incomplete |Number| 0: search was fully completed |
| 9374 | 1: recomputing was timed out |
| 9375 | 2: max count exceeded |
| 9376 | |
| 9377 | For {options} see further down. |
| 9378 | |
| 9379 | To get the last search count when |n| or |N| was pressed, call |
| 9380 | this function with `recompute: 0` . This sometimes returns |
| 9381 | wrong information because |n| and |N|'s maximum count is 99. |
| 9382 | If it exceeded 99 the result must be max count + 1 (100). If |
| 9383 | you want to get correct information, specify `recompute: 1`: > |
| 9384 | |
| 9385 | " result == maxcount + 1 (100) when many matches |
| 9386 | let result = searchcount(#{recompute: 0}) |
| 9387 | |
| 9388 | " Below returns correct result (recompute defaults |
| 9389 | " to 1) |
| 9390 | let result = searchcount() |
| 9391 | < |
Bram Moolenaar | b529cfb | 2022-07-25 15:42:07 +0100 | [diff] [blame] | 9392 | The function is useful to add the count to 'statusline': > |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9393 | function! LastSearchCount() abort |
| 9394 | let result = searchcount(#{recompute: 0}) |
| 9395 | if empty(result) |
| 9396 | return '' |
| 9397 | endif |
| 9398 | if result.incomplete ==# 1 " timed out |
| 9399 | return printf(' /%s [?/??]', @/) |
| 9400 | elseif result.incomplete ==# 2 " max count exceeded |
| 9401 | if result.total > result.maxcount && |
| 9402 | \ result.current > result.maxcount |
| 9403 | return printf(' /%s [>%d/>%d]', @/, |
| 9404 | \ result.current, result.total) |
| 9405 | elseif result.total > result.maxcount |
| 9406 | return printf(' /%s [%d/>%d]', @/, |
| 9407 | \ result.current, result.total) |
| 9408 | endif |
| 9409 | endif |
| 9410 | return printf(' /%s [%d/%d]', @/, |
| 9411 | \ result.current, result.total) |
| 9412 | endfunction |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 9413 | let &statusline ..= '%{LastSearchCount()}' |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9414 | |
| 9415 | " Or if you want to show the count only when |
| 9416 | " 'hlsearch' was on |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 9417 | " let &statusline ..= |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9418 | " \ '%{v:hlsearch ? LastSearchCount() : ""}' |
| 9419 | < |
| 9420 | You can also update the search count, which can be useful in a |
| 9421 | |CursorMoved| or |CursorMovedI| autocommand: > |
| 9422 | |
| 9423 | autocmd CursorMoved,CursorMovedI * |
| 9424 | \ let s:searchcount_timer = timer_start( |
| 9425 | \ 200, function('s:update_searchcount')) |
| 9426 | function! s:update_searchcount(timer) abort |
| 9427 | if a:timer ==# s:searchcount_timer |
| 9428 | call searchcount(#{ |
| 9429 | \ recompute: 1, maxcount: 0, timeout: 100}) |
| 9430 | redrawstatus |
| 9431 | endif |
| 9432 | endfunction |
| 9433 | < |
| 9434 | This can also be used to count matched texts with specified |
| 9435 | pattern in the current buffer using "pattern": > |
| 9436 | |
| 9437 | " Count '\<foo\>' in this buffer |
| 9438 | " (Note that it also updates search count) |
| 9439 | let result = searchcount(#{pattern: '\<foo\>'}) |
| 9440 | |
| 9441 | " To restore old search count by old pattern, |
| 9442 | " search again |
| 9443 | call searchcount() |
| 9444 | < |
| 9445 | {options} must be a |Dictionary|. It can contain: |
| 9446 | key type meaning ~ |
| 9447 | recompute |Boolean| if |TRUE|, recompute the count |
| 9448 | like |n| or |N| was executed. |
| 9449 | otherwise returns the last |
| 9450 | computed result (when |n| or |
| 9451 | |N| was used when "S" is not |
| 9452 | in 'shortmess', or this |
| 9453 | function was called). |
| 9454 | (default: |TRUE|) |
| 9455 | pattern |String| recompute if this was given |
| 9456 | and different with |@/|. |
| 9457 | this works as same as the |
| 9458 | below command is executed |
| 9459 | before calling this function > |
| 9460 | let @/ = pattern |
| 9461 | < (default: |@/|) |
| 9462 | timeout |Number| 0 or negative number is no |
| 9463 | timeout. timeout milliseconds |
| 9464 | for recomputing the result |
| 9465 | (default: 0) |
| 9466 | maxcount |Number| 0 or negative number is no |
| 9467 | limit. max count of matched |
| 9468 | text while recomputing the |
| 9469 | result. if search exceeded |
| 9470 | total count, "total" value |
| 9471 | becomes `maxcount + 1` |
| 9472 | (default: 99) |
| 9473 | pos |List| `[lnum, col, off]` value |
| 9474 | when recomputing the result. |
| 9475 | this changes "current" result |
| 9476 | value. see |cursor()|, |
| 9477 | |getpos()| |
| 9478 | (default: cursor's position) |
| 9479 | |
| 9480 | Can also be used as a |method|: > |
| 9481 | GetSearchOpts()->searchcount() |
| 9482 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9483 | Return type: dict<number> |
| 9484 | |
| 9485 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9486 | searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()* |
| 9487 | Search for the declaration of {name}. |
| 9488 | |
| 9489 | With a non-zero {global} argument it works like |gD|, find |
| 9490 | first match in the file. Otherwise it works like |gd|, find |
| 9491 | first match in the function. |
| 9492 | |
| 9493 | With a non-zero {thisblock} argument matches in a {} block |
| 9494 | that ends before the cursor position are ignored. Avoids |
| 9495 | finding variable declarations only valid in another scope. |
| 9496 | |
| 9497 | Moves the cursor to the found match. |
| 9498 | Returns zero for success, non-zero for failure. |
| 9499 | Example: > |
| 9500 | if searchdecl('myvar') == 0 |
| 9501 | echo getline('.') |
| 9502 | endif |
| 9503 | < |
| 9504 | Can also be used as a |method|: > |
| 9505 | GetName()->searchdecl() |
| 9506 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9507 | Return type: |Number| |
| 9508 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9509 | *searchpair()* |
| 9510 | searchpair({start}, {middle}, {end} [, {flags} [, {skip} |
| 9511 | [, {stopline} [, {timeout}]]]]) |
| 9512 | Search for the match of a nested start-end pair. This can be |
| 9513 | used to find the "endif" that matches an "if", while other |
| 9514 | if/endif pairs in between are ignored. |
| 9515 | The search starts at the cursor. The default is to search |
| 9516 | forward, include 'b' in {flags} to search backward. |
| 9517 | If a match is found, the cursor is positioned at it and the |
| 9518 | line number is returned. If no match is found 0 or -1 is |
| 9519 | returned and the cursor doesn't move. No error message is |
| 9520 | given. |
| 9521 | |
| 9522 | {start}, {middle} and {end} are patterns, see |pattern|. They |
| 9523 | must not contain \( \) pairs. Use of \%( \) is allowed. When |
| 9524 | {middle} is not empty, it is found when searching from either |
| 9525 | direction, but only when not in a nested start-end pair. A |
| 9526 | typical use is: > |
| 9527 | searchpair('\<if\>', '\<else\>', '\<endif\>') |
| 9528 | < By leaving {middle} empty the "else" is skipped. |
| 9529 | |
| 9530 | {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with |
| 9531 | |search()|. Additionally: |
| 9532 | 'r' Repeat until no more matches found; will find the |
| 9533 | outer pair. Implies the 'W' flag. |
| 9534 | 'm' Return number of matches instead of line number with |
| 9535 | the match; will be > 1 when 'r' is used. |
| 9536 | Note: it's nearly always a good idea to use the 'W' flag, to |
| 9537 | avoid wrapping around the end of the file. |
| 9538 | |
| 9539 | When a match for {start}, {middle} or {end} is found, the |
| 9540 | {skip} expression is evaluated with the cursor positioned on |
| 9541 | the start of the match. It should return non-zero if this |
| 9542 | match is to be skipped. E.g., because it is inside a comment |
| 9543 | or a string. |
| 9544 | When {skip} is omitted or empty, every match is accepted. |
| 9545 | When evaluating {skip} causes an error the search is aborted |
| 9546 | and -1 returned. |
| 9547 | {skip} can be a string, a lambda, a funcref or a partial. |
| 9548 | Anything else makes the function fail. |
| 9549 | In a `:def` function when the {skip} argument is a string |
| 9550 | constant it is compiled into instructions. |
| 9551 | |
| 9552 | For {stopline} and {timeout} see |search()|. |
| 9553 | |
| 9554 | The value of 'ignorecase' is used. 'magic' is ignored, the |
| 9555 | patterns are used like it's on. |
| 9556 | |
| 9557 | The search starts exactly at the cursor. A match with |
| 9558 | {start}, {middle} or {end} at the next character, in the |
| 9559 | direction of searching, is the first one found. Example: > |
| 9560 | if 1 |
| 9561 | if 2 |
| 9562 | endif 2 |
| 9563 | endif 1 |
| 9564 | < When starting at the "if 2", with the cursor on the "i", and |
| 9565 | searching forwards, the "endif 2" is found. When starting on |
| 9566 | the character just before the "if 2", the "endif 1" will be |
| 9567 | found. That's because the "if 2" will be found first, and |
| 9568 | then this is considered to be a nested if/endif from "if 2" to |
| 9569 | "endif 2". |
| 9570 | When searching backwards and {end} is more than one character, |
| 9571 | it may be useful to put "\zs" at the end of the pattern, so |
| 9572 | that when the cursor is inside a match with the end it finds |
| 9573 | the matching start. |
| 9574 | |
| 9575 | Example, to find the "endif" command in a Vim script: > |
| 9576 | |
| 9577 | :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W', |
| 9578 | \ 'getline(".") =~ "^\\s*\""') |
| 9579 | |
| 9580 | < The cursor must be at or after the "if" for which a match is |
| 9581 | to be found. Note that single-quote strings are used to avoid |
| 9582 | having to double the backslashes. The skip expression only |
| 9583 | catches comments at the start of a line, not after a command. |
| 9584 | Also, a word "en" or "if" halfway a line is considered a |
| 9585 | match. |
| 9586 | Another example, to search for the matching "{" of a "}": > |
| 9587 | |
| 9588 | :echo searchpair('{', '', '}', 'bW') |
| 9589 | |
| 9590 | < This works when the cursor is at or before the "}" for which a |
| 9591 | match is to be found. To reject matches that syntax |
| 9592 | highlighting recognized as strings: > |
| 9593 | |
| 9594 | :echo searchpair('{', '', '}', 'bW', |
| 9595 | \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"') |
| 9596 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9597 | Return type: |Number| |
| 9598 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9599 | *searchpairpos()* |
| 9600 | searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} |
| 9601 | [, {stopline} [, {timeout}]]]]) |
| 9602 | Same as |searchpair()|, but returns a |List| with the line and |
| 9603 | column position of the match. The first element of the |List| |
| 9604 | is the line number and the second element is the byte index of |
| 9605 | the column position of the match. If no match is found, |
| 9606 | returns [0, 0]. > |
| 9607 | |
| 9608 | :let [lnum,col] = searchpairpos('{', '', '}', 'n') |
| 9609 | < |
| 9610 | See |match-parens| for a bigger and more useful example. |
| 9611 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9612 | Return type: list<number> |
| 9613 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9614 | *searchpos()* |
| 9615 | searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) |
| 9616 | Same as |search()|, but returns a |List| with the line and |
| 9617 | column position of the match. The first element of the |List| |
| 9618 | is the line number and the second element is the byte index of |
| 9619 | the column position of the match. If no match is found, |
| 9620 | returns [0, 0]. |
| 9621 | Example: > |
| 9622 | :let [lnum, col] = searchpos('mypattern', 'n') |
| 9623 | |
| 9624 | < When the 'p' flag is given then there is an extra item with |
| 9625 | the sub-pattern match number |search()-sub-match|. Example: > |
| 9626 | :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np') |
| 9627 | < In this example "submatch" is 2 when a lowercase letter is |
| 9628 | found |/\l|, 3 when an uppercase letter is found |/\u|. |
| 9629 | |
| 9630 | Can also be used as a |method|: > |
| 9631 | GetPattern()->searchpos() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9632 | < |
| 9633 | Return type: list<number> |
| 9634 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9635 | |
| 9636 | server2client({clientid}, {string}) *server2client()* |
| 9637 | Send a reply string to {clientid}. The most recent {clientid} |
| 9638 | that sent a string can be retrieved with expand("<client>"). |
| 9639 | {only available when compiled with the |+clientserver| feature} |
| 9640 | Returns zero for success, -1 for failure. |
| 9641 | Note: |
| 9642 | This id has to be stored before the next command can be |
| 9643 | received. I.e. before returning from the received command and |
| 9644 | before calling any commands that waits for input. |
| 9645 | See also |clientserver|. |
| 9646 | Example: > |
| 9647 | :echo server2client(expand("<client>"), "HELLO") |
| 9648 | |
| 9649 | < Can also be used as a |method|: > |
| 9650 | GetClientId()->server2client(string) |
| 9651 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9652 | Return type: |Number| |
| 9653 | |
| 9654 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9655 | serverlist() *serverlist()* |
| 9656 | Return a list of available server names, one per line. |
| 9657 | When there are no servers or the information is not available |
| 9658 | an empty string is returned. See also |clientserver|. |
| 9659 | {only available when compiled with the |+clientserver| feature} |
| 9660 | Example: > |
| 9661 | :echo serverlist() |
| 9662 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9663 | Return type: |String| |
| 9664 | |
| 9665 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9666 | setbufline({buf}, {lnum}, {text}) *setbufline()* |
| 9667 | Set line {lnum} to {text} in buffer {buf}. This works like |
| 9668 | |setline()| for the specified buffer. |
| 9669 | |
| 9670 | This function works only for loaded buffers. First call |
| 9671 | |bufload()| if needed. |
| 9672 | |
| 9673 | To insert lines use |appendbufline()|. |
| 9674 | Any text properties in {lnum} are cleared. |
| 9675 | |
Bram Moolenaar | cd9c8d4 | 2022-11-05 23:46:43 +0000 | [diff] [blame] | 9676 | {text} can be a string to set one line, or a List of strings |
| 9677 | to set multiple lines. If the List extends below the last |
| 9678 | line then those lines are added. If the List is empty then |
| 9679 | nothing is changed and zero is returned. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9680 | |
| 9681 | For the use of {buf}, see |bufname()| above. |
| 9682 | |
| 9683 | {lnum} is used like with |setline()|. |
| 9684 | Use "$" to refer to the last line in buffer {buf}. |
| 9685 | When {lnum} is just below the last line the {text} will be |
| 9686 | added below the last line. |
| 9687 | |
| 9688 | When {buf} is not a valid buffer, the buffer is not loaded or |
| 9689 | {lnum} is not valid then 1 is returned. In |Vim9| script an |
| 9690 | error is given. |
| 9691 | On success 0 is returned. |
| 9692 | |
| 9693 | Can also be used as a |method|, the base is passed as the |
| 9694 | third argument: > |
| 9695 | GetText()->setbufline(buf, lnum) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9696 | < |
| 9697 | Return type: |Number| |
| 9698 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9699 | |
| 9700 | setbufvar({buf}, {varname}, {val}) *setbufvar()* |
| 9701 | Set option or local variable {varname} in buffer {buf} to |
| 9702 | {val}. |
| 9703 | This also works for a global or local window option, but it |
| 9704 | doesn't work for a global or local window variable. |
| 9705 | For a local window option the global value is unchanged. |
| 9706 | For the use of {buf}, see |bufname()| above. |
| 9707 | The {varname} argument is a string. |
| 9708 | Note that the variable name without "b:" must be used. |
| 9709 | Examples: > |
| 9710 | :call setbufvar(1, "&mod", 1) |
| 9711 | :call setbufvar("todo", "myvar", "foobar") |
| 9712 | < This function is not available in the |sandbox|. |
| 9713 | |
| 9714 | Can also be used as a |method|, the base is passed as the |
| 9715 | third argument: > |
| 9716 | GetValue()->setbufvar(buf, varname) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9717 | < |
| 9718 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9719 | |
| 9720 | |
| 9721 | setcellwidths({list}) *setcellwidths()* |
| 9722 | Specify overrides for cell widths of character ranges. This |
Bram Moolenaar | b59ae59 | 2022-11-23 23:46:31 +0000 | [diff] [blame] | 9723 | tells Vim how wide characters are when displayed in the |
| 9724 | terminal, counted in screen cells. The values override |
| 9725 | 'ambiwidth'. Example: > |
| 9726 | call setcellwidths([ |
Bram Moolenaar | 938ae28 | 2023-02-20 20:44:55 +0000 | [diff] [blame] | 9727 | \ [0x111, 0x111, 1], |
Bram Moolenaar | b59ae59 | 2022-11-23 23:46:31 +0000 | [diff] [blame] | 9728 | \ [0x2194, 0x2199, 2], |
| 9729 | \ ]) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9730 | |
Bram Moolenaar | b59ae59 | 2022-11-23 23:46:31 +0000 | [diff] [blame] | 9731 | < The {list} argument is a List of Lists with each three |
| 9732 | numbers: [{low}, {high}, {width}]. *E1109* *E1110* |
| 9733 | {low} and {high} can be the same, in which case this refers to |
| 9734 | one character. Otherwise it is the range of characters from |
| 9735 | {low} to {high} (inclusive). *E1111* *E1114* |
K.Takata | 7193323 | 2023-01-20 16:00:55 +0000 | [diff] [blame] | 9736 | Only characters with value 0x80 and higher can be used. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9737 | |
Bram Moolenaar | b59ae59 | 2022-11-23 23:46:31 +0000 | [diff] [blame] | 9738 | {width} must be either 1 or 2, indicating the character width |
| 9739 | in screen cells. *E1112* |
| 9740 | An error is given if the argument is invalid, also when a |
Bram Moolenaar | 938ae28 | 2023-02-20 20:44:55 +0000 | [diff] [blame] | 9741 | range overlaps with another. *E1113* |
Bram Moolenaar | b59ae59 | 2022-11-23 23:46:31 +0000 | [diff] [blame] | 9742 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9743 | If the new value causes 'fillchars' or 'listchars' to become |
| 9744 | invalid it is rejected and an error is given. |
| 9745 | |
Bram Moolenaar | b59ae59 | 2022-11-23 23:46:31 +0000 | [diff] [blame] | 9746 | To clear the overrides pass an empty {list}: > |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9747 | setcellwidths([]); |
Bram Moolenaar | b59ae59 | 2022-11-23 23:46:31 +0000 | [diff] [blame] | 9748 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9749 | < You can use the script $VIMRUNTIME/tools/emoji_list.vim to see |
Bram Moolenaar | b59ae59 | 2022-11-23 23:46:31 +0000 | [diff] [blame] | 9750 | the effect for known emoji characters. Move the cursor |
| 9751 | through the text to check if the cell widths of your terminal |
| 9752 | match with what Vim knows about each emoji. If it doesn't |
| 9753 | look right you need to adjust the {list} argument. |
| 9754 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9755 | Return type: |Number| |
| 9756 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9757 | |
| 9758 | setcharpos({expr}, {list}) *setcharpos()* |
| 9759 | Same as |setpos()| but uses the specified column number as the |
| 9760 | character index instead of the byte index in the line. |
| 9761 | |
| 9762 | Example: |
| 9763 | With the text "여보세요" in line 8: > |
| 9764 | call setcharpos('.', [0, 8, 4, 0]) |
| 9765 | < positions the cursor on the fourth character '요'. > |
| 9766 | call setpos('.', [0, 8, 4, 0]) |
| 9767 | < positions the cursor on the second character '보'. |
| 9768 | |
| 9769 | Can also be used as a |method|: > |
| 9770 | GetPosition()->setcharpos('.') |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9771 | < |
| 9772 | Return type: |Number| |
| 9773 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9774 | |
| 9775 | setcharsearch({dict}) *setcharsearch()* |
| 9776 | Set the current character search information to {dict}, |
| 9777 | which contains one or more of the following entries: |
| 9778 | |
| 9779 | char character which will be used for a subsequent |
| 9780 | |,| or |;| command; an empty string clears the |
| 9781 | character search |
| 9782 | forward direction of character search; 1 for forward, |
| 9783 | 0 for backward |
| 9784 | until type of character search; 1 for a |t| or |T| |
| 9785 | character search, 0 for an |f| or |F| |
| 9786 | character search |
| 9787 | |
| 9788 | This can be useful to save/restore a user's character search |
| 9789 | from a script: > |
| 9790 | :let prevsearch = getcharsearch() |
| 9791 | :" Perform a command which clobbers user's search |
| 9792 | :call setcharsearch(prevsearch) |
| 9793 | < Also see |getcharsearch()|. |
| 9794 | |
| 9795 | Can also be used as a |method|: > |
| 9796 | SavedSearch()->setcharsearch() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9797 | < |
| 9798 | Return type: dict<any> |
| 9799 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9800 | |
Shougo Matsushita | 07ea5f1 | 2022-08-27 12:22:25 +0100 | [diff] [blame] | 9801 | setcmdline({str} [, {pos}]) *setcmdline()* |
| 9802 | Set the command line to {str} and set the cursor position to |
| 9803 | {pos}. |
| 9804 | If {pos} is omitted, the cursor is positioned after the text. |
| 9805 | Returns 0 when successful, 1 when not editing the command |
| 9806 | line. |
| 9807 | |
| 9808 | Can also be used as a |method|: > |
| 9809 | GetText()->setcmdline() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9810 | < |
| 9811 | Return type: |Number| |
| 9812 | |
Shougo Matsushita | 07ea5f1 | 2022-08-27 12:22:25 +0100 | [diff] [blame] | 9813 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9814 | setcmdpos({pos}) *setcmdpos()* |
| 9815 | Set the cursor position in the command line to byte position |
| 9816 | {pos}. The first position is 1. |
| 9817 | Use |getcmdpos()| to obtain the current position. |
| 9818 | Only works while editing the command line, thus you must use |
| 9819 | |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For |
| 9820 | |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is |
| 9821 | set after the command line is set to the expression. For |
| 9822 | |c_CTRL-R_=| it is set after evaluating the expression but |
| 9823 | before inserting the resulting text. |
| 9824 | When the number is too big the cursor is put at the end of the |
| 9825 | line. A number smaller than one has undefined results. |
Shougo Matsushita | 07ea5f1 | 2022-08-27 12:22:25 +0100 | [diff] [blame] | 9826 | Returns 0 when successful, 1 when not editing the command |
| 9827 | line. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9828 | |
| 9829 | Can also be used as a |method|: > |
| 9830 | GetPos()->setcmdpos() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9831 | < |
| 9832 | Return type: |Number| |
| 9833 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9834 | |
| 9835 | setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()* |
| 9836 | setcursorcharpos({list}) |
| 9837 | Same as |cursor()| but uses the specified column number as the |
| 9838 | character index instead of the byte index in the line. |
| 9839 | |
| 9840 | Example: |
| 9841 | With the text "여보세요" in line 4: > |
| 9842 | call setcursorcharpos(4, 3) |
| 9843 | < positions the cursor on the third character '세'. > |
| 9844 | call cursor(4, 3) |
| 9845 | < positions the cursor on the first character '여'. |
| 9846 | |
| 9847 | Can also be used as a |method|: > |
| 9848 | GetCursorPos()->setcursorcharpos() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9849 | < |
Christian Brabandt | 17ad852 | 2025-05-09 00:03:20 +0200 | [diff] [blame] | 9850 | Returns 0 when the position could be set, -1 otherwise. |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9851 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9852 | |
| 9853 | |
| 9854 | setenv({name}, {val}) *setenv()* |
| 9855 | Set environment variable {name} to {val}. Example: > |
| 9856 | call setenv('HOME', '/home/myhome') |
| 9857 | |
| 9858 | < When {val} is |v:null| the environment variable is deleted. |
| 9859 | See also |expr-env|. |
| 9860 | |
| 9861 | Can also be used as a |method|, the base is passed as the |
| 9862 | second argument: > |
| 9863 | GetPath()->setenv('PATH') |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9864 | < |
| 9865 | Return type: |Number| |
| 9866 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9867 | |
| 9868 | setfperm({fname}, {mode}) *setfperm()* *chmod* |
| 9869 | Set the file permissions for {fname} to {mode}. |
| 9870 | {mode} must be a string with 9 characters. It is of the form |
| 9871 | "rwxrwxrwx", where each group of "rwx" flags represent, in |
| 9872 | turn, the permissions of the owner of the file, the group the |
| 9873 | file belongs to, and other users. A '-' character means the |
| 9874 | permission is off, any other character means on. Multi-byte |
| 9875 | characters are not supported. |
| 9876 | |
| 9877 | For example "rw-r-----" means read-write for the user, |
| 9878 | readable by the group, not accessible by others. "xx-x-----" |
| 9879 | would do the same thing. |
| 9880 | |
| 9881 | Returns non-zero for success, zero for failure. |
| 9882 | |
| 9883 | Can also be used as a |method|: > |
| 9884 | GetFilename()->setfperm(mode) |
| 9885 | < |
| 9886 | To read permissions see |getfperm()|. |
| 9887 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9888 | Return type: |Number| |
| 9889 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9890 | |
| 9891 | setline({lnum}, {text}) *setline()* |
| 9892 | Set line {lnum} of the current buffer to {text}. To insert |
| 9893 | lines use |append()|. To set lines in another buffer use |
Christian Brabandt | 946f61c | 2024-06-17 13:17:58 +0200 | [diff] [blame] | 9894 | |setbufline()|. |
h-east | 52e7cc2 | 2024-07-28 17:03:29 +0200 | [diff] [blame] | 9895 | Any text properties in {lnum} are cleared. See |
| 9896 | |text-prop-cleared| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9897 | |
| 9898 | {lnum} is used like with |getline()|. |
| 9899 | When {lnum} is just below the last line the {text} will be |
| 9900 | added below the last line. |
| 9901 | {text} can be any type or a List of any type, each item is |
Bram Moolenaar | cd9c8d4 | 2022-11-05 23:46:43 +0000 | [diff] [blame] | 9902 | converted to a String. When {text} is an empty List then |
| 9903 | nothing is changed and FALSE is returned. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9904 | |
| 9905 | If this succeeds, FALSE is returned. If this fails (most likely |
| 9906 | because {lnum} is invalid) TRUE is returned. |
| 9907 | In |Vim9| script an error is given if {lnum} is invalid. |
| 9908 | |
| 9909 | Example: > |
| 9910 | :call setline(5, strftime("%c")) |
| 9911 | |
| 9912 | < When {text} is a |List| then line {lnum} and following lines |
| 9913 | will be set to the items in the list. Example: > |
| 9914 | :call setline(5, ['aaa', 'bbb', 'ccc']) |
| 9915 | < This is equivalent to: > |
| 9916 | :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']] |
| 9917 | : call setline(n, l) |
| 9918 | :endfor |
| 9919 | |
| 9920 | < Note: The '[ and '] marks are not set. |
| 9921 | |
| 9922 | Can also be used as a |method|, the base is passed as the |
| 9923 | second argument: > |
| 9924 | GetText()->setline(lnum) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9925 | < |
| 9926 | Return type: |Number| |
| 9927 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9928 | |
| 9929 | setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()* |
| 9930 | Create or replace or add to the location list for window {nr}. |
| 9931 | {nr} can be the window number or the |window-ID|. |
| 9932 | When {nr} is zero the current window is used. |
| 9933 | |
| 9934 | For a location list window, the displayed location list is |
| 9935 | modified. For an invalid window number {nr}, -1 is returned. |
| 9936 | Otherwise, same as |setqflist()|. |
| 9937 | Also see |location-list|. |
| 9938 | |
| 9939 | For {action} see |setqflist-action|. |
| 9940 | |
| 9941 | If the optional {what} dictionary argument is supplied, then |
| 9942 | only the items listed in {what} are set. Refer to |setqflist()| |
| 9943 | for the list of supported keys in {what}. |
| 9944 | |
| 9945 | Can also be used as a |method|, the base is passed as the |
| 9946 | second argument: > |
| 9947 | GetLoclist()->setloclist(winnr) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9948 | < |
| 9949 | Return type: |Number| |
| 9950 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9951 | |
| 9952 | setmatches({list} [, {win}]) *setmatches()* |
| 9953 | Restores a list of matches saved by |getmatches()| for the |
| 9954 | current window. Returns 0 if successful, otherwise -1. All |
| 9955 | current matches are cleared before the list is restored. See |
| 9956 | example for |getmatches()|. |
| 9957 | If {win} is specified, use the window with this number or |
| 9958 | window ID instead of the current window. |
| 9959 | |
| 9960 | Can also be used as a |method|: > |
| 9961 | GetMatches()->setmatches() |
| 9962 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 9963 | Return type: |Number| |
| 9964 | |
| 9965 | |
| 9966 | setpos({expr}, {list}) *setpos()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 9967 | Set the position for String {expr}. Possible values: |
| 9968 | . the cursor |
| 9969 | 'x mark x |
| 9970 | |
| 9971 | {list} must be a |List| with four or five numbers: |
| 9972 | [bufnum, lnum, col, off] |
| 9973 | [bufnum, lnum, col, off, curswant] |
| 9974 | |
| 9975 | "bufnum" is the buffer number. Zero can be used for the |
| 9976 | current buffer. When setting an uppercase mark "bufnum" is |
| 9977 | used for the mark position. For other marks it specifies the |
| 9978 | buffer to set the mark in. You can use the |bufnr()| function |
| 9979 | to turn a file name into a buffer number. |
| 9980 | For setting the cursor and the ' mark "bufnum" is ignored, |
| 9981 | since these are associated with a window, not a buffer. |
| 9982 | Does not change the jumplist. |
| 9983 | |
| 9984 | "lnum" and "col" are the position in the buffer. The first |
| 9985 | column is 1. Use a zero "lnum" to delete a mark. If "col" is |
| 9986 | smaller than 1 then 1 is used. To use the character count |
| 9987 | instead of the byte count, use |setcharpos()|. |
| 9988 | |
| 9989 | The "off" number is only used when 'virtualedit' is set. Then |
| 9990 | it is the offset in screen columns from the start of the |
| 9991 | character. E.g., a position within a <Tab> or after the last |
| 9992 | character. |
| 9993 | |
| 9994 | The "curswant" number is only used when setting the cursor |
| 9995 | position. It sets the preferred column for when moving the |
| 9996 | cursor vertically. When the "curswant" number is missing the |
| 9997 | preferred column is not set. When it is present and setting a |
| 9998 | mark position it is not used. |
| 9999 | |
| 10000 | Note that for '< and '> changing the line number may result in |
| 10001 | the marks to be effectively be swapped, so that '< is always |
| 10002 | before '>. |
| 10003 | |
| 10004 | Returns 0 when the position could be set, -1 otherwise. |
| 10005 | An error message is given if {expr} is invalid. |
| 10006 | |
| 10007 | Also see |setcharpos()|, |getpos()| and |getcurpos()|. |
| 10008 | |
| 10009 | This does not restore the preferred column for moving |
| 10010 | vertically; if you set the cursor position with this, |j| and |
| 10011 | |k| motions will jump to previous columns! Use |cursor()| to |
| 10012 | also set the preferred column. Also see the "curswant" key in |
| 10013 | |winrestview()|. |
| 10014 | |
| 10015 | Can also be used as a |method|: > |
| 10016 | GetPosition()->setpos('.') |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10017 | < |
| 10018 | Return type: |Number| |
| 10019 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10020 | |
| 10021 | setqflist({list} [, {action} [, {what}]]) *setqflist()* |
| 10022 | Create or replace or add to the quickfix list. |
| 10023 | |
| 10024 | If the optional {what} dictionary argument is supplied, then |
| 10025 | only the items listed in {what} are set. The first {list} |
| 10026 | argument is ignored. See below for the supported items in |
| 10027 | {what}. |
| 10028 | *setqflist-what* |
| 10029 | When {what} is not present, the items in {list} are used. Each |
| 10030 | item must be a dictionary. Non-dictionary items in {list} are |
| 10031 | ignored. Each dictionary item can contain the following |
| 10032 | entries: |
| 10033 | |
| 10034 | bufnr buffer number; must be the number of a valid |
| 10035 | buffer |
| 10036 | filename name of a file; only used when "bufnr" is not |
| 10037 | present or it is invalid. |
| 10038 | module name of a module; if given it will be used in |
| 10039 | quickfix error window instead of the filename. |
| 10040 | lnum line number in the file |
Bram Moolenaar | a2baa73 | 2022-02-04 16:09:54 +0000 | [diff] [blame] | 10041 | end_lnum end of lines, if the item spans multiple lines |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10042 | pattern search pattern used to locate the error |
| 10043 | col column number |
| 10044 | vcol when non-zero: "col" is visual column |
| 10045 | when zero: "col" is byte index |
Bram Moolenaar | a2baa73 | 2022-02-04 16:09:54 +0000 | [diff] [blame] | 10046 | end_col end column, if the item spans multiple columns |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10047 | nr error number |
| 10048 | text description of the error |
| 10049 | type single-character error type, 'E', 'W', etc. |
| 10050 | valid recognized error message |
Tom Praschan | ca6ac99 | 2023-08-11 23:26:12 +0200 | [diff] [blame] | 10051 | user_data custom data associated with the item, can be |
| 10052 | any type. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10053 | |
| 10054 | The "col", "vcol", "nr", "type" and "text" entries are |
| 10055 | optional. Either "lnum" or "pattern" entry can be used to |
| 10056 | locate a matching error line. |
| 10057 | If the "filename" and "bufnr" entries are not present or |
| 10058 | neither the "lnum" or "pattern" entries are present, then the |
| 10059 | item will not be handled as an error line. |
| 10060 | If both "pattern" and "lnum" are present then "pattern" will |
| 10061 | be used. |
| 10062 | If the "valid" entry is not supplied, then the valid flag is |
| 10063 | set when "bufnr" is a valid buffer or "filename" exists. |
| 10064 | If you supply an empty {list}, the quickfix list will be |
| 10065 | cleared. |
| 10066 | Note that the list is not exactly the same as what |
| 10067 | |getqflist()| returns. |
| 10068 | |
| 10069 | {action} values: *setqflist-action* *E927* |
| 10070 | 'a' The items from {list} are added to the existing |
| 10071 | quickfix list. If there is no existing list, then a |
| 10072 | new list is created. |
| 10073 | |
| 10074 | 'r' The items from the current quickfix list are replaced |
| 10075 | with the items from {list}. This can also be used to |
| 10076 | clear the list: > |
| 10077 | :call setqflist([], 'r') |
| 10078 | < |
Jeremy Fleischman | 27fbf6e | 2024-10-14 20:46:27 +0200 | [diff] [blame] | 10079 | 'u' Like 'r', but tries to preserve the current selection |
| 10080 | in the quickfix list. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10081 | 'f' All the quickfix lists in the quickfix stack are |
| 10082 | freed. |
| 10083 | |
| 10084 | If {action} is not present or is set to ' ', then a new list |
| 10085 | is created. The new quickfix list is added after the current |
| 10086 | quickfix list in the stack and all the following lists are |
| 10087 | freed. To add a new quickfix list at the end of the stack, |
| 10088 | set "nr" in {what} to "$". |
| 10089 | |
| 10090 | The following items can be specified in dictionary {what}: |
| 10091 | context quickfix list context. See |quickfix-context| |
| 10092 | efm errorformat to use when parsing text from |
| 10093 | "lines". If this is not present, then the |
| 10094 | 'errorformat' option value is used. |
| 10095 | See |quickfix-parse| |
| 10096 | id quickfix list identifier |quickfix-ID| |
| 10097 | idx index of the current entry in the quickfix |
| 10098 | list specified by 'id' or 'nr'. If set to '$', |
| 10099 | then the last entry in the list is set as the |
| 10100 | current entry. See |quickfix-index| |
| 10101 | items list of quickfix entries. Same as the {list} |
| 10102 | argument. |
| 10103 | lines use 'errorformat' to parse a list of lines and |
| 10104 | add the resulting entries to the quickfix list |
| 10105 | {nr} or {id}. Only a |List| value is supported. |
| 10106 | See |quickfix-parse| |
| 10107 | nr list number in the quickfix stack; zero |
| 10108 | means the current quickfix list and "$" means |
| 10109 | the last quickfix list. |
| 10110 | quickfixtextfunc |
| 10111 | function to get the text to display in the |
| 10112 | quickfix window. The value can be the name of |
| 10113 | a function or a funcref or a lambda. Refer to |
| 10114 | |quickfix-window-function| for an explanation |
| 10115 | of how to write the function and an example. |
| 10116 | title quickfix list title text. See |quickfix-title| |
| 10117 | Unsupported keys in {what} are ignored. |
| 10118 | If the "nr" item is not present, then the current quickfix list |
| 10119 | is modified. When creating a new quickfix list, "nr" can be |
| 10120 | set to a value one greater than the quickfix stack size. |
| 10121 | When modifying a quickfix list, to guarantee that the correct |
| 10122 | list is modified, "id" should be used instead of "nr" to |
| 10123 | specify the list. |
| 10124 | |
| 10125 | Examples (See also |setqflist-examples|): > |
| 10126 | :call setqflist([], 'r', {'title': 'My search'}) |
| 10127 | :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'}) |
| 10128 | :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]}) |
| 10129 | < |
| 10130 | Returns zero for success, -1 for failure. |
| 10131 | |
| 10132 | This function can be used to create a quickfix list |
| 10133 | independent of the 'errorformat' setting. Use a command like |
| 10134 | `:cc 1` to jump to the first position. |
| 10135 | |
| 10136 | Can also be used as a |method|, the base is passed as the |
| 10137 | second argument: > |
| 10138 | GetErrorlist()->setqflist() |
| 10139 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10140 | Return type: |Number| |
| 10141 | |
| 10142 | |
| 10143 | setreg({regname}, {value} [, {options}]) *setreg()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10144 | Set the register {regname} to {value}. |
| 10145 | If {regname} is "" or "@", the unnamed register '"' is used. |
| 10146 | The {regname} argument is a string. In |Vim9-script| |
| 10147 | {regname} must be one character. |
| 10148 | |
| 10149 | {value} may be any value returned by |getreg()| or |
| 10150 | |getreginfo()|, including a |List| or |Dict|. |
| 10151 | If {options} contains "a" or {regname} is upper case, |
| 10152 | then the value is appended. |
| 10153 | |
| 10154 | {options} can also contain a register type specification: |
| 10155 | "c" or "v" |characterwise| mode |
| 10156 | "l" or "V" |linewise| mode |
| 10157 | "b" or "<CTRL-V>" |blockwise-visual| mode |
| 10158 | If a number immediately follows "b" or "<CTRL-V>" then this is |
| 10159 | used as the width of the selection - if it is not specified |
| 10160 | then the width of the block is set to the number of characters |
| 10161 | in the longest line (counting a <Tab> as 1 character). |
| 10162 | |
| 10163 | If {options} contains no register settings, then the default |
| 10164 | is to use character mode unless {value} ends in a <NL> for |
| 10165 | string {value} and linewise mode for list {value}. Blockwise |
| 10166 | mode is never selected automatically. |
| 10167 | Returns zero for success, non-zero for failure. |
| 10168 | |
| 10169 | *E883* |
| 10170 | Note: you may not use |List| containing more than one item to |
| 10171 | set search and expression registers. Lists containing no |
| 10172 | items act like empty strings. |
| 10173 | |
| 10174 | Examples: > |
| 10175 | :call setreg(v:register, @*) |
| 10176 | :call setreg('*', @%, 'ac') |
| 10177 | :call setreg('a', "1\n2\n3", 'b5') |
| 10178 | :call setreg('"', { 'points_to': 'a'}) |
| 10179 | |
| 10180 | < This example shows using the functions to save and restore a |
| 10181 | register: > |
| 10182 | :let var_a = getreginfo() |
| 10183 | :call setreg('a', var_a) |
| 10184 | < or: > |
| 10185 | :let var_a = getreg('a', 1, 1) |
| 10186 | :let var_amode = getregtype('a') |
| 10187 | .... |
| 10188 | :call setreg('a', var_a, var_amode) |
| 10189 | < Note: you may not reliably restore register value |
| 10190 | without using the third argument to |getreg()| as without it |
| 10191 | newlines are represented as newlines AND Nul bytes are |
| 10192 | represented as newlines as well, see |NL-used-for-Nul|. |
| 10193 | |
| 10194 | You can also change the type of a register by appending |
| 10195 | nothing: > |
| 10196 | :call setreg('a', '', 'al') |
| 10197 | |
| 10198 | < Can also be used as a |method|, the base is passed as the |
| 10199 | second argument: > |
| 10200 | GetText()->setreg('a') |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10201 | < |
| 10202 | Return type: |Number| |
| 10203 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10204 | |
| 10205 | settabvar({tabnr}, {varname}, {val}) *settabvar()* |
| 10206 | Set tab-local variable {varname} to {val} in tab page {tabnr}. |
| 10207 | |t:var| |
| 10208 | The {varname} argument is a string. |
| 10209 | Note that autocommands are blocked, side effects may not be |
| 10210 | triggered, e.g. when setting 'filetype'. |
| 10211 | Note that the variable name without "t:" must be used. |
| 10212 | Tabs are numbered starting with one. |
| 10213 | This function is not available in the |sandbox|. |
| 10214 | |
| 10215 | Can also be used as a |method|, the base is passed as the |
| 10216 | third argument: > |
| 10217 | GetValue()->settabvar(tab, name) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10218 | < |
| 10219 | Return type: |Number| |
| 10220 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10221 | |
| 10222 | settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()* |
| 10223 | Set option or local variable {varname} in window {winnr} to |
| 10224 | {val}. |
| 10225 | Tabs are numbered starting with one. For the current tabpage |
| 10226 | use |setwinvar()|. |
| 10227 | {winnr} can be the window number or the |window-ID|. |
| 10228 | When {winnr} is zero the current window is used. |
| 10229 | Note that autocommands are blocked, side effects may not be |
| 10230 | triggered, e.g. when setting 'filetype' or 'syntax'. |
| 10231 | This also works for a global or local buffer option, but it |
| 10232 | doesn't work for a global or local buffer variable. |
| 10233 | For a local buffer option the global value is unchanged. |
| 10234 | Note that the variable name without "w:" must be used. |
| 10235 | Examples: > |
| 10236 | :call settabwinvar(1, 1, "&list", 0) |
| 10237 | :call settabwinvar(3, 2, "myvar", "foobar") |
| 10238 | < This function is not available in the |sandbox|. |
| 10239 | |
| 10240 | Can also be used as a |method|, the base is passed as the |
| 10241 | fourth argument: > |
| 10242 | GetValue()->settabwinvar(tab, winnr, name) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10243 | < |
| 10244 | Return type: |Number| |
| 10245 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10246 | |
| 10247 | settagstack({nr}, {dict} [, {action}]) *settagstack()* |
| 10248 | Modify the tag stack of the window {nr} using {dict}. |
| 10249 | {nr} can be the window number or the |window-ID|. |
| 10250 | |
| 10251 | For a list of supported items in {dict}, refer to |
| 10252 | |gettagstack()|. "curidx" takes effect before changing the tag |
| 10253 | stack. |
| 10254 | *E962* |
| 10255 | How the tag stack is modified depends on the {action} |
| 10256 | argument: |
| 10257 | - If {action} is not present or is set to 'r', then the tag |
| 10258 | stack is replaced. |
| 10259 | - If {action} is set to 'a', then new entries from {dict} are |
| 10260 | pushed (added) onto the tag stack. |
| 10261 | - If {action} is set to 't', then all the entries from the |
| 10262 | current entry in the tag stack or "curidx" in {dict} are |
| 10263 | removed and then new entries are pushed to the stack. |
| 10264 | |
| 10265 | The current index is set to one after the length of the tag |
| 10266 | stack after the modification. |
| 10267 | |
| 10268 | Returns zero for success, -1 for failure. |
| 10269 | |
| 10270 | Examples (for more examples see |tagstack-examples|): |
| 10271 | Empty the tag stack of window 3: > |
| 10272 | call settagstack(3, {'items' : []}) |
| 10273 | |
| 10274 | < Save and restore the tag stack: > |
| 10275 | let stack = gettagstack(1003) |
| 10276 | " do something else |
| 10277 | call settagstack(1003, stack) |
| 10278 | unlet stack |
| 10279 | < |
| 10280 | Can also be used as a |method|, the base is passed as the |
| 10281 | second argument: > |
| 10282 | GetStack()->settagstack(winnr) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10283 | < |
| 10284 | Return type: |Number| |
| 10285 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10286 | |
| 10287 | setwinvar({winnr}, {varname}, {val}) *setwinvar()* |
| 10288 | Like |settabwinvar()| for the current tab page. |
| 10289 | Examples: > |
| 10290 | :call setwinvar(1, "&list", 0) |
| 10291 | :call setwinvar(2, "myvar", "foobar") |
| 10292 | |
| 10293 | < Can also be used as a |method|, the base is passed as the |
| 10294 | third argument: > |
| 10295 | GetValue()->setwinvar(winnr, name) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10296 | < |
| 10297 | Return type: |Number| |
| 10298 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10299 | |
| 10300 | sha256({string}) *sha256()* |
| 10301 | Returns a String with 64 hex characters, which is the SHA256 |
| 10302 | checksum of {string}. |
| 10303 | |
| 10304 | Can also be used as a |method|: > |
| 10305 | GetText()->sha256() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10306 | < |
| 10307 | Return type: |String| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10308 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10309 | {only available when compiled with the |+cryptv| feature} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10310 | |
| 10311 | shellescape({string} [, {special}]) *shellescape()* |
| 10312 | Escape {string} for use as a shell command argument. |
| 10313 | When the 'shell' contains powershell (MS-Windows) or pwsh |
Bram Moolenaar | 944697a | 2022-02-20 19:48:20 +0000 | [diff] [blame] | 10314 | (MS-Windows, Linux, and macOS) then it will enclose {string} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10315 | in single quotes and will double up all internal single |
| 10316 | quotes. |
| 10317 | On MS-Windows, when 'shellslash' is not set, it will enclose |
| 10318 | {string} in double quotes and double all double quotes within |
| 10319 | {string}. |
| 10320 | Otherwise it will enclose {string} in single quotes and |
| 10321 | replace all "'" with "'\''". |
| 10322 | |
Enno | 5faeb60 | 2024-05-15 21:54:19 +0200 | [diff] [blame] | 10323 | The {special} argument adds additional escaping of keywords |
| 10324 | used in Vim commands. When it is not omitted and a non-zero |
K.Takata | c0e038b | 2024-05-16 12:39:01 +0900 | [diff] [blame] | 10325 | number or a non-empty String (|non-zero-arg|), then special |
| 10326 | items such as "!", "%", "#" and "<cword>" (as listed in |
| 10327 | |expand()|) will be preceded by a backslash. |
Enno | 5faeb60 | 2024-05-15 21:54:19 +0200 | [diff] [blame] | 10328 | This backslash will be removed again by the |:!| command. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10329 | |
| 10330 | The "!" character will be escaped (again with a |non-zero-arg| |
| 10331 | {special}) when 'shell' contains "csh" in the tail. That is |
| 10332 | because for csh and tcsh "!" is used for history replacement |
| 10333 | even when inside single quotes. |
| 10334 | |
| 10335 | With a |non-zero-arg| {special} the <NL> character is also |
| 10336 | escaped. When 'shell' containing "csh" in the tail it's |
| 10337 | escaped a second time. |
| 10338 | |
| 10339 | The "\" character will be escaped when 'shell' contains "fish" |
| 10340 | in the tail. That is because for fish "\" is used as an escape |
| 10341 | character inside single quotes. |
| 10342 | |
| 10343 | Example of use with a |:!| command: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 10344 | :exe '!dir ' .. shellescape(expand('<cfile>'), 1) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10345 | < This results in a directory listing for the file under the |
| 10346 | cursor. Example of use with |system()|: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 10347 | :call system("chmod +w -- " .. shellescape(expand("%"))) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10348 | < See also |::S|. |
| 10349 | |
| 10350 | Can also be used as a |method|: > |
| 10351 | GetCommand()->shellescape() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10352 | < |
| 10353 | Return type: |String| |
| 10354 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10355 | |
| 10356 | shiftwidth([{col}]) *shiftwidth()* |
| 10357 | Returns the effective value of 'shiftwidth'. This is the |
| 10358 | 'shiftwidth' value unless it is zero, in which case it is the |
| 10359 | 'tabstop' value. This function was introduced with patch |
| 10360 | 7.3.694 in 2012, everybody should have it by now (however it |
| 10361 | did not allow for the optional {col} argument until 8.1.542). |
| 10362 | |
| 10363 | When there is one argument {col} this is used as column number |
| 10364 | for which to return the 'shiftwidth' value. This matters for the |
| 10365 | 'vartabstop' feature. If the 'vartabstop' setting is enabled and |
| 10366 | no {col} argument is given, column 1 will be assumed. |
| 10367 | |
| 10368 | Can also be used as a |method|: > |
| 10369 | GetColumn()->shiftwidth() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10370 | < |
| 10371 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10372 | |
| 10373 | sign_ functions are documented here: |sign-functions-details| |
| 10374 | |
| 10375 | |
| 10376 | simplify({filename}) *simplify()* |
| 10377 | Simplify the file name as much as possible without changing |
| 10378 | the meaning. Shortcuts (on MS-Windows) or symbolic links (on |
| 10379 | Unix) are not resolved. If the first path component in |
| 10380 | {filename} designates the current directory, this will be |
| 10381 | valid for the result as well. A trailing path separator is |
| 10382 | not removed either. On Unix "//path" is unchanged, but |
| 10383 | "///path" is simplified to "/path" (this follows the Posix |
| 10384 | standard). |
| 10385 | Example: > |
| 10386 | simplify("./dir/.././/file/") == "./file/" |
| 10387 | < Note: The combination "dir/.." is only removed if "dir" is |
| 10388 | a searchable directory or does not exist. On Unix, it is also |
| 10389 | removed when "dir" is a symbolic link within the same |
| 10390 | directory. In order to resolve all the involved symbolic |
| 10391 | links before simplifying the path name, use |resolve()|. |
| 10392 | |
| 10393 | Can also be used as a |method|: > |
| 10394 | GetName()->simplify() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10395 | < |
| 10396 | Return type: |String| |
| 10397 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10398 | |
| 10399 | sin({expr}) *sin()* |
| 10400 | Return the sine of {expr}, measured in radians, as a |Float|. |
| 10401 | {expr} must evaluate to a |Float| or a |Number|. |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 10402 | Returns 0.0 if {expr} is not a |Float| or a |Number|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10403 | Examples: > |
| 10404 | :echo sin(100) |
| 10405 | < -0.506366 > |
| 10406 | :echo sin(-4.01) |
| 10407 | < 0.763301 |
| 10408 | |
| 10409 | Can also be used as a |method|: > |
| 10410 | Compute()->sin() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10411 | < |
| 10412 | Return type: |Float| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10413 | |
| 10414 | |
| 10415 | sinh({expr}) *sinh()* |
| 10416 | Return the hyperbolic sine of {expr} as a |Float| in the range |
| 10417 | [-inf, inf]. |
| 10418 | {expr} must evaluate to a |Float| or a |Number|. |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 10419 | Returns 0.0 if {expr} is not a |Float| or a |Number|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10420 | Examples: > |
| 10421 | :echo sinh(0.5) |
| 10422 | < 0.521095 > |
| 10423 | :echo sinh(-0.9) |
| 10424 | < -1.026517 |
| 10425 | |
| 10426 | Can also be used as a |method|: > |
| 10427 | Compute()->sinh() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10428 | < |
| 10429 | Return type: |Float| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10430 | |
| 10431 | |
| 10432 | slice({expr}, {start} [, {end}]) *slice()* |
| 10433 | Similar to using a |slice| "expr[start : end]", but "end" is |
| 10434 | used exclusive. And for a string the indexes are used as |
| 10435 | character indexes instead of byte indexes, like in |
zeertzjq | ad38769 | 2024-03-23 08:23:48 +0100 | [diff] [blame] | 10436 | |vim9script|. Also, composing characters are treated as a |
| 10437 | part of the preceding base character. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10438 | When {end} is omitted the slice continues to the last item. |
| 10439 | When {end} is -1 the last item is omitted. |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 10440 | Returns an empty value if {start} or {end} are invalid. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10441 | |
| 10442 | Can also be used as a |method|: > |
| 10443 | GetList()->slice(offset) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10444 | < |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 10445 | Return type: list<{type}> or tuple<{type}> |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10446 | |
| 10447 | |
Bram Moolenaar | 2007dd4 | 2022-02-23 13:17:47 +0000 | [diff] [blame] | 10448 | sort({list} [, {how} [, {dict}]]) *sort()* *E702* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10449 | Sort the items in {list} in-place. Returns {list}. |
| 10450 | |
| 10451 | If you want a list to remain unmodified make a copy first: > |
| 10452 | :let sortedlist = sort(copy(mylist)) |
| 10453 | |
Bram Moolenaar | 2d8ed02 | 2022-05-21 13:08:16 +0100 | [diff] [blame] | 10454 | < When {how} is omitted or is a string, then sort() uses the |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10455 | string representation of each item to sort on. Numbers sort |
| 10456 | after Strings, |Lists| after Numbers. For sorting text in the |
| 10457 | current buffer use |:sort|. |
| 10458 | |
Bram Moolenaar | 2007dd4 | 2022-02-23 13:17:47 +0000 | [diff] [blame] | 10459 | When {how} is given and it is 'i' then case is ignored. |
| 10460 | In legacy script, for backwards compatibility, the value one |
| 10461 | can be used to ignore case. Zero means to not ignore case. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10462 | |
Bram Moolenaar | 2007dd4 | 2022-02-23 13:17:47 +0000 | [diff] [blame] | 10463 | When {how} is given and it is 'l' then the current collation |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10464 | locale is used for ordering. Implementation details: strcoll() |
| 10465 | is used to compare strings. See |:language| check or set the |
| 10466 | collation locale. |v:collate| can also be used to check the |
| 10467 | current locale. Sorting using the locale typically ignores |
| 10468 | case. Example: > |
| 10469 | " ö is sorted similarly to o with English locale. |
| 10470 | :language collate en_US.UTF8 |
| 10471 | :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l') |
| 10472 | < ['n', 'o', 'O', 'ö', 'p', 'z'] ~ |
| 10473 | > |
| 10474 | " ö is sorted after z with Swedish locale. |
| 10475 | :language collate sv_SE.UTF8 |
| 10476 | :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l') |
| 10477 | < ['n', 'o', 'O', 'p', 'z', 'ö'] ~ |
| 10478 | This does not work properly on Mac. |
| 10479 | |
Bram Moolenaar | 2007dd4 | 2022-02-23 13:17:47 +0000 | [diff] [blame] | 10480 | When {how} is given and it is 'n' then all items will be |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10481 | sorted numerical (Implementation detail: this uses the |
Bram Moolenaar | be19d78 | 2023-03-09 22:06:49 +0000 | [diff] [blame] | 10482 | strtod() function to parse numbers. Strings, Lists, Dicts and |
| 10483 | Funcrefs will be considered as being 0). Note that this won't |
| 10484 | sort a list of strings with numbers! |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10485 | |
Bram Moolenaar | 2007dd4 | 2022-02-23 13:17:47 +0000 | [diff] [blame] | 10486 | When {how} is given and it is 'N' then all items will be |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10487 | sorted numerical. This is like 'n' but a string containing |
| 10488 | digits will be used as the number they represent. |
| 10489 | |
Bram Moolenaar | 2007dd4 | 2022-02-23 13:17:47 +0000 | [diff] [blame] | 10490 | When {how} is given and it is 'f' then all items will be |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10491 | sorted numerical. All values must be a Number or a Float. |
| 10492 | |
Bram Moolenaar | 2007dd4 | 2022-02-23 13:17:47 +0000 | [diff] [blame] | 10493 | When {how} is a |Funcref| or a function name, this function |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10494 | is called to compare items. The function is invoked with two |
| 10495 | items as argument and must return zero if they are equal, 1 or |
| 10496 | bigger if the first one sorts after the second one, -1 or |
| 10497 | smaller if the first one sorts before the second one. |
| 10498 | |
| 10499 | {dict} is for functions with the "dict" attribute. It will be |
| 10500 | used to set the local variable "self". |Dictionary-function| |
| 10501 | |
| 10502 | The sort is stable, items which compare equal (as number or as |
| 10503 | string) will keep their relative position. E.g., when sorting |
| 10504 | on numbers, text strings will sort next to each other, in the |
| 10505 | same order as they were originally. |
| 10506 | |
| 10507 | Can also be used as a |method|: > |
| 10508 | mylist->sort() |
| 10509 | |
| 10510 | < Also see |uniq()|. |
| 10511 | |
| 10512 | Example: > |
| 10513 | func MyCompare(i1, i2) |
| 10514 | return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1 |
| 10515 | endfunc |
| 10516 | eval mylist->sort("MyCompare") |
| 10517 | < A shorter compare version for this specific simple case, which |
| 10518 | ignores overflow: > |
| 10519 | func MyCompare(i1, i2) |
| 10520 | return a:i1 - a:i2 |
| 10521 | endfunc |
| 10522 | < For a simple expression you can use a lambda: > |
| 10523 | eval mylist->sort({i1, i2 -> i1 - i2}) |
| 10524 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10525 | Return type: list<{type}> |
| 10526 | |
| 10527 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10528 | sound_clear() *sound_clear()* |
| 10529 | Stop playing all sounds. |
| 10530 | |
| 10531 | On some Linux systems you may need the libcanberra-pulse |
| 10532 | package, otherwise sound may not stop. |
| 10533 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10534 | Return type: |Number| |
| 10535 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10536 | {only available when compiled with the |+sound| feature} |
| 10537 | |
| 10538 | *sound_playevent()* |
| 10539 | sound_playevent({name} [, {callback}]) |
| 10540 | Play a sound identified by {name}. Which event names are |
| 10541 | supported depends on the system. Often the XDG sound names |
| 10542 | are used. On Ubuntu they may be found in |
| 10543 | /usr/share/sounds/freedesktop/stereo. Example: > |
| 10544 | call sound_playevent('bell') |
| 10545 | < On MS-Windows, {name} can be SystemAsterisk, SystemDefault, |
| 10546 | SystemExclamation, SystemExit, SystemHand, SystemQuestion, |
| 10547 | SystemStart, SystemWelcome, etc. |
Yee Cheng Chin | 4314e4f | 2022-10-08 13:50:05 +0100 | [diff] [blame] | 10548 | On macOS, {name} refers to files located in |
| 10549 | /System/Library/Sounds (e.g. "Tink"). It will also work for |
| 10550 | custom installed sounds in folders like ~/Library/Sounds. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10551 | |
| 10552 | When {callback} is specified it is invoked when the sound is |
| 10553 | finished. The first argument is the sound ID, the second |
| 10554 | argument is the status: |
| 10555 | 0 sound was played to the end |
| 10556 | 1 sound was interrupted |
| 10557 | 2 error occurred after sound started |
| 10558 | Example: > |
| 10559 | func Callback(id, status) |
| 10560 | echomsg "sound " .. a:id .. " finished with " .. a:status |
| 10561 | endfunc |
| 10562 | call sound_playevent('bell', 'Callback') |
| 10563 | |
| 10564 | < MS-Windows: {callback} doesn't work for this function. |
| 10565 | |
| 10566 | Returns the sound ID, which can be passed to `sound_stop()`. |
| 10567 | Returns zero if the sound could not be played. |
| 10568 | |
| 10569 | Can also be used as a |method|: > |
| 10570 | GetSoundName()->sound_playevent() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10571 | < |
| 10572 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10573 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10574 | {only available when compiled with the |+sound| feature} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10575 | |
| 10576 | *sound_playfile()* |
| 10577 | sound_playfile({path} [, {callback}]) |
| 10578 | Like `sound_playevent()` but play sound file {path}. {path} |
| 10579 | must be a full path. On Ubuntu you may find files to play |
| 10580 | with this command: > |
| 10581 | :!find /usr/share/sounds -type f | grep -v index.theme |
| 10582 | |
| 10583 | < Can also be used as a |method|: > |
| 10584 | GetSoundPath()->sound_playfile() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10585 | < |
| 10586 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10587 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10588 | {only available when compiled with the |+sound| feature} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10589 | |
| 10590 | |
| 10591 | sound_stop({id}) *sound_stop()* |
| 10592 | Stop playing sound {id}. {id} must be previously returned by |
| 10593 | `sound_playevent()` or `sound_playfile()`. |
| 10594 | |
| 10595 | On some Linux systems you may need the libcanberra-pulse |
| 10596 | package, otherwise sound may not stop. |
| 10597 | |
| 10598 | On MS-Windows, this does not work for event sound started by |
| 10599 | `sound_playevent()`. To stop event sounds, use `sound_clear()`. |
| 10600 | |
| 10601 | Can also be used as a |method|: > |
| 10602 | soundid->sound_stop() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10603 | < |
| 10604 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10605 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10606 | {only available when compiled with the |+sound| feature} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10607 | |
| 10608 | *soundfold()* |
| 10609 | soundfold({word}) |
| 10610 | Return the sound-folded equivalent of {word}. Uses the first |
| 10611 | language in 'spelllang' for the current window that supports |
| 10612 | soundfolding. 'spell' must be set. When no sound folding is |
| 10613 | possible the {word} is returned unmodified. |
| 10614 | This can be used for making spelling suggestions. Note that |
| 10615 | the method can be quite slow. |
| 10616 | |
| 10617 | Can also be used as a |method|: > |
| 10618 | GetWord()->soundfold() |
| 10619 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10620 | Return type: |String| |
| 10621 | |
| 10622 | |
| 10623 | spellbadword([{sentence}]) *spellbadword()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10624 | Without argument: The result is the badly spelled word under |
| 10625 | or after the cursor. The cursor is moved to the start of the |
| 10626 | bad word. When no bad word is found in the cursor line the |
| 10627 | result is an empty string and the cursor doesn't move. |
| 10628 | |
| 10629 | With argument: The result is the first word in {sentence} that |
| 10630 | is badly spelled. If there are no spelling mistakes the |
| 10631 | result is an empty string. |
| 10632 | |
| 10633 | The return value is a list with two items: |
| 10634 | - The badly spelled word or an empty string. |
| 10635 | - The type of the spelling error: |
| 10636 | "bad" spelling mistake |
| 10637 | "rare" rare word |
| 10638 | "local" word only valid in another region |
| 10639 | "caps" word should start with Capital |
| 10640 | Example: > |
| 10641 | echo spellbadword("the quik brown fox") |
| 10642 | < ['quik', 'bad'] ~ |
| 10643 | |
| 10644 | The spelling information for the current window and the value |
| 10645 | of 'spelllang' are used. |
| 10646 | |
| 10647 | Can also be used as a |method|: > |
| 10648 | GetText()->spellbadword() |
| 10649 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10650 | Return type: list<string> |
| 10651 | |
| 10652 | |
| 10653 | spellsuggest({word} [, {max} [, {capital}]]) *spellsuggest()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10654 | Return a |List| with spelling suggestions to replace {word}. |
| 10655 | When {max} is given up to this number of suggestions are |
| 10656 | returned. Otherwise up to 25 suggestions are returned. |
| 10657 | |
| 10658 | When the {capital} argument is given and it's non-zero only |
| 10659 | suggestions with a leading capital will be given. Use this |
| 10660 | after a match with 'spellcapcheck'. |
| 10661 | |
| 10662 | {word} can be a badly spelled word followed by other text. |
| 10663 | This allows for joining two words that were split. The |
| 10664 | suggestions also include the following text, thus you can |
| 10665 | replace a line. |
| 10666 | |
| 10667 | {word} may also be a good word. Similar words will then be |
| 10668 | returned. {word} itself is not included in the suggestions, |
| 10669 | although it may appear capitalized. |
| 10670 | |
| 10671 | The spelling information for the current window is used. The |
| 10672 | values of 'spelllang' and 'spellsuggest' are used. |
| 10673 | |
| 10674 | Can also be used as a |method|: > |
| 10675 | GetWord()->spellsuggest() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10676 | < |
| 10677 | Return type: list<string> or list<any> |
| 10678 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10679 | |
| 10680 | split({string} [, {pattern} [, {keepempty}]]) *split()* |
| 10681 | Make a |List| out of {string}. When {pattern} is omitted or |
Shane Harper | c1b3984 | 2024-07-17 19:40:40 +0200 | [diff] [blame] | 10682 | empty each white space separated sequence of characters |
| 10683 | becomes an item. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10684 | Otherwise the string is split where {pattern} matches, |
| 10685 | removing the matched characters. 'ignorecase' is not used |
| 10686 | here, add \c to ignore case. |/\c| |
| 10687 | When the first or last item is empty it is omitted, unless the |
| 10688 | {keepempty} argument is given and it's non-zero. |
| 10689 | Other empty items are kept when {pattern} matches at least one |
| 10690 | character or when {keepempty} is non-zero. |
| 10691 | Example: > |
| 10692 | :let words = split(getline('.'), '\W\+') |
| 10693 | < To split a string in individual characters: > |
| 10694 | :for c in split(mystring, '\zs') |
| 10695 | < If you want to keep the separator you can also use '\zs' at |
| 10696 | the end of the pattern: > |
| 10697 | :echo split('abc:def:ghi', ':\zs') |
| 10698 | < ['abc:', 'def:', 'ghi'] ~ |
| 10699 | Splitting a table where the first element can be empty: > |
| 10700 | :let items = split(line, ':', 1) |
| 10701 | < The opposite function is |join()|. |
| 10702 | |
| 10703 | Can also be used as a |method|: > |
| 10704 | GetString()->split() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10705 | < |
| 10706 | Return type: list<string> |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10707 | |
| 10708 | sqrt({expr}) *sqrt()* |
| 10709 | Return the non-negative square root of Float {expr} as a |
| 10710 | |Float|. |
| 10711 | {expr} must evaluate to a |Float| or a |Number|. When {expr} |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 10712 | is negative the result is NaN (Not a Number). Returns 0.0 if |
| 10713 | {expr} is not a |Float| or a |Number|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10714 | Examples: > |
| 10715 | :echo sqrt(100) |
| 10716 | < 10.0 > |
| 10717 | :echo sqrt(-4.01) |
| 10718 | < nan |
| 10719 | "nan" may be different, it depends on system libraries. |
| 10720 | |
| 10721 | Can also be used as a |method|: > |
| 10722 | Compute()->sqrt() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10723 | < |
| 10724 | Return type: |Float| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10725 | |
| 10726 | |
| 10727 | srand([{expr}]) *srand()* |
| 10728 | Initialize seed used by |rand()|: |
| 10729 | - If {expr} is not given, seed values are initialized by |
| 10730 | reading from /dev/urandom, if possible, or using time(NULL) |
| 10731 | a.k.a. epoch time otherwise; this only has second accuracy. |
| 10732 | - If {expr} is given it must be a Number. It is used to |
| 10733 | initialize the seed values. This is useful for testing or |
| 10734 | when a predictable sequence is intended. |
| 10735 | |
| 10736 | Examples: > |
| 10737 | :let seed = srand() |
| 10738 | :let seed = srand(userinput) |
| 10739 | :echo rand(seed) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10740 | < |
| 10741 | Return type: list<number> |
| 10742 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10743 | |
| 10744 | state([{what}]) *state()* |
| 10745 | Return a string which contains characters indicating the |
| 10746 | current state. Mostly useful in callbacks that want to do |
| 10747 | work that may not always be safe. Roughly this works like: |
| 10748 | - callback uses state() to check if work is safe to do. |
| 10749 | Yes: then do it right away. |
| 10750 | No: add to work queue and add a |SafeState| and/or |
| 10751 | |SafeStateAgain| autocommand (|SafeState| triggers at |
| 10752 | toplevel, |SafeStateAgain| triggers after handling |
| 10753 | messages and callbacks). |
| 10754 | - When SafeState or SafeStateAgain is triggered and executes |
| 10755 | your autocommand, check with `state()` if the work can be |
| 10756 | done now, and if yes remove it from the queue and execute. |
| 10757 | Remove the autocommand if the queue is now empty. |
| 10758 | Also see |mode()|. |
| 10759 | |
| 10760 | When {what} is given only characters in this string will be |
| 10761 | added. E.g, this checks if the screen has scrolled: > |
| 10762 | if state('s') == '' |
| 10763 | " screen has not scrolled |
| 10764 | < |
| 10765 | These characters indicate the state, generally indicating that |
| 10766 | something is busy: |
| 10767 | m halfway a mapping, :normal command, feedkeys() or |
| 10768 | stuffed command |
| 10769 | o operator pending, e.g. after |d| |
| 10770 | a Insert mode autocomplete active |
| 10771 | x executing an autocommand |
| 10772 | w blocked on waiting, e.g. ch_evalexpr(), ch_read() and |
| 10773 | ch_readraw() when reading json |
| 10774 | S not triggering SafeState or SafeStateAgain, e.g. after |
| 10775 | |f| or a count |
| 10776 | c callback invoked, including timer (repeats for |
| 10777 | recursiveness up to "ccc") |
| 10778 | s screen has scrolled for messages |
| 10779 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10780 | Return type: |String| |
| 10781 | |
| 10782 | |
Yegappan Lakshmanan | a11b23c | 2025-01-16 19:16:42 +0100 | [diff] [blame] | 10783 | str2blob({list} [, {options}]) *str2blob()* |
| 10784 | Return a Blob by converting the characters in the List of |
| 10785 | strings in {list} into bytes. |
| 10786 | |
| 10787 | A <NL> byte is added to the blob after each list item. A |
| 10788 | newline character in the string is translated into a <NUL> |
| 10789 | byte in the blob. |
Yegappan Lakshmanan | 1aefe1d | 2025-01-14 17:29:42 +0100 | [diff] [blame] | 10790 | |
| 10791 | If {options} is not supplied, the current 'encoding' value is |
Yegappan Lakshmanan | a11b23c | 2025-01-16 19:16:42 +0100 | [diff] [blame] | 10792 | used to convert the characters into bytes. |
Yegappan Lakshmanan | 1aefe1d | 2025-01-14 17:29:42 +0100 | [diff] [blame] | 10793 | |
| 10794 | The argument {options} is a |Dict| and supports the following |
| 10795 | items: |
Bakudankun | b3854bf | 2025-02-23 20:29:21 +0100 | [diff] [blame] | 10796 | encoding Convert the characters using this encoding |
| 10797 | before making the Blob. |
Yegappan Lakshmanan | a11b23c | 2025-01-16 19:16:42 +0100 | [diff] [blame] | 10798 | The value is a |String|. See |encoding-names| |
| 10799 | for the supported values. |
Yegappan Lakshmanan | 1aefe1d | 2025-01-14 17:29:42 +0100 | [diff] [blame] | 10800 | |
| 10801 | An error is given and an empty blob is returned if the |
| 10802 | character encoding fails. |
| 10803 | |
Yegappan Lakshmanan | a11b23c | 2025-01-16 19:16:42 +0100 | [diff] [blame] | 10804 | Returns an empty Blob if {list} is empty. |
Yegappan Lakshmanan | 1aefe1d | 2025-01-14 17:29:42 +0100 | [diff] [blame] | 10805 | |
| 10806 | See also |blob2str()| |
| 10807 | |
| 10808 | Examples: > |
Hirohito Higashi | 932a535 | 2025-03-23 10:20:20 +0100 | [diff] [blame] | 10809 | str2blob(["ab"]) returns 0z6162 |
| 10810 | str2blob(["«»"]) returns 0zC2ABC2BB |
| 10811 | str2blob(["a\nb"]) returns 0z610062 |
| 10812 | str2blob(["a","b"]) returns 0z610A62 |
Yegappan Lakshmanan | a11b23c | 2025-01-16 19:16:42 +0100 | [diff] [blame] | 10813 | str2blob(["«»"], {'encoding': 'latin1'}) returns 0zABBB |
Hirohito Higashi | 932a535 | 2025-03-23 10:20:20 +0100 | [diff] [blame] | 10814 | str2blob(readfile('myfile.txt')) |
Yegappan Lakshmanan | 1aefe1d | 2025-01-14 17:29:42 +0100 | [diff] [blame] | 10815 | < |
| 10816 | Can also be used as a |method|: > |
Yegappan Lakshmanan | a11b23c | 2025-01-16 19:16:42 +0100 | [diff] [blame] | 10817 | GetListOfStrings()->str2blob() |
Yegappan Lakshmanan | 1aefe1d | 2025-01-14 17:29:42 +0100 | [diff] [blame] | 10818 | < |
| 10819 | Return type: |Blob| |
| 10820 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10821 | str2float({string} [, {quoted}]) *str2float()* |
| 10822 | Convert String {string} to a Float. This mostly works the |
| 10823 | same as when using a floating point number in an expression, |
| 10824 | see |floating-point-format|. But it's a bit more permissive. |
| 10825 | E.g., "1e40" is accepted, while in an expression you need to |
| 10826 | write "1.0e40". The hexadecimal form "0x123" is also |
| 10827 | accepted, but not others, like binary or octal. |
| 10828 | When {quoted} is present and non-zero then embedded single |
| 10829 | quotes before the dot are ignored, thus "1'000.0" is a |
| 10830 | thousand. |
| 10831 | Text after the number is silently ignored. |
| 10832 | The decimal point is always '.', no matter what the locale is |
| 10833 | set to. A comma ends the number: "12,345.67" is converted to |
| 10834 | 12.0. You can strip out thousands separators with |
| 10835 | |substitute()|: > |
| 10836 | let f = str2float(substitute(text, ',', '', 'g')) |
| 10837 | < |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 10838 | Returns 0.0 if the conversion fails. |
| 10839 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10840 | Can also be used as a |method|: > |
| 10841 | let f = text->substitute(',', '', 'g')->str2float() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10842 | < |
| 10843 | Return type: |Float| |
| 10844 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10845 | |
| 10846 | str2list({string} [, {utf8}]) *str2list()* |
| 10847 | Return a list containing the number values which represent |
| 10848 | each character in String {string}. Examples: > |
| 10849 | str2list(" ") returns [32] |
| 10850 | str2list("ABC") returns [65, 66, 67] |
| 10851 | < |list2str()| does the opposite. |
| 10852 | |
| 10853 | When {utf8} is omitted or zero, the current 'encoding' is used. |
| 10854 | When {utf8} is TRUE, always treat the String as UTF-8 |
| 10855 | characters. With UTF-8 composing characters are handled |
| 10856 | properly: > |
| 10857 | str2list("á") returns [97, 769] |
| 10858 | |
| 10859 | < Can also be used as a |method|: > |
| 10860 | GetString()->str2list() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10861 | < |
| 10862 | Return type: list<number> |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10863 | |
| 10864 | |
| 10865 | str2nr({string} [, {base} [, {quoted}]]) *str2nr()* |
| 10866 | Convert string {string} to a number. |
| 10867 | {base} is the conversion base, it can be 2, 8, 10 or 16. |
| 10868 | When {quoted} is present and non-zero then embedded single |
| 10869 | quotes are ignored, thus "1'000'000" is a million. |
| 10870 | |
| 10871 | When {base} is omitted base 10 is used. This also means that |
| 10872 | a leading zero doesn't cause octal conversion to be used, as |
| 10873 | with the default String to Number conversion. Example: > |
| 10874 | let nr = str2nr('0123') |
| 10875 | < |
| 10876 | When {base} is 16 a leading "0x" or "0X" is ignored. With a |
| 10877 | different base the result will be zero. Similarly, when |
| 10878 | {base} is 8 a leading "0", "0o" or "0O" is ignored, and when |
| 10879 | {base} is 2 a leading "0b" or "0B" is ignored. |
| 10880 | Text after the number is silently ignored. |
| 10881 | |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 10882 | Returns 0 if {string} is empty or on error. |
| 10883 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10884 | Can also be used as a |method|: > |
| 10885 | GetText()->str2nr() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10886 | < |
| 10887 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10888 | |
| 10889 | |
| 10890 | strcharlen({string}) *strcharlen()* |
| 10891 | The result is a Number, which is the number of characters |
| 10892 | in String {string}. Composing characters are ignored. |
| 10893 | |strchars()| can count the number of characters, counting |
| 10894 | composing characters separately. |
| 10895 | |
Bram Moolenaar | 6ba83ba | 2022-06-12 22:15:57 +0100 | [diff] [blame] | 10896 | Returns 0 if {string} is empty or on error. |
| 10897 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10898 | Also see |strlen()|, |strdisplaywidth()| and |strwidth()|. |
| 10899 | |
| 10900 | Can also be used as a |method|: > |
| 10901 | GetText()->strcharlen() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10902 | < |
| 10903 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10904 | |
| 10905 | |
| 10906 | strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()* |
| 10907 | Like |strpart()| but using character index and length instead |
| 10908 | of byte index and length. |
| 10909 | When {skipcc} is omitted or zero, composing characters are |
| 10910 | counted separately. |
zeertzjq | ad38769 | 2024-03-23 08:23:48 +0100 | [diff] [blame] | 10911 | When {skipcc} set to 1, composing characters are treated as a |
| 10912 | part of the preceding base character, similar to |slice()|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10913 | When a character index is used where a character does not |
| 10914 | exist it is omitted and counted as one character. For |
| 10915 | example: > |
| 10916 | strcharpart('abc', -1, 2) |
| 10917 | < results in 'a'. |
| 10918 | |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 10919 | Returns an empty string on error. |
| 10920 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10921 | Can also be used as a |method|: > |
| 10922 | GetText()->strcharpart(5) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10923 | < |
| 10924 | Return type: |String| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10925 | |
| 10926 | |
| 10927 | strchars({string} [, {skipcc}]) *strchars()* |
| 10928 | The result is a Number, which is the number of characters |
| 10929 | in String {string}. |
| 10930 | When {skipcc} is omitted or zero, composing characters are |
| 10931 | counted separately. |
zeertzjq | ad38769 | 2024-03-23 08:23:48 +0100 | [diff] [blame] | 10932 | When {skipcc} set to 1, composing characters are ignored. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10933 | |strcharlen()| always does this. |
| 10934 | |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 10935 | Returns zero on error. |
| 10936 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10937 | Also see |strlen()|, |strdisplaywidth()| and |strwidth()|. |
| 10938 | |
| 10939 | {skipcc} is only available after 7.4.755. For backward |
| 10940 | compatibility, you can define a wrapper function: > |
| 10941 | if has("patch-7.4.755") |
| 10942 | function s:strchars(str, skipcc) |
| 10943 | return strchars(a:str, a:skipcc) |
| 10944 | endfunction |
| 10945 | else |
| 10946 | function s:strchars(str, skipcc) |
| 10947 | if a:skipcc |
| 10948 | return strlen(substitute(a:str, ".", "x", "g")) |
| 10949 | else |
| 10950 | return strchars(a:str) |
| 10951 | endif |
| 10952 | endfunction |
| 10953 | endif |
| 10954 | < |
| 10955 | Can also be used as a |method|: > |
| 10956 | GetText()->strchars() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10957 | < |
| 10958 | Return type: |Number| |
| 10959 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10960 | |
| 10961 | strdisplaywidth({string} [, {col}]) *strdisplaywidth()* |
| 10962 | The result is a Number, which is the number of display cells |
| 10963 | String {string} occupies on the screen when it starts at {col} |
| 10964 | (first column is zero). When {col} is omitted zero is used. |
| 10965 | Otherwise it is the screen column where to start. This |
| 10966 | matters for Tab characters. |
| 10967 | The option settings of the current window are used. This |
| 10968 | matters for anything that's displayed differently, such as |
| 10969 | 'tabstop' and 'display'. |
| 10970 | When {string} contains characters with East Asian Width Class |
| 10971 | Ambiguous, this function's return value depends on 'ambiwidth'. |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 10972 | Returns zero on error. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10973 | Also see |strlen()|, |strwidth()| and |strchars()|. |
| 10974 | |
| 10975 | Can also be used as a |method|: > |
| 10976 | GetText()->strdisplaywidth() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 10977 | < |
| 10978 | Return type: |Number| |
| 10979 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 10980 | |
| 10981 | strftime({format} [, {time}]) *strftime()* |
| 10982 | The result is a String, which is a formatted date and time, as |
| 10983 | specified by the {format} string. The given {time} is used, |
| 10984 | or the current time if no time is given. The accepted |
| 10985 | {format} depends on your system, thus this is not portable! |
| 10986 | See the manual page of the C function strftime() for the |
| 10987 | format. The maximum length of the result is 80 characters. |
| 10988 | See also |localtime()|, |getftime()| and |strptime()|. |
| 10989 | The language can be changed with the |:language| command. |
| 10990 | Examples: > |
| 10991 | :echo strftime("%c") Sun Apr 27 11:49:23 1997 |
| 10992 | :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25 |
| 10993 | :echo strftime("%y%m%d %T") 970427 11:53:55 |
| 10994 | :echo strftime("%H:%M") 11:55 |
| 10995 | :echo strftime("%c", getftime("file.c")) |
| 10996 | Show mod time of file.c. |
| 10997 | < Not available on all systems. To check use: > |
| 10998 | :if exists("*strftime") |
| 10999 | |
| 11000 | < Can also be used as a |method|: > |
| 11001 | GetFormat()->strftime() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11002 | < |
| 11003 | Return type: |String| |
| 11004 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11005 | |
| 11006 | strgetchar({str}, {index}) *strgetchar()* |
Bram Moolenaar | 2d8ed02 | 2022-05-21 13:08:16 +0100 | [diff] [blame] | 11007 | Get a Number corresponding to the character at {index} in |
| 11008 | {str}. This uses a zero-based character index, not a byte |
| 11009 | index. Composing characters are considered separate |
| 11010 | characters here. Use |nr2char()| to convert the Number to a |
| 11011 | String. |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 11012 | Returns -1 if {index} is invalid. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11013 | Also see |strcharpart()| and |strchars()|. |
| 11014 | |
| 11015 | Can also be used as a |method|: > |
| 11016 | GetText()->strgetchar(5) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11017 | < |
| 11018 | Return type: |Number| |
| 11019 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11020 | |
| 11021 | stridx({haystack}, {needle} [, {start}]) *stridx()* |
| 11022 | The result is a Number, which gives the byte index in |
| 11023 | {haystack} of the first occurrence of the String {needle}. |
| 11024 | If {start} is specified, the search starts at index {start}. |
| 11025 | This can be used to find a second match: > |
| 11026 | :let colon1 = stridx(line, ":") |
| 11027 | :let colon2 = stridx(line, ":", colon1 + 1) |
| 11028 | < The search is done case-sensitive. |
| 11029 | For pattern searches use |match()|. |
| 11030 | -1 is returned if the {needle} does not occur in {haystack}. |
| 11031 | See also |strridx()|. |
| 11032 | Examples: > |
| 11033 | :echo stridx("An Example", "Example") 3 |
| 11034 | :echo stridx("Starting point", "Start") 0 |
| 11035 | :echo stridx("Starting point", "start") -1 |
| 11036 | < *strstr()* *strchr()* |
| 11037 | stridx() works similar to the C function strstr(). When used |
| 11038 | with a single character it works similar to strchr(). |
| 11039 | |
| 11040 | Can also be used as a |method|: > |
| 11041 | GetHaystack()->stridx(needle) |
| 11042 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11043 | Return type: |Number| |
| 11044 | |
| 11045 | |
| 11046 | string({expr}) *string()* |
| 11047 | Return {expr} converted to a String. If {expr} is a Number, |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11048 | Float, String, Blob or a composition of them, then the result |
| 11049 | can be parsed back with |eval()|. |
| 11050 | {expr} type result ~ |
| 11051 | String 'string' (single quotes are doubled) |
| 11052 | Number 123 |
| 11053 | Float 123.123456 or 1.123456e8 |
| 11054 | Funcref function('name') |
| 11055 | Blob 0z00112233.44556677.8899 |
| 11056 | List [item, item] |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 11057 | Tuple (item, item) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11058 | Dictionary {key: value, key: value} |
Bram Moolenaar | f1dcd14 | 2022-12-31 15:30:45 +0000 | [diff] [blame] | 11059 | Class class SomeName |
| 11060 | Object object of SomeName {lnum: 1, col: 3} |
Yegappan Lakshmanan | 3164cf8 | 2024-03-28 10:36:42 +0100 | [diff] [blame] | 11061 | Enum enum EnumName |
Yegappan Lakshmanan | 3cf121e | 2024-03-31 18:45:35 +0200 | [diff] [blame] | 11062 | EnumValue enum name.value {name: str, ordinal: nr} |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11063 | |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 11064 | When a |List|, |Tuple| or |Dictionary| has a recursive |
| 11065 | reference it is replaced by "[...]" or "(...)" or "{...}". |
| 11066 | Using eval() on the result will then fail. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11067 | |
mityu | 7f0bba2 | 2024-03-29 10:14:41 +0100 | [diff] [blame] | 11068 | For an object, invokes the string() method to get a textual |
Yegappan Lakshmanan | d3eae7b | 2024-03-03 16:26:58 +0100 | [diff] [blame] | 11069 | representation of the object. If the method is not present, |
mityu | 7f0bba2 | 2024-03-29 10:14:41 +0100 | [diff] [blame] | 11070 | then the default representation is used. |object-string()| |
Yegappan Lakshmanan | d3eae7b | 2024-03-03 16:26:58 +0100 | [diff] [blame] | 11071 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11072 | Can also be used as a |method|: > |
| 11073 | mylist->string() |
| 11074 | |
| 11075 | < Also see |strtrans()|. |
| 11076 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11077 | Return type: |String| |
| 11078 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11079 | |
| 11080 | strlen({string}) *strlen()* |
| 11081 | The result is a Number, which is the length of the String |
| 11082 | {string} in bytes. |
| 11083 | If the argument is a Number it is first converted to a String. |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 11084 | For other types an error is given and zero is returned. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11085 | If you want to count the number of multibyte characters use |
| 11086 | |strchars()|. |
| 11087 | Also see |len()|, |strdisplaywidth()| and |strwidth()|. |
| 11088 | |
| 11089 | Can also be used as a |method|: > |
| 11090 | GetString()->strlen() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11091 | < |
| 11092 | Return type: |Number| |
| 11093 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11094 | |
| 11095 | strpart({src}, {start} [, {len} [, {chars}]]) *strpart()* |
| 11096 | The result is a String, which is part of {src}, starting from |
| 11097 | byte {start}, with the byte length {len}. |
| 11098 | When {chars} is present and TRUE then {len} is the number of |
| 11099 | characters positions (composing characters are not counted |
| 11100 | separately, thus "1" means one base character and any |
| 11101 | following composing characters). |
| 11102 | To count {start} as characters instead of bytes use |
| 11103 | |strcharpart()|. |
| 11104 | |
| 11105 | When bytes are selected which do not exist, this doesn't |
| 11106 | result in an error, the bytes are simply omitted. |
| 11107 | If {len} is missing, the copy continues from {start} till the |
| 11108 | end of the {src}. > |
| 11109 | strpart("abcdefg", 3, 2) == "de" |
| 11110 | strpart("abcdefg", -2, 4) == "ab" |
| 11111 | strpart("abcdefg", 5, 4) == "fg" |
| 11112 | strpart("abcdefg", 3) == "defg" |
| 11113 | |
| 11114 | < Note: To get the first character, {start} must be 0. For |
| 11115 | example, to get the character under the cursor: > |
| 11116 | strpart(getline("."), col(".") - 1, 1, v:true) |
| 11117 | < |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 11118 | Returns an empty string on error. |
| 11119 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11120 | Can also be used as a |method|: > |
| 11121 | GetText()->strpart(5) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11122 | < |
| 11123 | Return type: |String| |
| 11124 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11125 | |
| 11126 | strptime({format}, {timestring}) *strptime()* |
| 11127 | The result is a Number, which is a unix timestamp representing |
| 11128 | the date and time in {timestring}, which is expected to match |
| 11129 | the format specified in {format}. |
| 11130 | |
| 11131 | The accepted {format} depends on your system, thus this is not |
| 11132 | portable! See the manual page of the C function strptime() |
| 11133 | for the format. Especially avoid "%c". The value of $TZ also |
| 11134 | matters. |
| 11135 | |
| 11136 | If the {timestring} cannot be parsed with {format} zero is |
| 11137 | returned. If you do not know the format of {timestring} you |
| 11138 | can try different {format} values until you get a non-zero |
| 11139 | result. |
| 11140 | |
| 11141 | See also |strftime()|. |
| 11142 | Examples: > |
| 11143 | :echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23") |
| 11144 | < 862156163 > |
| 11145 | :echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55")) |
| 11146 | < Sun Apr 27 11:53:55 1997 > |
| 11147 | :echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600) |
| 11148 | < Sun Apr 27 12:53:55 1997 |
| 11149 | |
| 11150 | Can also be used as a |method|: > |
| 11151 | GetFormat()->strptime(timestring) |
| 11152 | < |
| 11153 | Not available on all systems. To check use: > |
| 11154 | :if exists("*strptime") |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11155 | < |
| 11156 | Return type: |Number| |
| 11157 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11158 | |
| 11159 | strridx({haystack}, {needle} [, {start}]) *strridx()* |
| 11160 | The result is a Number, which gives the byte index in |
| 11161 | {haystack} of the last occurrence of the String {needle}. |
| 11162 | When {start} is specified, matches beyond this index are |
| 11163 | ignored. This can be used to find a match before a previous |
| 11164 | match: > |
| 11165 | :let lastcomma = strridx(line, ",") |
| 11166 | :let comma2 = strridx(line, ",", lastcomma - 1) |
| 11167 | < The search is done case-sensitive. |
| 11168 | For pattern searches use |match()|. |
| 11169 | -1 is returned if the {needle} does not occur in {haystack}. |
| 11170 | If the {needle} is empty the length of {haystack} is returned. |
| 11171 | See also |stridx()|. Examples: > |
| 11172 | :echo strridx("an angry armadillo", "an") 3 |
| 11173 | < *strrchr()* |
| 11174 | When used with a single character it works similar to the C |
| 11175 | function strrchr(). |
| 11176 | |
| 11177 | Can also be used as a |method|: > |
| 11178 | GetHaystack()->strridx(needle) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11179 | < |
| 11180 | Return type: |Number| |
| 11181 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11182 | |
| 11183 | strtrans({string}) *strtrans()* |
| 11184 | The result is a String, which is {string} with all unprintable |
| 11185 | characters translated into printable characters |'isprint'|. |
| 11186 | Like they are shown in a window. Example: > |
| 11187 | echo strtrans(@a) |
| 11188 | < This displays a newline in register a as "^@" instead of |
| 11189 | starting a new line. |
| 11190 | |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 11191 | Returns an empty string on error. |
| 11192 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11193 | Can also be used as a |method|: > |
| 11194 | GetString()->strtrans() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11195 | < |
| 11196 | Return type: |String| |
| 11197 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11198 | |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 11199 | strutf16len({string} [, {countcc}]) *strutf16len()* |
| 11200 | The result is a Number, which is the number of UTF-16 code |
| 11201 | units in String {string} (after converting it to UTF-16). |
| 11202 | |
| 11203 | When {countcc} is TRUE, composing characters are counted |
| 11204 | separately. |
| 11205 | When {countcc} is omitted or FALSE, composing characters are |
| 11206 | ignored. |
| 11207 | |
| 11208 | Returns zero on error. |
| 11209 | |
| 11210 | Also see |strlen()| and |strcharlen()|. |
| 11211 | Examples: > |
| 11212 | echo strutf16len('a') returns 1 |
| 11213 | echo strutf16len('©') returns 1 |
| 11214 | echo strutf16len('😊') returns 2 |
| 11215 | echo strutf16len('ą́') returns 1 |
| 11216 | echo strutf16len('ą́', v:true) returns 3 |
a5ob7r | 790f9a8 | 2023-09-25 06:05:47 +0900 | [diff] [blame] | 11217 | < |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 11218 | Can also be used as a |method|: > |
| 11219 | GetText()->strutf16len() |
| 11220 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11221 | Return type: |Number| |
| 11222 | |
| 11223 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11224 | strwidth({string}) *strwidth()* |
| 11225 | The result is a Number, which is the number of display cells |
| 11226 | String {string} occupies. A Tab character is counted as one |
| 11227 | cell, alternatively use |strdisplaywidth()|. |
| 11228 | When {string} contains characters with East Asian Width Class |
| 11229 | Ambiguous, this function's return value depends on 'ambiwidth'. |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 11230 | Returns zero on error. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11231 | Also see |strlen()|, |strdisplaywidth()| and |strchars()|. |
| 11232 | |
| 11233 | Can also be used as a |method|: > |
| 11234 | GetString()->strwidth() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11235 | < |
| 11236 | Return type: |Number| |
| 11237 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11238 | |
| 11239 | submatch({nr} [, {list}]) *submatch()* *E935* |
| 11240 | Only for an expression in a |:substitute| command or |
| 11241 | substitute() function. |
| 11242 | Returns the {nr}'th submatch of the matched text. When {nr} |
| 11243 | is 0 the whole matched text is returned. |
| 11244 | Note that a NL in the string can stand for a line break of a |
| 11245 | multi-line match or a NUL character in the text. |
| 11246 | Also see |sub-replace-expression|. |
| 11247 | |
| 11248 | If {list} is present and non-zero then submatch() returns |
| 11249 | a list of strings, similar to |getline()| with two arguments. |
| 11250 | NL characters in the text represent NUL characters in the |
| 11251 | text. |
| 11252 | Only returns more than one item for |:substitute|, inside |
| 11253 | |substitute()| this list will always contain one or zero |
| 11254 | items, since there are no real line breaks. |
| 11255 | |
| 11256 | When substitute() is used recursively only the submatches in |
| 11257 | the current (deepest) call can be obtained. |
| 11258 | |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 11259 | Returns an empty string or list on error. |
| 11260 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11261 | Examples: > |
| 11262 | :s/\d\+/\=submatch(0) + 1/ |
| 11263 | :echo substitute(text, '\d\+', '\=submatch(0) + 1', '') |
| 11264 | < This finds the first number in the line and adds one to it. |
| 11265 | A line break is included as a newline character. |
| 11266 | |
| 11267 | Can also be used as a |method|: > |
| 11268 | GetNr()->submatch() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11269 | < |
| 11270 | Return type: |String| or list<string> depending on {list} |
| 11271 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11272 | |
| 11273 | substitute({string}, {pat}, {sub}, {flags}) *substitute()* |
| 11274 | The result is a String, which is a copy of {string}, in which |
| 11275 | the first match of {pat} is replaced with {sub}. |
| 11276 | When {flags} is "g", all matches of {pat} in {string} are |
| 11277 | replaced. Otherwise {flags} should be "". |
| 11278 | |
| 11279 | This works like the ":substitute" command (without any flags). |
| 11280 | But the matching with {pat} is always done like the 'magic' |
| 11281 | option is set and 'cpoptions' is empty (to make scripts |
| 11282 | portable). 'ignorecase' is still relevant, use |/\c| or |/\C| |
| 11283 | if you want to ignore or match case and ignore 'ignorecase'. |
| 11284 | 'smartcase' is not used. See |string-match| for how {pat} is |
| 11285 | used. |
| 11286 | |
| 11287 | A "~" in {sub} is not replaced with the previous {sub}. |
| 11288 | Note that some codes in {sub} have a special meaning |
| 11289 | |sub-replace-special|. For example, to replace something with |
| 11290 | "\n" (two characters), use "\\\\n" or '\\n'. |
| 11291 | |
| 11292 | When {pat} does not match in {string}, {string} is returned |
| 11293 | unmodified. |
| 11294 | |
| 11295 | Example: > |
| 11296 | :let &path = substitute(&path, ",\\=[^,]*$", "", "") |
| 11297 | < This removes the last component of the 'path' option. > |
| 11298 | :echo substitute("testing", ".*", "\\U\\0", "") |
| 11299 | < results in "TESTING". |
| 11300 | |
| 11301 | When {sub} starts with "\=", the remainder is interpreted as |
| 11302 | an expression. See |sub-replace-expression|. Example: > |
| 11303 | :echo substitute(s, '%\(\x\x\)', |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 11304 | \ '\=nr2char("0x" .. submatch(1))', 'g') |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11305 | |
| 11306 | < When {sub} is a Funcref that function is called, with one |
| 11307 | optional argument. Example: > |
| 11308 | :echo substitute(s, '%\(\x\x\)', SubNr, 'g') |
| 11309 | < The optional argument is a list which contains the whole |
| 11310 | matched string and up to nine submatches, like what |
| 11311 | |submatch()| returns. Example: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 11312 | :echo substitute(s, '%\(\x\x\)', {m -> '0x' .. m[1]}, 'g') |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11313 | |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 11314 | < Returns an empty string on error. |
| 11315 | |
| 11316 | Can also be used as a |method|: > |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11317 | GetString()->substitute(pat, sub, flags) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11318 | < |
| 11319 | Return type: |String| |
| 11320 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11321 | |
Bram Moolenaar | c216a7a | 2022-12-05 13:50:55 +0000 | [diff] [blame] | 11322 | swapfilelist() *swapfilelist()* |
| 11323 | Returns a list of swap file names, like what "vim -r" shows. |
| 11324 | See the |-r| command argument. The 'directory' option is used |
| 11325 | for the directories to inspect. If you only want to get a |
| 11326 | list of swap files in the current directory then temporarily |
| 11327 | set 'directory' to a dot: > |
| 11328 | let save_dir = &directory |
| 11329 | let &directory = '.' |
| 11330 | let swapfiles = swapfilelist() |
| 11331 | let &directory = save_dir |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11332 | < |
| 11333 | Return type: list<string> |
| 11334 | |
Bram Moolenaar | c216a7a | 2022-12-05 13:50:55 +0000 | [diff] [blame] | 11335 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11336 | swapinfo({fname}) *swapinfo()* |
| 11337 | The result is a dictionary, which holds information about the |
| 11338 | swapfile {fname}. The available fields are: |
| 11339 | version Vim version |
| 11340 | user user name |
| 11341 | host host name |
| 11342 | fname original file name |
| 11343 | pid PID of the Vim process that created the swap |
| 11344 | file |
| 11345 | mtime last modification time in seconds |
| 11346 | inode Optional: INODE number of the file |
| 11347 | dirty 1 if file was modified, 0 if not |
| 11348 | Note that "user" and "host" are truncated to at most 39 bytes. |
| 11349 | In case of failure an "error" item is added with the reason: |
| 11350 | Cannot open file: file not found or in accessible |
| 11351 | Cannot read file: cannot read first block |
| 11352 | Not a swap file: does not contain correct block ID |
| 11353 | Magic number mismatch: Info in first block is invalid |
| 11354 | |
| 11355 | Can also be used as a |method|: > |
| 11356 | GetFilename()->swapinfo() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11357 | < |
| 11358 | Return type: dict<any> or dict<string> |
| 11359 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11360 | |
| 11361 | swapname({buf}) *swapname()* |
| 11362 | The result is the swap file path of the buffer {expr}. |
| 11363 | For the use of {buf}, see |bufname()| above. |
| 11364 | If buffer {buf} is the current buffer, the result is equal to |
| 11365 | |:swapname| (unless there is no swap file). |
| 11366 | If buffer {buf} has no swap file, returns an empty string. |
| 11367 | |
| 11368 | Can also be used as a |method|: > |
| 11369 | GetBufname()->swapname() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11370 | < |
| 11371 | Return type: |String| |
| 11372 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11373 | |
| 11374 | synID({lnum}, {col}, {trans}) *synID()* |
| 11375 | The result is a Number, which is the syntax ID at the position |
| 11376 | {lnum} and {col} in the current window. |
| 11377 | The syntax ID can be used with |synIDattr()| and |
| 11378 | |synIDtrans()| to obtain syntax information about text. |
| 11379 | |
| 11380 | {col} is 1 for the leftmost column, {lnum} is 1 for the first |
| 11381 | line. 'synmaxcol' applies, in a longer line zero is returned. |
| 11382 | Note that when the position is after the last character, |
| 11383 | that's where the cursor can be in Insert mode, synID() returns |
| 11384 | zero. {lnum} is used like with |getline()|. |
| 11385 | |
| 11386 | When {trans} is |TRUE|, transparent items are reduced to the |
| 11387 | item that they reveal. This is useful when wanting to know |
| 11388 | the effective color. When {trans} is |FALSE|, the transparent |
| 11389 | item is returned. This is useful when wanting to know which |
| 11390 | syntax item is effective (e.g. inside parens). |
| 11391 | Warning: This function can be very slow. Best speed is |
| 11392 | obtained by going through the file in forward direction. |
| 11393 | |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 11394 | Returns zero on error. |
| 11395 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11396 | Example (echoes the name of the syntax item under the cursor): > |
| 11397 | :echo synIDattr(synID(line("."), col("."), 1), "name") |
| 11398 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11399 | Return type: |Number| |
| 11400 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11401 | |
| 11402 | synIDattr({synID}, {what} [, {mode}]) *synIDattr()* |
| 11403 | The result is a String, which is the {what} attribute of |
| 11404 | syntax ID {synID}. This can be used to obtain information |
| 11405 | about a syntax item. |
| 11406 | {mode} can be "gui", "cterm" or "term", to get the attributes |
| 11407 | for that mode. When {mode} is omitted, or an invalid value is |
| 11408 | used, the attributes for the currently active highlighting are |
| 11409 | used (GUI, cterm or term). |
| 11410 | Use synIDtrans() to follow linked highlight groups. |
| 11411 | {what} result |
| 11412 | "name" the name of the syntax item |
| 11413 | "fg" foreground color (GUI: color name used to set |
| 11414 | the color, cterm: color number as a string, |
| 11415 | term: empty string) |
| 11416 | "bg" background color (as with "fg") |
| 11417 | "font" font name (only available in the GUI) |
| 11418 | |highlight-font| |
| 11419 | "sp" special color for the GUI (as with "fg") |
| 11420 | |highlight-guisp| |
| 11421 | "ul" underline color for cterm: number as a string |
| 11422 | "fg#" like "fg", but for the GUI and the GUI is |
| 11423 | running the name in "#RRGGBB" form |
| 11424 | "bg#" like "fg#" for "bg" |
| 11425 | "sp#" like "fg#" for "sp" |
| 11426 | "bold" "1" if bold |
| 11427 | "italic" "1" if italic |
| 11428 | "reverse" "1" if reverse |
| 11429 | "inverse" "1" if inverse (= reverse) |
| 11430 | "standout" "1" if standout |
| 11431 | "underline" "1" if underlined |
| 11432 | "undercurl" "1" if undercurled |
| 11433 | "strike" "1" if strikethrough |
Bram Moolenaar | de78632 | 2022-07-30 14:56:17 +0100 | [diff] [blame] | 11434 | "nocombine" "1" if nocombine |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11435 | |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 11436 | Returns an empty string on error. |
| 11437 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11438 | Example (echoes the color of the syntax item under the |
| 11439 | cursor): > |
| 11440 | :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg") |
| 11441 | < |
| 11442 | Can also be used as a |method|: > |
| 11443 | :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg") |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11444 | < |
| 11445 | Return type: |String| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11446 | |
| 11447 | |
| 11448 | synIDtrans({synID}) *synIDtrans()* |
| 11449 | The result is a Number, which is the translated syntax ID of |
| 11450 | {synID}. This is the syntax group ID of what is being used to |
| 11451 | highlight the character. Highlight links given with |
| 11452 | ":highlight link" are followed. |
| 11453 | |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 11454 | Returns zero on error. |
| 11455 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11456 | Can also be used as a |method|: > |
| 11457 | :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg") |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11458 | < |
| 11459 | Return type: |Number| |
| 11460 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11461 | |
| 11462 | synconcealed({lnum}, {col}) *synconcealed()* |
| 11463 | The result is a |List| with currently three items: |
| 11464 | 1. The first item in the list is 0 if the character at the |
| 11465 | position {lnum} and {col} is not part of a concealable |
| 11466 | region, 1 if it is. {lnum} is used like with |getline()|. |
| 11467 | 2. The second item in the list is a string. If the first item |
| 11468 | is 1, the second item contains the text which will be |
| 11469 | displayed in place of the concealed text, depending on the |
| 11470 | current setting of 'conceallevel' and 'listchars'. |
| 11471 | 3. The third and final item in the list is a number |
| 11472 | representing the specific syntax region matched in the |
| 11473 | line. When the character is not concealed the value is |
| 11474 | zero. This allows detection of the beginning of a new |
| 11475 | concealable region if there are two consecutive regions |
| 11476 | with the same replacement character. For an example, if |
| 11477 | the text is "123456" and both "23" and "45" are concealed |
| 11478 | and replaced by the character "X", then: |
| 11479 | call returns ~ |
| 11480 | synconcealed(lnum, 1) [0, '', 0] |
| 11481 | synconcealed(lnum, 2) [1, 'X', 1] |
| 11482 | synconcealed(lnum, 3) [1, 'X', 1] |
| 11483 | synconcealed(lnum, 4) [1, 'X', 2] |
| 11484 | synconcealed(lnum, 5) [1, 'X', 2] |
| 11485 | synconcealed(lnum, 6) [0, '', 0] |
| 11486 | |
Christian Brabandt | fe1e2b5 | 2024-04-26 18:42:59 +0200 | [diff] [blame] | 11487 | Note: Doesn't consider |matchadd()| highlighting items, |
| 11488 | since syntax and matching highlighting are two different |
| 11489 | mechanisms |syntax-vs-match|. |
h-east | 52e7cc2 | 2024-07-28 17:03:29 +0200 | [diff] [blame] | 11490 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11491 | Return type: list<any> |
Christian Brabandt | fe1e2b5 | 2024-04-26 18:42:59 +0200 | [diff] [blame] | 11492 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11493 | |
| 11494 | synstack({lnum}, {col}) *synstack()* |
| 11495 | Return a |List|, which is the stack of syntax items at the |
| 11496 | position {lnum} and {col} in the current window. {lnum} is |
| 11497 | used like with |getline()|. Each item in the List is an ID |
| 11498 | like what |synID()| returns. |
| 11499 | The first item in the List is the outer region, following are |
| 11500 | items contained in that one. The last one is what |synID()| |
| 11501 | returns, unless not the whole item is highlighted or it is a |
| 11502 | transparent item. |
| 11503 | This function is useful for debugging a syntax file. |
| 11504 | Example that shows the syntax stack under the cursor: > |
| 11505 | for id in synstack(line("."), col(".")) |
| 11506 | echo synIDattr(id, "name") |
| 11507 | endfor |
| 11508 | < When the position specified with {lnum} and {col} is invalid |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 11509 | an empty List is returned. The position just after the last |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11510 | character in a line and the first column in an empty line are |
| 11511 | valid positions. |
| 11512 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11513 | Return type: list<number> or list<any> |
| 11514 | |
| 11515 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11516 | system({expr} [, {input}]) *system()* *E677* |
| 11517 | Get the output of the shell command {expr} as a |String|. See |
| 11518 | |systemlist()| to get the output as a |List|. |
| 11519 | |
| 11520 | When {input} is given and is a |String| this string is written |
| 11521 | to a file and passed as stdin to the command. The string is |
| 11522 | written as-is, you need to take care of using the correct line |
| 11523 | separators yourself. |
| 11524 | If {input} is given and is a |List| it is written to the file |
| 11525 | in a way |writefile()| does with {binary} set to "b" (i.e. |
| 11526 | with a newline between each list item with newlines inside |
| 11527 | list items converted to NULs). |
| 11528 | When {input} is given and is a number that is a valid id for |
| 11529 | an existing buffer then the content of the buffer is written |
| 11530 | to the file line by line, each line terminated by a NL and |
| 11531 | NULs characters where the text has a NL. |
| 11532 | |
| 11533 | Pipes are not used, the 'shelltemp' option is not used. |
| 11534 | |
| 11535 | When prepended by |:silent| the terminal will not be set to |
| 11536 | cooked mode. This is meant to be used for commands that do |
| 11537 | not need the user to type. It avoids stray characters showing |
| 11538 | up on the screen which require |CTRL-L| to remove. > |
| 11539 | :silent let f = system('ls *.vim') |
| 11540 | < |
| 11541 | Note: Use |shellescape()| or |::S| with |expand()| or |
| 11542 | |fnamemodify()| to escape special characters in a command |
| 11543 | argument. Newlines in {expr} may cause the command to fail. |
| 11544 | The characters in 'shellquote' and 'shellxquote' may also |
| 11545 | cause trouble. |
| 11546 | This is not to be used for interactive commands. |
| 11547 | |
| 11548 | The result is a String. Example: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 11549 | :let files = system('ls ' .. shellescape(expand('%:h'))) |
| 11550 | :let files = system('ls ' .. expand('%:h:S')) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11551 | |
| 11552 | < To make the result more system-independent, the shell output |
| 11553 | is filtered to replace <CR> with <NL> for Macintosh, and |
| 11554 | <CR><NL> with <NL> for DOS-like systems. |
| 11555 | To avoid the string being truncated at a NUL, all NUL |
| 11556 | characters are replaced with SOH (0x01). |
| 11557 | |
| 11558 | The command executed is constructed using several options: |
| 11559 | 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote' |
| 11560 | ({tmp} is an automatically generated file name). |
| 11561 | For Unix, braces are put around {expr} to allow for |
| 11562 | concatenated commands. |
| 11563 | |
| 11564 | The command will be executed in "cooked" mode, so that a |
| 11565 | CTRL-C will interrupt the command (on Unix at least). |
| 11566 | |
| 11567 | The resulting error code can be found in |v:shell_error|. |
| 11568 | This function will fail in |restricted-mode|. |
| 11569 | |
| 11570 | Note that any wrong value in the options mentioned above may |
| 11571 | make the function fail. It has also been reported to fail |
| 11572 | when using a security agent application. |
| 11573 | Unlike ":!cmd" there is no automatic check for changed files. |
| 11574 | Use |:checktime| to force a check. |
| 11575 | |
| 11576 | Can also be used as a |method|: > |
| 11577 | :echo GetCmd()->system() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11578 | < |
| 11579 | Return type: |String| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11580 | |
| 11581 | |
| 11582 | systemlist({expr} [, {input}]) *systemlist()* |
| 11583 | Same as |system()|, but returns a |List| with lines (parts of |
| 11584 | output separated by NL) with NULs transformed into NLs. Output |
| 11585 | is the same as |readfile()| will output with {binary} argument |
| 11586 | set to "b", except that there is no extra empty item when the |
| 11587 | result ends in a NL. |
| 11588 | Note that on MS-Windows you may get trailing CR characters. |
| 11589 | |
| 11590 | To see the difference between "echo hello" and "echo -n hello" |
| 11591 | use |system()| and |split()|: > |
| 11592 | echo system('echo hello')->split('\n', 1) |
| 11593 | < |
| 11594 | Returns an empty string on error. |
| 11595 | |
| 11596 | Can also be used as a |method|: > |
| 11597 | :echo GetCmd()->systemlist() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11598 | < |
| 11599 | Return type: list<string> |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11600 | |
| 11601 | |
| 11602 | tabpagebuflist([{arg}]) *tabpagebuflist()* |
| 11603 | The result is a |List|, where each item is the number of the |
| 11604 | buffer associated with each window in the current tab page. |
| 11605 | {arg} specifies the number of the tab page to be used. When |
| 11606 | omitted the current tab page is used. |
| 11607 | When {arg} is invalid the number zero is returned. |
| 11608 | To get a list of all buffers in all tabs use this: > |
| 11609 | let buflist = [] |
| 11610 | for i in range(tabpagenr('$')) |
| 11611 | call extend(buflist, tabpagebuflist(i + 1)) |
| 11612 | endfor |
| 11613 | < Note that a buffer may appear in more than one window. |
| 11614 | |
| 11615 | Can also be used as a |method|: > |
| 11616 | GetTabpage()->tabpagebuflist() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11617 | < |
| 11618 | Return type: list<number> |
| 11619 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11620 | |
| 11621 | tabpagenr([{arg}]) *tabpagenr()* |
| 11622 | The result is a Number, which is the number of the current |
| 11623 | tab page. The first tab page has number 1. |
| 11624 | |
| 11625 | The optional argument {arg} supports the following values: |
| 11626 | $ the number of the last tab page (the tab page |
| 11627 | count). |
| 11628 | # the number of the last accessed tab page |
| 11629 | (where |g<Tab>| goes to). if there is no |
| 11630 | previous tab page 0 is returned. |
| 11631 | The number can be used with the |:tab| command. |
| 11632 | |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 11633 | Returns zero on error. |
| 11634 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11635 | Return type: |Number| |
| 11636 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11637 | |
| 11638 | tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()* |
| 11639 | Like |winnr()| but for tab page {tabarg}. |
| 11640 | {tabarg} specifies the number of tab page to be used. |
| 11641 | {arg} is used like with |winnr()|: |
| 11642 | - When omitted the current window number is returned. This is |
| 11643 | the window which will be used when going to this tab page. |
| 11644 | - When "$" the number of windows is returned. |
| 11645 | - When "#" the previous window nr is returned. |
| 11646 | Useful examples: > |
| 11647 | tabpagewinnr(1) " current window of tab page 1 |
| 11648 | tabpagewinnr(4, '$') " number of windows in tab page 4 |
| 11649 | < When {tabarg} is invalid zero is returned. |
| 11650 | |
| 11651 | Can also be used as a |method|: > |
| 11652 | GetTabpage()->tabpagewinnr() |
| 11653 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11654 | Return type: |Number| |
| 11655 | |
| 11656 | |
| 11657 | tagfiles() *tagfiles()* |
| 11658 | Returns a |List| with the file names used to search for tags |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11659 | for the current buffer. This is the 'tags' option expanded. |
| 11660 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11661 | Return type: list<string> or list<any> |
| 11662 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11663 | |
| 11664 | taglist({expr} [, {filename}]) *taglist()* |
| 11665 | Returns a |List| of tags matching the regular expression {expr}. |
| 11666 | |
| 11667 | If {filename} is passed it is used to prioritize the results |
| 11668 | in the same way that |:tselect| does. See |tag-priority|. |
| 11669 | {filename} should be the full path of the file. |
| 11670 | |
| 11671 | Each list item is a dictionary with at least the following |
| 11672 | entries: |
| 11673 | name Name of the tag. |
| 11674 | filename Name of the file where the tag is |
| 11675 | defined. It is either relative to the |
| 11676 | current directory or a full path. |
| 11677 | cmd Ex command used to locate the tag in |
| 11678 | the file. |
| 11679 | kind Type of the tag. The value for this |
| 11680 | entry depends on the language specific |
| 11681 | kind values. Only available when |
| 11682 | using a tags file generated by |
Bram Moolenaar | 47c532e | 2022-03-19 15:18:53 +0000 | [diff] [blame] | 11683 | Universal/Exuberant ctags or hdrtag. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11684 | static A file specific tag. Refer to |
| 11685 | |static-tag| for more information. |
| 11686 | More entries may be present, depending on the content of the |
| 11687 | tags file: access, implementation, inherits and signature. |
| 11688 | Refer to the ctags documentation for information about these |
| 11689 | fields. For C code the fields "struct", "class" and "enum" |
| 11690 | may appear, they give the name of the entity the tag is |
| 11691 | contained in. |
| 11692 | |
| 11693 | The ex-command "cmd" can be either an ex search pattern, a |
| 11694 | line number or a line number followed by a byte number. |
| 11695 | |
| 11696 | If there are no matching tags, then an empty list is returned. |
| 11697 | |
| 11698 | To get an exact tag match, the anchors '^' and '$' should be |
| 11699 | used in {expr}. This also make the function work faster. |
| 11700 | Refer to |tag-regexp| for more information about the tag |
| 11701 | search regular expression pattern. |
| 11702 | |
| 11703 | Refer to |'tags'| for information about how the tags file is |
| 11704 | located by Vim. Refer to |tags-file-format| for the format of |
| 11705 | the tags file generated by the different ctags tools. |
| 11706 | |
| 11707 | Can also be used as a |method|: > |
| 11708 | GetTagpattern()->taglist() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11709 | < |
| 11710 | Return type: list<dict<any>> or list<any> |
| 11711 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11712 | |
| 11713 | tan({expr}) *tan()* |
| 11714 | Return the tangent of {expr}, measured in radians, as a |Float| |
| 11715 | in the range [-inf, inf]. |
| 11716 | {expr} must evaluate to a |Float| or a |Number|. |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 11717 | Returns 0.0 if {expr} is not a |Float| or a |Number|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11718 | Examples: > |
| 11719 | :echo tan(10) |
| 11720 | < 0.648361 > |
| 11721 | :echo tan(-4.01) |
| 11722 | < -1.181502 |
| 11723 | |
| 11724 | Can also be used as a |method|: > |
| 11725 | Compute()->tan() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11726 | < |
| 11727 | Return type: |Float| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11728 | |
| 11729 | |
| 11730 | tanh({expr}) *tanh()* |
| 11731 | Return the hyperbolic tangent of {expr} as a |Float| in the |
| 11732 | range [-1, 1]. |
| 11733 | {expr} must evaluate to a |Float| or a |Number|. |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 11734 | Returns 0.0 if {expr} is not a |Float| or a |Number|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11735 | Examples: > |
| 11736 | :echo tanh(0.5) |
| 11737 | < 0.462117 > |
| 11738 | :echo tanh(-1) |
| 11739 | < -0.761594 |
| 11740 | |
| 11741 | Can also be used as a |method|: > |
| 11742 | Compute()->tanh() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11743 | < |
| 11744 | Return type: |Float| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11745 | |
| 11746 | |
| 11747 | tempname() *tempname()* *temp-file-name* |
| 11748 | The result is a String, which is the name of a file that |
| 11749 | doesn't exist. It can be used for a temporary file. The name |
| 11750 | is different for at least 26 consecutive calls. Example: > |
| 11751 | :let tmpfile = tempname() |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 11752 | :exe "redir > " .. tmpfile |
Christian Brabandt | 5cf5301 | 2024-05-18 10:13:11 +0200 | [diff] [blame] | 11753 | < For Unix, the file will be in a private directory |tempfile| |
| 11754 | that is recursively deleted when Vim exits, on other systems |
| 11755 | temporary files are not cleaned up automatically on exit. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11756 | For MS-Windows forward slashes are used when the 'shellslash' |
| 11757 | option is set, or when 'shellcmdflag' starts with '-' and |
| 11758 | 'shell' does not contain powershell or pwsh. |
| 11759 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11760 | Return type: |String| |
| 11761 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11762 | |
| 11763 | term_ functions are documented here: |terminal-function-details| |
| 11764 | |
| 11765 | |
| 11766 | terminalprops() *terminalprops()* |
| 11767 | Returns a |Dictionary| with properties of the terminal that Vim |
| 11768 | detected from the response to |t_RV| request. See |
| 11769 | |v:termresponse| for the response itself. If |v:termresponse| |
| 11770 | is empty most values here will be 'u' for unknown. |
| 11771 | cursor_style whether sending |t_RS| works ** |
| 11772 | cursor_blink_mode whether sending |t_RC| works ** |
| 11773 | underline_rgb whether |t_8u| works ** |
| 11774 | mouse mouse type supported |
Bram Moolenaar | 4bc85f2 | 2022-10-21 14:17:24 +0100 | [diff] [blame] | 11775 | kitty whether Kitty terminal was detected |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11776 | |
| 11777 | ** value 'u' for unknown, 'y' for yes, 'n' for no |
| 11778 | |
| 11779 | If the |+termresponse| feature is missing then the result is |
| 11780 | an empty dictionary. |
| 11781 | |
| 11782 | If "cursor_style" is 'y' then |t_RS| will be sent to request the |
| 11783 | current cursor style. |
| 11784 | If "cursor_blink_mode" is 'y' then |t_RC| will be sent to |
| 11785 | request the cursor blink status. |
| 11786 | "cursor_style" and "cursor_blink_mode" are also set if |t_u7| |
| 11787 | is not empty, Vim will detect the working of sending |t_RS| |
| 11788 | and |t_RC| on startup. |
| 11789 | |
| 11790 | When "underline_rgb" is not 'y', then |t_8u| will be made empty. |
| 11791 | This avoids sending it to xterm, which would clear the colors. |
| 11792 | |
| 11793 | For "mouse" the value 'u' is unknown |
| 11794 | |
| 11795 | Also see: |
| 11796 | - 'ambiwidth' - detected by using |t_u7|. |
| 11797 | - |v:termstyleresp| and |v:termblinkresp| for the response to |
| 11798 | |t_RS| and |t_RC|. |
| 11799 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11800 | Return type: dict<string> |
| 11801 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11802 | |
| 11803 | test_ functions are documented here: |test-functions-details| |
| 11804 | |
| 11805 | |
| 11806 | *timer_info()* |
| 11807 | timer_info([{id}]) |
| 11808 | Return a list with information about timers. |
| 11809 | When {id} is given only information about this timer is |
| 11810 | returned. When timer {id} does not exist an empty list is |
| 11811 | returned. |
| 11812 | When {id} is omitted information about all timers is returned. |
| 11813 | |
| 11814 | For each timer the information is stored in a |Dictionary| with |
| 11815 | these items: |
| 11816 | "id" the timer ID |
| 11817 | "time" time the timer was started with |
| 11818 | "remaining" time until the timer fires |
| 11819 | "repeat" number of times the timer will still fire; |
| 11820 | -1 means forever |
| 11821 | "callback" the callback |
| 11822 | "paused" 1 if the timer is paused, 0 otherwise |
| 11823 | |
| 11824 | Can also be used as a |method|: > |
| 11825 | GetTimer()->timer_info() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11826 | < |
| 11827 | Return type: list<dict<any>> or list<any> |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11828 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11829 | {only available when compiled with the |+timers| feature} |
| 11830 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11831 | |
| 11832 | timer_pause({timer}, {paused}) *timer_pause()* |
| 11833 | Pause or unpause a timer. A paused timer does not invoke its |
| 11834 | callback when its time expires. Unpausing a timer may cause |
| 11835 | the callback to be invoked almost immediately if enough time |
| 11836 | has passed. |
| 11837 | |
| 11838 | Pausing a timer is useful to avoid the callback to be called |
| 11839 | for a short time. |
| 11840 | |
| 11841 | If {paused} evaluates to a non-zero Number or a non-empty |
| 11842 | String, then the timer is paused, otherwise it is unpaused. |
| 11843 | See |non-zero-arg|. |
| 11844 | |
| 11845 | Can also be used as a |method|: > |
| 11846 | GetTimer()->timer_pause(1) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11847 | < |
| 11848 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11849 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11850 | {only available when compiled with the |+timers| feature} |
| 11851 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11852 | |
| 11853 | *timer_start()* *timer* *timers* |
| 11854 | timer_start({time}, {callback} [, {options}]) |
| 11855 | Create a timer and return the timer ID. |
| 11856 | |
| 11857 | {time} is the waiting time in milliseconds. This is the |
| 11858 | minimum time before invoking the callback. When the system is |
| 11859 | busy or Vim is not waiting for input the time will be longer. |
Bram Moolenaar | dd60c36 | 2023-02-27 15:49:53 +0000 | [diff] [blame] | 11860 | Zero can be used to execute the callback when Vim is back in |
| 11861 | the main loop. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11862 | |
| 11863 | {callback} is the function to call. It can be the name of a |
| 11864 | function or a |Funcref|. It is called with one argument, which |
| 11865 | is the timer ID. The callback is only invoked when Vim is |
| 11866 | waiting for input. |
| 11867 | If you want to show a message look at |popup_notification()| |
| 11868 | to avoid interfering with what the user is doing. |
| 11869 | |
| 11870 | {options} is a dictionary. Supported entries: |
| 11871 | "repeat" Number of times to repeat calling the |
| 11872 | callback. -1 means forever. When not present |
| 11873 | the callback will be called once. |
| 11874 | If the timer causes an error three times in a |
| 11875 | row the repeat is cancelled. This avoids that |
| 11876 | Vim becomes unusable because of all the error |
| 11877 | messages. |
| 11878 | |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 11879 | Returns -1 on error. |
| 11880 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11881 | Example: > |
| 11882 | func MyHandler(timer) |
| 11883 | echo 'Handler called' |
| 11884 | endfunc |
| 11885 | let timer = timer_start(500, 'MyHandler', |
| 11886 | \ {'repeat': 3}) |
| 11887 | < This will invoke MyHandler() three times at 500 msec |
| 11888 | intervals. |
| 11889 | |
| 11890 | Can also be used as a |method|: > |
| 11891 | GetMsec()->timer_start(callback) |
| 11892 | |
| 11893 | < Not available in the |sandbox|. |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11894 | |
| 11895 | Return type: |Number| |
| 11896 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11897 | {only available when compiled with the |+timers| feature} |
| 11898 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11899 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11900 | timer_stop({timer}) *timer_stop()* |
| 11901 | Stop a timer. The timer callback will no longer be invoked. |
| 11902 | {timer} is an ID returned by timer_start(), thus it must be a |
| 11903 | Number. If {timer} does not exist there is no error. |
| 11904 | |
| 11905 | Can also be used as a |method|: > |
| 11906 | GetTimer()->timer_stop() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11907 | < |
| 11908 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11909 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11910 | {only available when compiled with the |+timers| feature} |
| 11911 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11912 | |
| 11913 | timer_stopall() *timer_stopall()* |
| 11914 | Stop all timers. The timer callbacks will no longer be |
| 11915 | invoked. Useful if a timer is misbehaving. If there are no |
| 11916 | timers there is no error. |
| 11917 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11918 | Return type: |Number| |
| 11919 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11920 | {only available when compiled with the |+timers| feature} |
| 11921 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11922 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11923 | tolower({expr}) *tolower()* |
| 11924 | The result is a copy of the String given, with all uppercase |
| 11925 | characters turned into lowercase (just like applying |gu| to |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 11926 | the string). Returns an empty string on error. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11927 | |
| 11928 | Can also be used as a |method|: > |
| 11929 | GetText()->tolower() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11930 | < |
| 11931 | Return type: |String| |
| 11932 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11933 | |
| 11934 | toupper({expr}) *toupper()* |
| 11935 | The result is a copy of the String given, with all lowercase |
| 11936 | characters turned into uppercase (just like applying |gU| to |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 11937 | the string). Returns an empty string on error. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11938 | |
| 11939 | Can also be used as a |method|: > |
| 11940 | GetText()->toupper() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11941 | < |
| 11942 | Return type: |String| |
| 11943 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11944 | |
| 11945 | tr({src}, {fromstr}, {tostr}) *tr()* |
| 11946 | The result is a copy of the {src} string with all characters |
| 11947 | which appear in {fromstr} replaced by the character in that |
| 11948 | position in the {tostr} string. Thus the first character in |
| 11949 | {fromstr} is translated into the first character in {tostr} |
| 11950 | and so on. Exactly like the unix "tr" command. |
| 11951 | This code also deals with multibyte characters properly. |
| 11952 | |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 11953 | Returns an empty string on error. |
| 11954 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11955 | Examples: > |
| 11956 | echo tr("hello there", "ht", "HT") |
| 11957 | < returns "Hello THere" > |
| 11958 | echo tr("<blob>", "<>", "{}") |
| 11959 | < returns "{blob}" |
| 11960 | |
| 11961 | Can also be used as a |method|: > |
| 11962 | GetText()->tr(from, to) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11963 | < |
| 11964 | Return type: |String| |
| 11965 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11966 | |
| 11967 | trim({text} [, {mask} [, {dir}]]) *trim()* |
| 11968 | Return {text} as a String where any character in {mask} is |
| 11969 | removed from the beginning and/or end of {text}. |
| 11970 | |
Illia Bobyr | 8079917 | 2023-10-17 18:00:50 +0200 | [diff] [blame] | 11971 | If {mask} is not given, or is an empty string, {mask} is all |
| 11972 | characters up to 0x20, which includes Tab, space, NL and CR, |
| 11973 | plus the non-breaking space character 0xa0. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11974 | |
| 11975 | The optional {dir} argument specifies where to remove the |
| 11976 | characters: |
| 11977 | 0 remove from the beginning and end of {text} |
| 11978 | 1 remove only at the beginning of {text} |
| 11979 | 2 remove only at the end of {text} |
| 11980 | When omitted both ends are trimmed. |
| 11981 | |
| 11982 | This function deals with multibyte characters properly. |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 11983 | Returns an empty string on error. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11984 | |
| 11985 | Examples: > |
| 11986 | echo trim(" some text ") |
| 11987 | < returns "some text" > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 11988 | echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") .. "_TAIL" |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 11989 | < returns "RESERVE_TAIL" > |
| 11990 | echo trim("rm<Xrm<>X>rrm", "rm<>") |
| 11991 | < returns "Xrm<>X" (characters in the middle are not removed) > |
| 11992 | echo trim(" vim ", " ", 2) |
| 11993 | < returns " vim" |
| 11994 | |
| 11995 | Can also be used as a |method|: > |
| 11996 | GetText()->trim() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 11997 | < |
| 11998 | Return type: |String| |
| 11999 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12000 | |
| 12001 | trunc({expr}) *trunc()* |
| 12002 | Return the largest integral value with magnitude less than or |
| 12003 | equal to {expr} as a |Float| (truncate towards zero). |
| 12004 | {expr} must evaluate to a |Float| or a |Number|. |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 12005 | Returns 0.0 if {expr} is not a |Float| or a |Number|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12006 | Examples: > |
| 12007 | echo trunc(1.456) |
| 12008 | < 1.0 > |
| 12009 | echo trunc(-5.456) |
| 12010 | < -5.0 > |
| 12011 | echo trunc(4.0) |
| 12012 | < 4.0 |
| 12013 | |
| 12014 | Can also be used as a |method|: > |
| 12015 | Compute()->trunc() |
| 12016 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12017 | Return type: |Float| |
| 12018 | |
| 12019 | |
Yegappan Lakshmanan | 1c2f475 | 2025-03-30 15:37:24 +0200 | [diff] [blame] | 12020 | tuple2list({tuple}) *tuple2list()* |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 12021 | Create a List from a shallow copy of the tuple items. |
| 12022 | Examples: > |
| 12023 | tuple2list((1, 2, 3)) returns [1, 2, 3] |
| 12024 | < |list2tuple()| does the opposite. |
| 12025 | |
| 12026 | This function doesn't recursively convert all the Tuple items |
| 12027 | in {tuple} to a List. Note that the items are identical |
| 12028 | between the list and the tuple, changing an item changes the |
| 12029 | contents of both the tuple and the list. |
| 12030 | |
| 12031 | Returns an empty list on error. |
| 12032 | |
| 12033 | Can also be used as a |method|: > |
| 12034 | GetTuple()->tuple2list() |
| 12035 | < |
| 12036 | Return type: list<{type}> (depending on the given |Tuple|) |
| 12037 | |
| 12038 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12039 | *type()* |
| 12040 | type({expr}) The result is a Number representing the type of {expr}. |
| 12041 | Instead of using the number directly, it is better to use the |
| 12042 | v:t_ variable that has the value: |
| 12043 | Number: 0 |v:t_number| |
| 12044 | String: 1 |v:t_string| |
| 12045 | Funcref: 2 |v:t_func| |
| 12046 | List: 3 |v:t_list| |
| 12047 | Dictionary: 4 |v:t_dict| |
| 12048 | Float: 5 |v:t_float| |
| 12049 | Boolean: 6 |v:t_bool| (v:false and v:true) |
| 12050 | None: 7 |v:t_none| (v:null and v:none) |
| 12051 | Job: 8 |v:t_job| |
| 12052 | Channel: 9 |v:t_channel| |
| 12053 | Blob: 10 |v:t_blob| |
h_east | 596a9f2 | 2023-11-21 21:24:23 +0900 | [diff] [blame] | 12054 | Class: 12 |v:t_class| |
| 12055 | Object: 13 |v:t_object| |
Yegappan Lakshmanan | 2a71b54 | 2023-12-14 20:03:03 +0100 | [diff] [blame] | 12056 | Typealias: 14 |v:t_typealias| |
Yegappan Lakshmanan | 3164cf8 | 2024-03-28 10:36:42 +0100 | [diff] [blame] | 12057 | Enum: 15 |v:t_enum| |
| 12058 | EnumValue: 16 |v:t_enumvalue| |
Yegappan Lakshmanan | 9cb865e | 2025-03-23 16:42:16 +0100 | [diff] [blame] | 12059 | Tuple: 17 |v:t_tuple| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12060 | For backward compatibility, this method can be used: > |
| 12061 | :if type(myvar) == type(0) |
| 12062 | :if type(myvar) == type("") |
| 12063 | :if type(myvar) == type(function("tr")) |
| 12064 | :if type(myvar) == type([]) |
| 12065 | :if type(myvar) == type({}) |
| 12066 | :if type(myvar) == type(0.0) |
| 12067 | :if type(myvar) == type(v:false) |
| 12068 | :if type(myvar) == type(v:none) |
| 12069 | < To check if the v:t_ variables exist use this: > |
| 12070 | :if exists('v:t_number') |
| 12071 | |
| 12072 | < Can also be used as a |method|: > |
| 12073 | mylist->type() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12074 | < |
| 12075 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12076 | |
| 12077 | |
| 12078 | typename({expr}) *typename()* |
| 12079 | Return a string representation of the type of {expr}. |
| 12080 | Example: > |
| 12081 | echo typename([1, 2, 3]) |
Kota Kato | 66bb9ae | 2023-01-17 18:31:56 +0000 | [diff] [blame] | 12082 | < list<number> ~ |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12083 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12084 | Return type: |String| |
| 12085 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12086 | |
| 12087 | undofile({name}) *undofile()* |
| 12088 | Return the name of the undo file that would be used for a file |
| 12089 | with name {name} when writing. This uses the 'undodir' |
| 12090 | option, finding directories that exist. It does not check if |
| 12091 | the undo file exists. |
| 12092 | {name} is always expanded to the full path, since that is what |
| 12093 | is used internally. |
| 12094 | If {name} is empty undofile() returns an empty string, since a |
| 12095 | buffer without a file name will not write an undo file. |
| 12096 | Useful in combination with |:wundo| and |:rundo|. |
| 12097 | When compiled without the |+persistent_undo| option this always |
| 12098 | returns an empty string. |
| 12099 | |
| 12100 | Can also be used as a |method|: > |
| 12101 | GetFilename()->undofile() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12102 | < |
| 12103 | Return type: |String| |
| 12104 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12105 | |
Devin J. Pohly | 5fee111 | 2023-04-23 20:26:59 -0500 | [diff] [blame] | 12106 | undotree([{buf}]) *undotree()* |
| 12107 | Return the current state of the undo tree for the current |
| 12108 | buffer, or for a specific buffer if {buf} is given. The |
| 12109 | result is a dictionary with the following items: |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12110 | "seq_last" The highest undo sequence number used. |
| 12111 | "seq_cur" The sequence number of the current position in |
| 12112 | the undo tree. This differs from "seq_last" |
| 12113 | when some changes were undone. |
| 12114 | "time_cur" Time last used for |:earlier| and related |
| 12115 | commands. Use |strftime()| to convert to |
| 12116 | something readable. |
| 12117 | "save_last" Number of the last file write. Zero when no |
| 12118 | write yet. |
| 12119 | "save_cur" Number of the current position in the undo |
| 12120 | tree. |
| 12121 | "synced" Non-zero when the last undo block was synced. |
| 12122 | This happens when waiting from input from the |
| 12123 | user. See |undo-blocks|. |
| 12124 | "entries" A list of dictionaries with information about |
| 12125 | undo blocks. |
| 12126 | |
| 12127 | The first item in the "entries" list is the oldest undo item. |
| 12128 | Each List item is a |Dictionary| with these items: |
| 12129 | "seq" Undo sequence number. Same as what appears in |
| 12130 | |:undolist|. |
| 12131 | "time" Timestamp when the change happened. Use |
| 12132 | |strftime()| to convert to something readable. |
| 12133 | "newhead" Only appears in the item that is the last one |
| 12134 | that was added. This marks the last change |
| 12135 | and where further changes will be added. |
| 12136 | "curhead" Only appears in the item that is the last one |
| 12137 | that was undone. This marks the current |
| 12138 | position in the undo tree, the block that will |
| 12139 | be used by a redo command. When nothing was |
| 12140 | undone after the last change this item will |
| 12141 | not appear anywhere. |
| 12142 | "save" Only appears on the last block before a file |
| 12143 | write. The number is the write count. The |
| 12144 | first write has number 1, the last one the |
| 12145 | "save_last" mentioned above. |
| 12146 | "alt" Alternate entry. This is again a List of undo |
| 12147 | blocks. Each item may again have an "alt" |
| 12148 | item. |
| 12149 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12150 | Return type: dict<any> |
| 12151 | |
| 12152 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12153 | uniq({list} [, {func} [, {dict}]]) *uniq()* *E882* |
| 12154 | Remove second and succeeding copies of repeated adjacent |
| 12155 | {list} items in-place. Returns {list}. If you want a list |
| 12156 | to remain unmodified make a copy first: > |
| 12157 | :let newlist = uniq(copy(mylist)) |
| 12158 | < The default compare function uses the string representation of |
| 12159 | each item. For the use of {func} and {dict} see |sort()|. |
Hirohito Higashi | 74f0a77 | 2025-06-23 21:42:36 +0200 | [diff] [blame] | 12160 | For deduplicating text in the current buffer see |:uniq|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12161 | |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 12162 | Returns zero if {list} is not a |List|. |
| 12163 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12164 | Can also be used as a |method|: > |
| 12165 | mylist->uniq() |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 12166 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12167 | Return type: list<{type}> |
| 12168 | |
| 12169 | |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 12170 | *utf16idx()* |
| 12171 | utf16idx({string}, {idx} [, {countcc} [, {charidx}]]) |
Yegappan Lakshmanan | 577922b | 2023-06-08 17:09:45 +0100 | [diff] [blame] | 12172 | Same as |charidx()| but returns the UTF-16 code unit index of |
| 12173 | the byte at {idx} in {string} (after converting it to UTF-16). |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 12174 | |
| 12175 | When {charidx} is present and TRUE, {idx} is used as the |
| 12176 | character index in the String {string} instead of as the byte |
| 12177 | index. |
Yegappan Lakshmanan | 9570703 | 2023-06-14 13:10:15 +0100 | [diff] [blame] | 12178 | An {idx} in the middle of a UTF-8 sequence is rounded |
| 12179 | downwards to the beginning of that sequence. |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 12180 | |
Yegappan Lakshmanan | 577922b | 2023-06-08 17:09:45 +0100 | [diff] [blame] | 12181 | Returns -1 if the arguments are invalid or if there are less |
| 12182 | than {idx} bytes in {string}. If there are exactly {idx} bytes |
| 12183 | the length of the string in UTF-16 code units is returned. |
| 12184 | |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 12185 | See |byteidx()| and |byteidxcomp()| for getting the byte index |
| 12186 | from the UTF-16 index and |charidx()| for getting the |
| 12187 | character index from the UTF-16 index. |
| 12188 | Refer to |string-offset-encoding| for more information. |
| 12189 | Examples: > |
| 12190 | echo utf16idx('a😊😊', 3) returns 2 |
| 12191 | echo utf16idx('a😊😊', 7) returns 4 |
| 12192 | echo utf16idx('a😊😊', 1, 0, 1) returns 2 |
| 12193 | echo utf16idx('a😊😊', 2, 0, 1) returns 4 |
| 12194 | echo utf16idx('aą́c', 6) returns 2 |
| 12195 | echo utf16idx('aą́c', 6, 1) returns 4 |
| 12196 | echo utf16idx('a😊😊', 9) returns -1 |
| 12197 | < |
| 12198 | Can also be used as a |method|: > |
| 12199 | GetName()->utf16idx(idx) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12200 | < |
| 12201 | Return type: |Number| |
Christian Brabandt | 67672ef | 2023-04-24 21:09:54 +0100 | [diff] [blame] | 12202 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12203 | |
| 12204 | values({dict}) *values()* |
| 12205 | Return a |List| with all the values of {dict}. The |List| is |
| 12206 | in arbitrary order. Also see |items()| and |keys()|. |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 12207 | Returns zero if {dict} is not a |Dict|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12208 | |
| 12209 | Can also be used as a |method|: > |
| 12210 | mydict->values() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12211 | < |
| 12212 | Return type: list<any> |
| 12213 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12214 | |
zeertzjq | 825cf81 | 2023-08-17 22:55:25 +0200 | [diff] [blame] | 12215 | virtcol({expr} [, {list} [, {winid}]]) *virtcol()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12216 | The result is a Number, which is the screen column of the file |
| 12217 | position given with {expr}. That is, the last screen position |
| 12218 | occupied by the character at that position, when the screen |
| 12219 | would be of unlimited width. When there is a <Tab> at the |
| 12220 | position, the returned Number will be the column at the end of |
| 12221 | the <Tab>. For example, for a <Tab> in column 1, with 'ts' |
| 12222 | set to 8, it returns 8. |conceal| is ignored. |
| 12223 | For the byte position use |col()|. |
LemonBoy | 0f7a3e1 | 2022-05-26 12:10:37 +0100 | [diff] [blame] | 12224 | |
zeertzjq | 02f3eba | 2024-06-12 20:45:24 +0200 | [diff] [blame] | 12225 | For the use of {expr} see |getpos()| and |col()|. |
zeertzjq | d353d27 | 2024-06-13 23:00:25 +0800 | [diff] [blame] | 12226 | When {expr} is "$", it means the end of the cursor line, so |
| 12227 | the result is the number of cells in the cursor line plus one. |
LemonBoy | 0f7a3e1 | 2022-05-26 12:10:37 +0100 | [diff] [blame] | 12228 | |
| 12229 | When 'virtualedit' is used {expr} can be [lnum, col, off], |
| 12230 | where "off" is the offset in screen columns from the start of |
| 12231 | the character. E.g., a position within a <Tab> or after the |
| 12232 | last character. When "off" is omitted zero is used. When |
| 12233 | Virtual editing is active in the current mode, a position |
| 12234 | beyond the end of the line can be returned. Also see |
| 12235 | |'virtualedit'| |
| 12236 | |
zeertzjq | 825cf81 | 2023-08-17 22:55:25 +0200 | [diff] [blame] | 12237 | If {list} is present and non-zero then virtcol() returns a |
| 12238 | List with the first and last screen position occupied by the |
LemonBoy | 0f7a3e1 | 2022-05-26 12:10:37 +0100 | [diff] [blame] | 12239 | character. |
| 12240 | |
zeertzjq | 825cf81 | 2023-08-17 22:55:25 +0200 | [diff] [blame] | 12241 | With the optional {winid} argument the values are obtained for |
| 12242 | that window instead of the current window. |
| 12243 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12244 | Note that only marks in the current file can be used. |
zeertzjq | 02f3eba | 2024-06-12 20:45:24 +0200 | [diff] [blame] | 12245 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12246 | Examples: > |
LemonBoy | 0f7a3e1 | 2022-05-26 12:10:37 +0100 | [diff] [blame] | 12247 | " With text "foo^Lbar" and cursor on the "^L": |
| 12248 | |
| 12249 | virtcol(".") " returns 5 |
| 12250 | virtcol(".", 1) " returns [4, 5] |
| 12251 | virtcol("$") " returns 9 |
| 12252 | |
| 12253 | " With text " there", with 't at 'h': |
| 12254 | |
| 12255 | virtcol("'t") " returns 6 |
zeertzjq | 02f3eba | 2024-06-12 20:45:24 +0200 | [diff] [blame] | 12256 | < |
| 12257 | The first column is 1. 0 or [0, 0] is returned for an error. |
| 12258 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12259 | A more advanced example that echoes the maximum length of |
| 12260 | all lines: > |
| 12261 | echo max(map(range(1, line('$')), "virtcol([v:val, '$'])")) |
| 12262 | |
| 12263 | < Can also be used as a |method|: > |
| 12264 | GetPos()->virtcol() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12265 | < |
| 12266 | Return type: |Number| |
| 12267 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12268 | |
Bram Moolenaar | 5a6ec10 | 2022-05-27 21:58:00 +0100 | [diff] [blame] | 12269 | virtcol2col({winid}, {lnum}, {col}) *virtcol2col()* |
| 12270 | The result is a Number, which is the byte index of the |
| 12271 | character in window {winid} at buffer line {lnum} and virtual |
| 12272 | column {col}. |
| 12273 | |
zeertzjq | b583eda | 2023-10-14 11:32:28 +0200 | [diff] [blame] | 12274 | If buffer line {lnum} is an empty line, 0 is returned. |
| 12275 | |
Bram Moolenaar | 5a6ec10 | 2022-05-27 21:58:00 +0100 | [diff] [blame] | 12276 | If {col} is greater than the last virtual column in line |
| 12277 | {lnum}, then the byte index of the character at the last |
| 12278 | virtual column is returned. |
| 12279 | |
Yegappan Lakshmanan | b209b86 | 2023-08-15 23:01:44 +0200 | [diff] [blame] | 12280 | For a multi-byte character, the column number of the first |
| 12281 | byte in the character is returned. |
| 12282 | |
Bram Moolenaar | 5a6ec10 | 2022-05-27 21:58:00 +0100 | [diff] [blame] | 12283 | The {winid} argument can be the window number or the |
| 12284 | |window-ID|. If this is zero, then the current window is used. |
| 12285 | |
| 12286 | Returns -1 if the window {winid} doesn't exist or the buffer |
| 12287 | line {lnum} or virtual column {col} is invalid. |
| 12288 | |
| 12289 | See also |screenpos()|, |virtcol()| and |col()|. |
| 12290 | |
| 12291 | Can also be used as a |method|: > |
| 12292 | GetWinid()->virtcol2col(lnum, col) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12293 | < |
| 12294 | Return type: |Number| |
| 12295 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12296 | |
| 12297 | visualmode([{expr}]) *visualmode()* |
| 12298 | The result is a String, which describes the last Visual mode |
| 12299 | used in the current buffer. Initially it returns an empty |
| 12300 | string, but once Visual mode has been used, it returns "v", |
| 12301 | "V", or "<CTRL-V>" (a single CTRL-V character) for |
| 12302 | character-wise, line-wise, or block-wise Visual mode |
| 12303 | respectively. |
| 12304 | Example: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 12305 | :exe "normal " .. visualmode() |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12306 | < This enters the same Visual mode as before. It is also useful |
| 12307 | in scripts if you wish to act differently depending on the |
| 12308 | Visual mode that was used. |
| 12309 | If Visual mode is active, use |mode()| to get the Visual mode |
| 12310 | (e.g., in a |:vmap|). |
| 12311 | If {expr} is supplied and it evaluates to a non-zero Number or |
| 12312 | a non-empty String, then the Visual mode will be cleared and |
| 12313 | the old value is returned. See |non-zero-arg|. |
| 12314 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12315 | Return type: |String| |
| 12316 | |
| 12317 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12318 | wildmenumode() *wildmenumode()* |
| 12319 | Returns |TRUE| when the wildmenu is active and |FALSE| |
| 12320 | otherwise. See 'wildmenu' and 'wildmode'. |
| 12321 | This can be used in mappings to handle the 'wildcharm' option |
| 12322 | gracefully. (Makes only sense with |mapmode-c| mappings). |
| 12323 | |
| 12324 | For example to make <c-j> work like <down> in wildmode, use: > |
| 12325 | :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>" |
| 12326 | < |
Milly | 6c2fc37 | 2024-10-16 22:11:17 +0200 | [diff] [blame] | 12327 | (Note: this needs the 'wildcharm' option set appropriately). |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12328 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12329 | Return type: |Number| |
| 12330 | |
| 12331 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12332 | win_execute({id}, {command} [, {silent}]) *win_execute()* |
| 12333 | Like `execute()` but in the context of window {id}. |
| 12334 | The window will temporarily be made the current window, |
| 12335 | without triggering autocommands or changing directory. When |
| 12336 | executing {command} autocommands will be triggered, this may |
Bram Moolenaar | b7398fe | 2023-05-14 18:50:25 +0100 | [diff] [blame] | 12337 | have unexpected side effects. Use `:noautocmd` if needed. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12338 | Example: > |
| 12339 | call win_execute(winid, 'set syntax=python') |
| 12340 | < Doing the same with `setwinvar()` would not trigger |
| 12341 | autocommands and not actually show syntax highlighting. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12342 | *E994* |
| 12343 | Not all commands are allowed in popup windows. |
| 12344 | When window {id} does not exist then no error is given and |
| 12345 | an empty string is returned. |
| 12346 | |
| 12347 | Can also be used as a |method|, the base is passed as the |
| 12348 | second argument: > |
| 12349 | GetCommand()->win_execute(winid) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12350 | < |
| 12351 | Return type: |String| |
| 12352 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12353 | |
| 12354 | win_findbuf({bufnr}) *win_findbuf()* |
| 12355 | Returns a |List| with |window-ID|s for windows that contain |
| 12356 | buffer {bufnr}. When there is none the list is empty. |
| 12357 | |
| 12358 | Can also be used as a |method|: > |
| 12359 | GetBufnr()->win_findbuf() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12360 | < |
| 12361 | Return type: list<number> or list<any> |
| 12362 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12363 | |
| 12364 | win_getid([{win} [, {tab}]]) *win_getid()* |
| 12365 | Get the |window-ID| for the specified window. |
| 12366 | When {win} is missing use the current window. |
| 12367 | With {win} this is the window number. The top window has |
| 12368 | number 1. |
| 12369 | Without {tab} use the current tab, otherwise the tab with |
| 12370 | number {tab}. The first tab has number one. |
| 12371 | Return zero if the window cannot be found. |
| 12372 | |
| 12373 | Can also be used as a |method|: > |
| 12374 | GetWinnr()->win_getid() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12375 | < |
| 12376 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12377 | |
| 12378 | |
| 12379 | win_gettype([{nr}]) *win_gettype()* |
| 12380 | Return the type of the window: |
| 12381 | "autocmd" autocommand window. Temporary window |
| 12382 | used to execute autocommands. |
| 12383 | "command" command-line window |cmdwin| |
| 12384 | (empty) normal window |
| 12385 | "loclist" |location-list-window| |
| 12386 | "popup" popup window |popup| |
| 12387 | "preview" preview window |preview-window| |
| 12388 | "quickfix" |quickfix-window| |
| 12389 | "unknown" window {nr} not found |
| 12390 | |
| 12391 | When {nr} is omitted return the type of the current window. |
| 12392 | When {nr} is given return the type of this window by number or |
| 12393 | |window-ID|. |
| 12394 | |
| 12395 | Also see the 'buftype' option. When running a terminal in a |
| 12396 | popup window then 'buftype' is "terminal" and win_gettype() |
| 12397 | returns "popup". |
| 12398 | |
| 12399 | Can also be used as a |method|: > |
| 12400 | GetWinid()->win_gettype() |
| 12401 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12402 | Return type: |String| |
| 12403 | |
| 12404 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12405 | win_gotoid({expr}) *win_gotoid()* |
| 12406 | Go to window with ID {expr}. This may also change the current |
| 12407 | tabpage. |
| 12408 | Return TRUE if successful, FALSE if the window cannot be found. |
| 12409 | |
| 12410 | Can also be used as a |method|: > |
| 12411 | GetWinid()->win_gotoid() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12412 | < |
| 12413 | Return type: |Number| |
| 12414 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12415 | |
| 12416 | win_id2tabwin({expr}) *win_id2tabwin()* |
| 12417 | Return a list with the tab number and window number of window |
| 12418 | with ID {expr}: [tabnr, winnr]. |
| 12419 | Return [0, 0] if the window cannot be found. |
| 12420 | |
| 12421 | Can also be used as a |method|: > |
| 12422 | GetWinid()->win_id2tabwin() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12423 | < |
| 12424 | Return type: list<number> |
| 12425 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12426 | |
| 12427 | win_id2win({expr}) *win_id2win()* |
| 12428 | Return the window number of window with ID {expr}. |
| 12429 | Return 0 if the window cannot be found in the current tabpage. |
| 12430 | |
| 12431 | Can also be used as a |method|: > |
| 12432 | GetWinid()->win_id2win() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12433 | < |
| 12434 | Return type: |Number| |
| 12435 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12436 | |
Daniel Steinberg | ee63031 | 2022-01-10 13:36:34 +0000 | [diff] [blame] | 12437 | win_move_separator({nr}, {offset}) *win_move_separator()* |
| 12438 | Move window {nr}'s vertical separator (i.e., the right border) |
| 12439 | by {offset} columns, as if being dragged by the mouse. {nr} |
| 12440 | can be a window number or |window-ID|. A positive {offset} |
| 12441 | moves right and a negative {offset} moves left. Moving a |
| 12442 | window's vertical separator will change the width of the |
| 12443 | window and the width of other windows adjacent to the vertical |
| 12444 | separator. The magnitude of movement may be smaller than |
| 12445 | specified (e.g., as a consequence of maintaining |
| 12446 | 'winminwidth'). Returns TRUE if the window can be found and |
| 12447 | FALSE otherwise. |
Bram Moolenaar | d592deb | 2022-06-17 15:42:40 +0100 | [diff] [blame] | 12448 | This will fail for the rightmost window and a full-width |
| 12449 | window, since it has no separator on the right. |
Bram Moolenaar | 76db9e0 | 2022-11-09 21:21:04 +0000 | [diff] [blame] | 12450 | Only works for the current tab page. *E1308* |
Daniel Steinberg | ee63031 | 2022-01-10 13:36:34 +0000 | [diff] [blame] | 12451 | |
| 12452 | Can also be used as a |method|: > |
| 12453 | GetWinnr()->win_move_separator(offset) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12454 | < |
| 12455 | Return type: |Number| |
| 12456 | |
Daniel Steinberg | ee63031 | 2022-01-10 13:36:34 +0000 | [diff] [blame] | 12457 | |
| 12458 | win_move_statusline({nr}, {offset}) *win_move_statusline()* |
| 12459 | Move window {nr}'s status line (i.e., the bottom border) by |
| 12460 | {offset} rows, as if being dragged by the mouse. {nr} can be a |
| 12461 | window number or |window-ID|. A positive {offset} moves down |
| 12462 | and a negative {offset} moves up. Moving a window's status |
| 12463 | line will change the height of the window and the height of |
| 12464 | other windows adjacent to the status line. The magnitude of |
| 12465 | movement may be smaller than specified (e.g., as a consequence |
| 12466 | of maintaining 'winminheight'). Returns TRUE if the window can |
| 12467 | be found and FALSE otherwise. |
Bram Moolenaar | 76db9e0 | 2022-11-09 21:21:04 +0000 | [diff] [blame] | 12468 | Only works for the current tab page. |
Daniel Steinberg | ee63031 | 2022-01-10 13:36:34 +0000 | [diff] [blame] | 12469 | |
| 12470 | Can also be used as a |method|: > |
| 12471 | GetWinnr()->win_move_statusline(offset) |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12472 | < |
| 12473 | Return type: |Number| |
| 12474 | |
Daniel Steinberg | ee63031 | 2022-01-10 13:36:34 +0000 | [diff] [blame] | 12475 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12476 | win_screenpos({nr}) *win_screenpos()* |
| 12477 | Return the screen position of window {nr} as a list with two |
| 12478 | numbers: [row, col]. The first window always has position |
| 12479 | [1, 1], unless there is a tabline, then it is [2, 1]. |
| 12480 | {nr} can be the window number or the |window-ID|. Use zero |
| 12481 | for the current window. |
Sean Dewar | 5866bc3 | 2024-03-13 20:17:24 +0100 | [diff] [blame] | 12482 | Returns [0, 0] if the window cannot be found. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12483 | |
| 12484 | Can also be used as a |method|: > |
| 12485 | GetWinid()->win_screenpos() |
| 12486 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12487 | Return type: list<number> |
| 12488 | |
| 12489 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12490 | win_splitmove({nr}, {target} [, {options}]) *win_splitmove()* |
Sean Dewar | 96cc4ae | 2024-02-20 21:52:31 +0100 | [diff] [blame] | 12491 | Temporarily switch to window {target}, then move window {nr} |
| 12492 | to a new split adjacent to {target}. |
| 12493 | Unlike commands such as |:split|, no new windows are created |
| 12494 | (the |window-ID| of window {nr} is unchanged after the move). |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12495 | |
| 12496 | Both {nr} and {target} can be window numbers or |window-ID|s. |
| 12497 | Both must be in the current tab page. |
| 12498 | |
| 12499 | Returns zero for success, non-zero for failure. |
| 12500 | |
| 12501 | {options} is a |Dictionary| with the following optional entries: |
| 12502 | "vertical" When TRUE, the split is created vertically, |
| 12503 | like with |:vsplit|. |
| 12504 | "rightbelow" When TRUE, the split is made below or to the |
| 12505 | right (if vertical). When FALSE, it is done |
| 12506 | above or to the left (if vertical). When not |
| 12507 | present, the values of 'splitbelow' and |
| 12508 | 'splitright' are used. |
| 12509 | |
| 12510 | Can also be used as a |method|: > |
| 12511 | GetWinid()->win_splitmove(target) |
| 12512 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12513 | Return type: |Number| |
| 12514 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12515 | |
| 12516 | *winbufnr()* |
| 12517 | winbufnr({nr}) The result is a Number, which is the number of the buffer |
| 12518 | associated with window {nr}. {nr} can be the window number or |
| 12519 | the |window-ID|. |
| 12520 | When {nr} is zero, the number of the buffer in the current |
| 12521 | window is returned. |
| 12522 | When window {nr} doesn't exist, -1 is returned. |
| 12523 | Example: > |
| 12524 | :echo "The file in the current window is " . bufname(winbufnr(0)) |
| 12525 | < |
| 12526 | Can also be used as a |method|: > |
| 12527 | FindWindow()->winbufnr()->bufname() |
| 12528 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12529 | Return type: |Number| |
| 12530 | |
| 12531 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12532 | *wincol()* |
| 12533 | wincol() The result is a Number, which is the virtual column of the |
| 12534 | cursor in the window. This is counting screen cells from the |
| 12535 | left side of the window. The leftmost column is one. |
| 12536 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12537 | Return type: |Number| |
| 12538 | |
| 12539 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12540 | *windowsversion()* |
| 12541 | windowsversion() |
| 12542 | The result is a String. For MS-Windows it indicates the OS |
| 12543 | version. E.g, Windows 10 is "10.0", Windows 8 is "6.2", |
| 12544 | Windows XP is "5.1". For non-MS-Windows systems the result is |
| 12545 | an empty string. |
| 12546 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12547 | Return type: |String| |
| 12548 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12549 | winheight({nr}) *winheight()* |
| 12550 | The result is a Number, which is the height of window {nr}. |
| 12551 | {nr} can be the window number or the |window-ID|. |
| 12552 | When {nr} is zero, the height of the current window is |
| 12553 | returned. When window {nr} doesn't exist, -1 is returned. |
| 12554 | An existing window always has a height of zero or more. |
| 12555 | This excludes any window toolbar line. |
| 12556 | Examples: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 12557 | :echo "The current window has " .. winheight(0) .. " lines." |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12558 | |
| 12559 | < Can also be used as a |method|: > |
| 12560 | GetWinid()->winheight() |
| 12561 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12562 | Return type: |Number| |
| 12563 | |
| 12564 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12565 | winlayout([{tabnr}]) *winlayout()* |
| 12566 | The result is a nested List containing the layout of windows |
| 12567 | in a tabpage. |
| 12568 | |
| 12569 | Without {tabnr} use the current tabpage, otherwise the tabpage |
| 12570 | with number {tabnr}. If the tabpage {tabnr} is not found, |
| 12571 | returns an empty list. |
| 12572 | |
| 12573 | For a leaf window, it returns: |
| 12574 | ['leaf', {winid}] |
| 12575 | For horizontally split windows, which form a column, it |
| 12576 | returns: |
| 12577 | ['col', [{nested list of windows}]] |
| 12578 | For vertically split windows, which form a row, it returns: |
| 12579 | ['row', [{nested list of windows}]] |
| 12580 | |
| 12581 | Example: > |
| 12582 | " Only one window in the tab page |
| 12583 | :echo winlayout() |
| 12584 | ['leaf', 1000] |
| 12585 | " Two horizontally split windows |
| 12586 | :echo winlayout() |
| 12587 | ['col', [['leaf', 1000], ['leaf', 1001]]] |
| 12588 | " The second tab page, with three horizontally split |
| 12589 | " windows, with two vertically split windows in the |
| 12590 | " middle window |
| 12591 | :echo winlayout(2) |
| 12592 | ['col', [['leaf', 1002], ['row', [['leaf', 1003], |
| 12593 | ['leaf', 1001]]], ['leaf', 1000]]] |
| 12594 | < |
| 12595 | Can also be used as a |method|: > |
| 12596 | GetTabnr()->winlayout() |
| 12597 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12598 | Return type: list<any> |
| 12599 | |
| 12600 | |
| 12601 | winline() *winline()* |
| 12602 | The result is a Number, which is the screen line of the cursor |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12603 | in the window. This is counting screen lines from the top of |
| 12604 | the window. The first line is one. |
| 12605 | If the cursor was moved the view on the file will be updated |
| 12606 | first, this may cause a scroll. |
| 12607 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12608 | Return type: |Number| |
| 12609 | |
| 12610 | |
| 12611 | winnr([{arg}]) *winnr()* |
| 12612 | The result is a Number, which is the number of the current |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12613 | window. The top window has number 1. |
| 12614 | Returns zero for a popup window. |
| 12615 | |
| 12616 | The optional argument {arg} supports the following values: |
| 12617 | $ the number of the last window (the window |
| 12618 | count). |
| 12619 | # the number of the last accessed window (where |
| 12620 | |CTRL-W_p| goes to). If there is no previous |
| 12621 | window or it is in another tab page 0 is |
Sean Dewar | d64801e | 2024-03-12 20:46:12 +0100 | [diff] [blame] | 12622 | returned. May refer to the current window in |
| 12623 | some cases (e.g. when evaluating 'statusline' |
| 12624 | expressions). |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12625 | {N}j the number of the Nth window below the |
| 12626 | current window (where |CTRL-W_j| goes to). |
| 12627 | {N}k the number of the Nth window above the current |
| 12628 | window (where |CTRL-W_k| goes to). |
| 12629 | {N}h the number of the Nth window left of the |
| 12630 | current window (where |CTRL-W_h| goes to). |
| 12631 | {N}l the number of the Nth window right of the |
| 12632 | current window (where |CTRL-W_l| goes to). |
| 12633 | The number can be used with |CTRL-W_w| and ":wincmd w" |
| 12634 | |:wincmd|. |
Bram Moolenaar | 016188f | 2022-06-06 20:52:59 +0100 | [diff] [blame] | 12635 | When {arg} is invalid an error is given and zero is returned. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12636 | Also see |tabpagewinnr()| and |win_getid()|. |
| 12637 | Examples: > |
| 12638 | let window_count = winnr('$') |
| 12639 | let prev_window = winnr('#') |
| 12640 | let wnum = winnr('3k') |
| 12641 | |
| 12642 | < Can also be used as a |method|: > |
| 12643 | GetWinval()->winnr() |
| 12644 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12645 | Return type: |Number| |
| 12646 | |
| 12647 | |
| 12648 | winrestcmd() *winrestcmd()* |
| 12649 | Returns a sequence of |:resize| commands that should restore |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12650 | the current window sizes. Only works properly when no windows |
| 12651 | are opened or closed and the current window and tab page is |
| 12652 | unchanged. |
| 12653 | Example: > |
| 12654 | :let cmd = winrestcmd() |
| 12655 | :call MessWithWindowSizes() |
| 12656 | :exe cmd |
| 12657 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12658 | Return type: |String| |
| 12659 | |
| 12660 | |
| 12661 | winrestview({dict}) *winrestview()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12662 | Uses the |Dictionary| returned by |winsaveview()| to restore |
| 12663 | the view of the current window. |
| 12664 | Note: The {dict} does not have to contain all values, that are |
| 12665 | returned by |winsaveview()|. If values are missing, those |
| 12666 | settings won't be restored. So you can use: > |
| 12667 | :call winrestview({'curswant': 4}) |
| 12668 | < |
| 12669 | This will only set the curswant value (the column the cursor |
| 12670 | wants to move on vertical movements) of the cursor to column 5 |
| 12671 | (yes, that is 5), while all other settings will remain the |
| 12672 | same. This is useful, if you set the cursor position manually. |
| 12673 | |
| 12674 | If you have changed the values the result is unpredictable. |
| 12675 | If the window size changed the result won't be the same. |
| 12676 | |
| 12677 | Can also be used as a |method|: > |
| 12678 | GetView()->winrestview() |
| 12679 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12680 | Return type: |Number| |
| 12681 | |
| 12682 | |
| 12683 | winsaveview() *winsaveview()* |
| 12684 | Returns a |Dictionary| that contains information to restore |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12685 | the view of the current window. Use |winrestview()| to |
| 12686 | restore the view. |
| 12687 | This is useful if you have a mapping that jumps around in the |
| 12688 | buffer and you want to go back to the original view. |
| 12689 | This does not save fold information. Use the 'foldenable' |
| 12690 | option to temporarily switch off folding, so that folds are |
| 12691 | not opened when moving around. This may have side effects. |
| 12692 | The return value includes: |
| 12693 | lnum cursor line number |
| 12694 | col cursor column (Note: the first column |
naohiro ono | 56200ee | 2022-01-01 14:59:44 +0000 | [diff] [blame] | 12695 | zero, as opposed to what |getcurpos()| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12696 | returns) |
| 12697 | coladd cursor column offset for 'virtualedit' |
naohiro ono | 56200ee | 2022-01-01 14:59:44 +0000 | [diff] [blame] | 12698 | curswant column for vertical movement (Note: |
| 12699 | the first column is zero, as opposed |
| 12700 | to what |getcurpos()| returns). After |
| 12701 | |$| command it will be a very large |
| 12702 | number equal to |v:maxcol|. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12703 | topline first line in the window |
| 12704 | topfill filler lines, only in diff mode |
| 12705 | leftcol first column displayed; only used when |
| 12706 | 'wrap' is off |
| 12707 | skipcol columns skipped |
| 12708 | Note that no option values are saved. |
| 12709 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12710 | Return type: dict<number> |
| 12711 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12712 | |
| 12713 | winwidth({nr}) *winwidth()* |
| 12714 | The result is a Number, which is the width of window {nr}. |
| 12715 | {nr} can be the window number or the |window-ID|. |
| 12716 | When {nr} is zero, the width of the current window is |
| 12717 | returned. When window {nr} doesn't exist, -1 is returned. |
| 12718 | An existing window always has a width of zero or more. |
| 12719 | Examples: > |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 12720 | :echo "The current window has " .. winwidth(0) .. " columns." |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12721 | :if winwidth(0) <= 50 |
| 12722 | : 50 wincmd | |
| 12723 | :endif |
| 12724 | < For getting the terminal or screen size, see the 'columns' |
| 12725 | option. |
| 12726 | |
| 12727 | Can also be used as a |method|: > |
| 12728 | GetWinid()->winwidth() |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12729 | < |
| 12730 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12731 | |
| 12732 | |
| 12733 | wordcount() *wordcount()* |
| 12734 | The result is a dictionary of byte/chars/word statistics for |
| 12735 | the current buffer. This is the same info as provided by |
| 12736 | |g_CTRL-G| |
| 12737 | The return value includes: |
| 12738 | bytes Number of bytes in the buffer |
| 12739 | chars Number of chars in the buffer |
| 12740 | words Number of words in the buffer |
| 12741 | cursor_bytes Number of bytes before cursor position |
| 12742 | (not in Visual mode) |
| 12743 | cursor_chars Number of chars before cursor position |
| 12744 | (not in Visual mode) |
| 12745 | cursor_words Number of words before cursor position |
| 12746 | (not in Visual mode) |
| 12747 | visual_bytes Number of bytes visually selected |
| 12748 | (only in Visual mode) |
| 12749 | visual_chars Number of chars visually selected |
| 12750 | (only in Visual mode) |
| 12751 | visual_words Number of words visually selected |
| 12752 | (only in Visual mode) |
| 12753 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12754 | Return type: dict<number> |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12755 | |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12756 | |
| 12757 | writefile({object}, {fname} [, {flags}]) *writefile()* |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12758 | When {object} is a |List| write it to file {fname}. Each list |
| 12759 | item is separated with a NL. Each list item must be a String |
| 12760 | or Number. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12761 | All NL characters are replaced with a NUL character. |
| 12762 | Inserting CR characters needs to be done before passing {list} |
| 12763 | to writefile(). |
Bram Moolenaar | 806a273 | 2022-09-04 15:40:36 +0100 | [diff] [blame] | 12764 | |
| 12765 | When {object} is a |Blob| write the bytes to file {fname} |
| 12766 | unmodified, also when binary mode is not specified. |
| 12767 | |
| 12768 | {flags} must be a String. These characters are recognized: |
| 12769 | |
| 12770 | 'b' Binary mode is used: There will not be a NL after the |
| 12771 | last list item. An empty item at the end does cause the |
| 12772 | last line in the file to end in a NL. |
| 12773 | |
| 12774 | 'a' Append mode is used, lines are appended to the file: > |
| 12775 | :call writefile(["foo"], "event.log", "a") |
| 12776 | :call writefile(["bar"], "event.log", "a") |
| 12777 | < |
| 12778 | 'D' Delete the file when the current function ends. This |
| 12779 | works like: > |
Bram Moolenaar | 938ae28 | 2023-02-20 20:44:55 +0000 | [diff] [blame] | 12780 | :defer delete({fname}) |
Bram Moolenaar | 806a273 | 2022-09-04 15:40:36 +0100 | [diff] [blame] | 12781 | < Fails when not in a function. Also see |:defer|. |
| 12782 | |
| 12783 | 's' fsync() is called after writing the file. This flushes |
| 12784 | the file to disk, if possible. This takes more time but |
| 12785 | avoids losing the file if the system crashes. |
| 12786 | |
| 12787 | 'S' fsync() is not called, even when 'fsync' is set. |
| 12788 | |
| 12789 | When {flags} does not contain "S" or "s" then fsync() is |
| 12790 | called if the 'fsync' option is set. |
| 12791 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12792 | An existing file is overwritten, if possible. |
Bram Moolenaar | 806a273 | 2022-09-04 15:40:36 +0100 | [diff] [blame] | 12793 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12794 | When the write fails -1 is returned, otherwise 0. There is an |
| 12795 | error message if the file can't be created or when writing |
| 12796 | fails. |
Bram Moolenaar | 806a273 | 2022-09-04 15:40:36 +0100 | [diff] [blame] | 12797 | |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12798 | Also see |readfile()|. |
| 12799 | To copy a file byte for byte: > |
| 12800 | :let fl = readfile("foo", "b") |
| 12801 | :call writefile(fl, "foocopy", "b") |
| 12802 | |
| 12803 | < Can also be used as a |method|: > |
| 12804 | GetText()->writefile("thefile") |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12805 | < |
| 12806 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12807 | |
| 12808 | |
| 12809 | xor({expr}, {expr}) *xor()* |
| 12810 | Bitwise XOR on the two arguments. The arguments are converted |
| 12811 | to a number. A List, Dict or Float argument causes an error. |
Bram Moolenaar | 5a6ec10 | 2022-05-27 21:58:00 +0100 | [diff] [blame] | 12812 | Also see `and()` and `or()`. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12813 | Example: > |
| 12814 | :let bits = xor(bits, 0x80) |
| 12815 | < |
| 12816 | Can also be used as a |method|: > |
| 12817 | :let bits = bits->xor(0x80) |
| 12818 | < |
Christian Brabandt | 5674c9a | 2024-06-09 00:13:43 +0200 | [diff] [blame] | 12819 | Return type: |Number| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12820 | |
| 12821 | ============================================================================== |
| 12822 | 3. Feature list *feature-list* |
| 12823 | |
| 12824 | There are three types of features: |
| 12825 | 1. Features that are only supported when they have been enabled when Vim |
| 12826 | was compiled |+feature-list|. Example: > |
| 12827 | :if has("cindent") |
| 12828 | < *gui_running* |
| 12829 | 2. Features that are only supported when certain conditions have been met. |
| 12830 | Example: > |
| 12831 | :if has("gui_running") |
| 12832 | < *has-patch* |
| 12833 | 3. Beyond a certain version or at a certain version and including a specific |
| 12834 | patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or |
| 12835 | later, or it is version 7.4 and patch 248 was included. Example: > |
| 12836 | :if has("patch-7.4.248") |
| 12837 | < Note that it's possible for patch 248 to be omitted even though 249 is |
| 12838 | included. Only happens when cherry-picking patches. |
| 12839 | Note that this form only works for patch 7.4.237 and later, before that |
| 12840 | you need to check for the patch and the v:version. Example (checking |
| 12841 | version 6.2.148 or later): > |
| 12842 | :if v:version > 602 || (v:version == 602 && has("patch148")) |
| 12843 | |
| 12844 | Hint: To find out if Vim supports backslashes in a file name (MS-Windows), |
| 12845 | use: `if exists('+shellslash')` |
| 12846 | |
| 12847 | |
| 12848 | acl Compiled with |ACL| support. |
Bram Moolenaar | 2ee347f | 2022-08-26 17:53:44 +0100 | [diff] [blame] | 12849 | all_builtin_terms Compiled with all builtin terminals enabled. (always |
| 12850 | true) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12851 | amiga Amiga version of Vim. |
| 12852 | arabic Compiled with Arabic support |Arabic|. |
| 12853 | arp Compiled with ARP support (Amiga). |
| 12854 | autocmd Compiled with autocommand support. (always true) |
| 12855 | autochdir Compiled with support for 'autochdir' |
| 12856 | autoservername Automatically enable |clientserver| |
| 12857 | balloon_eval Compiled with |balloon-eval| support. |
| 12858 | balloon_multiline GUI supports multiline balloons. |
| 12859 | beos BeOS version of Vim. |
| 12860 | browse Compiled with |:browse| support, and browse() will |
| 12861 | work. |
| 12862 | browsefilter Compiled with support for |browsefilter|. |
| 12863 | bsd Compiled on an OS in the BSD family (excluding macOS). |
Bram Moolenaar | 2ee347f | 2022-08-26 17:53:44 +0100 | [diff] [blame] | 12864 | builtin_terms Compiled with some builtin terminals. (always true) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12865 | byte_offset Compiled with support for 'o' in 'statusline' |
| 12866 | channel Compiled with support for |channel| and |job| |
Bram Moolenaar | e1dc76f | 2022-06-25 18:01:32 +0100 | [diff] [blame] | 12867 | cindent Compiled with 'cindent' support. (always true) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12868 | clientserver Compiled with remote invocation support |clientserver|. |
| 12869 | clipboard Compiled with 'clipboard' support. |
| 12870 | clipboard_working Compiled with 'clipboard' support and it can be used. |
| 12871 | cmdline_compl Compiled with |cmdline-completion| support. |
| 12872 | cmdline_hist Compiled with |cmdline-history| support. |
| 12873 | cmdline_info Compiled with 'showcmd' and 'ruler' support. |
| 12874 | comments Compiled with |'comments'| support. |
| 12875 | compatible Compiled to be very Vi compatible. |
| 12876 | conpty Platform where |ConPTY| can be used. |
| 12877 | cryptv Compiled with encryption support |encryption|. |
| 12878 | cscope Compiled with |cscope| support. |
| 12879 | cursorbind Compiled with |'cursorbind'| (always true) |
| 12880 | debug Compiled with "DEBUG" defined. |
| 12881 | dialog_con Compiled with console dialog support. |
glepnir | df46115 | 2024-04-04 22:23:29 +0200 | [diff] [blame] | 12882 | dialog_con_gui Compiled with console and GUI dialog support. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12883 | dialog_gui Compiled with GUI dialog support. |
| 12884 | diff Compiled with |vimdiff| and 'diff' support. |
| 12885 | digraphs Compiled with support for digraphs. |
| 12886 | directx Compiled with support for DirectX and 'renderoptions'. |
| 12887 | dnd Compiled with support for the "~ register |quote_~|. |
| 12888 | drop_file Compiled with |drop_file| support. |
| 12889 | ebcdic Compiled on a machine with ebcdic character set. |
| 12890 | emacs_tags Compiled with support for Emacs tags. |
| 12891 | eval Compiled with expression evaluation support. Always |
| 12892 | true, of course! |
| 12893 | ex_extra |+ex_extra| (always true) |
| 12894 | extra_search Compiled with support for |'incsearch'| and |
| 12895 | |'hlsearch'| |
| 12896 | farsi Support for Farsi was removed |farsi|. |
Bram Moolenaar | f80f40a | 2022-08-25 16:02:23 +0100 | [diff] [blame] | 12897 | file_in_path Compiled with support for |gf| and |<cfile>| (always |
| 12898 | true) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12899 | filterpipe When 'shelltemp' is off pipes are used for shell |
| 12900 | read/write/filter commands |
| 12901 | find_in_path Compiled with support for include file searches |
| 12902 | |+find_in_path|. |
| 12903 | float Compiled with support for |Float|. |
| 12904 | fname_case Case in file names matters (for Amiga and MS-Windows |
| 12905 | this is not present). |
| 12906 | folding Compiled with |folding| support. |
| 12907 | footer Compiled with GUI footer support. |gui-footer| |
| 12908 | fork Compiled to use fork()/exec() instead of system(). |
| 12909 | gettext Compiled with message translation |multi-lang| |
| 12910 | gui Compiled with GUI enabled. |
Bram Moolenaar | cbaff5e | 2022-04-08 17:45:08 +0100 | [diff] [blame] | 12911 | gui_athena Compiled with Athena GUI (always false). |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12912 | gui_gnome Compiled with Gnome support (gui_gtk is also defined). |
| 12913 | gui_gtk Compiled with GTK+ GUI (any version). |
| 12914 | gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined). |
| 12915 | gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined). |
| 12916 | gui_haiku Compiled with Haiku GUI. |
| 12917 | gui_mac Compiled with Macintosh GUI. |
| 12918 | gui_motif Compiled with Motif GUI. |
| 12919 | gui_photon Compiled with Photon GUI. |
| 12920 | gui_running Vim is running in the GUI, or it will start soon. |
| 12921 | gui_win32 Compiled with MS-Windows Win32 GUI. |
| 12922 | gui_win32s idem, and Win32s system being used (Windows 3.1) |
| 12923 | haiku Haiku version of Vim. |
| 12924 | hangul_input Compiled with Hangul input support. |hangul| |
| 12925 | hpux HP-UX version of Vim. |
Zhaoming Luo | a41dfcd | 2025-02-06 21:39:35 +0100 | [diff] [blame] | 12926 | hurd GNU/Hurd version of Vim |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12927 | iconv Can use iconv() for conversion. |
| 12928 | insert_expand Compiled with support for CTRL-X expansion commands in |
| 12929 | Insert mode. (always true) |
| 12930 | job Compiled with support for |channel| and |job| |
| 12931 | ipv6 Compiled with support for IPv6 networking in |channel|. |
Bram Moolenaar | e1dc76f | 2022-06-25 18:01:32 +0100 | [diff] [blame] | 12932 | jumplist Compiled with |jumplist| support. (always true) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12933 | keymap Compiled with 'keymap' support. |
| 12934 | lambda Compiled with |lambda| support. |
| 12935 | langmap Compiled with 'langmap' support. |
| 12936 | libcall Compiled with |libcall()| support. |
| 12937 | linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and |
| 12938 | 'breakindent' support. |
| 12939 | linux Linux version of Vim. |
| 12940 | lispindent Compiled with support for lisp indenting. |
Bram Moolenaar | e1dc76f | 2022-06-25 18:01:32 +0100 | [diff] [blame] | 12941 | (always true) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12942 | listcmds Compiled with commands for the buffer list |:files| |
| 12943 | and the argument list |arglist|. |
| 12944 | localmap Compiled with local mappings and abbr. |:map-local| |
| 12945 | lua Compiled with Lua interface |Lua|. |
| 12946 | mac Any Macintosh version of Vim cf. osx |
| 12947 | macunix Synonym for osxdarwin |
| 12948 | menu Compiled with support for |:menu|. |
| 12949 | mksession Compiled with support for |:mksession|. |
| 12950 | modify_fname Compiled with file name modifiers. |filename-modifiers| |
| 12951 | (always true) |
| 12952 | mouse Compiled with support for mouse. |
| 12953 | mouse_dec Compiled with support for Dec terminal mouse. |
| 12954 | mouse_gpm Compiled with support for gpm (Linux console mouse) |
| 12955 | mouse_gpm_enabled GPM mouse is working |
| 12956 | mouse_netterm Compiled with support for netterm mouse. |
| 12957 | mouse_pterm Compiled with support for qnx pterm mouse. |
| 12958 | mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse) |
| 12959 | mouse_sgr Compiled with support for sgr mouse. |
| 12960 | mouse_urxvt Compiled with support for urxvt mouse. |
| 12961 | mouse_xterm Compiled with support for xterm mouse. |
| 12962 | mouseshape Compiled with support for 'mouseshape'. |
| 12963 | multi_byte Compiled with support for 'encoding' (always true) |
| 12964 | multi_byte_encoding 'encoding' is set to a multibyte encoding. |
| 12965 | multi_byte_ime Compiled with support for IME input method. |
| 12966 | multi_lang Compiled with support for multiple languages. |
| 12967 | mzscheme Compiled with MzScheme interface |mzscheme|. |
| 12968 | nanotime Compiled with sub-second time stamp checks. |
| 12969 | netbeans_enabled Compiled with support for |netbeans| and connected. |
| 12970 | netbeans_intg Compiled with support for |netbeans|. |
Bram Moolenaar | e1dc76f | 2022-06-25 18:01:32 +0100 | [diff] [blame] | 12971 | num64 Compiled with 64-bit |Number| support. (always true) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12972 | ole Compiled with OLE automation support for Win32. |
| 12973 | osx Compiled for macOS cf. mac |
| 12974 | osxdarwin Compiled for macOS, with |mac-darwin-feature| |
| 12975 | packages Compiled with |packages| support. |
| 12976 | path_extra Compiled with up/downwards search in 'path' and 'tags' |
| 12977 | perl Compiled with Perl interface. |
| 12978 | persistent_undo Compiled with support for persistent undo history. |
| 12979 | postscript Compiled with PostScript file printing. |
| 12980 | printer Compiled with |:hardcopy| support. |
| 12981 | profile Compiled with |:profile| support. |
Bram Moolenaar | 71badf9 | 2023-04-22 22:40:14 +0100 | [diff] [blame] | 12982 | prof_nsec Profile results are in nanoseconds. |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12983 | python Python 2.x interface available. |has-python| |
| 12984 | python_compiled Compiled with Python 2.x interface. |has-python| |
| 12985 | python_dynamic Python 2.x interface is dynamically loaded. |has-python| |
| 12986 | python3 Python 3.x interface available. |has-python| |
| 12987 | python3_compiled Compiled with Python 3.x interface. |has-python| |
| 12988 | python3_dynamic Python 3.x interface is dynamically loaded. |has-python| |
Yee Cheng Chin | c13b3d1 | 2023-08-20 21:18:38 +0200 | [diff] [blame] | 12989 | python3_stable Python 3.x interface is using Python Stable ABI. |has-python| |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 12990 | pythonx Python 2.x and/or 3.x interface available. |python_x| |
| 12991 | qnx QNX version of Vim. |
| 12992 | quickfix Compiled with |quickfix| support. |
| 12993 | reltime Compiled with |reltime()| support. |
| 12994 | rightleft Compiled with 'rightleft' support. |
| 12995 | ruby Compiled with Ruby interface |ruby|. |
| 12996 | scrollbind Compiled with 'scrollbind' support. (always true) |
| 12997 | showcmd Compiled with 'showcmd' support. |
| 12998 | signs Compiled with |:sign| support. |
Bram Moolenaar | e1dc76f | 2022-06-25 18:01:32 +0100 | [diff] [blame] | 12999 | smartindent Compiled with 'smartindent' support. (always true) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 13000 | sodium Compiled with libsodium for better crypt support |
| 13001 | sound Compiled with sound support, e.g. `sound_playevent()` |
| 13002 | spell Compiled with spell checking support |spell|. |
| 13003 | startuptime Compiled with |--startuptime| support. |
| 13004 | statusline Compiled with support for 'statusline', 'rulerformat' |
| 13005 | and special formats of 'titlestring' and 'iconstring'. |
| 13006 | sun SunOS version of Vim. |
| 13007 | sun_workshop Support for Sun |workshop| has been removed. |
| 13008 | syntax Compiled with syntax highlighting support |syntax|. |
| 13009 | syntax_items There are active syntax highlighting items for the |
| 13010 | current buffer. |
| 13011 | system Compiled to use system() instead of fork()/exec(). |
| 13012 | tag_binary Compiled with binary searching in tags files |
Bram Moolenaar | e1dc76f | 2022-06-25 18:01:32 +0100 | [diff] [blame] | 13013 | |tag-binary-search|. (always true) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 13014 | tag_old_static Support for old static tags was removed, see |
| 13015 | |tag-old-static|. |
| 13016 | tcl Compiled with Tcl interface. |
| 13017 | termguicolors Compiled with true color in terminal support. |
| 13018 | terminal Compiled with |terminal| support. |
| 13019 | terminfo Compiled with terminfo instead of termcap. |
| 13020 | termresponse Compiled with support for |t_RV| and |v:termresponse|. |
| 13021 | textobjects Compiled with support for |text-objects|. |
| 13022 | textprop Compiled with support for |text-properties|. |
| 13023 | tgetent Compiled with tgetent support, able to use a termcap |
| 13024 | or terminfo file. |
| 13025 | timers Compiled with |timer_start()| support. |
| 13026 | title Compiled with window title support |'title'|. |
Bram Moolenaar | e1dc76f | 2022-06-25 18:01:32 +0100 | [diff] [blame] | 13027 | (always true) |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 13028 | toolbar Compiled with support for |gui-toolbar|. |
| 13029 | ttyin input is a terminal (tty) |
| 13030 | ttyout output is a terminal (tty) |
| 13031 | unix Unix version of Vim. *+unix* |
| 13032 | unnamedplus Compiled with support for "unnamedplus" in 'clipboard' |
| 13033 | user_commands User-defined commands. (always true) |
| 13034 | vartabs Compiled with variable tabstop support |'vartabstop'|. |
| 13035 | vcon Win32: Virtual console support is working, can use |
| 13036 | 'termguicolors'. Also see |+vtp|. |
| 13037 | vertsplit Compiled with vertically split windows |:vsplit|. |
| 13038 | (always true) |
| 13039 | vim_starting True while initial source'ing takes place. |startup| |
| 13040 | *vim_starting* |
Bram Moolenaar | a6feb16 | 2022-01-02 12:06:33 +0000 | [diff] [blame] | 13041 | vim9script Compiled with |Vim9| script support |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 13042 | viminfo Compiled with viminfo support. |
| 13043 | vimscript-1 Compiled Vim script version 1 support |
| 13044 | vimscript-2 Compiled Vim script version 2 support |
| 13045 | vimscript-3 Compiled Vim script version 3 support |
Bram Moolenaar | 8a3b805 | 2022-06-26 12:21:15 +0100 | [diff] [blame] | 13046 | vimscript-4 Compiled Vim script version 4 support |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 13047 | virtualedit Compiled with 'virtualedit' option. (always true) |
| 13048 | visual Compiled with Visual mode. (always true) |
| 13049 | visualextra Compiled with extra Visual mode commands. (always |
| 13050 | true) |blockwise-operators|. |
| 13051 | vms VMS version of Vim. |
| 13052 | vreplace Compiled with |gR| and |gr| commands. (always true) |
| 13053 | vtp Compiled for vcon support |+vtp| (check vcon to find |
| 13054 | out if it works in the current console). |
Foxe Chen | b90c239 | 2025-06-27 21:10:35 +0200 | [diff] [blame] | 13055 | wayland Compiled with Wayland protocol support. |
Hirohito Higashi | 73b9650 | 2025-06-28 18:18:21 +0200 | [diff] [blame] | 13056 | wayland_clipboard Compiled with support for Wayland selections/clipboard |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 13057 | wildignore Compiled with 'wildignore' option. |
| 13058 | wildmenu Compiled with 'wildmenu' option. |
| 13059 | win16 old version for MS-Windows 3.1 (always false) |
| 13060 | win32 Win32 version of Vim (MS-Windows 95 and later, 32 or |
| 13061 | 64 bits) |
| 13062 | win32unix Win32 version of Vim, using Unix files (Cygwin) |
| 13063 | win64 Win64 version of Vim (MS-Windows 64 bit). |
| 13064 | win95 Win32 version for MS-Windows 95/98/ME (always false) |
| 13065 | winaltkeys Compiled with 'winaltkeys' option. |
| 13066 | windows Compiled with support for more than one window. |
| 13067 | (always true) |
| 13068 | writebackup Compiled with 'writebackup' default on. |
Christian Brabandt | e085dfd | 2023-09-30 12:49:18 +0200 | [diff] [blame] | 13069 | xattr Compiled with extended attributes support |xattr| |
| 13070 | (currently only supported on Linux). |
Bram Moolenaar | 1cae5a0 | 2021-12-27 21:28:34 +0000 | [diff] [blame] | 13071 | xfontset Compiled with X fontset support |xfontset|. |
| 13072 | xim Compiled with X input method support |xim|. |
| 13073 | xpm Compiled with pixmap support. |
| 13074 | xpm_w32 Compiled with pixmap support for Win32. (Only for |
| 13075 | backward compatibility. Use "xpm" instead.) |
| 13076 | xsmp Compiled with X session management support. |
| 13077 | xsmp_interact Compiled with interactive X session management support. |
| 13078 | xterm_clipboard Compiled with support for xterm clipboard. |
| 13079 | xterm_save Compiled with support for saving and restoring the |
| 13080 | xterm screen. |
| 13081 | x11 Compiled with X11 support. |
| 13082 | |
| 13083 | |
| 13084 | ============================================================================== |
| 13085 | 4. Matching a pattern in a String *string-match* |
| 13086 | |
| 13087 | This is common between several functions. A regexp pattern as explained at |
| 13088 | |pattern| is normally used to find a match in the buffer lines. When a |
| 13089 | pattern is used to find a match in a String, almost everything works in the |
| 13090 | same way. The difference is that a String is handled like it is one line. |
| 13091 | When it contains a "\n" character, this is not seen as a line break for the |
| 13092 | pattern. It can be matched with a "\n" in the pattern, or with ".". Example: |
| 13093 | > |
| 13094 | :let a = "aaaa\nxxxx" |
| 13095 | :echo matchstr(a, "..\n..") |
| 13096 | aa |
| 13097 | xx |
| 13098 | :echo matchstr(a, "a.x") |
| 13099 | a |
| 13100 | x |
| 13101 | |
| 13102 | Don't forget that "^" will only match at the first character of the String and |
| 13103 | "$" at the last character of the string. They don't match after or before a |
| 13104 | "\n". |
| 13105 | |
| 13106 | vim:tw=78:ts=8:noet:ft=help:norl: |