Run {cmd} and add an error message to v:errors if it does NOT produce a beep or visual bell. Also see assert_fails(), assert_nobeep() and assert-return.

When {expected} and {actual} are not equal an error message is added to v:errors and 1 is returned. Otherwise zero is returned assert-return. There is no automatic conversion, the String "4" is different from the Number 4. And the number 4 is different from the Float 4.0. The value of 'ignorecase' is not used here, case always matters. When {msg} is omitted an error in the form "Expected {expected} but got {actual}" is produced. Example:

When the files {fname-one} and {fname-two} do not contain exactly the same text an error message is added to v:errors. Also see assert-return. When {fname-one} or {fname-two} does not exist the error will mention that. Mainly useful with terminal-diff.

When v:exception does not contain the string {error} an error message is added to v:errors. Also see assert-return. This can be used to assert that a command throws an exception. Using the error number, followed by a colon, avoids problems with translations:

Run {cmd} and add an error message to v:errors if it does NOT produce an error or when {error} is not found in the error message. Also see assert-return.

When {actual} is not false an error message is added to v:errors, like with assert_equal(). Also see assert-return. A value is false when it is zero. When {actual} is not a number the assert fails. When {msg} is omitted an error in the form "Expected False but got {actual}" is produced.

This asserts number and Float values. When {actual} is lower than {lower} or higher than {upper} an error message is added to v:errors. Also see assert-return. When {msg} is omitted an error in the form "Expected range {lower} - {upper}, but got {actual}" is produced.

When {pattern} does not match {actual} an error message is added to v:errors. Also see assert-return.

Run {cmd} and add an error message to v:errors if it produces a beep or visual bell. Also see assert_beeps().

The opposite of assert_equal(): add an error message to v:errors when {expected} and {actual} are equal. Also see assert-return.

The opposite of assert_match(): add an error message to v:errors when {pattern} matches {actual}. Also see assert-return.

Report a test failure directly, using String {msg}. Always returns one.

When {actual} is not true an error message is added to v:errors, like with assert_equal(). Also see assert-return. A value is TRUE when it is a non-zero number. When {actual} is not a number the assert fails. When {msg} is omitted an error in the form "Expected True but got {actual}" is produced.

Adds a List of autocmds and autocmd groups.

Deletes a List of autocmds and autocmd groups.

Returns a List of autocmds. If {opts} is not supplied, then returns the autocmds for all the events in all the groups.

Return the current text in the balloon. Only for the string, not used for the List. Returns an empty string if balloon is not present.

Show {expr} inside the balloon. For the GUI {expr} is used as a string. For a terminal {expr} can be a list, which contains the lines of the balloon. If {expr} is not a list it will be split with balloon_split(). If {expr} is an empty string any existing balloon is removed.

Split String {msg} into lines to be displayed in a balloon. The splits are made for the current window size and optimize to show debugger output. Returns a List with the split lines. Returns an empty List on error. Can also be used as a method:

Return a List containing the number value of each byte in Blob {blob}. Examples:

Return non-zero when there is something to read from {handle}. {handle} can be a Channel or a Job that has a Channel.

Close {handle}. See channel-close. {handle} can be a Channel or a Job that has a Channel. A close callback is not invoked.

Close the "in" part of {handle}. See channel-close-in. {handle} can be a Channel or a Job that has a Channel. A close callback is not invoked.

Send {expr} over {handle}. The {expr} is encoded according to the type of channel. The function cannot be used with a raw channel. See channel-use. {handle} can be a Channel or a Job that has a Channel. When using the "lsp" channel mode, {expr} must be a Dict.

Send {string} over {handle}. {handle} can be a Channel or a Job that has a Channel.

Get the buffer number that {handle} is using for String {what}. {handle} can be a Channel or a Job that has a Channel. {what} can be "err" for stderr, "out" for stdout or empty for socket output. Returns -1 when there is no buffer.

