homepage • source code

Getting started with TEA

If you are looking into TEA for the first time, a great place to start is to play around with the bundled actions. Aside from providing a suite of tools that can speed up and simplify your editing workflow, the bundled actions are an excellent example of the kind of actions that TEA is best at helping you create. If you are interested in creating your own custom actions, then you may be more interested in the developer’s reference.

Bundled actions

TEA’s bundled actions come in two main flavors:

  • General actions for selecting text, sorting lines, or converting between different indentation types
  • HTML actions specifically tailored to supercharging your HTML editing

Custom actions

If you are interested in modifying Espresso with your own custom actions, there are a few different places to start:

  • TEA Preferences describes how to enable custom actions, and the caveats of working with custom actions
  • Custom action support folder offers info on the layout of the Support folder that TEA custom actions use
  • Action XML definitions documents the syntax of TEA TextAction XML files
  • Python action syntax examines the required syntax for Python actions loaded through TEA
  • Shell scripts discusses the special XML syntax for working with TEALoader, TEA’s method for executing non-Python scripts
  • Overriding scripts contains information on where TEA searches for scripts, and how to override the functionality of bundled scripts in TEA or other Sugars

Developer reference

Once you have a handle on the basic syntax for creating TEA actions, then you’ll likely be interested in the developer reference materials:

  • Generic action API provides a reference for the built-in TEA actions. You’ll need this if you want to create custom actions using just XML that are similar to TEA’s bundled actions.
  • Python utility functions module describes the functions available in tea_actions, a collection of utility functions useful for jump-starting Python actions
  • Espresso API module discusses how to load in Espresso classes via PyObjC to supplement your Python actions
  • Miscellaneous modules offers information about various miscellaneous items available to Python actions, such as zen coding and the persistent_re class

Pick your poison

The different types of TEA actions (XML-only, shell script, and Python) offer increasing levels of complexity coupled with increasing levels of flexibility. If you have an action in mind, but aren’t sure how best to leverage TEA to bring it to fruition here’s a quick breakdown of the strengths and weaknesses of TEA’s offerings:

  1. XML-only actions are the easiest to create, but the most limited. See the generic action API for a comprehensive list of all actions bundled with TEA, along with descriptions of generally what they can do.

  2. Shell script actions are more powerful (particularly because they can be defined in just about any language you’re comfortable with), but are limited to accepting input text and spitting out new text to replace it with. Shell scripts are thus great for transforming the current word, line, selection, or document, but cannot do things otherwise supported by Espresso’s API like changing the selection.

  3. Python actions are the most powerful of the three and offer the most flexibility, but of course require you know Python and – for more complicated actions – are comfortable with PyObjC so that you can access Espresso’s API directly.

Currently, TEA does not support any custom UI for shell scripts, and custom UI for Python actions is possible but requires you to understand how Interface Builder interacts with PyObjC.

If you need the flexibility of the full Espresso API without the complication of Python, you may also be interested in Spice, which offers full API access using Javascript and a comprehensive library of Javascript classes to make using the Espresso API easier.