diff options
author | Yegappan Lakshmanan <yegappan@yahoo.com> | 2024-01-04 22:28:46 +0100 |
---|---|---|
committer | Christian Brabandt <cb@256bit.org> | 2024-01-04 22:28:46 +0100 |
commit | f93b1c881a99fa847a1bafa71877d7e16f18e6ef (patch) | |
tree | 939f3990596c22218d49b3a70c80ad336fa244b2 /runtime/doc/builtin.txt | |
parent | 30994d686c9199edae887e7322ef046c91988566 (diff) |
patch 9.1.0009: Cannot easily get the list of matchesv9.1.0009
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>
Diffstat (limited to 'runtime/doc/builtin.txt')
-rw-r--r-- | runtime/doc/builtin.txt | 83 |
1 files changed, 83 insertions, 0 deletions
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt index 084c76edfb..8f79d2001d 100644 --- a/runtime/doc/builtin.txt +++ b/runtime/doc/builtin.txt @@ -370,6 +370,8 @@ matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]]) 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 @@ matchlist({expr}, {pat} [, {start} [, {count}]]) 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 @@ matcharg({nr}) *matcharg()* 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 @@ matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()* 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: > |