patch 9.1.0009: Cannot easily get the list of matches
Problem: Cannot easily get the list of matches
Solution: Add the matchstrlist() and matchbufline() Vim script
functions (Yegappan Lakshmanan)
closes: #13766
Signed-off-by: Yegappan Lakshmanan <yegappan@yahoo.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 084c76e..8f79d20 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -370,6 +370,8 @@
matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
Number highlight positions with {group}
matcharg({nr}) List arguments of |:match|
+matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict})
+ List all the {pat} matches in buffer {buf}
matchdelete({id} [, {win}]) Number delete match identified by {id}
matchend({expr}, {pat} [, {start} [, {count}]])
Number position where {pat} ends in {expr}
@@ -381,6 +383,8 @@
List match and submatches of {pat} in {expr}
matchstr({expr}, {pat} [, {start} [, {count}]])
String {count}'th match of {pat} in {expr}
+matchstrlist({list}, {pat} [, {dict})
+ List all the {pat} matches in {list}
matchstrpos({expr}, {pat} [, {start} [, {count}]])
List {count}'th match of {pat} in {expr}
max({expr}) Number maximum value of items in {expr}
@@ -6054,6 +6058,51 @@
Can also be used as a |method|: >
GetMatch()->matcharg()
+<
+ *matchbufline()*
+matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}])
+ Returns the |List| of matches in lines from {lnum} to {end} in
+ buffer {buf} where {pat} matches.
+
+ {lnum} and {end} can either be a line number or the string "$"
+ to refer to the last line in {buf}.
+
+ The {dict} argument supports following items:
+ submatches include submatch information (|/\(|)
+
+ For each match, a |Dict| with the following items is returned:
+ byteidx starting byte index of the match
+ lnum line number where there is a match
+ text matched string
+ Note that there can be multiple matches in a single line.
+
+ This function works only for loaded buffers. First call
+ |bufload()| if needed.
+
+ When {buf} is not a valid buffer, the buffer is not loaded or
+ {lnum} or {end} is not valid then an error is given and an
+ empty |List| is returned.
+
+ Examples: >
+ " Assuming line 3 in buffer 5 contains "a"
+ :echo matchbufline(5, '\<\k\+\>', 3, 3)
+ [{'lnum': 3, 'byteidx': 0, 'text': 'a'}]
+ " Assuming line 4 in buffer 10 contains "tik tok"
+ :echo matchbufline(10, '\<\k\+\>', 1, 4)
+ [{'lnum': 4, 'byteidx': 0, 'text': 'tik'}, {'lnum': 4, 'byteidx': 4, 'text': 'tok'}]
+<
+ If {submatch} is present and is v:true, then submatches like
+ "\1", "\2", etc. are also returned. Example: >
+ " Assuming line 2 in buffer 2 contains "acd"
+ :echo matchbufline(2, '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 2, 2
+ \ {'submatches': v:true})
+ [{'lnum': 2, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
+< The "submatches" List always contains 9 items. If a submatch
+ is not found, then an empty string is returned for that
+ submatch.
+
+ Can also be used as a |method|: >
+ GetBuffer()->matchbufline('mypat', 1, '$')
matchdelete({id} [, {win}) *matchdelete()* *E802* *E803*
Deletes a match with ID {id} previously defined by |matchadd()|
@@ -6187,6 +6236,40 @@
Can also be used as a |method|: >
GetText()->matchlist('word')
+<
+ *matchstrlist()*
+matchstrlist({list}, {pat} [, {dict}])
+ Returns the |List| of matches in {list} where {pat} matches.
+ {list} is a |List| of strings. {pat} is matched against each
+ string in {list}.
+
+ The {dict} argument supports following items:
+ submatches include submatch information (|/\(|)
+
+ For each match, a |Dict| with the following items is returned:
+ byteidx starting byte index of the match.
+ idx index in {list} of the match.
+ text matched string
+ submatches a List of submatches. Present only if
+ "submatches" is set to v:true in {dict}.
+
+ Example: >
+ :echo matchstrlist(['tik tok'], '\<\k\+\>')
+ [{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}]
+ :echo matchstrlist(['a', 'b'], '\<\k\+\>')
+ [{'idx': 0, 'byteidx': 0, 'text': 'a'}, {'idx': 1, 'byteidx': 0, 'text': 'b'}]
+<
+ If "submatches" is present and is v:true, then submatches like
+ "\1", "\2", etc. are also returned. Example: >
+ :echo matchstrlist(['acd'], '\(a\)\?\(b\)\?\(c\)\?\(.*\)',
+ \ #{submatches: v:true})
+ [{'idx': 0, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
+< The "submatches" List always contains 9 items. If a submatch
+ is not found, then an empty string is returned for that
+ submatch.
+
+ Can also be used as a |method|: >
+ GetListOfStrings()->matchstrlist('mypat')
matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
Same as |match()|, but return the matched string. Example: >
diff --git a/runtime/doc/tags b/runtime/doc/tags
index e8ac2bc..9af1ac0 100644
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -8594,6 +8594,7 @@
matchadd() builtin.txt /*matchadd()*
matchaddpos() builtin.txt /*matchaddpos()*
matcharg() builtin.txt /*matcharg()*
+matchbufline() builtin.txt /*matchbufline()*
matchdelete() builtin.txt /*matchdelete()*
matchend() builtin.txt /*matchend()*
matchfuzzy() builtin.txt /*matchfuzzy()*
@@ -8602,6 +8603,7 @@
matchlist() builtin.txt /*matchlist()*
matchparen pi_paren.txt /*matchparen*
matchstr() builtin.txt /*matchstr()*
+matchstrlist() builtin.txt /*matchstrlist()*
matchstrpos() builtin.txt /*matchstrpos()*
matlab-indent indent.txt /*matlab-indent*
matlab-indenting indent.txt /*matlab-indenting*
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index c4f2a8c..2286d48 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -743,10 +743,13 @@
toupper() turn a string to uppercase
charclass() class of a character
match() position where a pattern matches in a string
+ matchbufline() all the matches of a pattern in a buffer
matchend() position where a pattern match ends in a string
matchfuzzy() fuzzy matches a string in a list of strings
matchfuzzypos() fuzzy matches a string in a list of strings
matchstr() match of a pattern in a string
+ matchstrlist() all the matches of a pattern in a List of
+ strings
matchstrpos() match and positions of a pattern in a string
matchlist() like matchstr() and also return submatches
stridx() first index of a short string in a long string