Get the Job associated with {channel}. If there is no job calling job_status() on the returned Job will result in "fail".

Returns a Dictionary with information about {handle}. The items are: "id" number of the channel "status" "open", "buffered" or "closed", like ch_status() When opened with ch_open(): "hostname" the hostname of the address "port" the port of the address "path" the path of the Unix-domain socket "sock_status" "open" or "closed" "sock_mode" "NL", "RAW", "JSON" or "JS" "sock_io" "socket" "sock_timeout" timeout in msec

Write String {msg} in the channel log file, if it was opened with ch_logfile(). The text "ch_log():" is prepended to the message to make clear it came from this function call and make it easier to find in the log file. When {handle} is passed the channel number is used for the message. {handle} can be a Channel or a Job that has a Channel. The Channel must be open for the channel number to be used.

Start logging channel activity to {fname}. When {fname} is an empty string: stop logging.

Open a channel to {address}. See channel. Returns a Channel. Use ch_status() to check for failure.

Read from {handle} and return the received message. {handle} can be a Channel or a Job that has a Channel. For a NL channel this waits for a NL to arrive, except when there is nothing more to read (channel was closed). See channel-more.

Like ch_read() but reads binary data and returns a Blob. See channel-more.

Like ch_read() but for a JS and JSON channel does not decode the message. For a NL channel it does not block waiting for the NL to arrive, but otherwise works like ch_read(). See channel-more.

Send {expr} over {handle}. The {expr} is encoded according to the type of channel. The function cannot be used with a raw channel. See channel-use. {handle} can be a Channel or a Job that has a Channel. When using the "lsp" channel mode, {expr} must be a Dict.

Send String or Blob {expr} over {handle}. Works like ch_sendexpr(), but does not encode the request or decode the response. The caller is responsible for the correct contents. Also does not add a newline for a channel in NL mode, the caller must do that. The NL in the response is removed. See channel-use.

Set options on {handle}: "callback" the channel callback "timeout" default read timeout in msec "mode" mode for the whole channel See ch_open() for more explanation. {handle} can be a Channel or a Job that has a Channel.

Return the status of {handle}: "fail" failed to open the channel "open" channel can be used "buffered" channel can be read, not written to "closed" channel can not be used {handle} can be a Channel or a Job that has a Channel. "buffered" is used when the channel was closed but there is still data that can be obtained with ch_read().

Output {string} as-is, including unprintable characters. This can be used to output a terminal code. For example, to disable modifyOtherKeys:

Like exists() but evaluated at compile time. This is useful to skip a block where a function is used that would otherwise give an error:

Like extend() but instead of adding items to {expr1} a new List or Dictionary is created and returned. {expr1} remains unchanged.

Like flatten() but first make a copy of {list}.

Move the Vim window to the foreground. Useful when sent from a client to a Vim server. remote_send() On Win32 systems this might not work, the OS does not always allow a window to bring itself to the foreground. Use remote_foreground() instead. only in the Win32, Motif and GTK GUI versions and the Win32 console version

Just like getbufline() but only get one line and return it as a string.

Returns a List of cell widths of character ranges overridden by setcellwidths(). The format is equal to the argument of setcellwidths(). If no character ranges have their cell widths overridden, an empty List is returned.

The result is a Number, which is TRUE when the IME status is active and FALSE otherwise. See 'imstatusfunc'.

Returns the name of the currently showing mouse pointer. When the +mouseshape feature is not supported or the shape is unknown an empty string is returned. This function is mainly intended for testing.

Returns a List with information about all the sourced Vim scripts in the order they were sourced, like what :scriptnames shows.

Translate String {text} if possible. This is mainly for use in the distributed Vim scripts. When generating message translations the {text} is extracted by xgettext, the translator can add the translated message in the .po file and Vim will lookup the translation when gettext() is called. For {text} double quoted strings are preferred, because xgettext does not understand escaping in single quoted strings.

