vim: runtime/doc/eval.txt comparison

comparison runtime/doc/eval.txt @ 17456:e414281d8bb4 v8.1.1726

patch 8.1.1726: the eval.txt help file is too big commit https://github.com/vim/vim/commit/ed997adaa1e9bd057ce732a73d933b739e9d0c30 Author: Bram Moolenaar <Bram@vim.org> Date: Sun Jul 21 16:42:00 2019 +0200 patch 8.1.1726: the eval.txt help file is too big Problem: The eval.txt help file is too big. Solution: Split off testing support to testing.txt. Move function details to where the functionality is explained.

author	Bram Moolenaar <Bram@vim.org>
date	Sun, 21 Jul 2019 16:45:05 +0200
parents	509542f1fffb
children	1e45331bd2ab

comparison

equal deleted inserted replaced

-:4ae435e21326
+:e414281d8bb4
-*eval.txt*	For Vim version 8.1.  Last change: 2019 Jul 19
+*eval.txt*	For Vim version 8.1.  Last change: 2019 Jul 21
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
 9.  Examples			|eval-examples|
 10. Vim script version		|vimscript-version|
 11. No +eval feature		|no-eval-feature|
 12. The sandbox			|eval-sandbox|
 13. Textlock			|textlock|
-14. Testing			|testing|
+Testing support is documented in |testing.txt|.
+Profiling is documented at |profiling|.
 ==============================================================================
 1. Variables						*variables*
 1.1 Variable types ~
 <		Without the {nr} argument, or when {nr} is -1, a |List| with
 		the whole |arglist| is returned.
 		The {winid} argument specifies the window ID, see |argc()|.
-assert_beeps({cmd})					*assert_beeps()*
-		Run {cmd} and add an error message to |v:errors| if it does
+assert_ functions are documented here: |assert-functions|
-		NOT produce a beep or visual bell.
-		Also see |assert_fails()| and |assert-return|.
-							*assert_equal()*
-assert_equal({expected}, {actual} [, {msg}])
-		When {expected} and {actual} are not equal an error message is
-		added to |v:errors| and 1 is returned.  Otherwise zero is
-		returned |assert-return|.
-		There is no automatic conversion, the String "4" is different
-		from the Number 4.  And the number 4 is different from the
-		Float 4.0.  The value of 'ignorecase' is not used here, case
-		always matters.
-		When {msg} is omitted an error in the form "Expected
-		{expected} but got {actual}" is produced.
-		Example: >
-	assert_equal('foo', 'bar')
-<		Will result in a string to be added to |v:errors|:
-	test.vim line 12: Expected 'foo' but got 'bar' ~
-							*assert_equalfile()*
-assert_equalfile({fname-one}, {fname-two})
-		When the files {fname-one} and {fname-two} do not contain
-		exactly the same text an error message is added to |v:errors|.
-		Also see |assert-return|.
-		When {fname-one} or {fname-two} does not exist the error will
-		mention that.
-		Mainly useful with |terminal-diff|.
-assert_exception({error} [, {msg}])			*assert_exception()*
-		When v:exception does not contain the string {error} an error
-		message is added to |v:errors|.  Also see |assert-return|.
-		This can be used to assert that a command throws an exception.
-		Using the error number, followed by a colon, avoids problems
-		with translations: >
-			try
-			  commandthatfails
-			  call assert_false(1, 'command should have failed')
-			catch
-			  call assert_exception('E492:')
-			endtry
-assert_fails({cmd} [, {error} [, {msg}]])			*assert_fails()*
-		Run {cmd} and add an error message to |v:errors| if it does
-		NOT produce an error.  Also see |assert-return|.
-		When {error} is given it must match in |v:errmsg|.
-		Note that beeping is not considered an error, and some failing
-		commands only beep.  Use |assert_beeps()| for those.
-assert_false({actual} [, {msg}])				*assert_false()*
-		When {actual} is not false an error message is added to
-		|v:errors|, like with |assert_equal()|.
-		Also see |assert-return|.
-		A value is false when it is zero. When {actual} is not a
-		number the assert fails.
-		When {msg} is omitted an error in the form
-		"Expected False but got {actual}" is produced.
-assert_inrange({lower}, {upper}, {actual} [, {msg}])	 *assert_inrange()*
-		This asserts number and |Float| values.  When {actual}  is lower
-		than {lower} or higher than {upper} an error message is added
-		to |v:errors|.  Also see |assert-return|.
-		When {msg} is omitted an error in the form
-		"Expected range {lower} - {upper}, but got {actual}" is
-		produced.
-								*assert_match()*
-assert_match({pattern}, {actual} [, {msg}])
-		When {pattern} does not match {actual} an error message is
-		added to |v:errors|.  Also see |assert-return|.
-		{pattern} is used as with |=~|: The matching is always done
-		like 'magic' was set and 'cpoptions' is empty, no matter what
-		the actual value of 'magic' or 'cpoptions' is.
-		{actual} is used as a string, automatic conversion applies.
-		Use "^" and "$" to match with the start and end of the text.
-		Use both to match the whole text.
-		When {msg} is omitted an error in the form
-		"Pattern {pattern} does not match {actual}" is produced.
-		Example: >
-	assert_match('^f.*o$', 'foobar')
-<		Will result in a string to be added to |v:errors|:
-	test.vim line 12: Pattern '^f.*o$' does not match 'foobar' ~
-							*assert_notequal()*
-assert_notequal({expected}, {actual} [, {msg}])
-		The opposite of `assert_equal()`: add an error message to
-		|v:errors| when {expected} and {actual} are equal.
-		Also see |assert-return|.
-							*assert_notmatch()*
-assert_notmatch({pattern}, {actual} [, {msg}])
-		The opposite of `assert_match()`: add an error message to
-		|v:errors| when {pattern} matches {actual}.
-		Also see |assert-return|.
-assert_report({msg})					*assert_report()*
-		Report a test failure directly, using {msg}.
-		Always returns one.
-assert_true({actual} [, {msg}])				*assert_true()*
-		When {actual} is not true an error message is added to
-		|v:errors|, like with |assert_equal()|.
-		Also see |assert-return|.
-		A value is TRUE when it is a non-zero number.  When {actual}
-		is not a number the assert fails.
-		When {msg} is omitted an error in the form "Expected True but
-		got {actual}" is produced.
 asin({expr})						*asin()*
 		Return the arc sine of {expr} measured in radians, as a |Float|
 		in the range of [-pi/2, pi/2].
 		{expr} must evaluate to a |Float| or a |Number| in the range
 <			-5.0  >
 			echo ceil(4.0)
 <			4.0
 		{only available when compiled with the |+float| feature}
