MacRabbit

What’s possible

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:

• Syntaxes: syntaxes define a coding language using regular expressions, and a Sugar can do one or more of the following:
  • define a new language
  • add new definitions or replace existing definitions in a language defined in another Sugar
  • include syntax definitions from another language (for instance, CSS inside <script> tags in HTML)
• CodeSense: CodeSense is what Espresso calls auto-complete, and a sugar can do the following:
  • create CodeSense definitions for a new language
  • add new CodeSense definitions to an existing language
  • define in what context certain completions should be used (based on the syntax definition of the language)
• Itemizers: itemizers build on the syntax definition to allow code folding and the Navigator to work
• Text Actions: a Text Action lives in the Actions menu, and is used to modify the contents of the active document
• File Actions: a File Action lives in the File→Actions menu, and is used to do something with a folder or file

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.

Limitations

Espresso’s Sugar API is quite powerful, but there are some limitations to keep in mind while you’re imagining the possibilities:

• Text or file actions must be invoked by the user, either through a menu item, a keyboard shortcut, or an automatic completion. This means that your action cannot execute on its own based on something happening in Espresso (for instance, it’s not possible to do something to a file as a result of it being saved unless the user intentionally invokes your action after saving the file).
• Although text actions have quite a lot of power when it comes to modifying the contents of the active document, there is not currently any way to ask Espresso to execute tasks outside the file. For instance, there is no API currently for opening up a preview window and populating it with a URL or file.
• Creating custom interface elements is certainly possible, but adding or modifying interface within existing Espresso windows is not supported (aside from custom sheets).

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.

Specific layout

A Sugar is a folder with a .sugar extension, and the following structure:

• CodeSenseLibraries/
• CodeSenseProviders/
• Contents/
  • Info.plist
• FileActions/
• Itemizers/
• Languages.xml
• PlaceholderThemes/
• Syntaxes/
• SyntaxInjections/
• TextActions/

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.

A quick overview

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!).