Before going into details about how to make a syntax, it’s important to realize how Espresso loads and uses syntaxes.
(sugar collection) > (detected xml syntaxes) + (detected xml syntax injections) > syntax compiling and injecting > (pool with syntaxes)
Espresso syntaxes are similar to TextMate language definitions, so anyone with previous experience there should feel right at home. To convert a .tmLanguage to the Espresso XML format, you can use the Espresso Syntax Tool.
Espresso syntaxes are defined using XML files. The basic structure looks as follows:
<?xml version="1.0"?>
<syntax name="root.type.identifier">
<!-- Syntax zones go into the <zones> tag -->
<zones>
...
</zones>
<!-- The (optional) <library> tag contains collections of reusable zones -->
<library>
...
</library>
</syntax>
The key piece in this XML is the name of the syntax. This identifier should be unique for each syntax in Espresso, so it’s a good idea to prefix it with your domain name or something similar. Syntaxes shipping with Espresso reserve the prefix espresso.default.
In the following sections, we’ll have a look at what the <zones> and <library> tags should contain.
Espresso has a syntax core based on regular expressions (“regexes” henceforth). When all syntax rules have been evaluated for the entire text, the result is a hierarchical structure that contains syntax zones mapping to parts of the text. Each of those zones has a type identifier that describes what it is, and can contain more syntax zones within.
To understand how the core builds this tree, let’s start with the notion of a syntax context. This context maintains a list of all the currently active syntax rules: the rules that can be evaluated to find a new piece of structure. The initial context consists of the rules defined in the root of a grammar, which comes down to all the rules in the <zones> tag.
There are 4 rule types that can be defined: start/end, match, include and cut-off. Each has a specific purpose and XML syntax. For performance reasons, the syntax core has one limitation that you must absolutely remember: syntax regular expressions only search in a single line of the text.
This rule produces a syntax zone which begins with a piece of text matching the regex from the starts-with tag and ends with a piece of text matching the ends-with regex. When this rule becomes active (when a start match is found), the new syntax context comprises the syntax rules defined in the <subzones> tag. Once the end expression is encountered, the old syntax context is restored again.
<zone name="zone.identifier">
<starts-with>
<expression>regular expression here</expression>
</starts-with>
<ends-with>
<expression>regular expression here</expression>
</ends-with>
<subzones>
...
</subzones>
</zone>
For simple structures like keywords, it’s sufficient to match a single piece of text. The syntax looks as follows:
<zone name="zone.identifier">
<expression>regular expression here</expression>
</zone>
For more complex syntaxes, it can be handy to use the rules of other syntaxes (for CSS embedded in HTML, for example) or to reuse sets of rules. Include rules address both, and come in 3 forms:
<include syntax="syntax.identifier"/>
<include syntax="self"/>
This rule collects all the root rules (inside the <zones> tag) of the syntax named syntax.identifier, and inserts them in place of the include rule. To recursively include the current syntax’s root rules (useful for languages like XML), use “self” as the attribute value.
<include collection="collection.identifier"/>
<include syntax="syntax.identifier" collection="collection.identifier"/>
In this form, the rule collects all zones from the collection named collection.identifier. Without a “syntax” attribute, the collection is assumed to be in the syntax of the include rule.
<cut-off>
<expression>regular expression here</expression>
</cut-off>
This rule is a processing instruction, rather than a true syntax rule, since it never generates a syntax zone. Normally, the regexes in the various rules are searched in the rest of the current line. Some situations may arise where a search expression could become unwieldy trying to define the cut-off point for the search.
Even though it’s often possible to use regex lookahead for these cases, much more convenient is the ability to say “no search expressions for rules in the current context can go beyond this point”. When the cut-off expression is found in the text, expressions for all real rules cannot go beyond the location of the cut-off.
The usefulness of cut-offs becomes apparent with large syntaxes and the use of syntax injections (see further). For example, the HTML syntax uses cut-offs to make sure embedded CSS doesn’t go beyond its closing </style> tag. Instead making the CSS syntax explicitly aware of this by modifying the rule regexes, a simple external cut-off has the same result. Because the CSS syntax should require no knowledge about languages it’s embedded in, this is clearly a preferable solution to a pure regex-based approach.
Important: a cut-off rule only has an effect on the rules in the same context, not in higher or deeper contexts.
When looking for a new syntax zone, the syntax core evaluates all rules in the order they’re written in the syntax definition. The rule that has the earliest occurrence in the text is then used to create a new syntax zone.
Start or match expressions have no precedence over others in the same context; they are simply evaluated in their source order. However, in case an end expression starts at the same point as a begin or match expression, the end expression takes precedence. Do note that this is only the case for occurrences at the exact same position. A match expression of rule A that begins before the end expression of rule B will always be chosen over the end of B, even if A’s match extends far past B’s end.
Now that we discussed the basic workings of syntax rules, let’s look at some details. Because expressions for syntax rules are often composed of several semantic parts (for example, a HTML <tag> has at least angle brackets and the actual tag name), <expression> tags inside <zone> tags can be combined with <capture> tags to easily define subzones based on captures in the regex. An example:
<zone name="a.surrounded">
<expression>(+)(a*)(+)</expression>
<capture number="1" name="plus"/>
<capture number="2" name="multiple.a"/>
<capture number="3" name="plus"/>
</zone>
Instead of simply generating a syntax zone with identifier “a.surrounded”, the capture definitions insert subzones for “plus”, “multiple.a” and “plus” inside the “a.surrounded” zone.
<library>
<collection name="collection.identifier">
...
</collection>
</library>
The optional zone library in a syntax can define several zone collections, which can then be referenced using include rules. Each collection needs to specify a name, and can contain the same elements as the <zones> tag.
To avoid unnecessary dependencies between syntaxes and to prevent duplication, Espresso offers syntax injections. Injections are best compared to rule collections, except that they’re included automatically by the syntax core. The basic structure of a syntax injection looks as follows:
<?xml version="1.0" encoding="UTF-8"?>
<injections>
<injection name="injection.identifier" selector="..." action="...">
...
</injection>
</injections>
Each <injection> element contains a list of rules that need to be injected. The allowed elements are the same for collections, so they won’t be repeated here. Each syntax injection must have a unique name (once again, the espresso.default prefix is reserved).
The selector attribute specifies which syntax rules have to be targeted for this particular injection. Note that the selector is interpreted against syntax rules in the syntax definitions, not against the resulting syntax zones. Additionally, collections can not be targeted (they serve mainly as syntactic sugar to improve the organization in the XML).
For all targeted rules, an action is performed with the rules in the injection body. The value can be any of these:
Syntax injections have no enforced relative order, but any replace-target action will neutralize any subzone-related actions for the same target rule.
]]>This is the most direct way to do things, and preferable if you are comfortable with Objective-C. You’ll code custom Objective-C classes (that use the right methods so Espresso can interact with them), and then tell Espresso which class to link to which menu item using XML. To get started see the Intro to Cocoa Sugars.
The remaining types of custom actions all use pre-defined Objective-C classes that allow you to interact with the Espresso API using other languages.
Spice.sugar provides full access to the Objective-C API using JSCocoa (a Javascript to Objective-C bridge). The main benefits to going this route are:
The main downside is that the users of your Sugar will need to install Spice.sugar before your actions will work.
For more information about developing Espresso actions using Spice, see the Spice documentation.
TEA for Espresso is a Sugar that is bundled with Espresso. TEA leverages the PyObjC bridge to allow you to work directly with the Objective-C API using Python. This has the same trade-offs as working with Javascript, mostly, with some differences:
The main benefit is that TEA has been bundled with Espresso since version 1.0, so your Sugar will work for anyone with an up-to-date copy of Espresso. You can find more information about Python actions in the TEA documentation.
Any language you can execute on the command-line (PHP, Ruby, etc.) can be used for a custom action. This is very similar to Textmate bundle actions. You’ll get the contents of the document (or the line, or word, or whatever else you specify) in standard input along with numerous environment variables containing info about the document and so forth. What you send to standard output gets inserted into the document.
This is often the quickest way to get an action up and running (fewest new things to learn; just the environment variables and XML action definitions), but has the downside of not having any way to do more than text input/output. Additionally, standard input has a memory limit to it, so if you are trying to process a large document you may not actually get all of the text. Of course, if all you need is to invoke a shell action for the document’s path or whatever, this is WAY easier than learning another language or API. Running shell scripts is also possible thanks to TEA for Espresso: shell scripts in the TEA documentation.
]]>If you are not familiar or comfortable with Cocoa bundles yet, you may find the Intro to Cocoa Sugars and Espresso Cocoa API useful places to start. If you are interested in coding Espresso actions but disinclined to work in Objective-C, see Types of Custom Actions. Otherwise, the resources below should give you a place to start.
The Espresso API’s headers come with every build of Espresso, and are located in Espresso.app/Contents/Headers. The best way to learn about the possibilities is to look at these documented headers.
Right now, the easiest way to dig in and learn more about the Cocoa Sugar API is to download the example. You need Apple’s Xcode Tools installed to compile.
1. Download the Example Cocoa Sugar.
2. Open Example Sugar.xcodeproj.
3. Open the project inspector and set the ESPRESSO_PATH variable to wherever Espresso is installed. (Do this by choosing Project > Edit Project Settings in Xcode, then going to the Build tab and finding the ESPRESSO_PATH setting all the way down the list).
4. Optionally change the sugar’s product name to something of your own.
5. Compile!
6. Install into ~/Library/Application Support/Espresso/Sugars
7. Relaunch Espresso to test
If for whatever reason you’re interested in coding in Python rather than Objective-C, it’s possible to code Sugars without ever touching Xcode. Here’s the steps:
python setup.py py2app (see the setup.py file for how to create a development version you can edit without recompiling)For more detailed information, see CocoaSugars in Python.
]]>Although Espresso is a powerful editor, you may come across areas that you think could improve. Perhaps it doesn’t support your favorite coding language, you wish there was a way to delete the current line with a single keystroke, or you need the auto-complete to offer completions for a PHP framework that you use all the time. If you want to extend the capabilities of editor for something like this, then you will be creating a Sugar. Sugars are plugins that Espresso loads when it launches that extend its capabilities.
In general, here is what Sugars can do:
Unless you need advanced itemizers, text actions, or file actions, your Sugar will be entirely authored in XML. See below for links to documentation for each feature.
Espresso’s Sugar API is quite powerful, but there are some limitations to keep in mind while you’re imagining the possibilities:
There may be other limitations within the API, but these are the ones that most often trip people up when they’re trying to imagine what they can accomplish. We’re always working to improve the Sugar API, as well, so some of these limitations may cease to exist eventually.
A Sugar is a folder with a .sugar extension, and the following structure:
Each of these is optional, depending on what features you want your Sugar to provide. To test a Sugar in Espresso, move it to ~/Library/Application Support/Espresso/Sugars/ and restart Espresso for the changes to take effect.
Although not all Sugars will use all of the files and folders above, a useful way to get a handle on what the files do is to think about a sugar that is describing a completely new syntax (rather than expanding on an existing syntax). For such a Sugar that’s building a syntax from the ground up, here’s how the files interact with one another:
Languages.xml — see Languages
This is the entry point for Sugars that define new languages. The Languages.xml file describes all the languages that your Sugar is defining and tells Espresso how to detect those languages (for instance, which file extensions should trigger this Sugar).
Contents — see CocoaSugars
This is a folder that gets automatically generated when the Sugar contains compiled code.
Every Sugar (Cocoa or otherwise) must have an Info.plist in the Contents folder. This file defines a unique identifier, version and optional update information for your Sugar. At some point in the future, we will no longer load Sugars without this file present.
Syntaxes — see Syntaxes
In this folder, you define the zones that make up your syntax using regular expressions. You can have multiple XML files for different languages (see the XML+HTML Sugar for a great example); a standard usage is to have one XML file for each language in Languages.xml. The syntax definition is incredibly important, because it’s the basis of both CodeSense and itemizers.
SyntaxInjections — see Syntaxes
This folder contains XML documents for your syntax injections; syntax injections allow you to either inject a different syntax into your Sugar (for example, styling embedded CSS as CSS even though it’s in the larger context of an HTML syntax), or inject rules of your own into a pre-existing syntax.
CodeSenseLibraries — see CodeSense
The XML files in this folder define lists of completions, but do not contain any logic for where those completions should be offered. For example, in the XML+HTML Sugar, one of the XML files in CodeSenseLibraries contains a list of HTML attributes.
CodeSenseProviders — see CodeSense
The XML files in this folder add the contextual logic for defining when a given CodeSenseLibrary should be used using the Selectors from the Syntaxes files.
Itemizers — see Itemizers
Using the selectors defined by the syntaxes, the XML files in Itemizers define the organizational logic for the Sugar. By defining your itemizers, you enable Espresso to use its code navigator and code folding for your syntax.
PlaceholderThemes — see SyntaxThemes
This folder contains CSS theme files that provide default coloring when the Sugar is loaded. User themes can override known placeholder themes to provide custom coloring.
TextActions — see TextActions
The XML files in this folder define actions that can be performed on text, along with the categories they should be grouped in. In order to create text actions, some Cocoa object code must exist to support it. As of writing Espresso doesn’t come with generic action objects, but this may change.
FileActions — see FileActions
The XML files in this folder define actions that can be performed on files, and are set up almost exactly like text actions, with that difference that they operate on file contexts instead of text contexts.
Although we try to keep this wiki up to date with documentation for all portions of Espresso, often the best way to figure out how to do things is to right click on an existing Sugar, choose Show Package Contents, and take a look at what’s inside its various XML files. You can find the Sugars bundled with Espresso by right clicking on the application and navigating to Contents/SharedSupport/Sugars (make sure not to save anything in there, or it will be lost when you update Espresso!).
]]>Espresso does not currently have any official documentation, but if you have just started working with Espresso, see our Intro to Espresso for useful resources.
Espresso has a regular-expressions-based syntax core, much like TextMate (in fact, developers of TextMate language plists will be able to convert them). Espresso reads XML-based syntaxes, then uses those rules to generate a syntax tree for opened text documents. Each syntax zone in that tree has a type identifier (similar to CSS class names in HTML) that can be targeted using CSS-like selectors. This selector targeting is used all over Espresso, for various subsystems like syntax coloring and CodeSense.
That first layer has been done before, so while Espresso’s implementation is quite powerful (especially its selectors), the contextual information usually stays very local and somewhat limited. To remedy that, Espresso layers an “itemizer” above the syntax core. Itemizer definitions group syntax zones into semantical blocks that behave like an “item”, a logical piece of the document.
Itemizing currently brings along two features: the Navigator and great code folding. CSSEdit-like structure listings are now possible for any language, as long as someone takes the time to create a good itemizer definition. Any language offering an itemizer also gets code folding support for free.
This multi-layered design delivers excellent performance while still allowing high-level representations of a document that are actually useful to the user.
]]>This channel is available for anybody to use, for general discussion, for requesting help from other Espresso users, or for quick help with Sugars.
You can either download an IRC client (see below), or use the following link to open a web chat:
http://webchat.freenode.net/?channels=##Espresso
There are multiple viable IRC clients for Mac OS X. Here are several very popular ones:
Ian Beck, who does QA and support for MacRabbit, is typically in IRC during business hours (9-5) Pacific time.
Jan Van Boghout, the core Espresso developer, occasionally (… very, very ocassionally …) drops his head into the room, as well. If you’ve got an urgent question that only Jan can answer, or a suggestion/complaint with Espresso, you’ll probably want to try email first. He most often drops by IRC immediately following a new release.
]]>If you need to modify a sugar bundled with Espresso (HTML, CSS, and PHP are the ones people most often want to modify), here’s how to do so without losing your updates whenever Espresso is updated:
1) In the Finder, right click on Espresso and choose “Show Package Contents”
2) Navigate to Contents/SharedSupport/Sugars, duplicate whichever sugar you want to override (for instance, PHP.sugar), and move the new copy here:
~/Library/Application Support/Espresso/Sugars/
3) Show package contents on the copied sugar, and open up Contents/Info.plist (I recommend using a dedicated plist editor like Plist Edit Pro, but any text editor will work). You need to update the CFBundleVersion property to something higher than what’s currently there. For instance, if the current version is 1.0, you could change it to 1.0.1.
4) Make your desired modifications to the duplicated sugar. To add a new extension to the PHP.sugar, for instance, you need to open up Languages.xml and add something like this nested in the <detectors> tag:
<extension casesensitive="false">phtml</extension>
5) Once you’ve saved your changes, relaunch Espresso. Only the version of the sugar with the highest CFBundleVersion defined will be loaded, and your custom sugar won’t be overwritten when the program is updated. Of course, if the bundled version of the sugar is updated you’ll need to repeat the process, but you would want to do that anyway to get whatever improvements are included with the new version.
Good luck! Drop a line in the forums if you’ve got a specific modification that you aren’t sure how to achieve.
There are two components for CodeSense: libraries and providers.
XML files within your CodeSenseLibraries folder define the possible completions for your Sugar, grouped into sets. The library contains no logic about when various sets should be shown for auto-completion, but it does offer the ability to specify text snippets for use with specific sets of strings.
A typical CodeSenseLibraries XML file looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<codesense version="1.0">
<!-- The behavior defined in the root codesense element serves is used for all sets,
unless the set defines its own behavior -->
<behavior>
<!-- The append-static element defines a snippet that gets appended after the
completion string. -->
<append-static> is a fruit</append-static>
</behavior>
<set name="com.yourdomain.yoursugar.fruits">
<completion string="apple" />
<completion string="pear" />
<completion string="orange" />
</set>
<set name="com.yourdomain.yoursugar.vegetables">
<!-- A behavior defined in a set applies only to that set. -->
<behavior>
<append-static> is a vegetable</append-static>
</behavior>
<completion string="carrot" />
<completion string="cabbage" />
<completion string="potato" />
</set>
</codesense>
Sets and their completions should be straight-forward; the set has a name (which will be used in the CodeSense Provider to determine when to use these completions), and each completion has a string attribute that is the completion. By convention, the name for each set should be in reverse domain format.
Behaviors are used to append text snippets after the completion. In the simple example above, when the user uses CodeSense to insert “apple” what will actually be inserted is “apple is a fruit”. Behaviors are powerful because they allow you to conditionally insert things based on what comes after the completion, and also use text snippets to create tab stops.
The above example showcases how to use a static snippet to be appended to the completion string, but for more advanced behaviors, you can use additional settings and a dynamic snippet:
<behavior>
<!-- The <append-dynamic> element allows you to dynamically generate a snippet
to append after the actual completion. -->
<append-dynamic>
<!-- The matched suffix allows you to capture information about the text
after the completion. Specify a regular expression here. -->
<matched-suffix>(\s+)(is a vegetable)?</matched-suffix>
<!-- The transform-into element is a regex replacement expression, and can use
the captured strings from matched-suffix to generate a conditional snippet. -->
<transform-into>(?2:\1is a vegetable:\1is fantastic and )</transform-into>
</append-dynamic>
<!-- (optional) The confirm-characters element specifies additional characters that
trigger the confirmation of a completion. -->
<confirm characters=" " />
<!-- (optional) The confirm-partial element specifies characters that are contained
within the completion. When they're pressed, the completion will confirm up to
that character (including the character itself) and continue completing. This
is useful for things like CSS properties or PHP functions. -->
<confirm-partial characters="-" />
</behavior>
The example above may be confusing at first glance. The matched-suffix should be comprehensible (it’s a simple regex that with two capture groups that grabs whitespace immediately after the completion and then looks for the optional string “is a vegetable”). However, the transform-into expression uses a conditional that outputs different contents based on whether the second capture is empty or not. The syntax for regex conditionals in transform-into elements is:
(?x:a:b)
Which means: if the numbered capture group “x” has contents, insert “a”. Otherwise, insert “b”.
In the example, if the text “is a vegetable” does not fall after the name of the vegetable, then it will be inserted. If it does already exist, then “is fantastic and” will be inserted leaving the full completion reading something like “carrot is fantastic and is a vegetable”.
A real-life example is the CSS.sugar, which when auto-completing property names looks for a colon after the property, and if it isn’t there inserts it.
Providers map contexts in a document to possible completions (reference based on the name of the sets you defined in CodeSenseLibraries). Providers should be defined in the CodeSense Providers subfolder of a sugar, as an XML file with the following structure:
<?xml version="1.0" encoding="UTF-8"?>
<codesense>
<provider>
<!-- The selector element specifies in what document contexts the provider
is active. The :capture pseudo-class will save the contents of the zone in a
variable. For the example below, the property-name is saved in the "name"
variable. -->
<selector>css > property-name:capture(name) + property-value</selector>
<!-- The completions element points to the CodeSense Library key that has to
be used. It can contain placeholders for captured pieces of text from
the selector. -->
<completions>com.macrabbit.css.property.${name}</completions>
<!-- The complete-match element defines a regular expression for the piece of
text that is completed by this provider. It is not necessary to append
an end-of-line symbol: this happens automatically. Note that even if this
provider is active in the current context, and the expression is matched,
it may still be ignored for a completion if other providers match a
different piece of the same text. -->
<complete-match>[a-zA-Z0-9-]*</complete-match>
<!-- (Optional) The require-suffix element defines a regular expression which
the text *after* the completion has to match. It is not necessary to
prepend a begin-of-line symbol: this happens automatically. -->
<require-suffix>[^:]|</require-suffix>
</provider>
<!-- Many providers can be defined in the same XML -->
<provider>
...
</provider>
</codesense>
The example above should be largely self-explanatory thanks to its comments, but one thing to keep in mind is that thanks to the :capture(VARIABLE) pseudo-class you do not have to directly refer to all sets in your CodeSenseLibraries directly. In the example above, both of these sets will be used depending on which CSS property the user is currently editing:
<set name="com.maccrabbit.css.property.display"> ... </set>
<set name="com.macrabbit.css.property.float"> ... </set>
Espresso’s syntax coloring approach is modeled after HTML and CSS. In fact, Espresso themes are CSS files. Just like regular style sheets, they contain rules that apply to certain zones in the document. Instead of targeting the web page DOM, Selectors are now used to target syntax zones in your documents.
Espresso features user themes (loaded from ~/Library/Application Support/Espresso/Themes) and placeholder themes (loaded from the PlaceholderThemes directory in a sugar). Together, they are combined into the final set of rules that define the coloring for documents. A placeholder theme requires a special comment in the CSS file:
/*
@theme XYZ Placeholder
@placeholder some.category.here
*/
The value for @placeholder is a type identifier and can be freely chosen, but must be descriptive about the rules your placeholder theme contains. It’s a good idea to make a single placeholder theme (and identifier) per language instead of grouping several unrelated languages into one.
Example: currently, the CSS built-in sugar is the only one defining a placeholder theme.
One user theme can be active at a time. It must contain a comment like this:
/*
@theme My Theme Name
@override-placeholders identifier, some.other.category
*/
When it’s active, the user theme will be combined with all placeholder themes that do not have an identifier matched by the selector in @override-placeholders. Note that an override like “text” matches “text.html”, “something.text”, etc.
Since themes are simple CSS files, you can use a range of color definitions: hex colors, rgb() notation and even composited rgba() for blended alpha colors. Each rule can contain any of the following properties: color, background-color, font-weight, font-style and spell-check.
To adjust global colors, you need to specify a special rule with “@base” in place of the selector. It’s recommended to add this to any theme you make.
@base {
color: #000000;
background-color: #FFFFFF;
insertion-point-color: #000000;
selection-background-color: default;
current-line-background-color: #fff8dd;
}
You can also specify whether a zone should have spell-checking disabled by default:
tag, source, sourcecode {
spell-check: disabled;
}
Themes can be directly edited within Espresso by choosing “Preferences” (command + ,) from the “Espresso” contextual menu, clicking on “Colors” within the Preferences window, then clicking “Edit Theme…”.
Alternately, if you’d like to edit the Syntax theme with another application (For instance the wonderful CSSEdit), while in the “Colors” section within the Preferences window, click “Reveal in Finder”. In Finder you can right (or control) click on the theme you’d like to edit, go to “Open With”, and select the application of your choice.
A new window will open with the syntax colors written in hex. If you are unfamiliar with hex colors see: Wikipedia , and be sure to pick up the indispensable and free HexColorPicker for the OS X Color Panel.
If you are editing the currently active theme, changes will be updated live in all open windows.
]]>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.
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:
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!}
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">