-ch_canread({handle})						*ch_canread()*
-		Return non-zero when there is something to read from {handle}.
+ch_ functions are documented here: |channel-functions-details|
-		{handle} can be a Channel or a Job that has a Channel.
-		This is useful to read from a channel at a convenient time,
-		e.g. from a timer.
-		Note that messages are dropped when the channel does not have
-		a callback.  Add a close callback to avoid that.
-		{only available when compiled with the |+channel| feature}
-ch_close({handle})						*ch_close()*
-		Close {handle}.  See |channel-close|.
-		{handle} can be a Channel or a Job that has a Channel.
-		A close callback is not invoked.
-		{only available when compiled with the |+channel| feature}
-ch_close_in({handle})						*ch_close_in()*
-		Close the "in" part of {handle}.  See |channel-close-in|.
-		{handle} can be a Channel or a Job that has a Channel.
-		A close callback is not invoked.
-		{only available when compiled with the |+channel| feature}
-ch_evalexpr({handle}, {expr} [, {options}])			*ch_evalexpr()*
-		Send {expr} over {handle}.  The {expr} is encoded
-		according to the type of channel.  The function cannot be used
-		with a raw channel.  See |channel-use|.
-		{handle} can be a Channel or a Job that has a Channel.
-								*E917*
-		{options} must be a Dictionary.  It must not have a "callback"
-		entry.  It can have a "timeout" entry to specify the timeout
-		for this specific request.
-		ch_evalexpr() waits for a response and returns the decoded
-		expression.  When there is an error or timeout it returns an
-		empty string.
-		{only available when compiled with the |+channel| feature}
-ch_evalraw({handle}, {string} [, {options}])		*ch_evalraw()*
-		Send {string} over {handle}.
-		{handle} can be a Channel or a Job that has a Channel.
-		Works like |ch_evalexpr()|, but does not encode the request or
-		decode the response.  The caller is responsible for the
-		correct contents.  Also does not add a newline for a channel
-		in NL mode, the caller must do that.  The NL in the response
-		is removed.
-		Note that Vim does not know when the text received on a raw
-		channel is complete, it may only return the first part and you
-		need to use |ch_readraw()| to fetch the rest.
-		See |channel-use|.
-		{only available when compiled with the |+channel| feature}
-ch_getbufnr({handle}, {what})				 *ch_getbufnr()*
-		Get the buffer number that {handle} is using for {what}.
-		{handle} can be a Channel or a Job that has a Channel.
-		{what} can be "err" for stderr, "out" for stdout or empty for
-		socket output.
-		Returns -1 when there is no buffer.
-		{only available when compiled with the |+channel| feature}
-ch_getjob({channel})						*ch_getjob()*
-		Get the Job associated with {channel}.
-		If there is no job calling |job_status()| on the returned Job
-		will result in "fail".
-		{only available when compiled with the |+channel| and
-		|+job| features}
-ch_info({handle})						*ch_info()*
-		Returns a Dictionary with information about {handle}.  The
-		items are:
-		   "id"		  number of the channel
-		   "status"	  "open", "buffered" or "closed", like
-				  ch_status()
-		When opened with ch_open():
-		   "hostname"	  the hostname of the address
-		   "port"	  the port of the address
-		   "sock_status"  "open" or "closed"
-		   "sock_mode"	  "NL", "RAW", "JSON" or "JS"
-		   "sock_io"	  "socket"
-		   "sock_timeout" timeout in msec
-		When opened with job_start():
-		   "out_status"	  "open", "buffered" or "closed"
-		   "out_mode"	  "NL", "RAW", "JSON" or "JS"
-		   "out_io"	  "null", "pipe", "file" or "buffer"
-		   "out_timeout"  timeout in msec
-		   "err_status"	  "open", "buffered" or "closed"
-		   "err_mode"	  "NL", "RAW", "JSON" or "JS"
-		   "err_io"	  "out", "null", "pipe", "file" or "buffer"
-		   "err_timeout"  timeout in msec
-		   "in_status"	  "open" or "closed"
-		   "in_mode"	  "NL", "RAW", "JSON" or "JS"
-		   "in_io"	  "null", "pipe", "file" or "buffer"
-		   "in_timeout"	  timeout in msec
-ch_log({msg} [, {handle}])					*ch_log()*
-		Write {msg} in the channel log file, if it was opened with
-		|ch_logfile()|.
-		When {handle} is passed the channel number is used for the
-		message.
-		{handle} can be a Channel or a Job that has a Channel.  The
-		Channel must be open for the channel number to be used.
-ch_logfile({fname} [, {mode}])					*ch_logfile()*
-		Start logging channel activity to {fname}.
-		When {fname} is an empty string: stop logging.
-		When {mode} is omitted or "a" append to the file.
-		When {mode} is "w" start with an empty file.
-		Use |ch_log()| to write log messages.  The file is flushed
-		after every message, on Unix you can use "tail -f" to see what
-		is going on in real time.
-		This function is not available in the |sandbox|.
-		NOTE: the channel communication is stored in the file, be
-		aware that this may contain confidential and privacy sensitive
-		information, e.g. a password you type in a terminal window.
-ch_open({address} [, {options}])				*ch_open()*
-		Open a channel to {address}.  See |channel|.
-		Returns a Channel.  Use |ch_status()| to check for failure.
-		{address} has the form "hostname:port", e.g.,
-		"localhost:8765".
-		If {options} is given it must be a |Dictionary|.
-		See |channel-open-options|.
-		{only available when compiled with the |+channel| feature}
-ch_read({handle} [, {options}])					*ch_read()*
-		Read from {handle} and return the received message.
-		{handle} can be a Channel or a Job that has a Channel.
-		For a NL channel this waits for a NL to arrive, except when
-		there is nothing more to read (channel was closed).
-		See |channel-more|.
-		{only available when compiled with the |+channel| feature}
-ch_readblob({handle} [, {options}])			*ch_readblob()*
-		Like ch_read() but reads binary data and returns a |Blob|.
-		See |channel-more|.
-		{only available when compiled with the |+channel| feature}
-ch_readraw({handle} [, {options}])			*ch_readraw()*
-		Like ch_read() but for a JS and JSON channel does not decode
-		the message.  For a NL channel it does not block waiting for
-		the NL to arrive, but otherwise works like ch_read().
-		See |channel-more|.
-		{only available when compiled with the |+channel| feature}
-ch_sendexpr({handle}, {expr} [, {options}])			*ch_sendexpr()*
-		Send {expr} over {handle}.  The {expr} is encoded
-		according to the type of channel.  The function cannot be used
-		with a raw channel.
-		See |channel-use|.				*E912*
-		{handle} can be a Channel or a Job that has a Channel.
-		{only available when compiled with the |+channel| feature}
-ch_sendraw({handle}, {expr} [, {options}])		*ch_sendraw()*
-		Send |String| or |Blob| {expr} over {handle}.
-		Works like |ch_sendexpr()|, but does not encode the request or
-		decode the response.  The caller is responsible for the
-		correct contents.  Also does not add a newline for a channel
-		in NL mode, the caller must do that.  The NL in the response
-		is removed.
-		See |channel-use|.
-		{only available when compiled with the |+channel| feature}
-ch_setoptions({handle}, {options})			*ch_setoptions()*
-		Set options on {handle}:
-			"callback"	the channel callback
-			"timeout"	default read timeout in msec
-			"mode"		mode for the whole channel
-		See |ch_open()| for more explanation.
-		{handle} can be a Channel or a Job that has a Channel.
-		Note that changing the mode may cause queued messages to be
-		lost.
-		These options cannot be changed:
-			"waittime"	only applies to |ch_open()|
-ch_status({handle} [, {options}])				*ch_status()*
-		Return the status of {handle}:
-			"fail"		failed to open the channel
-			"open"		channel can be used
-			"buffered"	channel can be read, not written to
-			"closed"	channel can not be used
-		{handle} can be a Channel or a Job that has a Channel.
-		"buffered" is used when the channel was closed but there is
-		still data that can be obtained with |ch_read()|.
-		If {options} is given it can contain a "part" entry to specify
-		the part of the channel to return the status for: "out" or
-		"err".  For example, to get the error status: >
-			ch_status(job, {"part": "err"})
-<
 changenr()						*changenr()*
 		Return the number of the most recent change.  This is the same
 		number as what is displayed with |:undolist| and can be used
 		with the |:undo| command.
 		When a change was made it is the number of that change.  After
 		Example: >
 			for [key, value] in items(mydict)
 			   echo key . ': ' . value
 			endfor
