xenia/kakoune
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update highlighters.asciidoc page to reflect the new syntax

Browse Source
This commit is contained in:
Maxime Coste 2018-06-28 20:48:53 +10:00
parent 64d0fd91ae
commit 7976f8289e
1 changed files with 63 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

124
doc/pages/highlighters.asciidoc
View File

@ -5,24 +5,23 @@
Manipulation of the displayed text is done through highlighters, which can Manipulation of the displayed text is done through highlighters, which can
be added or removed with the following commands: be added or removed with the following commands:
---------------------------------------------------------------------- -----------------------------------------------------
add-highlighter <path> <highlighter_name> <highlighter_parameters> ... add-highlighter <path>/<name> <type> <parameters> ...
---------------------------------------------------------------------- -----------------------------------------------------
and and
------------------------------------------ --------------------------------
remove-highlighter <path>/<highlighter_id> remove-highlighter <path>/<name>
------------------------------------------ --------------------------------
*path* is the name of an highlighter group, it is expressed as a */* *path* is the name of an highlighter group, it is expressed as a */*
separated path starting with a scope. Scopes are *global*, *buffer*, separated path starting with a scope. Scopes are *global*, *buffer*,
*window* and *shared* *window* and *shared*
*highlighter_id* is a name generated by the highlighter specified with *name* is the name of the highlighter, if name is omitted in
*highlighter_name*, possibly dependent on the parameters. Use command `add-highlighter` (the path ends with a `/`), it will be auto-generated
completion in a prompt on the *remove-highlighter* command to see the from the remaining parameters.
existing highlighters ids.
== Convenient highlighters == Convenient highlighters
@ -96,18 +95,18 @@ existing highlighters ids.
This highlights C++ style comments in cyan, with an eventual 'TODO:' This highlights C++ style comments in cyan, with an eventual 'TODO:'
in yellow on red background: in yellow on red background:
------------------------------------------------------------------- --------------------------------------------------------------------
add-highlighter window regex //\h*(TODO:)[^\n]* 0:cyan 1:yellow,red add-highlighter window/ regex //\h*(TODO:)[^\n]* 0:cyan 1:yellow,red
------------------------------------------------------------------- --------------------------------------------------------------------
*dynregex* <expression> <capture_id>:<face> ...:: *dynregex* <expression> <capture_id>:<face> ...::
similar to regex, but expand (like a command parameter would) the similar to regex, but expand (like a command parameter would) the
given expression before building a regex from the result. given expression before building a regex from the result.
This highlights all the current search matches in italic: This highlights all the current search matches in italic:
---------------------------------------------- -----------------------------------------------
add-highlighter window dynregex '%reg{/}' 0:+i add-highlighter window/ dynregex '%reg{/}' 0:+i
---------------------------------------------- -----------------------------------------------
== Specs highlighters == Specs highlighters
@ -158,21 +157,22 @@ The *group* highlighter is a container for other highlighters. A subgroup
can be added to an existing group or scope using: can be added to an existing group or scope using:
----------------------------------- -----------------------------------
add-highlighter <path> group <name> add-highlighter <path>/<name> group
----------------------------------- -----------------------------------
That group is then accessible using the *<path>/<name>* path Other highlighters can then be added to that group
------------------------------------------------ ------------------------------------------------
add-highlighter <path>/<name> <type> <params>... add-highlighter <path>/<name> <type> <params>...
------------------------------------------------ ------------------------------------------------
In order to specify which kinds of highlighters can be added to a given group, the *-passes* In order to specify which kinds of highlighters can be added to a
flag set can be passed along with the group name. Possible values for this option can be one given group, the *-passes* flag set can be passed along with the group
or several (separated with a pipe sign) of *colorize*, *move* or *wrap* (default: *colorize*): name. Possible values for this option can be one or several (separated
with a pipe sign) of *colorize*, *move* or *wrap* (default: *colorize*):
-------------------------------------------------------------- --------------------------------------------------------------
add-highlighter window group -passes colorize|move|wrap <name> add-highlighter window/<name> group -passes colorize|move|wrap
-------------------------------------------------------------- --------------------------------------------------------------
== Regions highlighters == Regions highlighters
@ -180,16 +180,35 @@ add-highlighter window group -passes colorize|move|wrap <name>
A special highlighter provides a way to segment the buffer into regions, A special highlighter provides a way to segment the buffer into regions,
which are to be highlighted differently. which are to be highlighted differently.
*name*:: -------------------------------------
user defined, used to identify the region add-highlighter <path>/<name> regions
-------------------------------------
Individual region definitions can then be added to that highlighter
----------------------------------------------------
add-highlighter <path>/<name>/<region_name> region \
<opening> <closing> <recurse> <type> <params>...
----------------------------------------------------
*opening*:: *opening*::
regex that defines the region start text regex that defines the region start text
*closing*:: *closing*::
regex that defines the region end text regex that defines the region end text
*recurse*:: *recurse*::
regex that defines the text that matches recursively an end token regex that defines the text that matches recursively an end token
into the region into the region
*type* and *params*::
An highlighter type, and associated params, as they would be passed
to `add-highlighter` if they were not applied as a region.
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.
The *recurse* option is useful for regions that can be nested, for example The *recurse* option is useful for regions that can be nested, for example
the following contruct: the following contruct:
@ -209,47 +228,30 @@ This region can be defined with:
shell_expand %sh\{ \} \{ shell_expand %sh\{ \} \{
------------------------ ------------------------
Regions are used in the region highlighters which can take any number
of regions.
The following command:
------------------------------------------------------
add-highlighter <path> 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 <path>/<name>/<region_name> ...
-----------------------------------------------
Regions are matched using the left-most rule: the left-most region opening 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 starts a new region. When a region closes, the closest next opening start
another region. another region.
That matches the rule governing most programming language parsing. That matches the rule governing most programming language parsing.
Regions also supports a *-default <default_region>* switch to define the A default region, that will apply its given highlighter for segments of the
default region, when no other region matches the current buffer range. buffer that are not in any defined region, can be added with the *default-region*
highlighter type.
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 add-highlighter <path>/<name>/<region_name> default-region <type> <params>...
matched the same content for the capture 1. -----------------------------------------------------------------------------
Most programming languages can then be properly highlighted using a region Most programming languages can then be properly highlighted using a region
highlighter as root: highlighter as root:
----------------------------------------------------------------- -----------------------------------------------------------------
add-highlighter <path> regions -default code <lang> \ add-highlighter <path>/<lang> regions
string <str_opening> <str_closing> <str_recurse> \ add-highlighter <path>/<lang>/string '"' '"' '' fill string
comment <comment_opening> <comment_closing> <comment_recurse> add-highlighter <path>/<lang>/comment '//' '$' '' fill comment
add-highlighter <path>/<lang>/code default-region group
add-highlighter <path>/<lang>/code ... add-highlighter <path>/<lang>/code/variable regex ...
add-highlighter <path>/<lang>/string ... add-highlighter <path>/<lang>/code/function regex ...
add-highlighter <path>/<lang>/comment ...
----------------------------------------------------------------- -----------------------------------------------------------------
== Shared Highlighters == Shared Highlighters
@ -259,12 +261,12 @@ sense to share the highlighters between all the windows on the same filetypes.
Highlighters can be put in the shared scope in order to make them reusable. Highlighters can be put in the shared scope in order to make them reusable.
--------------------------------------- ---------------------------------
add-highlighter shared/<group_name> ... add-highlighter shared/<name> ...
--------------------------------------- ---------------------------------
The common case would be to create a named shared group, and then fill it The common case would be to create a named shared group, or regions and then
with highlighters: fill it with highlighters:
--------------------------------------- ---------------------------------------
add-highlighter shared/ group <name> add-highlighter shared/ group <name>
@ -273,8 +275,8 @@ add-highlighter shared/<name> regex ...
It can then be referenced in a window using the ref highlighter. It can then be referenced in a window using the ref highlighter.
--------------------------------- ----------------------------------
add-highlighter window ref <name> add-highlighter window/ ref <name>
--------------------------------- ----------------------------------
The ref can reference any named highlighter in the shared scope. The ref can reference any named highlighter in the shared scope.