vim: runtime/doc/eval.txt comparison

comparison runtime/doc/eval.txt @ 15454:1d2b5c016f17 v8.1.0735

patch 8.1.0735: cannot handle binary data commit https://github.com/vim/vim/commit/6e5ea8d2a995b32bbc5972edc4f827b959f2702f Author: Bram Moolenaar <Bram@vim.org> Date: Sat Jan 12 22:47:31 2019 +0100 patch 8.1.0735: cannot handle binary data Problem: Cannot handle binary data. Solution: Add the Blob type. (Yasuhiro Matsumoto, closes https://github.com/vim/vim/issues/3638)

author	Bram Moolenaar <Bram@vim.org>
date	Sat, 12 Jan 2019 23:00:06 +0100
parents	8ac454818352
children	f01eb1aed348

comparison

equal deleted inserted replaced

-:cdee6e827112
+:1d2b5c016f17
 Job		Used for a job, see |job_start()|. *Job* *Jobs*
 Channel		Used for a channel, see |ch_open()|. *Channel* *Channels*
+Blob		Binary Large Object. Stores any sequence of bytes. *Blob*
+		Example: 0zFF00ED015DAF
+		0z is an empty Blob.
 The Number and String types are converted automatically, depending on how they
 are used.
 Conversion from a Number to a String is by making the ASCII representation of
 the Number.  Examples:
 non-empty String, then the value is considered to be TRUE.
 Note that " " and "0" are also non-empty strings, thus considered to be TRUE.
 A List, Dictionary or Float is not a Number or String, thus evaluate to FALSE.
 		*E745* *E728* *E703* *E729* *E730* *E731* *E908* *E910* *E913*
-List, Dictionary, Funcref, Job and Channel types are not automatically
+		*E974* *E975* *E976*
+List, Dictionary, Funcref, Job, Channel and Blob types are not automatically
 converted.
 							*E805* *E806* *E808*
 When mixing Number and Float the Number is converted to Float.  Otherwise
 there is no automatic conversion of Float.  You can use str2float() for String
 the indexes expr1a and expr1b.  This works like with a String, as explained
 just above. Also see |sublist| below.  Examples: >
 	:let l = mylist[:3]		" first four items
 	:let l = mylist[4:4]		" List with one item
 	:let l = mylist[:]		" shallow copy of a List
+If expr8 is a |Blob| this results in a new |Blob| with the bytes in the
+indexes expr1a and expr1b, inclusive.  Examples: >
+	:let b = 0zDEADBEEF
+	:let bs = b[1:2]		" 0zADBE
+	:let bs = b[]			" copy ov 0zDEADBEEF
 Using expr8[expr1] or expr8[expr1a : expr1b] on a |Funcref| results in an
 error.
 Watch out for confusion between a namespace and a variable followed by a colon
 of 'encoding'.
 Note that "\000" and "\x00" force the end of the string.
+blob-literal				*blob-literal* *E973* *E977* *E978*
+------------
+Hexadecimal starting with 0z or 0Z, with an arbitrary number of bytes.
+The sequence must be an even number of hex characters.  Example: >
+	:let b = 0zFF00ED015DAF
 literal-string						*literal-string* *E115*
 ---------------
 'string'		string constant			*expr-'*
 Note that single quotes are used.
 v:t_none	Value of None type.  Read-only.  See: |type()|
 					*v:t_number* *t_number-variable*
 v:t_number	Value of Number type.  Read-only.  See: |type()|
 					*v:t_string* *t_string-variable*
 v:t_string	Value of String type.  Read-only.  See: |type()|
