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:

Naming

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

• The term "recipe" has been replaced with "item":
  • <recipe> tag renamed to <item>
  • <subrecipes> tag renamed to <subitems>
  • <include-root-recipes/> tag renamed to <include-root-itemizers/>
• The term "selector" has been replaced with "zone":
  • <selector> tag renamed to <zone>
  • <start-selector> tag renamed to <start-zone>
  • <end-selector> tag renamed to <end-zone>
• New: language-context attribute has been added to the root-level <itemizer> tag
• New: <start-zones> tag can be used instead of <start-zone> with an "itemizer-firstused" capture group for most cases, as it captures all top-level sibling zones (instead of capturing the final zone as <start-zone> does)
• New: <end-before-zone> tag can be used to define a zone that will act as a cut-off for the itemizer; in conjunction with <end-zone> this allows you to support things like optional end tags in HTML
• New: itemize-subzones="true" attribute can be added to <zone> tags to allow itemization within the final zone within a selector

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

Actions

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:

• 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 plug-in have been rewritten, including the plug-in's bundle identifier (it is now an official first-party plug-in rather than a trusted third party sugar). Open source versions of this plug-in 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 plug-in'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 plug-in.

Themes

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 ActionsXML
• 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 plug-in, you could modify those subzones within your injection with a later injection's selector like "my.injection.id common.subzone"