Home • Explore • Blog • CI
☰



neovim
78th chunk of `runtime/doc/vimfn.txt`
57e83bca4f4a10cb5856d579133939a5b651309f156c3de60000000100000fbc
 a match will
		always overrule syntax highlighting.

		The optional {id} argument allows the request for a specific
		match ID.  If a specified ID is already taken, an error
		message will appear and the match will not be added.  An ID
		is specified as a positive integer (zero excluded).  IDs 1, 2
		and 3 are reserved for |:match|, |:2match| and |:3match|,
		respectively.  3 is reserved for use by the |matchparen|
		plugin.
		If the {id} argument is not specified or -1, |matchadd()|
		automatically chooses a free ID, which is at least 1000.

		The optional {dict} argument allows for further custom
		values. Currently this is used to specify a match specific
		conceal character that will be shown for |hl-Conceal|
		highlighted matches. The dict can have the following members:

			conceal	    Special character to show instead of the
				    match (only for |hl-Conceal| highlighted
				    matches, see |:syn-cchar|)
			window	    Instead of the current window use the
				    window with this number or window ID.

		The number of matches is not limited, as it is the case with
		the |:match| commands.

		Returns -1 on error.

		Example: >vim
			highlight MyGroup ctermbg=green guibg=green
			let m = matchadd("MyGroup", "TODO")
<		Deletion of the pattern: >vim
			call matchdelete(m)

<		A list of matches defined by |matchadd()| and |:match| are
		available from |getmatches()|.  All matches can be deleted in
		one operation by |clearmatches()|.

                Parameters: ~
                  • {group} (`integer|string`)
                  • {pattern} (`string`)
                  • {priority} (`integer?`)
                  • {id} (`integer?`)
                  • {dict} (`string?`)

                Return: ~
                  (`any`)

matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])   *matchaddpos()*
		Same as |matchadd()|, but requires a list of positions {pos}
		instead of a pattern. This command is faster than |matchadd()|
		because it does not handle regular expressions and it sets
		buffer line boundaries to redraw screen. It is supposed to be
		used when fast match additions and deletions are required, for
		example to highlight matching parentheses.
							*E5030* *E5031*
		{pos} is a list of positions.  Each position can be one of
		these:
		- A number.  This whole line will be highlighted.  The first
		  line has number 1.
		- A list with one number, e.g., [23]. The whole line with this
		  number will be highlighted.
		- A list with two numbers, e.g., [23, 11]. The first number is
		  the line number, the second one is the column number (first
		  column is 1, the value must correspond to the byte index as
		  |col()| would return).  The character at this position will
		  be highlighted.
		- A list with three numbers, e.g., [23, 11, 3]. As above, but
		  the third number gives the length of the highlight in bytes.

		Entries with zero and negative line numbers are silently
		ignored, as well as entries with negative column numbers and
		lengths.

		Returns -1 on error.

		Example: >vim
			highlight MyGroup ctermbg=green guibg=green
			let m = matchaddpos("MyGroup", [[23, 24], 34])
<		Deletion of the pattern: >vim
			call matchdelete(m)

<		Matches added by |matchaddpos()| are returned by
		|getmatches()|.

                Parameters: ~
                  • {group} (`integer|string`)
                  • {pos} (`any[]`)
                  • {priority} (`integer?`)
                  • {id} (`integer?`)
                  • {dict} (`string?`)

                Return: ~
                  (`any`)

matcharg({nr})                                                      *matcharg()*
		Selects the {nr} match item, as set with a |:match|,
		|:2match| or |:3match| command.
		Return a |List| with two elements:
			The name of the highlight group used
			The pattern used.
		When {nr} is not 1, 2 or 3 returns an empty |List|.
		When there is no match item set returns ['', ''].
		This is useful to save and restore a |:match|.
		Highlighting
Title: Vim Function Documentation: matchadd() and matchaddpos() continued
Summary
This section continues documenting the `matchadd()` function, detailing the optional `{id}` argument for requesting specific match IDs and the `{dict}` argument for custom values like conceal characters. It mentions that the number of matches is unlimited, shows an example of using `matchadd()` and `matchdelete()`, and references functions for managing matches (`getmatches()` and `clearmatches()`). Furthermore, it describes the `matchaddpos()` function, which is similar to `matchadd()` but uses a list of positions instead of a pattern for faster match additions and deletions. It explains the different formats of the position list and provides an example.