Generic Action API

This page outlines all of the available generic TEA actions and their options for use in your action XML definitions.

Formatting for this API is as follows:

example_action

The description of what example_action does will live here.

first_option (string : ‘example’)

First option’s description lives here

second_option (bool : true)

Second option’s description follows here

default (string : ”)

The default insertion if no matching syntax is found.

Standard options

undo_name
syntaxes

For the above example, your action’s XML might look like this:

<action id="com.onecrayon.ExampleAction" category="my.category.id">
    <class>TEAforEspresso</class>
    <title>Example Action</title>
    <setup>
        <action>example_action</action>
        <options>
            <dict>
                <key>first_option</key>
                <string>Something other than 'example'</string>

                <key>second_option</key>
                <false />

                <key>default</key>
                <string>The insertion that's used by default</string>

                <key>undo_name</key>
                <string>My Example Action</string>

                <!-- This type of option is available if syntaxes are supported -->
                <key>html, html *</key>
                <string>HTML-specific insertion goes here</string>
            </dict>
        </options>
    </setup>
</action>

Standard options and variables

undo_name (string : None)

A standard option included in almost all of the actions; whatever you pass here will be placed in the Edit menu after the word “Undo” (for example, if you pass “Insert Tag” the Edit menu will read “Undo Insert Tag”).

syntaxes (string : None)

You can pass in any number of options where the key is the syntax identifier and the string is a syntax-specific alternative which will be used if the context’s syntax matches the selector when the action is run. See the above example code for a simple example.

Additionally, TEA uses several dollar-delineated variables as placeholders in generic actions. Most of these are specific to a given action, but $EDITOR_SELECTION is used in a lot of the actions as a placeholder for the selected text that is passed to the action. If an option supports $EDITOR_SELECTION, it will be noted. Please note: the old $SELECTED_TEXT variable is deprecated and may be removed in a future release. Please convert your old actions.

$E_XHTML is also supported by all snippet actions. Place the $E_XHTML placeholder anywhere you want filled with a self-closing slash (you can specify the specific string you wish to use, or if you want to default to plain HTML, in the TEA Preferences).

Single selection methods

insert_snippet • insert_text • insert_url_snippet • selected_lines_to_snippet • word_to_snippet

insert_snippet

Inserts a snippet at the user’s cursor; useful for tab completions if you don’t like Espresso’s snippet GUI.

default (string : None)

The default snippet to be used if none of the passed syntaxes match; supports $EDITOR_SELECTION

Standard options

undo_name
syntaxes (supports $EDITOR_SELECTION)

insert_text

Inserts arbitrary text over all selections.

default (string : None)

Plain text replacement for selected text; does not support $EDITOR_SELECTION

prefix_selection (bool : false)

If true, the inserted text will be placed before the selected text rather than replacing it

suffix_selection (bool : false)

If true, the inserted text will be placed after the selected text rather than replacing it

Standard options

undo_name
syntaxes

Special placeholder variables

$TOUCH

If the text you wish to insert consists entirely of whitespace, you can place the $TOUCH variable anywhere in your insertion strings to force Espresso to interpret the whitespace (by default, it will discard whitespace if there aren’t any other characters). $TOUCH is always stripped out of the final insertion.

Special notes: both prefix_selection and suffix_selection may be true to surround the selection; if the selection is empty, however, only one copy will be inserted.

insert_url_snippet

Replaces selected text in a snippet that has access to the URL on the clipboard.

default (string : None)

The default snippet to be used; supports $EDITOR_SELECTION. Also supports $URL, which will be replaced with the clipboard’s contents if they appear to be a URL.

fallback_url (string : ”)

The string used as the fallback if the clipboard’s contents don’t appear to be a URL

Standard options

undo_name
syntaxes (supports $EDITOR_SELECTION and $URL)

selected_lines_to_snippet

Replaces each line in the current selection with a snippet.

first_snippet (string : ”)

This snippet will be used for the first line; supports $EDITOR_SELECTION, which represents the contents of the first line (not the whole selection)

following_snippet (string : ”)

This snippet will be used for all lines after the first; supports $EDITOR_SELECTION, which represents the contents of each line

final_append (string : ”)

This snippet will be appended to the end of the selected text (useful to place $0, for instance)

Standard options

undo_name

word_to_snippet

Converts the word or selection under the cursor into a snippet.

default (string : None)

The default snippet to be used; supports $EDITOR_SELECTION, which will be either the selection, or the word under the cursor if no selection. Also supports $WORD, which will be the first word in the selected text if there is a selection, and if not is the word under the cursor.