+					*v:t_blob* *t_blob-variable*
+v:t_blob	Value of Blob type.  Read-only.  See: |type()|
 				*v:termresponse* *termresponse-variable*
 v:termresponse	The escape sequence returned by the terminal for the |t_RV|
 		termcap entry.  It is set when Vim receives an escape sequence
 		that starts with ESC [ or CSI and ends in a 'c', with only
 ch_log({msg} [, {handle}])	none	write {msg} in the channel log file
 ch_logfile({fname} [, {mode}])	none	start logging channel activity
 ch_open({address} [, {options}])
 				Channel	open a channel to {address}
 ch_read({handle} [, {options}]) String	read from {handle}
+ch_readblob({handle} [, {options}])
+				Blob	read Blob from {handle}
 ch_readraw({handle} [, {options}])
 				String	read raw from {handle}
 ch_sendexpr({handle}, {expr} [, {options}])
 				any	send {expr} over JSON {handle}
-ch_sendraw({handle}, {string} [, {options}])
+ch_sendraw({handle}, {expr} [, {options}])
-				any	send {string} over raw {handle}
+				any	send {expr} over raw {handle}
 ch_setoptions({handle}, {options})
 				none	set options for {handle}
 ch_status({handle} [, {options}])
 				String	status of channel {handle}
 changenr()			Number	current change number
 hlexists({name})		Number	|TRUE| if highlight group {name} exists
 hlID({name})			Number	syntax ID of highlight group {name}
 hostname()			String	name of the machine Vim is running on
 iconv({expr}, {from}, {to})	String	convert encoding of {expr}
 indent({lnum})			Number	indent of line {lnum}
-index({list}, {expr} [, {start} [, {ic}]])
+index({object}, {expr} [, {start} [, {ic}]])
-				Number	index in {list} where {expr} appears
+				Number	index in {object} where {expr} appears
 input({prompt} [, {text} [, {completion}]])
 				String	get input from the user
 inputdialog({prompt} [, {text} [, {completion}]])
 				String	like input() but in a GUI dialog
 inputlist({textlist})		Number	let the user pick from a choice list
 inputrestore()			Number	restore typeahead
 inputsave()			Number	save and clear typeahead
 inputsecret({prompt} [, {text}]) String	like input() but hiding the text
-insert({list}, {item} [, {idx}]) List	insert {item} in {list} [before {idx}]
+insert({object}, {item} [, {idx}]) List	insert {item} in {object} [before {idx}]
 invert({expr})			Number	bitwise invert
 isdirectory({directory})	Number	|TRUE| if {directory} is a directory
 islocked({expr})		Number	|TRUE| if {expr} is locked
 isnan({expr})			Number	|TRUE| if {expr} is NaN
 items({dict})			List	key-value pairs in {dict}
 pyeval({expr})			any	evaluate |Python| expression
 py3eval({expr})			any	evaluate |python3| expression
 pyxeval({expr})			any	evaluate |python_x| expression
 range({expr} [, {max} [, {stride}]])
 				List	items from {expr} to {max}
-readfile({fname} [, {binary} [, {max}]])
+readfile({fname} [, {type} [, {max}]])
 				List	get list of lines from file {fname}
 reg_executing()			String	get the executing register name
 reg_recording()			String	get the recording register name
 reltime([{start} [, {end}]])	List	get time value
 reltimefloat({time})		Float	turn the time value into a Float
 winrestcmd()			String	returns command to restore window sizes
 winrestview({dict})		none	restore view of current window
 winsaveview()			Dict	save view of current window
 winwidth({nr})			Number	width of window {nr}
 wordcount()			Dict	get byte/char/word statistics
-writefile({list}, {fname} [, {flags}])
+writefile({object}, {fname} [, {flags}])
-				Number	write list of lines to file {fname}
+				Number	write |Blob| or |List| of lines to file
 xor({expr}, {expr})		Number	bitwise XOR
 abs({expr})							*abs()*
 		Return the absolute value of {expr}.  When {expr} evaluates to
 		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|.
 		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}, {string} [, {options}])		*ch_sendraw()*
+ch_sendraw({handle}, {expr} [, {options}])		*ch_sendraw()*
-		Send {string} over {handle}.
+		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.
 		of 'tabstop' is relevant.  {lnum} is used just like in
 		|getline()|.
 		When {lnum} is invalid -1 is returned.
-index({list}, {expr} [, {start} [, {ic}]])			*index()*
+index({object}, {expr} [, {start} [, {ic}]])			*index()*
-		Return the lowest index in |List| {list} where the item has a
+		If {object} is a |List| return the lowest index where the item
-		value equal to {expr}.  There is no automatic conversion, so
+		has a value equal to {expr}.  There is no automatic
-		the String "4" is different from the Number 4.  And the number
+		conversion, so the String "4" is different from the Number 4.
-		4 is different from the Float 4.0.  The value of 'ignorecase'
+		And the number 4 is different from the Float 4.0.  The value
-		is not used here, case always matters.
+		of 'ignorecase' is not used here, case always matters.
+		If {object} is |Blob| return the lowest index where the byte
+		value is equal to {expr}.
 		If {start} is given then start looking at the item with index
 		{start} (may be negative for an item relative to the end).
 		When {ic} is given and it is |TRUE|, ignore case.  Otherwise
 		case must match.
-		-1 is returned when {expr} is not found in {list}.
+		-1 is returned when {expr} is not found in {object}.
 		Example: >
 			:let idx = index(words, "the")
 			:if index(numbers, 123) >= 0
 		|history| stack.
 		The result is a String, which is whatever the user actually
 		typed on the command-line in response to the issued prompt.
 		NOTE: Command-line completion is not supported.
-insert({list}, {item} [, {idx}])			*insert()*
+insert({object}, {item} [, {idx}])			*insert()*
-		Insert {item} at the start of |List| {list}.
+		When {object} is a |List| or a |Blob| insert {item} at the start
+		of it.
 		If {idx} is specified insert {item} before the item with index
 		{idx}.  If {idx} is zero it goes before the first item, just
 		like omitting {idx}.  A negative {idx} is also possible, see
 		|list-index|.  -1 inserts just before the last item.
-		Returns the resulting |List|.  Examples: >
+		Returns the resulting |List| or |Blob|.  Examples: >
 			:let mylist = insert([2, 3, 5], 1)
 			:call insert(mylist, 4, -1)
 			:call insert(mylist, 6, len(mylist))
 <		The last example can be done simpler with |add()|.
 		Note that when {item} is a |List| it is inserted as a single
 		   Funcref		not possible, error
 		   List			as an array (possibly null); when
 					used recursively: []
 		   Dict			as an object (possibly null); when
 					used recursively: {}
