Text - Replace
Declaration
<AMTEXT ACTIVITY="replace" TEXT="text" FIND="text" REPLACE="text" RESULTVARIABLE="text" USERE="YES/NO" USECASE="YES/NO" INDEX="number" MAXMATCHES=number TOTALMATCHESVARIABLE=number />
Description
Finds and replaces a word or phrase inside of a larger piece of text and populates a variable with the result. Regular expressions can be used for added flexibility and extended search capabilities.
Practical usage
Commonly used to find and replace each or every occurrence of a text pattern. It can also search for and replace special characters and document elements such as tabs and manual page breaks. Can also be used to quickly find and replace across multiple files.
Parameters
General
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| Text | Text | Yes | (Empty) | TEXT="My Name is Joe" | The target text to be searched. As with every text parameter, if the data you wish to enter is contained in a variable, simply enter the variable name surrounded by percentage signs to resolve it to it's contents at runtime (for example, %VarName%). |
| Find | Text | Yes | (Empty) | FIND="Joe" | The text to search for. |
| Replace with | Text | Yes | (Empty) | REPLACE="Jim" | The text to replace the found text with. |
| Case sensitive | Yes/No | No | No | USECASE="YES" | In a case sensitive language, "abc" is considered different data than "ABC." Therefore, setting this parameter to YES denotes that the text to search for must match the exact case (upper/lower case) of the text specified in the Find parameter. This parameter is disabled by default. |
| Regular expression | Yes/No | No | No | USECASE="YES" | If selected, specifies that the Find parameter contains a regular expression. If disabled (default), specifies that the Find parameter contains literal text. |
| Populate variable with result | Text | Yes | (Empty) | RESULTVARIABLE="varname" | The name of an existing variable to receive the new text after replacement. |
Advanced
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| Starting at the following instance | Number | No | 1 | INDEX="5" | Specifies at what instance text replacement should be applied. |
| Maximum replacements (optional) | Number | No | 0 | MAXMATCHES="6" | Specifies the maximum number of replacements that should be made. If 0 (default) is specified, all instances of the found text will be replaced. |
| Total replacement count into variable | Text | No | (Empty) | TOTALMATCHESVAR="varname" | The name of the variable to receive the total number of replacements that were made. |
Examples
- Copy and paste the sample AML code below directly into the Task Builder Steps Panel.
- To successfully run the sample code, update parameters containing user credentials, files, file paths, or other information specific to the task to match your environment.
Example 1
This sample task uses the Text - Replace activity to find and replace a single word inside of a larger piece of text.
<AMVARIABLE NAME="sourcedata" VALUE="The Automate and Automate Desktop products add power, speed, flexibility and intelligence." />
<AMVARIABLE NAME="newdata" />
<AMSHOWDIALOG>Text before Replace text activity: %sourcedata%</AMSHOWDIALOG>
<AMTEXT ACTIVITY="replace" TEXT="%sourcedata%" FIND="speed" REPLACE="swiftness" RESULTVARIABLE="newdata" USECASE="YES" />
<AMSHOWDIALOG>Text after Replace text activity is performed: %newdata%</AMSHOWDIALOG>Example 2
This sample task uses the Text - Replace activity to find and replace every occurrence of a text pattern.
<AMVARIABLE NAME="theOriginalText" VALUE="All_underscore_characters_will_be_replaced_with_a_space." DESCRIPTION="Replace Task Demonstration" />
<AMVARIABLE NAME="theNewText" />
<AMTEXT ACTIVITY="replace" TEXT="%theOriginalText%" FIND="_" REPLACE=" " RESULTVARIABLE="theNewText" />
<AMSHOWDIALOG WINDOWTITLE="Replace text demonstration">The original text string:%theOriginalText%The new text string:%theNewText%</AMSHOWDIALOG>Example 3
This sample task replaces the pipe "|" character with a tab character.
<AMVARIABLE NAME="theFile" VALUE="one|two|three|four|five|six|seven|eight|nine|ten" />
<AMVARIABLE NAME="theLine" />
<AMVARIABLE NAME="newData" />
<AMTEXT ACTIVITY="replace" TEXT="%theFile%" FIND="|" REPLACE="" "" RESULTVARIABLE="newData" />
<AMSHOWDIALOG>%newData%</AMSHOWDIALOG>