Returns a List of all the highlight group attributes. If the optional {name} is specified, then returns a List with only the attributes of the specified highlight group. Returns an empty List if the highlight group {name} is not present.

Creates or modifies the attributes of a List of highlight groups. Each item in {list} is a dictionary containing the attributes of a highlight group. See hlget() for the list of supported items in this dictionary.

Returns the index of an item in {object} where {expr} is v:true. {object} must be a List or a Blob.

Like input(), but when the GUI is running and text dialogs are supported, a dialog window pops up to input the text. Example:

The result is a Number, which is TRUE when {path} is an absolute path. On Unix, a path is considered absolute when it starts with '/'. On MS-Windows, it is considered absolute when it starts with an optional drive prefix and is followed by a '' or '/'. UNC paths are always absolute. Example:

Get the channel handle that {job} is using. To check if the job has no channel:

Returns a Dictionary with information about {job}: "status" what job_status() returns "channel" what job_getchannel() returns "cmd" List of command arguments used to start the job "process" process ID "tty_in" terminal input name, empty when none "tty_out" terminal output name, empty when none "exitval" only valid when "status" is "dead" "exit_cb" function to be called on exit "stoponexit" job-stoponexit

Change options for {job}. Supported are: "stoponexit" job-stoponexit "exit_cb" job-exit_cb

Start a job and return a Job object. Unlike system() and :!cmd this does not wait for the job to finish. To start a job in a terminal window see term_start().

Returns a String with the status of {job}: "run" job is running "fail" job failed to start "dead" job died or was stopped after running

Stop the {job}. This can also be used to signal the job.

This is similar to json_decode() with these differences:

• Object key names do not have to be in quotes.
• Strings can be in single quotes.
• Empty items in an array (between two commas) are allowed and result in v:none items.

This is similar to json_encode() with these differences:

• Object key names are not in quotes.
• v:none items in an array result in an empty item between commas. For example, the Vim object: [1,v:none,{"one":1},v:none] Will be encoded as: [1,,{one:1},,] While json_encode() would produce: [1,null,{"one":1},null] This encoding is valid for JavaScript. It is more efficient than JSON, especially when using an array with optional items.

Return a Blob concatenating all the number values in {list}. Examples:

Add a callback function that will be invoked when changes have been made to buffer {buf}. {buf} refers to a buffer name or number. For the accepted values, see bufname(). When {buf} is omitted the current buffer is used. Returns a unique ID that can be passed to listener_remove().

Invoke listener callbacks for buffer {buf}. If there are no pending changes then no callbacks are invoked.

Remove a listener previously added with listener_add(). Returns FALSE when {id} could not be found, TRUE when {id} was removed.

Evaluate Lua expression {expr} and return its result converted to Vim data structures. Second {expr} may hold additional argument accessible as _A inside first {expr}. Strings are returned as they are. Boolean objects are converted to numbers. Numbers are converted to Float values. Dictionaries and lists obtained by vim.eval() are returned as-is. Other objects are returned as zero without any errors. See lua-luaeval for more details. Note that in a :def function local variables are not visible to {expr}.

Returns a List of all mappings. Each List item is a Dict, the same as what is returned by maparg(), see mapping-dict. When {abbr} is there and it is TRUE use abbreviations instead of mappings.

Like map() but instead of replacing items in {expr1} a new List or Dictionary is created and returned. {expr1} remains unchanged. Items can still be changed by {expr2}, if you don't want that use deepcopy() first.

Evaluate MzScheme expression {expr} and return its result converted to Vim data structures. Numbers and strings are returned as they are. Pairs (including lists and improper lists) and vectors are returned as Vim Lists. Hash tables are represented as Vim Dictionary type with keys converted to strings. All other types are converted to string with display function. Examples:

Attach a text property at position {lnum}, {col}. {col} is counted in bytes, use one for the first column. If {lnum} is invalid an error is given. If {col} is invalid an error is given.

