kakoune

Fork of kakoune, an acceptable text editor
git clone git://git.laack.co/kakoune.git
Log | Files | Refs

highlighters.asciidoc (12594B)


      1 = Highlighters
      2 
      3 == Description
      4 
      5 Manipulation of the displayed text is done through highlighters, which can
      6 be added or removed with the following commands:
      7 
      8 -----------------------------------------------------------------
      9 add-highlighter [-override] <path>/<name> <type> <parameters> ...
     10 -----------------------------------------------------------------
     11 
     12 and
     13 
     14 --------------------------------
     15 remove-highlighter <path>/<name>
     16 --------------------------------
     17 
     18 *path* is the name of a highlighter group, it is expressed as a */*
     19 separated path starting with a scope. Scopes are *global*, *buffer*,
     20 *window* and *shared*
     21 
     22 *name* is the name of the highlighter, if name is omitted in
     23 `add-highlighter` (the path ends with a `/`), it will be auto-generated
     24 from the remaining parameters.
     25 
     26 if `-override` is specified and the given name already exists, that
     27 highlighter is replaced with the new one.
     28 
     29 == Convenient highlighters
     30 
     31 *show-matching*::
     32     highlight matching char of the character under the selections' cursor
     33     using `MatchingChar` face, with the following *options*:
     34 
     35     *-previous*:::
     36         fall back to the character before the cursor when the cursor is not
     37         over a matching char
     38 
     39 *show-whitespaces* [options]::
     40     display symbols on top of whitespaces to make them more explicit
     41     using the `Whitespace` face, with the following *options*:
     42 
     43     *-lf* <separator>:::
     44         a one character long separator that will replace line feeds,
     45         or an empty string to ignore them.
     46 
     47     *-spc* <separator>:::
     48         a one character long separator that will replace spaces,
     49         or an empty string to ignore them.
     50 
     51     *-nbsp* <separator>:::
     52         a one character long separator that will replace non-breakable spaces,
     53         or an empty string to ignore them.
     54 
     55     *-tab* <separator>:::
     56         a one character long separator that will replace tabulations,
     57         or an empty string to ignore them.
     58 
     59     *-tabpad* <separator>:::
     60         a one character long separator that will be appended to tabulations to honor the *tabstop* option
     61 
     62     *-indent* <separator>:::
     63         a one character long separator that will replace the first space in indentation 
     64         according to the *indentwidth* option, or an empty string to ignore them.
     65         This will use the `WhitespaceIndent` face.
     66 
     67     *-only-trailing*:::
     68         only highlight whitespaces at the end of the line
     69 
     70 *number-lines* [options]::
     71     show line numbers using the `LineNumbers`, `LineNumberCursor` and `LineNumbersWrapped` faces,
     72     with the following *options*: 
     73 
     74     *-relative*:::
     75         show line numbers relative to the main cursor line
     76 
     77     *-full-relative*:::
     78         same as relative but show main cursor line as 0
     79 
     80     *-hlcursor*:::
     81         highlight the cursor line with a separate face
     82 
     83     *-separator* <separator text>:::
     84         specify a string to separate the line numbers column from
     85         the rest of the buffer (default is '|')
     86 
     87     *-cursor-separator* <separator text>:::
     88         identical to *-separator* but applies only to the line of the cursor
     89         (default is the same value passed to *-separator*)
     90 
     91     *-min-digits* <num>:::
     92         always reserve room for at least *num* digits,
     93         so text doesn't jump around as lines are added or removed
     94         (default is 2)
     95 
     96 *wrap* [options]::
     97     soft wrap buffer text at window width, with the following *options*:
     98 
     99     *-word*:::
    100         wrap at word boundaries instead of codepoint boundaries.
    101 
    102     *-indent*:::
    103         preserve line indent when wrapping.
    104 
    105     *-width <max_width>*:::
    106         wrap text at *max_width* if the window is wider.
    107 
    108     *-marker <marker_text>*:::
    109         prefix wrapped lines with *marker_text*; if *-indent* was given,
    110         the marker_text is displayed into the indentation if possible.
    111 
    112 == General highlighters
    113 
    114 *fill* <face>::
    115     fill using the given *face*, mostly useful with regions highlighters
    116 
    117 *column* <number> <face> [options]::
    118     highlight column *number* with face *face*, with the following *options*:
    119 
    120     *-ruler* <character>:::
    121         a single character to display instead of empty or whitespace cells at
    122         column *number*. If this option is provided, *face* will also not
    123         apply to non-empty cells, and will only apply to *character*.
    124 
    125 *line* <number> <face>::
    126     highlight line *number* with face *face*
    127 
    128 *regex* <regex> <capture_id>:<face> ...::
    129     highlight a regex, takes the regex as first parameter, followed by
    130     any number of face parameters.
    131     This highlights C++ style comments in cyan, with an eventual 'TODO:'
    132     in yellow on red background:
    133 
    134 -----------------------------------------------------------------
    135 add-highlighter window/ regex //\h*(TODO:)\N* 0:cyan 1:yellow,red
    136 -----------------------------------------------------------------
    137 
    138     capture_id can be either the capture number, or its name if a
    139     named capture is used in the regex (See
    140     <<regex#groups, `:doc regex groups`>>)
    141 
    142 *dynregex* <expression> <capture_id>:<face> ...::
    143     similar to regex, but expand (like a command parameter would) the
    144     given expression before building a regex from the result.
    145     This highlights all the current search matches in italic:
    146 
    147 -----------------------------------------------
    148 add-highlighter window/ dynregex '%reg{/}' 0:+i
    149 -----------------------------------------------
    150 
    151 == Specs highlighters
    152 
    153 The following highlighters are useful to add indicators like lint warnings,
    154 git blame output or spelling mistakes.
    155 See <<options#types,`:doc options types`>> for the format of `line-specs`
    156 and `range-specs`.
    157 
    158 *flag-lines* <face> <option_name>::
    159     add columns in front of the buffer, and display the flags specified
    160     in `line-specs` option, using <face>.
    161     In this example two words will be added in the gutter: a blue Foo at
    162     line 1 and a bold red/yellow Bar on line 3:
    163 
    164 ------------------------------------------------------------------------
    165 declare-option line-specs my_flags
    166 set-option window my_flags %val{timestamp} '1|Foo' '3|{red,yellow+b}Bar'
    167 add-highlighter window/ flag-lines blue my_flags
    168 ------------------------------------------------------------------------
    169 
    170 *ranges* <option_name>::
    171     use the data in the `range-specs` option of the given name to highlight
    172     the buffer. The string part of each tuple of the range-specs is
    173     interpreted as a *face* to apply to the range.
    174     In this example the 3 first chars of the buffer will be colored in red:
    175 
    176 --------------------------------------------------------
    177 declare-option range-specs my_range
    178 set-option window my_range %val{timestamp} '1.1,1.3|red'
    179 add-highlighter window/ ranges my_range
    180 --------------------------------------------------------
    181 
    182 *replace-ranges* <option_name>::
    183     use the data in the `range-specs` option of the given name to highlight
    184     the buffer. The string part of each tuple of the range-specs is
    185     interpreted as markup string (see <<faces#markup-strings,
    186     `:doc faces markup-strings`>>) and displayed in place of the range.
    187     Here, the 3 first chars of the buffer will be replaced by the word 'red':
    188 
    189 --------------------------------------------------------
    190 declare-option range-specs my_range
    191 set-option window my_range %val{timestamp} '1.1,1.3|red'
    192 add-highlighter window/ replace-ranges my_range
    193 --------------------------------------------------------
    194 
    195 == Highlighting Groups
    196 
    197 The *group* highlighter is a container for other highlighters. A subgroup
    198 can be added to an existing group or scope using:
    199 
    200 -----------------------------------
    201 add-highlighter <path>/<name> group 
    202 -----------------------------------
    203 
    204 Other highlighters can then be added to that group
    205 
    206 ------------------------------------------------
    207 add-highlighter <path>/<name> <type> <params>...
    208 ------------------------------------------------
    209 
    210 In order to specify which kinds of highlighters can be added to a
    211 given group, the *-passes* flag set can be passed along with the group
    212 name. Possible values for this option can be one or several (separated
    213 with a pipe sign) of *colorize*, *move*, *wrap* or *replace*
    214 (default: *colorize*):
    215 
    216 ----------------------------------------------------------------------
    217 add-highlighter window/<name> group -passes colorize|move|wrap|replace
    218 ----------------------------------------------------------------------
    219 
    220 == Regions highlighters
    221 
    222 A special highlighter provides a way to segment the buffer into regions,
    223 which are to be highlighted differently.
    224 
    225 -------------------------------------
    226 add-highlighter <path>/<name> regions
    227 -------------------------------------
    228 
    229 Individual region definitions can then be added to that highlighter
    230 
    231 ----------------------------------------------------
    232 add-highlighter <path>/<name>/<region_name> region \
    233     [-match-capture] [-recurse <recurse>]          \
    234     <opening> <closing> <type> <params>...
    235 ----------------------------------------------------
    236 
    237 *opening*::
    238     regex that defines the region start text
    239 
    240 *closing*::
    241     regex that defines the region end text
    242 
    243 *recurse*::
    244     regex that defines the text that matches recursively an end token
    245     into the region, every match of *recurse* will consume a following
    246     match of *closing* regex, preventing it from closing the region.
    247 
    248 *type* and *params*::
    249     A highlighter type, and associated params, as they would be passed
    250     to `add-highlighter` if they were not applied as a region.
    251 
    252 If the *-match-capture* switch is passed, then region *closing* and *recurse*
    253 regex matches are considered valid for a given region opening match only if they
    254 matched the same content for the capture 1 in the *opening* regex.
    255 
    256 The *recurse* option is useful for regions that can be nested, for example
    257 the following construct:
    258 
    259 ----------
    260 %sh{ ... }
    261 ----------
    262 
    263 accepts nested braces scopes ('{ ... }') so the following string is valid:
    264 
    265 ----------------------
    266 %sh{ ... { ... } ... }
    267 ----------------------
    268 
    269 This region can be defined with:
    270 
    271 ---------------------------------
    272 shell_expand -recurse \{ %sh\{ \}
    273 ---------------------------------
    274 
    275 Regions are matched using the left-most rule: the left-most region opening
    276 starts a new region. When a region closes, the closest next opening start
    277 another region.
    278 
    279 That matches the rule governing most programming language parsing.
    280 
    281 A default region, that will apply its given highlighter to the segments of the
    282 buffer that are not in any defined region, can be added with the *default-region*
    283 highlighter type.
    284 
    285 -----------------------------------------------------------------------------
    286 add-highlighter <path>/<name>/<region_name> default-region <type> <params>...
    287 -----------------------------------------------------------------------------
    288 
    289 Most programming languages can then be properly highlighted using a region
    290 highlighter as root:
    291 
    292 -----------------------------------------------------------------
    293 add-highlighter <path>/<lang> regions
    294 add-highlighter <path>/<lang>/string region '"' '"' fill string
    295 add-highlighter <path>/<lang>/comment region '//' '$' fill comment
    296 add-highlighter <path>/<lang>/code default-region group
    297 add-highlighter <path>/<lang>/code/variable regex ...
    298 add-highlighter <path>/<lang>/code/function regex ...
    299 -----------------------------------------------------------------
    300 
    301 == Shared Highlighters
    302 
    303 Highlighters are often defined for a specific filetype, and it makes then
    304 sense to share the highlighters between all the windows on the same filetypes.
    305 
    306 Highlighters can be put in the shared scope in order to make them reusable.
    307 
    308 ---------------------------------
    309 add-highlighter shared/<name> ...
    310 ---------------------------------
    311 
    312 The common case would be to create a named shared group, or regions and then
    313 fill it with highlighters:
    314 
    315 ---------------------------------------
    316 add-highlighter shared/<name> group
    317 add-highlighter shared/<name>/ regex ...
    318 ---------------------------------------
    319 
    320 It can then be referenced in a window using the ref highlighter.
    321 
    322 ----------------------------------
    323 add-highlighter window/ ref <name>
    324 ----------------------------------
    325 
    326 The ref can reference any named highlighter in the shared scope.
    327 
    328 Like the group highlighter, ref accepts a *-passes* flag set selecting the
    329 kinds of highlighters that are forwarded (default: *colorize*). A shared
    330 highlighter running in another pass, such as *replace-ranges*, needs the
    331 matching pass to be listed explicitly:
    332 
    333 ---------------------------------------------------------
    334 add-highlighter shared/<name> replace-ranges <option_name>
    335 add-highlighter window/ ref -passes replace <name>
    336 ---------------------------------------------------------