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