RegexLocate and RegexLocateUp (Stringlist functions): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (syntax diagram, tags and links)
Line 1: Line 1:
{{Template:Stringlist:RegexLocate and RegexLocateUp subtitle}}
{{Template:Stringlist:RegexLocate and RegexLocateUp subtitle}}


These methods use a regular expression (regex) to locate an item in the method <var>Stringlist</var>. They return the item number of the first item that the regex matches. Information about the regular expression matching rules observed is provided in [[Regex processing]]. The methods are available as of Version 6.9 of the <var class=product>Sirius Mods</var>. Both functions proceed item-by-item through the <var>Stringlist</var>. RegexLocate starts by default from item 1, the first item in the <var>Stringlist</var>, or it starts from the item you specify. RegexLocateUp starts from the item <tt>.n</tt> you specify and proceeds "upward" to item n-1, then n-2, and so on. RegexLocate and RegexLocateUp accept one required and five optional arguments, and they return a number. They are also callable methods. Specifying an invalid argument results in request cancellation.
These methods use a regular expression (regex) to locate an item in the method <var>Stringlist</var>. They return the item number of the first item that the regex matches. Both methods proceed item-by-item through the <var>Stringlist</var>. <var>RegexLocate</var> starts, by default, from item 1, the first item in the <var>Stringlist</var>; or it starts from the item you specify. <var>RegexLocateUp</var> starts from the item <code>n</code> you specify and proceeds "upward" to item n-1, then n-2, and so on. <var>RegexLocate</var> and <var>RegexLocateUp</var>accept one required and five optional arguments, and may, optionally, return a number. They are callable methods.
 
Information about the regular expression matching rules observed is provided in [[Regex processing]].  


