Chapter 10
Documenting Regular Expressions
Any programming project of significant size can benefit from good documentation. It makes the purpose of many aspects of the project clear and can assist in further development of the code at a future date. Given the compact, cryptic nature of regular expression syntax, it makes good sense seriously to consider documenting your approach to the creation of a particular regular expression and what you expect the parts of the regular expression to do.
In many circumstances, your use of regular expressions may be on a very small scale, where it is tempting to avoid any documentation. Sometimes, no documentation is the only sensible approach. For example, in some situations, such as using regular expressions in Microsoft Word or OpenOffice.org Writer, documenting a regular expression is overkill. You want to find or replace a character sequence there and then in a single document. Formal documentation is unnecessary.
However, in more significant tasks or projects, creating documentation can be a useful discipline, serving to make explicit aspects of the task that you might otherwise be tempted to allow to remain ambiguous.
Document the Problem Definition
The problem definition is a key component in recording your thought process while designing a regular expression pattern. As mentioned in earlier chapters, you may well not get the problem definition sufficiently precise the first time round. If the problem is a complex one, it may be worth recording a problem definition that isn’t what you want so that if you come back to the code in a few months’ time, you will be reminded of the work you needed to do while designing the regular expression pattern.
A first attempt at a problem definition might be very nonspecific or expressed in a way that doesn’t immediately allow definition of a pattern to match what it is hoped to do.
A first attempt at a problem definition to solve the Star Training Company problem in Chapter 1 might be as follows:
Replace Star with Moon.
A brute-force search and replace can cause a substantial number of inappropriate changes. If you made such inappropriate changes across a large number of documents in the absence of recent backups, it could take a considerable amount of time to rectify the problems that poor use of a literal regular expression caused.
Refining a problem definition depends on an understanding of the data. You might have text like the following:
Star Training Company ...
... I highly recommend Star.
Why not accept this special offer from Star?
... recent course with Star - which was great!
242
Documenting and Debugging Regular Expressions
You can see the different ways in which desired matches can be expressed. You must understand the data to be able to construct a pattern that will match (and then replace) all of these.
On the other hand, there may be text that contains similar text, which is text that you want to leave alone:
The trainer was good - a real star!
The training was excellent - star training.
Star performer among the trainers ...
Again, if you don’t take time to understand undesired possible matches, you may end up making inappropriate changes to the documents you are working with.
Add Comments to Your Code
Adding comments to your code is a basic task. Try to make comments as meaningful as possible, and try to make them express what the pattern you create is expected to do.
Comments such as the following are pretty useless, particularly when you come back to the code to find out why it isn’t doing that:
// This will replace Star with Moon
Make the comments meaningful, such as in the following example:
// This matches Star case sensitively, avoiding words like start and star
//It matches when Star is followed by a space character and the character sequence Training
//or followed by a period (full stop)
//or followed by a question mark
Comments like these give a much clearer idea of what was intended and should correspond pretty closely to components of the regular expression pattern.
If you make a false start of some kind in attempting to solve a problem, it can also be useful to include a comment about what doesn’t work and why. While it can be embarrassing to admit a mistake in your thinking, being upfront about the problem is better than wasting time a few weeks later by going down the same blind alley.
Making Use of Extended Mode
When I write code in JavaScript, Java, Visual Basic .NET, and various other programming languages. I space the components of the code out and indent nested components so that the structure of the code is easily discerned. I would never consider jamming sizeable chunks of code onto a single line if it was
243
Chapter 10
avoidable, because that is much harder to read. Making code readable and adding comments where they are most relevant make the coding and maintenance experience a much smoother one.
One of the key advantages of comments on ordinary code is that you can place the comments right next to the component of the code to which the comments relate. It’s far less useful to have comments that are a screen or two away from the code to which they refer. A similar problem can occur in many regular expression implementations, where you simply cannot put the comments adjacent to the code that they refer to.
Extended mode is available in languages such as Perl, Java, and PHP. It allows you to include comments on the same line as the pattern component that they describe. Keeping a piece of code right next to its description helps cut down on occurrences of misunderstanding code.
Extended mode in Perl is indicated by the x modifier following the second forward slash of the m// operator.
To match input from two known users, you could use a simple program such as JimOrFred.pl:
#!/usr/bin/perl -w use strict;
print “This program will say ‘Hello’ to Jim or Fred.\n”; my $myPattern = “^(Jim|Fred)\$”;
# The pattern matches only ‘Jim’ or ‘Fred’. Nothing else is allowed. print “Enter your first name here: “;
my $myTestString = <STDIN>; chomp ($myTestString);
if ($myTestString =~ m/$myPattern/x)
{
print “Hello $myTestString. How are you today?”;
}
else
{
print “Sorry I don’t know you!”;
}
The program simply accepts input from the user. If the name entered is Jim or Fred, a Hello message is displayed; otherwise, the user is told that the system doesn’t recognize the name.
Figure 10-1 shows the appearance after both the desired names have been entered.
Figure 10-1
The following single comment is reasonably informative:
# The pattern matches only ‘Jim’ or ‘Fred’. Nothing else is allowed.
244
Documenting and Debugging Regular Expressions
Extended mode allows you to give much more detail inside the code about what each part of the pattern actually does.
The file JimOrFred2.pl shows the same code using extended mode. Notice that the assignment statement for the $myPattern variable is spread over several lines:
#!/usr/bin/perl -w use strict;
print “This program will say ‘Hello’ to Jim or Fred.\n”; my $myPattern = “
^ # Matches the position before the first character on the line (Jim # Literally matches ‘Jim’
| # The alternation character Fred)# Literally matches ‘Fred’
\$” # Matches the position after the last character on the line
;
# The pattern matches only ‘Jim’ or ‘Fred’. Nothing else is allowed. print “Enter your first name here: “;
my $myTestString = <STDIN>; chomp ($myTestString);
if ($myTestString =~ m/$myPattern/x)
{
print “Hello $myTestString. How are you today?”;
}
else
{
print “Sorry I don’t know you!”;
}
What was previously written on a single line in JimOrFred.pl
my $myPattern = “^(Jim|Fred)\$”;
is now written across several lines in JimOrFred2.pl, each of which includes a comment describing what that component of the pattern does:
my $myPattern = “
^ # Matches the position before the first character on the line (Jim # Literally matches ‘Jim’
| # The alternation character Fred)# Literally matches ‘Fred’
\$” # Matches the position after the last character on the line
;
In addition to the comments allowed by extended mode, you can still include the following overall comment, which makes clear the purpose of the whole regular expression pattern:
# The pattern matches only ‘Jim’ or ‘Fred’. Nothing else is allowed.
The x modifier means that the whitespace used for layout in JimOrFred2.pl is ignored inside the value of $myPattern:
if ($myTestString =~ m/$myPattern/x)
245