Snippet Definition Reference

Snippet Definition Reference

Reference to the GtkSourceView snippet definition file format

Overview

This is an overview of the Snippet Definition XML format, describing the meaning and usage of every element and attribute. The formal definition is stored in the RelaxNG schema file snippets.rng which should be installed on your system in the directory ${PREFIX}/share/gtksourceview-5/ (where ${PREFIX} can be /usr/ or /usr/local/ if you have installed from source).

The toplevel tag in a snippet file is <snippets>. It has the following attributes:

  • _group

The group for the snippet. This is purely used to group snippets together in user-interfaces.

Within the snippets tag is one or more <snippets> elements. It has the following attributes:

  • _name

The name of the snippet. This may be displayed in the user interface such as in a snippet editor or completion providers. An attempt will be made to translate it by GtkSourceView.

  • trigger

The word trigger of the snippet. If the user types this word and hits Tab, the snippet will be inserted.

  • _description

The description of the snippet. This may be displayed in the user interface such as in a snippet editor or completion providers. An attempt will be made to translate it by GtkSourceView.

Within the snippet tag is one or more <text> elements. It has the following attributes:

  • languages

A semicolon separated list of GtkSourceView language identifiers for which this text should be used when inserting the snippet. Defining this on the <text> tag allows a snippet to have multiple variants based on the programming language.

  • CDATA Within the <text> tag should be a single

<![CDATA[]]> tag containing the text for the snippet between the []. You do not need to use CDATA if the text does not have any embedded characters that will conflict with XML.

Snippet Text Format

GtkSourceView’s snippet text format is largely based upon other snippet implementations that have gained popularity. Since there are so many, it likely differs in some small ways from what you may have used previously.

Focus Positions

Focus positions allow the user to move through chunks within the snippet that are meant to be edited by the user. Each subsequent “Tab” by the user will advance them to the next focus position until all have been exhausted.

To set a focus position in your snippet, use a dollar sign followed by curly braces with the focus position number inside like ${1} or ${2}. The user can also use Shift+Tab to move to a previous tab stop.

The special $0 tab stop is used to place the cursor after all focus positions have been exhausted. If no focus position was provided, the cursor will be placed there automatically.

You can also set a default value for a focus position by appending a colon and the initial value such as ${2:default_value}. You can even reference other chunks such as ${3:$2_$1} to join the contents of $2, an underbar _, and $1.

Variable Expansion

When a snippet is expanded into the GtkSourceView, chunks may reference a number of built-in or application provided variables. Applications may add additional variables with either gtk_source_snippet_context_set_constant() (for things that do not change) or gtk_source_snippet_context_set_variable() for values that may change.

Snippet chunks can reference a variable anywhere by using a dollar sign followed by the variable name such as $variable.

You can also reference another focus position’s value by using their focus position number as the variable such as $1.

To post-process a variables value, enclose the variable in curly-brackets and use the pipe operator to denote the post-processing function such as ${$1|capitalize}.

Predefined Variables

A number of predefined variables are provided by GtkSourceView which can be extended by applications.

  • $CURRENT_YEAR The current 4-digit year
  • $CURRENT_YEAR_SHORT The last 2 digits of the current year
  • $CURRENT_MONTH The current month as a number from 01-12
  • $CURRENT_MONTH_NAME The full month name such as “August” in the current locale
  • $CURRENT_MONTH_NAME_SHORT The short month name such as “Aug” in the current locale
  • $CURRENT_DATE The current day of the month from 1-31
  • $CURRENT_DAY_NAME The current day such as “Friday” in the current locale
  • $CURRENT_DAY_NAME_SHORT The current day using the shortened name such as “Fri” in the current locale
  • $CURRENT_HOUR The current hour in 24-hour format
  • $CURRENT_MINUTE The current minute within the hour
  • $CURRENT_SECOND The current second within the minute
  • $CURRENT_SECONDS_UNIX The number of seconds since the UNIX epoch
  • $NAME_SHORT The users login user name (See g_get_user_name())
  • $NAME The users full name, if known (See g_get_full_name())
  • $TM_CURRENT_LINE The contents of the current line
  • $TM_LINE_INDEX The zero-index based line number
  • $TM_LINE_NUMBER The one-index based line number

Post-Processing

By appending a pipe to a variable within curly braces, you can post-process the variable. A number of built-in functions are available for processing. For example ${$1|stripsuffix|functify}.

  • lower
  • upper
  • captialize
  • uncapitalize
  • html
  • camelize
  • functify
  • namespace
  • class
  • instance
  • space
  • stripsuffix
  • slash_to_dots
  • descend_path

Default snippets

The GtkSourceView team prefers to just keep a small number of snippets distributed with the library. To add a new snippet in GtkSourceView itself, the snippet must be very popular, and ideally a GtkSourceView-based application must use it by default.