![]() |
![]() |
![]() |
GtkSourceView Reference Manual |
---|
Language Definition v2.0 ReferenceLanguage Definition v2.0 Reference — Reference to the GtkSourceView language definition file format |
This is an overview of the Language Definition XML format, describing the
meaning and usage of every element and attribute. The formal definition is
stored in the RelaxNG schema file language2.rng
which
should be installed on your system in the directory
${PREFIX}/share/gtksourceview-2.0/
(where
${PREFIX} can be /usr/
or
/usr/local/
if you have installed from source.
<language>
The root element for Language Definition files.
Contained elements:
<metadata>
(optional), <styles>
(optional), <default-regex-options>
(optional), <keyword-char-class>
(optional), <definitions>
(mandatory).
Attributes:
id (mandatory) |
Identifier for the description. This is used for
external references and must be unique among language descriptions. It can
contain a string of letters, digits, hyphens (" |
name (mandatory) |
The translatable name of the language presented to the user. It can be marked for translation putting an underscore before the attribute name (see the gettext documentation). |
version (mandatory) |
The version of the XML format (currently "2.0"). |
section (optional) |
The translatable category in which the language has to be grouped when presented to the user. It can be marked for translation putting an underscore before the attribute name. Currently used categories in GtkSourceView are "Sources", "Scripts", "Markup" and "Others", but it is possible to use arbitrary categories (while usually discouraged). |
hidden (optional) |
It's a hint that the language should be "hidden" from user. For instance, def.lang has this flag, and a text editor should not present "default" as a syntax highlighting choice. |
<metadata>
Contains optional metadata about the language definition.
Recognized elements are (all optional):
mimetypes
The semicolon-separated list of mimetypes associated to the language.
globs
The semicolon-separated list of globs associated to the language.
line-comment-start
String used to create single-line comment in files of this type, e.g. "#" in shell scripts. It may be used in an editor to implement Comment/Uncomment functionality.
block-comment-start
String used to start block comment in files of this type, e.g. "/*" in C files.
block-comment-end
String used to end block comment in files of this type, e.g. "*/" in C files.
<styles>
Contains the definitions of every style used in the current language and their association with predefined styles in GtkSourceView.
Contained elements:
<style>
(one or more).
<style>
Defines a style, associating it's id with a user visible translatable name and a default style.
Contained elements: none.
Attributes:
id (mandatory) |
Identifier for the style. This is used in the current language
to refer to this style and must be unique for the current document.
It can contain a string of letters, digits,
hyphens (" |
name (mandatory) |
The user visible translatable name for the style. It has to be preceded
with a underscore (" |
map-to (optional) |
Used to map the style with a default style, to use colors and font properties defined for those default styles. The id of the default style has to be preceded with the id of the language where it is defined, separated with a semicolon ":". When omitted the style is not considered derived from any style and will be not highlighted until the user specifies a color scheme for this style. |
<keyword-char-class>
Contains a regex character class used to redefine the customizable word boundary delimiters "\%[" and "\%]". This class is the set of character that can be commonly found in a keyword. If the element is omitted the two delimiters default to "\b".
Contained elements: none.
<default-regex-options>
A string that will set the default regular expression options. Avaliable options are:
i
: case insensitive;
x
: extended (spaces are ignored and it is possible to
put comments starting with "#
" and ending at the end of the
line);
s
: the metacharacter ".
" matches the "\n
".
Those options can be overridden in every regular espression using the
/regex/options
syntax: to disable a group of enabled options,
put an hyphen brefore them (e.g. /[A-Z][a-z]*/-i
matches are
case sensitive even if the default is to ignore case differencies).
Contained elements: none.
<definitions>
The element containing the real description of the syntax to be
highlighted. It contains one or more <context>
element and an
arbitrary number of <define-regex>
elements, interleaved.
It has no attributes.
Every contained element must have its id
attribute set to an
identifier unique for the document. Exactly one of the contained
<context>
element must have
the id
attribute set to the id
of the
<language>
root element,
representing the initial context for the highlighting, the one the engine
enters at the beginning of the highlighted file.
Contained elements:
<context>
(one or more), <define-regex>
(zero or more).
<define-regex>
Defines a regular expression that can be reused inside other regular
expression, to avoid replicating common portions. Those regular
expressions are PCRE regular expressions in the form /regex/options
(see
the documentation of PCRE for details). If there are no options to be
specified and you don't need to match the spaces at the start and at the
end of the regular expression, you can omit the slashes, putting here only
regex
. The possible options are those specified above in the description
of the <default-regex-options>
element. To disable a group of
options, instead, you have to prepend an hyphen -
to them. In
GtkSourceView are also available some extensions to the standard Perl style
regular expressions:
\%[
and \%]
are custom word boundaries, which can
be redefined with the <keyword-char-class>
(in contrast with
\b
);
\%{id}
will include the regular expression defined in another
<define-regex>
element with the specified id.
Contained elements: none.
Attributes:
id (mandatory) |
Identifier for the regular expression. This is used
for the inclusion of the defined regular expression and must be unique
for the current document. It can contain a string of letters, digits,
hyphens (" |
<context>
This is the most important element when describing the syntax: the file to be highlighted is partitioned in contexts representing the portions to be colored differently. Contexts can also contain other contexts. There are different kind of context elements: simple contexts, container contexts, sub-pattern contexts, reference contexts and keyword contexts.
<match>
element and an optional
<include>
element. The context will span over the strings
matched by the regular expression contained in the <match>
element. In the <include>
element you
can only put sub-pattern contexts.
Contained elements:
<match>
(mandatory).
Attributes:
id (optional) |
A unique identifier for the context, used in references to the context. It
can contain a string of letters, digits, hyphens (" |
style-ref (optional) |
Highlighting style for this context. Value of this attribute may be id of a style defined in current lang file, or id of a style defined in other files prefixed with corresponding language id, e.g. "def:comment". |
extend-parent (optional) |
A boolean value telling the engine whether the context has higher
priority than the end of its parent. If not specified it defaults to
|
end-parent (optional) |
A boolean value telling the engine whether the context terminates parent context.
If not specified it defaults to |
first-line-only (optional) |
A boolean value telling the engine whether the context can occur only
on the first line of buffer. If not specified it defaults to |
once-only (optional) |
A boolean value telling the engine whether the context can occur only
once in its parent. If not specified it defaults to |
<start>
element and an optional
<end>
. They respectively contain the regular
expression that makes the engine enter in the context and the terminating one.
In the optional <include>
element you can put contained
contexts of every type (simple, container, sub-pattern or reference).
If the <start>
element is omitted, then the
id
attribute and the <include>
become
mandatory (the context can only be used as a container to include
its children).
Contained elements:
<start>
(optional), <end>
(optional), <include>
(optional).
Attributes:
id (mandatory only if <start> not present) |
A unique identifier for the context, used in references to the context. It
can contain a string of letters, digits, hyphens (" |
style-ref (optional) |
Highlighting style for this context. Value of this attribute may be id of a style defined in current lang file, or id of a style defined in other files prefixed with corresponding language id, e.g. "def:comment". |
style-inside (optional) |
If this attribute is "true", then the highlighting style will be applied to the area between start and end matches; otherwise whole context will be highlighted. |
extend-parent (optional) |
A boolean value telling the engine whether the context has a higher
priority than the end of he parent. If not specified it defaults to
|
end-at-line-end (optional) |
A boolean value telling the engine whether the context must be forced
to end at the end of the line, displaying an error ???? XXX. If not specified
it defaults to |
end-parent (optional) |
A boolean value telling the engine whether the context terminates parent context
when it ends.
If not specified it defaults to |
first-line-only (optional) |
A boolean value telling the engine whether the context can start only
on the first line of buffer. If not specified it defaults to |
once-only (optional) |
A boolean value telling the engine whether the context can occur only
once in its parent. If not specified it defaults to |
They refer to a group in a regular expression of the parent context, so it is possible to highlight differently only a portion of the matched regular expression.
Contained elements: none.
Attributes:
id (optional) |
A unique identifier for the context. It can contain a string of letters,
digits, hyphens (" |
sub-pattern (mandatory) |
The sub-pattern to which we refer. "0" means the whole expression, "1" the first group, "2" the second one, etc. If named sub-patterns are used you can also use the name. |
where (mandatory only in container contexts) |
Can be " |
Used to include a previously defined context.
Contained elements: none.
Attributes:
ref (mandatory) |
The id of the context to be included. A colon followed by an asterisk
(" |
style-ref (optional) |
Style in included context may be overridden by using this attribute. Its value is id of the style to be used instead of style specified in the referenced context. |
ignore-style (optional) |
If this attribute it "true" then the referenced context will not be highlighted. It does not affect child contexts and their styles. |
<include>
Contains the list of context contained in the current
<context>
.
Contained elements:
<context>
(one or more), <define-regex>
(zero or more).
<match>
Contains the regular expression for the current simple context. The
expression is in the same form used in <define-regex>
elements.
Contained elements: none.
<start>
Contains the starting regular expression for the current container context.
The expression is in the same form used in <define-regex>
elements.
Contained elements: none.
<end>
Contains the terminating regular expression for the current container
context. The expression is in the same form used in <define-regex>
elements, with an extension: \%{sub-pattern@start}
will be
substituted with the string matched in the corresponding sub-pattern
(can be a number or a name if named sub-patterns are used) in the
preceding <start>
element. For instance you could
implement shell-style here-documents with this code:
<context id="here-doc"> <start><<\s*(\S+)$</start> <end>^\%{1@start}$</end> </context>
Contained elements: none.
<keyword>
Contains a keyword to be matched by the current context. The keyword is a
regular expression in the form used in <define-regex>
.
Contained elements: none.