Snippet Syntax

Espresso snippets allow you to automatically fill in certain information, navigate through multiple tab stops, execute shell commands, and more. However, because this functionality requires a special syntax you have to escape some characters (most notably the $, \, and ` characters) with a backslash in order to have them output to your document. So for instance, if you want a literal $ in your snippet you would enter \$.

If you are not sure how to create a new snippet, see creating snippets. This page describes the specific syntax that governs how snippets function.

Topics

• Tab stops
• Snippet variables
• Shell code

Tab stops

A tab stop is a special area in your snippet that is automatically selected when your snippet is inserted. Using tab stops you can quickly fill in the details for a snippet by hitting tab and shift-tab to move between them. Tab stops come in three flavors: plain stops, placeholder text, and mirrored stops.

A plain tab stop uses the format $n, and the cursor will advance in numeric order with $0 as a special final stop:

<p id="$1"$2>$0</p>

When you insert this snippet, your cursor will be inside the ID attribute. Then when you hit tab it will move outside of the ID so you can enter attributes, and when you hit tab a final time will move inside the paragraph.

A tab stop with placeholder text uses the format ${n:placeholder}, and you can nest tab stops within one another:

<p${1: id="$2"}>${3:your text here}</p>

When you insert this snippet, the text id="" will be selected. If you hit tab, your cursor will be placed inside the ID attribute. A second tab will select the text 'your text here'. If you had decided you didn't want an ID on this particular paragraph, you could hit delete to remove the first selected text, and then when you hit tab you would jump to the 'your text here' stop.

A mirrored tab stop outputs the text that you enter in one tab stop somewhere else in the snippet. For instance, you could create a simple HTML tag like so:

<${1:p}>$2</$1>

Because tab stop #1 occurs in multiple places, it will be mirrored. So if you insert this snippet and type li, you will end up with an LI tag.

A second type of mirrored tab stop is a transformation. Transformations use the syntax ${n/regex/replacement/flags}. For instance, here's a more advanced version of the tag insertion snippet above:

<${1:p}>$2></${1/\s.*//}>

This snippet will behave identically to the previous mirrored snippet, except that if you decide to enter any attributes in the opening tag they will not be mirrored to the closing tag. This is because of the transformation in the closing tag which says "take the first tab stop, search for a whitespace character followed by any other characters, and replace that with nothing using no special flags".

(Documentation on the available special flags is forthcoming.)

Snippet variables

You can use several variables for snippets to do things like including 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/dir/myfile.html)
• EDITOR_PATH: the absolute path to the file (e.g. /Users/myaccount/myproject/dir/myfile.html)
• EDITOR_DIRECTORY_PATH: the absolute path to the file's parent directory (e.g. /Users/myaccount/myproject/dir)
• EDITOR_PROJECT_PATH: the absolute path to the project root directory (e.g. /Users/myaccount/myproject)

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>

You can also specify an alternative in case the variable is empty:

${EDITOR_SELECTION:Sorry, no selection!}

By combining variable alternatives with tab stops, you can easily create snippets that will fill in the information if they have it and prompt you if not:

<a href="$1">${EDITOR_SELECTION:$2}</a>

Espresso also recognizes Textmate snippet variables for which there is a corresponding $EDITOR_* variable, and will fill them in intelligently. For instance, if your snippet includes $TM_SELECTED_TEXT, Espresso will insert the contents of $EDITOR_SELECTION.

Shell code

You can execute shell code directly within your snippet by surrounding it with backticks. For instance, this will use the shell command pbpaste to insert the contents of the clipboard as the default contents of an href attribute:

<a href="${1:`pbpaste`}">$2</a>

You can get much more complicated, as well, by including small shell programs within backticks. The only character you have to escape to use properly within such shell code is the backtick character.