-job_getchannel({job})					 *job_getchannel()*
-		Get the channel handle that {job} is using.
+job_ functions are documented here: |job-functions-details|
-		To check if the job has no channel: >
-			if string(job_getchannel()) == 'channel fail'
-<
-		{only available when compiled with the |+job| feature}
-job_info([{job}])					*job_info()*
-		Returns a Dictionary with information about {job}:
-		   "status"	what |job_status()| returns
-		   "channel"	what |job_getchannel()| returns
-		   "cmd"	List of command arguments used to start the job
-		   "process"	process ID
-		   "tty_in"	terminal input name, empty when none
-		   "tty_out"	terminal output name, empty when none
-		   "exitval"	only valid when "status" is "dead"
-		   "exit_cb"	function to be called on exit
-		   "stoponexit"	|job-stoponexit|
-		   Only in Unix:
-		   "termsig"	the signal which terminated the process
-				(See |job_stop()| for the values)
-				only valid when "status" is "dead"
-		   Only in MS-Windows:
-		   "tty_type"	Type of virtual console in use.
-				Values are "winpty" or "conpty".
-				See 'termwintype'.
-		Without any arguments, returns a List with all Job objects.
-job_setoptions({job}, {options})			*job_setoptions()*
-		Change options for {job}.  Supported are:
-		   "stoponexit"	|job-stoponexit|
-		   "exit_cb"	|job-exit_cb|
-job_start({command} [, {options}])			*job_start()*
-		Start a job and return a Job object.  Unlike |system()| and
-		|:!cmd| this does not wait for the job to finish.
-		To start a job in a terminal window see |term_start()|.
-		If the job fails to start then |job_status()| on the returned
-		Job object results in "fail" and none of the callbacks will be
-		invoked.
-		{command} can be a String.  This works best on MS-Windows.  On
-		Unix it is split up in white-separated parts to be passed to
-		execvp().  Arguments in double quotes can contain white space.
-		{command} can be a List, where the first item is the executable
-		and further items are the arguments.  All items are converted
-		to String.  This works best on Unix.
-		On MS-Windows, job_start() makes a GUI application hidden. If
-		want to show it, Use |:!start| instead.
-		The command is executed directly, not through a shell, the
-		'shell' option is not used.  To use the shell: >
-	let job = job_start(["/bin/sh", "-c", "echo hello"])
-<		Or: >
-	let job = job_start('/bin/sh -c "echo hello"')
-<		Note that this will start two processes, the shell and the
-		command it executes.  If you don't want this use the "exec"
-		shell command.
-		On Unix $PATH is used to search for the executable only when
-		the command does not contain a slash.
-		The job will use the same terminal as Vim.  If it reads from
-		stdin the job and Vim will be fighting over input, that
-		doesn't work.  Redirect stdin and stdout to avoid problems: >
-	let job = job_start(['sh', '-c', "myserver </dev/null >/dev/null"])
-<
-		The returned Job object can be used to get the status with
-		|job_status()| and stop the job with |job_stop()|.
-		Note that the job object will be deleted if there are no
-		references to it.  This closes the stdin and stderr, which may
-		cause the job to fail with an error.  To avoid this keep a
-		reference to the job.  Thus instead of: >
-	call job_start('my-command')
-<		use: >
-	let myjob = job_start('my-command')
-<		and unlet "myjob" once the job is not needed or is past the
-		point where it would fail (e.g. when it prints a message on
-		startup).  Keep in mind that variables local to a function
-		will cease to exist if the function returns.  Use a
-		script-local variable if needed: >
-	let s:myjob = job_start('my-command')
-<
-		{options} must be a Dictionary.  It can contain many optional
-		items, see |job-options|.
-		{only available when compiled with the |+job| feature}
-job_status({job})					*job_status()* *E916*
-		Returns a String with the status of {job}:
-			"run"	job is running
-			"fail"	job failed to start
-			"dead"	job died or was stopped after running
-		On Unix a non-existing command results in "dead" instead of
-		"fail", because a fork happens before the failure can be
-		detected.
-		If an exit callback was set with the "exit_cb" option and the
-		job is now detected to be "dead" the callback will be invoked.
-		For more information see |job_info()|.
-		{only available when compiled with the |+job| feature}
-job_stop({job} [, {how}])					*job_stop()*
-		Stop the {job}.  This can also be used to signal the job.
-		When {how} is omitted or is "term" the job will be terminated.
-		For Unix SIGTERM is sent.  On MS-Windows the job will be
-		terminated forcedly (there is no "gentle" way).
-		This goes to the process group, thus children may also be
-		affected.
-		Effect for Unix:
-			"term"	 SIGTERM (default)
-			"hup"	 SIGHUP
-			"quit"	 SIGQUIT
-			"int"	 SIGINT
-			"kill"	 SIGKILL (strongest way to stop)
-			number	 signal with that number
-		Effect for MS-Windows:
-			"term"	 terminate process forcedly (default)
-			"hup"	 CTRL_BREAK
-			"quit"	 CTRL_BREAK
-			"int"	 CTRL_C
-			"kill"	 terminate process forcedly
-			Others	 CTRL_BREAK
-		On Unix the signal is sent to the process group.  This means
-		that when the job is "sh -c command" it affects both the shell
-		and the command.
-		The result is a Number: 1 if the operation could be executed,
-		0 if "how" is not supported on the system.
-		Note that even when the operation was executed, whether the
-		job was actually stopped needs to be checked with
-		|job_status()|.
-		If the status of the job is "dead", the signal will not be
-		sent.  This is to avoid to stop the wrong job (esp. on Unix,
-		where process numbers are recycled).
-		When using "kill" Vim will assume the job will die and close
-		the channel.
-		{only available when compiled with the |+job| feature}
 join({list} [, {sep}])					*join()*
 		Join the items in {list} together into one String.
 		When {sep} is specified it is put in between the items.  If
 		{sep} is omitted a single space is used.
 		{text} to end in a space.
 		The result is only visible if {buf} has 'buftype' set to
 		"prompt".  Example: >
 			call prompt_setprompt(bufnr(''), 'command: ')
 <
