1- *terminal.txt* For Vim version 8.0. Last change: 2018 Mar 16
1+ *terminal.txt* For Vim version 8.0. Last change: 2018 Mar 25
22
33
44 VIM REFERENCE MANUAL by Bram Moolenaar
@@ -23,12 +23,16 @@ If the result is "1" you have it.
2323 Session | terminal-session |
2424 Unix | terminal-unix |
2525 MS-Windows | terminal-ms-windows |
26- 2. Remote testing | terminal-testing |
27- 3. Diffing screen dumps | terminal-diff |
26+ 2. Terminal communication | terminal-communication |
27+ Vim to job: term_sendkeys() | terminal-to-job |
28+ Job to Vim: JSON API | terminal-api |
29+ Using the client-server feature | terminal-client-server |
30+ 3. Remote testing | terminal-testing |
31+ 4. Diffing screen dumps | terminal-diff |
2832 Writing a screen dump test for Vim | terminal-dumptest |
2933 Creating a screen dump | terminal-screendump |
3034 Comparing screen dumps | terminal-diffscreendump |
31- 4 . Debugging | terminal-debug |
35+ 5 . Debugging | terminal-debug |
3236 Starting | termdebug-starting |
3337 Example session | termdebug-example |
3438 Stepping through code | termdebug-stepping |
@@ -355,15 +359,6 @@ Environment variables are used to pass information to the running job:
355359 COLORS number of colors, 't_Co' (256*256*256 in the GUI)
356360 VIM_SERVERNAME v:servername
357361
358- The | client-server | feature can be used to communicate with the Vim instance
359- where the job was started. This only works when v:servername is not empty.
360- If needed you can set it with: >
361- call remote_startserver('vim-server')
362-
363- In the job you can then do something like: >
364- vim --servername $VIM_SERVERNAME --remote +123 some_file.c
365- This will open the file "some_file.c" and put the cursor on line 123.
366-
367362
368363MS-Windows ~
369364 *terminal-ms-windows*
@@ -389,7 +384,91 @@ Environment variables are used to pass information to the running job:
389384 VIM_SERVERNAME v:servername
390385
391386==============================================================================
392- 2. Remote testing *terminal-testing*
387+ 2. Terminal communication *terminal-communication*
388+
389+ There are several ways to communicate with the job running in a terminal:
390+ - Use | term_sendkeys() | to send text and escape sequences from Vim to the job.
391+ - Use the JSON API to send encoded commands from the job to Vim.
392+ - Use the | client-server | mechanism. This works on machines with an X server
393+ and on MS-Windows.
394+
395+
396+ Vim to job: term_sendkeys() ~
397+ *terminal-to-job*
398+ This allows for remote controlling the job running in the terminal. It is a
399+ one-way mechanism. The job can update the display to signal back to Vim.
400+ For example, if a shell is running in a terminal, you can do: >
401+ call term_sendkeys(buf, "ls *.java\<CR>")
402+
403+ This requires for the job to be in the right state where it will do the right
404+ thing when receiving the keys. For the above example, the shell must be
405+ waiting for a command to be typed.
406+
407+ For a job that was written for the purpose, you can use the JSON API escape
408+ sequence in the other direction. E.g.: >
409+ call term_sendkeys(buf, "\<Esc>]51;["response"]\x07")
410+
411+
412+ Job to Vim: JSON API ~
413+ *terminal-api*
414+ The job can send JSON to Vim, using a special escape sequence. The JSON
415+ encodes a command that Vim understands. Example of such a message: >
416+ <Esc>]51;["drop", "README.md"]<07>
417+
418+ The body is always a list, making it easy to find the end: ]<07> .
419+ The <Esc> ]51;msg<07> sequence is reserved by xterm for "Emacs shell", which is
420+ similar to what we are doing here.
421+
422+ Currently supported commands:
423+
424+ call {funcname} {argument}
425+
426+ Call a user defined function with [argument] . The function is
427+ called with the buffer number of the terminal and the decoded
428+ argument. The user function must sanity check the argument.
429+ The function can use | term_sendkeys() | to send back a reply.
430+ Example in JSON: >
431+ ["call", "Impression", ["play", 14]]
432+ < Calls a function defined like this: >
433+ function Impression(bufnum, arglist)
434+ if len(a:arglist) == 2
435+ echo "impression " . a:arglist[0]
436+ echo "count " . a:arglist[1]
437+ endif
438+ endfunc
439+ <
440+ drop {filename}
441+
442+ Let Vim open a file, like the `:drop ` command. If {filename}
443+ is already open in a window, switch to that window. Otherwise
444+ open a new window to edit {filename} .
445+ Example in JSON: >
446+ ["drop", "path/file.txt", {"ff": "dos"}]
447+
448+ A trick to have Vim send this escape sequence: >
449+ exe "set t_ts=\<Esc>]51; t_fs=\x07"
450+ let &titlestring = '["call","TryThis",["hello",123]]'
451+ redraw
452+ set t_ts& t_fs&
453+
454+ Rationale: Why not allow for any command or expression? Because that might
455+ create a security problem.
456+
457+
458+ Using the client-server feature ~
459+ *terminal-client-server*
460+ This only works when v:servername is not empty. If needed you can set it,
461+ before opening the terminal, with: >
462+ call remote_startserver('vim-server')
463+
464+ $VIM_SERVERNAME is set in the terminal to pass on the server name.
465+
466+ In the job you can then do something like: >
467+ vim --servername $VIM_SERVERNAME --remote +123 some_file.c
468+ This will open the file "some_file.c" and put the cursor on line 123.
469+
470+ ==============================================================================
471+ 3. Remote testing *terminal-testing*
393472
394473Most Vim tests execute a script inside Vim. For some tests this does not
395474work, running the test interferes with the code being tested. To avoid this
@@ -404,7 +483,7 @@ term_scrape() inspect terminal screen
404483
405484
406485==============================================================================
407- 3 . Diffing screen dumps *terminal-diff*
486+ 4 . Diffing screen dumps *terminal-diff*
408487
409488In some cases it can be bothersome to test that Vim displays the right
410489characters on the screen. E.g. with syntax highlighting. To make this
@@ -494,7 +573,7 @@ Alternatively, press "s" to swap the first and second dump. Do this several
494573times so that you can spot the difference in the context of the text.
495574
496575==============================================================================
497- 4 . Debugging *terminal-debug*
576+ 5 . Debugging *terminal-debug*
498577
499578The Terminal debugging plugin can be used to debug a program with gdb and view
500579the source code in a Vim window. Since this is completely contained inside
0 commit comments