alpha_numeric (bool : true)

If false, the word will be defined as alphabetic characters + extra_characters; if true, the word can be alphanumeric + extra_characters

extra_characters (string : ”)

Non-alphanumeric characters that should still be counted as word characters; for instance ‘_-‘

mode (string : None)

Accepts zen or html. If set to zen, word/selection will be run through zen coding. If set to html, word/selection will be converted to an HTML tag a la Textmate’s Insert Open/Close Tag (For Current Word).

Standard options

undo_name

Multiple discontiguous selection methods

selections_to_snippets • selections_to_text

selections_to_snippets

Currently only accepts a single selection: will handle multiple discontiguous selections if/when that becomes available in the Espresso API

Wraps the currently selected text in a snippet.

first_snippet (string : ”)

This snippet will be used for the first selection; supports $EDITOR_SELECTION, which represents the first selection, not the combined selected text

following_snippet (string : ”)

This snippet will be used for any selections after the first; supports $EDITOR_SELECTION

final_append (string : ”)

This will be appended to the final selection

Standard options

undo_name

selections_to_text

Formats the selected text by wrapping it in the passed segment. Will use an automatically formatted snippet for a single selection, or a simple text replacement for multiple selections.

default (string : None)

Plain text replacement for selected text; supports $EDITOR_SELECTION

Standard options

undo_name
syntaxes (supports $EDITOR_SELECTION)

Miscellaneous

balance • encode_unicode • goto • sort_lines • trim • visit_url

balance

Attempts to locate the balanced delimiters around the cursor and select their contents.

direction (string : ‘out’)

Which direction you want the balancing to move; accepts in and out

mode (string : ‘auto’)

Accepts auto, zen, and itemizer. If auto (the default), it will try to detect if the current context is HTML or XML, and if so will use zen coding’s tag balancing algorithm. If zen, zen coding will always be used regardless of context. If itemizer, Espresso’s itemizer system will always be used regardless of context.

encode_unicode

Converts unicode characters in selection (or character preceding the cursor) into various types of ASCII strings.

type (string : ‘named’)

The type of conversion to perform; accepts named (named HTML entities), numeric (numeric HTML entities), or hex (4 character hex codes)

wrap (string : ‘$HEX’)

Allows you to wrap the hex code in a snippet; support $HEX for the outputted hex code. For instance, \u$HEX would lead to something like ‘\u022’. This option only applies if you are using type == ‘hex’.

Standard options

undo_name

goto

Attempts to go to (select) a location in the document.

target (string : None)

What to look for; may be text or if omitted will cause whatever is set as the source to be selected

source (string : None)

Where to gather the initial string; valid options include word (the word under the cursor) or line (the line under the cursor). If omitted this defaults to the current selection.

trim (bool : false)

Whether or not to trim the source of trailing whitespace

discard_indent (bool : false)

Only applicable if trim == true; if true, will trim all leading whitespace in the source

search_string (string : None)

The string to search for if target == ‘text’; supports $EDITOR_SELECTION, which will be replaced by the contents of the source

regex (bool : false)

If true, search_string will be evaluated as a regex expression

sort_lines

This only allows a single selection (enforced through the utility functions) then sorts the lines, either ascending or descending.

direction (string : None)

The direction to sort the lines in; accepts asc, desc, and random

remove_duplicates (bool : false)

If true, will remove any duplicate lines from the results

Standard options

undo_name

trim

Trims the text; what is trimmed depends on the options specified.

input (string : None)

Dictates what should be trimmed: selection (only trims beginning and end of selection, even if there are multiple lines in it) or selected_lines (trims each line in selection)

alternate (string : None)

What to fall back to if input == None or the chosen input is blank; supports line (trims the line the cursor is on) or all_lines (trims all lines in the document)

trim (string : ‘both’)

Sets which side of the text to trim; accepts both, start, or end

respect_indent (bool : false)

If set to true then any existing indentation at the beginning of the line/selection will be left alone (what determines indentation is defined in the Espresso preferences)

Standard options

undo_name

visit_url

Visits a URL, filling a placeholder with selected text (or similar).

input (string : None)

Dictates what fills the placeholder $EDITOR_SELECTION in the URL if there is no selected text; accepts word (the word immediately under the cursor) or line (the line under the cursor)

default (string : None)

The URL you want loaded by default; accepts $EDITOR_SELECTION, which will be the selection or whatever is specified in input if no selection

Standard options

syntaxes (supports $EDITOR_SELECTION)

← Overriding Scripts • Table of Contents • Python Utility Functions Module →