diff options
Diffstat (limited to 'runtime')
| -rw-r--r-- | runtime/doc/channel.txt | 99 | ||||
| -rw-r--r-- | runtime/doc/eval.txt | 73 |
2 files changed, 95 insertions, 77 deletions
diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt index 323d9ef004..f3fa3fa180 100644 --- a/runtime/doc/channel.txt +++ b/runtime/doc/channel.txt @@ -43,59 +43,66 @@ functions like |chansend()| consume channel ids. ============================================================================== 2. Reading and writing raw bytes *channel-bytes* -By default, channels opened by vimscript functions will operate with raw -bytes. Additionally, for a job channel using rpc, bytes can still be -read over its stderr. Similarily, only bytes can be written to nvim's own stderr. - - *channel-callback* *on_stdout* *on_stderr* *on_stdin* *on_data* -Scripts can react to channel activity (received data) via callback functions -assigned to the `on_stdout`, `on_stderr`, `on_stdin`, and `on_data` options. -Callbacks should be fast, avoid potentially slow/expensive work. +Channels opened by Vimscript functions operate with raw bytes by default. For +a job channel using RPC, bytes can still be read over its stderr. Similarily, +only bytes can be written to Nvim's own stderr. + + *channel-callback* +on_stdout({chan-id}, {data}, {name}) *on_stdout* +on_stderr({chan-id}, {data}, {name}) *on_stderr* +on_stdin({chan-id}, {data}, {name}) *on_stdin* +on_data({chan-id}, {data}, {name}) *on_data* + Scripts can react to channel activity (received data) via callback + functions assigned to the `on_stdout`, `on_stderr`, `on_stdin`, or + `on_data` option keys. Callbacks should be fast: avoid potentially + slow/expensive work. + + Parameters: ~ + {chan-id} Channel handle. |channel-id| + {data} Raw data (|readfile()|-style list of strings) read from + the channel. EOF is a single-item list: `['']`. First and + last items may be partial lines! |channel-lines| + {name} Stream name (string) like "stdout", so the same function + can handle multiple streams. Event names depend on how the + channel was opened and in what mode/protocol. *channel-buffered* -By default the callback is invoked immediately as data is available; empty -data indicates EOF (stream closed). Alternatively, set the `stdout_buffered`, -`stderr_buffered`, `stdin_buffered`, or `data_buffered` options to invoke the -callback only on EOF, after all output was gathered. + The callback is invoked immediately as data is available, where + a single-item list `['']` indicates EOF (stream closed). Alternatively + set the `stdout_buffered`, `stderr_buffered`, `stdin_buffered`, or + `data_buffered` option keys to invoke the callback only after all output + was gathered and the stream was closed. *E5210* -If the stream is set as buffered without assigning a callback, the data is -saved in the options dict with the stream name as key. This requires a new -options dict for each opened channel (|copy()|). If the stream name key -is already set, error E5210 is raised. - -Channel callback functions accept these arguments: - - 0: |channel-id| - 1: Raw data read from the channel, formatted as a |readfile()|-style - list. If EOF occured, a single empty string `['']` will be passed in. - Note that the items in this list do not directly correspond to actual - lines in the output. See |channel-lines| - 2: Stream name as a string, like `"stdout"`. This is to allow multiple - stream handlers to be implemented by the same function. The available - events depend on how the channel was opened and in what mode/protocol. + If a buffering mode is used without a callback, the data is saved in the + stream {name} key of the options dict. It is an error if the key exists. *channel-lines* - Note: - stream event handlers may receive partial (incomplete) lines. For a given - invocation of on_stdout etc, `a:data` is not guaranteed to end - with a newline. - - `abcdefg` may arrive as `['abc']`, `['defg']`. - - `abc\nefg` may arrive as `['abc', '']`, `['efg']` or `['abc']`, - `['','efg']`, or even `['ab']`, `['c','efg']`. - - If you only are interested in complete output when the process exits, - use buffered mode. Otherwise, an easy way to deal with this: - initialize a list as `['']`, then append to it as follows: > - let s:chunks = [''] - func! s:on_event(job_id, data, event) dict - let s:chunks[-1] .= a:data[0] - call extend(s:chunks, a:data[1:]) - endf + Stream event handlers receive data as it becomes available from the OS, + thus the first and last items in the {data} list may be partial lines. + Empty string completes the previous partial line. Examples (not including + the final `['']` emitted at EOF): + - `foobar` may arrive as `['fo'], ['obar']` + - `foo\nbar` may arrive as + `['foo','bar']` + or `['foo',''], ['bar']` + or `['foo'], ['','bar']` + or `['fo'], ['o','bar']` + There are two ways to deal with this: + 1. To wait for the entire output, use |channel-buffered| mode. + 2. To read line-by-line, use the following code: > + let s:lines = [''] + func! s:on_event(job_id, data, event) dict + let eof = (a:data == ['']) + " Complete the previous line. + let s:lines[-1] .= a:data[0] + " Append (last item may be a partial line, until EOF). + call extend(s:lines, a:data[1:]) + endf < -Additionally, if the callbacks are Dictionary functions, |self| can be used to -refer to the options dictionary containing the callbacks. |Partial|s can also be -used as callbacks. +If the callback functions are |Dictionary-function|s, |self| refers to the +options dictionary containing the callbacks. |Partial|s can also be used as +callbacks. Data can be sent to the channel using the |chansend()| function. Here is a simple example, echoing some data through a cat-process: diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index cc97117ffd..00194b4613 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -634,15 +634,15 @@ Expression syntax summary, from least to most significant: expr5 isnot expr5 different |List| instance |expr5| expr6 - expr6 + expr6 .. number addition or list concatenation - expr6 - expr6 .. number subtraction - expr6 . expr6 .. string concatenation - expr6 .. expr6 .. string concatenation + expr6 + expr6 ... number addition, list or blob concatenation + expr6 - expr6 ... number subtraction + expr6 . expr6 ... string concatenation + expr6 .. expr6 ... string concatenation |expr6| expr7 - expr7 * expr7 .. number multiplication - expr7 / expr7 .. number division - expr7 % expr7 .. number modulo + expr7 * expr7 ... number multiplication + expr7 / expr7 ... number division + expr7 % expr7 ... number modulo |expr7| expr8 ! expr7 logical NOT @@ -708,7 +708,9 @@ use in a variable such as "a:1". expr2 and expr3 *expr2* *expr3* --------------- - *expr-barbar* *expr-&&* +expr3 || expr3 .. logical OR *expr-barbar* +expr4 && expr4 .. logical AND *expr-&&* + The "||" and "&&" operators take one argument on each side. The arguments are (converted to) Numbers. The result is: @@ -848,10 +850,10 @@ can be matched like an ordinary character. Examples: expr5 and expr6 *expr5* *expr6* --------------- -expr6 + expr6 .. Number addition or |List| concatenation *expr-+* -expr6 - expr6 .. Number subtraction *expr--* -expr6 . expr6 .. String concatenation *expr-.* -expr6 .. expr6 .. String concatenation *expr-..* +expr6 + expr6 Number addition, |List| or |Blob| concatenation *expr-+* +expr6 - expr6 Number subtraction *expr--* +expr6 . expr6 String concatenation *expr-.* +expr6 .. expr6 String concatenation *expr-..* For |Lists| only "+" is possible and then both expr6 must be a list. The result is a new list with the two lists Concatenated. @@ -859,11 +861,11 @@ result is a new list with the two lists Concatenated. For String concatenation ".." is preferred, since "." is ambiguous, it is also used for |Dict| member access and floating point numbers. -expr7 * expr7 .. Number multiplication *expr-star* -expr7 / expr7 .. Number division *expr-/* -expr7 % expr7 .. Number modulo *expr-%* +expr7 * expr7 Number multiplication *expr-star* +expr7 / expr7 Number division *expr-/* +expr7 % expr7 Number modulo *expr-%* -For all, except ".", Strings are converted to Numbers. +For all, except "." and "..", Strings are converted to Numbers. For bitwise operators see |and()|, |or()| and |xor()|. Note the difference between "+" and ".": @@ -1054,11 +1056,6 @@ These are INVALID: 3. empty {M} 1e40 missing .{M} - *float-pi* *float-e* -A few useful values to copy&paste: > - :let pi = 3.14159265359 - :let e = 2.71828182846 - Rationale: Before floating point was introduced, the text "123.456" was interpreted as the two numbers "123" and "456", both converted to a string and concatenated, @@ -1067,6 +1064,15 @@ could not find it intentionally being used in Vim scripts, this backwards incompatibility was accepted in favor of being able to use the normal notation for floating point numbers. + *float-pi* *float-e* +A few useful values to copy&paste: > + :let pi = 3.14159265359 + :let e = 2.71828182846 +Or, if you don't want to write them in as floating-point literals, you can +also use functions, like the following: > + :let pi = acos(-1.0) + :let e = exp(1.0) +< *floating-point-precision* The precision and range of floating points numbers depends on what "double" means in the library Vim was compiled with. There is no way to change this at @@ -1106,8 +1112,10 @@ A string constant accepts these special characters: \\ backslash \" double quote \<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W. This is for use - in mappings, the 0x80 byte is escaped. Don't use <Char-xxxx> to get a - utf-8 character, use \uxxxx as mentioned above. + in mappings, the 0x80 byte is escaped. + To use the double quote character it must be escaped: "<M-\">". + Don't use <Char-xxxx> to get a utf-8 character, use \uxxxx as + mentioned above. Note that "\xff" is stored as the byte 255, which may be invalid in some encodings. Use "\u00ff" to store character 255 correctly as UTF-8. @@ -1216,8 +1224,8 @@ The arguments are optional. Example: > *closure* Lambda expressions can access outer scope variables and arguments. This is often called a closure. Example where "i" and "a:arg" are used in a lambda -while they exist in the function scope. They remain valid even after the -function returns: > +while they already exist in the function scope. They remain valid even after +the function returns: > :function Foo(arg) : let i = 3 : return {x -> x + i - a:arg} @@ -1225,8 +1233,11 @@ function returns: > :let Bar = Foo(4) :echo Bar(6) < 5 -See also |:func-closure|. Lambda and closure support can be checked with: > - if has('lambda') +Note that the variables must exist in the outer scope before the lamba is +defined for this to work. See also |:func-closure|. + +Lambda and closure support can be checked with: > + if has('lambda') Examples for using a lambda expression with |sort()|, |map()| and |filter()|: > :echo map([1, 2, 3], {idx, val -> val + 1}) @@ -5277,9 +5288,9 @@ jobstart({cmd}[, {opts}]) *jobstart()* *jobstart-options* {opts} is a dictionary with these keys: |on_stdout|: stdout event handler (function name or |Funcref|) - stdout_buffered : read stdout in |buffered| mode. + stdout_buffered : read stdout in |channel-buffered| mode. |on_stderr|: stderr event handler (function name or |Funcref|) - stderr_buffered : read stderr in |buffered| mode. + stderr_buffered : read stderr in |channel-buffered| mode. |on_exit| : exit event handler (function name or |Funcref|) cwd : Working directory of the job; defaults to |current-directory|. @@ -7686,7 +7697,7 @@ sockconnect({mode}, {address}, {opts}) *sockconnect()* {opts} is a dictionary with these keys: |on_data| : callback invoked when data was read from socket - data_buffered : read data from socket in |buffered| mode. + data_buffered : read socket data in |channel-buffered| mode. rpc : If set, |msgpack-rpc| will be used to communicate over the socket. Returns: @@ -7855,7 +7866,7 @@ stdioopen({opts}) *stdioopen()* {opts} is a dictionary with these keys: |on_stdin| : callback invoked when stdin is written to. - stdin_buffered : read stdin in |buffered| mode. + stdin_buffered : read stdin in |channel-buffered| mode. rpc : If set, |msgpack-rpc| will be used to communicate over stdio Returns: |