281 lines
9.8 KiB
Plaintext
281 lines
9.8 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.
|
|
|
|
== Convenient highlighters
|
|
|
|
*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 using the `LineNumbers`, `LineNumberCursor` and `LineNumbersWrapped` faces,
|
|
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.
|
|
|
|
*-marker <marker_text>*:::
|
|
prefix wrapped lines with *marker_text*; if *-indent* was given,
|
|
the marker_text is displayed into the indentation if possible.
|
|
|
|
== General highlighters
|
|
|
|
*fill* <face>::
|
|
fill using the given *face*, mostly useful with regions highlighters
|
|
|
|
*column* <number> <face>::
|
|
highlight column *number* with face *face*
|
|
|
|
*line* <number> <face>::
|
|
highlight line *number* with face *face*
|
|
|
|
*regex* <regex> <capture_id>:<face> ...::
|
|
highlight a regex, takes the regex as first parameter, followed by
|
|
any number of face parameters.
|
|
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
|
|
-------------------------------------------------------------------
|
|
|
|
*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
|
|
---------------------------------------------
|
|
|
|
== Specs highlighters
|
|
|
|
The following highlighters are useful to add indicators like lint warnings,
|
|
git blame output or spelling typos.
|
|
See <<options#types,`:doc options types`>> for the format of `line-specs`
|
|
and `range-specs`.
|
|
|
|
*flag_lines* <face> <option_name>::
|
|
add columns in front of the buffer, and display the flags specified
|
|
in `line-specs` option, using <face>.
|
|
In this example two words will be added in the gutter: a blue Foo at
|
|
line 1 and a bold red/yellow Bar on line 3:
|
|
|
|
----------------------------------------------------------------------
|
|
declare-option line-specs my_flags
|
|
set-option window my_flags "%val{timestamp}:1|Foo:3|{red,yellow+b}Bar"
|
|
add-highlighter window/ flag_lines blue my_flags
|
|
----------------------------------------------------------------------
|
|
|
|
*ranges* <option_name>::
|
|
use the data in the `range-specs` option of the given name to highlight
|
|
the buffer. The string part of each tuple of the range-specs is
|
|
interpreted as a *face* to apply to the range.
|
|
In this example the 3 first chars of the buffer will be colored in red:
|
|
|
|
--------------------------------------------------------
|
|
declare-option range-specs my_range
|
|
set-option window my_range "%val{timestamp}:1.1,1.3|red"
|
|
add-highlighter window/ ranges my_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 each tuple of the range-specs is
|
|
interpreted as a *display line* to display in place of the range.
|
|
Here, the 3 first chars of the buffer will be replaced by the word 'red':
|
|
|
|
--------------------------------------------------------
|
|
declare-option range-specs my_range
|
|
set-option window my_range "%val{timestamp}:1.1,1.3|red"
|
|
add-highlighter window/ replace-ranges my_range
|
|
--------------------------------------------------------
|
|
|
|
== 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 window ref <name>
|
|
---------------------------------
|
|
|
|
The ref can reference any named highlighter in the shared scope.
|