-						*prop_add()* *E965*
+prop_ functions are documented here: |text-prop-functions|.
-prop_add({lnum}, {col}, {props})
-		Attach a text property at position {lnum}, {col}.  {col} is
-		counted in bytes, use one for the first column.
-		If {lnum} is invalid an error is given. *E966*
-		If {col} is invalid an error is given. *E964*
-		{props} is a dictionary with these fields:
-		   length	length of text in bytes, can only be used
-				for a property that does not continue in
-				another line; can be zero
-		   end_lnum	line number for the end of text
-		   end_col	column just after the text; not used when
-				"length" is present; when {col} and "end_col"
-				are equal, and "end_lnum" is omitted or equal
-				to {lnum}, this is a zero-width text property
-		   bufnr	buffer to add the property to; when omitted
-				the current buffer is used
-		   id		user defined ID for the property; when omitted
-				zero is used
-		   type		name of the text property type
-		All fields except "type" are optional.
-		It is an error when both "length" and "end_lnum" or "end_col"
-		are given.  Either use "length" or "end_col" for a property
-		within one line, or use "end_lnum" and "end_col" for a
-		property that spans more than one line.
-		When neither "length" nor "end_col" are given the property
-		will be zero-width.  That means it will not be highlighted but
-		will move with the text, as a kind of mark.
-		The property can end exactly at the last character of the
-		text, or just after it.  In the last case, if text is appended
-		to the line, the text property size will increase, also when
-		the property type does not have "end_incl" set.
-		"type" will first be looked up in the buffer the property is
-		added to. When not found, the global property types are used.
-		If not found an error is given.
-		See |text-properties| for information about text properties.
-prop_clear({lnum} [, {lnum-end} [, {props}]])		*prop_clear()*
-		Remove all text properties from line {lnum}.
-		When {lnum-end} is given, remove all text properties from line
-		{lnum} to {lnum-end} (inclusive).
-		When {props} contains a "bufnr" item use this buffer,
-		otherwise use the current buffer.
-		See |text-properties| for information about text properties.
-							*prop_find()*
-prop_find({props} [, {direction}])
-		NOT IMPLEMENTED YET
-		Search for a text property as specified with {props}:
-		   id		property with this ID
-		   type		property with this type name
-		   bufnr	buffer to search in; when present a
-				start position with "lnum" and "col"
-				must be given; when omitted the
-				current buffer is used
-		   lnum		start in this line (when omitted start
-				at the cursor)
-		   col		start at this column (when omitted
-				and "lnum" is given: use column 1,
-				otherwise start at the cursor)
-		   skipstart	do not look for a match at the start
-				position
-		{direction} can be "f" for forward and "b" for backward.  When
-		omitted forward search is performed.
-		If a match is found then a Dict is returned with the entries
-		as with prop_list(), and additionally an "lnum" entry.
-		If no match is found then an empty Dict is returned.
-		See |text-properties| for information about text properties.
-prop_list({lnum} [, {props}])				*prop_list()*
-		Return a List with all text properties in line {lnum}.
-		When {props} contains a "bufnr" item, use this buffer instead
-		of the current buffer.
-		The properties are ordered by starting column and priority.
-		Each property is a Dict with these entries:
-		   col		starting column
-		   length	length in bytes, one more if line break is
-				included
-		   id		property ID
-		   type		name of the property type, omitted if
-				the type was deleted
-		   start	when TRUE property starts in this line
-		   end		when TRUE property ends in this line
-		When "start" is zero the property started in a previous line,
-		the current one is a continuation.
-		When "end" is zero the property continues in the next line.
-		The line break after this line is included.
-		See |text-properties| for information about text properties.
-						*prop_remove()* *E968*
-prop_remove({props} [, {lnum} [, {lnum-end}]])
-		Remove a matching text property from line {lnum}.  When
-		{lnum-end} is given, remove matching text properties from line
-		{lnum} to {lnum-end} (inclusive).
-		When {lnum} is omitted remove matching text properties from
-		all lines.
-		{props} is a dictionary with these fields:
-		   id		remove text properties with this ID
-		   type		remove text properties with this type name
-		   bufnr	use this buffer instead of the current one
-		   all		when TRUE remove all matching text properties,
-				not just the first one
-		A property matches when either "id" or "type" matches.
-		If buffer "bufnr" does not exist you get an error message.
-		If buffer "bufnr" is not loaded then nothing happens.
-		Returns the number of properties that were removed.
-		See |text-properties| for information about text properties.
-prop_type_add({name}, {props})		*prop_type_add()* *E969* *E970*
-		Add a text property type {name}.  If a property type with this
-		name already exists an error is given.
-		{props} is a dictionary with these optional fields:
-		   bufnr	define the property only for this buffer; this
-				avoids name collisions and automatically
-				clears the property types when the buffer is
-				deleted.
-		   highlight	name of highlight group to use
-		   priority	when a character has multiple text
-				properties the one with the highest priority
-				will be used; negative values can be used, the
-				default priority is zero
-		   combine	when TRUE combine the highlight with any
-				syntax highlight; when omitted or FALSE syntax
-				highlight will not be used
-		   start_incl	when TRUE inserts at the start position will
-				be included in the text property
-		   end_incl	when TRUE inserts at the end position will be
-				included in the text property
-		See |text-properties| for information about text properties.
-prop_type_change({name}, {props})			*prop_type_change()*
-		Change properties of an existing text property type.  If a
-		property with this name does not exist an error is given.
-		The {props} argument is just like |prop_type_add()|.
-		See |text-properties| for information about text properties.
-prop_type_delete({name} [, {props}])			*prop_type_delete()*
-		Remove the text property type {name}.  When text properties
-		using the type {name} are still in place, they will not have
-		an effect and can no longer be removed by name.
-		{props} can contain a "bufnr" item.  When it is given, delete
-		a property type from this buffer instead of from the global
-		property types.
-		When text property type {name} is not found there is no error.
-		See |text-properties| for information about text properties.
-prop_type_get([{name} [, {props}])			*prop_type_get()*
-		Returns the properties of property type {name}.  This is a
-		dictionary with the same fields as was given to
-		prop_type_add().
-		When the property type {name} does not exist, an empty
-		dictionary is returned.
-		{props} can contain a "bufnr" item.  When it is given, use
-		this buffer instead of the global property types.
-		See |text-properties| for information about text properties.
-prop_type_list([{props}])				*prop_type_list()*
-		Returns a list with all property type names.
-		{props} can contain a "bufnr" item.  When it is given, use
-		this buffer instead of the global property types.
-		See |text-properties| for information about text properties.
 pumvisible()						*pumvisible()*
 		Returns non-zero when the popup menu is visible, zero
 		otherwise.  See |ins-completion-menu|.
 		This can be used to avoid some things that would remove the
 		When there is one argument {col} this is used as column number
 		for which to return the 'shiftwidth' value. This matters for the
 		'vartabstop' feature. If the 'vartabstop' setting is enabled and
 		no {col} argument is given, column 1 will be assumed.
-sign_define({name} [, {dict}])				*sign_define()*
+sign_ functions are documented here: |sign-functions-details|
-sign_define({list})
-		Define a new sign named {name} or modify the attributes of an
-		existing sign.  This is similar to the |:sign-define| command.
-		Prefix {name} with a unique text to avoid name collisions.
-		There is no {group} like with placing signs.
-		The {name} can be a String or a Number.  The optional {dict}
-		argument specifies the sign attributes.  The following values
-		are supported:
-		   icon		full path to the bitmap file for the sign.
-		   linehl	highlight group used for the whole line the
-				sign is placed in.
-		   text		text that is displayed when there is no icon
-				or the GUI is not being used.
-		   texthl	highlight group used for the text item
-		If the sign named {name} already exists, then the attributes
-		of the sign are updated.
-		The one argument {list} can be used to define a list of signs.
-		Each list item is a dictionary with the above items in {dict}
-		and a 'name' item for the sign name.
-		Returns 0 on success and -1 on failure.  When the one argument
-		{list} is used, then returns a List of values one for each
-		defined sign.
-		Examples: >
-			call sign_define("mySign", {
-				\ "text" : "=>",
-				\ "texthl" : "Error",
-				\ "linehl" : "Search"})
-			call sign_define([
-				\ {'name' : 'sign1',
-				\  'text' : '=>'},
-				\ {'name' : 'sign2',
-				\  'text' : '!!'}
-				\ ])
-<
-sign_getdefined([{name}])				*sign_getdefined()*
-		Get a list of defined signs and their attributes.
-		This is similar to the |:sign-list| command.
-		If the {name} is not supplied, then a list of all the defined
-		signs is returned. Otherwise the attribute of the specified
-		sign is returned.
-		Each list item in the returned value is a dictionary with the
-		following entries:
-		   icon		full path to the bitmap file of the sign
-		   linehl	highlight group used for the whole line the
-				sign is placed in.
-		   name		name of the sign
-		   text		text that is displayed when there is no icon
-				or the GUI is not being used.
-		   texthl	highlight group used for the text item
-		Returns an empty List if there are no signs and when {name} is
-		not found.
-		Examples: >
-			" Get a list of all the defined signs
-			echo sign_getdefined()
-			" Get the attribute of the sign named mySign
-			echo sign_getdefined("mySign")
-<
-sign_getplaced([{expr} [, {dict}]])			*sign_getplaced()*
-		Return a list of signs placed in a buffer or all the buffers.
-		This is similar to the |:sign-place-list| command.
-		If the optional buffer name {expr} is specified, then only the
-		list of signs placed in that buffer is returned.  For the use
-		of {expr}, see |bufname()|. The optional {dict} can contain
-		the following entries:
-		   group	select only signs in this group
-		   id		select sign with this identifier
-		   lnum		select signs placed in this line. For the use
-				of {lnum}, see |line()|.
-		If {group} is '*', then signs in all the groups including the
-		global group are returned. If {group} is not supplied or is an
-		empty string, then only signs in the global group are
-		returned.  If no arguments are supplied, then signs in the
-		global group placed in all the buffers are returned.
-		See |sign-group|.
-		Each list item in the returned value is a dictionary with the
-		following entries:
-			bufnr	number of the buffer with the sign
-			signs	list of signs placed in {bufnr}. Each list
-				item is a dictionary with the below listed
-				entries
-		The dictionary for each sign contains the following entries:
-			group	sign group. Set to '' for the global group.
-			id	identifier of the sign
-			lnum	line number where the sign is placed
-			name	name of the defined sign
-			priority	sign priority
-		The returned signs in a buffer are ordered by their line
-		number and priority.
-		Returns an empty list on failure or if there are no placed
-		signs.
-		Examples: >
-			" Get a List of signs placed in eval.c in the
-			" global group
-			echo sign_getplaced("eval.c")
-			" Get a List of signs in group 'g1' placed in eval.c
-			echo sign_getplaced("eval.c", {'group' : 'g1'})
-			" Get a List of signs placed at line 10 in eval.c
-			echo sign_getplaced("eval.c", {'lnum' : 10})
-			" Get sign with identifier 10 placed in a.py
-			echo sign_getplaced("a.py", {'id' : 10})
-			" Get sign with id 20 in group 'g1' placed in a.py
-			echo sign_getplaced("a.py", {'group' : 'g1',
-							\  'id' : 20})
-			" Get a List of all the placed signs
-			echo sign_getplaced()
-<
-							*sign_jump()*
-sign_jump({id}, {group}, {expr})
-		Open the buffer {expr} or jump to the window that contains
-		{expr} and position the cursor at sign {id} in group {group}.
-		This is similar to the |:sign-jump| command.
-		For the use of {expr}, see |bufname()|.
-		Returns the line number of the sign. Returns -1 if the
-		arguments are invalid.
-		Example: >
-			" Jump to sign 10 in the current buffer
-			call sign_jump(10, '', '')
-<
-							*sign_place()*
-sign_place({id}, {group}, {name}, {expr} [, {dict}])
-		Place the sign defined as {name} at line {lnum} in file or
-		buffer {expr} and assign {id} and {group} to sign.  This is
-		similar to the |:sign-place| command.
-		If the sign identifier {id} is zero, then a new identifier is
-		allocated.  Otherwise the specified number is used. {group} is
-		the sign group name. To use the global sign group, use an
-		empty string.  {group} functions as a namespace for {id}, thus
-		two groups can use the same IDs. Refer to |sign-identifier|
-		and |sign-group| for more information.
-		{name} refers to a defined sign.
-		{expr} refers to a buffer name or number. For the accepted
-		values, see |bufname()|.
-		The optional {dict} argument supports the following entries:
-			lnum		line number in the file or buffer
-					{expr} where the sign is to be placed.
-					For the accepted values, see |line()|.
-			priority	priority of the sign. See
-					|sign-priority| for more information.
-		If the optional {dict} is not specified, then it modifies the
-		placed sign {id} in group {group} to use the defined sign
-		{name}.
-		Returns the sign identifier on success and -1 on failure.
-		Examples: >
-			" Place a sign named sign1 with id 5 at line 20 in
-			" buffer json.c
-			call sign_place(5, '', 'sign1', 'json.c',
-							\ {'lnum' : 20})
-			" Updates sign 5 in buffer json.c to use sign2
-			call sign_place(5, '', 'sign2', 'json.c')
-			" Place a sign named sign3 at line 30 in
-			" buffer json.c with a new identifier
-			let id = sign_place(0, '', 'sign3', 'json.c',
-							\ {'lnum' : 30})
-			" Place a sign named sign4 with id 10 in group 'g3'
-			" at line 40 in buffer json.c with priority 90
-			call sign_place(10, 'g3', 'sign4', 'json.c',
-					\ {'lnum' : 40, 'priority' : 90})
-<
-							*sign_placelist()*
-sign_placelist({list})
-		Place one or more signs.  This is similar to the
-		|sign_place()| function.  The {list} argument specifies the
-		List of signs to place. Each list item is a dict with the
-		following sign attributes:
-		    buffer	buffer name or number. For the accepted
-				values, see |bufname()|.
-		    group	sign group. {group} functions as a namespace
-				for {id}, thus two groups can use the same
-				IDs. If not specified or set to an empty
-				string, then the global group is used.   See
-				|sign-group| for more information.
-		    id		sign identifier. If not specified or zero,
-				then a new unique identifier is allocated.
-				Otherwise the specified number is used. See
-				|sign-identifier| for more information.
-		    lnum	line number in the buffer {expr} where the
-				sign is to be placed. For the accepted values,
-				see |line()|.
-		    name	name of the sign to place. See |sign_define()|
-		    		for more information.
-		    priority	priority of the sign. When multiple signs are
-				placed on a line, the sign with the highest
-				priority is used. If not specified, the
-				default value of 10 is used. See
-				|sign-priority| for more information.
-		If {id} refers to an existing sign, then the existing sign is
-		modified to use the specified {name} and/or {priority}.
-		Returns a List of sign identifiers. If failed to place a
-		sign, the corresponding list item is set to -1.
-		Examples: >
-			" Place sign s1 with id 5 at line 20 and id 10 at line
-			" 30 in buffer a.c
-			let [n1, n2] = sign_placelist([
-				\ {'id' : 5,
-				\  'name' : 's1',
-				\  'buffer' : 'a.c',
-				\  'lnum' : 20},
-				\ {'id' : 10,
-				\  'name' : 's1',
-				\  'buffer' : 'a.c',
-				\  'lnum' : 30}
-				\ ])
-			" Place sign s1 in buffer a.c at line 40 and 50
-			" with auto-generated identifiers
-			let [n1, n2] = sign_placelist([
-				\ {'name' : 's1',
-				\  'buffer' : 'a.c',
-				\  'lnum' : 40},
-				\ {'name' : 's1',
-				\  'buffer' : 'a.c',
-				\  'lnum' : 50}
-				\ ])
-<
-sign_undefine([{name}])					*sign_undefine()*
-sign_undefine({list})
-		Deletes a previously defined sign {name}. This is similar to
-		the |:sign-undefine| command. If {name} is not supplied, then
-		deletes all the defined signs.
-		The one argument {list} can be used to undefine a list of
-		signs. Each list item is the name of a sign.
-		Returns 0 on success and -1 on failure.  For the one argument
-		{list} call, returns a list of values one for each undefined
-		sign.
-		Examples: >
-			" Delete a sign named mySign
-			call sign_undefine("mySign")
-			" Delete signs 'sign1' and 'sign2'
-			call sign_undefine(["sign1", "sign2"])
-			" Delete all the signs
-			call sign_undefine()
-<
-sign_unplace({group} [, {dict}])			*sign_unplace()*
-		Remove a previously placed sign in one or more buffers.  This
-		is similar to the |:sign-unplace| command.
-		{group} is the sign group name. To use the global sign group,
-		use an empty string.  If {group} is set to '*', then all the
-		groups including the global group are used.
-		The signs in {group} are selected based on the entries in
-		{dict}.  The following optional entries in {dict} are
-		supported:
-			buffer	buffer name or number. See |bufname()|.
-			id	sign identifier
-		If {dict} is not supplied, then all the signs in {group} are
-		removed.
-		Returns 0 on success and -1 on failure.
-		Examples: >
-			" Remove sign 10 from buffer a.vim
-			call sign_unplace('', {'buffer' : "a.vim", 'id' : 10})
-			" Remove sign 20 in group 'g1' from buffer 3
-			call sign_unplace('g1', {'buffer' : 3, 'id' : 20})
-			" Remove all the signs in group 'g2' from buffer 10
-			call sign_unplace('g2', {'buffer' : 10})
-			" Remove sign 30 in group 'g3' from all the buffers
-			call sign_unplace('g3', {'id' : 30})
-			" Remove all the signs placed in buffer 5
-			call sign_unplace('*', {'buffer' : 5})
-			" Remove the signs in group 'g4' from all the buffers
-			call sign_unplace('g4')
-			" Remove sign 40 from all the buffers
-			call sign_unplace('*', {'id' : 40})
-			" Remove all the placed signs from all the buffers
-			call sign_unplace('*')
-<
-sign_unplacelist({list})				*sign_unplacelist()*
-		Remove previously placed signs from one or more buffers.  This
-		is similar to the |sign_unplace()| function.
-		The {list} argument specifies the List of signs to remove.
-		Each list item is a dict with the following sign attributes:
-		    buffer	buffer name or number. For the accepted
-				values, see |bufname()|. If not specified,
-				then the specified sign is removed from all
-				the buffers.
-		    group	sign group name. If not specified or set to an
-				empty string, then the global sign group is
-				used. If set to '*', then all the groups
-				including the global group are used.
-		    id		sign identifier. If not specified, then all
-				the signs in the specified group are removed.
-		Returns a List where an entry is set to 0 if the corresponding
-		sign was successfully removed or -1 on failure.
-		Example: >
-			" Remove sign with id 10 from buffer a.vim and sign
-			" with id 20 from buffer b.vim
-			call sign_unplacelist([
-				\ {'id' : 10, 'buffer' : "a.vim"},
-				\ {'id' : 20, 'buffer' : 'b.vim'},
-				\ ])
-<
 simplify({filename})					*simplify()*
 		Simplify the file name as much as possible without changing
 		the meaning.  Shortcuts (on MS-Windows) or symbolic links (on
 		Unix) are not resolved.  If the first path component in
 		{filename} designates the current directory, this will be
 			:exe "redir > " . tmpfile
 <		For Unix, the file will be in a private directory |tempfile|.
 		For MS-Windows forward slashes are used when the 'shellslash'
 		option is set or when 'shellcmdflag' starts with '-'.
 term_ functions are documented here: |terminal-function-details|
-test_alloc_fail({id}, {countdown}, {repeat})		*test_alloc_fail()*
+test_ functions are documented here: |test-functions|
-		This is for testing: If the memory allocation with {id} is
-		called, then decrement {countdown}, and when it reaches zero
-		let memory allocation fail {repeat} times.  When {repeat} is
-		smaller than one it fails one time.
-test_autochdir()					*test_autochdir()*
-		Set a flag to enable the effect of 'autochdir' before Vim
-		startup has finished.
-test_feedinput({string})				*test_feedinput()*
-		Characters in {string} are queued for processing as if they
-		were typed by the user. This uses a low level input buffer.
-		This function works only when with |+unix| or GUI is running.
-test_garbagecollect_now()			 *test_garbagecollect_now()*
-		Like garbagecollect(), but executed right away.  This must
-		only be called directly to avoid any structure to exist
-		internally, and |v:testing| must have been set before calling
-		any function.
-test_garbagecollect_soon()			 *test_garbagecollect_soon()*
-		Set the flag to call the garbagecollector as if in the main
-		loop.  Only to be used in tests.
-test_getvalue({name})					*test_getvalue()*
-		Get the value of an internal variable.  These values for
-		{name} are supported:
-			need_fileinfo
-test_ignore_error({expr})			 *test_ignore_error()*
-		Ignore any error containing {expr}.  A normal message is given
-		instead.
-		This is only meant to be used in tests, where catching the
-		error with try/catch cannot be used (because it skips over
-		following code).
-		{expr} is used literally, not as a pattern.
-		When the {expr} is the string "RESET" then the list of ignored
-		errors is made empty.
-test_null_blob()					*test_null_blob()*
-		Return a |Blob| that is null. Only useful for testing.
-test_null_channel()					*test_null_channel()*
-		Return a |Channel| that is null. Only useful for testing.
-		{only available when compiled with the +channel feature}
-test_null_dict()					*test_null_dict()*
-		Return a |Dict| that is null. Only useful for testing.
-test_null_job()						*test_null_job()*
-		Return a |Job| that is null. Only useful for testing.
-		{only available when compiled with the +job feature}
-test_null_list()					*test_null_list()*
-		Return a |List| that is null. Only useful for testing.
-test_null_partial()					*test_null_partial()*
-		Return a |Partial| that is null. Only useful for testing.
-test_null_string()					*test_null_string()*
-		Return a |String| that is null. Only useful for testing.
-test_option_not_set({name})				*test_option_not_set()*
-		Reset the flag that indicates option {name} was set.  Thus it
-		looks like it still has the default value. Use like this: >
-			set ambiwidth=double
-			call test_option_not_set('ambiwidth')
-<		Now the 'ambiwidth' option behaves like it was never changed,
-		even though the value is "double".
-		Only to be used for testing!
-test_override({name}, {val})				*test_override()*
-		Overrides certain parts of Vim's internal processing to be able
-		to run tests. Only to be used for testing Vim!
-		The override is enabled when {val} is non-zero and removed
-		when {val} is zero.
-		Current supported values for name are:
-		name	     effect when {val} is non-zero ~
-		redraw       disable the redrawing() function
-		redraw_flag  ignore the RedrawingDisabled flag
-		char_avail   disable the char_avail() function
-		starting     reset the "starting" variable, see below
-		nfa_fail     makes the NFA regexp engine fail to force a
-			     fallback to the old engine
-		no_query_mouse  do not query the mouse position for "dec"
-				terminals
-		no_wait_return	set the "no_wait_return" flag.  Not restored
-				with "ALL".
-		ALL	     clear all overrides ({val} is not used)
-		"starting" is to be used when a test should behave like
-		startup was done.  Since the tests are run by sourcing a
-		script the "starting" variable is non-zero. This is usually a
-		good thing (tests run faster), but sometimes changes behavior
-		in a way that the test doesn't work properly.
-		When using: >
-			call test_override('starting', 1)
-<		The value of "starting" is saved.  It is restored by: >
-			call test_override('starting', 0)
-test_refcount({expr})					*test_refcount()*
-		Return the reference count of {expr}.  When {expr} is of a
-		type that does not have a reference count, returns -1.  Only
-		to be used for testing.
-test_scrollbar({which}, {value}, {dragging})		*test_scrollbar()*
-		Pretend using scrollbar {which} to move it to position
-		{value}.  {which} can be:
-			left	Left scrollbar of the current window
-			right	Right scrollbar of the current window
-			hor	Horizontal scrollbar
-		For the vertical scrollbars {value} can be 1 to the
-		line-count of the buffer.  For the horizontal scrollbar the
-		{value} can be between 1 and the maximum line length, assuming
-		'wrap' is not set.
-		When {dragging} is non-zero it's like dragging the scrollbar,
-		otherwise it's like clicking in the scrollbar.
-		Only works when the {which} scrollbar actually exists,
-		obviously only when using the GUI.
-test_setmouse({row}, {col})				*test_setmouse()*
-		Set the mouse position to be used for the next mouse action.
-		{row} and {col} are one based.
-		For example: >
-			call test_setmouse(4, 20)
-			call feedkeys("\<LeftMouse>", "xt")
-test_settime({expr})					*test_settime()*
-		Set the time Vim uses internally.  Currently only used for
-		timestamps in the history, as they are used in viminfo, and
-		for undo.
-		Using a value of 1 makes Vim not sleep after a warning or
-		error message.
-		{expr} must evaluate to a number.  When the value is zero the
-		normal behavior is restored.
 							*timer_info()*
 timer_info([{id}])
 		Return a list with information about timers.
 		When {id} is given only information about this timer is
 	- jumping to another buffer or window
 	- editing another file
 	- closing a window or quitting Vim
 	- etc.
-==============================================================================
-14. Testing							*testing*
-Vim can be tested after building it, usually with "make test".
-The tests are located in the directory "src/testdir".
-There are several types of tests added over time:
-	test33.in		oldest, don't add any more
-	test_something.in	old style tests
-	test_something.vim	new style tests
-						*new-style-testing*
-New tests should be added as new style tests.  These use functions such as
-|assert_equal()| to keep the test commands and the expected result in one
-place.
-						*old-style-testing*
-In some cases an old style test needs to be used.  E.g. when testing Vim
-without the |+eval| feature.
-Find more information in the file src/testdir/README.txt.
 vim:tw=78:ts=8:noet:ft=help:norl:

Mercurial > vim

comparison runtime/doc/eval.txt @ 17456:e414281d8bb4 v8.1.1726