The [modeColoring] command.
Examples
Introduction
The modeColoring command lets you manipulate syntax coloring schemes.
Each mode can define different coloring schemes which indicate how syntax
coloring should be performed by Alpha. Each scheme corresponds to a
particular aspect of syntax coloring: it specifies for instance which color
to use for language-specific keywords, for comments, for quoted strings,
etc.
When the coloring engine applies the coloring schemes defined for a
particular mode, it may be in three different states: plain, string or comment. The string and comment
states are set when the engine is respectively inside a string or inside a comment. Otherwise, the engine is in
plain state. In that case, coloring is executed by applying the
currently defined schemes in the following order:
Synopsis
The formal syntax of the [modeColoring] command is:
| modeColoring subcommand ?options? |
The possible subcommands are described below. Depending on the
subcommand, some options may be specified. A double slash -- always
indicates the end of the options.
Mode coloring subcommands
The [list] subcommand
This subcommand returns existing coloring schemes. The
complete syntax is:
modeColoring list mode
The returned value is a list of tokens corresponding to the schemes
declared for the mode specified in the mode argument.
The [modes] subcommand
This subcommand returns a list of all the modes for which syntax coloring
schemes have been defined. The complete syntax is:
modeColoring modes
This is useful mainly for debugging.
The [register] subcommand
This subcommand declares a coloring scheme for a given mode. The complete syntax is:
modeColoring register type mode color ?options? ?items?
The mode argument specifies the mode the coloring scheme applies to.
Each mode can have any number of coloring schemes. The color
argument specifies the color attached to this scheme: the value is a color
token obtained from the [colorRef] command.
The type argument specifies which kind of scheme is
declared: there are several types of coloring schemes and the options and items arguments have a different meaning depending on the
type. The available types are: comment, keywords, regexp, string,
symbol. The sections below give a description of all the types with
their exact syntax.
The command returns a token which uniquely
identifies the coloring scheme and can be used with other subcommands (like
unregister and set).
Keywords
The keywords type is used to declare a list of mode-specific keywords.
The syntax is:
modeColoring register keywords mode color ?-nocase? ?-anchored? ?-word regex? ?-style num? ?--? list
The -nocase option specifies that
the keywords are case insensitive (by default, they are case sensitive).
The -word option
specifies a regular expression to describe what is considered a word. The
coloring engine tokenizes the text based on this definition of a word,
then it looks if each "word" is present in the corresponding keywords list.
By default, a word is an alphanumeric string (made of letters, digits and
the underscore).
The -anchored
option concerns the regular expression provided with a -word option (if any): it allows
^ and $ to match the start and end of lines. It there is
no -word option or if
the regular expression does not contain the ^ and/or $
metacharacters, then the -anchored option has no effect.
The -style
option is numeric value describing a style. By default, it is set to -1,
which means that it is undefined. You may set it to a combination of the
following values:
| Clear | 0 |
| Italic | 1 |
| Bold | 2 |
| Underline | 4 |
| Strikethrough | 8 |
Comments
The comment type is used to declare mode-specific comment
characters.
The syntax is:
modeColoring register comment mode color ?-anchored? ?--? {beg ?end?}
Many languages support single line or multiline comments. If
the last argument of this command is a single element, it designates a
single line comment symbol: anything after this symbol up to the end of the
line is considered a comment. If the last argument is a two-elements list,
it designates the starting and ending symbols delimiting a (possibly
multiline) comment block.
The -anchored option concerns single line comments and
specifies that the comment symbol must be at the beginning of a line.
Strings
The string type is used to declare a color for strings.
The syntax is:
modeColoring register string mode color ?-nospan? ?--? ?{beg ?end?}?
By default, a string is enclosed in double quotes: the optional last
argument can be used to specify another symbol (like a single quote '
for instance) or a pair of symbols if the opening symbol is different from
the closing one (for instance a pair “ ”).
By default, the coloring mechanism supports strings that span
multiple lines but, if the -nospan option is specified, then it will stop at the end of the
current line if no closing symbol was found and will not propagate coloring
to the next ones.
Regular Expressions
The regexp type is used to declare a regular expression. Any
string matching this regular expression inside a plain text section will be
colored with the specified color.
The syntax is:
modeColoring register regexp mode color ?-nocase? ?-anchored? ?-style num? ?--? expr
This coloring scheme does not apply inside a quoted string or a comment.
The -nocase option
specifies that matching with the regular expression is independent of case.
The -anchored option
concerns regular expressions containing a ^ or a $ anchor.
It allows ^ and $ to match the start and end of lines.
For more information about the regular expressions syntax, see the
file Regular Expressions.
The -style option
has the same meaning than with the modeColoring register keywords command. See the possible values in this table.
Sub patterns
If the regular expression contains a pair of parentheses (usually
acting as a capture group), only the parts of the matches corresponding to
the first capturing group are colored. For instance, if the regular
expression is <(\w+)> (in order to find words enclosed in a pair of
chevrons), only the enclosed word will be colored, not the chevrons. On the
contrary, if the expression was specified as <\w+> (that is to say
without the parentheses), then the chevrons would be colored too.
On the contrary, if you do not want the previous convention to
apply, you can use non capturing parentheses (?: ). For instance,
if you want to colorize the strings oo::class, oo::define
and oo::object, you must specify the regular expression as
oo::(?:class|define|object) (note the ?: after the opening
parenthesis). If you were using just oo::(class|define|object), then only
the words class, define and object inside the
matches would be colored.
Symbols
The symbol type is used to declare a special character (like curly
braces, dollar signs, etc.) to display in a different color. The syntax is:
modeColoring register symbol mode color ?-style num? ?--? symb
The -style option
has the same meaning than with the modeColoring register keywords command.
The [set] subcommand
This subcommand is used to get information about a coloring scheme or to
modify some of its attributes. The complete syntax is:
modeColoring set token key ?value?
The token argument is the unique token (obtained via a previous
call to the [modeColoring register] subcommand) identifying the
coloring scheme. The key argument can be color, items, mode, style or type.
The mode, type and items keys are read-only
and return respectively the mode, the type and the items with which the
coloring scheme was declared. Their value cannot be altered with this
command.
The color key lets you get or set the color of the scheme:
its value is a color token (typically obtained with the [colorRef]
command).
The style key lets you specify a style. By default, this
option is set to -1. The possible values are found in this table. You would use the value 0 in order to
clear a text style attribute previously set to a positive value.
The [unregister] subcommand
This subcommand deletes an existing coloring scheme. The complete syntax is:
modeColoring unregister token
The coloring scheme is designated by its unique token. Once a coloring
scheme is unregistered, the token is not valid anymore and the scheme is
no longer applied by the syntax coloring engine.
Examples
Here are a few examples taken from the AlphaTcl library.
In TexC (TeX console) mode:
modeColoring register keywords TeXC [colors::named red] $TeXCKeyWords
modeColoring register comment TeXC [colors::named red] "!"
modeColoring register regexp TeXC [colors::named blue] {\\\w+}
In Clan mode:
modeColoring register regexp Clan [colors::named red] -anchored {^\*\w+:}
modeColoring register regexp Clan [colors::named green] -anchored {^%\w+:}
modeColoring register regexp Clan [colors::named blue] {\$\w+(?::\w+)+}
modeColoring register comment Clan [colors::named magenta] "@"
In Ada mode:
modeColoring register keywords Ada [colors::named blue] $adaKeyWords
modeColoring register comment Ada [colors::named red] "--"
foreach symb [list ")" "(" ":" ";" "," "."] {
modeColoring register symbol Ada [colors::named green] $symb
}
Last updated 2020-06-29 13:33:34