RegexReplaceCorresponding (Stringlist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (quoted references)
No edit summary
 
(32 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Template:Stringlist:RegexReplaceCorresponding subtitle}}
{{Template:Stringlist:RegexReplaceCorresponding subtitle}}
<p>This method searches a given string for matches to one of multiple regular expressions contained in a list, and it replaces found matches with or according to a string contained in a list that corresponds to the regex list.</p><p>The regex list items are treated as mutually exclusive alternatives, and the function stops as soon as an item matches and the replacement is made. A "global" option is also available to continue searching and replacing within the given string using the matching regex item until no more matches are found.</p><p><var>RegexReplaceCorresponding</var> uses the rules of regular expression matching (information about which is provided in <var>[[Regex_processing#Regex_rules|"Regex processing rules"]]</var>).</p><p><var>RegexReplaceCorresponding</var> accepts two required and two optional arguments, and it returns a string.</p>
 
<p class="warn"><b>This method is deprecated and should not be used.</b></p>
 
This method searches a given string for matches to one of multiple regular expressions contained in a list, and it replaces found matches with or according to a string contained in a list that corresponds to the regex list.
 
The regex list items are treated as mutually exclusive alternatives, and the function stops as soon as an item matches and the replacement is made. A "global" option is also available to continue searching and replacing within the given string using the matching regex item until no more matches are found.
<var>RegexReplaceCorresponding</var> uses the rules of regular expression matching (information about which is provided in [[Regex_processing#Regex_rules|"Regex processing rules"]]).
 
<var>RegexReplaceCorresponding</var> accepts two required and two optional arguments, and it returns a string.


==Syntax==
==Syntax==
{{Template:Stringlist:RegexReplaceCorresponding syntax}}
{{Template:Stringlist:RegexReplaceCorresponding syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>outString</th>
<tr><th>outString</th>
<td>A string set to the value of <var class="term">inString</var> with each matched substring replaced by the value of the <var class="term">replacementList</var> item that corresponds to the matching <var class="term">sl</var> item.</td></tr>
<td>A string set to the value of <var class="term">inString</var> with each matched substring replaced by the value of the <var class="term">replacementList</var> item that corresponds to the matching <var class="term">sl</var> item.</td></tr>
<tr><th>sl</th>
<tr><th>sl</th>
<td>A <var>Stringlist</var> object whose items are interpreted as regular expressions and applied to the <var class="term">inString</var> value.</td></tr>
<td>A <var>Stringlist</var> object whose items are interpreted as regular expressions and applied to the <var class="term">inString</var> value.</td></tr>
<tr><th>inString</th>
<tr><th>inString</th>
<td>The input string, to which the regular expressions in <var class="term">sl</var> are applied.</td></tr>
<td>The input string, to which the regular expressions in <var class="term">sl</var> are applied.</td></tr>
<tr><th>replacementList</th>
<tr><th>replacementList</th>
<td><p>A <var>Stringlist</var>, each of whose items is a potential replacement string for the substring of <var class="term">inString</var> that is matched by the corresponding item of <var class="term">sl</var>.</p><p>Except when the <code>A</code> option is specified (as described below for the <var>Options</var> argument), you can include <code>$0</code> markers in <var class="term">replacementList</var> items as placeholders for the substring of <var class="term">inString</var> that the item matches.</p><p><code>xxx$0</code> is an example of a valid replacement string, and <code>xxx</code> concatenated with the portion of <var class="term">inString</var> that gets matched (by the corresponding <var class="term">sl</var> item) constitute the replacement string.</p><p>Any character after the dollar sign other than a zero is an error. Multiple zeroes (as many as 9) are permitted; a digit following such a string of zeroes must be escaped.</p><p>You can also use the format <code>$m0</code>, where <i>m</i> is one of the following modifiers:</p>
<td><p>A <var>Stringlist</var>, each of whose items is a potential replacement string for the substring of <var class="term">inString</var> that is matched by the corresponding item of <var class="term">sl</var>.</p>
<p>
Except when the <code>A</code> option is specified (as described below for the <var>Options</var> argument), you can include <code>$0</code> markers in <var class="term">replacementList</var> items as placeholders for the substring of <var class="term">inString</var> that the item matches.</p>
<p>
<code>xxx$0</code> is an example of a valid replacement string, and <code>xxx</code> concatenated with the portion of <var class="term">inString</var> that gets matched (by the corresponding <var class="term">sl</var> item) constitute the replacement string.</p>
<p>
Any character after the dollar sign other than a zero is an error. Multiple zeroes (as many as 9) are permitted; a digit following such a string of zeroes must be escaped.</p>
<p>
You can also use the format <code>$m0</code>, where <i>m</i> is one of the following modifiers:</p>
<table class="syntaxNested">
<table class="syntaxNested">
<tr><th>U or u</th>
<tr><th><var>U</var> or <var>u</var></th>
<td>Specifies that the matched substring should be uppercased when inserted.</td></tr>
<td>Specifies that the matched substring should be uppercased when inserted.</td></tr>
<tr><th>L or l</th>
 
<tr><th><var>L</var> or <var>l</var></th>
<td>Indicates that the matched substring should be lowercased when inserted.</td></tr>
<td>Indicates that the matched substring should be lowercased when inserted.</td></tr>
</table>
</table>
<p>The only characters you can escape in a replacement string are dollar sign (<code>$</code>), backslash (<code>\</code>), and the digits <code>0</code> through <code>9</code>. So only these escapes are respected:<code>\\</code>, <code>\$</code>, and <code>\0</code> through <code>\9</code>. No other escapes are allowed in a replacement string -- this includes "shorthand" escapes like <code>\d</code> -- and an "unaccompanied" backslash (<code>\</code>) is an error.</p><p>For example, since the scan for the number that accompanies the meta-$ stops at the first nonnumeric, you use <code>1$0\0</code> to indicate that the first matched substring should go between the numbers <code>1</code> and <code>0</code> in the replacement string.</p></td></tr><tr><th>Options</th>
<p>
<td>This is an optional, but <var class="term">nameRequired</var>, parameter supplying a string of single letter options, which may be specified in uppercase or lowercase, in any combination, and blank separated or not as you prefer. For more information about these options, see <var>[[Regex_processing#Common_regex_options|"Common regex options"]]</var>.
The only characters you can escape in a replacement string are dollar sign (<code>$</code>), backslash (<code>\</code>), and the digits <code>0</code> through <code>9</code>. So only these escapes are respected:<code>\\</code>, <code>\$</code>, and <code>\0</code> through <code>\9</code>. No other escapes are allowed in a replacement string &mdash; this includes "shorthand" escapes like <code>\d</code> &mdash; and an "unaccompanied" backslash (<code>\</code>) is an error.</p>
<p>
For example, since the scan for the number that accompanies the meta-$ stops at the first nonnumeric, you use <code>1$0\0</code> to indicate that the first matched substring should go between the numbers <code>1</code> and <code>0</code> in the replacement string.</p></td></tr>
 
<tr><th><var>Options</var></th>
<td>This is an optional, [[Notation conventions for methods#Named parameters|name required]], parameter supplying a string of single-letter options, which may be specified in uppercase or lowercase, in any combination, and blank separated or not as you prefer. For more information about these options, see [[Regex_processing#Common_regex_options|"Common regex options"]].
<table class="syntaxNested">
<table class="syntaxNested">
<tr><th>I</th>
<tr><th><var>I</var></th>
<td>Do case-insensitive matching between <var class="term">string</var> and <var class="term">regex</var>.</td></tr>
<td>Do case-insensitive matching between <var class="term">string</var> and <var class="term">regex</var>.</td></tr>
<tr><th>S</th>
 
<td>Dot-All mode: a period (<code>.</code>) can match any character, including carriage return and linefeed.</td></tr>
<tr><th><var>S</var></th>
<tr><th>M</th>
<td>Dot-All mode: a period (<tt>.</tt>) can match any character, including carriage return and linefeed.</td></tr>
<td>Multi-line mode: let anchor characters match end-of-line indicators <b><i>wherever</i></b> the indicator appears in the input string.  <var class="term">M</var> mode is ignored if <var class="term">C</var> (XML Schema) mode is specified.</td></tr>
 
<tr><th>C</th>
<tr><th><var>M</var></th>
<td>Do the match according to <var>[[Regex_processing#XML_Schema_mode|"XML Schema regex rules"]]</var>.  Each <var class="term">regex</var> is implicitly anchored at the beginning and end, and no characters serve as anchors.</td></tr>
<td>Multi-line mode: let anchor characters match end-of-line indicators <b><i>wherever</i></b> the indicator appears in the input string.  <var>M</var> mode is ignored if <var>C</var> (XML Schema) mode is specified.</td></tr>
<tr><th>G</th>
 
<td>Replace every occurrence of the match, not just (as in non-<var class="term">G</var> mode) the first matched substring only.</td></tr>
<tr><th><var>C</var></th>
<tr><th>A</th>
<td>Do the match according to [[Regex_processing#XML_Schema_mode|"XML Schema regex rules"]].  Each <var class="term">regex</var> is implicitly anchored at the beginning and end, and no characters serve as anchors.</td></tr>
 
<tr><th><var>G</var></th>
<td>Replace every occurrence of the match, not just (as in non-<var>G</var> mode) the first matched substring only.</td></tr>
 
<tr><th><var>A</var></th>
<td>Copy the <i>replacement</i> string as is. Do not recognize escapes; interpret a <var class="term">$n</var> combination as a literal and <b><i>not</i></b> as a special marker; and so on.</td></tr>
<td>Copy the <i>replacement</i> string as is. Do not recognize escapes; interpret a <var class="term">$n</var> combination as a literal and <b><i>not</i></b> as a special marker; and so on.</td></tr>
</table></td></tr>
</table></td></tr>
<tr><th><b>Status</b></th>
 
<td>The <var class="term">Status</var> argument (name required) is optional; if specified, it is set to an integer code. These values are possible:
<tr><th><var>Status</var></th>
<td>The <var>Status</var> argument ([[Notation conventions for methods#Named parameters|name required]]) is optional; if specified, it is set to an integer code. These values are possible:
<table class="syntaxNested">
<table class="syntaxNested">
<tr><th><i>n</i></th>
<tr><th>n</th>
<td>The number of replacements made. A value greater than 1 indicates option <code>G</code> was in effect.</td></tr>
<td>The number of replacements made. A value greater than 1 indicates option <code>G</code> was in effect.</td></tr>
<tr><th>0</th>
 
<tr><th><var>0</var></th>
<td>No match: <var class="term">inString</var> not matched by any <var class="term">sl</var> items.</td></tr>
<td>No match: <var class="term">inString</var> not matched by any <var class="term">sl</var> items.</td></tr>
<tr><th>-2</th>
 
<tr><th><var>-2</var></th>
<td>Syntax or other error: for example, the number of items in <var class="term">sl</var> does not equal the number in <var class="term">replacementList</var>; or a <var class="term">sl</var> item exceeds 6124 bytes; or <var class="term">sl</var> is empty.</td></tr>
<td>Syntax or other error: for example, the number of items in <var class="term">sl</var> does not equal the number in <var class="term">replacementList</var>; or a <var class="term">sl</var> item exceeds 6124 bytes; or <var class="term">sl</var> is empty.</td></tr>
<tr><th>-5</th>
 
<tr><th><var>-5</var></th>
<td>An invalid string in a <var class="term">replacementList</var> item. For example, an invalid escape sequence, or a <code>$</code> followed by any characters other than one or more (but no more than 9) zeroes.</td></tr>
<td>An invalid string in a <var class="term">replacementList</var> item. For example, an invalid escape sequence, or a <code>$</code> followed by any characters other than one or more (but no more than 9) zeroes.</td></tr>
<tr><th>-1<i>nnn</i></th>
 
<td><p>A regex in <var class="term">sl</var> is invalid.  <i>nnn</i> (the absolute value of the return minus 1000) gives the 1-based position of the character being scanned when the error was discovered. The value for an error occurring at end-of-string is the length of the string + 1.</p><p>Prior to <var class="product">Sirius Mods</var> Version 7.0, an invalid regex results in a Status value of <code>-1</code>.</p></td></tr>
<tr><th><var>-1</var>nnn</th>
<td><p>A regex in <var class="term">sl</var> is invalid.  <i>nnn</i> (the absolute value of the return minus 1000) gives the 1-based position of the character being scanned when the error was discovered. The value for an error occurring at end-of-string is the length of the string + 1.</p><p>Prior to <var class="product">Sirius Mods</var> Version 7.0, an invalid regex results in a <var>Status</var> value of <code>-1</code>.</p></td></tr>
</table>
</table>
<b>Note:</b> If you omit this argument and a negative <var class="Term">Status</var> value is to be returned, the run is cancelled.</td></tr>
<b>Note:</b> If you omit this argument and a negative <var>Status</var> value is to be returned, the run is cancelled.</td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
<ul><li>All errors in <var class="term">RegexReplaceCorresponding</var>, including invalid argument(s) result in request cancellation.
<ul>
<li>It is strongly recommended that you protect your environment from regular expression processing demands on PDL and STBL space by setting, say, <code>UTABLE LPDLST 3000</code> and <code>UTABLE LSTBL 9000</code>. See <var>[[Regex_processing#User_Language_programming_considerations|"User Language programming considerations"]]</var>.
<li>All errors in <var>RegexReplaceCorresponding</var>, including invalid argument(s) result in request cancellation.
<li>Items in <var  class="term">sl</var> must <b><i>not</i></b> exceed 6124 bytes. However, the <var class="term">inString</var> value and items in <var class="term">replacementList</var> may exceed 6124 bytes.<li>For information about additional methods and $functions that support regular expressions, see <var>[[Regex_processing|"Regex Processing"]]</var>.
 
<li><var class="term">RegexReplaceCorresponding</var> is available as of <var class="product">[[Sirius Mods|"Sirius Mods"]]</var> Version 6.9.</ul>
<li>It is strongly recommended that you protect your environment from regular expression processing demands on PDL and STBL space by setting, say, <code>UTABLE LPDLST 3000</code> and <code>UTABLE LSTBL 9000</code>. See [[Regex processing#SOUL programming considerations|SOUL programming considerations]].
 
<li>Items in <var  class="term">sl</var> must <b><i>not</i></b> exceed 6124 bytes. However, the <var class="term">inString</var> value and items in <var class="term">replacementList</var> may exceed 6124 bytes.<li>For information about additional methods and $functions that support regular expressions, see [[Regex_processing]].
</ul>


==Examples==
==Examples==
<ol><li>In the following code fragment, the second item in regex list <code>%regList</code> is the first to match the input string <code>inStr</code>. The subexpression in that item performs no special capturing function -- the parentheses are for grouping only. Since <code>%opt='g'</code> is specified, three replacements are made (using the corresponding, second, item in <code>%repList</code>):
In the following code fragment, the second item in regex list <code>%regList</code> is the first to match the input string <code>inStr</code>. The subexpression in that item performs no special capturing function &mdash; the parentheses are for grouping only. Since <code>%opt='g'</code> is specified, three replacements are made (using the corresponding, second, item in <code>%repList</code>):
<p class="code"> ...
<p class="code">...
%regList = new
%regList = new
text to %regList
text to %regList
<p class="code">abcx
  abcx
a(bc?)
  a(bc?)
abcd
  abcd
</p>
end text
end text


%repList = new
%repList = new
text to %repList
text to %repList
<p class="code">&
  &amp;
&&
  &amp;&amp;
&&&
  &amp;&amp;&amp;
</p>
end text
end text


Line 84: Line 122:
Print 'Status from ReplaceCorresponding is ' %st
Print 'Status from ReplaceCorresponding is ' %st
Print 'Output String: ' %outStr
Print 'Output String: ' %outStr
<p class="code">...
...
</p>
</p>
</p>


Line 91: Line 128:


<p class="code">Status from ReplaceCorresponding is 3
<p class="code">Status from ReplaceCorresponding is 3
Output String: &&1&&2&&d
Output String: &amp;&amp;1&amp;&amp;2&amp;&amp;d
</p></ol>
</p>
 


==See also==
==See also==
{{Template:Stringlist:RegexReplaceCorresponding footer}}
{{Template:Stringlist:RegexReplaceCorresponding footer}}

Latest revision as of 00:02, 11 January 2022

Replace substrings that match regex with items in a Stringlist (Stringlist class)


This method is deprecated and should not be used.

This method searches a given string for matches to one of multiple regular expressions contained in a list, and it replaces found matches with or according to a string contained in a list that corresponds to the regex list.

The regex list items are treated as mutually exclusive alternatives, and the function stops as soon as an item matches and the replacement is made. A "global" option is also available to continue searching and replacing within the given string using the matching regex item until no more matches are found.

RegexReplaceCorresponding uses the rules of regular expression matching (information about which is provided in "Regex processing rules").

RegexReplaceCorresponding accepts two required and two optional arguments, and it returns a string.

Syntax

%outString = sl:RegexReplaceCorresponding( inString, replacementList, - [Options= string], - [Status= %output]) Throws InvalidRegex

Syntax terms

outString A string set to the value of inString with each matched substring replaced by the value of the replacementList item that corresponds to the matching sl item.
sl A Stringlist object whose items are interpreted as regular expressions and applied to the inString value.
inString The input string, to which the regular expressions in sl are applied.
replacementList

A Stringlist, each of whose items is a potential replacement string for the substring of inString that is matched by the corresponding item of sl.

Except when the A option is specified (as described below for the Options argument), you can include $0 markers in replacementList items as placeholders for the substring of inString that the item matches.

xxx$0 is an example of a valid replacement string, and xxx concatenated with the portion of inString that gets matched (by the corresponding sl item) constitute the replacement string.

Any character after the dollar sign other than a zero is an error. Multiple zeroes (as many as 9) are permitted; a digit following such a string of zeroes must be escaped.

You can also use the format $m0, where m is one of the following modifiers:

U or u Specifies that the matched substring should be uppercased when inserted.
L or l Indicates that the matched substring should be lowercased when inserted.

The only characters you can escape in a replacement string are dollar sign ($), backslash (\), and the digits 0 through 9. So only these escapes are respected:\\, \$, and \0 through \9. No other escapes are allowed in a replacement string — this includes "shorthand" escapes like \d — and an "unaccompanied" backslash (\) is an error.

For example, since the scan for the number that accompanies the meta-$ stops at the first nonnumeric, you use 1$0\0 to indicate that the first matched substring should go between the numbers 1 and 0 in the replacement string.

Options This is an optional, name required, parameter supplying a string of single-letter options, which may be specified in uppercase or lowercase, in any combination, and blank separated or not as you prefer. For more information about these options, see "Common regex options".
I Do case-insensitive matching between string and regex.
S Dot-All mode: a period (.) can match any character, including carriage return and linefeed.
M Multi-line mode: let anchor characters match end-of-line indicators wherever the indicator appears in the input string. M mode is ignored if C (XML Schema) mode is specified.
C Do the match according to "XML Schema regex rules". Each regex is implicitly anchored at the beginning and end, and no characters serve as anchors.
G Replace every occurrence of the match, not just (as in non-G mode) the first matched substring only.
A Copy the replacement string as is. Do not recognize escapes; interpret a $n combination as a literal and not as a special marker; and so on.
Status The Status argument (name required) is optional; if specified, it is set to an integer code. These values are possible:
n The number of replacements made. A value greater than 1 indicates option G was in effect.
0 No match: inString not matched by any sl items.
-2 Syntax or other error: for example, the number of items in sl does not equal the number in replacementList; or a sl item exceeds 6124 bytes; or sl is empty.
-5 An invalid string in a replacementList item. For example, an invalid escape sequence, or a $ followed by any characters other than one or more (but no more than 9) zeroes.
-1nnn

A regex in sl is invalid. nnn (the absolute value of the return minus 1000) gives the 1-based position of the character being scanned when the error was discovered. The value for an error occurring at end-of-string is the length of the string + 1.

Prior to Sirius Mods Version 7.0, an invalid regex results in a Status value of -1.

Note: If you omit this argument and a negative Status value is to be returned, the run is cancelled.

Usage notes

  • All errors in RegexReplaceCorresponding, including invalid argument(s) result in request cancellation.
  • It is strongly recommended that you protect your environment from regular expression processing demands on PDL and STBL space by setting, say, UTABLE LPDLST 3000 and UTABLE LSTBL 9000. See SOUL programming considerations.
  • Items in sl must not exceed 6124 bytes. However, the inString value and items in replacementList may exceed 6124 bytes.
  • For information about additional methods and $functions that support regular expressions, see Regex_processing.

Examples

In the following code fragment, the second item in regex list %regList is the first to match the input string inStr. The subexpression in that item performs no special capturing function — the parentheses are for grouping only. Since %opt='g' is specified, three replacements are made (using the corresponding, second, item in %repList):

... %regList = new text to %regList abcx a(bc?) abcd end text %repList = new text to %repList & && &&& end text %inStr = 'abc1abc2abcd' %opt='g' %outStr = %regList:RegexReplaceCorresponding(%inStr, %repList, Options=%opt, Status=%st) Print 'Status from ReplaceCorresponding is ' %st Print 'Output String: ' %outStr ...

The result would be:

Status from ReplaceCorresponding is 3 Output String: &&1&&2&&d

See also