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 ---------------------------------------------------------