Regular Expression (Regex) Pattern Matching

JADE provides the JadeRegexLibrary class, which is the abstract superclass of the regular expression (Regex) pattern‑matching Application Programming Interface (API) subclasses in JADE. This API reduces hand‑crafted string parsing and code manipulation, to assist in the reading and testing of your code.

JADE does not implement a Regex engine itself, but wraps an existing implementation (the Perl Compatible Regular Expressions (PCRE) dialect) with defined behavior and documentation. (For details, see https://www.pcre.org/current/doc/html/pcre2syntax.html.)

The JADE regular expression pattern‑matching provides:

The ability to find words and numbers, and their positions in a body of text based on a pattern
The ability to replace a word or number in a body of text based on a pattern with a substitute word or number
Extraction of data, using a pattern to extract data fields from a string
Validation of data; for example, checking that a credit card number is in the correct format
Find, replace, scan, and match APIs that support first‑only occurrence and all occurrences, as these are distinct usages
Command line Key=Value pair parsing
Log error message parsing, particularly in a test framework
Simplified JADE coding of string parsing and code manipulation
Regex functionality for the Global Search And Replace dialog
Replacement of hand‑rolled string parsing in JADE development environment to simplify and improve the long‑term ability to read and test your code

The subclasses of the JadeRegexLibrary superclass are summarized in the following table. (For details, see Volume 1 of the JADE Encyclopaedia of Classes.)

Class	Description
JadeRegex	Contains type methods for quick, simple use of the JadeRegexLibrary. Each method has common options that suit most use cases.
JadeRegexCapture	A capture group of your regular expression, containing information about it; for example, the text it matched, the group name, length, and so on
JadeRegexMatch	A single match of your regular expression against the subject string. It optionally contains JadeRegexCapture objects if you have the enable parameter of the setExplicitCapture method in the JadeRegexPattern class set to true.
JadeRegexPattern	A compiled Regex object, providing compiled methods that enable you to define more‑complex methods instead of calling a fluent type method defined in the JadeRegex class. (These methods require more programming overhead for repeated and complicated operations.)
JadeRegexResult	A result of matches that can be iterated through; that is, an array of match tuples used for Regex operations such as ReplaceAll, to store all of the successful matches of a specified string.

In addition, the JadeRegexException subclass of the NormalException class is the transient class that defines behavior for exceptions that occur as a result of JADE regular expression pattern matching.

The JadeRegexPattern class provides a more‑tailored Regex experience, giving you more control over getting matches as well as consecutive use of the API, because the pattern is not compiled with every Regex operation. The JadeRegex class provides simpler methods with common options that are useful in many situations.

The following is an example of a findAll type method for quick, simple use of the JadeRegexLibrary. (Use the JadeRegexPattern class findAll method if you want to define a more‑complex method.)

typeFindAll();
vars
    text, pattern : String;
    matches : JadeRegexResult;
    match : JadeRegexMatch;
    tagName, innerHtml : JadeRegexCapture;
    i, matchCount : Integer;
begin
    text := "
    <html>
    <head></head>
    <body>
    <importanttag>one</importanttag> <importanttag>two</importanttag>
    <importanttag>three</importanttag>
    <importanttag>four</importanttag>
    <importanttag>five</importanttag>
    <importanttag>six</importanttag>
    </body>
    </html>";

    matchCount := JadeRegex@findAll(text, "<([A-Z][A-Z0-9]*)\b[^>]*>(.*?)</\1>", 
                                    true, true, matches);
    foreach i in 1 to matchCount do
        match := matches.at(i);
        write match.value;
        tagName := match.at(1);
        innerHtml := match.at(2);
        write Tab & "Tag: " & tagName.value;
        write Tab & "inner: " & innerHtml.value;
    endforeach;

    /* output:
    <head></head>
        Tag: head
        inner:
    <importanttag>one</importanttag>
        Tag: importanttag
        inner: one
    <importanttag>two</importanttag>
        Tag: importanttag
        inner: two
    <importanttag>three</importanttag>
        Tag: importanttag
        inner: three
    <importanttag>four</importanttag>
        Tag: importanttag
        inner: four
    <importanttag>five</importanttag>
        Tag: importanttag
        inner: five
    <importanttag>six</importanttag>
        Tag: importanttag
        inner: six
    */
end;

The following is an example of the findAll method that performs a complex search operation. (Call the JadeRegex class findAll type method if you want to perform a quick, simple string search.)

findAll();
vars
    compiledPattern : JadeRegexPattern;
    result : JadeRegexResult;
    match : JadeRegexMatch;
    usernames : String;
    matchCount: Integer;
    i : Integer;
begin
    usernames := "user1;user2;WilburWattsII;user4";
    create compiledPattern;

    compiledPattern
        .setIgnoreCase(true)
        .compile("[a-z0-9_-]{3,16}");

    matchCount := compiledPattern.findAll(usernames, result);
    write "We have the following users:";
    foreach i in 1 to matchCount do
        match := result.at(i);
        write Tab&i.String&") "&match.value;
    endforeach;
    /* writes:
       We have the following users:
       1) user1
       2) user2
       3) WilburWattsII
       4) user4
    */
end;

2020.0.01 and higher