KAKOUNE(1) ========== 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 //(\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 *show_whitespaces*:: display symbols on top of whitespaces to make them more explicit using the Whitespace 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 ---------------------------- 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>... ---------------------------------------------------------- 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 regions highlighter 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. Most programming languages can then be properly highlighted using a regions 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.