MacRabbit

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 your Sugar. 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.

For specific details about the contents of the various XML files throughout a Sugar, your best bet is currently to explore the Sugars bundled with Espresso.