kakoune/doc/manpages/highlighters.asciidoc

kakoune(k)
==========

NAME
----
highlighters - a

Description
-----------

Manipulation of the displayed text is done through highlighters, which can
be added or removed with the following commands:

---------------------------------------------------------------
add-highlighter <highlighter_name> <highlighter_parameters> ...
---------------------------------------------------------------

and

-----------------------------------
remove-highlighter <highlighter_id>
-----------------------------------

*highlighter_id* is a name generated by the highlighter specified with
*highlighter_name*, possibly dependent on the parameters. Use command
completion in a prompt on the *remove-highlighter* command to see the existing highlighters
ids.

General highlighters
--------------------
*regex* <ex> <capture_id>:<face> ...::
	highlight a regex, takes the regex as first parameter, followed by
	any number of face parameters. For example:

----------------------------------------------------------------
    add-highlighter regex //\h*(TODO:)[^\n]* 0:cyan 1:yellow,red
----------------------------------------------------------------

	will highlight C++ style comments in cyan, with an eventual 'TODO:'
	in yellow on red background

*dynregex*::
	Similar to regex, but expand (like a command parameter would) the
	given expression before building a regex from the result

*flag_lines* <face> <option_name>::
	add a column in front of the buffer, and display the flags specified
	in <option_name>, using <face>

*show_matching*::
	highlight matching char of the character under the selections' cursor
	using MatchingChar face

*show_whitespaces* [options]::
	display symbols on top of whitespaces to make them more explicit
	using the Whitespace face, with the following *options*:

	*-lf* <separator>:::
		a one character long separator that will replace line feeds

	*-spc* <separator>:::
		a one character long separator that will replace spaces

	*-nbsp* <separator>:::
		a one character long separator that will replace non-breakable spaces

	*-tab* <separator>:::
		a one character long separator that will replace tabulations

	*-tabpad* <separator>:::
		a one character long separator that will be appended to tabulations to honor the *tabstop* option


*number_lines* [options]::
	show line numbers, with the following *options*:

	*-relative*:::
		show line numbers relative to the main cursor line

	*-hlcursor*:::
		highlight the cursor line with a separate face

	*-separator* <separator text>:::
		specify a string to separate the line numbers column with
		the rest of the buffer (default is '|')

*wrap* [options]::
	soft wrap buffer text at window width, with the following *options*:

	*-word*:::
		wrap at word boundaries instead of codepoint boundaries.

	*-width <max_width>*:::
		wrap text at *max_width* if the window is wider.

*fill* <face>::
	fill using the given *face*, mostly useful with regions highlighters

*ranges* <option_name>::
	use the data in the range-specs option of the given name to highlight
	the buffer. The string part of the is interpretted as a face to apply
	to the range.

*replace-ranges* <option_name>::
	use the data in the range-specs option of the given name to highlight
	the buffer. The string part of the is interpretted as a display line to
	display in place of the range.

*column* <number> <face>::
	highlight column *number* with face *face*

*line* <number> <face>::
	highlight line *number* with face *face*

Highlighting Groups
-------------------

The *group* highlighter is a container for other highlighters. You can add a
group to the current window using

----------------------------
add-highlighter group <name>
----------------------------

The *-group* switch of the *add-highlighter* command provides a mean to add highlighters
inside this group:

------------------------------------------------
add-highlighter -group <name> <type> <params>...
------------------------------------------------

Groups can contain other groups, the *-group* switch can be used to define
a path as follows:

----------------------------------------------------------
add-highlighter -group <name> group <subname>
add-highlighter -group <name>/<subname> <type> <params>...
----------------------------------------------------------

In order to specify which kinds of highlighters can be added to a given group, the *-passes*
flag set can be passed along with the group name. Possible values for this option can be one
or several (separated with a pipe sign) of *colorize*, *move* or *wrap* (default: *colorize*):

-------------------------------------------------------
add-highlighter group -passes colorize|move|wrap <name>
-------------------------------------------------------

Regions highlighters
--------------------

A special highlighter provides a way to segment the buffer into regions,
which are to be highlighted differently.

*name*::
	user defined, used to identify the region
*opening*::
	regex that defines the region start text
*closing*::
	regex that defines the region end text
*recurse*::
	regex that defines the text that matches recursively an end token
	into the region

The *recurse* option is useful for regions that can be nested, for example
the following contruct:

----------
%sh{ ... }
----------

accepts nested braces scopes ('{ ... }') so the following string is valid:

----------------------
%sh{ ... { ... } ... }
----------------------

This region can be defined with:

------------------------
shell_expand %sh\{ \} \{
------------------------

Regions are used in the region highlighters which can take any number
of regions.

The following command:

------------------------------------------------------------------------------
add-highlighter regions <name> <region_name1> <opening1> <closing1> <recurse1>
				<region_name2> <opening2> <closing2> <recurse2>...
------------------------------------------------------------------------------

defines multiple regions in which other highlighters can be added as follows:

-----------------------------------------------
add-highlighter -group <name>/<region_name> ...
-----------------------------------------------

Regions are matched using the left-most rule: the left-most region opening
starts a new region. When a region closes, the closest next opening start
another region.

That matches the rule governing most programming language parsing.

Regions also supports a *-default <default_region>* switch to define the
default region, when no other region matches the current buffer range.

If the *-match-capture* switch is passed, then region closing and recurse
matches are considered valid for a given region opening match only if they
matched the same content for the capture 1.

Most programming languages can then be properly highlighted using a region
highlighter as root:

-----------------------------------------------------------------
add-highlighter regions -default code <lang> \
	string <str_opening> <str_closing> <str_recurse> \
	comment <comment_opening> <comment_closing> <comment_recurse>

add-highlighter -group <lang>/code ...
add-highlighter -group <lang>/string ...
add-highlighter -group <lang>/comment ...
-----------------------------------------------------------------

Shared Highlighters
-------------------

Highlighters are often defined for a specific filetype, and it makes then
sense to share the highlighters between all the windows on the same filetypes.

A shared highlighter can be defined with the following command:

----------------------------------------
add-highlighter -group /<group_name> ...
----------------------------------------

When the group switch values starts with a '/', it references a group in
the shared highlighters, rather than the window highlighters.

The common case would be to create a named shared group, and then fill it
with highlighters:

--------------------------------------
add-highlighter -group / group <name>
add-highlighter -group /name regex ...
--------------------------------------

It can then be referenced in a window using the ref highlighter.

--------------------------
add-highlighter ref <name>
--------------------------

The ref can reference any named highlighter in the shared namespace.