This site has been retired. For up to date information, see handbook.gnome.org or gitlab.gnome.org.


[Home] [TitleIndex] [WordIndex] 

Overview

The idea is to allow users to create little tags that expand to a snippet of text. When the tag is entered in the Gedit view and <tab> is pressed, it gets expanded to the snippet. The user can specify insertion points in the snippet so that when <tab> is pressed again, the cursor moves to the next insertion position. It's very basic and a bit TM alike (though it probably will need some extra features)

Using snippets

Install the plugin. Menu: Tools -> Manage Snippets. A dialog will appear and you can start add snippets. Select a 'Language' (or Global for global snippets). Start adding snippets.

Syntax

There are six different types of placeholders which can be used to specify 'action-areas' in the snippet.

  1. Simple placeholders: ${n[:default-value]}.

    • Here 'n' specifies the tabstop of this placeholder, with n: 1 → ∞. The ':default-value' is optional and indicates a default value to be inserted at the placeholders position. The default value van also be a list by encapsulating it in [] and separating values by a comma. By default, the first non-empty value will be used, and from 2.30 on, a popup will be shown listing the different alternatives when you tab into the placeholder. Example: 

      <div class="${1:text}">

  2. Mirror placeholders: $n.

    • Here 'n' specifies the placeholder to mirror, with n: 1 → ∞. Placeholders are automatically mirrors when 'n' is already defined before. Mirror placeholders are updated instantly while you type, which is cool. Example: 

      <div class="${1:text}">This div has class: ${1}</div>

  3. Shell placeholders: $([n:]cmd) (Available in v2.16)

    • Here 'n' specifies the reference of this placeholder, with n: 1 → ∞. The reference is optional and when specified can be used in other placeholders to use the contents returned by the shell command. 'cmd' can contain any number of ${n} which will be replaced with the contents of the corresponding placeholders and will be executed in a subshell. Everything written to stdout will be inserted. Example: 

      $(1:echo $GEDIT_SELECTED_TEXT | head -n 2)

  4. Python placeholders: $<[n1[, n2, ...]:]cmd> (Available in v2.16)

    • Python placeholders are like shell placeholders, but they are somewhat different. Here n1, n2 etc specify the additional dependencies of this placeholder (additional to the placeholder dependencies specified in the command). These dependencies are useful when you have multiple python placeholders in one snippet. An example follows below. `cmd' can contain any number of ${n} which will be replaced with the contents of the corresponding placeholders and will be evaluated by the python interpreter. The return value of the placeholder will be inserted. Additionally all the python placeholders in the same snippet share the same namespace. So functions defined in one placeholder can be used on another. Also when you declare variables with 'global <var>' you can use that var in other placeholders. Example snippet: 

      Word separated with underscores: ${1:A_WORD}
Camelcase: $< global split
split = $1.lower().split('_')
camelcase = ''

for s in split:
    camelcase += s.capitalize()

return camelcase >
First word: $<[1]: return split[0].capitalize()>

  5. Regular expression placeholder: ${[n:]input/regular expression/substitution[/modifiers]}

    • n (optional): the reference tabstop of this placeholder. It's not a real tabstop because you can't tab to it, but you can use it in other placeholders to mirror the result of the substitution
    • input (mandatory): a reference to another placeholder (a number) or an environmental variable ($GEDIT_SELECTED_TEXT). This is the input for the match
    • regular expression (mandatory): a regular expression to match the input. This uses the python re module and thus its syntax
    • substitution (mandatory): the substitution string, this can contain backreferences to groups in the regular expression with \n where n is the number of the group or 0 for the whole match. You can also use group names (see python docs) in the regular expression, you can backreference to those with

      \<name> (you can also backreference with \<n> where n is a number of a group). Further more, you can have modifiers in a backreference with the following syntax \<n|name,modifiers>. Currently supported modifiers are:

      • u: upper case first character
      • U: upper case whole group
      • l: lower case first character
      • L: lower case whole group
      • t: title case whole group
      You can specify multiple modifiers (very modifier is processed in turn). This means that you can use the modifier Lu to first make the matched group lowercase and then make the first character upper case. One more neat thing you can do with substitutions is conditional substitution. The syntax is as follows: (?n|name,truepart,falsepart). This means that truepart will be used when the group n (or name) is non-empty and falsepart otherwise. These can be nested (?1,(?2,yes2,no2),no1) and used wherever in the substitution. The truepart and falsepart can itself contain any backreference.
    • modifiers (optional): python regex modifiers can be specified: I, L, M, S, U and X (example: IMX). For information on the meaning of these modifiers see the python documentation

  6. End placeholder: $0

    • This placeholder specifies the end of the snippet. It's the last placeholder position to jump to (when no $0 is specified, the last placeholder position will be at the end of the snippet). When this placeholder is entered, the snippet placeholders are removed and you are left with normal text.

Additional there is environmental variable substitution ($PATH, $HOME), you can use them freely throughout the snippet. There are currently three gedit environmental variables you can use:

From gedit 2.28 on, these have been renamed to behave more consistently over different plugins in gedit:

There is one additional somewhat special environmental variable, $GEDIT_CURRENT_WORD. When you use this and apply the snippet the current word (defined by pango) at the cursor position will be stored in $GEDIT_CURRENT_WORD, the word itself will be removed! This is useful for snippets like the following generic begin/end section latex snippet: 

# Accelerator: <Ctrl>+B
\begin{$GEDIT_CURRENT_WORD}
  $0
\end{$GEDIT_CURRENT_WORD}

Here you can type: document<Ctrl+B> which will expand to a begin/end document section.

You can use $n for simple placeholder substitution throughout the snippet instead of using the more verbose ${n}.

Current features

Possible features

Problems to be fixed

Non distributed snippets

gobject.xml

2024-10-23 10:58