A Sugar is a normal folder with a
.sugar extension. Inside that folder, you will create specifically named folders and XML files depending on what you want your Sugar to do.
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:
chflags nohidden ~/Library/
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.
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:
- Create your Sugar folder as per above
- Inside your root Sugar folder, create a folder called Contents
- 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:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<!--Modify these for your Sugar-->
<!--No need to modify these values-->
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:
Languages.xml, Syntaxes, SyntaxInjections, Itemizers, PlaceholderThemes, and ContextualSettings are all used for LanguageSugars.
CodeSenseLibraries and CodeSenseProviders are used to define new CodeSense auto-completions.
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.
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:
cd ~/Library/Application\ Support/Espresso/Sugars
ln -s MySugar-sugar MySugar.sugar
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!).