Home » Custom Cleaner Actions TextSoap

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).


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. You can use the following special token to indicate which column to use: $v{col:A} replacing A with the column A, B, C or D.


Create Hyperlink URLs


This is a special variation 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.

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 with the "Capitalize Common Tech Names" cleaner, which will search for an fix up specially-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 "\" 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.


custom_cleaner_actions1.png


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.


For Each Line (shortcut)


This is a simple shortcut to "If Text Matches"


--


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 will be plain text


Note


This is simple action that allows you to store notes. It is effectively ignored when the cleaner is applied.


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:


custom_cleaner_actions2.png


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.