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: #13998
closes: #11579
Co-authored-by: =?UTF-8?q?Jakub=20=C5=81uczy=C5=84ski?= <doubleloop@o2.pl>
Co-authored-by: Shougo Matsushita <Shougo.Matsu@gmail.com>
Signed-off-by: Shougo Matsushita <Shougo.Matsu@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 0cddeff..93b3000 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -263,6 +263,8 @@
getreg([{regname} [, 1 [, {list}]]])
String or List contents of a register
getreginfo([{regname}]) Dict information about a register
+getregion({pos1}, {pos2}, {type})
+ List get the text from {pos1} to {pos2}
getregtype([{regname}]) String type of a register
getscriptinfo([{opts}]) List list of sourced scripts
gettabinfo([{expr}]) List list of tab pages
@@ -4266,6 +4268,43 @@
Can also be used as a |method|: >
GetRegname()->getreginfo()
+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 |characterwise| 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 |characterwise-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>echo getregion('v', '.', mode())<CR>
+<
+ Can also be used as a |method|: >
+ '.'->getregion("'a', 'v')
+<
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/tags b/runtime/doc/tags
index 330ac8b..b7e26ee 100644
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -7760,6 +7760,7 @@
getqflist-examples quickfix.txt /*getqflist-examples*
getreg() builtin.txt /*getreg()*
getreginfo() builtin.txt /*getreginfo()*
+getregion() builtin.txt /*getregion()*
getregtype() builtin.txt /*getregtype()*
getscript pi_getscript.txt /*getscript*
getscript-autoinstall pi_getscript.txt /*getscript-autoinstall*
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index 0ca19be..0d832a3 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -1,4 +1,4 @@
-*usr_41.txt* For Vim version 9.1. Last change: 2024 Feb 01
+*usr_41.txt* For Vim version 9.1. Last change: 2024 Feb 20
VIM USER MANUAL - by Bram Moolenaar
@@ -929,6 +929,7 @@
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/doc/version9.txt b/runtime/doc/version9.txt
index e8973ce..29dbfb8 100644
--- a/runtime/doc/version9.txt
+++ b/runtime/doc/version9.txt
@@ -41560,6 +41560,7 @@
|foreach()| apply function to List items
|matchbufline()| all the matches of a pattern in a buffer
|matchstrlist()| all the matches of a pattern in a List of strings
+|getregion()| get a region of text from a buffer
Autocommands: ~