text_recipe.js

Text recipes allow you to queue up multiple changes to a text document and then apply them all at once without needing to worry about tracking range offsets and so forth.

Exports

TextRecipe (class)

constructor(undo_name)
Accepts a single argument: undo_name.

If no undo_name is passed, the recipe will automatically use the undo_name provided by the XML action definition (if one exists).

var TextRecipe = require('text_recipe').TextRecipe;
var recipe = new TextRecipe('Awesome Action');
insert(string, rangeOrIndex[, insertAfterRange])
Returns the TextRecipe object (for easy chaining of methods); accepts the string to insert and the range or character index where you would like the string inserted. If you pass a range-like object, the text will by default be inserted after the range, unless you specify insertAfterRange to be false.
insertAfter(string, rangeOrIndex)
Shortcut to insert a string after the given range or index. Identical arguments to insert()
insertBefore(string, rangeOrIndex)
Shortcut to insert a string before the given range or index. Identical arguments to insert()
replace(string, ranges)
Returns the TextRecipe object for chaining; the second parameter may be a single range-like object or an array of range-like objects if you would like to replace multiple selections in the document
remove(ranges)
Returns the TextRecipe object for chaining; accepts a single range-like object or array of range-like objects to delete
prepare()
Returns the TextRecipe object for chaining; if you want to check if a recipe is going to apply any changes, you must prepare it first. Once a recipe is prepared, you cannot modify it further.
numberOfChanges()
Returns the number of changes this recipe will make to the text document (int); will prepare the recipe if it has not already been prepared
apply()
Returns bool (was the recipe successful); applies the text recipe to the active text document context

New Range methods

Requiring text_recipe adds the following methods to the default Range class:

insert(string[, insertAfterRange, undo_name])
Shortcut for TextRecipe.insert() that inserts a string before or after the Range. Defaults to inserting after; undo_name is optional.
insertAfter(string[, undo_name])
Shortcut to insert the string after the Range.
insertBefore(string[, undo_name])
Shortcut to insert the string before the Range.
replace(string[, undo_name])
Shortcut to replace the Range’s text with string.
remove(string[,undo_name])
Shortcut to remove the current Range.

New String methods

The following methods are added to the default String class.

insert(range[, insertAfterRange, undo_name])
Inserts the string before or after the passed range (defaults to after).
insertAfter(range[, undo_name])
Shortcut to insert the string after the range.
insertBefore(range[, undo_name])
Shortcut to insert the string before the range.
write([overwrite, undo_name])
Writes the string to the document (very similar to Snippet.write()). By default will overwrite the first selection (overwrite can be true, false, or a target range). undo_name is optional.