Just as you don't directly instantiate a pattern object, you don't directly instantiate a matcher. You get an instance of the Matcher class by calling the matcher() method of your pattern object. Then you send it input from anything that implements the CharSequence interface. String, StringBuffer, and CharBuffer implement CharSequence, so they are easy to pattern match. If you want to match patterns in a text file, this is also easy to do using the new Channel I/O feature. You get the Channel for the file, then you get a Buffer from the Channel. Character Buffers implement the CharSequence interface. If you need to pattern match from some other source, you can implement the CharSequence interface yourself (it's small and easy).

After you have a matcher object, it supports three kinds of match operations:

A regular expression, or pattern, is a String that describes the kind of thing you want to match. Most letters represent themselves. If you compile a literal pattern of “To: [email protected]”, it will match exactly those letters in that order. If you have a file containing old email, you could use this pattern to find all the email addressed that way.

After you have compiled a pattern and have a matcher object, you can invoke its find() method to look for the next occurrence of the pattern in the input.You can then call its group() method to get back the input sequence that was matched by the previous match operation. The code is similar to the following:

The find() method returns a Boolean result indicating if the next occurrence of the pattern was found in the input. The group() method returns a String containing the most recent part of the input to match. If you provide a main program and run the code on a file containing my email, it prints the matches with output similar to the following:

The following sections use this example data file of email. It contains five email messages, each of which starts with “From:” and continues until the next “From:”.

The following sections use this program as a framework for trying different patterns. The pattern line is marked in bold. If you want to experiment with the different patterns shown, this is the line to update. This program and the data file are on the web site afu.com/jj6.

Running the program creates the following output:

The following three lines of code may be unfamiliar:

The three lines of code specify how the bytes in the file are translated into characters as they are brought into the buffer. The earlier examples of mapped I/O just took bytes from the file and put them into bytes in the buffer. In this case, we get an object that represents the ISO 8859 Latin-1 character set (shown in Appendix B). Using that object we get a decoder object. The decoder object has the ability to “decode” or translate bytes into double-byte characters. The 8859 example is a single byte character set and the translation turns each byte in the file into two bytes in the buffer; zero is the most significant byte. For more details about character sets and encodings, see the second I/O chapter.

The pattern “To: [email protected]” won't find all email to bbb. Email should be delivered whether the domain part of the address is in upper or lowercase. This pattern matches only lowercase. As frequently happens with regular expressions, there are several different ways of writing a pattern. We can make the pattern ignore letter case by passing a flag when we compile the pattern, as shown in the following example:

Another way to achieve the same effect is to use a range. When the pattern object sees square brackets, it tries to match one of the characters inside the brackets. If we want to match “sun” without regard to case of the first letter, we could use this pattern:

The pattern in one pair of square brackets matches one character. You can use a hyphen to indicate a range of characters (hence the name for this feature). Both of the following patterns will match any single digit:

To exactly match two digits “00” to “99” we could use “[0-9][0-9]”.

A powerful feature of the range function is the ability to match “anything but” the list of characters in the range. If the first character in a range is "^” (caret), it means “match any character except the ones that follow”. In order to extract the “To:” lines for all names except those that start with “j” we could use this pattern:

"To: [^j]"

Similarly, “[^ ]” matches any character other than a space, and “[^0-9]” matches any one character that is not a digit. If you need to match against one of the special characters like square bracket or caret, you can “escape” them in the String. You escape a special character (treat it literally) by putting two backslashes before it in the String. Rather than use one backslash, use two because the rules of Java Strings take precedence over the rules of regular expression patterns. To get one backslash in a Java String, you must escape it with its own backslash.

Ranges can be used to match literal Strings. But we are often in a situation where we want to match a String that conforms to some pattern. The email subject line, for example, starts with “Subject: “, then has some kind of text, and ends with an end-of-line character. To match a pattern that includes some arbitrary text, use metacharacters.

Let's say we want to match the Subject line of email. We want a pattern to match “Subject: anything” on one line. We will use the metacharacter “.” (dot) that matches any single character. There are other metacharacters besides dot that match a single character. These metacharacters are shown in Pattern metacharacters.

We use “.” to match any character. We also need to apply a quantifier that says how many times to do this. The quantifier “*” means “any number of times.” It applies to whatever immediately precedes it. Putting together the “match any character” dot with the “any number of times” quantifier, our pattern to match the subject line of email is the following:

This matches up to the end of a line because, by default, the dot does not match line terminator characters. If you put that pattern into a suitable program and run it, you get output similar to the following:

If you look back at the email.txt file, you'll see that the “Born in London” text is not actually a subject line. We will fix that in a later section.

There are other quantifiers that can express different amounts of repetition. Table 19-2 on page 476 shows some quantifiers that specify the number of times a particular character or pattern should match. In this table, “X” represents any pattern.

You can group patterns in parentheses to indicate exactly what is being repeated. So “(\w*: \w*)*” will match any number of sequences that consist of wordcharacters-colon-space-wordcharacters. This is a pattern for email headers. Don't be fooled by the name “wordcharacter”. It only matches a single character, not an entire word. If you want it to match a word, you have to use a quantifier to repeat it, as shown in the email example.

All quantifier operators (+, *, ?, {m,n}) are greedy by default, meaning that they match as many elements of the String as possible without causing the overall match to fail. In contrast, a reluctant closure will match as few elements of the String as possible when finding matches. You can make a quantifier reluctant by appending a '?' to the quantifier. An example of a reluctant quantifier is shown later.

Another use for parentheses is to represent matching subpatterns within the overall pattern. These subpatterns are called capturing groups, and you can retrieve them independently from the matcher you use in your code. You can also refer to one of these capturing groups later in the expression itself with a backslash-escaped number. A backslash followed by a number is always interpreted as a back reference. The first back reference in a regular expression is denoted by 1, the second by 2, and so on. Therefore, the expression: “([0-9]+)==1” would match input like “2==2” or “17==17.” Remember to double those backslashes when you want to put them in a Java String!

Back references let you match against patterns that contain Reader's Digest style junk mail. If you've never received a Reader's Digest letter, it is personalized by repeating your name and other details they have on file about you. A typical phony letter would be similar to the following:

The following pattern would match against this:

As you can see, patterns quickly become difficult to read. This pattern matches the greeting and then up to the first line not containing the name. The important things in the Reader's Digest example are the expression in parentheses on the first line (the parentheses make it a capturing group), and the “\1” on the third line of the pattern, which is a back reference to capturing group 1. The back references are numbered according to the order in which their opening parenthesis appears. Capturing groups can nest inside each other.

Whenever you use parentheses, the bracketed part of the pattern becomes a capturing group (there is a way to turn that off). The method Matcher.group(int i) returns the input sequence captured by group i during the most recent match. To extract the actual name and print it, we would add the following code:

Group 1 is the name. The call to group(2) will return the String “Please contact us for more details, Peter,” since that is the most recent match of all the lines that the group captured.

Returning to our email example, the pattern “Subject: .*” will also find non-subject lines, where text similar to the following exists:

That's not an email subject line, but it contains characters that match our pattern. If we really only want Subject lines, we need to be able to specify that the pattern only matches something at the beginning of a line. To do this we use a set of metacharacters called “anchors”, which attach the pattern to a particular place. Anchor characters shows some anchor characters and how they affect matching. In this email example, anchoring the pattern to the beginning of a line is still not enough. The pattern could occur in the body of an email message at the beginning of a line. To get this exactly right, you will need to match on the whole message, and distinguish headers from the body. An exercise at the end of the chapter allows you to do that.

Notice that the anchor for the beginning of a line is a caret. Don't get confused by the fact that caret is also used in ranges with a different meaning. There are so many metacharacters needed that it's inevitable that a few would be reused. We can anchor our email subject search to the beginning of a line with a pattern similar to the following:

By default, the expressions for beginning and end of line don't do that! They only match the beginning and end of the input. You must set a pattern flag for multiple lines, as we did previously for letter case. The multiline flag will cause pattern matching to extend across line boundaries in the input. The following example shows you how to set the pattern and a couple of flags in one statement:

The flags are actually integer constants, and you “or” them together to combine their effect, as shown in the previous line of code.

Let's make this example more realistic by writing a pattern to extract a series of entire email messages. A mail message is defined as everything between one “From:” at the start of a line, and the next one. There is a method in pattern that splits an input sequence into pieces that are separated by the pattern. This is similar to what a Scanner does with a delimiter. It returns an array of Strings, and is perfect for this purpose. The code to use it looks similar to the following example:

This code will split our file into Strings, each of which contains one e-mail. The delimiter pattern is not copied into the resulting messages array.

Now let's look at a couple of other topics relating to pattern matching. The first one is alternation, which uses the “|” (vertical bar) meta character. The second topic is how to say “anything except this word”?

When you place a “|” in a pattern, it means “or”. The pattern will match if either the left side of the “|” or the right side matches the input. That's all there is to alternation! You can use parentheses to group the alternate things more explicitly if needed. There is no corresponding “and” feature, because you get that effect by writing two subpatterns one after the other. So “XY” means “match an X followed by a Y,” while “X|Y” means “match if you see either an X or a Y.”

The next topic we will cover in this section is how to match the negation of a word. Ranges provide an easy way to match the negation of a single character. There is no built-in support for negation (“everything but”) of an entire word. Most people's first guess at a pattern to exclude all lines that start with “From” is “^[^F][^r][^o][^m]”.

This doesn't do what you want! It matches everything where the first character is not an “F”, and the second character is not an “r”, and the third character is not an “o”, and so on. Because these “not equal to” conditions are “anded” together, if you have a word for which any of these letters-and-positions is a F... or .r.. or ..o. or ...m; for example, “Frob” or “grin” or “shot” or “glum” you will find that the pattern rejects that line overall as a match. Regular expressions really ought to have an operator that matches the negation of a word.

You have to create the idiom of “exclude this word” from other primitive operations that are available. To extract complete email messages, we want to start with a “From:” at the beginning of a line, and go up to but not including the next “From:” at the beginning of a line.

One way to express this is with a pattern in three parts: a “^From:” matched literally, then an “everything except a '^From'”, then a “^From:” or an end-of-input (using alternation). Following is the code example:

The “?” in pattern “*?” is the “reluctant quantifier” that we mentioned earlier. It matches zero or more times reluctantly. For example, if there is another way to interpret this match, that other part of the pattern is preferred. Similarly, the “?=From” is a special construct that provides a match with lookahead. The matching characters are not regarded as part of the captured group but remain in the buffer for the next find() attempt. Finally, the “|\z” causes a match on either the “From” or the end of input.

One place where regular expressions can be used is in the accept method of the class javax.swing.filechooser.FileFilter. The class java.io.File has a method: File[] listFiles( FileFilter filter). You can write a class implementing FileFilter and supply the only method there, which is accept(File). You can put your file selection logic in there, and base it on desired filename patterns.

There are also metawords that match entire categories, as shown in POSIX character classes.

All of the state involved in performing a match is in the matcher, so many matchers can share the same pattern. But matcher objects are not thread safe, and one matcher should not be invoked from different threads at the same time.

Finally, the JDK comes with an example program that searches for regular expressions in files. This program is also a Unix utility known as “grep,” which stands for “globally search for regular expression and print.” A much simplified version of the program follows. Please review it carefully, as it provides a non-trivial practical example of the use of regular expressions.

That concludes the discussion of regular expressions. Now let's describe some more classes from package java.util.