+		   Blob			as an array of the individual bytes
 		   v:false		"false"
 		   v:true		"true"
 		   v:none		"null"
 		   v:null		"null"
 		Note that NaN and Infinity are passed on as values.  This is
 			range(2, -2, -1)	" [2, 1, 0, -1, -2]
 			range(0)		" []
 			range(2, 0)		" error!
 <
 							*readfile()*
-readfile({fname} [, {binary} [, {max}]])
+readfile({fname} [, {type} [, {max}]])
 		Read file {fname} and return a |List|, each line of the file
 		as an item.  Lines are broken at NL characters.  Macintosh
 		files separated with CR will result in a single long line
 		(unless a NL appears somewhere).
 		All NUL characters are replaced with a NL character.
-		When {binary} contains "b" binary mode is used:
+		When {type} contains "b" binary mode is used:
 		- When the last line ends in a NL an extra empty list item is
 		  added.
 		- No CR characters are removed.
+		When {type} contains "B" a |Blob| is returned with the binary
+		data of the file unmodified.
 		Otherwise:
 		- CR characters that appear before a NL are removed.
 		- Whether the last line ends in a NL or not does not matter.
 		- When 'encoding' is Unicode any UTF-8 byte order mark is
 		  removed from the text.
 		points to an item before {idx} this is an error.
 		See |list-index| for possible values of {idx} and {end}.
 		Example: >
 			:echo "last item: " . remove(mylist, -1)
 			:call remove(mylist, 0, 9)
+remove({blob}, {idx} [, {end}])
+		Without {end}: Remove the byte at {idx} from |Blob| {blob} and
+		return the byte.
+		With {end}: Remove bytes from {idx} to {end} (inclusive) and
+		return a |Blob| with these bytes.  When {idx} points to the same
+		byte as {end} a |Blob| with one byte is returned.  When {end}
+		points to a byte before {idx} this is an error.
+		Example: >
+			:echo "last byte: " . remove(myblob, -1)
+			:call remove(mylist, 0, 9)
 remove({dict}, {key})
 		Remove the entry from {dict} with key {key}.  Example: >
 			:echo "removed " . remove(dict, "one")
 <		If there is no {key} in {dict} this is an error.
 		resolve() keeps a leading path component specifying the
 		current directory (provided the result is still a relative
 		path name) and also keeps a trailing path separator.
 							*reverse()*
-reverse({list})	Reverse the order of items in {list} in-place.  Returns
+reverse({object})
-		{list}.
+		Reverse the order of items in {object} in-place.
-		If you want a list to remain unmodified make a copy first: >
+		{object} can be a |List| or a |Blob|.
+		Returns {object}.
+		If you want an object to remain unmodified make a copy first: >
 			:let revlist = reverse(copy(mylist))
 round({expr})							*round()*
 		Round off {expr} to the nearest integral value and return it
 		as a |Float|.  If {expr} lies halfway between two integral
 			Float:	    5  |v:t_float|
 			Boolean:    6  |v:t_bool| (v:false and v:true)
 			None	    7  |v:t_none| (v:null and v:none)
 			Job	    8  |v:t_job|
 			Channel	    9  |v:t_channel|
+			Blob	   10  |v:t_blob|
 		For backward compatibility, this method can be used: >
 			:if type(myvar) == type(0)
 			:if type(myvar) == type("")
 			:if type(myvar) == type(function("tr"))
 			:if type(myvar) == type([])
 			visual_words    Number of words visually selected
 					(only in Visual mode)
 							*writefile()*
-writefile({list}, {fname} [, {flags}])
+writefile({object}, {fname} [, {flags}])
-		Write |List| {list} to file {fname}.  Each list item is
+		When {object} is a |List| write it to file {fname}.  Each list
-		separated with a NL.  Each list item must be a String or
+		item is separated with a NL.  Each list item must be a String
-		Number.
+		or Number.
 		When {flags} contains "b" then binary mode is used: There will
 		not be a NL after the last list item.  An empty item at the
 		end does cause the last line in the file to end in a NL.
+		When {object} is a |Blob| write the bytes to file {fname}
+		unmodified.
 		When {flags} contains "a" then append mode is used, lines are
 		appended to the file: >
 			:call writefile(["foo"], "event.log", "a")
 			:call writefile(["bar"], "event.log", "a")
 			the index can be repeated.
 			This cannot be used to add an item to a |List|.
 			This cannot be used to set a byte in a String.  You
 			can do that like this: >
 				:let var = var[0:2] . 'X' . var[4:]
-<
+<			When {var-name} is a |Blob| then {idx} can be the
+			length of the blob, in which case one byte is
+			appended.
 							*E711* *E719*
 :let {var-name}[{idx1}:{idx2}] = {expr1}		*E708* *E709* *E710*
 			Set a sequence of items in a |List| to the result of
 			the expression {expr1}, which must be a list with the
 			correct number of items.

Mercurial > vim

comparison runtime/doc/eval.txt @ 15454:1d2b5c016f17 v8.1.0735