Python Utility Functions Module (tea_actions)

The tea_actions module provides numerous functions to make working with Espresso’s API less verbose and annoying. For more complicated actions, you’ll still likely need some PyObjC, but the tea_actions module should make most common operations a lot simpler. Typical usage is:

import tea_actions as tea

# use various actions, for instance:

tea.say(context, "This is a title", "Thanks for using this action!")
tea.log("Some message for the console")

# etc.

In the following reference, formatting is:

function_name argument1 (type), argument2 (type : Default value)

Description of function here.

Return type

Arguments without a default value specified are required, those with a default value are optional. You may use arguments with default values in the order specified, or as keyword arguments.

Functions in tea_actions come in several flavors:

User interactions and logging

say context (TextAction context), title (string), message (string), main_button (string : None), alt_button (string : None), other_button (string : None)

Displays a dialog with a message for the user and an optional three custom-named buttons.

Returns result of sheet

log message (string)

Convenience function for logging messages to console (wraps NSLog). Will automatically turn things into strings, so pass whatever you want to it.

Returns void

Preference lookup shortcuts

get_prefs context (TextAction context)

Convenience function.

Returns the CETextPreferences object with current preferences

get_line_ending context (TextAction context)

Shortcut function to get the line-endings for the context.

Returns line-ending as a string

get_indentation_string context (TextAction context)

Shortcut to retrieve the indentation string.

Returns indentation string

get_xhtml_closestring

Returns the XHTML closing string (based on user preferences; may be an empty string).

Text manipulations and helper functions

parse_word selection (string)

Extract the first word from a selection.

Returns word

string_to_tag string (string)

Parses a string into a tag with id and class attributes. For example, div#stuff.good.things translates into div id="stuff" class="good things". Legacy function; consider using zen coding instead.

Returns converted string

is_selfclosing tag (string)

Checks a tag and returns if it’s a self-closing XHTML tag.

Returns bool

get_tag_closestring context

Tries to determine if the current context is XHTML or not, and returns the proper string for self-closing tags. Currently just defaults to the Espresso preferences setting.

Returns string

encode_ampersands text (string), enc (string : &)

Encodes ampersands as HTML entities. Value of enc is used to replace the ampersands (should be & or & in most instances).

Returns text with ampersands encoded

named_entities text (string)

Converts Unicode characters into named HTML entities.

Returns modified text

numeric_entities text (string), ampersands (string : None)

Converts Unicode characters into numeric HTML entities. If ampersands is named will use & for ampersands; if numeric will use & and if None will not encode ampersands.

Returns converted text

entities_to_hex text (string), wrap (string)

Converts HTML entities into hexadecimal; replaces $HEX in wrap with the hex code.

Returns converted text

trim context (string), text (string), lines (bool : True), sides (string : both), respect_indent (bool : False)

Trims whitespace from the text. If lines is True, will trim each line in the text. sides can be both, start, or end and dictates where trimming occurs. If respect_indent is True, indent characters at the start of lines will be left alone (specific character determined by preferences).

Returns trimmed text

unix_line_endings text (string)

Converts all line endings to Unix.

Returns converted text

clean_line_endings context (TextAction context), text (string), line_ending (string : None)

Converts all line endings to the default line ending of the file, or if line_ending is specified uses that.

Returns converted text

Espresso object convenience methods

new_range_set context (TextAction context)

Returns the MRRangeSet for the selection in the current context

new_recipe

Returns new text recipe

new_snippet snippet (string)

Initializes a string as a CETextSnippet object.

Returns initialized CETextSnippet

Working with ranges and selected text

new_range location (integer), length (integer)

Returns new NSRange

get_ranges context (TextAction context)

Convenience function to get a list of all selection ranges in the document. Automatically cleans them up into NSRanges from NSConcreateValues.

Returns list of NSRanges

get_first_range context

Shortcut function to snag the first selection in the document; guaranteed to be at least one because the cursor is a range.

