I am extremely happy to announce that my Text Editor Actions for Espresso (or “TEA” for short) has at last been released as version 1.0. Version 1.0 is available for download, or you’ll also find it bundled in the upcoming Espresso 1.0.7.

So just what the heck is TEA for Espresso? Simply this:

1. A selection of my favorite text actions, mostly (but not entirely) copied from Textmate
2. Generic actions that allow you to create variations on TEA’s bundled functionality to suit your workflow by editing simple XML
3. A general framework for coding and running text actions in arbitrary languages without needing to create a Sugar or (for third party Sugars) without needing compiled Objective-C classes

Espresso’s Sugar API was already pretty sweet. TEA makes it that much better by lowering the barrier to creating custom text actions for users and Sugar developers alike.

Documentation for TEA is currently limited to info on creating your own actions, so I’ll walk you through the basic actions included with the plugin.

The vast majority of TEA’s built-in actions focus on making HTML easier to edit, because editing HTML is most often why I need a text editor.

Generic text actions

Spaces To Tabs… and Tabs To Spaces…
As you might expect, these actions convert the type of indentation in your document or (if it exists) your selected text. When you run the actions you’ll be prompted to enter the number of spaces per tabs you wish to use (it defaults to whatever is in your Espresso preferences, so you can just hit enter most of the time).

Trim Line(s)
Trim Line(s) will, when invoked, either trim all of the lines in your selection or the current line the cursor is on (if no selection exists). Unlike some trim lines actions, TEA’s Trim Line(s) attempts to be smart about what whitespace it removes:

• All whitespace at the end of the line will be stripped
• Any whitespace at the beginning of the line that isn’t part of the indentation will be stripped

What the latter means is that if in the Espresso preferences you have the program set to use spaces instead of tabs with four spaces per tab, and the beginning of a line has ten spaces, two of the spaces will be stripped.

Select → Word, Select → Line, Select → Line Contents
As you might expect, these actions select the word under the cursor, the line under the cursor (including leading and trailing whitespace), or the textual contents of the line under the cursor (excluding leading and trailing whitespace), respectively.

Sorting → Sort Lines (Ascending) and Sorting → Sort Lines (Descending)
As you might expect, these actions sort all lines in the selection (or document, if no selection) in ascending and descending order, respectively.

Sorting → Randomize Lines
This randomly sorts all lines in the selection (or document, if no selection).

Sorting → Remove Duplicate Lines
If for some reason you need to strip all duplicate lines from your selection or document, this is the command for you.

Formatting commands

Indent New Line (command-shift-enter)
One of my favorite parts of Textmate is that after creating an HTML tag, I only have to hit enter once to get a perfectly indented tag pair with the cursor in between and bumped in a level. The fact that Espresso doesn’t do this irks me greatly, and so this action allows you to force the issue. Indent New Line will turn this (pipe represents cursor):

<div>|</div>

Into this:

<div>
    |
</div>

If you have any text selected when you run the action, the selected text will be moved to the middle line and indented.

Insert Linebreak(s) (control-enter)
In HTML, Insert Linebreak(s) will insert a break tag (<br />). In some other contexts (like PHP double quoted strings), it will insert \n. In Markdown it will insert two spaces and a linebreak. If you have one or more selections, the tag or textual linebreak will be inserted at the end of each selection.

In case you didn’t quite catch that, Espresso allows you to have multiple selections (hold down command while you select multiple items with your mouse), and this action will affect all of them. This is extremely cool, and one of the features that I’m still learning to use; before now, I’d never come across a text editor that allowed me to so much as select multiple items at once. Of course, it isn’t all that often that you need to append br tags in a whole bunch of places around a document, but what about when you want tags for…

Strong (command-B) and Emphasize (command-shift-I)
These do about what you’d expect. If you have one or more selections, they’re surrounded with strong or em tags. If no selection, you get a tag wrapping your cursor. Incidentally, if you’re working with a single selection (or no selection) you’ll get a text snippet with tab stops, so hit the tab key to edit what’s inside the tag.

A note on Emphasize’s shortcut; command-I by default is used to show and hide the navigator sidebar, hence this somewhat odd shortcut for italics. If you wish to switch the shortcuts, you can do so through the System Preferences Keyboard & Mouse controls.

HTML actions

Entities → Convert To Named Entities (control-&) and Entities → Convert To Numeric Entities
Run one of these actions to have the character immediately to the left of the cursor converted from Unicode into an HTML character entity. If you have one or more selections, all non-ASCII Unicode characters will be converted to entities of the desired variety. If using named entities, Unicode characters without a named entity will still be converted to their numeric equivalent. These actions will also convert ampersands (but will ignore ampersands that are already part of an entity).

Entities → Insert Non-Breaking Space, etc.
Use these actions to quickly insert the named HTML entity for the given character.

