live.gnome.org

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 five 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. 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. 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:

• $GEDIT_SELECTED_TEXT - The currently selected text

• $GEDIT_FILENAME - The full filename of the document, empty string when the document isn't saved yet

• $GEDIT_BASENAME - The basename of the filename of the document, empty string when the document isn't saved yet

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

• Tab triggers as well as keyboard accelerators

• Completion popup showing available snippets (activate with <Ctrl><Space>). When you have text selected, it will show all snippets you can apply to the selected text. Otherwise it will find the tab trigger you're currently on (working backwards from the cursor) and provide a list with every snippet having a tab triggers starting with that prefix.

• Completion popup for multiple defined tabtriggers and accelerators. When you press tab after a tabtrigger that is bound to multiple snippets, the completion popup will show displaying the different snippets to choose from. An example of this behavior are the HTML doctype snippets.
• Apply .leave() on cursor movements
• Manage multiple buffers
• Implement system-wide snippets (multiple system wide file in $PREFIX, multiple files in userdir, only userdir is editable, userdir can override system wide).

Possible features

• Importing/exporting snippets? Is this really needed?
• Make sure that every aspect is also accessible from GUI (expression builder like)
• Write user documentation
• If a trigger ist written, highlight it, that the user knows, that she spellt it right.
• Having variables giving the line number and character number where the tag is to be inserted would be great.

Problems to be fixed

• Possible problems with dragging tabs to other gedit windows
• There are problems when a snippet is inserted without "editing" the placeholders of the previously inserted snippet

  • [JesseVanDenKieboom] I'm not sure what you mean by this, maybe you can explain it to me on IRC.

    • I'm possibly seeing this too -- TAB selects the whole second snippet text instead of advancing. -- Joachim

Screenshots

The snippet dialog showing the once snippet

http://www.icecrew.nl/~jesse/files/gedit/snippet_dlg1.png

Header file without include guards

http://www.icecrew.nl/~jesse/files/gedit/snippet_1.png

Select text, press <Ctrl>+<space> and select the once snippet

http://www.icecrew.nl/~jesse/files/gedit/snippet_2.png

The once snippet applied and TEST_APPLICATION has been typed in the first placeholder

http://www.icecrew.nl/~jesse/files/gedit/snippet_3.png

Non distributed snippets

gobject.xml