View Snippets
Snippets provide shortcuts for frequently used pieces of code. You can define standard snippets that are included in your sugar.
Defining Snippets
Snippets are defined in an XML file in the TextActions subdirectory of your sugar. For example, this snippet will expand into a C for loop when the user types “for[tab]”
<?xml version="1.0" encoding="UTF-8"?>
<action-recipes>
<snippet id="com.example.snippets.for" category="tools.Snippets">
<title>for loop</title>
<text><![CDATA[int ${1:i};
for ($1 = 0; $1 < ${2:N}; $1++)
{
$0
}]]></text>
<syntax-context>c, c *</syntax-context>
<text-trigger>for</text-trigger>
<key-equivalent>control option shift f</key-equivalent>
</snippet>
</action-recipes>
The <title> element defines the name shown in the snippets viewer.
The <text> element defines the contents of the snippet (as per the TextMate syntax).
The <snippet-context> element defines where the snippet will be available.
The optional <text-trigger> element defines a tab-trigger. Adding a key-equivalent=”…” allows a custom trigger key to be set instead of [tab].
The optional <key-equivalent> element defines a keyboard shortcut for the snippet composed of any number of modifiers (command, control, option, and/or shift) and a character (“tab”, “enter”, “space”, etc. may also be used for some special keys). Although this isn’t always 100% accurate, you can sometimes leave off the “shift” modifier if you use a capitalized character (or other character that can only be typed by holding down shift). Note, also, that if you use capital letters this may add a shift modifier even if you don’t want one.
Snippet placeholders
Version 1.1 of Espresso introduces several placeholders for snippets, allowing you to do things like include selected text in a snippet. Available placeholders include:
- EDITOR_SELECTION: the selected text, if any, when the snippet is invoked
- EDITOR_SELECTION_LINE: the contents of the first line of the selection when the snippet is invoked
- EDITOR_SELECTION_LINENUMBER: the number of the first selected line in the document when the snippet is invoked
- EDITOR_URL: the URL of the current file (e.g. file://localhost/Users/myaccount/myproject/myfile.html)
- EDITOR_PATH: the absolute path to the file (e.g. /Users/myaccount/myproject/myfile.html)
- EDITOR_DIRECTORY_PATH: the absolute path to the file’s parent directory (e.g. /Users/myaccount/myproject)
- EDITOR_PROJECT_PATH: the absolute path to the project root directory (e.g. /Users/myaccount)
To use a placeholder in a snippet, simply prepend a dollar sign to the variable name:
<p>This is the selected text: $EDITOR_SELECTION</p>
Just like in Textmate, you can also specify an alternative in case the variable is empty:
${EDITOR_SELECTION:Sorry, no selection!}
Hiding Snippets
Snippets can also be hidden. Hidden snippets aren’t exposed in the tools pane but can be accessed by their key equivalents or tab triggers. To hide a snippet, change its category to “hidden”.
For example:
<snippet id="com.example.snippets.closetag" category="hidden">