Custom Cleaner Core Actions

Find and Replace Actions

Common options. These options are common to the collection of Find and Replace actions. Specific changes for each action will be noted below.

Expression - Indicates whether this is a regular expression

Match Case - Require case matching, otherwise ignores text case (Uppercase A = Lowercase a)

Options

Textual matches

Expression matches

Find - Text to find

Replace - Text to replace

Find and Replace Text

Regular text fields may use the following special characters

\\ = backslash (\)
\t = tab
\n = end of line (return)
\s = space
\x{hhhh} = hex character value, ie. tab = \x{09}, pace = \x{20}

Regex Find and Replace Text

When Expression option is selected, find text is a regular expression and is highlighted as such. See Reference on Regular Expressions for more details.

Replace text supports both the characters supported in regular text fields (\t, \n, etc) as well as replacement template ($0 for entire match, $1 for first captured group, etc).

Using Lists

Some actions, like Batch Find and Replace, Create Hyperlink URLs make use of list data, which is a table of up to 4 columns edited separately. See Custom Cleaner Editor for more details.

Each action specifies whether to use the entire list or a subsection (specified with markers). To specify which column of data to use, you will need to use special “tokens” within your action.

The action is performed for each row of data specified, replacing $v{col:A} with the value in column A, and $v{col:B} with the value in column B, etc.

If you forget these tokens, you can use the Insert button on the action and select the List Columns category.

Batch Find and Replace Text

In addition to the options of standard Find & Replace Text, there is an option to indicate the Group to use from the Data table. The action will cycle through all the items in that group. See above on “Using Lists” for more details on specifying the columns within the list.

Create Hyperlink URLs

This is a special variant of Batch Find and Replace Text action.

Use the find field to match the text (most common is simple text match, but you can use an expression as needed). Use $v{col:A} to specify the column A value. See above on “Using Lists” for more details on specifying the columns within the list.

The “replace” value is somewhat unique. The replace field specifies the text used in the hyperlink. If column B specifies a complete URL, you can simply use $v{col:B}.

General Actions

Title Case with Options

TextSoap has a built-in cleaner called “Capitalize with Title Case”. However, if you need a more customized behavior, you can use this action, which provides for extending or replacing both the small words list, and the special words list used.

Small words specify words that are to not be capitalized. Special Words specify words that are keep the case as specified in the list.

You can often use this in combination with the “Capitalize Common Tech Names” cleaner, which will fix up special-cased words like MacBook, iPhone, TextSoap, etc.

Custom Text Wrap

TextSoap has built-in cleaners to hard wrap text at 50, 60, and 70 character boundaries. You can use this action to specify a custom value. The custom wrap will word wrap the text, attempting to keep lines <= the specified character length.

Quote Text

Quoting references an old style quoting where a common mark such as ‘>’ is used before text to quote some previous text.

The options include:

Quote level (0–10) : specifies how many of the “Mark” characters to use.

Wrap text : allows for re-wrapping the text at a fix character length

Quote Chars:

Prefix: typically a space to provide padding

Mark: The character used to quote. Commonly ‘>’, but can be any character.

Suffix: padding after the mark.

Insert Text

Allows for inserting a piece of text either before, after or replacing the text.

Tag Text

Allows for simple tagging of text. Often used as part of a conditional (see below). While HTML tags are most common, you can specify any tag and it will surround the given text with the open tag and close tag.

Extract Text

Expression : Regular expression to match the text to extract.

Capture Group : Result group to use. $0 indicates entire match, but you can specify a sub group.

Match Case : Indicates whether to require case matching. If not selected, text case is ignored.

Append Result: If selected, will return original text along with extracted text appended. Otherwise, will replace the text with the extracted text.

Extract Beginning Characters

Will extract the specified number of characters from the beginning of text.

Alternative : You can use extract text with the expression ^.{n} for the same result, where n is number of characters.

Extract End Characters

Will extract the specified number of characters from the end of text.

Alternative : You can use extract text with the expression .{n}$ for the same result, where n is number of characters.

Extract Middle Characters

Will extract the specified number of characters in the middle of text.

Alternative : You can use extract text with the expression ^.{n}(.{m}) for the same result, where n is number of characters to start and m is the number of characters to extract and using $1 as the capture group.

Hyperlinks to Text

This special action will find rich text with a link attribute and extract the link out as specified.

Result Pattern: text template used to extract the link. Default demonstrates how to convert to the HTML “<a>” tag.

<a href="{link}">{text}</a>

Note: Special tokens will substitute the original text “{text}” and the link, “{link}”.

Keep hyperlinks active : optionally keep the link specified as clickable.

Delete Text

Simply deletes the provided text. This is most commonly used as part of a conditional.

Copy Text to Clipboard

Will copy the current text to the clipboard. You might use this at the end of a cleaner to always place the results on the clipboard.

Style Actions

When working with rich text (vs. plain text), you can change various attributes of the text. These actions can be used globally (for example, to change a font) or selectively on text using conditionals.

Set Font

