Merge remote-tracking branch 'vim/master'

Author: splhack

runtime/doc/channel.txt

@@ -1,4 +1,4 @@
-*channel.txt*      For Vim version 7.4.  Last change: 2016 Feb 20
+*channel.txt*      For Vim version 7.4.  Last change: 2016 Feb 21
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -93,21 +93,23 @@ To handle asynchronous communication a callback needs to be used: >
 	func MyHandler(channel, msg)
 	  echo "from the handler: " . a:msg
 	endfunc
-	call ch_sendexpr(channel, 'hello!', "MyHandler")
+	call ch_sendexpr(channel, 'hello!', {'callback': "MyHandler"})
 Vim will not wait for a response.  Now the server can send the response later
 and MyHandler will be invoked.
 
 Instead of giving a callback with every send call, it can also be specified
 when opening the channel: >
 	call ch_close(channel)
 	let channel = ch_open('localhost:8765', {'callback': "MyHandler"})
-	call ch_sendexpr(channel, 'hello!', 0)
+	call ch_sendexpr(channel, 'hello!', {'callback': 0})
 
 ==============================================================================
 3. Opening a channel					*channel-open*
 
 To open a channel: >
     let channel = ch_open({address} [, {options}])
+    if ch_status(channel) == "open"
+      " use the channel
 
 Use |ch_status()| to see if the channel could be opened.
 
@@ -131,25 +133,32 @@ Use |ch_status()| to see if the channel could be opened.
 							*channel-callback*
 "callback"	A function that is called when a message is received that is
 		not handled otherwise.  It gets two arguments: the channel
-		handle and the received message. Example: >
+		and the received message. Example: >
 	func Handle(channel, msg)
 	  echo 'Received: ' . a:msg
 	endfunc
 	let channel = ch_open("localhost:8765", {"callback": "Handle"})
 <
+		When "mode" is "json" or "js" the "msg" argument is the body
+		of the received message, converted to Vim types.
+		When "mode" is "nl" the "msg" argument is one message,
+		excluding the NL.
+		When "mode" is "raw" the "msg" argument is the whole message
+		as a string.
+							*out-cb*
 "out-cb"	A function like "callback" but used for stdout.  Only for when
 		the channel uses pipes.  When "out-cb" wasn't set the channel
 		callback is used.
-
+							*err-cb*
 "err-cb"	A function like "callback" but used for stderr.  Only for when
 		the channel uses pipes.  When "err-cb" wasn't set the channel
 		callback is used.
 
-		TODO:
+		TODO:					*close-cb*
 "close-cb"	A function that is called when the channel gets closed, other
 		than by calling ch_close().  It should be defined like this: >
 	func MyCloseHandler(channel)
-
+<							*waittime*
 "waittime"	The time to wait for the connection to be made in
 		milliseconds.  The default is zero, don't wait, which is
 		useful if the server is supposed to be running already.  A
@@ -158,41 +167,34 @@ Use |ch_status()| to see if the channel could be opened.
 "timeout"	The time to wait for a request when blocking, E.g. when using
 		ch_sendexpr().  In milliseconds.  The default is 2000 (2
 		seconds).
-
+						*out-timeout* *err-timeout*
 "out-timeout"	Timeout for stdout.  Only when using pipes.
 "err-timeout"	Timeout for stderr.  Only when using pipes.
 		Note: when setting "timeout" the part specific mode is
 		overwritten.  Therefore set "timeout" first and the part
 		specific mode later.
 
-When "mode" is "json" or "js" the "msg" argument is the body of the received
-message, converted to Vim types.
-When "mode" is "raw" the "msg" argument is the whole message as a string.
-
 When "mode" is "json" or "js" the "callback" is optional.  When omitted it is
 only possible to receive a message after sending one.
 
-To change the channel options after opening it use ch_setoptions().  The
-arguments are similar to what is passed to ch_open(), but "waittime" cannot be
-given, since that only applies to opening the channel.
+To change the channel options after opening it use |ch_setoptions()|.  The
+arguments are similar to what is passed to |ch_open()|, but "waittime" cannot
+be given, since that only applies to opening the channel.
 
-The handler can be added or changed: >
+For example, the handler can be added or changed: >
     call ch_setoptions(channel, {'callback': callback})
 When "callback" is empty (zero or an empty string) the handler is removed.
 
 The timeout can be changed: >
     call ch_setoptions(channel, {'timeout': msec})
 <
