Custom Cleaners

Custom cleaners are mini-scripts that allow you to define one or more actions to transform your specific text.

TextSoap offers a completely new Custom Cleaner Definition Editor.

Cleaners are now stored as individual documents in the in folder location:

~/Library/Application Support/TextSoap/Custom Cleaners/

where "~" is your home folder.

Naming Convention - Starting with 5.5, TextSoap Deluxe increases the use of custom cleaners as "subroutines" (or sub-actions) for use by another custom cleaner.

To better support this, TextSoap now places any cleaners starting with a dash (-) at the end of the custom cleaner list based on the following conventions.

We recommend following these conventions:

Actions to apply a style should be prefixed with a "-s:"
Subroutine actions should be prefixed with a "-a:"

Apply Cleaner

This action allows you to apply an existing cleaner to the selected text. The cleaner specified can be any built-in cleaner or custom cleaner.

Note: if the cleaner cannot be found, the command is simply ignored.

Find and Replace Text

This action allows you to find a value and replace it with another value.

Is Regular Expression : check this if you wish to use regular expressions (See section on regular expressions). If you don't know what regular expressions are, just leave this unchecked.

Ignore Case : check this option if you wish to find the text without regard to the case.

Find and Replace Repeating Character

This action allows you to search for N or more occurrences of a character and replace it with a value. The search is only of a specific character (after the meta characters are converted).

For example, if you specify 2 or more "\t", the action will match tab-tab or tab-tab-tab.

Find and Replace (Special characters)

Find and Replace strings also allow you to specify some meta-characters, the table below describes each:

\\backslash (\) character
\rtraditional carriage return character
\nnewline character
\ttab character
\x{HHHH}Hexadecimal character with the hex value: {HHHH} (indicating a Unicode character)

Rewrap Text

This action will rewrap the text at the specified number of characters. The text will be word wrapped to fit within the given number of characters.

Quote Text

This action allows you to quote text. You can specify the

For example, with a quote level of 4 and a quote marker of ">", the quoted string would be prefixed with a " >>>> ".

You can override the characters used to quote the text. You can specify a leading set of characters (usually spaces), the actual quote characters and the trailing characters (usually spaces).

Note: The actual wrap amount is this number minus the number of prefixes characters needed. In the example above, the actual text wrapping is 65 - 6 characters ( leading space, four ">", trailing space).

Insert Text

Clicking on the "Insert Text Options" button brings up a dialog that allows you to define the insertion of text in a cleaner. This is handy for inserting boilerplate text or, using the conditional test, expanding acronyms.

Checking the "If selection equals" item will enable a conditional text insertion. The selected text is tested against the string, if it matches, then the text insertion/replacement is done. If it does not match, the text insertion is skipped.

The third option allows you to specify how the text is inserted. It can be inserted before or after the selected text or you can use it to replace the selected text.

The Following Requires a TextSoap Deluxe license.

Tag Text

Specify the text to place before and after selected text.

An Example:

Specify the before tag as "<custom>" and the after tag as "</custom>".

Now select a word like "this" and apply the cleaner.

Now "this" becomes "<custom>this</custom>".

The HTML and PLIST tag cleaners are specific examples of this type of cleaner action in action.

Sort Lines

Specify which direction you wish to sort the lines.

For this cleaner action, lines are defined as ending with a paragraph marker.

Add Prefix to Lines

This action allows you to add a prefix to the beginning of each line.

For this cleaner action, lines are defined as ending with a paragraph marker.

Add Suffix to Lines

This action allows you to add a suffix to the end of each line.

For this cleaner action, lines are defined as ending with a paragraph marker.

Remove Prefix from Lines

This action allows you to remove a specific prefix (if it exists) from the beginning of each line.

For this cleaner action, lines are defined as ending with a paragraph marker.

Remove Suffix from Lines

This action allows you to remove a specific suffix (if it exists) from the end of each line.

For this cleaner action, lines are defined as ending with a paragraph marker.

Extract Text

This action allows you to specify a regular expression to find and extract the text.

The default behavior is to replace the existing text with the extracted text. You can optionally append the results to the end of the text.

Find Text and Apply Style

This action allows you to find text (optionally using a regular expression) and then apply a style to it.

If a style attribute is not checked, the text will retain its original value.

Size allows you to specify an absolute value or a relative value, allowing you to "grow" or "shrink" text.

Find a Style

This action allows you to find text based on a set of font attributes and then apply a cleaner to that text.

Exact font allows to specify the exact font name, for example: AmericanTypewriter-CondensedBold. This is useful if you are looking for trait such as condensed, which can't be found with the family/typeface option.

More commonly, you'll likely specify the family name allow and/or typeface.

Multiple sizes may be specified by separating them by commas (e.g. 12,14,16,24). You can also specify a range (e.g. 12,14-18,24).

Set Style

This action allows you to apply a font, size and color to text.

The size option allows you to specify either absolute size or a relative size.

Find Text and Apply Cleaner

This action allows you to find text and then apply a cleaner to that found text. This is useful for complex cleaner actions. The Find Text and Apply Style is an example of this type action. It finds the text and then applies a Set Style action cleaner to that text.

Tag Text based on Style

This action allows you to find text based on a style (see above) and then tag that text. This action combines the Find a Style and Tag Text cleaners together for a common usage of the Find Style action. For example, you can find Bolded text and then tag it with <B>/</B>