One piece of functionality that is missing from the terminal feature is
for the job in the terminal to communcate back to Vim. It is possible
with the client-server feature, but that is not always available and
isn't easy to use.
term_sendkeys() can already be used to send anything from Vim to the
job. What is missing is for the job to send something to Vim that is
not displayed in the terminal.
This is for all kinds of plugins and extensions, thus it needs to be
flexible. At the same time, we must be careful not to open up a
security wormhole, letting a stray job have Vim do bad things (or just
messing up Vim by accident).
We'll start with a minimal API and extend it when useful. Also, we need
a way for Vim to await a complete message. This is similar to what is
used on a channel, wrapped inside an escape sequence. Using JSON
messages is the most flexible and easy to use. And it's already
implemented.
Below is the documentation that I have written so far. Feel free to
comment. I'll also see if I can make a first implementation to find out
how well this will work.
==============================================================================
2. Terminal communication *terminal-communication*
There are several ways to communicate with the job running in a terminal:
- Use |term_sendkeys()| to send text and escape sequences from Vim to the job.
- Use the JSON API to send encoded commands from the job to Vim.
- Use the |client-server| mechanism. This works on machines with an X server
and on MS-Windows.
Vim to job: term_sendkeys() ~
*terminal-to-job*
This allows for remote controlling the job running in the terminal. It is a
one-way mechanism. The job can update the display to signal back to Vim.
For example, if a shell is running in a terminal, you can do: >
call term_sendkeys(buf, "ls *.java\<CR>")
This requires for the job to be in the right state where it will do the right
thing when receiving the keys. For the above example, the shell must be
waiting for a command to be typed.
For a job that was written for the purpose, you can use the JSON API escape
sequence in the other direction. E.g.: >
call term_sendkeys(buf, "\<Esc>]51;["response"]\x07")
Job to Vim: JSON API ~
*terminal-api*
The job can send JSON to Vim, using a special escape sequence. The JSON
encodes a command that Vim understands. Example of such a message: >
<Esc>]51;["drop", "README.md"]<07>
The body is always a list, making it easy to find the end: ]<07>.
The <Esc>]51;msg<07> sequence is reserved by xterm for "Emacs shell", which is
similar to what we are doing here.
Currently supported commands:
call {funcname} {argument}
Call a user defined function with [argument]. This does not work to
call built-in functions to avoid security issues.
[argument] is decoded and passed to the function. Thus the function
must accept one argument. The user function must sanity check the
argument. The function can use |term_sendkeys()| to send back a
reply.
Example in JSON: >
["call", "Impression", ["play", 14]]
drop {filename} [options]
Let Vim open a file, like the `:drop` command.
[options], if present, must be a dictionary. For the entries see
|++opt|.
Example in JSON: >
["drop", "path/file.txt", {"ff": "dos"}]
Rationale: Why not allow for any command or expression? Because that would
create a security problem.
Using the client-server feature ~
*terminal-client-server*
This only works when v:servername is not empty. If needed you can set it,
before opening the terminal, with: >
call remote_startserver('vim-server')
$VIM_SERVERNAME is set in the terminal to pass on the server name.
In the job you can then do something like: >
vim --servername $VIM_SERVERNAME --remote +123 some_file.c
This will open the file "some_file.c" and put the cursor on line 123.
--
hundred-and-one symptoms of being an internet addict:
53. To find out what time it is, you send yourself an e-mail and check the
"Date:" field.
/// Bram Moolenaar -- b...@moolenaar.net -- http://www.Moolenaar.net \\\
/// sponsor Vim, vote for features -- http://www.Vim.org/sponsor/ \\\
\\\ an exciting new programming language -- http://www.Zimbu.org ///
\\\ help me help AIDS victims -- http://ICCF-Holland.org ///
--
--
You received this message from the "vim_dev" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php
---
You received this message because you are subscribed to the Google Groups
"vim_dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to vim_dev+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
