Class rxRegex

PatternPro
ClassModule rxRegex

Provides access to regular expressions.

Description:
This class provides the functionality needed to perform regular expression matching on text strings. After creating an instance and setting the regular expression pattern, use the FindFirst/FindNext methods, or the FindImmediate and FindString methods to locate matching text. Retrieve information on successful matches using the MatchString, MatchOffset, and MatchLength properties. After locating a match, substitution may be performed using the Substitute method.

Author:
Andrew Friedl

Copyright:
1998, 1999, 2000 BlackBox Software & Consulting


General Methods
object members
Pattern Public Property Let Pattern(Expression As String)
        Sets the regular expression pattern to be used in matching operations.
Pattern Public Property Get Pattern() As String
        Returns the regular expression pattern assigned to the matcher.
MatchOffset Public Property Get MatchOffset() As Long
        The offset of the most recent match.
MatchOffset Public Property Let MatchOffset(Offset As Long)
        Allows matching to begin or continue at any offset.
MatchLength Public Property Get MatchLength() As Long
        The length of the most recent match.
MatchString Public Property Get MatchString() As String
        The most recent matching string.
Newline Public Property Let Newline(S As String)
        Sets the character sequence to be recognized as a "newline"
Newline Public Property Get Newline() As String
        returns the current value of the Newline setting.
BOLmatchesBeg Public Property Let BOLmatchesBeg(B As Boolean)
        Sets the flag governing the behavior of the "^" metacharacter.
BOLmatchesBeg Public Property Get BOLmatchesBeg() As Boolean
        Returns the current value of the "beginning of line" matching flag.
EOLmatchesEnd Public Property Let EOLmatchesEnd(B As Boolean)
        Sets the flag governing the behavior of the "$" metacharacter.
EOLmatchesEnd Public Property Get EOLmatchesEnd() As Boolean
        Returns the current value of the "end of line" matching flag.
Text Public Property Let Text(T As String)
        Sets the input string.
Text Public Property Get Text() As String
        Returns the current input string.
FindFirst Public Function FindFirst(S As String) As Boolean
        Searches the input for the first match.
FindNext Public Function FindNext() As Boolean
        Searches for subsequent matches in the input string.
FindImmediate Public Function FindImmediate(S As String) As Boolean
        Searches for a match at the beginning of the input.
FindString Public Function FindString(S As String) As Boolean
        Attempts to match the entire input string.
Substitute Public Function Substitute(SubText As String) As Boolean
        Substitue a string for the current match.

General Methods - Detail
object members

Pattern

Sets the regular expression pattern to be used in matching operations.

Description:
Before searching for matches, you must set the regular expression pattern. Setting the pattern causes all previous matching to be discarded. Attempting any matching operation without a pattern raises an error.

Definition:
Public Property Let Pattern(Expression As String)

Parameters:
Expression A well formed, syntatically correct regular expression.


Pattern

Returns the regular expression pattern assigned to the matcher.

Definition:
Public Property Get Pattern() As String


MatchOffset

The offset of the most recent match.

Description:
When a match is located for a given pattern, the offset of the matching text may be retrieved using this property.

Definition:
Public Property Get MatchOffset() As Long

Returns:
A long value.


MatchOffset

Allows matching to begin or continue at any offset.

Description:
At any time before or during matching, the match offset may be set to any reasonable value for the current input string. Setting this value causes subsequent matching operations to begin at the new offset. Additionally, MatchString and MatchLength are updated to reflect a zero length match at the new offset. Setting this value less than 1 or greater than the current input's length generates an error.

Definition:
Public Property Let MatchOffset(Offset As Long)

Parameters:
Offset A long value that indicates where in current input matching should resume.


MatchLength

The length of the most recent match.

Description:
When a match is located within the current input, the length may be retrieved using this property. Zero lengths matches may occur.

Definition:
Public Property Get MatchLength() As Long

Returns:
A long value.


MatchString

The most recent matching string.

Description:
When a match is located within the current input, the value may be retrieved using this property. This value may be all, part or none of the input string depending on the length and offset of the match.

Definition:
Public Property Get MatchString() As String

Returns:
A string value.


Newline

Sets the character sequence to be recognized as a "newline"

