What are regular expressions?

So regular expressions are a general text search feature across many programming languages. They allow us to sift through text with wonderfully detailed and specific conditions. Although, the supported capabilities can vary some across implementations like in VBA.

Of course, “wonderfully detailed” can also mean “awfully annoying” to setup. I’m not trying to scare you away because it’s great overall, but it can be a bear to get running if your search criteria are uber specific or overly vague.

Setting up the regex variable

We first need to tell VBA we’re using VBScript regex for our search.

Accessing the Microsoft RegEx library

We’ll need a separate library called Microsoft VBScript Regular Expressions 5.5.

Open the relevant Dragon advanced script (see the previous article for more explanation) and press Alt+Enter. Then scroll down and click the checkbox beside the library name. Alternatively, in the Word VBA Editor select Tools → References in the menu (Windows). It will look something like this in whether accessed in the Word VBA Editor or a Dragon Professional script.

Unfortunately, In Dragon Profession you have to enable this for each script where you use regex in Dragon’s advanced scripting, but I usually copy my scripts over when creating a new command, so that isn’t much of a problem. Or you can create your regex searches in the Word VBA editor. It's not quite a 50/50 choice as far as ease of use, but it is available in both applications.

Declaring the RegEx variable

We need to tell VBA we’re using a regex search variable. Recall we declare variables in VBA using “Dim” followed by a variable name then “As” with a data type.

This is called “early binding” because we’re telling VBA ahead of time what data type we need. It is my preferred approach because it is clear and specific.

We have to use Set because a RegExp variable is an object not just a value like 0 or True. Similarly, the “New” keyword is required to create the regex object variable which we’ll use below. Otherwise, our MySearch variable would literally refer to Nothing until it was created.

Using an Object

However, you can also be vague with the variable type if you prefer.

This is called “late binding”. An “Object” is a generic data type which can refer to any type of object in VBA. You're basically telling VBA you don’t know the type but figure it out when I tell you which object to create.

Then you use CreateObject to create a specific RegEx object from the VBScript library. At this point, VBA can determine what type it should use for the MySearch variable.

The advantage with this approach is we don’t have to know specifically what data type to use. Disadvantages include we won’t get any help from the VBA editor on available variable data (properties) or actions (methods) as we create the script.

I don’t like being vague with my variable types unless there is a good reason.

Setting the search criteria

There are three basic parameters we need to set up.

Global peace (or searches)

Do we want to find only the first match or all of them? That is controlled by a “Global” True-False (Boolean) property of the search variable.

We reference the Global property with a dot . (but no spaces) after the variable name. Essentially, if Global is assigned a value of True, the following search should find all possible matches in the text, but False directs the search to find just the first match.

For custom voice commands, I often use non-global search because the text is so short, and I don’t expect a bunch of matches. For other uses with batches of text, global searches are probably more common.

Case sensitive

Do you want Donald and donald to be the same thing as far as the search results are concerned? If so, case insensitive searches are set by the IgnoreCase property.

Case insensitive is a little slower because it has to match either case (no pun intended).

For voice commands in Dragon Professional advanced scripting, most commands are recognized and given by Dragon in lower case text, so I usually use case sensitive just to make it slightly faster.

Exceptions are rare but might occur, for example, if you want to say “next paragraph” anywhere inside a dictation list variable for a custom command (more on that in an upcoming article).

Make a search pattern

This is where it gets “fun.”

Yeah, there be quotes there, so tighten your seat belt (a little), but it’s also where we begin to access the power of regex searches. Even though VBA regex is slightly less functional than some implementations in other languages, we can still do so much with it.

The search criteria is stored in a Pattern property which is just some plain text in double quotes. For now lets assume a case-insensitive search, and we’re looking at something simple like a name.

Note this article is not a full tutorial on regex search patterns because that’s a large topic. There are whole web pages dedicated to helping people understand, create, and debug regex search patterns. Some of them look more like ascii hieroglyphics than search-related text.

When the search is performed, the pattern first looks for the specific text “donald” without the parentheses possibly following by the last name "duck". Let's break it down.

Groups

The (parentheses) identify the text as a group (called submatches in VBA), specifically the first name here.

We can refer to identified groups later when we’re processing the search results. VBA regex doesn’t allow named groups like some other languages, but you can still refer to groups in the order included or generically using a For Each loop (see below).

What about the space?

Because of the literal space “ ” between the first and last names, the search pattern also requires a single space between them. Whole search patterns can fail to find a match if off by even a single space.

Last name

Finally, the search pattern looks for the following specific text “duck”. Again, the parentheses indicate a second group as part of a potential match, but the ? following it means this group is optional (0 or 1 matches of duck are allowed).

Thus, we can match with “donald ” or “donald Duck” or other case variations since our search is not case sensitive, but note the extra space with donald.

Optional space?

It’s a little awkward to have to match “donald ” with a space after it if there is no "duck" after it, so let’s add our first tweak.

The space should be optional if the last name is optional. There are a couple ways to do this, but the most straight forward is to explicitly identify a space.

We include a “?” to say the space is optional. That is, we allow 0 or 1 spaces in between the names. If you wish to allow tabs or line breaks between the names, any whitespace character is indicated by “\s” (a backslash followed by an s) instead like "\s?".

