vim-patch:9.1.0120: hard to get visual region using Vim script

Problem:  hard to get visual region using Vim script
Solution: Add getregion() Vim script function
          (Shougo Matsushita, Jakub Łuczyński)

closes: vim/vim#13998
closes: vim/vim#11579

https://github.com/vim/vim/commit/3f905ab3c4f66562f4a224bf00f49d98a0b0da91

Cherry-pick changes from patch 9.1.0122, with :echom instead of :echow.

Co-authored-by: Shougo Matsushita <Shougo.Matsu@gmail.com>
Co-authored-by: Jakub Łuczyński <doubleloop@o2.pl>

3 files changed, 76 insertions, 0 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index c6d75ab985..9c1855806e 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -2918,6 +2918,41 @@ getreginfo([{regname}])                                           *getreginfo()*
 		If {regname} is not specified, |v:register| is used.
 		The returned Dictionary can be passed to |setreg()|.
 
+getregion({pos1}, {pos2}, {type})                                  *getregion()*
+		Returns the list of strings from {pos1} to {pos2} as if it's
+		selected in visual mode of {type}.
+		For possible values of {pos1} and {pos2} see |line()|.
+		{type} is the selection type:
+			"v" for |charwise| mode
+			"V" for |linewise| mode
+			"<CTRL-V>" for |blockwise-visual| mode
+		You can get the last selection type by |visualmode()|.
+		If Visual mode is active, use |mode()| to get the Visual mode
+		(e.g., in a |:vmap|).
+		This function uses the line and column number from the
+		specified position.
+		It is useful to get text starting and ending in different
+		columns, such as |charwise-visual| selection.
+
+		Note that:
+		- Order of {pos1} and {pos2} doesn't matter, it will always
+		  return content from the upper left position to the lower
+		  right position.
+		- If 'virtualedit' is enabled and selection is past the end of
+		  line, resulting lines are filled with blanks.
+		- If the selection starts or ends in the middle of a multibyte
+		  character, it is not included but its selected part is
+		  substituted with spaces.
+		- If {pos1} or {pos2} equals "v" (see |line()|) and it is not in
+		  |visual-mode|, an empty list is returned.
+		- If {pos1}, {pos2} or {type} is an invalid string, an empty
+		  list is returned.
+
+		Examples: >
+			:xnoremap <CR>
+			\ <Cmd>echom getregion('v', '.', mode())<CR>
+<
+
 getregtype([{regname}])                                           *getregtype()*
 		The result is a String, which is type of register {regname}.
 		The value will be one of:
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index 2dae9333b6..56750420e9 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -793,6 +793,7 @@ Cursor and mark position:		*cursor-functions* *mark-functions*
 
 Working with text in the current buffer:		*text-functions*
 	getline()		get a line or list of lines from the buffer
+	getregion()		get a region of text from the buffer
 	setline()		replace a line in the buffer
 	append()		append line or list of lines in the buffer
 	indent()		indent of a specific line
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 224cecf144..527113c016 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -3525,6 +3525,46 @@ function vim.fn.getreg(regname, list) end
 --- @return table
 function vim.fn.getreginfo(regname) end
 
+--- Returns the list of strings from {pos1} to {pos2} as if it's
+--- selected in visual mode of {type}.
+--- For possible values of {pos1} and {pos2} see |line()|.
+--- {type} is the selection type:
+---   "v" for |charwise| mode
+---   "V" for |linewise| mode
+---   "<CTRL-V>" for |blockwise-visual| mode
+--- You can get the last selection type by |visualmode()|.
+--- If Visual mode is active, use |mode()| to get the Visual mode
+--- (e.g., in a |:vmap|).
+--- This function uses the line and column number from the
+--- specified position.
+--- It is useful to get text starting and ending in different
+--- columns, such as |charwise-visual| selection.
+---
+--- Note that:
+--- - Order of {pos1} and {pos2} doesn't matter, it will always
+---   return content from the upper left position to the lower
+---   right position.
+--- - If 'virtualedit' is enabled and selection is past the end of
+---   line, resulting lines are filled with blanks.
+--- - If the selection starts or ends in the middle of a multibyte
+---   character, it is not included but its selected part is
+---   substituted with spaces.
+--- - If {pos1} or {pos2} equals "v" (see |line()|) and it is not in
+---   |visual-mode|, an empty list is returned.
+--- - If {pos1}, {pos2} or {type} is an invalid string, an empty
+---   list is returned.
+---
+--- Examples: >
+---   :xnoremap <CR>
+---   \ <Cmd>echom getregion('v', '.', mode())<CR>
+--- <
+---
+--- @param pos1 string
+--- @param pos2 string
+--- @param type string
+--- @return string[]
+function vim.fn.getregion(pos1, pos2, type) end
+
 --- The result is a String, which is type of register {regname}.
 --- The value will be one of:
 ---     "v"      for |charwise| text