Description:
This property allows users to set the value of the "newline". Typically, the ^ and the $ meta characters recognize the unix carriage return "\r" as the end of a line. In the DOS world, a line's end often follows this with a linefeed character "\n". PatternPro defaults to a line ending with both characters, insuring that the linefeed is not misread as the first charcter of the "next line". This property may be set to reflect unix, dos and mac style text.

Definition:
Public Property Let Newline(S As String)

Parameters:
S Only vbCr, vbLf, vbCrLf, or the default vbNewline.


Newline

returns the current value of the Newline setting.

Definition:
Public Property Get Newline() As String


BOLmatchesBeg

Sets the flag governing the behavior of the "^" metacharacter.

Description:
This flag determines whether or not the "^" metacharacter matches the beginning of a string or not. Setting this value to true causes the "^" to match the strings beginning. A false value causes "^" to match only after a valid newline sequence. The default value for this property is True. (see NewLine)

Definition:
Public Property Let BOLmatchesBeg(B As Boolean)

Parameters:
B A Boolean value.


BOLmatchesBeg

Returns the current value of the "beginning of line" matching flag.

Definition:
Public Property Get BOLmatchesBeg() As Boolean

Returns:
A Boolean


EOLmatchesEnd

Sets the flag governing the behavior of the "$" metacharacter.

Description:
This flag determines whether or not the "$" metacharacter matches the end of a string or not. Setting this value to true causes the "$" to match the inputs end. A false value causes "$" to match only at the character position prior to a valid newline sequence. The default value for this property is True. (see NewLine)

Definition:
Public Property Let EOLmatchesEnd(B As Boolean)

Parameters:
B A Boolean value.


EOLmatchesEnd

Returns the current value of the "end of line" matching flag.

Definition:
Public Property Get EOLmatchesEnd() As Boolean

Returns:
A Boolean


Text

Sets the input string.

Description:
This property allows the setting of the input string. Matching may be "continued" at the first position of the input string by calling "FindNext".

Definition:
Public Property Let Text(T As String)

Parameters:
T The new input string to be used.


Text

Returns the current input string.

Description:
This property returns the string currently being used for matching and for substitutions. The return value will reflect any and all modifications made to the string using "Substitute".

Definition:
Public Property Get Text() As String

Returns:
A string.


FindFirst

Searches the input for the first match.

Description:
This method causes the matcher to search an input string from beginning to end for a match. If a match is located, the offset, length, and value may be retrieved using appropriate properties.

Definition:
Public Function FindFirst(S As String) As Boolean

Parameters:
S The input string to be searched.

Returns:
True if a match is found, False otherwise.


FindNext

Searches for subsequent matches in the input string.

Description:
This method causes the matcher to locate the next match from the input string. Matching begins at the offset given by adding the previous match offset and length. If a previous match length was zero, matching begins at the next character. If a match is found, the offset, length, and value may be retrieved using appropriate properties. If no previous match is found using FindFirst no matches are reported.

Definition:
Public Function FindNext() As Boolean

Returns:
True if a match is found, False otherwise.


FindImmediate

Searches for a match at the beginning of the input.

Description:
This method causes the matcher search only for a match that begins on the first character of the input. A match will only be returned if it begins on the first character of the input. If a match is found, the offset, length, and value may be retrieved using appropriate properties.

Definition:
Public Function FindImmediate(S As String) As Boolean

Returns:
True if a match is found, False otherwise.


FindString

Attempts to match the entire input string.

Description:
This method causes the matcher search only for a match that begins on the first character of the input and consumes the entire input string. A match successful match will only be returned if it begins on the first character of the input includes the entire input string. If a match is found, the offset, length, and value may be retrieved using appropriate properties.

Definition:
Public Function FindString(S As String) As Boolean

Returns:
True if a match is found, False otherwise.


Substitute

Substitue a string for the current match.

Description:
This function causes the current match to be replaced with with another string. If no match has been found, this function does nothing. The replacement string may be larger or small than the current match, or even a zero length string. After substitution, matching resumes at the character folling the substituted text.

Definition:
Public Function Substitute(SubText As String) As Boolean

Parameters:
SubText The string to be substituted in for the current match.

Returns:
True if a substitution was made, False otherwise.


Generated by DocuPro for VB5
Copyright 1999-2000 BlackBox Software & Consulting