The Pattern built-ins implement a simplified and slightly modified subset of UNIX's regular expression pattern matching. They allow find patterns to be compiled for finding patterns within text, as well as change patterns which replacing that text as well.

A find pattern may consist of the following elements:

ElementMeaning in find pattern
cMatch exact character (c is any character here)
@cMatch escaped character ( such as @%, @[, @*)
?Match any character except end of line
%Match beginning of line
$Match end of line (null string before end of line)
[...] Match character class (any one of 'these' characters, such as [abc] or [a-z])
[!...]Match negated character class (all but these characters, such as [! ] for no spaces)
*Closure (match zero or more occurrences of the previous element, such as [0-9]* for zero or more digits)
+Closure (match one or more occurrences of the previous element, such as [A-Za-z]+ for one or more letters)
<>Brackets tagged material which is specially extracted for later reference or use

Any element of a find pattern may be 'tagged' with the angle brackets <>. The tagged elements are numbered 1..n from left to right and can be specially extracted from the return value of Pattern.Find() or specially referred to in a change pattern.

A character class consists of zero or more of the following elements, surrounded by brackets ([]):

ElementMeaning in character class
cLiteral character, including [
a-cRange of characters (digits, lower or upper case)
!Negated character class (if at beginning)
@cEscaped character (@!, @-, @@, @])

Special meaning of characters in a character class is lost when escaped or for exclamation point (!) when it is not at the beginning, and dash (-) when it is not at the beginning or end of the character class.

A change pattern is used to map the results of a find pattern to some replacement patter, as for a find and replace operation. It consists of zero or more of the following elements:

ElementMeaning in change pattern
cliteral character
&ditto (whatever was matched)
@cescaped character (such as @&)
#ntagged substring insertion

In any pattern, an escape sequence consists of the character @ followed by a single character:
ElementMeaning in escape sequence
@rcarriage return
@nend of line
@ttab character
@cany other character (including @@)

For those familiar with UNIX's regexp, use of OScript's pattern built-ins is easy keeping the following in mind:

  • Use at sign @ instead of backslash (\) to escape characters.
  • Use percent (%) instead of caret (^) to match beginning of line.
  • Use exclamation point (!) instead of caret (^) to negate at the beginning of a character class.
  • Use question mark (?) instead of dot (.) to match any character.
  • Remember that OScript's patterns are a small subset and do not support composition, etc.
    •

    Here is an example of Pattern.Find() which retrieves name value pairs, formatted in a particular way (" name = value;"), from a data string:

    String	target = "<data> firstname   =  Mary;lastname =Smith;job=plumber; phone = 555-5555; address= 4444 Some Lane, Nowhere, SS 99999; </data>"
String	search = " *<[A-Za-z]+> *= *<[!;]+>;"
String	s = target
PatFind	finder = Pattern.CompileFind( search )
List	result = Pattern.Find( s, finder )

while ( IsDefined( result ) )
	Echo( result[ 4 ], ' = "', result[ 5 ], '"' )

	s = s[ result[ 2 ] : ]
	result = Pattern.Find( s, finder )
end

    The output of the example is: 

    address = "4444 Some Lane, Nowhere, SS 99999"
firstname = "Mary"
job = "plumber"
lastname = "Smith"
phone = "555-5555"

    Here is an example of Pattern.Change() which operates on the same data, but instead produces an alteration of the input string with quoted data values and extraneous spaces removed:

    String		target = "<data> firstname   =  Mary;lastname =Smith;job=plumber; phone = 555-5555; address= 4444 Some Lane, Nowhere, SS 99999; </data>"
String		search = " *<[A-Za-z]+> *= *<[!;]+>;"
String		change = '#1="#2";'
PatFind		finder = Pattern.CompileFind( search )
PatChange	replacer = Pattern.CompileChange( change )
String		result = Pattern.Change( target, finder, replacer )

Echo( "Input: ", target )
Echo( "Result: ", result )

    The output of the example is: 

    Input: <data> firstname   =  Mary;lastname =Smith;job=plumber; phone = 555-5555; address= 4444 Some Lane, Nowhere, SS 99999; </data>
Result: <data>firstname="Mary";lastname="Smith";job="plumber";phone="555-5555";address="4444 Some Lane, Nowhere, SS 99999"; </data>

    Class Attributes Index

    o E_IllegalChangePattern
    Error returned when an invalid change pattern is compiled.
    o E_IllegalFindPattern
    Error returned when an invalid find pattern is compiled.
    o PatChangeType
    The datatype number for the PatChange datatype.
    o PatFindType
    The datatype number for the PatFind datatype.

    Class Methods Index

    o Change( String target, Dynamic find, Dynamic change, [Boolean ignoreCase] )
    Performs a find and replace on the target String with the given patterns.
    o CompileChange( String pattern )
    Returns a compiled version of the specified change pattern.
    o CompileFind( String pattern )
    Returns a compiled version of the specified find pattern.
    o Find( String target, Dynamic find, [Boolean ignoreCase] )
    Returns the result of the applying the find pattern to the target String.

    Class Attributes

    o E_IllegalChangePattern 
     Error E_IllegalChangePattern

    Error returned when an invalid change pattern is compiled.

    o E_IllegalFindPattern 
     Error E_IllegalFindPattern

    Error returned when an invalid find pattern is compiled.

    o PatChangeType 
     Integer PatChangeType

    The datatype number for the PatChange datatype.

    o PatFindType 
     Integer PatFindType

    The datatype number for the PatFind datatype.

    Class Methods

    o Change 
     String Change(
            String target,
            Dynamic find,
            Dynamic change,
           [Boolean ignoreCase] )

    Searches the target String for all occurrences of the find pattern, and replaces each occurrence with the specified change pattern.

    Parameters:
    target - The target String upon which to perform a search and replace.
    find - The find pattern, either as a String or a compiled PatFind.
    change - The change pattern, either as a String or a compiled PatChange.
    ignoreCase - If specified and TRUE, case is ignored in comparisons, otherwise FALSE, the default, for case-sensitive comparisons.
    Returns:
    The new String result of the find and replace operation.

    See the example in the class description.

    o CompileChange 
     PatChange CompileChange(
                  String pattern )

    Returns a compiled version of the specified String change pattern.

    Parameters:
    pattern - The change pattern to compile.
    Returns:
    The successfully compiled PatChange, or an Error if the pattern String could not be compiled.
    o CompileFind 
     PatFind CompileFind(
               String pattern )

    Returns a compiled version of the specified String find pattern.

    Parameters:
    pattern - The find pattern to compile.
    Returns:
    The successfully compiled PatChange, or an Error if the pattern String could not be compiled.

     

    o Find 
     List Find(
         String target,
         Dynamic find,
        [Boolean ignoreCase] )

    Finds and returns a List describing the first match found of the find pattern in the target String. Otherwise, Undefined is returned if no match could be found.

    Parameters:
    target -  The target String upon which the pattern match is performed.
    find - The find pattern, either as a String or a compiled FindPat.
    ignoreCase - If specified and TRUE, case is ignored in comparisons, otherwise FALSE, the default, for case-sensitive comparisons.
    Returns:
    If a match was found, a List, otherwise, Undefined if a match could not be found, or Error if a String pattern could not be compiled. The List will contain the following elements:

    Element    Meaning
    1    The inclusive start index of the match within the target String.
    2    The exclusive end index of the match within the target String.
    3    The complete match text as a String.
    [ 4 onwards ]    Optionally any tagged elements extracted as Strings listed in the order they were tagged.

    Remember that Pattern.Find() returns only the first match found. To do multiple matches, the material following the match must be passed back to Find() until no matches can be found. Also, find pattern should be compiled beforehand to avoid the performance costs of repeated unnecessary compilation. See the example in the class description.