Similar to prop_add(), but attaches a text property at multiple positions in a buffer.

Remove all text properties from line {lnum}. When {lnum-end} is given, remove all text properties from line {lnum} to {lnum-end} (inclusive).

Search for a text property as specified with {props}: id property with this ID type property with this type name both "id" and "type" must both match bufnr buffer to search in; when present a start position with "lnum" and "col" must be given; when omitted the current buffer is used lnum start in this line (when omitted start at the cursor) col start at this column (when omitted and "lnum" is given: use column 1, otherwise start at the cursor) skipstart do not look for a match at the start position

Returns a List with all the text properties in line {lnum}.

Remove a matching text property from line {lnum}. When {lnum-end} is given, remove matching text properties from line {lnum} to {lnum-end} (inclusive). When {lnum} is omitted remove matching text properties from all lines (this requires going over all lines, thus will be a bit slow for a buffer with many lines).

Add a text property type {name}. If a property type with this name already exists an error is given. Nothing is returned. {props} is a dictionary with these optional fields: bufnr define the property only for this buffer; this avoids name collisions and automatically clears the property types when the buffer is deleted. highlight name of highlight group to use priority when a character has multiple text properties the one with the highest priority will be used; negative values can be used, the default priority is zero combine when omitted or TRUE combine the highlight with any syntax highlight; when FALSE syntax highlight will not be used override when TRUE the highlight overrides any other, including 'cursorline' and Visual start_incl when TRUE inserts at the start position will be included in the text property end_incl when TRUE inserts at the end position will be included in the text property

Change properties of an existing text property type. If a property with this name does not exist an error is given. The {props} argument is just like prop_type_add().

Remove the text property type {name}. When text properties using the type {name} are still in place, they will not have an effect and can no longer be removed by name.

Returns the properties of property type {name}. This is a dictionary with the same fields as was given to prop_type_add(). When the property type {name} does not exist, an empty dictionary is returned.

Returns a list with all property type names.

Read file {fname} in binary mode and return a Blob. If {offset} is specified, read the file from the specified offset. If it is a negative value, it is used as an offset from the end of the file. E.g., to read the last 12 bytes:

Extended version of readdir(). Return a list of Dictionaries with file and directory information in {directory}. This is useful if you want to get the attributes of file and directory at the same time as getting a list of a directory. This is much faster than calling readdir() then calling getfperm(), getfsize(), getftime() and getftype() for each file and directory especially on MS-Windows. The list will by default be sorted by name (case sensitive), the sorting can be changed by using the optional {dict} argument, see readdir().

Send the {string} to {server}. The {server} argument is a string, also see {server}.

Move the Vim server with the name {server} to the foreground. The {server} argument is a string, also see {server}. This works like:

Returns a positive number if there are available strings from {serverid}. Copies any reply string into the variable {retvar} if specified. {retvar} must be a string with the name of a variable. Returns zero if none are available. Returns -1 if something is wrong. See also clientserver. This function is not available in the sandbox. only available when compiled with the +clientserver feature Examples:

Return the oldest available reply from {serverid} and consume it. Unless a {timeout} in seconds is given, it blocks until a reply is available. Returns an empty string, if a reply is not available or on error. See also clientserver. This function is not available in the sandbox. only available when compiled with the +clientserver feature Example:

Send the {string} to {server}. The {server} argument is a string, also see {server}.

Become the server {name}. This fails if already running as a server, when v:servername is not empty.

Send a reply string to {clientid}. The most recent {clientid} that sent a string can be retrieved with expand("<client>"). only available when compiled with the +clientserver feature Returns zero for success, -1 for failure. Note: This id has to be stored before the next command can be received. I.e. before returning from the received command and before calling any commands that waits for input. See also clientserver. Example:

Similar to using a slice "expr[start : end]", but "end" is used exclusive. And for a string the indexes are used as character indexes instead of byte indexes, like in vim9script. Also, composing characters are not counted. When {end} is omitted the slice continues to the last item. When {end} is -1 the last item is omitted. Returns an empty value if {start} or {end} are invalid.

