patch 8.1.1043: Lua interface does not support Blobv8.1.1043

Problem:    Lua interface does not support Blob.
Solution:   Add support to Blob. (Ozaki Kiichi, closes #4151)

1 files changed, 50 insertions, 14 deletions

diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt
index a68f972f67..d3576100e7 100644
--- a/runtime/doc/if_lua.txt
+++ b/runtime/doc/if_lua.txt
@@ -10,11 +10,12 @@ The Lua Interface to Vim				*lua* *Lua*
 2. The vim module		|lua-vim|
 3. List userdata		|lua-list|
 4. Dict userdata		|lua-dict|
-5. Funcref userdata		|lua-funcref|
-6. Buffer userdata		|lua-buffer|
-7. Window userdata		|lua-window|
-8. The luaeval function		|lua-luaeval|
-9. Dynamic loading		|lua-dynamic|
+5. Blob userdata		|lua-blob|
+6. Funcref userdata		|lua-funcref|
+7. Buffer userdata		|lua-buffer|
+8. Window userdata		|lua-window|
+9. luaeval() Vim function	|lua-luaeval|
+10. Dynamic loading		|lua-dynamic|
 
 {Vi does not have any of these commands}
 
@@ -141,6 +142,14 @@ Vim evaluation and command execution, and others.
 				    :" {'1': 3.141593, '2': v:false,
 				    :" 'say': 'hi'}
 <
+	vim.blob([arg])		Returns an empty blob or, if "arg" is a Lua
+				string, returns a blob b such that b is
+				equivalent to "arg" as a byte string.
+				Examples: >
+				    :lua s = "12ab\x00\x80\xfe\xff"
+				    :echo luaeval('vim.blob(s)')
+				    :" 0z31326162.0080FEFF
+<
 	vim.funcref({name})	Returns a Funcref to function {name} (see
 				|Funcref|). It is equivalent to Vim's
 				function().
@@ -260,7 +269,34 @@ Examples:
 <
 
 ==============================================================================
-5. Funcref userdata					*lua-funcref*
+5. Blob userdata					*lua-blob*
+
+Blob userdata represent vim blobs. A blob "b" has the following properties:
+
+Properties
+----------
+	o "#b" is the length of blob "b", equivalent to "len(b)" in Vim.
+	o "b[k]" returns the k-th item in "b"; "b" is zero-indexed, as in Vim.
+	    To modify the k-th item, simply do "b[k] = number"; in particular,
+	    "b[#b] = number" can append a byte to tail.
+
+Methods
+-------
+	o "b:add(bytes)" appends "bytes" to the end of "b".
+
+Examples:
+>
+	:let b = 0z001122
+	:lua b = vim.eval('b') -- same 'b'
+	:lua print(b, b[0], #b)
+	:lua b[1] = 32
+	:lua b[#b] = 0x33 -- append a byte to tail
+	:lua b:add("\x80\x81\xfe\xff")
+	:echo b
+<
+
+==============================================================================
+6. Funcref userdata					*lua-funcref*
 
 Funcref userdata represent funcref variables in Vim. Funcrefs that were
 defined with a "dict" attribute need to be obtained as a dictionary key
@@ -293,7 +329,7 @@ Examples:
 <
 
 ==============================================================================
-6. Buffer userdata					*lua-buffer*
+7. Buffer userdata					*lua-buffer*
 
 Buffer userdata represent vim buffers. A buffer userdata "b" has the following
 properties and methods:
@@ -345,7 +381,7 @@ Examples:
 <
 
 ==============================================================================
-7. Window userdata					*lua-window*
+8. Window userdata					*lua-window*
 
 Window objects represent vim windows. A window userdata "w" has the following
 properties and methods:
@@ -377,7 +413,7 @@ Examples:
 <
 
 ==============================================================================
-8. The luaeval function					*lua-luaeval* *lua-eval*
+9. luaeval() Vim function				*lua-luaeval* *lua-eval*
 
 The (dual) equivalent of "vim.eval" for passing Lua values to Vim is
 "luaeval". "luaeval" takes an expression string and an optional argument and
@@ -390,10 +426,10 @@ returns the result of the expression. It is semantically equivalent in Lua to:
 	end
 <
 Note that "_A" receives the argument to "luaeval". Lua numbers, strings, and
-list, dict, and funcref userdata are converted to their Vim respective types,
-while Lua booleans are converted to numbers. An error is thrown if conversion
-of any of the remaining Lua types, including userdata other than lists, dicts,
-and funcrefs, is attempted.
+list, dict, blob, and funcref userdata are converted to their Vim respective
+types, while Lua booleans are converted to numbers. An error is thrown if
+conversion of any of the remaining Lua types, including userdata other than
+lists, dicts, blobs, and funcrefs, is attempted.
 
 Examples: >
 
@@ -408,7 +444,7 @@ Examples: >
 
 
 ==============================================================================
-9. Dynamic loading				    *lua-dynamic*
+10. Dynamic loading				    *lua-dynamic*
 
 On MS-Windows and Unix the Lua library can be loaded dynamically.  The
 |:version| output then includes |+lua/dyn|.