==Syntax==
==Syntax==
Line 8: Line 10:
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%itemnum</th>
<tr><th>%itemNum</th>
<td>If specified, a numeric variable that is set to the number of the '''%sl''' item matched by '''regex''', or it is 0 if no items are matched.</td></tr>
<td>If specified, a numeric variable that is set to the number of the <var class="term">sl</var> item matched by <var class="term">regex</var>, or it is 0 if no items are matched.</td></tr>
<tr><th>%sl</th>
<tr><th>sl</th>
<td>A <var>Stringlist</var> object.</td></tr>
<td>A <var>Stringlist</var> object.</td></tr>
<tr><th>regex</th>
<tr><th>regex</th>
<td>A string that is interpreted as a regular expression and is applied to the '''%sl''' method <var>Stringlist</var> items to determine whether the regex finds a match.</td></tr>
<td>A string that is interpreted as a regular expression and is applied to the <var class="term">sl</var> method <var>Stringlist</var> items to determine whether the <var class="term">regex</var> finds a match.</td></tr>
<tr><th>startitem</th>
<tr><th>startItem</th>
<td>The item number from which the regex matching is to begin. If this item is not matched, the method attempts to match the item with the next higher (if RegexLocate) or lower (if RegexLocateUp) item number, and so on. This numeric value is an optional argument that defaults to 1 (if RegexLocate) or to the number of items in '''%sl''' (if RegexLocateUp). This value must not be negative and must not be greater than the number of '''sl''' items. Setting this argument to 0 is the same as setting it to 1.</td></tr>
<td>The item number from which the <var class="term">regex</var> matching is to begin. If this item is not matched, the method attempts to match the item with the next higher (if <var>RegexLocate</var>) or lower (if <var>RegexLocateUp</var>) item number, and so on. This numeric value is an optional argument that defaults to 1 (if <var>RegexLocate</var>) or to the number of items in <var class="term">sl</var> (if <var>RegexLocateUp</var>). This value must not be negative and must not be greater than the number of <var class="term">sl</var> items. Setting this argument to 0 is the same as setting it to 1.</td></tr>
<tr><th><b>StartCol=</b> num1</th>
<tr><th><b>startCol</b></th>
<td>The StartCol argument (name required) is an optional number that specifies the starting column of the range of columns in which the matched string must be located. If the argument is specified, its value must be greater than or equal to 1 and less than or equal to the EndCol argument value. If the argument is omitted, its default value is 1. If you specify a value that is greater than the length of a particular '''%sl''' item, '''regex''' is matched against the empty string for that item.</td></tr>
<td>The <var class="term">startCol</var> argument (name required) is an optional number that specifies the starting column of the range of columns in which the matched string must be located. If the argument is specified, its value must be greater than or equal to 1 and less than or equal to the <var class="term">EndCol</var> argument value. If the argument is omitted, its default value is 1. If you specify a value that is greater than the length of a particular <var class="term">sl</var> item, the <var class="term">regex</var> is matched against the empty string for that item.</td></tr>
<tr><th><b>EndCol=</b> num2</th>
<tr><th><b>endCol</b></th>
<td>The EndCol argument (name required) is an optional number that specifies the ending column of the range of columns in which the matched string must be located. If the argument is specified, its value must be greater than or equal to 1, greater than or equal to the StartCol argument value, and less than or equal to 6124. If the EndCol argument is omitted, its default value is 6124.<blockquote> If the EndCol argument is omitted and a '''%sl''' item exceeds 6124 bytes, the run is cancelled.</blockquote></td></tr>
<td>The <var class="term">endCol</var> argument (name required) is an optional number that specifies the ending column of the range of columns in which the matched string must be located. If the argument is specified, its value must be greater than or equal to 1, greater than or equal to the <var class="term">startCol</var> argument value, and less than or equal to 6124. If the <var class="term">endCol</var> argument is omitted, its default value is 6124.<br><br><b>Note:</b> If the <var class="term">endCol</var> argument is omitted and a <var class="term">sl</var> item exceeds 6124 bytes, the run is cancelled.</td></tr>
<tr><th><b>Options=</b> string</th>
<tr><th><b>Options</b></th>
<td>The Options argument (name required) is an optional string of options. The options are single letters, which may be specified in uppercase or lowercase, in any combination, and separated by blanks or not separated. For more information about these options, see [[Regex processing]].
<td>The Options argument (name required) is an optional string of options. The options are single letters, which may be specified in uppercase or lowercase, in any combination, and separated by blanks or not separated. For more information about these options, see [[Regex processing]].
<table class="syntaxNested">
<table class="syntaxNested">
<tr><th>I</th>
<tr><th>I</th>
<td>Do case-insensitive matching between '''string''' and '''regex'''.</td></tr>
<td>Do case-insensitive matching between <var class="term">sl</var> item(s) and <var class="term">regex</var>.</td></tr>
<tr><th>S</th>
<tr><th>S</th>
<td>Dot-All mode: a dot (<tt>..</tt>) can match any character, including carriage return and linefeed.</td></tr>
<td>Dot-All mode: a dot (<code>.</code>) can match any character, including carriage return and linefeed.</td></tr>
<tr><th>M</th>
<tr><th>M</th>
<td>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.</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. <code>M</code> mode is ignored if <code>C</code> (XML Schema) mode is specified.</td></tr>
<tr><th>C</th>
<tr><th>C</th>
<td>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. For more information, see :hdref refid=regxml..</td></tr>
<td>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. For more information, see [[Regex processing]].</td></tr>
</table>
</table>
</td></tr>
</td></tr>
<tr><th><b>Status=</b> num</th>
<tr><th><b>Status</b></th>
<td>The Status argument (name required) is optional; if specified, it is set to an integer code. These values are possible:
<td>The Status argument (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><i>n</i></th>
<td>The number of the '''%sl''' item that is first matched.</td></tr>
<td>The number of the <var class="term">sl</var> item that is first matched.</td></tr>
<tr><th>0</th>
<tr><th>0</th>
<td>No match: no items in :hp1.%sl:ehp1. were matched by :hp1.regex:ehp1..</td></tr>
<td>No match: no items in <var class="term">sl</var> were matched by <var class="term">regex</var>.</td></tr>
<tr><th>-2</th>
<tr><th>-2</th>
<td>The '''%startitem''' value is invalid (either a negative value or a value greater than the number of list items), or the method <var>Stringlist</var> is empty.</td></tr>
<td>The <var class="term">startItem</var> value is invalid (either a negative value or a value greater than the number of list items), or the method <var>Stringlist</var> is empty.</td></tr>
<tr><th>-1<i>nnn</i></th>
<tr><th>-1<i>nnn</i></th>
<td>The pattern in '''regex''' 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. Prior to Version 7.0 of the <var class=product>Sirius Mods</var>, an invalid regex results in a Status value of <tt>.-1</tt>.</td></tr>
<td>The pattern in <var class="term">regex</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. Prior to Version 7.0 of the <var class=product>Sirius Mods</var>, an invalid regex results in a Status value of <code>-1</code>.</td></tr>
</table>
</table>
<blockquote> If you omit this argument and a negative Status value is to be returned, the run is cancelled.</blockquote></td></tr>
<b>Note:</b> If you omit this argument and a negative Status value is to be returned, the run is cancelled.</td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
<ul><li>It is strongly recommended that you protect your environment from regex processing demands on PDL and STBL space by setting, say, <tt>.UTABLE LPDLST 3000</tt> and <tt>.UTABLE LSTBL 9000</tt>. For further discussion of this, see :hdref refid=ulcons..<li>The regex matching is limited to the first 6124 bytes of each item.<li>The request is cancelled in any of these cases:<ul><li>You specify an invalid argument option.<li>You omit the Status argument and a situation occurs that would cause a negative Status value.<li>You omit the EndCol argument and the length of an '''%sl''' item exceeds 6124 bytes.</ul><li>For information about additional methods and $functions that support regular expressions, see :hdref refid=regexp..</ul>
<ul><li>All errors in <var class="term">RegexLocate</var> / <var class="term">RegexLocateUp</var>, including invalid argument(s), will result in request cancellation.
<li>It is strongly recommended that you protect your environment from regex processing demands on PDL and STBL space by setting, say, <code>UTABLE LPDLST 3000</code> and <code>UTABLE LSTBL 9000</code>. For further discussion of this, see [[User Language Coding Considerations]].<li>The regex matching is limited to the first 6124 bytes of each item.<li>The request is cancelled in any of these cases:<ul><li>You specify an invalid argument option.<li>You omit the <var class="term">Status</var> argument and a situation occurs that would cause a negative <var class="term">Status</var> value.<li>You omit the <var class="term">endCol</var> argument and the length of an <var class="term">sl</var> item exceeds 6124 bytes.</ul><li>For information about additional methods and $functions that support regular expressions, see [[Regex processing]].
<li> The methods are available as of <var class="product">Sirius Mods</var> Version 6.9.</ul>
 
==Examples==
==Examples==
In the following code fragment, RegexLocate is applied to the method <var>Stringlist</var> <tt>.%sl</tt> to find the first occurrence of the string <tt>.'CUST'</tt>. If this is successful, the containing item is copied to a new <var>Stringlist</var>. The matching is done case-insensitively, and the starting item is the beginning of the list, by default. Substituting RegexLocateUp for RegexLocate in the example would find the last occurrence of <tt>.'CUST'</tt>.
<ol><li>
In the following code fragment, <var>RegexLocate</var> is applied to the method <var>Stringlist</var> <code>%sl</code> to find the first occurrence of the string <code>'CUST'</code>. If this is successful, the containing item is copied to a new <var>Stringlist</var>. The matching is done case-insensitively, and the starting item is the beginning of the list, by default. Substituting <var>RegexLocateUp</var> for <var>RegexLocate</var> in the example would find the last occurrence of <code>'CUST'</code>.


<pre>
<pre>
...
  ...
%sl = new
%sl = new
text to %sl
  text to %sl
%n = %list:findImageItem(%cust:ssn)
  %n = %list:findImageItem(%cust:ssn)
if %n then
  if %n then
%list:replaceImage(%n, 'CUST')
      %list:replaceImage(%n, 'CUST')
else
  else
%list:addimage('CUST')
      %list:addimage('CUST')
end if
  end if
end text
end text


Line 69: Line 75:
%itemnum = %sl:RegexLocate(%regex, Options=%opt, Status=%st)
%itemnum = %sl:RegexLocate(%regex, Options=%opt, Status=%st)
If (%itemnum EQ 0) then
If (%itemnum EQ 0) then
Print 'Status from RegexLocate[Up] is ' %st
  Print 'Status from RegexLocate[Up] is ' %st
Else
Else
Print %regex ' matches item ' %itemnum
  Print %regex ' matches item ' %itemnum
Print 'Now for %sl2 . . . '
  Print 'Now for %sl2 . . . '
%sl2 = new
  %sl2 = new
%i = %sl2:CopyItems(%sl, %itemnum, '1')
  %i = %sl2:CopyItems(%sl, %itemnum, '1')
%i = %sl2:Print
  %i = %sl2:Print
End If
  End If
...
  ...
</pre>
</pre></ol>
 


==See also==
==See also==
{{Template:Stringlist:RegexLocate and RegexLocateUp footer}}
{{Template:Stringlist:RegexLocate and RegexLocateUp footer}}

Revision as of 07:05, 27 January 2011

Find next/previous item in Stringlist that matches a regex (Stringlist class)


These methods use a regular expression (regex) to locate an item in the method Stringlist. They return the item number of the first item that the regex matches. Both methods proceed item-by-item through the Stringlist. RegexLocate starts, by default, from item 1, the first item in the Stringlist; or it starts from the item you specify. RegexLocateUp starts from the item n you specify and proceeds "upward" to item n-1, then n-2, and so on. RegexLocate and RegexLocateUpaccept one required and five optional arguments, and may, optionally, return a number. They are callable methods.

Information about the regular expression matching rules observed is provided in Regex processing.

Syntax

[%itemNum =] sl:RegexLocate( regex, [startItem], [Options= string], - [Status= %output], [StartCol= number], - [EndCol= number]) Throws InvalidRegex

[%itemNum =] sl:RegexLocateUp( regex, [startItem], [Options= string], - [Status= %output], [StartCol= number], - [EndCol= number]) Throws InvalidRegex

Syntax terms

%itemNum If specified, a numeric variable that is set to the number of the sl item matched by regex, or it is 0 if no items are matched.
sl A Stringlist object.
regex A string that is interpreted as a regular expression and is applied to the sl method Stringlist items to determine whether the regex finds a match.
startItem The item number from which the regex matching is to begin. If this item is not matched, the method attempts to match the item with the next higher (if RegexLocate) or lower (if RegexLocateUp) item number, and so on. This numeric value is an optional argument that defaults to 1 (if RegexLocate) or to the number of items in sl (if RegexLocateUp). This value must not be negative and must not be greater than the number of sl items. Setting this argument to 0 is the same as setting it to 1.
startCol The startCol argument (name required) is an optional number that specifies the starting column of the range of columns in which the matched string must be located. If the argument is specified, its value must be greater than or equal to 1 and less than or equal to the EndCol argument value. If the argument is omitted, its default value is 1. If you specify a value that is greater than the length of a particular sl item, the regex is matched against the empty string for that item.
endCol The endCol argument (name required) is an optional number that specifies the ending column of the range of columns in which the matched string must be located. If the argument is specified, its value must be greater than or equal to 1, greater than or equal to the startCol argument value, and less than or equal to 6124. If the endCol argument is omitted, its default value is 6124.

Note: If the endCol argument is omitted and a sl item exceeds 6124 bytes, the run is cancelled.
Options The Options argument (name required) is an optional string of options. The options are single letters, which may be specified in uppercase or lowercase, in any combination, and separated by blanks or not separated. For more information about these options, see Regex processing.
I Do case-insensitive matching between sl item(s) and regex.
S Dot-All mode: a dot (.) 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. For more information, see Regex processing.
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 the sl item that is first matched.
0 No match: no items in sl were matched by regex.
-2 The startItem value is invalid (either a negative value or a value greater than the number of list items), or the method Stringlist is empty.
-1nnn The pattern in regex 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 Version 7.0 of the Sirius Mods, 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 RegexLocate / RegexLocateUp, including invalid argument(s), will result in request cancellation.
  • It is strongly recommended that you protect your environment from regex processing demands on PDL and STBL space by setting, say, UTABLE LPDLST 3000 and UTABLE LSTBL 9000. For further discussion of this, see User Language Coding Considerations.
  • The regex matching is limited to the first 6124 bytes of each item.
  • The request is cancelled in any of these cases:
    • You specify an invalid argument option.
    • You omit the Status argument and a situation occurs that would cause a negative Status value.
    • You omit the endCol argument and the length of an sl item exceeds 6124 bytes.
  • For information about additional methods and $functions that support regular expressions, see Regex processing.
  • The methods are available as of Sirius Mods Version 6.9.

Examples

  1. In the following code fragment, RegexLocate is applied to the method Stringlist %sl to find the first occurrence of the string 'CUST'. If this is successful, the containing item is copied to a new Stringlist. The matching is done case-insensitively, and the starting item is the beginning of the list, by default. Substituting RegexLocateUp for RegexLocate in the example would find the last occurrence of 'CUST'.
      ...
    %sl = new
       text to %sl
       %n = %list:findImageItem(%cust:ssn)
       if %n then
          %list:replaceImage(%n, 'CUST')
       else
          %list:addimage('CUST')
       end if
    end text
    
    %opt='i'
    %regex = '''cust'''
    %itemnum = %sl:RegexLocate(%regex, Options=%opt, Status=%st)
    If (%itemnum EQ 0) then
       Print 'Status from RegexLocate[Up] is ' %st
    Else
       Print %regex ' matches item ' %itemnum
       Print 'Now for %sl2 . . . '
       %sl2 = new
       %i = %sl2:CopyItems(%sl, %itemnum, '1')
       %i = %sl2:Print
       End If
      ...
    

See also