Stop playing all sounds.

Play a sound identified by {name}. Which event names are supported depends on the system. Often the XDG sound names are used. On Ubuntu they may be found in /usr/share/sounds/freedesktop/stereo. Example:

Like sound_playevent() but play sound file {path}. {path} must be a full path. On Ubuntu you may find files to play with this command:

Stop playing sound {id}. {id} must be previously returned by sound_playevent() or sound_playfile().

Return a string which contains characters indicating the current state. Mostly useful in callbacks that want to do work that may not always be safe. Roughly this works like:

• callback uses state() to check if work is safe to do. Yes: then do it right away. No: add to work queue and add a SafeState and/or SafeStateAgain autocommand (SafeState triggers at toplevel, SafeStateAgain triggers after handling messages and callbacks).
• When SafeState or SafeStateAgain is triggered and executes your autocommand, check with state() if the work can be done now, and if yes remove it from the queue and execute. Remove the autocommand if the queue is now empty. Also see mode().

The result is a Number, which is the number of characters in String {string}. Composing characters are ignored. strchars() can count the number of characters, counting composing characters separately.

The result is a Number, which is the number of UTF-16 code units in String {string} (after converting it to UTF-16).

Returns a list of swap file names, like what "vim -r" shows. See the -r command argument. The 'directory' option is used for the directories to inspect. If you only want to get a list of swap files in the current directory then temporarily set 'directory' to a dot:

Open a new window displaying the difference between the two files. The files must have been created with term_dumpwrite(). Returns the buffer number or zero when the diff fails. Also see terminal-diff. NOTE: this does not work with double-width characters yet.

Open a new window displaying the contents of {filename} The file must have been created with term_dumpwrite(). Returns the buffer number or zero when it fails. Also see terminal-diff.

Dump the contents of the terminal screen of {buf} in the file {filename}. This uses a format that can be used with term_dumpload() and term_dumpdiff(). If the job in the terminal already finished an error is given:

Returns 1 if the terminal of {buf} is using the alternate screen. {buf} is used as with term_getsize().

Get the ANSI color palette in use by terminal {buf}. Returns a List of length 16 where each element is a String representing a color in hexadecimal "#rrggbb" format. Also see term_setansicolors() and g:terminal_ansi_colors. If neither was used returns the default colors.

Given {attr}, a value returned by term_scrape() in the "attr" item, return whether {what} is on. {what} can be one of: bold italic underline strike reverse

Get the cursor position of terminal {buf}. Returns a list with two numbers and a dictionary: [row, col, dict].

Get the Job associated with terminal window {buf}. {buf} is used as with term_getsize(). Returns v:null when there is no job.

Get a line of text from the terminal window of {buf}. {buf} is used as with term_getsize().

Return the number of lines that scrolled to above the top of terminal {buf}. This is the offset between the row number used for term_getline() and getline(), so that:

Get the size of terminal {buf}. Returns a list with two numbers: [rows, cols]. This is the size of the terminal, not the window containing the terminal.

Get the status of terminal {buf}. This returns a String with a comma-separated list of these items: running job is running finished job has finished normal in Terminal-Normal mode One of "running" or "finished" is always present.

Get the title of terminal {buf}. This is the title that the job in the terminal has set.

Get the name of the controlling terminal associated with terminal window {buf}. {buf} is used as with term_getsize().

Return a list with the buffer numbers of all buffers for terminal windows.

Get the contents of {row} of terminal screen of {buf}. For {buf} see term_getsize().

Send keystrokes {keys} to terminal {buf}. {buf} is used as with term_getsize().

Set the ANSI color palette used by terminal {buf}. {colors} must be a List of 16 valid color names or hexadecimal color codes, like those accepted by highlight-guifg. Also see term_getansicolors() and g:terminal_ansi_colors.

