subregex
Syntax: %subregex(string,regular-expression,substring)
Related: #REGEX, %regex, %match
See also: Advanced substitutions
Test to see if string matches the given Regular Expression. If it matches, the matched part of the string is replaced with the substring string (which is also expanded for any variables or function calls). This continues until there are no more matches of the pattern in the string. The modified string is then returned. This is similar to the #SUB command but substitutes patterns within a string rather than patterns on the screen output. To reference any captured subpatterns in the regular expression, use \nn. For example, \1 returns the first subpattern (similar to using %1 in a trigger script). Remember that the pattern is a Regular Expression and not a CMUD trigger pattern. All Perl backreference symbols may be used to reference captures in the substitution string, for example \k'name', \g{1} and (?P=name).
Examples:
#SHOW %subregex("100 gold, 200 silver", "\d+", "%d")
displays: %d gold, %d silver
#SHOW %subregex("100 gold, 200 silver", "(\d+)", "%eval(\1+10)")
displays: 110 gold, 210 silver
The quotes "" around the %eval function are needed to prevent %eval from being executed immediately when %subregex is parsed. With the quotes, it is executed each time a string is replaced.
The use of named captures is also supported.
#SHOW %subregex("100 gold, 200 silver", "(?<n>\d+)", "%eval(\n+10)")
displays: 110 gold, 210 silver
When you want to place text or numbers directly next to your capture reference you must enclose the reference in a delimeter. The delimeters recognized are ' ', < >, and { }.
#SHOW %subregex("100 gold, 200 silver", "(\d+)", "\'1'0")
displays: 1000 gold, 2000 silver
To make a replacement with a valid capture symbol as text the backslash needs to be escaped. This is done with \ in the substring.
#SHOW %subregex("100 gold, 200 silver", "(?<n>\d+)", "\n \z")
displays: \n \z gold, \n \z silver
The "\z" does not need to be escaped because z is not a valid capture. Escaping backslashes are only recognized when the following portion is a valid substitution symbol.
You may also use octal and hex notations within the substitution string. These are done with the same codes as regexes. Octal notations require 3 digits, meaning leading 0's must be present. The hex notation supports only a signle character replacement (2 hex digits), and does not support enclosing delimeters.
#SHOW %subregex("Hello", "^", "\042 \x41")
displays: "AHello |
%abs