Mercurial > vim
annotate runtime/doc/remote.txt @ 27804:8fc68ce4a097
Update runtime files
Commit: https://github.com/vim/vim/commit/944697ae19683441981539cd4d2469df89d6ec82
Author: Bram Moolenaar <Bram@vim.org>
Date: Sun Feb 20 19:48:20 2022 +0000
Update runtime files
| author | Bram Moolenaar <Bram@vim.org> |
|---|---|
| date | Sun, 20 Feb 2022 21:00:04 +0100 |
| parents | edb7d53fc7e3 |
| children | f8116058ca76 |
| rev | line source |
|---|---|
| 27804 | 1 *remote.txt* For Vim version 8.2. Last change: 2022 Feb 17 |
| 7 | 2 |
| 3 | |
| 4 VIM REFERENCE MANUAL by Bram Moolenaar | |
| 5 | |
| 6 | |
| 7 Vim client-server communication *client-server* | |
| 8 | |
| 9 1. Common functionality |clientserver| | |
| 10 2. X11 specific items |x11-clientserver| | |
| 11 3. MS-Windows specific items |w32-clientserver| | |
| 12 | |
| 13 ============================================================================== | |
| 14 1. Common functionality *clientserver* | |
| 15 | |
| 16 When compiled with the |+clientserver| option, Vim can act as a command | |
| 17 server. It accepts messages from a client and executes them. At the same | |
| 18 time, Vim can function as a client and send commands to a Vim server. | |
| 19 | |
| 20 The following command line arguments are available: | |
| 21 | |
| 22 argument meaning ~ | |
| 23 | |
| 24 --remote [+{cmd}] {file} ... *--remote* | |
| 25 Open the file list in a remote Vim. When | |
| 26 there is no Vim server, execute locally. | |
| 27 There is one optional init command: +{cmd}. | |
| 28 This must be an Ex command that can be | |
| 29 followed by "|". | |
| 30 The rest of the command line is taken as the | |
| 31 file list. Thus any non-file arguments must | |
| 32 come before this. | |
| 33 You cannot edit stdin this way |--|. | |
| 34 The remote Vim is raised. If you don't want | |
| 35 this use > | |
| 36 vim --remote-send "<C-\><C-N>:n filename<CR>" | |
| 6648 | 37 < |
| 38 --remote-silent [+{cmd}] {file} ... *--remote-silent* | |
| 7 | 39 As above, but don't complain if there is no |
| 40 server and the file is edited locally. | |
| 41 --remote-wait [+{cmd}] {file} ... *--remote-wait* | |
| 42 As --remote, but wait for files to complete | |
| 43 (unload) in remote Vim. | |
| 44 --remote-wait-silent [+{cmd}] {file} ... *--remote-wait-silent* | |
| 45 As --remote-wait, but don't complain if there | |
| 46 is no server. | |
| 856 | 47 *--remote-tab* |
| 733 | 48 --remote-tab Like --remote but open each file in a new |
| 856 | 49 tabpage. |
| 50 *--remote-tab-silent* | |
| 733 | 51 --remote-tab-silent Like --remote-silent but open each file in a |
| 856 | 52 new tabpage. |
| 733 | 53 *--remote-tab-wait* |
| 54 --remote-tab-wait Like --remote-wait but open each file in a new | |
| 856 | 55 tabpage. |
| 733 | 56 |
| 856 | 57 *--remote-tab-wait-silent* |
| 733 | 58 --remote-tab-wait-silent Like --remote-wait-silent but open each file |
| 856 | 59 in a new tabpage. |
| 7 | 60 *--servername* |
| 61 --servername {name} Become the server {name}. When used together | |
| 62 with one of the --remote commands: connect to | |
| 63 server {name} instead of the default (see | |
| 14193 | 64 below). The name used will be uppercase. |
| 7 | 65 *--remote-send* |
| 1624 | 66 --remote-send {keys} Send {keys} to server and exit. The {keys} |
| 67 are not mapped. Special key names are | |
| 68 recognized, e.g., "<CR>" results in a CR | |
| 69 character. | |
| 7 | 70 *--remote-expr* |
| 714 | 71 --remote-expr {expr} Evaluate {expr} in server and print the result |
| 856 | 72 on stdout. |
| 7 | 73 *--serverlist* |
| 74 --serverlist Output a list of server names. | |
| 75 | |
| 76 | |
| 77 Examples ~ | |
| 78 | |
| 79 Edit "file.txt" in an already running GVIM server: > | |
| 80 gvim --remote file.txt | |
| 81 | |
| 82 Edit "file.txt" in an already running server called FOOBAR: > | |
| 83 gvim --servername FOOBAR --remote file.txt | |
| 84 | |
| 85 Edit "file.txt" in server "FILES" if it exists, become server "FILES" | |
| 86 otherwise: > | |
| 87 gvim --servername FILES --remote-silent file.txt | |
| 88 | |
| 89 This doesn't work, all arguments after --remote will be used as file names: > | |
| 90 gvim --remote --servername FOOBAR file.txt | |
| 91 | |
| 92 Edit file "+foo" in a remote server (note the use of "./" to avoid the special | |
| 93 meaning of the leading plus): > | |
| 94 vim --remote ./+foo | |
| 95 | |
| 96 Tell the remote server "BLA" to write all files and exit: > | |
| 97 vim --servername BLA --remote-send '<C-\><C-N>:wqa<CR>' | |
| 98 | |
| 99 | |
| 11914 | 100 SERVER NAME *client-server-name* |
| 7 | 101 |
| 102 By default Vim will try to register the name under which it was invoked (gvim, | |
| 103 egvim ...). This can be overridden with the --servername argument. If the | |
| 104 specified name is not available, a postfix is applied until a free name is | |
| 237 | 105 encountered, i.e. "gvim1" for the second invocation of gvim on a particular |
| 7 | 106 X-server. The resulting name is available in the servername builtin variable |
| 107 |v:servername|. The case of the server name is ignored, thus "gvim" and | |
| 108 "GVIM" are considered equal. | |
| 109 | |
| 110 When Vim is invoked with --remote, --remote-wait or --remote-send it will try | |
| 111 to locate the server name determined by the invocation name and --servername | |
| 112 argument as described above. If an exact match is not available, the first | |
| 113 server with the number postfix will be used. If a name with the number | |
| 114 postfix is specified with the --servername argument, it must match exactly. | |
| 115 | |
| 116 If no server can be located and --remote or --remote-wait was used, Vim will | |
| 117 start up according to the rest of the command line and do the editing by | |
| 118 itself. This way it is not necessary to know whether gvim is already started | |
| 119 when sending command to it. | |
| 120 | |
| 121 The --serverlist argument will cause Vim to print a list of registered command | |
| 122 servers on the standard output (stdout) and exit. | |
| 27804 | 123 *{server}* |
| 124 The {server} argument is used by several functions. When this is an empty | |
| 125 string then on Unix the default server name is used, which is "GVIM". On | |
| 126 MS-Windows an empty string does not work. | |
| 7 | 127 |
| 128 Win32 Note: Making the Vim server go to the foreground doesn't always work, | |
| 129 because MS-Windows doesn't allow it. The client will move the server to the | |
| 130 foreground when using the --remote or --remote-wait argument and the server | |
| 131 name starts with "g". | |
| 132 | |
| 133 | |
| 134 REMOTE EDITING | |
| 135 | |
| 136 The --remote argument will cause a |:drop| command to be constructed from the | |
| 137 rest of the command line and sent as described above. | |
| 138 The --remote-wait argument does the same thing and additionally sets up to | |
| 139 wait for each of the files to have been edited. This uses the BufUnload | |
| 140 event, thus as soon as a file has been unloaded, Vim assumes you are done | |
| 141 editing it. | |
| 142 Note that the --remote and --remote-wait arguments will consume the rest of | |
| 237 | 143 the command line. I.e. all remaining arguments will be regarded as filenames. |
| 7 | 144 You can not put options there! |
| 145 | |
| 146 | |
| 147 FUNCTIONS | |
| 148 *E240* *E573* | |
| 149 There are a number of Vim functions for scripting the command server. See | |
|
26777
629e7046ef63
patch 8.2.3917: the eval.txt help file is way too big
Bram Moolenaar <Bram@vim.org>
parents:
21676
diff
changeset
|
150 the description in |builtin.txt| or use CTRL-] on the function name to jump to |
| 7 | 151 the full explanation. |
| 152 | |
| 153 synopsis explanation ~ | |
|
11229
146a1e213b60
Update runtime files. Add Rust support.
Christian Brabandt <cb@256bit.org>
parents:
10198
diff
changeset
|
154 remote_startserver( name) run a server |
| 7 | 155 remote_expr( server, string, idvar) send expression |
| 156 remote_send( server, string, idvar) send key sequence | |
| 157 serverlist() get a list of available servers | |
| 158 remote_peek( serverid, retvar) check for reply string | |
| 159 remote_read( serverid) read reply string | |
| 160 server2client( serverid, string) send reply string | |
| 161 remote_foreground( server) bring server to the front | |
| 162 | |
| 163 See also the explanation of |CTRL-\_CTRL-N|. Very useful as a leading key | |
| 164 sequence. | |
| 165 The {serverid} for server2client() can be obtained with expand("<client>") | |
| 166 | |
| 167 ============================================================================== | |
| 168 2. X11 specific items *x11-clientserver* | |
| 169 *E247* *E248* *E251* *E258* *E277* | |
| 170 | |
| 171 The communication between client and server goes through the X server. The | |
| 172 display of the Vim server must be specified. The usual protection of the X | |
| 173 server is used, you must be able to open a window on the X server for the | |
| 174 communication to work. It is possible to communicate between different | |
| 175 systems. | |
| 176 | |
| 177 By default, a GUI Vim will register a name on the X-server by which it can be | |
| 178 addressed for subsequent execution of injected strings. Vim can also act as | |
| 179 a client and send strings to other instances of Vim on the same X11 display. | |
| 180 | |
| 181 When an X11 GUI Vim (gvim) is started, it will try to register a send-server | |
| 182 name on the 'VimRegistry' property on the root window. | |
| 183 | |
| 184 A non GUI Vim with access to the X11 display (|xterm-clipboard| enabled), can | |
| 185 also act as a command server if a server name is explicitly given with the | |
| 21676 | 186 --servername argument, or when Vim was built with the |+autoservername| |
| 12909 | 187 feature. |
| 7 | 188 |
| 189 An empty --servername argument will cause the command server to be disabled. | |
| 190 | |
| 191 To send commands to a Vim server from another application, read the source | |
| 192 file src/if_xcmdsrv.c, it contains some hints about the protocol used. | |
| 193 | |
| 194 ============================================================================== | |
| 195 3. Win32 specific items *w32-clientserver* | |
| 196 | |
| 197 Every Win32 Vim can work as a server, also in the console. You do not need a | |
| 198 version compiled with OLE. Windows messages are used, this works on any | |
| 199 version of MS-Windows. But only communication within one system is possible. | |
| 200 | |
| 201 Since MS-Windows messages are used, any other application should be able to | |
| 202 communicate with a Vim server. An alternative is using the OLE functionality | |
| 203 |ole-interface|. | |
| 204 | |
| 205 When using gvim, the --remote-wait only works properly this way: > | |
| 206 | |
| 207 start /w gvim --remote-wait file.txt | |
| 208 < | |
| 14421 | 209 vim:tw=78:sw=4:ts=8:noet:ft=help:norl: |