Update highlighters.asciidoc page to reflect the new syntax
This commit is contained in:
Maxime Coste
parent
64d0fd91ae
commit
7976f8289e
|
|
@ -5,24 +5,23 @@
|
|||
Manipulation of the displayed text is done through highlighters, which can
|
||||
be added or removed with the following commands:
|
||||
|
||||
----------------------------------------------------------------------
|
||||
add-highlighter <path> <highlighter_name> <highlighter_parameters> ...
|
||||
----------------------------------------------------------------------
|
||||
-----------------------------------------------------
|
||||
add-highlighter <path>/<name> <type> <parameters> ...
|
||||
-----------------------------------------------------
|
||||
|
||||
and
|
||||
|
||||
------------------------------------------
|
||||
remove-highlighter <path>/<highlighter_id>
|
||||
------------------------------------------
|
||||
--------------------------------
|
||||
remove-highlighter <path>/<name>
|
||||
--------------------------------
|
||||
|
||||
*path* is the name of an highlighter group, it is expressed as a */*
|
||||
separated path starting with a scope. Scopes are *global*, *buffer*,
|
||||
*window* and *shared*
|
||||
|
||||
*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.
|
||||
*name* is the name of the highlighter, if name is omitted in
|
||||
`add-highlighter` (the path ends with a `/`), it will be auto-generated
|
||||
from the remaining parameters.
|
||||
|
||||
== Convenient highlighters
|
||||
|
||||
|
|
@ -96,18 +95,18 @@ existing highlighters ids.
|
|||
This highlights C++ style comments in cyan, with an eventual 'TODO:'
|
||||
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> ...::
|
||||
similar to regex, but expand (like a command parameter would) the
|
||||
given expression before building a regex from the result.
|
||||
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
|
||||
|
||||
|
|
@ -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:
|
||||
|
||||
-----------------------------------
|
||||
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>...
|
||||
------------------------------------------------
|
||||
|
||||
In order to specify which kinds of highlighters can be added to a given group, the *-passes*
|
||||
flag set can be passed along with the group name. Possible values for this option can be one
|
||||
or several (separated with a pipe sign) of *colorize*, *move* or *wrap* (default: *colorize*):
|
||||
In order to specify which kinds of highlighters can be added to a
|
||||
given group, the *-passes* flag set can be passed along with the group
|
||||
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
|
||||
|
|
@ -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,
|
||||
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*::
|
||||
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
|
||||
|
||||
*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 following contruct:
|
||||
|
||||
|
|
@ -209,47 +228,30 @@ This region can be defined with:
|
|||
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
|
||||
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.
|
||||
A default region, that will apply its given highlighter for segments of the
|
||||
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
|
||||
matched the same content for the capture 1.
|
||||
-----------------------------------------------------------------------------
|
||||
add-highlighter <path>/<name>/<region_name> default-region <type> <params>...
|
||||
-----------------------------------------------------------------------------
|
||||
|
||||
Most programming languages can then be properly highlighted using a region
|
||||
highlighter as root:
|
||||
|
||||
-----------------------------------------------------------------
|
||||
add-highlighter <path> regions -default code <lang> \
|
||||
string <str_opening> <str_closing> <str_recurse> \
|
||||
comment <comment_opening> <comment_closing> <comment_recurse>
|
||||
|
||||
add-highlighter <path>/<lang>/code ...
|
||||
add-highlighter <path>/<lang>/string ...
|
||||
add-highlighter <path>/<lang>/comment ...
|
||||
add-highlighter <path>/<lang> regions
|
||||
add-highlighter <path>/<lang>/string '"' '"' '' fill string
|
||||
add-highlighter <path>/<lang>/comment '//' '$' '' fill comment
|
||||
add-highlighter <path>/<lang>/code default-region group
|
||||
add-highlighter <path>/<lang>/code/variable regex ...
|
||||
add-highlighter <path>/<lang>/code/function regex ...
|
||||
-----------------------------------------------------------------
|
||||
|
||||
== 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.
|
||||
|
||||
---------------------------------------
|
||||
add-highlighter shared/<group_name> ...
|
||||
---------------------------------------
|
||||
---------------------------------
|
||||
add-highlighter shared/<name> ...
|
||||
---------------------------------
|
||||
|
||||
The common case would be to create a named shared group, and then fill it
|
||||
with highlighters:
|
||||
The common case would be to create a named shared group, or regions and then
|
||||
fill it with highlighters:
|
||||
|
||||
---------------------------------------
|
||||
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.
|
||||
|
||||
---------------------------------
|
||||
add-highlighter window ref <name>
|
||||
---------------------------------
|
||||
----------------------------------
|
||||
add-highlighter window/ ref <name>
|
||||
----------------------------------
|
||||
|
||||
The ref can reference any named highlighter in the shared scope.
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user