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

Espresso 2.0

For the most part, Sugars should be backwards compatible between Espresso 1.0 and 2.0. However, the following changes may affect your Sugar (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 Sugars. 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 Sugars

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

Changes to specific Sugars:

  • JavaScript.sugar: completely rewritten; about the only thing it shares with the Espresso 1.0 version is the name
  • PHP: almost all aspects of this Sugar have been rewritten, including the Sugar’s bundle identifier (it is now an official first-party Sugar rather than a trusted third party sugar). Open source versions of this Sugar will no longer override the PHP.sugar, and share very little code with it.
  • Ruby: all-new support for Ruby
  • Python: all-new support for Python
  • Apache config files: all-new support for Apache config files (.htaccess, etc.)
  • Markdown: all-new support for Markdown documents
  • TEA for Espresso: as per above, TEA Python actions are removed. Additionally, it is no longer possible to define actions based on TEA actions but with different XML setups (Espresso will only search for the named action in your Sugar’s bundle). Custom user actions stored in ~/Library/Application Support/Espresso/Support will no longer work. You will need to package any custom actions into a Sugar.


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

  • Actions and some other elements can now use <language-context> in addition to or instead of <syntax-context>; see ActionXML
  • ContextualSettings can be used to tweak things such as the syntax for comments
  • Localizable.strings files are recommended instead of <title> elements
  • SyntaxInjections can now include common zones within a <library> element; see Syntaxes
  • SyntaxInjection selectors can target other injections; for instance, if you inject a new zone that bundles subzones from a first-party Sugar, you could modify those subzones within your injection with a later injection’s selector like “ common.subzone”