Mercurial > vim

diff runtime/doc/terminal.txt @ 13547:87a9c1be0ae3 v8.0.1647

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
patch 8.0.1647: terminal API may call any user function commit https://github.com/vim/vim/commit/2a77d21f7893ba14e682a3c5891d606f117a3f36 Author: Bram Moolenaar <Bram@vim.org> Date: Mon Mar 26 21:38:52 2018 +0200 patch 8.0.1647: terminal API may call any user function Problem: Terminal API may call a function not meant to be called by this API. Solution: Require the function to start with Tapi_.
author Christian Brabandt <cb@256bit.org>
date Mon, 26 Mar 2018 21:45:07 +0200
parents e9ffb5b35266
children 5923f64c8f5b
line wrap: on
line diff
--- a/runtime/doc/terminal.txt
+++ b/runtime/doc/terminal.txt
@@ -423,20 +423,26 @@ Currently supported commands:
 
 	call {funcname} {argument}
 
-		Call a user defined function with [argument].  The function is
-		called with the buffer number of the terminal and the decoded
-		argument.  The user function must sanity check the argument.
+		Call a user defined function with {argument}.
+		The function is called with two arguments: the buffer number
+		of the terminal and {argument}, the decoded JSON argument. 
+		The function name must start with "Tapi_" to avoid
+		accidentally calling a function not meant to be used for the
+		terminal API
+		The user function should sanity check the argument.
 		The function can use |term_sendkeys()| to send back a reply.
 		Example in JSON: >
-			["call", "Impression", ["play", 14]]
+			["call", "Tapi_Impression", ["play", 14]]
 <		Calls a function defined like this: >
-			function Impression(bufnum, arglist)
+			function Tapi_Impression(bufnum, arglist)
 			  if len(a:arglist) == 2
-			    echo "impression " . a:arglist[0]
-			    echo "count " . a:arglist[1]
+			    echomsg "impression " . a:arglist[0]
+			    echomsg "count " . a:arglist[1]
 			  endif
 			endfunc
-<
+<		Output from `:echo` may be erased by a redraw, use `:echomsg`
+		to be able to see it with `:messages`.
+
 	drop {filename}
 
 		Let Vim open a file, like the `:drop` command.  If {filename}
@@ -447,7 +453,7 @@ Currently supported commands:
 
 A trick to have Vim send this escape sequence: >
 	exe "set t_ts=\<Esc>]51; t_fs=\x07"
-	let &titlestring = '["call","TryThis",["hello",123]]'
+	let &titlestring = '["call","Tapi_TryThis",["hello",123]]'
 	redraw
 	set t_ts& t_fs&