RegExp (gb.pcre)

This class represents a regular expression, with which you can perform matches against various strings and retrieve submatches (those parts of the subject string that match parenthesized expressions).

This class is creatable.

This class acts like a read-only array.

الثوابت
Anchored   If this compilation is specified, the pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched (the "subject string").
BadMagic   This PCRE error constant is not used in Gambas (yet.)
BadOption   This PCRE error constant is not used in Gambas (yet.)
BadUTF8   This PCRE error constant is not used in Gambas (yet.)
BadUTF8Offset   This PCRE error constant is not used in Gambas (yet.)
Callout   This PCRE error constant is not used in Gambas (yet.)
Caseless   Specifies a case-insensitive match.
DollarEndOnly   Specifies that the dollar ($) expression will not match a newline at the end of the subject string, but only the actual end of the string. By default, a dollar will match the end of the string with or without a newline preceding it.
DotAll   Specifies that the dot (.) regular expression will even match line endings, allowing you to treat a multi-line subject text as one long line.
Extended   Specifies extended regular-expression syntax. In this mode, whitespace and comments are allowed in your regular expressions. Comments are Perl-style, that is, they start with a hash (#) and continue until the next newline.
Extra   This compilation option was invented in order to turn on additional functionality of PCRE that is incompatible with Perl, but it is currently of very little use.
Greedy   Constant that allows to remove the ungreedy default option of Replace.
MatchLimit   Specifies the maximum number of matches to return.
MultiLine   Specifies that the subject text is multi-line, so that the caret (^) and dollar ($) modifiers will match the beginnings and endings of lines anywhere within the text.
NoAutoCapture   If this compilation option is specified, it disables the use of numbered capturing parentheses in the pattern.
NoMatch   This PCRE error constant is not used in Gambas (yet.)
NoMemory   This PCRE error constant is not used in Gambas (yet.)
NoSubstring   This PCRE error constant is not used in Gambas (yet.)
NoUTF8Check   When the UTF8 option is set, the validity of the pattern as a UTF-8 string is automatically checked.
NotBOL   With the MultiLine constant specified, indicates that the caret (^) expression should not match the beginning of the string. Without the MultiLine constant, indicates that the caret should never match anything.
NotEOL   With the MultiLine constant specified, indicates that the dollar ($) expression should not match the end of the string. Without the MultiLine constant, indicates that the dollar should never match anything.
NotEmpty   An empty string is not considered to be a valid match if this option is set. If there are alternatives in the pattern, they are tried. If all the alternatives match the empty string, the entire match fails.
Null   This PCRE error constant is not used in Gambas (yet.)
UTF8   This option causes PCRE to regard both the pattern and the subject as strings of UTF-8 characters instead of single-byte character strings. However, it is available only when PCRE is built to include UTF-8 support. If not, the use of this option provokes an error.
Ungreedy   Inverts the greediness of each quantifier. Every quantifier has a greedy and an ungreedy variant, e.g. the "+" quantifier is greedy and its ungreedy variant is "+?". Setting the Ungreedy flag converts all greedy variants to ungreedy ones and vice versa. It does not make all quantifiers ungreedy.
UnknownNode   This PCRE error constant is not used in Gambas (yet.)

Static methods
FindAll   Return a string array of all sub-strings matching a pattern.
Match   This static method takes the same parameters as the Regexp constructor does. However, is does not create a new object but instead it returns whether the subject matches the pattern.
Replace   Find all occurences of the specified Pattern in the Subject, and return a string where they are all replaced by the Replace string.

الخصائص
Count   Return the number of submatches produced by the regular expression.
Error   Return the error code raised by the last call to Compile or Exec method.
Offset   Returns the offset of the beginning of the match, i.e. how many characters precede it in the subject string.
Pattern   Return the regular expression pattern.
SubMatches   A submatch is a part of your pattern contained in parentheses. For example, given the pattern "brown (\S+)", the first and only element in the SubMatches collection would be the word following "brown" in the subject text. With a subject of "quick brown fox", SubMatches[0] would contain "fox" and Submatches.Count would be 1.
Subject   Return the regular expression subject.
Text   Contains the text returned by the match. With a subject of "quick brown fox" and a pattern of "brown (\S+)", Text would contain "brown fox".

الطرق
Compile   Compile allows you to pre-compile a regular expression for later execution by the Exec method. This is useful when you have one pattern which you want to match against a lot of text, because compiling once and executing many times is much faster than compiling and executing every time.
Exec   Exec lets you execute a previously compiled regular expression against a subject text. This is mainly useful when you have many different subject texts you want to match against, because you can compile a regular expression once and use Exec repeatedly for increased speed.

SubMatches

A submatch is a part of your pattern contained in parentheses.

To access the submatches use the Count property and the array accessor of the RegExp class.

Example

For example, given the regular expression: 

brown (\S+)

and subject string: 

The quick brown fox slyly jumped over the lazy dog

your Regexp object's Text (or RegEx[0].Text) property would be: 

brown fox

and its RegExp[1].Text property would give the text of the first submatch: 

fox

the offset in the string is given by the Offset property, 10 in this case.

This is just a simple example of what regular expressions can do for you when parsing textual input; they are a very powerful tool. For example, the following regular expression will extract valid email addresses for you: 

(?i)\b[a-z0-9._%\-]+@[a-z0-9._%\-]+\.[A-Z]{2,4}\b

Sample program to parse the output of vmstat -D: 
Dim sDiskIO, sVal As String
Dim cVal As New Collection
Dim rMatch As New RegExp

' get disk I/O stats
Exec ["vmstat", "-D"] To sDiskIO
For Each sVal In ["total reads", "read sectors", "writes", "written sectors"]
  rMatch.Compile("^\\s*(\\d+)\\s+" & sVal, RegExp.MultiLine)
  rMatch.Exec(sDiskIO)
  If rMatch.Count = 1 Then
    cVal[Replace(sVal, " ", "_")] = rMatch[1].Text
  Else
    Error.Raise("Missing '" & sVal & "' in 'vmstat -D' output")
  Endif
Next
Print "total reads: " & cVal!total_reads & " read sectors:" & cVal!read_sectors
Print "writes: " & cVal!writes & " written sectors: " & cVal!written_sectors

See also