Another tweak …

Sorry another tweak … I can’t help myself.

Sometimes people accidentally hit the space bar more than once when typing, so what if you wanted to allow more spaces in between the names. Instead of the “?” we use an “*”.

The asterisk “*” says to allow 0 up to any number of spaces in between the names, and it will still count as a successful match for the overall search pattern. There is another way to be more specific with how many spaces you allow, but the above are easier and clearer to use.

But ooops …

This will now match “donald” (without a trailing space) or “Donald Duck” as expected, but unfortunately in this context, it also matches “Donaldduck” or “dOnAld    DucK” because it allows zero or more than one space between names. Also, the search is case insensitive, so we unintentionally allow some weird capitalization combinations.

See how this can get messy real quick if you want to take care of these variations? But it’s up to you how detailed and specific you want your search pattern to be.

How many groups?

The previous name pattern included two possible groups, so a single match can contain several groups of identified text. This will be important when using the results in practice, but the number of groups depends on how many groups you specify in the pattern using parentheses.

You can also designate uncaptured groups that are matched but not tracked, but we won’t worry about that here.

A voice command example pattern ...

Here is a more complicated sample search pattern to match a natural language custom voice command in Dragon Professional advanced scripting. Don’t choke or quit after this. I’m merely showing a possibility to prove it’s more useful than the above trivialized examples imply.

I’m not explaining all the details here, but this pattern is relatively simple believe it or not. An example text match might be:

The above pattern would match the last five words of the voice command.

It also allows some natural variation in the spoken command while still identifying several relevant groups. For example, this command would also make a match with the pattern.

See the variability with a single search pattern? And they sound like regular English.

What do I do with it?

We would need some additional VBA machinery to interpret the groups of text, but the pattern is the starting point. We can then use this information to identify and run an appropriate VBA macro in Microsoft Word (see previous article for the latter part of that).

There are many other things we can add to regex search patterns like look ahead matches (VBA doesn’t support look behind), subgroups, optional characters, alternative words or phrases, excluded text, numbers, and more.

Consolidate the settings

Combine these RegEx search settings into a With statement to make them easier to read (it’s also an itsy bitsy slightly tiny bit faster).

Set up the regex search

But alas, time fails us here, so let’s set up the basics of the actual regex search in VBA.

Match variables

Now we have to do the search. We need several variables to perform the search and store the results.

Match Collection variable

The matches are stored in a match collection data type.

This variable will store all the matches found. If Global is False, there will only be one match stored in the MyMatches collection.

If you don’t like remembering what data type is necessary, you can just use “Object” and let VBA figure it out, but you know how I feel about that.

Match variable

Each match has a type Match (how profound is that?).

The variable aMatch corresponds to a single match that contains a collection of submatches.

For most of my own searches, I’m only looking for a single match, meaning the first one. I wish there was a pretty way to reference the first match of the MyMatches variable, but here goes:

Matches(0) is the first match since the Collection increments members starting from zero (called zero-indexed which is common among programming languages).

SubMatches variable (not really required)

Each match will contain zero, one, or more SubMatch(es) which include all groups identified within the single match as a collection.

In practice, we probably don’t need to declare this variable explicitly since it’s only used once in a loop (see below).

Do the regex search

Now that the regex variables are set up, we’ll do the search. We need another pair of variables to store the results.

What search text?

We need some text to search. Just to be extra clear, we’ll assume it’s stored in a string variable called SomeText meaning it is plain text without any Microsoft Word-specific or even rich-text formatting.

In practice, you’ll already have a text variable you want to search such as a voice command phrase in Dragon Professional advanced scripting.

Execute the search …

The search variable MySearch has an Execute method (action) we can use.

Notice MySearch.Execute(…) performs the search, and we’re storing the results in the MyMatches variable. Set is required because the search results include more information than a plain value like 7, True, or “abc.”

Was the search successful?

If any matches were found, the Count property of MyMatches will be positive. We check this with a conditional statement.

I wish a “Found” property existed to be consistent with the Find.Found property (which gives a True or False value) when using Microsoft Word’s Find operation with a range variable, but the above is how we check for results in VBA regex.

See this previous article if you want a brief review of conditional statements in VBA.

Loop over all matches

To my knowledge, there is no way to get the number of groups (submatches) for a match in a general VBA regex search, and we don’t want to “hard code” the number based on a specific search because it will vary.

With that in mind, it’s easier to use a For Each loop with the MySubMatches variable from earlier. Recall VBA regex refers to the groups as SubMatches.

This loops over all groups found in the MySubMatches variable. The For Each loop allows us to not know how many groups exist ahead of time.

wGroup is a Variant type because For Each loops in VBA require a generic loop variable type even if you know the specific data type of the items it loops over. As the loop iterates through each member, the wGroup variable will refer to the current submatch. It corresponds to the current matched group plain text as a string.

I like prepending my loop variables with a “w” just to imply “which” text group, but it’s not required.

Or just skip the SubMatches variable …

We could skip declaring a submatch variable and just refer to the Collection directly in the For Each loop.

This is a little easier, but both versions work.