There are two components for CodeSense: libraries and providers.

CodeSenseLibraries

XML files within your CodeSenseLibraries folder define the possible completions for your Sugar, grouped into sets. Libraries contain no logic regarding when various sets should be shown to the user, but they do offer the ability to specify text snippets for use with specific sets or strings (see SnippetSyntax for more info about text snippets).

XML files within CodeSenseLibraries can be named anything you wish, and use this basic syntax:

Each <set> has a name (which will be used in the CodeSenseProviders to determine when to use these completions), and each <completion> element has a string attribute that will be suggested to the user.

To use text snippets, you must add an additional <behavior> element. Behaviors cascade, so if you place a behavior in the root <codesense> element it will be used by default for all sets. If you have a behavior within a <set>, it will be used instead of the default behavior (if there is one) for all completion strings in the set. And if you nest a behavior within a <completion> it will be used only for that string instead of any behavior in the set or root element.

There are two types of behaviors, but they use very similar syntax:

Static appends are straight-forward: if the user chooses the related CodeSense completion string, the snippet in <append-static> is inserted after the string no matter what.

Dynamic appends are more complicated. The <matched-suffix> element is a standard regular expression that can optionally contain capture groups, and it is tested on the characters immediately after the string the user is inserting via CodeSense. Like all regex in Sugars, <matched-suffix> is constrained to a single line.

The <transform-into> element typically uses regex conditional logic based on the capture groups in the <matched-suffix> element. This uses this syntax:

Which means: if capture group number “x” has contents, insert “a”. Otherwise, insert “b”.

So in the example, if the string is followed by zero or more spaces and a curly brace, there will be something in capture group 1. Then <transform-into> specifies that if something is inside capture group 1, nothing is inserted (the location of “a” is blank). If the string is not followed by optional whitespace and a curly brace, though, a snippet with matched curly braces is inserted with a tab stop in between them (see SnippetSyntax for in-depth info about snippet syntax).

This system can be tricky to get your head around. For real-world examples, make sure to open up the Sugars bundled with Espresso and see how they are using dynamic appends to insert different snippets based on context.

The <confirm> and <partial-confirm> elements allow you to specify characters that will complete or advance the CodeSense completion in addition to tab and enter. For instance, in the built-in CSS.sugar hyphens (-) are used as a partial-comfirm character so that you can type something like “bo-t” and end up with “border-top”. Then the colon (:) is used to confirm CodeSense entries, so you could type “bo-t:” to insert “border-top”. In general, you should use confirm and partial-confirm characters sparingly. They work well for speeding up CodeSense in languages like CSS where the user is not defining their own properties, but for other languages where the user might have a custom variable or function that starts the same as a built-in CodeSense completion string, confirm characters can be maddening.

CodeSenseProviders

The XML files in your CodeSenseProviders folder define the rules that tell Espresso when to display the sets you defined in your “CodeSenseLibraries”#libraries and use the following syntax:

In the example, zero or more letters are required and the syntax context must be JavaScript source code (but not a string or comment). If both of these requirements are met, the completions in the two sets listed will be displayed to the user.

You can also use the :capture() pseudo-element in selectors to attach sets to a provider dynamically. For instance, in the CSS.sugar this is how attribute values are defined in the CodeSenseProviders:

A named capture is being used to map one provider onto an arbitrary number of set names. For instance, the CSS CodeSenseLibraries will contain sets named “com.macrabbit.css.property.display”, “com.macrabbit.css.property.float”, etc. to define completion strings for different CSS properties.

The <require-suffix> element is an optional element that restricts CodeSense depending on whether or not the characters to the right of the cursor match the provided regex. In this instance, the rule will only be shown if the character to the cursor’s right is not a colon (:).

Download SugarDev.sugar

Unzip the Sugar and double click it to install (as with any other Sugar), then relaunch Espresso to gain access to the new CodeSense and snippets.

If you are using the program and need help, please choose Help→Send Feedback… in the app and ask us your questions directly.

If you want to download custom Sugars or themes, please choose Help→Get Sugar Plug-Ins… in the app, or search GitHub (vast majority of Sugars and themes end up on GitHub).

Getting started

If you are new to Sugar development, here are some good starting points:

• Introduce yourself to the SugarBasics and SugarStructure
• Create custom SyntaxThemes to change the colors of your code
• Learn LanguageSugars so you can add support for a new language, or improve an existing one
• Craft new CodeSense to add auto-completion to new or existing languages
• Dive into JavaScriptActions and supercharge your code editing

Reference

If you are already comfortable with Espresso Sugars and themes, here are some links to jump quickly to various info:

• SugarBasics and SugarStructure

• Selectors
• SyntaxThemes
• Snippets and SnippetSyntax

• LanguageSugars
• CodeSense
• Syntaxes and LanguagesXML
• Itemizers
• ContextualSettings

• JavaScriptActions
• ActionXML
• Localizable.strings
• JavaScriptAPI
• CocoaAPI

If you’re an old hand with Espresso Sugars, you may be interested in the RecentChanges.

To create new snippets, see Snippets. Snippets offer the following features:

