3. Script Language > String commands > !STR.- String Command

STR.RegRepl

Previous Top Next

MiniRobotLanguage (MRL)

STR.RegReplace

Replace Text in a String Using Regular Expressions

Intention

This command scans a target string for a matching regular expression and replaces it with a specified string.

The result is either placed on the Top of Stack (TOS) or in optional variables.

The command uses regular expressions for matching. It supports a variety of metacharacters and special sequences.

If no match is found, the position variable will be set to zero, and the new target string will be a direct copy of the original.

The search is case-insensitive by default.

Syntax

STR.RegReplace|P1|P2|P3[|P4|P5|P6]

Parameter Explanation

•P1 - (Target String) The string in which to search and replace.

•P2 - (Regular Expression Mask) The regular expression to match.

•P3 - (Replacement String) The string to replace the matched text with.

•P4 - (Optional) Starting position in the target string.

•P5 - (Optional) Variable for the new position. If omitted, the result is placed on TOS.

•P6 - (Optional) Variable for the new target string. If omitted, the result is placed in P1.

Metacharacters Table for STR.RegRepl

Char	Definition
.	(period) Matches any character, except the end-of-line.
^	(caret) Matches the actual beginning-of-line position or the preceding line-delimiter character pair (CHR$(13,10) or $CRLF).
$	(dollar) Matches the end-of-line position or the first line-delimiter character pair (CHR$(13,10) or $CRLF) that is encountered.
`	`
?	(question mark) Specifies that zero or one match of the preceding sub-pattern is allowed.
+	(plus) Specifies that one or more matches of the preceding sub-pattern are allowed.
*	(asterisk) Specifies that zero or more matches of the preceding sub-pattern are allowed.
[ ]	(square brackets) Identifies a user-defined class of characters.
[-]	(hyphen) Identifies a range of characters to match.
[^]	(caret) Identifies a complemented class of characters, which will not match.

Character Classes Table for STR.RegRepl

Symbol	Definition
[ ]	Square brackets identify a user-defined class of characters, any of which will match. For example, [abc] will match a, b, or c.
\\, \-, \], \e, \f, \n, \q, \r, \t, \v, \x##	These are the only special metacharacters recognized within a class definition. Any other use of a backslash yields an undefined operation.
[-]	The hyphen identifies a range of characters to match. For example, [a-f] will match a, b, c, d, e, or f.
	Characters in an individual range must occur in the natural order. For example, [f-a] will match nothing.
	Multiple ranges in a class are valid. For example, [a-d2-5] matches a, b, c, d, 2, 3, 4, or 5.
	When the hyphen is escaped, it is treated as a literal. For example, [a\-c] matches a, -, or c.
[^]	When the caret appears as the first item in a class definition, it identifies a complemented class of characters, which will not match. For example, [^abc] matches any character except a, b, or c.
	A range can also be specified for the complemented class. For example, [^a-z] matches any character except a through z.

Tags/Sub-patterns Table for STR.RegRepl

Symbol	Definition
( )	Parentheses are used to match a Tag, or sub-pattern, within the full search pattern. The matched sub-pattern can be retrieved later in the mask or in a replace operation with \01 through \99.
	Parentheses can also be used to force precedence of evaluation with the alternation operator ` For example, "(Begin)\|(End)File" would match either "BeginFile" or "EndFile", but without the Tag designations, "Begin\|EndFile" would only match either "BeginndFile" or "BegiEndFile".
	Note: Parentheses may not be used with ?, +, * as any match repetition could cause the tag value to be ambiguous. To match repeated expressions, use parentheses followed by \01*.

Escaped Characters Table for STR.RegRepl

Escape Sequence	Definition
\\	Backslash, treated as a literal value.
\b	A word boundary. Matches the start or end of a word.
\c	Enables case-sensitive search.
\e	Escape character: CHR(27) or "ESC".
\f	Formfeed character: CHR(12) or "FF".
\n	Linefeed (or newline) character: CHR(10) or "LF".
\q	Double-quote mark ("): CHR(34) or "DQ".
\r	Carriage-return character: CHR(13) or "CR".
\s	Shortest match character.
\t	Horizontal tab character: CHR(9) or "TAB".
\v	Vertical tab character: CHR(11) or "VT".
\x##	Hex character code.
\##	Tag number. Evaluated as the characters matched by tag number ##.

Restrictions

•To maximize performance, avoid overuse of the *, +, and ? metacharacters.

Example

'***********************************

' STR.-Sample

'***********************************

' Result: please mail to Sales@smart-package.com in all cases.

$$TGT=please mail to support@smart-package.com in all cases.

$$MSK=([a-z0-9._/+-]+)(@[a-z0-9.-]+)

$$RPL=Sales@smart-package.com

STR.RegReplace|$$TGT|$$MSK|$$RPL|1|$$POS|$$NEW

DBP.$$NEW

ENR.

Remarks