Overview

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-4/ (where ${PREFIX} can be /usr/ or /usr/local/ if you have installed from source.

The preinstalled language files are located in ${PREFIX}/share/gtksourceview-4/language-specs/. Custom user languages are usually placed in ~/.local/share/gtksourceview-4/language-specs/. Note: replace 4 with 2.0 or 3.0 in the path for GtkSourceView version 2 or version 3.

Some advices

The easiest way to start a new language definition is to copy a preinstalled language definition from a language that has similar constructs as the one you want to write a specification for. You can copy and rename a file from the systems directory to the local user one (create the directory if it doesn't exist yet) and edit the file accordingly.

The important thing you need to change are the id and name of the language and the metadata properties mimetypes and globs in the language spec. These should resemble your new language. It might be that your files do not have an appropriate mimetype associated yet. You can either in that case leave it empty, or add a new mimetype (see below).

If for some reason your language spec doesn't show up in an application like gedit, it might be a good idea to start the application from a terminal window and see if any errors/warnings appear for your language file. This usually gives good clues what's wrong with the specification. Note that you need to restart the application to take into account changes in a language definition file.

Conventions

It is better to follow the following conventions, especially if you want to contribute upstream, and get your language definition file included in GtkSourceView.

Tag <language>

The root element for Language Definition files.

Contained elements: <metadata> (optional), <styles> (optional), <default-regex-options> (optional), <keyword-char-class> (optional), <definitions> (mandatory).

Tag <metadata>

Contains optional metadata about the language definition.

Recognized elements are (all optional):

Tag <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).

Tag <style>

Defines a style, associating its id with a user visible translatable name and a default style.

Contained elements: none.

Tag <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.

Tag <default-regex-options>

Used to set global options for how regular expressions are processed.

Contained elements: none.

Tag <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).

Tag <define-regex>

The syntax highlighting engine of GtkSourceView uses GRegex, which uses the PCRE library. See the Regular expression syntax page in the GLib reference manual.

The <define-regex> tag defines a regular expression that can be reused inside other regular expression, to avoid replicating common portions. Those regular expressions are in the form /regex/options. 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:

It is allowed to use any of the attributes from <default-regex-options> as attributes of this tag.

Contained elements: none.

Tag <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.

Context classes can be enabled or disabled for some contexts, with the class and class-disabled attributes. You can create your own context classes in custom language definition files. Here are the default context classes:

Tag <include>

Contains the list of context contained in the current <context>.

Contained elements: <context> (one or more), <define-regex> (zero or more).

Tag <match>

Contains the regular expression for the current simple context. The expression is in the same form used in <define-regex> elements. It is allowed to use any of the attributes from <default-regex-options> as attributes of this tag.

Contained elements: none.

Tag <start>

Contains the starting regular expression for the current container context. The expression is in the same form used in <define-regex> elements. It is allowed to use any of the attributes from <default-regex-options> as attributes of this tag.

Contained elements: none.

Tag <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>&lt;&lt;\s*(\S+)$</start>
    <end>^\%{1@start}$</end>
</context>

It is also possible to use any of the attributes from <default-regex-options> as attributes of this tag.

Contained elements: none.

Tag <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.

Tag <prefix>

Contains a prefix common to all of the following keywords in the current context. The prefix is a regular expression in the form used in <define-regex>. If not specified it defaults to \%[

Contained elements: none.

Tag <suffix>

Contains a suffix common to all of the following keywords in the current context. The suffix is a regular expression in the form used in <define-regex>. If not specified it defaults to \%]

Contained elements: none.

Tag <replace>

The replace tag allows you to change one context so it functions as another context. For example, in the html.lang definition, there are a few references to a null context with id "embedded-lang-hook". In php.lang, that context is replaced like this: <replace id="html:embedded-lang-hook" ref="php-block">, so that php blocks are recognized within the html:html context at the points where the embedded-lang-hook context appears.

Contained elements: none.