• 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:

When you insert this snippet, your cursor will be inside the ID attribute. Then when you hit tab it will move between the paragraph tags, and when you hit tab a final time will move outside the paragraph.

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

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’ and a third will take the cursor outside the paragraph. 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:

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:

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”.

Further documentation on the available flags and other advanced transformation techniques is forthcoming.

Snippet variables

You can use several variables for snippets 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/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:

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

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:

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:

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.

Where to install Sugars

Sugars live here:

To access your Library folder in Lion, hold down option while you click the Go menu in the Finder, and then click the Library item. Alternatively, run this in Terminal to permanently unhide your Library folder:

If the Sugars folder does not exist, create it. Inside create a folder named whatever you want your sugar to be called; for instance MySugar.sugar.

To open your new Sugar, right click on it and choose Show Package Contents. A new window will open in the Finder. This is where you will need to create your Sugar files and folders; we will refer to it as the root Sugar folder throughout this wiki.

Required files

The Info.plist file is the only required file for a Sugar, and should live inside of a Contents folder. To get started with a new Sugar:

1. Create your Sugar folder as per above
2. Inside your root Sugar folder, create a folder called Contents
3. Inside the Contents folder, create a plain text file called Info.plist

Info.plist is a standard Mac OS X file. You can create it with a plist editor, or just edit it in Espresso. Here are example contents:

Download basic Sugar template

You now have a fully-functioning Sugar (albeit one that adds nothing to Espresso)! If you relaunch Espresso, your Sugar will be silently loaded. In order to add functionality, you now simply need to add XML files for LanguageSugars, CodeSense, JavaScriptActions, or similar.

Full Sugar structure

The folders and files inside of a Sugar use the following names and structure. Directories are suffixed with a / character, * is a wildcard for filenames, and bold items are required for all Sugars:

• MySugar.sugar/
  • CodeSenseLibraries/
    • *.xml
  • CodeSenseProviders/
    • *.xml
  • Contents/
    • Info.plist
    • Resources/
      • *.lproj/
        • Localizable.strings
  • ContextualSettings/
    • *.xml
  • FileActions/
    • *.xml
    • *Categories.xml
    • *Sorting.xml
  • Itemizers/
    • *.xml
  • Languages.xml
  • PlaceholderThemes/
    • *.css
  • ScriptLibraries/
    • *.js
  • Scripts/
    • *.js
  • Syntaxes/
    • *.xml
  • SyntaxInjections/
    • *.xml
  • TextActions/
    • *.xml
    • *Categories.xml
    • *Sorting.xml

Languages.xml, Syntaxes, SyntaxInjections, Itemizers, PlaceholderThemes, and ContextualSettings are all used for LanguageSugars.

CodeSenseLibraries and CodeSenseProviders are used to define new CodeSense auto-completions.

Scripts, ScriptLibraries, and TextActions are used for JavaScriptActions.

TextActions and FileActions can both be used to create custom actions with the CocoaAPI.

Localizable.strings files make it easy to translate your Sugar’s user-facing strings into multiple languages.

Development tips

An easy way to work on Sugars without needing to be constantly right clicking them in the Finder is to name your Sugar folder without a .sugar extension, and then create a symlink to it in your Sugars folder. For instance, if you have created a sugar folder called MySugar-sugar in your Sugars folder, you could run this in Terminal to make sure Espresso recognizes it:

This also makes it easier to create an Espresso project for your Sugar folder.

Although we try to keep this wiki up to date with documentation for all portions of the Espresso API, 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. You can find the Sugars bundled with Espresso by right clicking on the application, choosing Show Package Contents, and navigating to Contents/SharedSupport/Sugars (make sure not to save anything in there, though, or it will be lost when you update Espresso!).

Localizable.strings files live inside of *.lproj folders in the root-level Resources folder of your Sugar. For instance, your English strings will live here:

Syntax

Localizable.strings files are plain text files that use the following syntax:

Most commonly, you will be localizing the titles for your ActionXML files. In this instance, if you have an action with the ID “com.mydomain.mysugar.text-actions.action-name” then you would have the following entry in your Localizable.strings file:

If you are localizing a different element, you will append something other than “title” to the action ID.

Basic layout

JavaScript actions are made up of up to three parts:

1. The XML definition that tells Espresso how to present the action to the user
2. The JavaScript action file, which lives in the Scripts folder
3. Optional additional JavaScript files to share logic between multiple actions using ScriptLibraries

Most of the things you can do with the CocoaAPI are possible with JavaScript; notable exceptions are any actions that require custom GUI and FileActions. For an API reference, see the JavaScriptAPI.

XML action definitions

JavaScript actions use the same XML syntax as all other actions, but instead of associating a <class> with the action, they have a <script> element:

The file referenced in the <script> element must be saved in the Scripts folder in your Sugar. Note that there are several elements you can use that are not shown in this example; see the ActionXML documentation for details.

The contents of the <setup> element can be arbitrarily named elements that are strings, or other data formats using plist formatting.

JavaScript action syntax

Within your JavaScript action you will be provided with a root-level action object that you can use to create the logic for your action. The most basic actions will include a single function:

