Skip to content

Commit 8fbaeb1

Browse files
committed
patch 8.0.1641: job in terminal can't communicate with Vim
Problem: Job in terminal can't communicate with Vim. Solution: Add the terminal API.
1 parent 6587384 commit 8fbaeb1

6 files changed

Lines changed: 317 additions & 25 deletions

File tree

‎runtime/doc/terminal.txt‎

Lines changed: 95 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
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

368363
MS-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

394473
Most Vim tests execute a script inside Vim. For some tests this does not
395474
work, 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

409488
In some cases it can be bothersome to test that Vim displays the right
410489
characters 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
494573
times 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

499578
The Terminal debugging plugin can be used to debug a program with gdb and view
500579
the source code in a Vim window. Since this is completely contained inside

‎src/buffer.c‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -948,7 +948,7 @@ clear_wininfo(buf_T *buf)
948948
}
949949
}
950950

951-
#if defined(FEAT_LISTCMDS) || defined(PROTO)
951+
#if defined(FEAT_LISTCMDS) || defined(FEAT_TERMINAL) || defined(PROTO)
952952
/*
953953
* Go to another buffer. Handles the result of the ATTENTION dialog.
954954
*/

‎src/terminal.c‎

Lines changed: 141 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -38,12 +38,11 @@
3838
* in tl_scrollback are no longer used.
3939
*
4040
* TODO:
41-
* - Win32: In the GUI use a terminal emulator for :!cmd.
41+
* - For the "drop" command accept another argument for options.
4242
* - Add a way to set the 16 ANSI colors, to be used for 'termguicolors' and in
4343
* the GUI.
44-
* - Some way for the job running in the terminal to send a :drop command back
45-
* to the Vim running the terminal. Should be usable by a simple shell or
46-
* python script.
44+
* - Win32: Make terminal used for :!cmd in the GUI work better. Allow for
45+
* redirection.
4746
* - implement term_setsize()
4847
* - Copy text in the vterm to the Vim buffer once in a while, so that
4948
* completion works.
@@ -3145,6 +3144,140 @@ init_default_colors(term_T *term)
31453144
}
31463145
}
31473146

