---
name: "kak_highlighters"
section: "1"
platform: "linux"
package: "kakoune"
version: "0~2016.12.20.1.3a6167ae-1"
release: "Debian 9 (Stretch)"
platforms: ["linux"]
url: "https://new.carta.tech/kak_highlighters"
---

# kak\_highlighters(1)

a

## NAME

highlighters - a

## DESCRIPTION

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

```
addhl <highlighter_name> <highlighter_parameters> ...
```

and

```
rmhl <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 **rmhl** 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:

```
    addhl regex //(\hTODO:)?[^\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** \<flag\> \<option\_name\>

add a column in front of text, and display the given flag in it for every line contained in the int-list option named \<option\_name\>

**show\_matching**

highlight matching char of the character under the selections cursor using MatchingChar face

**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 *\|*)

**ranges** \<option\_name\>

use the data in the range-faces option of the given name to highlight the buffer.

**fill** \<face\>

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

## HIGHLIGHTING GROUPS

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

```
addhl group <name>
```

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

```
addhl -group <name> <type> <params>...
```

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

```
addhl -group <name> group <subname>
addhl -group <name>/<subname> <type> <params>...
```

## 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 construct:

```
%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 regions highlighter which can take any number of regions.

The following command:

```
addhl regions <name> <region_name1> <opening1> <closing1> <recurse1>
                                <region_name2> <opening2> <closing2> <recurse2>...
```

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

```
addhl -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.

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

```
addhl regions -default code <lang> \
        string <str_opening> <str_closing> <str_recurse> \
        comment <comment_opening> <comment_closing> <comment_recurse>
addhl -group <lang>/code ...
addhl -group <lang>/string ...
addhl -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:

```
addhl -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:

```
addhl -group / group <name>
addhl -group /name regex ...
```

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

```
addhl ref <name>
```

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