6 The owa_pattern Package

The owa_pattern package in the PL/SQL Web Toolkit locates text patterns within strings and replaces the matched string with another string. Use regular expressions with the subprograms in this package.

6.1 Subprograms

Regular Expressions - this section describes the special characters, quantifiers, and flags used in forming regular expressions.

owa_pattern.amatch function - determines if a string contains the specified pattern. It lets you specify where in the string the match has to occur.

These subprograms are overloaded. That is, there are several versions of each, distinguished by the parameters they use. Specifically, there are six versions of MATCH, and four each of AMATCH and CHANGE. The subprograms use the following parameters:

line - This is the target to be examined for a match. It can be more than one line of text or a owa_text.multi_line data type.

pat - This is the pattern that the subprograms attempt to locate in line. The pattern can contain regular expressions. In the owa_pattern.change function and procedure, this parameter is called from_str.

flags - This specifies whether the search is case-sensitive or if substitutions are done globally.

6.2Regular Expressions

Specify a regular expression by creating the string you want to match interspersed with various wildcard tokens and quantifiers.

Matches the value in the current character set of the two hexadecimal digits

\<OCT>

Matches the value in the current character set of the two or three octal digits

\

Followed by any character not covered by another case matches that character

&

Applies only to CHANGE. This causes the string that matched the regular expression to be included in the string that replaces it. This differs from the other tokens in that it specifies how a target is changed rather than how it is matched. This is explained further under CHANGE.

6.2.2 Quantifiers

Any tokens except & can have their meaning extended by any of the following quantifiers. You can also apply these quantifiers to literals.

This applies only to CHANGE. It indicates a global replace. That is, all portions of the target that match the regular expression are replaced.

6.3owa_pattern.amatch function

This function specifies if a pattern occurs in a particular location in a string. There are four versions to this function:

The first and second versions of the function do not save the matched tokens (these are saved in the backrefs parameters in the third and fourth versions). The difference between the first and second versions is the pat parameter, which can be a VARCHAR2 or a pattern data type.

The third and fourth versions of the function save the matched tokens in the backrefs parameter. The difference between the third and fourth versions is the pat parameter, which can be a VARCHAR2 or a pattern data type.

flags - whether or not the search is case-sensitive, and whether or not changes are to be made globally. If "i" is specified, the search is case-insensitive. If "g" is specified, changes are made to all matches. Otherwise, the function stops after the first substitution is made.

Returns:

As a function, it returns the number of substitutions made. If the flag `g' is not used, this number can only be 0 or 1 and only the first match is replaced. The flag `g' specifies to replace all matches with the regular expression.

Example:

Example 1:

owa_pattern.change('Cats in pajamas', 'C.+in', '& red ')

The regular expression matches the substring `Cats in'. It then replaces this string with `& red'. The ampersand character (&) indicates `Cats in', since that's what matched the regular expression. Thus, this procedure replaces the string `Cats in pajamas' with 'Cats in red pajamas'. If you called this as a function instead of a procedure, the value it returns is 1, indicating that a single substitution has been made.

6.6owa_pattern.match function

This function determines if a string contains the specified pattern. The pattern can contain regular expressions. If multiple overlapping strings can match the regular expression, this function takes the longest match.

The regular expression in this function can be either a VARCHAR2 or a owa_pattern.pattern data type. Create a owa_pattern.pattern data type from a string using the owa_pattern.getpat procedure.

Create a multi_line data type from a long string using the owa_text.stream2multi procedure. If a multi_line is used, the rlist parameter specifies a list of chunks where matches were found.

If the line is a string and not a multi_line, you can add an optional output parameter called backrefs. This parameter is a row_list that holds each string in the target that was matched by a sequence of tokens in the regular expression.

pat - the pattern to match. This is either a VARCHAR2 or a owa_pattern.pattern data type data type. It it is a pattern, the output value of this parameter is the pattern matched.

backrefs - the text that is matched. Each token that is matched is placed in a cell in the owa_text.vc_arr data type PL/SQL table. This parameter is a row_list that holds each string in the target that was matched by a sequence of tokens in the regular expression.

rlist - an output parameter containing a list of matches.

flags - whether or not the search is case-sensitive. If the value of this parameter is "i", the search is case-insensitive. Otherwise the search is case-sensitive.

Returns:

TRUE if a match was found, FALSE otherwise.

Examples:

KAZOO is the target where it is searching for the zoo.* regular expression. The period indicates any character other than newline, and the asterisk matches 0 or more of the preceding characters. In this case, it matches any character other than the newline.

Therefore, this regular expression specifies that a matching target consists of zoo, followed by any set of characters neither ending in nor including a newline (which does not match the period). The i flag indicates to ignore case in the search. In this case, the function returns TRUE, which indicates that a match had been found.