Mercurial > vim

comparison runtime/doc/channel.txt @ 8540:fec8655cf1bf v7.4.1560

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
commit https://github.com/vim/vim/commit/d6c2f0526064eef6f8917d2bad00df707d79ea16 Author: Bram Moolenaar <Bram@vim.org> Date: Mon Mar 14 23:22:59 2016 +0100 patch 7.4.1560 Problem: Dict options with a dash are more difficult to use. Solution: Use an underscore, so that dict.err_io can be used.
author Christian Brabandt <cb@256bit.org>
date Mon, 14 Mar 2016 23:30:05 +0100
parents da01d5da2cfa
children ed7251c3e2d3
comparison
equal deleted inserted replaced
8539:5212782d6378 8540:fec8655cf1bf
1 *channel.txt* For Vim version 7.4. Last change: 2016 Mar 12 1 *channel.txt* For Vim version 7.4. Last change: 2016 Mar 14
2 2
3 3
4 VIM REFERENCE MANUAL by Bram Moolenaar 4 VIM REFERENCE MANUAL by Bram Moolenaar
5 5
6 6
125 "mode" can be: *channel-mode* 125 "mode" can be: *channel-mode*
126 "json" - Use JSON, see below; most convenient way. Default. 126 "json" - Use JSON, see below; most convenient way. Default.
127 "js" - Use JS (JavaScript) encoding, more efficient than JSON. 127 "js" - Use JS (JavaScript) encoding, more efficient than JSON.
128 "nl" - Use messages that end in a NL character 128 "nl" - Use messages that end in a NL character
129 "raw" - Use raw messages 129 "raw" - Use raw messages
130 130 *in_mode* *out_mode* *err_mode*
131 "in-mode" mode specifically for stdin, only when using pipes 131 "in_mode" mode specifically for stdin, only when using pipes
132 "out-mode" mode specifically for stdout, only when using pipes 132 "out_mode" mode specifically for stdout, only when using pipes
133 "err-mode" mode specifically for stderr, only when using pipes 133 "err_mode" mode specifically for stderr, only when using pipes
134 Note: when setting "mode" the part specific mode is 134 Note: when setting "mode" the part specific mode is
135 overwritten. Therefore set "mode" first and the part specific 135 overwritten. Therefore set "mode" first and the part specific
136 mode later. 136 mode later.
137 137
138 Note: when writing to a file or buffer and when reading from a 138 Note: when writing to a file or buffer and when reading from a
139 buffer NL mode is used by default. 139 buffer NL mode is used by default.
140 140
141 *channel-callback* 141 *channel-callback* *E921*
142 "callback" A function that is called when a message is received that is 142 "callback" A function that is called when a message is received that is
143 not handled otherwise. It gets two arguments: the channel 143 not handled otherwise. It gets two arguments: the channel
144 and the received message. Example: > 144 and the received message. Example: >
145 func Handle(channel, msg) 145 func Handle(channel, msg)
146 echo 'Received: ' . a:msg 146 echo 'Received: ' . a:msg
151 of the received message, converted to Vim types. 151 of the received message, converted to Vim types.
152 When "mode" is "nl" the "msg" argument is one message, 152 When "mode" is "nl" the "msg" argument is one message,
153 excluding the NL. 153 excluding the NL.
154 When "mode" is "raw" the "msg" argument is the whole message 154 When "mode" is "raw" the "msg" argument is the whole message
155 as a string. 155 as a string.
156 *out-cb* 156 *out_cb*
157 "out-cb" A function like "callback" but used for stdout. Only for when 157 "out_cb" A function like "callback" but used for stdout. Only for when
158 the channel uses pipes. When "out-cb" wasn't set the channel 158 the channel uses pipes. When "out_cb" wasn't set the channel
159 callback is used. 159 callback is used.
160 *err-cb* 160 *err_cb*
161 "err-cb" A function like "callback" but used for stderr. Only for when 161 "err_cb" A function like "callback" but used for stderr. Only for when
162 the channel uses pipes. When "err-cb" wasn't set the channel 162 the channel uses pipes. When "err_cb" wasn't set the channel
163 callback is used. 163 callback is used.
164 164
165 *close-cb* 165 *close_cb*
166 "close-cb" A function that is called when the channel gets closed, other 166 "close_cb" A function that is called when the channel gets closed, other
167 than by calling ch_close(). It should be defined like this: > 167 than by calling ch_close(). It should be defined like this: >
168 func MyCloseHandler(channel) 168 func MyCloseHandler(channel)
169 < *waittime* 169 < *waittime*
170 "waittime" The time to wait for the connection to be made in 170 "waittime" The time to wait for the connection to be made in
171 milliseconds. A negative number waits forever. 171 milliseconds. A negative number waits forever.
177 msec at least. 177 msec at least.
178 178
179 "timeout" The time to wait for a request when blocking, E.g. when using 179 "timeout" The time to wait for a request when blocking, E.g. when using
180 ch_evalexpr(). In milliseconds. The default is 2000 (2 180 ch_evalexpr(). In milliseconds. The default is 2000 (2
181 seconds). 181 seconds).
182 *out-timeout* *err-timeout* 182 *out_timeout* *err_timeout*
183 "out-timeout" Timeout for stdout. Only when using pipes. 183 "out_timeout" Timeout for stdout. Only when using pipes.
184 "err-timeout" Timeout for stderr. Only when using pipes. 184 "err_timeout" Timeout for stderr. Only when using pipes.
185 Note: when setting "timeout" the part specific mode is 185 Note: when setting "timeout" the part specific mode is
186 overwritten. Therefore set "timeout" first and the part 186 overwritten. Therefore set "timeout" first and the part
187 specific mode later. 187 specific mode later.
188 188
189 When "mode" is "json" or "js" the "callback" is optional. When omitted it is 189 When "mode" is "json" or "js" the "callback" is optional. When omitted it is
438 this in {options}. When changing the mode later some text may have already 438 this in {options}. When changing the mode later some text may have already
439 been received and not parsed correctly. 439 been received and not parsed correctly.
440 440
441 If the command produces a line of output that you want to deal with, specify 441 If the command produces a line of output that you want to deal with, specify
442 a handler for stdout: > 442 a handler for stdout: >
443 let job = job_start(command, {"out-cb": "MyHandler"}) 443 let job = job_start(command, {"out_cb": "MyHandler"})
444 The function will be called with the channel and a message. You would define 444 The function will be called with the channel and a message. You would define
445 it like this: > 445 it like this: >
446 func MyHandler(channel, msg) 446 func MyHandler(channel, msg)
447 447
448 Without the handler you need to read the output with |ch_read()| or 448 Without the handler you need to read the output with |ch_read()| or
449 |ch_readraw()|. 449 |ch_readraw()|.
450 450
451 The handler defined for "out-cb" will not receive stderr. If you want to 451 The handler defined for "out_cb" will not receive stderr. If you want to
452 handle that separately, add an "err-cb" handler: > 452 handle that separately, add an "err_cb" handler: >
453 let job = job_start(command, {"out-cb": "MyHandler", 453 let job = job_start(command, {"out_cb": "MyHandler",
454 \ "err-cb": "ErrHandler"}) 454 \ "err_cb": "ErrHandler"})
455 455
456 If you want to handle both stderr and stdout with one handler use the 456 If you want to handle both stderr and stdout with one handler use the
457 "callback" option: > 457 "callback" option: >
458 let job = job_start(command, {"callback": "MyHandler"}) 458 let job = job_start(command, {"callback": "MyHandler"})
459 459
461 JSON or JS mode you can use ch_evalexpr(). 461 JSON or JS mode you can use ch_evalexpr().
462 462
463 There are several options you can use, see |job-options|. 463 There are several options you can use, see |job-options|.
464 For example, to start a job and write its output in buffer "dummy": > 464 For example, to start a job and write its output in buffer "dummy": >
465 let logjob = job_start("tail -f /tmp/log", 465 let logjob = job_start("tail -f /tmp/log",
466 \ {'out-io': 'buffer', 'out-name': 'dummy'}) 466 \ {'out_io': 'buffer', 'out_name': 'dummy'})
467 sbuf dummy 467 sbuf dummy
468 468
469 469
470 Job input from a buffer ~ 470 Job input from a buffer ~
471 471
472 To run a job that reads from a buffer: > 472 To run a job that reads from a buffer: >
473 let job = job_start({command}, 473 let job = job_start({command},
474 \ {'in-io': 'buffer', 'in-name': 'mybuffer'}) 474 \ {'in_io': 'buffer', 'in_name': 'mybuffer'})
475 < 475 <
476 *E915* *E918* 476 *E915* *E918*
477 The buffer is found by name, similar to |bufnr()|. The buffer must exist and 477 The buffer is found by name, similar to |bufnr()|. The buffer must exist and
478 be loaded when job_start() is called. 478 be loaded when job_start() is called.
479 479
480 By default this reads the whole buffer. This can be changed with the "in-top" 480 By default this reads the whole buffer. This can be changed with the "in_top"
481 and "in-bot" options. 481 and "in_bot" options.
482 482
483 A special mode is when "in-top" is set to zero and "in-bot" is not set: Every 483 A special mode is when "in_top" is set to zero and "in_bot" is not set: Every
484 time a line is added to the buffer, the last-but-one line will be send to the 484 time a line is added to the buffer, the last-but-one line will be send to the
485 job stdin. This allows for editing the last line and sending it when pressing 485 job stdin. This allows for editing the last line and sending it when pressing
486 Enter. 486 Enter.
487 487
488 ============================================================================== 488 ==============================================================================
489 9. Starting a job without a channel *job-start-nochannel* 489 9. Starting a job without a channel *job-start-nochannel*
490 490
491 To start another process without creating a channel: > 491 To start another process without creating a channel: >
492 let job = job_start(command, 492 let job = job_start(command,
493 \ {"in-io": "null", "out-io": "null", "err-io": "null"}) 493 \ {"in_io": "null", "out_io": "null", "err_io": "null"})
494 494
495 This starts {command} in the background, Vim does not wait for it to finish. 495 This starts {command} in the background, Vim does not wait for it to finish.
496 496
497 When Vim sees that neither stdin, stdout or stderr are connected, no channel 497 When Vim sees that neither stdin, stdout or stderr are connected, no channel
498 will be created. Often you will want to include redirection in the command to 498 will be created. Often you will want to include redirection in the command to
522 See |job_setoptions()| and |ch_setoptions()|. 522 See |job_setoptions()| and |ch_setoptions()|.
523 523
524 *job-callback* 524 *job-callback*
525 "callback": handler Callback for something to read on any part of the 525 "callback": handler Callback for something to read on any part of the
526 channel. 526 channel.
527 *job-out-cb* 527 *job-out_cb*
528 "out-cb": handler Callback for when there is something to read on 528 "out_cb": handler Callback for when there is something to read on
529 stdout. 529 stdout.
530 *job-err-cb* 530 *job-err_cb*
531 "err-cb": handler Callback for when there is something to read on 531 "err_cb": handler Callback for when there is something to read on
532 stderr. 532 stderr.
533 *job-close-cb* 533 *job-close_cb*
534 "close-cb": handler Callback for when the channel is closed. Same as 534 "close_cb": handler Callback for when the channel is closed. Same as
535 "close-cb" on ch_open(). 535 "close_cb" on ch_open().
536 *job-exit-cb* 536 *job-exit_cb*
537 "exit-cb": handler Callback for when the job ends. The arguments are the 537 "exit_cb": handler Callback for when the job ends. The arguments are the
538 job and the exit status. 538 job and the exit status.
539 Vim checks about every 10 seconds for jobs that ended. 539 Vim checks about every 10 seconds for jobs that ended.
540 The callback can also be triggered by calling 540 The callback can also be triggered by calling
541 |job_status()|. 541 |job_status()|.
542 *job-stoponexit* 542 *job-stoponexit*
555 will be disconnected from what they were used before. 555 will be disconnected from what they were used before.
556 If the channel was still use by another job this may 556 If the channel was still use by another job this may
557 cause I/O errors. 557 cause I/O errors.
558 Existing callbacks and other settings remain. 558 Existing callbacks and other settings remain.
559 559
560 *job-in-io* *in-top* *in-bot* *in-name* *in-buf* 560 *job-in_io* *in_top* *in_bot* *in_name* *in_buf*
561 "in-io": "null" disconnect stdin (read from /dev/null) 561 "in_io": "null" disconnect stdin (read from /dev/null)
562 "in-io": "pipe" stdin is connected to the channel (default) 562 "in_io": "pipe" stdin is connected to the channel (default)
563 "in-io": "file" stdin reads from a file 563 "in_io": "file" stdin reads from a file
564 "in-io": "buffer" stdin reads from a buffer 564 "in_io": "buffer" stdin reads from a buffer
565 "in-top": number when using "buffer": first line to send (default: 1) 565 "in_top": number when using "buffer": first line to send (default: 1)
566 "in-bot": number when using "buffer": last line to send (default: last) 566 "in_bot": number when using "buffer": last line to send (default: last)
567 "in-name": "/path/file" the name of the file or buffer to read from 567 "in_name": "/path/file" the name of the file or buffer to read from
568 "in-buf": number the number of the buffer to read from 568 "in_buf": number the number of the buffer to read from
569 569
570 *job-out-io* *out-name* *out-buf* 570 *job-out_io* *out_name* *out_buf*
571 "out-io": "null" disconnect stdout (goes to /dev/null) 571 "out_io": "null" disconnect stdout (goes to /dev/null)
572 "out-io": "pipe" stdout is connected to the channel (default) 572 "out_io": "pipe" stdout is connected to the channel (default)
573 "out-io": "file" stdout writes to a file 573 "out_io": "file" stdout writes to a file
574 "out-io": "buffer" stdout appends to a buffer 574 "out_io": "buffer" stdout appends to a buffer
575 "out-name": "/path/file" the name of the file or buffer to write to 575 "out_name": "/path/file" the name of the file or buffer to write to
576 "out-buf": number the number of the buffer to write to 576 "out_buf": number the number of the buffer to write to
577 577
578 *job-err-io* *err-name* *err-buf* 578 *job-err_io* *err_name* *err_buf*
579 "err-io": "out" stderr messages to go to stdout 579 "err_io": "out" stderr messages to go to stdout
580 "err-io": "null" disconnect stderr (goes to /dev/null) 580 "err_io": "null" disconnect stderr (goes to /dev/null)
581 "err-io": "pipe" stderr is connected to the channel (default) 581 "err_io": "pipe" stderr is connected to the channel (default)
582 "err-io": "file" stderr writes to a file 582 "err_io": "file" stderr writes to a file
583 "err-io": "buffer" stderr appends to a buffer 583 "err_io": "buffer" stderr appends to a buffer
584 "err-name": "/path/file" the name of the file or buffer to write to 584 "err_name": "/path/file" the name of the file or buffer to write to
585 "err-buf": number the number of the buffer to write to 585 "err_buf": number the number of the buffer to write to
586 586
587 587
588 Writing to a buffer ~ 588 Writing to a buffer ~
589 589
590 When the out-io or err-io mode is "buffer" and there is a callback, the text 590 When the out_io or err_io mode is "buffer" and there is a callback, the text
591 is appended to the buffer before invoking the callback. 591 is appended to the buffer before invoking the callback.
592 592
593 When a buffer is used both for input and output, the output lines are put 593 When a buffer is used both for input and output, the output lines are put
594 above the last line, since the last line is what is written to the channel 594 above the last line, since the last line is what is written to the channel
595 input. Otherwise lines are appended below the last line. 595 input. Otherwise lines are appended below the last line.
612 612
613 Undo is synced for every added line. 613 Undo is synced for every added line.
614 614
615 615
616 Writing to a file ~ 616 Writing to a file ~
617 617 *E920*
618 The file is created with permissions 600 (read-write for the user, not 618 The file is created with permissions 600 (read-write for the user, not
619 accessible for others). Use |setfperm()| to change this. 619 accessible for others). Use |setfperm()| to change this.
620 620
621 If the file already exists it is truncated. 621 If the file already exists it is truncated.
622 622