3147+
/*
3148+
* Handles a "drop" command from the job in the terminal.
3149+
* "item" is the file name, "item->li_next" may have options.
3150+
*/
3151+
static void
3152+
handle_drop_command(listitem_T *item)
3153+
{
3154+
char_u *fname = get_tv_string(&item->li_tv);
3155+
int bufnr;
3156+
win_T *wp;
3157+
tabpage_T *tp;
3158+
exarg_T ea;
3159+
3160+
bufnr = buflist_add(fname, BLN_LISTED | BLN_NOOPT);
3161+
FOR_ALL_TAB_WINDOWS(tp, wp)
3162+
{
3163+
if (wp->w_buffer->b_fnum == bufnr)
3164+
{
3165+
/* buffer is in a window already, go there */
3166+
goto_tabpage_win(tp, wp);
3167+
return;
3168+
}
3169+
}
3170+
3171+
/* open in new window, like ":sbuffer N" */
3172+
vim_memset(&ea, 0, sizeof(ea));
3173+
ea.cmd = (char_u *)"sbuffer";
3174+
goto_buffer(&ea, DOBUF_FIRST, FORWARD, bufnr);
3175+
}
3176+
3177+
/*
3178+
* Handles a function call from the job running in a terminal.
3179+
* "item" is the function name, "item->li_next" has the arguments.
3180+
*/
3181+
static void
3182+
handle_call_command(term_T *term, channel_T *channel, listitem_T *item)
3183+
{
3184+
char_u *func;
3185+
typval_T argvars[2];
3186+
typval_T rettv;
3187+
int doesrange;
3188+
3189+
if (item->li_next == NULL)
3190+
{
3191+
ch_log(channel, "Missing function arguments for call");
3192+
return;
3193+
}
3194+
func = get_tv_string(&item->li_tv);
3195+
3196+
if (!ASCII_ISUPPER(*func))
3197+
{
3198+
ch_log(channel, "Invalid function name: %s", func);
3199+
return;
3200+
}
3201+
3202+
argvars[0].v_type = VAR_NUMBER;
3203+
argvars[0].vval.v_number = term->tl_buffer->b_fnum;
3204+
argvars[1] = item->li_next->li_tv;
3205+
if (call_func(func, STRLEN(func), &rettv,
3206+
2, argvars, /* argv_func */ NULL,
3207+
/* firstline */ 1, /* lastline */ 1,
3208+
&doesrange, /* evaluate */ TRUE,
3209+
/* partial */ NULL, /* selfdict */ NULL) == OK)
3210+
{
3211+
clear_tv(&rettv);
3212+
ch_log(channel, "Function %s called", func);
3213+
}
3214+
else
3215+
ch_log(channel, "Calling function %s failed", func);
3216+
}
3217+
3218+
/*
3219+
* Called by libvterm when it cannot recognize an OSC sequence.
3220+
* We recognize a terminal API command.
3221+
*/
3222+
static int
3223+
parse_osc(const char *command, size_t cmdlen, void *user)
3224+
{
3225+
term_T *term = (term_T *)user;
3226+
js_read_T reader;
3227+
typval_T tv;
3228+
channel_T *channel = term->tl_job == NULL ? NULL
3229+
: term->tl_job->jv_channel;
3230+
3231+
/* We recognize only OSC 5 1 ; {command} */
3232+
if (cmdlen < 3 || STRNCMP(command, "51;", 3) != 0)
3233+
return 0; /* not handled */
3234+
3235+
reader.js_buf = vim_strnsave((char_u *)command + 3, cmdlen - 3);
3236+
if (reader.js_buf == NULL)
3237+
return 1;
3238+
reader.js_fill = NULL;
3239+
reader.js_used = 0;
3240+
if (json_decode(&reader, &tv, 0) == OK
3241+
&& tv.v_type == VAR_LIST
3242+
&& tv.vval.v_list != NULL)
3243+
{
3244+
listitem_T *item = tv.vval.v_list->lv_first;
3245+
3246+
if (item == NULL)
3247+
ch_log(channel, "Missing command");
3248+
else
3249+
{
3250+
char_u *cmd = get_tv_string(&item->li_tv);
3251+
3252+
item = item->li_next;
3253+
if (item == NULL)
3254+
ch_log(channel, "Missing argument for %s", cmd);
3255+
else if (STRCMP(cmd, "drop") == 0)
3256+
handle_drop_command(item);
3257+
else if (STRCMP(cmd, "call") == 0)
3258+
handle_call_command(term, channel, item);
3259+
else
3260+
ch_log(channel, "Invalid command received: %s", cmd);
3261+
}
3262+
}
3263+
else
3264+
ch_log(channel, "Invalid JSON received");
3265+
3266+
vim_free(reader.js_buf);
3267+
clear_tv(&tv);
3268+
return 1;
3269+
}
3270+
3271+
static VTermParserCallbacks parser_fallbacks = {
3272+
NULL, /* text */
3273+
NULL, /* control */
3274+
NULL, /* escape */
3275+
NULL, /* csi */
3276+
parse_osc, /* osc */
3277+
NULL, /* dcs */
3278+
NULL /* resize */
3279+
};
3280+
31483281
/*
31493282
* Create a new vterm and initialize it.
31503283
*/
@@ -3153,6 +3286,7 @@ create_vterm(term_T *term, int rows, int cols)
31533286
{
31543287
VTerm *vterm;
31553288
VTermScreen *screen;
3289+
VTermState *state;
31563290
VTermValue value;
31573291

31583292
vterm = vterm_new(rows, cols);
@@ -3186,8 +3320,9 @@ create_vterm(term_T *term, int rows, int cols)
31863320
#else
31873321
value.boolean = 0;
31883322
#endif
3189-
vterm_state_set_termprop(vterm_obtain_state(vterm),
3190-
VTERM_PROP_CURSORBLINK, &value);
3323+
state = vterm_obtain_state(vterm);
3324+
vterm_state_set_termprop(state, VTERM_PROP_CURSORBLINK, &value);
3325+
vterm_state_set_unrecognised_fallbacks(state, &parser_fallbacks, term);
31913326
}
31923327

31933328
/*

‎src/testdir/screendump.vim‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,8 @@ func RunVimInTerminal(arguments, options)
3838
endif
3939

4040
" Make a horizontal and vertical split, so that we can get exactly the right
41-
" size terminal window. Works only when we currently have one window.
42-
call assert_equal(1, winnr('$'))
41+
" size terminal window. Works only when the current window is full width.
42+
call assert_equal(&columns, winwidth(0))
4343
split
4444
vsplit
4545

0 commit comments

Comments
 (0)