Recent Changes

Although we try to keep the plug-in system backwards compatible, sometimes we make changes that will require updating your plug-in.

Espresso 3.0

Plug-ins should remain backwards compatible between Espresso 2.0 and 3.0. However, there are a number of changes and additions you may wish to take into consideration:


Rather than continuing to refer to plug-ins as "Sugars", we are now switching to the more generic and easily understood "plug-in". The .sugar file extension is deprecated in favor of .espressoplugin, and may be removed in the future. Plug-ins will now be automatically installed in this folder:

~/Library/Application Support/Espresso/Plug-Ins/

XML files

Itemizer XML has been completely overhauled (old syntax will continue to work, but is deprecated and may be removed in a future update):

x-espresso URL scheme

A new URL scheme has been added to allow you to open arbitrary files within Espresso, and optionally select particular lines or ranges.

Espresso 2.0

For the most part, plug-ins should be backwards compatible between Espresso 1.0 and 2.0. However, the following changes may affect your plug-in (some of these were available in 1.0 but are being officially exposed for the first time in 2.0):


Espresso 2.0 offers all-new JavaScriptActions for easily writing TextActions without needing compiled code. The bundled TEA for Espresso.sugar has been converted to run mainly using the new JavaScript API, so take a look at its source for some excellent examples, or take a gander at the API documentation.

TEA Python actions have been removed. Any Python actions using the TEAforEspresso class will need to be ported to JavaScript or Objective-C. For the time being, the TEALoader class remains, so you can continue to leverage actions in arbitrary shell languages using STDIN and STDOUT.

The third party Spice.sugar is no longer supported. You will need to port any actions using the Spice class over to the built-in JavaScript API.

API changes

It is no longer possible to define custom Itemizer classes for third party plug-ins. If you have a need that is not being covered by existing Itemizer classes in Espresso, please let us know.

CETextConvertingOptions has been deprecated in favor of CETextOptions; see EspressoTextCore.h for details.

CETextRecipe's addReplacementString:forRange:, addInsertedString:forIndex:, and addDeletedRange: methods have all been deprecated in favor of the simpler replaceRange:withString:, insertString:atIndex:, and deleteRange: methods.

CELineStorage's pass-by-reference lineNumber attribute in the lineStartIndexForIndex:lineNumber: method has been deprecated.

First-party plug-ins

First-party plug-ins use completely different root syntax zone names (text.basic.html ⟩ language-root.html, for instance). If you are extending a first-party plug-in, you will need to update your plug-in or theme to use the new naming schemes and syntax zones.

Changes to specific plug-ins:


Themes now use a special :document-base selector instead of @base for styling the root document; see SyntaxThemes. The @base selector is deprecated, and may be phased out in future updates.

XML files