Handy.sugar and Espresso 2’s JavaScript API

Although you are likely aware if you follow my antics online, we at MacRabbit released Espresso 2.0 recently. Whoo hoo!

A whole lot of things are new and improved in Espresso 2, but hands-down my favorite feature is the new Javascript API, which allows you to add custom text actions to the editor using web languages you already know: XML and Javascript. This is seriously awesome; back in the days of Espresso 1.x I created Spice.sugar to allow coding text actions in Javascript, but it was a hack that I was never completely happy with. The new Javascript API is something of a spiritual successor to Spice.sugar, except without the suckiness. It is simpler, better documented, and is true Javascript (rather than Objective-C methods contorted into Javascript).

Sadly, I don’t think people realize how awesome the new Javascript API is, so in the hopes of making people’s lives better and raising awareness for it, I present to you Handy.sugar:


Every so often someone writes in to MacRabbit with a feature request that I think is awesome, but which I doubt Jan will want to integrate in the core editor for whatever reason (or that I think he probably will implement, but is currently a low priority). Of course, this was exactly why Jan implemented the Sugar system in the first place: Espresso will never support a broad enough range of actions to make everyone happy out of the box, but it is ridiculously easy to extend.

And so was born Handy.sugar: a collection of some of my favorite feature requests I’ve read at MacRabbit recently, with a focus on actions that allow you to keep your hands on the keyboard.

I am still adding things to Handy.sugar, but here are my current two favorite features (all of the visible features that Handy.sugar adds will show up in the Actions→Handy menu, so you can explore others on your own).

Keyboard of coding +1

Handy.sugar’s actions for incrementing and decrementing numbers in your code are what prompted me to create the Sugar in the first place.

Using the actions is super easy: move your cursor next to a number, and hit command option ↑ to add 1 to the number. As you might expect, command option ↓ decreases it by 1. Add the shift key, and you’ll move up or down in increments of 10.

But wait, there’s more! The incrementing/decrementing actions are smart enough to also handle the following situations:

  • If you select a swathe of text that has a number somewhere in it, the action will affect that number
  • If you select a swathe of text with multiple numbers in it, the action will affect all of them
  • If you have multiple selections, the action will affect any numbers in them (as long as the first selection contains a number; otherwise the action will not be enabled)

For the moment, you can only modify base 10 integers using these actions. I thought about implementing something similar for hex or octals, but thanks to formatting differences across languages could not come up with a good “one size fits all” approach. You can modify floats, but only the portion before the decimal point will be modified. Transitioning between positive and negative numbers should work exactly as you would expect.

Multiple selections for fun and profit

Creating multiple selections in Espresso is easy (it works just like it does elsewhere in Mac OS X):

  • Hold down the option key, then click and drag to create a column of selections
  • Hold down the command key, and select things with your mouse in multiple places (by double clicking words, triple clicking lines, clicking and dragging, etc.)

But once you have multiple selections, Espresso unfortunately only really supports deleting all of them at once. Until you install the Handy.sugar, that is:

  • Hit control [ to prepend text to all selections
  • Hit control ] to append text to all selections
  • Hit control \ to replace all selections

(Incidentally, if you opt not to type anything after invoking that last shortcut, it will instead replace all selections with the contents of your first selection, which might be useful in its own right.)

If you have been missing column selections from Textmate or block editing from Coda, these actions will likely make you very happy since they perform basically the same functions.

Not just a useful tool

Handy.sugar offers a bunch of useful functionality, of course, but hopefully it will also serve as an example of the kinds of things you can accomplish with the JavaScript API. You can check out exactly how I am accomplishing any given action by right clicking on Handy.sugar in the Finder and choosing “Show Package Contents” or by browsing the source on GitHub. I tried to keep it pretty well commented.

If you decide you would like to try your hand at your own custom Sugar actions using the JavaScript API, check out the introduction to JavaScript actions and then take a gander at the JavaScript API reference.

And if you do undertake some Sugar development, you can always email MacRabbit for help or look for aid in our Sugar developer forums.

3 responses to “Handy.sugar and Espresso 2’s JavaScript API”

Leave a response

  1. Arturo says:

    WOW, thanks a LOT. Handy is really really useful…

  2. Patrick Gilmour says:

    Brilliant. MacRabbit really need to get a stronger message out there about just how incredible – and elegant – Espresso is. Add Sugar and it’s better still. Handy is one the best – thanks Ian!

Leave a response