Expand Abbreviation (control-,)
This action is much like Textmate’s “Insert Open/Close Tag (With Current Word)” which, when I saw it demoed in a screencast, changed my life. For far too long had I been toiling away, typing out every blessed less than/greater than symbol. With Expand Abbreviation, I merely type the HTML tag, hit the shortcut, and voilà. I have the complete tag ready to go with barely any effort at all.

And the fun doesn’t stop there! The reason for the action’s name change is that Expand Abbreviation is powered by the fantastic zen coding project, so in addition to Textmate’s functionality Expand Abbreviation offers the full range of zen coding abbreviations and CSS-selector style syntax to create complex markup from very simple declarations. Here’s a quick example of zen coding’s awesomeness:

div#stuff.things.booyah

Type that, hit control-, and you’ll end up with this (pipe represents cursor):

<div id="stuff" class="things booyah">|</div>

Or if you want to do something a little more complicated:

div#nav+div#content>p.item$*2

Which leads to this:

<div id="nav">|</div>
<div id="content">
	<p class="item1"></p>
	<p class="item2"></p>
</div>

And that’s just the tip of the iceberg. Zen coding offers numerous other selectors and scads of abbreviations for HTML and CSS. All of them will work with Expand Abbreviation.

You may also, if you need, use the old Textmate-style tag creation where you type out everything in the tag except the carets, highlight it, and run it through Expand Abbreviation to get a full tag. For instance, this:

div style="width:100%;"

Once selected and run through Expand Abbreviation leads to this markup:

<div style="width:100%;">|</div>

If there is no selection, this action will use the current word regardless of where the cursor falls in it (Textmate will only parse to the left of the cursor).

Wrap Selection In Tag (control-shift-W)
As you might expect, if you select some text and invoke Wrap Selection In Tag, the selection will be wrapped in an HTML tag. Just like in Textmate, you can type out tag attributes and they won’t be mirrored to the closing tag, and moving outside the tag is a tab away.

Wrap Selected Lines In Tag (command-control-shift-W)
This one acts just like Wrap Selection In Tag, except that each line in the selection is wrapped.

Wrap Selection In Link (control-shift-L)
Unsurprisingly, selecting some text and invoking this command will wrap it in an HTML link tag. What makes this action more worthwhile than some of the others is that if you have a recognizable link on your clipboard it will be inserted, and there are several tab stops set up to make removing or editing the link’s title extremely easy. Unlike Textmate, this action does not attempt to populate the title from the actual webpage’s title. I’ve had Textmate hang while it waits to retrieve the webpage too many times to want to implement that functionality myself.

If you use this action while editing Markdown or Textile, the selection will be wrapped in a Markdown or Textile link rather than an HTML anchor.

Documentation For Tag (control-H)
If your cursor is inside an HTML tag, you can run Documentation For Tag to have the word under the cursor (or the selection) searched for in HTMLHelp.com’s HTML reference. If the cursor is inside an HTML tag, you’ll be taken straight to the first result (almost always the correct tag page). Otherwise, you’ll get a Google result listing.

TEA Preferences

TEA → Preferences offers a GUI to modify some TEA-related preferences. You’ll need to have a document open in order to access the prefs due to limitations in how Espresso sets up actions.

General Prefs
Checking “use XHTML by default” will cause TEA-based snippets that use the $E_XHTML variable to leave it blank. At some point in the future, TEA will hopefully be more intelligent about detecting whether a document is HTML or XHTML, but for now you’ll need to control it using this preference.

Similar to Textmate, anything entered in the Custom Shell Variables section of the preferences will be available as an environmental variable to any shell scripts you run through TEA. For instance, if you add a variable with the name “MY_CUSTOM_VARIABLE” and the contents “I love TEA!” then wherever you use the shell environmental variable $MY_CUSTOM_VARIABLE you’ll get “I love TEA!”

Actions
If you check “Enable custom user actions” you will be able to create custom actions without needing a custom sugar. This is useful not only for custom TEA-based actions, but for custom actions using third party sugars, as well.

Beyond the bundle

If TEA’s included actions aren’t enough for you, it’s extremely easy to add your own custom actions, port actions from Textmate bundles, and otherwise use TEA to jumpstart your own Espresso customizations. The TEA for Espresso wiki has lots of info on this sort of thing, or you can take a look at the HTMLBundle.sugar’s source for an example of porting Textmate snippets and bundle items (the HTMLBundle.sugar may also be of use to other folks who want Textmate’s HTML tab completions, among other things; download it here).

I’m also usually available in the forums or Espresso IRC channel if you have questions about using TEA, feature requests, bug reports, or other comments. Alternatively if you have a GitHub account, you can file bug reports and feature requests directly into the TEA for Espresso Issues tracker.

I hope you enjoy TEA with your Espresso!