Mercurial > vim
diff runtime/doc/eval.txt @ 17456:e414281d8bb4 v8.1.1726
patch 8.1.1726: the eval.txt help file is too big
commit https://github.com/vim/vim/commit/ed997adaa1e9bd057ce732a73d933b739e9d0c30
Author: Bram Moolenaar <Bram@vim.org>
Date: Sun Jul 21 16:42:00 2019 +0200
patch 8.1.1726: the eval.txt help file is too big
Problem: The eval.txt help file is too big.
Solution: Split off testing support to testing.txt. Move function details
to where the functionality is explained.
author | Bram Moolenaar <Bram@vim.org> |
---|---|
date | Sun, 21 Jul 2019 16:45:05 +0200 |
parents | 509542f1fffb |
children | 1e45331bd2ab |
line wrap: on
line diff
--- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1,4 +1,4 @@ -*eval.txt* For Vim version 8.1. Last change: 2019 Jul 19 +*eval.txt* For Vim version 8.1. Last change: 2019 Jul 21 VIM REFERENCE MANUAL by Bram Moolenaar @@ -31,7 +31,9 @@ 10. Vim script version |vimscript-versi 11. No +eval feature |no-eval-feature| 12. The sandbox |eval-sandbox| 13. Textlock |textlock| -14. Testing |testing| + +Testing support is documented in |testing.txt|. +Profiling is documented at |profiling|. ============================================================================== 1. Variables *variables* @@ -2952,117 +2954,9 @@ argv([{nr} [, {winid}]) The {winid} argument specifies the window ID, see |argc()|. -assert_beeps({cmd}) *assert_beeps()* - Run {cmd} and add an error message to |v:errors| if it does - NOT produce a beep or visual bell. - Also see |assert_fails()| and |assert-return|. - - *assert_equal()* -assert_equal({expected}, {actual} [, {msg}]) - 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: > - assert_equal('foo', 'bar') -< Will result in a string to be added to |v:errors|: - test.vim line 12: Expected 'foo' but got 'bar' ~ - - *assert_equalfile()* -assert_equalfile({fname-one}, {fname-two}) - 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|. - -assert_exception({error} [, {msg}]) *assert_exception()* - 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: > - try - commandthatfails - call assert_false(1, 'command should have failed') - catch - call assert_exception('E492:') - endtry - -assert_fails({cmd} [, {error} [, {msg}]]) *assert_fails()* - Run {cmd} and add an error message to |v:errors| if it does - NOT produce an error. Also see |assert-return|. - When {error} is given it must match in |v:errmsg|. - Note that beeping is not considered an error, and some failing - commands only beep. Use |assert_beeps()| for those. - -assert_false({actual} [, {msg}]) *assert_false()* - 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. - -assert_inrange({lower}, {upper}, {actual} [, {msg}]) *assert_inrange()* - 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. - - *assert_match()* -assert_match({pattern}, {actual} [, {msg}]) - When {pattern} does not match {actual} an error message is - added to |v:errors|. Also see |assert-return|. - - {pattern} is used as with |=~|: The matching is always done - like 'magic' was set and 'cpoptions' is empty, no matter what - the actual value of 'magic' or 'cpoptions' is. - - {actual} is used as a string, automatic conversion applies. - Use "^" and "$" to match with the start and end of the text. - Use both to match the whole text. - - When {msg} is omitted an error in the form - "Pattern {pattern} does not match {actual}" is produced. - Example: > - assert_match('^f.*o$', 'foobar') -< Will result in a string to be added to |v:errors|: - test.vim line 12: Pattern '^f.*o$' does not match 'foobar' ~ - - *assert_notequal()* -assert_notequal({expected}, {actual} [, {msg}]) - The opposite of `assert_equal()`: add an error message to - |v:errors| when {expected} and {actual} are equal. - Also see |assert-return|. - - *assert_notmatch()* -assert_notmatch({pattern}, {actual} [, {msg}]) - The opposite of `assert_match()`: add an error message to - |v:errors| when {pattern} matches {actual}. - Also see |assert-return|. - -assert_report({msg}) *assert_report()* - Report a test failure directly, using {msg}. - Always returns one. - -assert_true({actual} [, {msg}]) *assert_true()* - 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. + +assert_ functions are documented here: |assert-functions| + asin({expr}) *asin()* Return the arc sine of {expr} measured in radians, as a |Float| @@ -3358,213 +3252,10 @@ ceil({expr}) *ceil()* < 4.0 {only available when compiled with the |+float| feature} -ch_canread({handle}) *ch_canread()* - Return non-zero when there is something to read from {handle}. - {handle} can be a Channel or a Job that has a Channel. - - This is useful to read from a channel at a convenient time, - e.g. from a timer. - - Note that messages are dropped when the channel does not have - a callback. Add a close callback to avoid that. - - {only available when compiled with the |+channel| feature} - -ch_close({handle}) *ch_close()* - Close {handle}. See |channel-close|. - {handle} can be a Channel or a Job that has a Channel. - A close callback is not invoked. - - {only available when compiled with the |+channel| feature} - -ch_close_in({handle}) *ch_close_in()* - 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. - - {only available when compiled with the |+channel| feature} - -ch_evalexpr({handle}, {expr} [, {options}]) *ch_evalexpr()* - 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. - *E917* - {options} must be a Dictionary. It must not have a "callback" - entry. It can have a "timeout" entry to specify the timeout - for this specific request. - - ch_evalexpr() waits for a response and returns the decoded - expression. When there is an error or timeout it returns an - empty string. - - {only available when compiled with the |+channel| feature} - -ch_evalraw({handle}, {string} [, {options}]) *ch_evalraw()* - Send {string} over {handle}. - {handle} can be a Channel or a Job that has a Channel. - - Works like |ch_evalexpr()|, 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. - Note that Vim does not know when the text received on a raw - channel is complete, it may only return the first part and you - need to use |ch_readraw()| to fetch the rest. - See |channel-use|. - - {only available when compiled with the |+channel| feature} - -ch_getbufnr({handle}, {what}) *ch_getbufnr()* - Get the buffer number that {handle} is using for {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. - {only available when compiled with the |+channel| feature} - -ch_getjob({channel}) *ch_getjob()* - Get the Job associated with {channel}. - If there is no job calling |job_status()| on the returned Job - will result in "fail". - - {only available when compiled with the |+channel| and - |+job| features} - -ch_info({handle}) *ch_info()* - 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 - "sock_status" "open" or "closed" - "sock_mode" "NL", "RAW", "JSON" or "JS" - "sock_io" "socket" - "sock_timeout" timeout in msec - When opened with job_start(): - "out_status" "open", "buffered" or "closed" - "out_mode" "NL", "RAW", "JSON" or "JS" - "out_io" "null", "pipe", "file" or "buffer" - "out_timeout" timeout in msec - "err_status" "open", "buffered" or "closed" - "err_mode" "NL", "RAW", "JSON" or "JS" - "err_io" "out", "null", "pipe", "file" or "buffer" - "err_timeout" timeout in msec - "in_status" "open" or "closed" - "in_mode" "NL", "RAW", "JSON" or "JS" - "in_io" "null", "pipe", "file" or "buffer" - "in_timeout" timeout in msec - -ch_log({msg} [, {handle}]) *ch_log()* - Write {msg} in the channel log file, if it was opened with - |ch_logfile()|. - 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. - -ch_logfile({fname} [, {mode}]) *ch_logfile()* - Start logging channel activity to {fname}. - When {fname} is an empty string: stop logging. - - When {mode} is omitted or "a" append to the file. - When {mode} is "w" start with an empty file. - - Use |ch_log()| to write log messages. The file is flushed - after every message, on Unix you can use "tail -f" to see what - is going on in real time. - - This function is not available in the |sandbox|. - NOTE: the channel communication is stored in the file, be - aware that this may contain confidential and privacy sensitive - information, e.g. a password you type in a terminal window. - - -ch_open({address} [, {options}]) *ch_open()* - Open a channel to {address}. See |channel|. - Returns a Channel. Use |ch_status()| to check for failure. - - {address} has the form "hostname:port", e.g., - "localhost:8765". - - If {options} is given it must be a |Dictionary|. - See |channel-open-options|. - - {only available when compiled with the |+channel| feature} - -ch_read({handle} [, {options}]) *ch_read()* - 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|. - {only available when compiled with the |+channel| feature} - -ch_readblob({handle} [, {options}]) *ch_readblob()* - Like ch_read() but reads binary data and returns a |Blob|. - See |channel-more|. - {only available when compiled with the |+channel| feature} - -ch_readraw({handle} [, {options}]) *ch_readraw()* - 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|. - {only available when compiled with the |+channel| feature} - -ch_sendexpr({handle}, {expr} [, {options}]) *ch_sendexpr()* - 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|. *E912* - {handle} can be a Channel or a Job that has a Channel. - - {only available when compiled with the |+channel| feature} - -ch_sendraw({handle}, {expr} [, {options}]) *ch_sendraw()* - 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|. - - {only available when compiled with the |+channel| feature} - -ch_setoptions({handle}, {options}) *ch_setoptions()* - 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. - - Note that changing the mode may cause queued messages to be - lost. - - These options cannot be changed: - "waittime" only applies to |ch_open()| - -ch_status({handle} [, {options}]) *ch_status()* - 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()|. - - If {options} is given it can contain a "part" entry to specify - the part of the channel to return the status for: "out" or - "err". For example, to get the error status: > - ch_status(job, {"part": "err"}) -< + +ch_ functions are documented here: |channel-functions-details| + + changenr() *changenr()* Return the number of the most recent change. This is the same number as what is displayed with |:undolist| and can be used @@ -6044,161 +5735,9 @@ items({dict}) *items()* echo key . ': ' . value endfor -job_getchannel({job}) *job_getchannel()* - Get the channel handle that {job} is using. - To check if the job has no channel: > - if string(job_getchannel()) == 'channel fail' -< - {only available when compiled with the |+job| feature} - -job_info([{job}]) *job_info()* - 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| - - Only in Unix: - "termsig" the signal which terminated the process - (See |job_stop()| for the values) - only valid when "status" is "dead" - - Only in MS-Windows: - "tty_type" Type of virtual console in use. - Values are "winpty" or "conpty". - See 'termwintype'. - - Without any arguments, returns a List with all Job objects. - -job_setoptions({job}, {options}) *job_setoptions()* - Change options for {job}. Supported are: - "stoponexit" |job-stoponexit| - "exit_cb" |job-exit_cb| - -job_start({command} [, {options}]) *job_start()* - 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()|. - - If the job fails to start then |job_status()| on the returned - Job object results in "fail" and none of the callbacks will be - invoked. - - {command} can be a String. This works best on MS-Windows. On - Unix it is split up in white-separated parts to be passed to - execvp(). Arguments in double quotes can contain white space. - - {command} can be a List, where the first item is the executable - and further items are the arguments. All items are converted - to String. This works best on Unix. - - On MS-Windows, job_start() makes a GUI application hidden. If - want to show it, Use |:!start| instead. - - The command is executed directly, not through a shell, the - 'shell' option is not used. To use the shell: > - let job = job_start(["/bin/sh", "-c", "echo hello"]) -< Or: > - let job = job_start('/bin/sh -c "echo hello"') -< Note that this will start two processes, the shell and the - command it executes. If you don't want this use the "exec" - shell command. - - On Unix $PATH is used to search for the executable only when - the command does not contain a slash. - - The job will use the same terminal as Vim. If it reads from - stdin the job and Vim will be fighting over input, that - doesn't work. Redirect stdin and stdout to avoid problems: > - let job = job_start(['sh', '-c', "myserver </dev/null >/dev/null"]) -< - The returned Job object can be used to get the status with - |job_status()| and stop the job with |job_stop()|. - - Note that the job object will be deleted if there are no - references to it. This closes the stdin and stderr, which may - cause the job to fail with an error. To avoid this keep a - reference to the job. Thus instead of: > - call job_start('my-command') -< use: > - let myjob = job_start('my-command') -< and unlet "myjob" once the job is not needed or is past the - point where it would fail (e.g. when it prints a message on - startup). Keep in mind that variables local to a function - will cease to exist if the function returns. Use a - script-local variable if needed: > - let s:myjob = job_start('my-command') -< - {options} must be a Dictionary. It can contain many optional - items, see |job-options|. - - {only available when compiled with the |+job| feature} - -job_status({job}) *job_status()* *E916* - 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 - - On Unix a non-existing command results in "dead" instead of - "fail", because a fork happens before the failure can be - detected. - - If an exit callback was set with the "exit_cb" option and the - job is now detected to be "dead" the callback will be invoked. - - For more information see |job_info()|. - - {only available when compiled with the |+job| feature} - -job_stop({job} [, {how}]) *job_stop()* - Stop the {job}. This can also be used to signal the job. - - When {how} is omitted or is "term" the job will be terminated. - For Unix SIGTERM is sent. On MS-Windows the job will be - terminated forcedly (there is no "gentle" way). - This goes to the process group, thus children may also be - affected. - - Effect for Unix: - "term" SIGTERM (default) - "hup" SIGHUP - "quit" SIGQUIT - "int" SIGINT - "kill" SIGKILL (strongest way to stop) - number signal with that number - - Effect for MS-Windows: - "term" terminate process forcedly (default) - "hup" CTRL_BREAK - "quit" CTRL_BREAK - "int" CTRL_C - "kill" terminate process forcedly - Others CTRL_BREAK - - On Unix the signal is sent to the process group. This means - that when the job is "sh -c command" it affects both the shell - and the command. - - The result is a Number: 1 if the operation could be executed, - 0 if "how" is not supported on the system. - Note that even when the operation was executed, whether the - job was actually stopped needs to be checked with - |job_status()|. - - If the status of the job is "dead", the signal will not be - sent. This is to avoid to stop the wrong job (esp. on Unix, - where process numbers are recycled). - - When using "kill" Vim will assume the job will die and close - the channel. - - {only available when compiled with the |+job| feature} + +job_ functions are documented here: |job-functions-details| + join({list} [, {sep}]) *join()* Join the items in {list} together into one String. @@ -7333,201 +6872,7 @@ prompt_setprompt({buf}, {text}) *prom "prompt". Example: > call prompt_setprompt(bufnr(''), 'command: ') < - *prop_add()* *E965* -prop_add({lnum}, {col}, {props}) - 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. *E966* - If {col} is invalid an error is given. *E964* - - {props} is a dictionary with these fields: - length length of text in bytes, can only be used - for a property that does not continue in - another line; can be zero - end_lnum line number for the end of text - end_col column just after the text; not used when - "length" is present; when {col} and "end_col" - are equal, and "end_lnum" is omitted or equal - to {lnum}, this is a zero-width text property - bufnr buffer to add the property to; when omitted - the current buffer is used - id user defined ID for the property; when omitted - zero is used - type name of the text property type - All fields except "type" are optional. - - It is an error when both "length" and "end_lnum" or "end_col" - are given. Either use "length" or "end_col" for a property - within one line, or use "end_lnum" and "end_col" for a - property that spans more than one line. - When neither "length" nor "end_col" are given the property - will be zero-width. That means it will not be highlighted but - will move with the text, as a kind of mark. - The property can end exactly at the last character of the - text, or just after it. In the last case, if text is appended - to the line, the text property size will increase, also when - the property type does not have "end_incl" set. - - "type" will first be looked up in the buffer the property is - added to. When not found, the global property types are used. - If not found an error is given. - - See |text-properties| for information about text properties. - - -prop_clear({lnum} [, {lnum-end} [, {props}]]) *prop_clear()* - Remove all text properties from line {lnum}. - When {lnum-end} is given, remove all text properties from line - {lnum} to {lnum-end} (inclusive). - - When {props} contains a "bufnr" item use this buffer, - otherwise use the current buffer. - - See |text-properties| for information about text properties. - - *prop_find()* -prop_find({props} [, {direction}]) - NOT IMPLEMENTED YET - Search for a text property as specified with {props}: - id property with this ID - type property with this type name - 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 - - {direction} can be "f" for forward and "b" for backward. When - omitted forward search is performed. - - If a match is found then a Dict is returned with the entries - as with prop_list(), and additionally an "lnum" entry. - If no match is found then an empty Dict is returned. - - See |text-properties| for information about text properties. - - -prop_list({lnum} [, {props}]) *prop_list()* - Return a List with all text properties in line {lnum}. - - When {props} contains a "bufnr" item, use this buffer instead - of the current buffer. - - The properties are ordered by starting column and priority. - Each property is a Dict with these entries: - col starting column - length length in bytes, one more if line break is - included - id property ID - type name of the property type, omitted if - the type was deleted - start when TRUE property starts in this line - end when TRUE property ends in this line - - When "start" is zero the property started in a previous line, - the current one is a continuation. - When "end" is zero the property continues in the next line. - The line break after this line is included. - - See |text-properties| for information about text properties. - - - *prop_remove()* *E968* -prop_remove({props} [, {lnum} [, {lnum-end}]]) - 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. - - {props} is a dictionary with these fields: - id remove text properties with this ID - type remove text properties with this type name - bufnr use this buffer instead of the current one - all when TRUE remove all matching text properties, - not just the first one - A property matches when either "id" or "type" matches. - If buffer "bufnr" does not exist you get an error message. - If buffer "bufnr" is not loaded then nothing happens. - - Returns the number of properties that were removed. - - See |text-properties| for information about text properties. - - -prop_type_add({name}, {props}) *prop_type_add()* *E969* *E970* - Add a text property type {name}. If a property type with this - name already exists an error is given. - {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 TRUE combine the highlight with any - syntax highlight; when omitted or FALSE syntax - highlight will not be used - 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 - - See |text-properties| for information about text properties. - - -prop_type_change({name}, {props}) *prop_type_change()* - 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()|. - - See |text-properties| for information about text properties. - - -prop_type_delete({name} [, {props}]) *prop_type_delete()* - 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. - - {props} can contain a "bufnr" item. When it is given, delete - a property type from this buffer instead of from the global - property types. - - When text property type {name} is not found there is no error. - - See |text-properties| for information about text properties. - - -prop_type_get([{name} [, {props}]) *prop_type_get()* - 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. - - {props} can contain a "bufnr" item. When it is given, use - this buffer instead of the global property types. - - See |text-properties| for information about text properties. - - -prop_type_list([{props}]) *prop_type_list()* - Returns a list with all property type names. - - {props} can contain a "bufnr" item. When it is given, use - this buffer instead of the global property types. - - See |text-properties| for information about text properties. - +prop_ functions are documented here: |text-prop-functions|. pumvisible() *pumvisible()* Returns non-zero when the popup menu is visible, zero @@ -8637,351 +7982,9 @@ shiftwidth([{col}]) *shiftwidth()* 'vartabstop' feature. If the 'vartabstop' setting is enabled and no {col} argument is given, column 1 will be assumed. -sign_define({name} [, {dict}]) *sign_define()* -sign_define({list}) - Define a new sign named {name} or modify the attributes of an - existing sign. This is similar to the |:sign-define| command. - - Prefix {name} with a unique text to avoid name collisions. - There is no {group} like with placing signs. - - The {name} can be a String or a Number. The optional {dict} - argument specifies the sign attributes. The following values - are supported: - icon full path to the bitmap file for the sign. - linehl highlight group used for the whole line the - sign is placed in. - text text that is displayed when there is no icon - or the GUI is not being used. - texthl highlight group used for the text item - - If the sign named {name} already exists, then the attributes - of the sign are updated. - - The one argument {list} can be used to define a list of signs. - Each list item is a dictionary with the above items in {dict} - and a 'name' item for the sign name. - - Returns 0 on success and -1 on failure. When the one argument - {list} is used, then returns a List of values one for each - defined sign. - - Examples: > - call sign_define("mySign", { - \ "text" : "=>", - \ "texthl" : "Error", - \ "linehl" : "Search"}) - call sign_define([ - \ {'name' : 'sign1', - \ 'text' : '=>'}, - \ {'name' : 'sign2', - \ 'text' : '!!'} - \ ]) -< -sign_getdefined([{name}]) *sign_getdefined()* - Get a list of defined signs and their attributes. - This is similar to the |:sign-list| command. - - If the {name} is not supplied, then a list of all the defined - signs is returned. Otherwise the attribute of the specified - sign is returned. - - Each list item in the returned value is a dictionary with the - following entries: - icon full path to the bitmap file of the sign - linehl highlight group used for the whole line the - sign is placed in. - name name of the sign - text text that is displayed when there is no icon - or the GUI is not being used. - texthl highlight group used for the text item - - Returns an empty List if there are no signs and when {name} is - not found. - - Examples: > - " Get a list of all the defined signs - echo sign_getdefined() - - " Get the attribute of the sign named mySign - echo sign_getdefined("mySign") -< -sign_getplaced([{expr} [, {dict}]]) *sign_getplaced()* - Return a list of signs placed in a buffer or all the buffers. - This is similar to the |:sign-place-list| command. - - If the optional buffer name {expr} is specified, then only the - list of signs placed in that buffer is returned. For the use - of {expr}, see |bufname()|. The optional {dict} can contain - the following entries: - group select only signs in this group - id select sign with this identifier - lnum select signs placed in this line. For the use - of {lnum}, see |line()|. - If {group} is '*', then signs in all the groups including the - global group are returned. If {group} is not supplied or is an - empty string, then only signs in the global group are - returned. If no arguments are supplied, then signs in the - global group placed in all the buffers are returned. - See |sign-group|. - - Each list item in the returned value is a dictionary with the - following entries: - bufnr number of the buffer with the sign - signs list of signs placed in {bufnr}. Each list - item is a dictionary with the below listed - entries - - The dictionary for each sign contains the following entries: - group sign group. Set to '' for the global group. - id identifier of the sign - lnum line number where the sign is placed - name name of the defined sign - priority sign priority - - The returned signs in a buffer are ordered by their line - number and priority. - - Returns an empty list on failure or if there are no placed - signs. - - Examples: > - " Get a List of signs placed in eval.c in the - " global group - echo sign_getplaced("eval.c") - - " Get a List of signs in group 'g1' placed in eval.c - echo sign_getplaced("eval.c", {'group' : 'g1'}) - - " Get a List of signs placed at line 10 in eval.c - echo sign_getplaced("eval.c", {'lnum' : 10}) - - " Get sign with identifier 10 placed in a.py - echo sign_getplaced("a.py", {'id' : 10}) - - " Get sign with id 20 in group 'g1' placed in a.py - echo sign_getplaced("a.py", {'group' : 'g1', - \ 'id' : 20}) - - " Get a List of all the placed signs - echo sign_getplaced() -< - *sign_jump()* -sign_jump({id}, {group}, {expr}) - Open the buffer {expr} or jump to the window that contains - {expr} and position the cursor at sign {id} in group {group}. - This is similar to the |:sign-jump| command. - - For the use of {expr}, see |bufname()|. - - Returns the line number of the sign. Returns -1 if the - arguments are invalid. - - Example: > - " Jump to sign 10 in the current buffer - call sign_jump(10, '', '') -< - *sign_place()* -sign_place({id}, {group}, {name}, {expr} [, {dict}]) - Place the sign defined as {name} at line {lnum} in file or - buffer {expr} and assign {id} and {group} to sign. This is - similar to the |:sign-place| command. - - If the sign identifier {id} is zero, then a new identifier is - allocated. Otherwise the specified number is used. {group} is - the sign group name. To use the global sign group, use an - empty string. {group} functions as a namespace for {id}, thus - two groups can use the same IDs. Refer to |sign-identifier| - and |sign-group| for more information. - - {name} refers to a defined sign. - {expr} refers to a buffer name or number. For the accepted - values, see |bufname()|. - - The optional {dict} argument supports the following entries: - lnum line number in the file or buffer - {expr} where the sign is to be placed. - For the accepted values, see |line()|. - priority priority of the sign. See - |sign-priority| for more information. - - If the optional {dict} is not specified, then it modifies the - placed sign {id} in group {group} to use the defined sign - {name}. - - Returns the sign identifier on success and -1 on failure. - - Examples: > - " Place a sign named sign1 with id 5 at line 20 in - " buffer json.c - call sign_place(5, '', 'sign1', 'json.c', - \ {'lnum' : 20}) - - " Updates sign 5 in buffer json.c to use sign2 - call sign_place(5, '', 'sign2', 'json.c') - - " Place a sign named sign3 at line 30 in - " buffer json.c with a new identifier - let id = sign_place(0, '', 'sign3', 'json.c', - \ {'lnum' : 30}) - - " Place a sign named sign4 with id 10 in group 'g3' - " at line 40 in buffer json.c with priority 90 - call sign_place(10, 'g3', 'sign4', 'json.c', - \ {'lnum' : 40, 'priority' : 90}) -< - *sign_placelist()* -sign_placelist({list}) - Place one or more signs. This is similar to the - |sign_place()| function. The {list} argument specifies the - List of signs to place. Each list item is a dict with the - following sign attributes: - buffer buffer name or number. For the accepted - values, see |bufname()|. - group sign group. {group} functions as a namespace - for {id}, thus two groups can use the same - IDs. If not specified or set to an empty - string, then the global group is used. See - |sign-group| for more information. - id sign identifier. If not specified or zero, - then a new unique identifier is allocated. - Otherwise the specified number is used. See - |sign-identifier| for more information. - lnum line number in the buffer {expr} where the - sign is to be placed. For the accepted values, - see |line()|. - name name of the sign to place. See |sign_define()| - for more information. - priority priority of the sign. When multiple signs are - placed on a line, the sign with the highest - priority is used. If not specified, the - default value of 10 is used. See - |sign-priority| for more information. - - If {id} refers to an existing sign, then the existing sign is - modified to use the specified {name} and/or {priority}. - - Returns a List of sign identifiers. If failed to place a - sign, the corresponding list item is set to -1. - - Examples: > - " Place sign s1 with id 5 at line 20 and id 10 at line - " 30 in buffer a.c - let [n1, n2] = sign_placelist([ - \ {'id' : 5, - \ 'name' : 's1', - \ 'buffer' : 'a.c', - \ 'lnum' : 20}, - \ {'id' : 10, - \ 'name' : 's1', - \ 'buffer' : 'a.c', - \ 'lnum' : 30} - \ ]) - - " Place sign s1 in buffer a.c at line 40 and 50 - " with auto-generated identifiers - let [n1, n2] = sign_placelist([ - \ {'name' : 's1', - \ 'buffer' : 'a.c', - \ 'lnum' : 40}, - \ {'name' : 's1', - \ 'buffer' : 'a.c', - \ 'lnum' : 50} - \ ]) -< -sign_undefine([{name}]) *sign_undefine()* -sign_undefine({list}) - Deletes a previously defined sign {name}. This is similar to - the |:sign-undefine| command. If {name} is not supplied, then - deletes all the defined signs. - - The one argument {list} can be used to undefine a list of - signs. Each list item is the name of a sign. - - Returns 0 on success and -1 on failure. For the one argument - {list} call, returns a list of values one for each undefined - sign. - - Examples: > - " Delete a sign named mySign - call sign_undefine("mySign") - - " Delete signs 'sign1' and 'sign2' - call sign_undefine(["sign1", "sign2"]) - - " Delete all the signs - call sign_undefine() -< -sign_unplace({group} [, {dict}]) *sign_unplace()* - Remove a previously placed sign in one or more buffers. This - is similar to the |:sign-unplace| command. - - {group} is the sign group name. To use the global sign group, - use an empty string. If {group} is set to '*', then all the - groups including the global group are used. - The signs in {group} are selected based on the entries in - {dict}. The following optional entries in {dict} are - supported: - buffer buffer name or number. See |bufname()|. - id sign identifier - If {dict} is not supplied, then all the signs in {group} are - removed. - - Returns 0 on success and -1 on failure. - - Examples: > - " Remove sign 10 from buffer a.vim - call sign_unplace('', {'buffer' : "a.vim", 'id' : 10}) - - " Remove sign 20 in group 'g1' from buffer 3 - call sign_unplace('g1', {'buffer' : 3, 'id' : 20}) - - " Remove all the signs in group 'g2' from buffer 10 - call sign_unplace('g2', {'buffer' : 10}) - - " Remove sign 30 in group 'g3' from all the buffers - call sign_unplace('g3', {'id' : 30}) - - " Remove all the signs placed in buffer 5 - call sign_unplace('*', {'buffer' : 5}) - - " Remove the signs in group 'g4' from all the buffers - call sign_unplace('g4') - - " Remove sign 40 from all the buffers - call sign_unplace('*', {'id' : 40}) - - " Remove all the placed signs from all the buffers - call sign_unplace('*') -< -sign_unplacelist({list}) *sign_unplacelist()* - Remove previously placed signs from one or more buffers. This - is similar to the |sign_unplace()| function. - - The {list} argument specifies the List of signs to remove. - Each list item is a dict with the following sign attributes: - buffer buffer name or number. For the accepted - values, see |bufname()|. If not specified, - then the specified sign is removed from all - the buffers. - group sign group name. If not specified or set to an - empty string, then the global sign group is - used. If set to '*', then all the groups - including the global group are used. - id sign identifier. If not specified, then all - the signs in the specified group are removed. - - Returns a List where an entry is set to 0 if the corresponding - sign was successfully removed or -1 on failure. - - Example: > - " Remove sign with id 10 from buffer a.vim and sign - " with id 20 from buffer b.vim - call sign_unplacelist([ - \ {'id' : 10, 'buffer' : "a.vim"}, - \ {'id' : 20, 'buffer' : 'b.vim'}, - \ ]) -< +sign_ functions are documented here: |sign-functions-details| + + simplify({filename}) *simplify()* Simplify the file name as much as possible without changing the meaning. Shortcuts (on MS-Windows) or symbolic links (on @@ -9822,147 +8825,11 @@ tempname() *tempname()* *temp-file-n For MS-Windows forward slashes are used when the 'shellslash' option is set or when 'shellcmdflag' starts with '-'. + term_ functions are documented here: |terminal-function-details| -test_alloc_fail({id}, {countdown}, {repeat}) *test_alloc_fail()* - 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. - -test_autochdir() *test_autochdir()* - Set a flag to enable the effect of 'autochdir' before Vim - startup has finished. - -test_feedinput({string}) *test_feedinput()* - 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. - -test_garbagecollect_now() *test_garbagecollect_now()* - 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. - -test_garbagecollect_soon() *test_garbagecollect_soon()* - Set the flag to call the garbagecollector as if in the main - loop. Only to be used in tests. - -test_getvalue({name}) *test_getvalue()* - Get the value of an internal variable. These values for - {name} are supported: - need_fileinfo - -test_ignore_error({expr}) *test_ignore_error()* - 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. - -test_null_blob() *test_null_blob()* - Return a |Blob| that is null. Only useful for testing. - -test_null_channel() *test_null_channel()* - Return a |Channel| that is null. Only useful for testing. - {only available when compiled with the +channel feature} - -test_null_dict() *test_null_dict()* - Return a |Dict| that is null. Only useful for testing. - -test_null_job() *test_null_job()* - Return a |Job| that is null. Only useful for testing. - {only available when compiled with the +job feature} - -test_null_list() *test_null_list()* - Return a |List| that is null. Only useful for testing. - -test_null_partial() *test_null_partial()* - Return a |Partial| that is null. Only useful for testing. - -test_null_string() *test_null_string()* - Return a |String| that is null. Only useful for testing. - -test_option_not_set({name}) *test_option_not_set()* - Reset the flag that indicates option {name} was set. Thus it - looks like it still has the default value. Use like this: > - set ambiwidth=double - call test_option_not_set('ambiwidth') -< Now the 'ambiwidth' option behaves like it was never changed, - even though the value is "double". - Only to be used for testing! - -test_override({name}, {val}) *test_override()* - 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: - - name effect when {val} is non-zero ~ - redraw disable the redrawing() function - redraw_flag ignore the RedrawingDisabled flag - char_avail disable the char_avail() function - starting reset the "starting" variable, see below - nfa_fail makes the NFA regexp engine fail to force a - fallback to the old engine - no_query_mouse do not query the mouse position for "dec" - terminals - no_wait_return set the "no_wait_return" flag. Not restored - with "ALL". - ALL clear all overrides ({val} is not used) - - "starting" is to be used when a test should behave like - startup was done. Since the tests are run by sourcing a - script the "starting" variable is non-zero. This is usually a - good thing (tests run faster), but sometimes changes behavior - in a way that the test doesn't work properly. - When using: > - call test_override('starting', 1) -< The value of "starting" is saved. It is restored by: > - call test_override('starting', 0) - -test_refcount({expr}) *test_refcount()* - 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. - -test_scrollbar({which}, {value}, {dragging}) *test_scrollbar()* - Pretend using scrollbar {which} to move it to position - {value}. {which} can be: - left Left scrollbar of the current window - right Right scrollbar of the current window - hor Horizontal scrollbar - - For the vertical scrollbars {value} can be 1 to the - line-count of the buffer. For the horizontal scrollbar the - {value} can be between 1 and the maximum line length, assuming - 'wrap' is not set. - - When {dragging} is non-zero it's like dragging the scrollbar, - otherwise it's like clicking in the scrollbar. - Only works when the {which} scrollbar actually exists, - obviously only when using the GUI. - -test_setmouse({row}, {col}) *test_setmouse()* - Set the mouse position to be used for the next mouse action. - {row} and {col} are one based. - For example: > - call test_setmouse(4, 20) - call feedkeys("\<LeftMouse>", "xt") - -test_settime({expr}) *test_settime()* - 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. +test_ functions are documented here: |test-functions| + *timer_info()* timer_info([{id}]) @@ -13121,26 +11988,5 @@ This is not allowed when the textlock is - closing a window or quitting Vim - etc. -============================================================================== -14. Testing *testing* - -Vim can be tested after building it, usually with "make test". -The tests are located in the directory "src/testdir". - -There are several types of tests added over time: - test33.in oldest, don't add any more - test_something.in old style tests - test_something.vim new style tests - - *new-style-testing* -New tests should be added as new style tests. These use functions such as -|assert_equal()| to keep the test commands and the expected result in one -place. - *old-style-testing* -In some cases an old style test needs to be used. E.g. when testing Vim -without the |+eval| feature. - -Find more information in the file src/testdir/README.txt. - vim:tw=78:ts=8:noet:ft=help:norl: