kakoune/doc/manpages/highlighters.asciidoc

226 lines
7.0 KiB
Plaintext
Raw Normal View History

KAKOUNE(1)
==========
NAME
----
highlighters - a
Description
-----------
2016-02-10 22:03:49 +01:00
Manipulation of the displayed text is done through highlighters, which can
be added or removed with the following commands:
2017-01-04 01:07:45 +01:00
---------------------------------------------------------------
add-highlighter <highlighter_name> <highlighter_parameters> ...
---------------------------------------------------------------
and
2017-01-04 01:07:45 +01:00
-----------------------------------
remove-highlighter <highlighter_id>
-----------------------------------
2016-02-10 22:03:49 +01:00
*highlighter_id* is a name generated by the highlighter specified with
*highlighter_name*, possibly dependent on the parameters. Use command
2017-01-04 01:07:45 +01:00
completion in a prompt on the *remove-highlighter* command to see the existing highlighters
2016-02-10 22:03:49 +01:00
ids.
General highlighters
--------------------
*regex* <ex> <capture_id>:<face> ...::
2016-02-10 22:03:49 +01:00
highlight a regex, takes the regex as first parameter, followed by
any number of face parameters. For example:
2017-01-04 01:07:45 +01:00
---------------------------------------------------------------
add-highlighter regex //(\hTODO:)?[^\n] 0:cyan 1:yellow,red
---------------------------------------------------------------
2016-02-10 22:03:49 +01:00
will highlight C++ style comments in cyan, with an eventual 'TODO:'
in yellow on red background
*dynregex*::
2016-04-08 18:00:24 +02:00
Similar to regex, but expand (like a command parameter would) the
2016-02-10 22:03:49 +01:00
given expression before building a regex from the result
*flag_lines* <flag> <option_name>::
2016-02-10 22:03:49 +01:00
add a column in front of text, and display the given flag in it for
2016-04-08 18:00:24 +02:00
every line contained in the int-list option named <option_name>
*show_matching*::
2016-02-10 22:03:49 +01:00
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>:::
2016-02-10 22:03:49 +01:00
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
-------------------
2016-02-10 22:03:49 +01:00
The group highlighter is a container for other highlighters. You can add a
group to the current window using
2017-01-04 01:07:45 +01:00
----------------------------
add-highlighter group <name>
----------------------------
2017-01-04 01:07:45 +01:00
The *-group* switch of the *add-highlighter* command provides a mean to add highlighters
2016-02-10 22:03:49 +01:00
inside this group:
2017-01-04 01:07:45 +01:00
------------------------------------------------
add-highlighter -group <name> <type> <params>...
------------------------------------------------
2016-02-10 22:03:49 +01:00
Groups can contain other groups, the *-group* switch can be used to define
a path as follows:
2017-01-04 01:07:45 +01:00
----------------------------------------------------------
add-highlighter -group <name> group <subname>
add-highlighter -group <name>/<subname> <type> <params>...
----------------------------------------------------------
Regions highlighters
--------------------
2016-02-10 22:03:49 +01:00
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*::
2016-02-10 22:03:49 +01:00
regex that defines the text that matches recursively an end token
into the region
2016-02-10 22:03:49 +01:00
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\{ \} \{
------------------------
2016-02-10 22:03:49 +01:00
Regions are used in the regions highlighter which can take any number
of regions.
The following command:
2017-01-04 01:07:45 +01:00
------------------------------------------------------------------------------
add-highlighter regions <name> <region_name1> <opening1> <closing1> <recurse1>
<region_name2> <opening2> <closing2> <recurse2>...
2017-01-04 01:07:45 +01:00
------------------------------------------------------------------------------
defines multiple regions in which other highlighters can be added as follows:
2017-01-04 01:07:45 +01:00
-----------------------------------------------
add-highlighter -group <name>/<region_name> ...
-----------------------------------------------
2016-02-10 22:03:49 +01:00
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.
2016-02-10 22:03:49 +01:00
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.
2016-02-10 22:03:49 +01:00
Most programming languages can then be properly highlighted using a regions
highlighter as root:
-----------------------------------------------------------------
2017-01-04 01:07:45 +01:00
add-highlighter regions -default code <lang> \
string <str_opening> <str_closing> <str_recurse> \
comment <comment_opening> <comment_closing> <comment_recurse>
2017-01-04 01:07:45 +01:00
add-highlighter -group <lang>/code ...
add-highlighter -group <lang>/string ...
add-highlighter -group <lang>/comment ...
-----------------------------------------------------------------
Shared Highlighters
-------------------
2016-02-10 22:03:49 +01:00
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:
2017-01-04 01:07:45 +01:00
----------------------------------------
add-highlighter -group /<group_name> ...
----------------------------------------
2016-02-10 22:03:49 +01:00
When the group switch values starts with a '/', it references a group in
the shared highlighters, rather than the window highlighters.
2016-02-10 22:03:49 +01:00
The common case would be to create a named shared group, and then fill it
with highlighters:
2017-01-04 01:07:45 +01:00
--------------------------------------
add-highlighter -group / group <name>
add-highlighter -group /name regex ...
--------------------------------------
It can then be referenced in a window using the ref highlighter.
2017-01-04 01:07:45 +01:00
--------------------------
add-highlighter ref <name>
--------------------------
The ref can reference any named highlighter in the shared namespace.