-							  *E906*
+							  *channel-close* *E906*
 Once done with the channel, disconnect it like this: >
     call ch_close(channel)
 When a socket is used this will close the socket for both directions.  When
 pipes are used (stdin/stdout/stderr) they are all closed.  This might not be
 what you want!  Stopping the job with job_stop() might be better.
 
-TODO:
-Currently up to 10 channels can be in use at the same time. *E897*
-
 When the channel can't be opened you will get an error message.  There is a
 difference between MS-Windows and Unix: On Unix when the port doesn't exist
 ch_open() fails quickly.  On MS-Windows "waittime" applies.
@@ -211,12 +213,13 @@ This awaits a response from the other side.
 When mode is JS this works the same, except that the messages use
 JavaScript encoding.  See |js_encode()| for the difference.
 
-To send a message, without handling a response: >
-    call ch_sendexpr(channel, {expr}, 0)
+To send a message, without handling a response or letting the channel callback
+handle the response: >
+    call ch_sendexpr(channel, {expr}, {'callback': 0})
 
 To send a message and letting the response handled by a specific function,
 asynchronously: >
-    call ch_sendexpr(channel, {expr}, {callback})
+    call ch_sendexpr(channel, {expr}, {'callback': Handler})
 
 Vim will match the response with the request using the message ID.  Once the
 response is received the callback will be invoked.  Further responses with the
@@ -424,13 +427,18 @@ The function will be called with the channel and a message. You would define
 it like this: >
     func MyHandler(channel, msg)
 
-Without the handler you need to read the output with ch_read().
+Without the handler you need to read the output with |ch_read()| or
+|ch_readraw()|.
 
-The handler defined for "out-cb" will also receive stderr.  If you want to
+The handler defined for "out-cb" will not receive stderr.  If you want to
 handle that separately, add an "err-cb" handler: >
     let job = job_start(command, {"out-cb": "MyHandler",
 	    \			  "err-cb": "ErrHandler"})
 
+If you want to handle both stderr and stdout with one handler use the
+"callback" option: >
+    let job = job_start(command, {"callback": "MyHandler"}) 
+
 You can send a message to the command with ch_sendraw().  If the channel is in
 JSON or JS mode you can use ch_sendexpr().
 
@@ -481,7 +489,10 @@ This gives the job some time to make the port available.
 10. Job options						*job-options*
 
 The {options} argument in job_start() is a dictionary.  All entries are
-optional.  The same options can be used with job_setoptions(job, {options}).
+optional.  Some options can be used after the job has started, using
+job_setoptions(job, {options}).  Many options can be used with the channel
+related to the job, using ch_setoptions(channel, {options}).
+See |job_setoptions()| and |ch_setoptions()|.
 
 						*job-callback*
 "callback": handler	Callback for something to read on any part of the
@@ -495,13 +506,18 @@ optional.  The same options can be used with job_setoptions(job, {options}).
 TODO:						*job-close-cb*
 "close-cb": handler	Callback for when the channel is closed.  Same as
 			"close-cb" on ch_open().
-TODO:						*job-exit-cb*
+						*job-exit-cb*
 "exit-cb": handler	Callback for when the job ends.  The arguments are the
 			job and the exit status.
-TODO:						*job-killonexit*
-"killonexit": 1		Stop the job when Vim exits.
-"killonexit": 0		Do not stop the job when Vim exits.
-			The default is 1.
+			Vim checks about every 10 seconds for jobs that ended.
+			The callback can also be triggered by calling
+			|job_status()|.
+						*job-stoponexit*
+"stoponexit": {signal}	Send {signal} to the job when Vim exits.  See
+			|job_stop()| for possible values.
+"stoponexit": ""	Do not stop the job when Vim exits.
+			The default is "term".
+
 TODO:						*job-term*
 "term": "open"		Start a terminal and connect the job
 			stdin/stdout/stderr to it.
@@ -529,9 +545,6 @@ TODO:						*job-err-io*
 "err-io": "buffer" 	stderr appends to a buffer
 "err-buffer": "name" 	buffer to append to
 
-TODO: more options
-
-
 ==============================================================================
 11. Controlling a job					*job-control*