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
- Contains : match text anywhere
- Starts with : Start of match must be start of word
- Whole Words : Do not match partial words
- Ends with : End of match must be at end of word
Expression matches
Matches Lines (m) : Control the behavior of “^” and “$” in a pattern. By default these will only match at the start and end, respectively, of the input text. If this flag is set, “^” and “$” will also match at the start and end of each line within the input text.
Note: This same option is often called “Multiline”.
Dot Matches Returns (s) : If set, a “.” in a pattern will match a line terminator in the input text. By default, it will not.
Note that a carriage-return / line-feed pair in text behave as a single line terminator, and will match a single “.” in a RE pattern. Line terminators are \u000a, \u000b, \u000c, \u000d, \u0085, \u2028, \u2029 and the sequence \u000d \u000a.
Use Unicode Words (w) : Controls the behavior of \b in a pattern. If set, word boundaries are found according to the definitions of word found in Unicode UAX 29, Text Boundaries.
By default, word boundaries are identified by means of a simple classification of characters as either “word” or “non-word”, which approximates traditional regular expression behavior. The results obtained with the two options can be quite different in runs of spaces and other non-word characters.
Allow comments (x) : If set, allow use of white space and (#comments) within patterns
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.
- Column A - $v{col:A}
- Column B - $v{col:B}
- Column C - $v{col:C}
- Column D - $v{col:D}
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:
- Superscript : make text superscript
- None : remove any superscript/subscript attribute
- Subscript: make text subscript
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.

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
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:

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.