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
