The [modeColoring] command.

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? ?-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
-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:
Clear0
Italic1
Bold2
Underline4
Strikethrough8

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



Last updated 2017-02-18 11:21:20