From fcdb1f372b4da5c33091ae2e69960b6168454695 Mon Sep 17 00:00:00 2001 From: Charlie Groves Date: Tue, 1 Mar 2022 16:23:57 -0500 Subject: docs(remote): restore remote.txt from removal in f2205b83c553367a76b6cad --- runtime/doc/remote.txt | 189 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 runtime/doc/remote.txt (limited to 'runtime/doc') diff --git a/runtime/doc/remote.txt b/runtime/doc/remote.txt new file mode 100644 index 0000000000..6c2ceb45be --- /dev/null +++ b/runtime/doc/remote.txt @@ -0,0 +1,189 @@ +*remote.txt* Nvim + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Vim client-server communication *client-server* + + Type |gO| to see the table of contents. + +============================================================================== +1. Common functionality *clientserver* + +When compiled with the |+clientserver| option, Vim can act as a command +server. It accepts messages from a client and executes them. At the same +time, Vim can function as a client and send commands to a Vim server. + +The following command line arguments are available: + + argument meaning ~ + + --remote [+{cmd}] {file} ... *--remote* + Open the file list in a remote Vim. When + there is no Vim server, execute locally. + There is one optional init command: +{cmd}. + This must be an Ex command that can be + followed by "|". + The rest of the command line is taken as the + file list. Thus any non-file arguments must + come before this. + You cannot edit stdin this way |--|. + The remote Vim is raised. If you don't want + this use > + vim --remote-send ":n filename" +< + --remote-silent [+{cmd}] {file} ... *--remote-silent* + As above, but don't complain if there is no + server and the file is edited locally. + --remote-wait [+{cmd}] {file} ... *--remote-wait* + As --remote, but wait for files to complete + (unload) in remote Vim. + --remote-wait-silent [+{cmd}] {file} ... *--remote-wait-silent* + As --remote-wait, but don't complain if there + is no server. + *--remote-tab* + --remote-tab Like --remote but open each file in a new + tabpage. + *--remote-tab-silent* + --remote-tab-silent Like --remote-silent but open each file in a + new tabpage. + *--remote-tab-wait* + --remote-tab-wait Like --remote-wait but open each file in a new + tabpage. + + *--remote-tab-wait-silent* + --remote-tab-wait-silent Like --remote-wait-silent but open each file + in a new tabpage. + *--remote-send* + --remote-send {keys} Send {keys} to server and exit. The {keys} + are not mapped. Special key names are + recognized, e.g., "" results in a CR + character. + *--remote-expr* + --remote-expr {expr} Evaluate {expr} in server and print the result + on stdout. + +Examples ~ + +Edit "file.txt" in an already running GVIM server: > + gvim --remote file.txt + +Edit "file.txt" in an already running server called FOOBAR: > + gvim --servername FOOBAR --remote file.txt + +Edit "file.txt" in server "FILES" if it exists, become server "FILES" +otherwise: > + gvim --servername FILES --remote-silent file.txt + +This doesn't work, all arguments after --remote will be used as file names: > + gvim --remote --servername FOOBAR file.txt + +Edit file "+foo" in a remote server (note the use of "./" to avoid the special +meaning of the leading plus): > + vim --remote ./+foo + +Tell the remote server "BLA" to write all files and exit: > + vim --servername BLA --remote-send ':wqa' + + +SERVER NAME *client-server-name* + +By default Vim will try to register the name under which it was invoked (gvim, +egvim ...). This can be overridden with the --servername argument. If the +specified name is not available, a postfix is applied until a free name is +encountered, i.e. "gvim1" for the second invocation of gvim on a particular +X-server. The resulting name is available in the servername builtin variable +|v:servername|. The case of the server name is ignored, thus "gvim" and +"GVIM" are considered equal. + +When Vim is invoked with --remote, --remote-wait or --remote-send it will try +to locate the server name determined by the invocation name and --servername +argument as described above. If an exact match is not available, the first +server with the number postfix will be used. If a name with the number +postfix is specified with the --servername argument, it must match exactly. + +If no server can be located and --remote or --remote-wait was used, Vim will +start up according to the rest of the command line and do the editing by +itself. This way it is not necessary to know whether gvim is already started +when sending command to it. + +The --serverlist argument will cause Vim to print a list of registered command +servers on the standard output (stdout) and exit. + +Win32 Note: Making the Vim server go to the foreground doesn't always work, +because MS-Windows doesn't allow it. The client will move the server to the +foreground when using the --remote or --remote-wait argument and the server +name starts with "g". + + +REMOTE EDITING + +The --remote argument will cause a |:drop| command to be constructed from the +rest of the command line and sent as described above. +The --remote-wait argument does the same thing and additionally sets up to +wait for each of the files to have been edited. This uses the BufUnload +event, thus as soon as a file has been unloaded, Vim assumes you are done +editing it. +Note that the --remote and --remote-wait arguments will consume the rest of +the command line. I.e. all remaining arguments will be regarded as filenames. +You can not put options there! + + +FUNCTIONS + *E240* *E573* +There are a number of Vim functions for scripting the command server. See +the description in |eval.txt| or use CTRL-] on the function name to jump to +the full explanation. + + synopsis explanation ~ + remote_startserver( name) run a server + remote_expr( server, string, idvar) send expression + remote_send( server, string, idvar) send key sequence + serverlist() get a list of available servers + remote_peek( serverid, retvar) check for reply string + remote_read( serverid) read reply string + server2client( serverid, string) send reply string + remote_foreground( server) bring server to the front + +See also the explanation of |CTRL-\_CTRL-N|. Very useful as a leading key +sequence. +The {serverid} for server2client() can be obtained with expand("") + +============================================================================== +2. X11 specific items *x11-clientserver* + *E247* *E248* *E251* *E258* *E277* + +The communication between client and server goes through the X server. The +display of the Vim server must be specified. The usual protection of the X +server is used, you must be able to open a window on the X server for the +communication to work. It is possible to communicate between different +systems. + +By default, a GUI Vim will register a name on the X-server by which it can be +addressed for subsequent execution of injected strings. Vim can also act as +a client and send strings to other instances of Vim on the same X11 display. + +When an X11 GUI Vim (gvim) is started, it will try to register a send-server +name on the 'VimRegistry' property on the root window. + +An empty --servername argument will cause the command server to be disabled. + +To send commands to a Vim server from another application, read the source +file src/if_xcmdsrv.c, it contains some hints about the protocol used. + +============================================================================== +3. Win32 specific items *w32-clientserver* + +Every Win32 Vim can work as a server, also in the console. You do not need a +version compiled with OLE. Windows messages are used, this works on any +version of MS-Windows. But only communication within one system is possible. + +Since MS-Windows messages are used, any other application should be able to +communicate with a Vim server. + +When using gvim, the --remote-wait only works properly this way: > + + start /w gvim --remote-wait file.txt +< + vim:tw=78:sw=4:ts=8:noet:ft=help:norl: -- cgit From e095a868cbc9ff504087b3df89e4d92d0421ab38 Mon Sep 17 00:00:00 2001 From: Charlie Groves Date: Wed, 2 Mar 2022 10:16:29 -0500 Subject: docs(remote): update remote.txt for current nvim implementation --- runtime/doc/remote.txt | 168 ++++++++++++++++--------------------------------- 1 file changed, 55 insertions(+), 113 deletions(-) (limited to 'runtime/doc') diff --git a/runtime/doc/remote.txt b/runtime/doc/remote.txt index 6c2ceb45be..dd5d44387d 100644 --- a/runtime/doc/remote.txt +++ b/runtime/doc/remote.txt @@ -11,9 +11,10 @@ Vim client-server communication *client-server* ============================================================================== 1. Common functionality *clientserver* -When compiled with the |+clientserver| option, Vim can act as a command -server. It accepts messages from a client and executes them. At the same -time, Vim can function as a client and send commands to a Vim server. +Nvim's |RPC| functionality allows clients to programmatically control Nvim. Nvim +itself takes command-line arguments that cause it to become a client to another +Nvim running as a server. These arguments match those provided by Vim's +clientserver option. The following command line arguments are available: @@ -22,39 +23,27 @@ The following command line arguments are available: --remote [+{cmd}] {file} ... *--remote* Open the file list in a remote Vim. When there is no Vim server, execute locally. - There is one optional init command: +{cmd}. + Vim allows one init command: +{cmd}. This must be an Ex command that can be - followed by "|". + followed by "|". It's not yet supported by + Nvim. The rest of the command line is taken as the file list. Thus any non-file arguments must come before this. You cannot edit stdin this way |--|. The remote Vim is raised. If you don't want this use > - vim --remote-send ":n filename" + nvim --remote-send ":n filename" < --remote-silent [+{cmd}] {file} ... *--remote-silent* As above, but don't complain if there is no server and the file is edited locally. - --remote-wait [+{cmd}] {file} ... *--remote-wait* - As --remote, but wait for files to complete - (unload) in remote Vim. - --remote-wait-silent [+{cmd}] {file} ... *--remote-wait-silent* - As --remote-wait, but don't complain if there - is no server. *--remote-tab* --remote-tab Like --remote but open each file in a new tabpage. *--remote-tab-silent* --remote-tab-silent Like --remote-silent but open each file in a new tabpage. - *--remote-tab-wait* - --remote-tab-wait Like --remote-wait but open each file in a new - tabpage. - - *--remote-tab-wait-silent* - --remote-tab-wait-silent Like --remote-wait-silent but open each file - in a new tabpage. *--remote-send* --remote-send {keys} Send {keys} to server and exit. The {keys} are not mapped. Special key names are @@ -63,127 +52,80 @@ The following command line arguments are available: *--remote-expr* --remote-expr {expr} Evaluate {expr} in server and print the result on stdout. + *--server* + --server {addr} Connect to the named pipe or socket at the + given address for executing remote commands. + See |--listen| for specifying an address when + starting a server. Examples ~ -Edit "file.txt" in an already running GVIM server: > - gvim --remote file.txt - -Edit "file.txt" in an already running server called FOOBAR: > - gvim --servername FOOBAR --remote file.txt +Start an Nvim server listening on a named pipe at '~/.cache/nvim/server.pipe': > + nvim --listen ~/.cache/nvim/server.pipe -Edit "file.txt" in server "FILES" if it exists, become server "FILES" -otherwise: > - gvim --servername FILES --remote-silent file.txt +Edit "file.txt" in an Nvim server listening at '~/.cache/nvim/server.pipe': > + nvim --server ~/.cache/nvim/server.pipe --remote file.txt This doesn't work, all arguments after --remote will be used as file names: > - gvim --remote --servername FOOBAR file.txt - -Edit file "+foo" in a remote server (note the use of "./" to avoid the special -meaning of the leading plus): > - vim --remote ./+foo - -Tell the remote server "BLA" to write all files and exit: > - vim --servername BLA --remote-send ':wqa' - - -SERVER NAME *client-server-name* - -By default Vim will try to register the name under which it was invoked (gvim, -egvim ...). This can be overridden with the --servername argument. If the -specified name is not available, a postfix is applied until a free name is -encountered, i.e. "gvim1" for the second invocation of gvim on a particular -X-server. The resulting name is available in the servername builtin variable -|v:servername|. The case of the server name is ignored, thus "gvim" and -"GVIM" are considered equal. - -When Vim is invoked with --remote, --remote-wait or --remote-send it will try -to locate the server name determined by the invocation name and --servername -argument as described above. If an exact match is not available, the first -server with the number postfix will be used. If a name with the number -postfix is specified with the --servername argument, it must match exactly. + nvim --remote --server ~/.cache/nvim/server.pipe file.txt -If no server can be located and --remote or --remote-wait was used, Vim will -start up according to the rest of the command line and do the editing by -itself. This way it is not necessary to know whether gvim is already started -when sending command to it. - -The --serverlist argument will cause Vim to print a list of registered command -servers on the standard output (stdout) and exit. - -Win32 Note: Making the Vim server go to the foreground doesn't always work, -because MS-Windows doesn't allow it. The client will move the server to the -foreground when using the --remote or --remote-wait argument and the server -name starts with "g". +Tell the remote server to write all files and exit: > + nvim --server ~/.cache/nvim/server.pipe --remote-send ':wqa' REMOTE EDITING The --remote argument will cause a |:drop| command to be constructed from the rest of the command line and sent as described above. -The --remote-wait argument does the same thing and additionally sets up to -wait for each of the files to have been edited. This uses the BufUnload -event, thus as soon as a file has been unloaded, Vim assumes you are done -editing it. Note that the --remote and --remote-wait arguments will consume the rest of the command line. I.e. all remaining arguments will be regarded as filenames. You can not put options there! -FUNCTIONS - *E240* *E573* -There are a number of Vim functions for scripting the command server. See -the description in |eval.txt| or use CTRL-] on the function name to jump to -the full explanation. - - synopsis explanation ~ - remote_startserver( name) run a server - remote_expr( server, string, idvar) send expression - remote_send( server, string, idvar) send key sequence - serverlist() get a list of available servers - remote_peek( serverid, retvar) check for reply string - remote_read( serverid) read reply string - server2client( serverid, string) send reply string - remote_foreground( server) bring server to the front - -See also the explanation of |CTRL-\_CTRL-N|. Very useful as a leading key -sequence. -The {serverid} for server2client() can be obtained with expand("") - ============================================================================== -2. X11 specific items *x11-clientserver* - *E247* *E248* *E251* *E258* *E277* +2. Missing functionality *clientserver-missing* -The communication between client and server goes through the X server. The -display of the Vim server must be specified. The usual protection of the X -server is used, you must be able to open a window on the X server for the -communication to work. It is possible to communicate between different -systems. +Vim supports additional functionality in clientserver that's not yet +implemented in Nvim. In particular, none of the 'wait' variants are supported +yet. The following command line arguments are not yet available: -By default, a GUI Vim will register a name on the X-server by which it can be -addressed for subsequent execution of injected strings. Vim can also act as -a client and send strings to other instances of Vim on the same X11 display. + argument meaning ~ -When an X11 GUI Vim (gvim) is started, it will try to register a send-server -name on the 'VimRegistry' property on the root window. + --remote-wait [+{cmd}] {file} ... *--remote-wait* + Not yet supported by Nvim. + As --remote, but wait for files to complete + (unload) in remote Vim. + --remote-wait-silent [+{cmd}] {file} ... *--remote-wait-silent* + Not yet supported by Nvim. + As --remote-wait, but don't complain if there + is no server. + *--remote-tab-wait* + --remote-tab-wait Not yet supported by Nvim. + Like --remote-wait but open each file in a new + tabpage. + *--remote-tab-wait-silent* + --remote-tab-wait-silent Not yet supported by Nvim. + Like --remote-wait-silent but open each file + in a new tabpage. + *--servername* + --servername {name} Not yet supported by Nvim. + Become the server {name}. When used together + with one of the --remote commands: connect to + server {name} instead of the default (see + below). The name used will be uppercase. -An empty --servername argument will cause the command server to be disabled. + *--serverlist* + --serverlist Not yet supported by Nvim. + Output a list of server names. -To send commands to a Vim server from another application, read the source -file src/if_xcmdsrv.c, it contains some hints about the protocol used. -============================================================================== -3. Win32 specific items *w32-clientserver* -Every Win32 Vim can work as a server, also in the console. You do not need a -version compiled with OLE. Windows messages are used, this works on any -version of MS-Windows. But only communication within one system is possible. -Since MS-Windows messages are used, any other application should be able to -communicate with a Vim server. +SERVER NAME *client-server-name* -When using gvim, the --remote-wait only works properly this way: > +By default Vim will try to register the name under which it was invoked (gvim, +egvim ...). This can be overridden with the --servername argument. Nvim +either listens on a named pipe or a socket and does not yet support this +--servername functionality. - start /w gvim --remote-wait file.txt -< vim:tw=78:sw=4:ts=8:noet:ft=help:norl: -- cgit From 29c36322857b37263b07eb1301d71ccd8a2ae044 Mon Sep 17 00:00:00 2001 From: Charlie Groves Date: Thu, 3 Mar 2022 16:33:27 -0500 Subject: fix(remote): report on missing wait commands, typecheck lua results Clean up lint errors, too --- runtime/doc/remote.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/doc') diff --git a/runtime/doc/remote.txt b/runtime/doc/remote.txt index dd5d44387d..b8991be738 100644 --- a/runtime/doc/remote.txt +++ b/runtime/doc/remote.txt @@ -83,7 +83,7 @@ You can not put options there! ============================================================================== -2. Missing functionality *clientserver-missing* +2. Missing functionality *E5600* *clientserver-missing* Vim supports additional functionality in clientserver that's not yet implemented in Nvim. In particular, none of the 'wait' variants are supported -- cgit