Updated June 2023; see History
Pre-compiling only:
xcall REGEX, pattern, patno {,flags}
General use:
xcall REGEX, pattern, status, subject {,flags, stpos, match { ,subcnt, submatch1, ... submatchn}}
xcall REGEX, pattern, status, subject ,flags, stpos, match ,subcnt, submatch(n)
REGEX provides a detailed XCALL interface to A-Shell's regular expression processor. Other interfaces to the same processor are provided in the INSTR() function and INFLD.
The first general syntax shown above is the traditional form, which uses individual submatch variables to receive the submatch results. The second uses an array to receive the submatch results.
If three parameters are specified, the type of the third parameter determines whether the operation is pre-compilation or general use: numeric (flags) for the former, string (subject) for the latter.
Parameters
pattern (String) [in]
Regular expression, without the Perl-style leading/trailing slash. To specify a pre-compiled pattern, set pattern= chr$(1) thru chr$(128) for the 128 precompiled patterns. Note that when using the same pattern string consecutively, explicit pre-compiling is superfluous; all pattern strings get internally pre-compiled, and whenever the current pattern string is the same as the previous one, the previously pre-compiled pattern is used automatically. Explicit pre-compilation only makes sense when you are repetitively using more than one pattern string in alternation.
status (F or I) [out]
Value |
Meaning |
|---|---|
>0 |
Matching success (starting position of match) |
-101 to -199 |
|
-99 |
Too few parameters |
-98 |
Unable to load PCRE library (pcre3.dll under Windows) |
-97 |
Unable to allocate memory for library |
-96 |
Unable to link to pcre_compil2 or pcre_exit function in lib |
-95 |
Invalid pre-compiled pattern number (1-128) |
-94 |
No such precompiled pattern (not previously compiled) |
-93 |
Error outputting to dynamic variable (out of memory?) |
-2 to -25 |
patno (F or I) [in/out]
For precompiling, on input must be set to an integer 1-128 (for the 128 numbered precompiled patterns). On output, will still be set to the same value for success, or <=0 on error; see status codes above. See note under pattern regarding pre-compilation.
subject (String) [in]
Subject string to test against the pattern.
flags (F or B,4) [in]
A bitmap of option flags whose symbols are defined in ASHINC:REGEX.DEF. See Options Flags. Note that you can use Perl-style internal option settings within a pattern to change options that would otherwise require using the flags parameter.
stpos (Num) [in]
Optional starting position in subject, base 1. If not specified or zero, treated same as 1 (i.e. start at beginning of subject).
match (String) [out]
Returns the string within the subject that was matched. On errors, it may return the text of the error description.
subcnt (Num) [in/out]
For the array syntax (where the subexpression matches are returned into an array instead of individual parameters), you must set subcnt to the number of elements in the array, starting from the element supplied in the parameter. In other words, if you pass submatch(1), then set subcnt to the total number of elements in the submatch() array; if you pass submatch(2), set subcnt to one less than the total.
For the non-array syntax, subcnt is ignored on input; the maximum number of possible matches is limited instead by the number of submatch1 .. submatchn parameters passed.
For either syntax, on return, subcnt will be set to the number of sub-expression matches in the subject, even if it exceeds the number of submatch parameters passed or the specified size of the submatch(n) array. Therefore, when processing the returned sub-expression matches, care must be taken that you don't get fooled by the return value of subcnt into trying to access more submatch parameters than were available to the routine or especially more array elements than exist. For example:
subcnt = .extent(submatch()) ! limit matches to extent of array
xcall REGEX, pattern, status, subject, flags, match, subcnt, submatch(1)
if status > 0 then ! on success...
for i = 1 to (subcnt min .extent(submatch())) ! process sub-matches (up to limit)
...
submatch1 ... submatchn (String) [out]
These return subexpression matches (up to the number specified by subcnt, up to a maximum number of 100. Note that null matches are quite possible; that is, subcnt may return N, but of those N, some of them, and not necessarily only the ones at the end, may be empty.
submatch(n) (String array) [out]
A single starting element in a string array, e.g. submatch(1), may be used in place of several individual submatchn parameters. The array must have a fixed number of elements, but its elements can be dynamic strings (e.g. map1 submatch(50),s,0). This is particularly useful where you are dealing with many expressions and thus don't know at the time of writing the code how many or how large they might be.
Note: Since the xcall interface does not pass information about the entire array, in order to use the array syntax, you must set subcnt to the number of elements in the array (see subcnt above), AND you must also set the PCREX_SUBMATCH_ARRAY (&h40000000) flag in the flags parameter. If the flag is not set, REGEX will treat your submatch(1) parameter as a single variable (as in the first syntax).
History
2023 June, A-Shell 6.5.1721: add support for pre-compilation options using the flags parameter. In order to distinguish this from the three-parameter general use, flags must be a numeric type.
2023 June, A-Shell 6.5.1721: increase maximum number of pre-compiled patterns from 20 to 128.
2017 March, A-Shell 6.4.1546: remove 1024 byte limit on subject string length.
Subtopics
