Mercurial > vim
diff runtime/doc/eval.txt @ 17259:6dbb9b3c53e2 v8.1.1629
patch 8.1.1629: terminal function help is in the wrong file
commit https://github.com/vim/vim/commit/6bf2c6264b5ebbe4981751840c5a8b69da08e744
Author: Bram Moolenaar <Bram@vim.org>
Date: Thu Jul 4 17:12:09 2019 +0200
patch 8.1.1629: terminal function help is in the wrong file
Problem: Terminal function help is in the wrong file.
Solution: Move the function details to terminal.txt.
author | Bram Moolenaar <Bram@vim.org> |
---|---|
date | Thu, 04 Jul 2019 17:15:07 +0200 |
parents | cb0ca75f0c26 |
children | 8a095d343c59 |
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 Jun 22 +*eval.txt* For Vim version 8.1. Last change: 2019 Jul 04 VIM REFERENCE MANUAL by Bram Moolenaar @@ -8172,8 +8172,9 @@ setbufline({expr}, {lnum}, {text}) *se {lnum} is used like with |setline()|. This works like |setline()| for the specified buffer. - When {expr} is not a valid buffer or {lnum} is not valid then - 1 is returned. On success 0 is returned. + When {expr} is not a valid buffer, the buffer is not loaded or + {lnum} is not valid then 1 is returned. On success 0 is + returned. setbufvar({expr}, {varname}, {val}) *setbufvar()* Set option or local variable {varname} in buffer {expr} to @@ -8734,9 +8735,9 @@ sign_jump({id}, {group}, {expr}) < *sign_place()* sign_place({id}, {group}, {name}, {expr} [, {dict}]) - Place the sign defined as {name} at line {lnum} in file {expr} - and assign {id} and {group} to sign. This is similar to the - |:sign-place| command. + 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 @@ -8750,9 +8751,9 @@ sign_place({id}, {group}, {name}, {expr} values, see |bufname()|. The optional {dict} argument supports the following entries: - lnum line number in the buffer {expr} where - the sign is to be placed. For the - accepted values, see |line()|. + 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. @@ -9677,364 +9678,7 @@ tempname() *tempname()* *temp-file-n For MS-Windows forward slashes are used when the 'shellslash' option is set or when 'shellcmdflag' starts with '-'. - *term_dumpdiff()* -term_dumpdiff({filename}, {filename} [, {options}]) - 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. - - The top part of the buffer contains the contents of the first - file, the bottom part of the buffer contains the contents of - the second file. The middle part shows the differences. - The parts are separated by a line of equals. - - If the {options} argument is present, it must be a Dict with - these possible members: - "term_name" name to use for the buffer name, instead - of the first file name. - "term_rows" vertical size to use for the terminal, - instead of using 'termwinsize' - "term_cols" horizontal size to use for the terminal, - instead of using 'termwinsize' - "vertical" split the window vertically - "curwin" use the current window, do not split the - window; fails if the current buffer - cannot be |abandon|ed - "bufnr" do not create a new buffer, use the - existing buffer "bufnr". This buffer - must have been previously created with - term_dumpdiff() or term_dumpload() and - visible in a window. - "norestore" do not add the terminal window to a - session file - - Each character in the middle part indicates a difference. If - there are multiple differences only the first in this list is - used: - X different character - w different width - f different foreground color - b different background color - a different attribute - + missing position in first file - - missing position in second file - - Using the "s" key the top and bottom parts are swapped. This - makes it easy to spot a difference. - - *term_dumpload()* -term_dumpload({filename} [, {options}]) - 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|. - - For {options} see |term_dumpdiff()|. - - *term_dumpwrite()* -term_dumpwrite({buf}, {filename} [, {options}]) - 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: - *E958* - If {filename} already exists an error is given: *E953* - Also see |terminal-diff|. - - {options} is a dictionary with these optional entries: - "rows" maximum number of rows to dump - "columns" maximum number of columns to dump - -term_getaltscreen({buf}) *term_getaltscreen()* - Returns 1 if the terminal of {buf} is using the alternate - screen. - {buf} is used as with |term_getsize()|. - {only available when compiled with the |+terminal| feature} - -term_getansicolors({buf}) *term_getansicolors()* - 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. - - {buf} is used as with |term_getsize()|. If the buffer does not - exist or is not a terminal window, an empty list is returned. - {only available when compiled with the |+terminal| feature and - with GUI enabled and/or the |+termguicolors| feature} - -term_getattr({attr}, {what}) *term_getattr()* - 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 - {only available when compiled with the |+terminal| feature} - -term_getcursor({buf}) *term_getcursor()* - Get the cursor position of terminal {buf}. Returns a list with - two numbers and a dictionary: [row, col, dict]. - - "row" and "col" are one based, the first screen cell is row - 1, column 1. This is the cursor position of the terminal - itself, not of the Vim window. - - "dict" can have these members: - "visible" one when the cursor is visible, zero when it - is hidden. - "blink" one when the cursor is blinking, zero when it - is not blinking. - "shape" 1 for a block cursor, 2 for underline and 3 - for a vertical bar. - "color" color of the cursor, e.g. "green" - - {buf} must be the buffer number of a terminal window. If the - buffer does not exist or is not a terminal window, an empty - list is returned. - {only available when compiled with the |+terminal| feature} - -term_getjob({buf}) *term_getjob()* - Get the Job associated with terminal window {buf}. - {buf} is used as with |term_getsize()|. - Returns |v:null| when there is no job. - {only available when compiled with the |+terminal| feature} - -term_getline({buf}, {row}) *term_getline()* - Get a line of text from the terminal window of {buf}. - {buf} is used as with |term_getsize()|. - - The first line has {row} one. When {row} is "." the cursor - line is used. When {row} is invalid an empty string is - returned. - - To get attributes of each character use |term_scrape()|. - {only available when compiled with the |+terminal| feature} - -term_getscrolled({buf}) *term_getscrolled()* - 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: > - term_getline(buf, N) -< is equal to: > - getline(N + term_getscrolled(buf)) -< (if that line exists). - - {buf} is used as with |term_getsize()|. - {only available when compiled with the |+terminal| feature} - -term_getsize({buf}) *term_getsize()* - 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. - - {buf} must be the buffer number of a terminal window. Use an - empty string for the current buffer. If the buffer does not - exist or is not a terminal window, an empty list is returned. - {only available when compiled with the |+terminal| feature} - -term_getstatus({buf}) *term_getstatus()* - Get the status of terminal {buf}. This returns 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. - - {buf} must be the buffer number of a terminal window. If the - buffer does not exist or is not a terminal window, an empty - string is returned. - {only available when compiled with the |+terminal| feature} - -term_gettitle({buf}) *term_gettitle()* - Get the title of terminal {buf}. This is the title that the - job in the terminal has set. - - {buf} must be the buffer number of a terminal window. If the - buffer does not exist or is not a terminal window, an empty - string is returned. - {only available when compiled with the |+terminal| feature} - -term_gettty({buf} [, {input}]) *term_gettty()* - Get the name of the controlling terminal associated with - terminal window {buf}. {buf} is used as with |term_getsize()|. - - When {input} is omitted or 0, return the name for writing - (stdout). When {input} is 1 return the name for reading - (stdin). On UNIX, both return same name. - {only available when compiled with the |+terminal| feature} - -term_list() *term_list()* - Return a list with the buffer numbers of all buffers for - terminal windows. - {only available when compiled with the |+terminal| feature} - -term_scrape({buf}, {row}) *term_scrape()* - Get the contents of {row} of terminal screen of {buf}. - For {buf} see |term_getsize()|. - - The first line has {row} one. When {row} is "." the cursor - line is used. When {row} is invalid an empty string is - returned. - - Return a List containing a Dict for each screen cell: - "chars" character(s) at the cell - "fg" foreground color as #rrggbb - "bg" background color as #rrggbb - "attr" attributes of the cell, use |term_getattr()| - to get the individual flags - "width" cell width: 1 or 2 - {only available when compiled with the |+terminal| feature} - -term_sendkeys({buf}, {keys}) *term_sendkeys()* - Send keystrokes {keys} to terminal {buf}. - {buf} is used as with |term_getsize()|. - - {keys} are translated as key sequences. For example, "\<c-x>" - means the character CTRL-X. - {only available when compiled with the |+terminal| feature} - -term_setansicolors({buf}, {colors}) *term_setansicolors()* - 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|. - - The colors normally are: - 0 black - 1 dark red - 2 dark green - 3 brown - 4 dark blue - 5 dark magenta - 6 dark cyan - 7 light grey - 8 dark grey - 9 red - 10 green - 11 yellow - 12 blue - 13 magenta - 14 cyan - 15 white - - These colors are used in the GUI and in the terminal when - 'termguicolors' is set. When not using GUI colors (GUI mode - or 'termguicolors'), the terminal window always uses the 16 - ANSI colors of the underlying terminal. - {only available when compiled with the |+terminal| feature and - with GUI enabled and/or the |+termguicolors| feature} - -term_setkill({buf}, {how}) *term_setkill()* - 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. - - After sending the signal Vim will wait for up to a second to - check that the job actually stopped. - -term_setrestore({buf}, {command}) *term_setrestore()* - Set the command to write in a session file to restore the job - in this terminal. The line written in the session file is: > - terminal ++curwin ++cols=%d ++rows=%d {command} -< Make sure to escape the command properly. - - Use an empty {command} to run 'shell'. - Use "NONE" to not restore this window. - {only available when compiled with the |+terminal| feature} - -term_setsize({buf}, {rows}, {cols}) *term_setsize()* *E955* - 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. - - {buf} must be the buffer number of a terminal window. Use an - empty string for the current buffer. If the buffer does not - exist or is not a terminal window, an error is given. - {only available when compiled with the |+terminal| feature} - -term_start({cmd} [, {options}]) *term_start()* - Open a terminal window and run {cmd} in it. - - {cmd} can be a string or a List, like with |job_start()|. The - string "NONE" can be used to open a terminal window without - starting a job, the pty of the terminal can be used by a - command like gdb. - - Returns the buffer number of the terminal window. If {cmd} - cannot be executed the window does open and shows an error - message. - If opening the window fails zero is returned. - - {options} are similar to what is used for |job_start()|, see - |job-options|. However, not all options can be used. These - are supported: - all timeout options - "stoponexit", "cwd", "env" - "callback", "out_cb", "err_cb", "exit_cb", "close_cb" - "in_io", "in_top", "in_bot", "in_name", "in_buf" - "out_io", "out_name", "out_buf", "out_modifiable", "out_msg" - "err_io", "err_name", "err_buf", "err_modifiable", "err_msg" - However, at least one of stdin, stdout or stderr must be - connected to the terminal. When I/O is connected to the - terminal then the callback function for that part is not used. - - There are extra options: - "term_name" name to use for the buffer name, instead - of the command name. - "term_rows" vertical size to use for the terminal, - instead of using 'termwinsize' - "term_cols" horizontal size to use for the terminal, - instead of using 'termwinsize' - "vertical" split the window vertically; note that - other window position can be defined with - command modifiers, such as |:belowright|. - "curwin" use the current window, do not split the - window; fails if the current buffer - cannot be |abandon|ed - "hidden" do not open a window - "norestore" do not add the terminal window to a - session file - "term_kill" what to do when trying to close the - terminal window, see |term_setkill()| - "term_finish" What to do when the job is finished: - "close": close any windows - "open": open window if needed - Note that "open" can be interruptive. - See |term++close| and |term++open|. - "term_opencmd" command to use for opening the window when - "open" is used for "term_finish"; must - have "%d" where the buffer number goes, - e.g. "10split|buffer %d"; when not - specified "botright sbuf %d" is used - "eof_chars" Text to send after all buffer lines were - written to the terminal. When not set - CTRL-D is used on MS-Windows. For Python - use CTRL-Z or "exit()". For a shell use - "exit". A CR is always added. - "ansi_colors" A list of 16 color names or hex codes - defining the ANSI palette used in GUI - color modes. See |g:terminal_ansi_colors|. - "tty_type" (MS-Windows only): Specify which pty to - use. See 'termwintype' for the values. - - {only available when compiled with the |+terminal| feature} - -term_wait({buf} [, {time}]) *term_wait()* - 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. - {only available when compiled with the |+terminal| feature} +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