The context parameter will be a TextActionContext object provided by Espresso for the current document. The outError parameter is currently a placeholder, but will likely be used by the system in future updates.

To access the contents of your action’s <setup> element, you will use the action.setup object. For instance, the JavaScript for the above XML example might do something like this:

The action.setup object is read-only.

In addition to performing your action with a given context, you can also specify custom logic to determine if your action applies to a particular context, or to give it a different title in different contexts. To do so, you will add two additional functions to your action object:

If you are using titleWithContext, you can additionally return a string formatted like @key to use the title associated with “key” in Localizable.strings. For instance, for the action above returning “@multiple” from the titleWithContext would use the *.title.multiple key:

JavaScript Libraries

If you are coding more than one JavaScript action that shares similar logic, you can gather it all into a JavaScript library. To do so, create a new JS file in the top-level ScriptLibraries folder:

Inside of your library, you can create whatever functions and variables that you need, and then assign the functions you need access to the global library object:

Then in your JavaScript action code, load in your library and use it like so:

CETextRecipe objects allow you to create recipes of changes to apply to a document via the TextActionContext object. By queuing up your changes in a recipe and applying them all at once, you do not have to worry about manually adjusting ranges to take into account previous insertions or deletions.

CETextRecipe()

The CETextSnippet constructor takes no arguments:

Properties

coalescesChanges

Returns true or false; whether or not this recipe groups its changes. Defaults to true.

Set to false if you wish to have each change in the recipe applied individually (may decrease performance).

undoActionName

Returns the string that will be shown in the Edit menu’s Undo item.

Most actions are automatically assigned an undo name, but if for some reason you need to change it you can set this to customize the undo name for the action.

Methods

replaceRange(range, string)

Returns void; replace the Range range with the string string when the recipe is applied.

insertAtIndex(index, string)

Returns void; insert the string string at the numerical character index index when the recipe is applied.

deleteRange(range)

Returns void; delete the Range range when the recipe is applied.

##Espresso

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

Clients

There are multiple viable IRC clients for Mac OS X. Here are a couple popular ones:

• Colloquy
• Linkinus

Who’s who

If you run across ianbeck in IRC, you are talking to the fellow responsible for QA and support for MacRabbit.

Although sightings are extremely rare, if you find yourself talking to CaptainNeutrino, then you have discovered Jan Van Boghout, the head honcho of MacRabbit.

We do not officially offer support through IRC, but time willing are happy to answer questions about Sugars or other aspects of Espresso. If you have something you definitely need a response to, you should email use using Help→Send Feedback in Espresso.

However, the sheer number of files containing the API may be a bit daunting at first. Here’s a breakdown of what files to look at based on types of actions you may wish to create.

EspressoActions.h
This file defines the protocol that your classes must support for text and file actions.

EspressoSDK.h
You can safely ignore this file; it doesn’t appear to actually define any API elements.

Text Actions

EspressoTextActions.h
This file contains the definition of the text action context that is passed to your custom classes. This class is your primary gateway to the other portions of the Espresso API; when looking through it you should make note of the types assigned to various objects and methods, as those will contain the main methods you’ll use to interact with the context object’s information.

EspressoTextCore.h
As of this writing, this contains four classes:

• CETextRecipe: an interface for working with text recipes. Text recipes allow you to queue up changes to the current document text without needing to worry about adjusting range offsets. You will use text recipes whenever you need to insert or delete text, and you can initialize new text recipes in your code as needed.

• CETextSnippet: a class for instantiating snippet objects (for use with [context insertTextSnippet:snippet]).

• CELineStorage: a class for working with the lines in a text document. You cannot instantiated a line storage element; it is purely there for reference when working with lineStorage.

• CETextPreferences: a class for working with [context textPreferences]. This is another that is there purely for reference.

EspressoSyntaxCore.h
This file contains all of the classes for working with Espresso syntax zones. The Example Cocoa Sugar contains an example of using syntax zones to manipulate text.

EspressoDocumentActions.h
Similar to file action contexts below but only applying to a single document, this class contains methods for working with the [context documentContext]. As of this writing, it does little more than provide a URL for accessing the file.

MRRangeSet.h
Contains the MRRangeSet class, which makes working with multiple ranges easier. None of the Espress objects that I’ve found return a range set; the class is purely a convenience for use in your own code.

NSString+MRFoundation.h
This contains convenience methods for working with strings, and is another example of useful utilities provided by MacRabbit for use in your own code.

File actions

EspressoFileActions.h
This file defines the interface for file action contexts. As of this writing, this provides little more than a list of URLs for selected files.

Itemizers

EspressoItemizer.h
I am unfamiliar with how itemizers function, but this appears to be the class you need to override in order to create custom itemizer definitions. Note: if Jan or someone else who is familiar with itemizers could expand on this, I’m sure folks would appreciate it.

EspressoItemizerCore.h
Again, I’m not familiar with itemizers, but as best I can tell this file defines useful classes for creating your custom itemizer definitions. It also contains CEItemizer, which you can access from text action contexts.