An option is applied only if selected. To change only one aspect of a font, leave the remaining options unselected. For example, to set the font, but keep existing sizes, along with bold and italics, only select the “Font family” option and specify the new font family to use.

Font family: The font name to use. For example “Helvetica Neue”.

Typeface: When selected, specify plain (to remove any bold & italic), bold and/or italic. Plain option overrides bold and italic.

Size: The size of the font to use.

Set Exact Font

*Note: Use more sparingly to specify the exact font name. This allows for additional choices outside of more standard “bold” and “italic”.

Exact font: The exact font to use. For example “HelveticalNeue-MediumItalic”

Size: The size of the font to use.

Adjust Font Size

Relative changes to the font sizes. To make everything 5 points larger, set to +5. 12pt becomes 17pt, 20pt becomes 25pt. To reduce everything by 10 pts, set to –10 pts. 24pt becomes 14pt, 48pt becomes 38pt.

Set Underline Attributes

Style: Single, Thick, Double to specify line style. None = remove this attribute (if it exists).

Pattern: Line patters defined in Apple’s Rich Text.

Color: Color of the line.

Set Strikethrough Attributes

Style: Single, Thick, Double to specify line style. None = remove this attribute (if it exists).

Pattern: Line patters defined in Apple’s Rich Text.

Color: Color of the line.

Set Super/Subscript Attribute

Script attribute:

Set Text Color

Set color of text.

Set Background Color

Set color of background.

Remove Character Attribute

Remove the specified attribute of text.

Line Actions

Add Prefix to Lines

Add text to the beginning of each line of text.

Add Suffix to Lines

Add text to the end of each line of text.

Remove Prefix from Lines

Remove given text from the beginning of each line of text. Ignored if the given text is not there.

Remove Suffix from Lines

Remove given text from the end of each line of text. Ignored if the given text is not there.

Conditional Actions

Conditional blocks are a way to apply specific actions only to text that matches given criteria. The actions inside the block can be virtually anything. Conditionals can even be nested to allow you to match more and more specific criteria. Using nest conditionals, it is possible to find words that are both bold and all uppercase. This example finds all capitalize bold words and changes the text color to red.

Example 1
Example 1

If Text Matches

Find the provided text and applies related actions to it.

When using a regular expression, you can also specify which capture group to use. $0 is the default for entire matched string. However, you could specify a find as (.*?) and use $1 to only specify the text within the given tag.

If Font Matches

Finds text that matches the font family, size(s), or face attributes (italic or bold). All the attributes can be found independently of each other. For example, you can specify Typeface: Italic to only find italic text, no matter its font family or size.

If Text Has Attribute

Finds text that matches the specified attribute.

Modifiers allow you to adjust the results of a conditional match. These modifiers should be placed as the first actions within the group or they will be ignored. They can be used together.

Modify Results: Invert Matches

This will flip the match results. For example, if you used a conditional to find bold words and then used invert matches, the match would be on all non-bolded words.

In some cases, it is easier to specify the text you don’t want and then invert the results.

Modify Results: Limit Matches

If multiple matches are found, this will limit the matches used.

Modify Results: Skip Matches

If multiple matches are found, this will skip the first N matches.

Misc

Group

Group containers encapsulate a hierarchy of actions. They represent the foundation for conditional actions and macros.

Additionally, they allow for encapsulated organization of actions. A group container controls whether the actions within are applied. If the container is disabled, all the contained actions are ignored. This is much easier than individually disabling actions.

If you move the group, all its contained actions move with it. And if you delete a group, all the actions within are deleted.

Run Automator Workflow

This action runs an Automator Workflow. Workflows are located at:

~/Library/Application Support/TextSoap/Workflows/

Note: The result of this action will be plain text

Note

This is a basic action that allows you to store notes within your cleaner. This is useful if you need to add a note to remind yourself of some detail in your cleaner. It does nothing to the text (it is ignored) when the cleaner is applied.

Additionally, if you want to make notes for a particular action, you can use the comment button on the individual action to store a short note with it.

Macros

Macros are way to specify a group of actions that you can use multiple times within a custom cleaner. Rather than duplicating the actions, you can create a macro with the actions and apply it instead.

Macro List

This is a top-level container. It will hold all your macro definitions. Any Macros defined outside of this are effectively ignored.

Define Macro

This action defines a Macro. It is also a group container. You specify the name of the Macro (which will be used later with the “Apply Macro” action). Add your actions to this group container.

Apply Macro

To apply the actions defined within a Macro, use this action. It provides a popup list of names defined in the Macro List container. The actions within the Define Macro group will be applied to the given text.

Here is a slightly altered version of our cleaner example:

Example 2
Example 2

Explanation: In this example, you create a macro the changes the text to red.

Instead of nesting the two conditional actions, they are separated, which means any text that is bold, or any words that are all uppercase will have the macro applied, changing the text to red.

If you wanted to change the text color to green, it now requires only one change. You can add additional actions to the macro definition and they will use used everywhere the macro is applied.