builtin.lua (11362B)
1 ---@meta 2 -- luacheck: no unused args 3 4 error('Cannot require a meta file') 5 6 --- @brief <pre>help 7 --- vim.api.{func}({...}) *vim.api* 8 --- Invokes Nvim |API| function {func} with arguments {...}. 9 --- Example: call the "nvim_get_current_line()" API function: >lua 10 --- print(tostring(vim.api.nvim_get_current_line())) 11 --- 12 --- vim.NIL *vim.NIL* 13 --- Special value representing NIL in |RPC| and |v:null| in Vimscript 14 --- conversion, and similar cases. Lua `nil` cannot be used as part of a Lua 15 --- table representing a Dictionary or Array, because it is treated as 16 --- missing: `{"foo", nil}` is the same as `{"foo"}`. 17 --- 18 --- vim.type_idx *vim.type_idx* 19 --- Type index for use in |lua-special-tbl|. Specifying one of the values from 20 --- |vim.types| allows typing the empty table (it is unclear whether empty Lua 21 --- table represents empty list or empty array) and forcing integral numbers 22 --- to be |Float|. See |lua-special-tbl| for more details. 23 --- 24 --- vim.val_idx *vim.val_idx* 25 --- Value index for tables representing |Float|s. A table representing 26 --- floating-point value 1.0 looks like this: >lua 27 --- { 28 --- [vim.type_idx] = vim.types.float, 29 --- [vim.val_idx] = 1.0, 30 --- } 31 --- < See also |vim.type_idx| and |lua-special-tbl|. 32 --- 33 --- vim.types *vim.types* 34 --- Table with possible values for |vim.type_idx|. Contains two sets of 35 --- key-value pairs: first maps possible values for |vim.type_idx| to 36 --- human-readable strings, second maps human-readable type names to values 37 --- for |vim.type_idx|. Currently contains pairs for `float`, `array` and 38 --- `dictionary` types. 39 --- 40 --- Note: One must expect that values corresponding to `vim.types.float`, 41 --- `vim.types.array` and `vim.types.dictionary` fall under only two following 42 --- assumptions: 43 --- 1. Value may serve both as a key and as a value in a table. Given the 44 --- properties of Lua tables this basically means “value is not `nil`”. 45 --- 2. For each value in `vim.types` table `vim.types[vim.types[value]]` is the 46 --- same as `value`. 47 --- No other restrictions are put on types, and it is not guaranteed that 48 --- values corresponding to `vim.types.float`, `vim.types.array` and 49 --- `vim.types.dictionary` will not change or that `vim.types` table will only 50 --- contain values for these three types. 51 --- 52 --- *log_levels* *vim.log.levels* 53 --- Log levels are one of the values defined in `vim.log.levels`: 54 --- 55 --- vim.log.levels.DEBUG 56 --- vim.log.levels.ERROR 57 --- vim.log.levels.INFO 58 --- vim.log.levels.TRACE 59 --- vim.log.levels.WARN 60 --- vim.log.levels.OFF 61 --- 62 --- </pre> 63 64 ---@nodoc 65 ---@class vim.NIL 66 67 ---@type vim.NIL 68 ---@nodoc 69 vim.NIL = ... 70 71 --- Returns true if the code is executing as part of a "fast" event handler, 72 --- where most of the API is disabled. These are low-level events (e.g. 73 --- |lua-loop-callbacks|) which can be invoked whenever Nvim polls for input. 74 --- When this is `false` most API functions are callable (but may be subject 75 --- to other restrictions such as |textlock|). 76 function vim.in_fast_event() end 77 78 --- Creates a special empty table (marked with a metatable), which Nvim 79 --- converts to an empty dictionary when translating Lua values to Vimscript 80 --- or API types. Nvim by default converts an empty table `{}` without this 81 --- metatable to an list/array. 82 --- 83 --- Note: If numeric keys are present in the table, Nvim ignores the metatable 84 --- marker and converts the dict to a list/array anyway. 85 --- @return table 86 function vim.empty_dict() end 87 88 --- Sends {event} to {channel} via |RPC| and returns immediately. If {channel} 89 --- is 0, the event is broadcast to all channels. 90 --- 91 --- This function also works in a fast callback |lua-loop-callbacks|. 92 --- @param channel integer 93 --- @param method string 94 --- @param ...? any 95 function vim.rpcnotify(channel, method, ...) end 96 97 --- Invokes |RPC| `method` on `channel` and blocks until a response is received. 98 --- 99 --- Note: Msgpack NIL values in the response are represented as |vim.NIL|. 100 --- 101 --- Example: see [nvim_exec_lua()] 102 --- 103 --- @param channel integer 104 --- @param method string 105 --- @param ...? any 106 function vim.rpcrequest(channel, method, ...) end 107 108 --- Compares strings case-insensitively. 109 --- @param a string 110 --- @param b string 111 --- @return 0|1|-1 112 --- if strings are 113 --- equal, {a} is greater than {b} or {a} is lesser than {b}, respectively. 114 function vim.stricmp(a, b) end 115 116 --- Gets a list of the starting byte positions of each UTF-8 codepoint in the given string. 117 --- 118 --- Embedded NUL bytes are treated as terminating the string. 119 --- @param str string 120 --- @return integer[] 121 function vim.str_utf_pos(str) end 122 123 --- Gets the distance (in bytes) from the starting byte of the codepoint (character) that {index} 124 --- points to. 125 --- 126 --- The result can be added to {index} to get the starting byte of a character. 127 --- 128 --- Examples: 129 --- 130 --- ```lua 131 --- -- The character 'æ' is stored as the bytes '\xc3\xa6' (using UTF-8) 132 --- 133 --- -- Returns 0 because the index is pointing at the first byte of a character 134 --- vim.str_utf_start('æ', 1) 135 --- 136 --- -- Returns -1 because the index is pointing at the second byte of a character 137 --- vim.str_utf_start('æ', 2) 138 --- ``` 139 --- 140 --- @param str string 141 --- @param index integer 142 --- @return integer 143 function vim.str_utf_start(str, index) end 144 145 --- Gets the distance (in bytes) from the last byte of the codepoint (character) that {index} points 146 --- to. 147 --- 148 --- Examples: 149 --- 150 --- ```lua 151 --- -- The character 'æ' is stored as the bytes '\xc3\xa6' (using UTF-8) 152 --- 153 --- -- Returns 0 because the index is pointing at the last byte of a character 154 --- vim.str_utf_end('æ', 2) 155 --- 156 --- -- Returns 1 because the index is pointing at the penultimate byte of a character 157 --- vim.str_utf_end('æ', 1) 158 --- ``` 159 --- 160 --- @param str string 161 --- @param index integer 162 --- @return integer 163 function vim.str_utf_end(str, index) end 164 165 --- The result is a String, which is the text {str} converted from 166 --- encoding {from} to encoding {to}. When the conversion fails `nil` is 167 --- returned. When some characters could not be converted they 168 --- are replaced with "?". 169 --- The encoding names are whatever the iconv() library function 170 --- can accept, see ":Man 3 iconv". 171 --- 172 --- @param str string Text to convert 173 --- @param from string Encoding of {str} 174 --- @param to string Target encoding 175 --- @return string? : Converted string if conversion succeeds, `nil` otherwise. 176 function vim.iconv(str, from, to, opts) end 177 178 --- Schedules {fn} to be invoked soon by the main event-loop. Useful 179 --- to avoid |textlock| or other temporary restrictions. 180 --- @param fn fun() 181 --- @return nil result 182 --- @return string? err Error message if scheduling failed, `nil` otherwise. 183 function vim.schedule(fn) end 184 185 --- Waits up to `time` milliseconds, until `callback` returns `true` (success). Executes 186 --- `callback` immediately, then on user events, internal events, and approximately every 187 --- `interval` milliseconds (default 200). Returns all `callback` results on success. 188 --- 189 --- Nvim processes other events while waiting. 190 --- Cannot be called during an |api-fast| event. 191 --- 192 --- Examples: 193 --- 194 --- ```lua 195 --- -- Wait for 100 ms, allowing other events to process. 196 --- vim.wait(100) 197 --- 198 --- -- Wait up to 1000 ms or until `vim.g.foo` is true, at intervals of ~500 ms. 199 --- vim.wait(1000, function() return vim.g.foo end, 500) 200 --- 201 --- -- Wait indefinitely until `vim.g.foo` is true, and get the callback results. 202 --- local ok, rv1, rv2, rv3 = vim.wait(math.huge, function() 203 --- return vim.g.foo, 'a', 42, { ok = { 'yes' } } 204 --- end) 205 --- 206 --- -- Schedule a function to set a value in 100ms. This would wait 10s if blocked, but actually 207 --- -- only waits 100ms because `vim.wait` processes other events while waiting. 208 --- vim.defer_fn(function() vim.g.timer_result = true end, 100) 209 --- if vim.wait(10000, function() return vim.g.timer_result end) then 210 --- print('Only waiting a little bit of time!') 211 --- end 212 --- ``` 213 --- 214 --- @param time number Number of milliseconds to wait. Must be non-negative number, any fractional 215 --- part is truncated. 216 --- @param callback? fun(): boolean, ... Optional callback. Waits until {callback} returns true 217 --- @param interval? integer (Approximate) number of milliseconds to wait between polls 218 --- @param fast_only? boolean If true, only |api-fast| events will be processed. 219 --- @return boolean, nil|-1|-2, ... 220 --- - If callback returns `true` before timeout: `true, nil, ...` 221 --- - On timeout: `false, -1` 222 --- - On interrupt: `false, -2` 223 --- - On error: the error is raised. 224 function vim.wait(time, callback, interval, fast_only) end 225 226 --- Subscribe to |ui-events|, similar to |nvim_ui_attach()| but receive events in a Lua callback. 227 --- Used to implement screen elements like popupmenu or message handling in Lua. 228 --- 229 --- {callback} receives event name plus additional parameters. See |ui-popupmenu| 230 --- and the sections below for event format for respective events. 231 --- 232 --- Callbacks for `msg_show` events originating from internal messages (as 233 --- opposed to events from commands or API calls) are executed in |api-fast| 234 --- context; showing the message needs to be scheduled. 235 --- 236 --- Excessive errors inside the callback will result in forced detachment. 237 --- 238 --- WARNING: This api is considered experimental. Usability will vary for 239 --- different screen elements. In particular `ext_messages` behavior is subject 240 --- to further changes and usability improvements. This is expected to be 241 --- used to handle messages when setting 'cmdheight' to zero (which is 242 --- likewise experimental). 243 --- 244 --- Example (stub for a |ui-popupmenu| implementation): 245 --- 246 --- ```lua 247 --- ns = vim.api.nvim_create_namespace('my_fancy_pum') 248 --- 249 --- vim.ui_attach(ns, {ext_popupmenu=true}, function(event, ...) 250 --- if event == 'popupmenu_show' then 251 --- local items, selected, row, col, grid = ... 252 --- print('display pum ', #items) 253 --- elseif event == 'popupmenu_select' then 254 --- local selected = ... 255 --- print('selected', selected) 256 --- elseif event == 'popupmenu_hide' then 257 --- print('FIN') 258 --- end 259 --- end) 260 --- ``` 261 --- 262 --- @since 0 263 --- 264 --- @param ns integer Namespace ID 265 --- @param opts table<string, any> Optional parameters. 266 --- - {ext_…}? (`boolean`) Any of |ui-ext-options|, if true 267 --- enable events for the respective UI element. 268 --- - {set_cmdheight}? (`boolean`) If false, avoid setting 269 --- 'cmdheight' to 0 when `ext_messages` is enabled. 270 --- @param callback fun(event: string, ...): any Function called for each UI event. 271 --- A truthy return value signals to Nvim that the event is handled, 272 --- in which case it is not propagated to remote UIs. 273 function vim.ui_attach(ns, opts, callback) end 274 275 --- Detach a callback previously attached with |vim.ui_attach()| for the 276 --- given namespace {ns}. 277 --- @param ns integer Namespace ID 278 function vim.ui_detach(ns) end