1f02a1f7e2
Except for the FAQ, it could be fixed, but it does not have to be as formal as the rest of the docs.
242 lines
7.9 KiB
Plaintext
242 lines
7.9 KiB
Plaintext
= Highlighters
|
|
|
|
== Description
|
|
|
|
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> ...
|
|
----------------------------------------------------------------------
|
|
|
|
and
|
|
|
|
------------------------------------------
|
|
remove-highlighter <path>/<highlighter_id>
|
|
------------------------------------------
|
|
|
|
*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.
|
|
|
|
== 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 window regex //\h*(TODO:)[^\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* <face> <option_name>::
|
|
add a column in front of the buffer, and display the flags specified
|
|
in <option_name>, using <face>
|
|
|
|
*show_matching*::
|
|
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>:::
|
|
specify a string to separate the line numbers column with
|
|
the rest of the buffer (default is '|')
|
|
|
|
*wrap* [options]::
|
|
soft wrap buffer text at window width, with the following *options*:
|
|
|
|
*-word*:::
|
|
wrap at word boundaries instead of codepoint boundaries.
|
|
|
|
*-indent*:::
|
|
preserve line indent when wrapping.
|
|
|
|
*-width <max_width>*:::
|
|
wrap text at *max_width* if the window is wider.
|
|
|
|
*fill* <face>::
|
|
fill using the given *face*, mostly useful with regions highlighters
|
|
|
|
*ranges* <option_name>::
|
|
use the data in the range-specs option of the given name to highlight
|
|
the buffer. The string part of the is interpretted as a face to apply
|
|
to the range.
|
|
|
|
*replace-ranges* <option_name>::
|
|
use the data in the range-specs option of the given name to highlight
|
|
the buffer. The string part of the is interpretted as a display line to
|
|
display in place of the range.
|
|
|
|
*column* <number> <face>::
|
|
highlight column *number* with face *face*
|
|
|
|
*line* <number> <face>::
|
|
highlight line *number* with face *face*
|
|
|
|
== Highlighting Groups
|
|
|
|
|
|
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>
|
|
-----------------------------------
|
|
|
|
That group is then accessible using the *<path>/<name>* path
|
|
|
|
------------------------------------------------
|
|
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*):
|
|
|
|
--------------------------------------------------------------
|
|
add-highlighter window group -passes colorize|move|wrap <name>
|
|
--------------------------------------------------------------
|
|
|
|
== 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 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.
|
|
|
|
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.
|
|
|
|
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 ...
|
|
-----------------------------------------------------------------
|
|
|
|
== 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.
|
|
|
|
Highlighters can be put in the shared scope in order to make them reusable.
|
|
|
|
---------------------------------------
|
|
add-highlighter shared/<group_name> ...
|
|
---------------------------------------
|
|
|
|
The common case would be to create a named shared group, and then fill it
|
|
with highlighters:
|
|
|
|
---------------------------------------
|
|
add-highlighter shared/ group <name>
|
|
add-highlighter shared/<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 scope.
|