Set the function name prefix to be used for the terminal-api function in terminal {buf}. For example:

When exiting Vim or trying to close the terminal window in another way, {how} defines whether the job in the terminal can be stopped. When {how} is empty (the default), the job will not be stopped, trying to exit will result in E947. Otherwise, {how} specifies what signal to send to the job. See job_stop() for the values.

Set the command to write in a session file to restore the job in this terminal. The line written in the session file is:

Set the size of terminal {buf}. The size of the window containing the terminal will also be adjusted, if possible. If {rows} or {cols} is zero or negative, that dimension is not changed.

Open a terminal window and run {cmd} in it.

Wait for pending updates of {buf} to be handled. {buf} is used as with term_getsize(). {time} is how long to wait for updates to arrive in msec. If not set then 10 msec will be used.

Returns a Dictionary with properties of the terminal that Vim detected from the response to t_RV request. See v:termresponse for the response itself. If v:termresponse is empty most values here will be 'u' for unknown. cursor_style whether sending t_RS works ** cursor_blink_mode whether sending t_RC works ** underline_rgb whether t_8u works ** mouse mouse type supported kitty whether Kitty terminal was detected

This is for testing: If the memory allocation with {id} is called, then decrement {countdown}, and when it reaches zero let memory allocation fail {repeat} times. When {repeat} is smaller than one it fails one time.

Set a flag to enable the effect of 'autochdir' before Vim startup has finished.

Characters in {string} are queued for processing as if they were typed by the user. This uses a low level input buffer. This function works only when with +unix or GUI is running.

Like garbagecollect(), but executed right away. This must only be called directly to avoid any structure to exist internally, and v:testing must have been set before calling any function. This will not work when called from a :def function, because variables on the stack will be freed.

Set the flag to call the garbagecollector as if in the main loop. Only to be used in tests.

Get the value of an internal variable. These values for {name} are supported: need_fileinfo

Generate a GUI {event} with arguments {args} for testing Vim functionality. This function works only when the GUI is running.

Ignore any error containing {expr}. A normal message is given instead. This is only meant to be used in tests, where catching the error with try/catch cannot be used (because it skips over following code). {expr} is used literally, not as a pattern. When the {expr} is the string "RESET" then the list of ignored errors is made empty.

Generate a low-level MS-Windows {event} with arguments {args} for testing Vim functionality. It works for MS-Windows GUI and for the console.

Return a Blob that is null. Only useful for testing.

Return a Channel that is null. Only useful for testing. only available when compiled with the +channel feature

Return a Dict that is null. Only useful for testing.

Return a Funcref that is null. Only useful for testing.

Return a Job that is null. Only useful for testing. only available when compiled with the +job feature

Return a List that is null. Only useful for testing.

Return a Partial that is null. Only useful for testing.

Return a String that is null. Only useful for testing.

Reset the flag that indicates option {name} was set. Thus it looks like it still has the default value. Use like this:

Overrides certain parts of Vim's internal processing to be able to run tests. Only to be used for testing Vim! The override is enabled when {val} is non-zero and removed when {val} is zero. Current supported values for {name} are:

Return the reference count of {expr}. When {expr} is of a type that does not have a reference count, returns -1. Only to be used for testing.

Set the mouse position to be used for the next mouse action. {row} and {col} are one based. For example:

Set the time Vim uses internally. Currently only used for timestamps in the history, as they are used in viminfo, and for undo. Using a value of 1 makes Vim not sleep after a warning or error message. {expr} must evaluate to a number. When the value is zero the normal behavior is restored.

When [seed] is given this sets the seed value used by srand(). When omitted the test seed is removed.

Return a value with unknown type. Only useful for testing.

Return a value with void type. Only useful for testing.

Return a string representation of the type of {expr}. Example:

Same as charidx() but returns the UTF-16 index of the byte at {idx} in {string} (after converting it to UTF-16).