Returns NSRange

get_selection context (TextAction context), range (NSRange)

Returns selected text within a given range

get_line context (TextAction context), range (NSRange)

Returns a tuple: contents of line bounding range.location, range of line

set_selected_range context (TextAction context), range (NSRange)

Sets the selection to the single range passed as an argument.

Returns void

get_single_range context (TextAction context), with_errors (bool : False)

Returns the range of a single selection, or throws an optional error if there are multiple selections

get_single_selection context (TextAction context), with_errors (bool : False)

If there’s a single selection, returns the selected text, otherwise throws optional descriptive errors.

Returns a tuple: the selected text, text’s range

get_character context (TextAction context), range (NSRange)

Fetches the character immediately preceding the range.

Returns a tuple: the character, the range of the character

get_word context (TextAction context), range (NSRange), alpha_numeric (bool : True), extra_characters (string : _-), bidirectional (bool : True)

Selects and returns the current word and its range from the passed range. By default it defines a word as a contiguous string of alphanumeric characters plus extra_characters. Setting alpha_numeric to False will define a word as a contiguous string of alphabetic characters plus extra_characters. If bidirectional is False, then it will only look behind the cursor.

Returns a tuple: the word, the range of the word

get_word_or_selection context (TextAction context), range (NSRange), alpha_numeric (bool : True), extra_characters (string : _-), bidirectional (bool : True)

Selects and returns the current word and its range from the passed range, or if there’s already a selection returns the contents and its range. See above for info on arguments.

Returns a tuple: the selected text or word, the range of the selected text

Syntax zone methods

get_root_zone context (TextAction context)

DEPRECATED: use select_from_zones instead.

Returns the string identifier of the current root zone

get_active_zone context (TextAction context), range (NSRange)

Returns the string identifier of the zone under the cursor

select_from_zones context (TextAction context), range (NSRange : None), default (string : None), **syntaxes (dictionary)

Checks the keys in **syntaxes to see what matches the active zone, and returns that item’s contents, or default if no match.

Returns string for matching selector

range_in_zone context (TextAction context), range (NSRange), selector (string)

Tests the location of the range to see if it matches the provided zone selector string.

Returns bool

cursor_in_zone context (TextAction context), selector (string)

Identical to range_in_zone() above, but automatically detects the range of the cursor.

Returns bool

Itemizer methods

get_item_for_range context (TextAction context), range (NSRange)

Returns the smallest itemizer item containing the given range.

Returns itemizer item (CEItem or ESBaseItem object)

get_item_parent_for_range context (TextAction context), range (NSRange)

Returns the parent of the itemizer item containing the given range.

Returns itemizer item (CEItem or ESBaseItem object)

Snippet methods

sanitize_for_snippet text (string)

Escapes special characters used by snippet syntax.

Returns sanitized text

construct_snippet text (string), snippet (string), parse_new_vars (bool : False)

Constructs a simple snippet by replacing $SELECTED_TEXT in snippet with a sanitized version of text. If parse_new_vars is True then $EDITOR_SELECTIONS variable will be replaced (typically this is not advisable, since Espresso itself will replace the variable more intelligently).

Returns text ready to be converted to a CETextSnippet

indent_snippet context (TextAction context), snippet (string), range (NSRange)

DEPRECATED. Sets a snippet’s indentation level to match that of the line starting at range.location.

Returns modified text

Insertion methods

insert_text_over_range context (TextAction context), text (string), range (NSRange), undo_name (string : None)

Immediately replaces the text at range with passed in text.

Returns bool; result of insertion

insert_snippet context (TextAction context), snippet (text), indent (bool : True)

Convenience function to insert a text snippet. Make sure to set the selection intelligently before calling this.

Returns bool; result of insertion

insert_snippet_over_range context (TextAction context), snippet (string), range (NSRange), undo_name (string : None), indent (bool : True)

Replaces text at range with a text snippet.

Returns bool; result of insertion

Clicky Web Analytics