Parsing a command phrase in a custom Dragon Professional script

Parsing a voice command roughly involves several steps:

• Identify any relevant keywords
• Set any relevant macro parameters based on the keywords (upcoming)
• Select and run intended Word VBA macro (upcoming but see also this previous article to get started)

Of course, this is a simplified set of steps, but the implementation isn’t far removed from this idealization. This article will focus on several functions to accomplish the first step. See the links for related articles on the following two steps.

Using keywords is a simple form of parsing text to act on the instruction. There are better ways to interpret command text, but for simple phrases such as with voice commands consisting of only a few words used to manipulate document content, we can still accomplish a lot with this simpler approach.

How do I search thee? Let me count the ways …

There are three main ways to search text in VBA.  Let’s start by saying what we’re not using today.

Not using Word Find in VBA

Microsoft Word’s Find property in VBA is part of the Selection object or any general Range variable. It implements the Find and Replace feature of Word in VBA. While it provides a powerful way to search Word document text, it does not apply to plain text variables without some awkward workarounds.

Nope on the In-String function also

The InStr(…) function searches a string for specific text. The function name is literally an abbreviation for “in string.” It gives the position of the desired text in a string, but it only matches specific text. No wildcards or other pattern-like searches are allowed. While it would work for our current simple parsing tasks, these features make it difficult to use when identifying spoken numbers in a command phrase. There is a workaround for numbers, but the command also reads a little more cryptically than searches using Like.

Avoiding regular expressions for now

Regular expressions (regex) allow detailed search patterns. The syntax often requires some time and testing to get right, but regex searches are powerful. Covering regular expressions is outside the scope of this article series, but if you’re interested in jumping right into probably the best approach, see this previous article for a brief introduction to setting up regex searches in VBA. However, the overall process is more involved than using command keywords. We will tackle parsing commands using regex in an upcoming article.

Today’s winner … the Like operator

In terms of simplicity, the Like operator is the probably the easiest search method. As far as available features, it falls somewhere in between using the InStr(…) function and regular expressions.

It’s an “operator” because it takes two inputs and gives a result. It’s similar to using a plus + sign with numbers (such as 1 + 2 = 3), but Like works with a text variable and a search pattern both of which are plain text strings.

Like returns a True-False (Boolean) result which we can immediately use in conditional statements to make decisions in our script.

Using Like in text searches

Like is clean and clear to read. It further allows some flexibility with wildcard characters to match varied text patterns, but it’s not as detailed as regex. Given Like's flexibility and relative simplicity, it is easier to use in many cases.

Use of keywords

We’re not enforcing a strict word order which is the point of a natural language command. These commands are relatively simple, so the relevant keywords are all we need to properly interpret the command meaning.

What is a plain text string?

Plain text is just the character content without any Microsoft Word or rich text formatting. They are almost always called “strings” in programming. Historically, this probably derived from the literal idea of connecting a string of characters together. We define a string in VBA using double quotes and often store them in “String” variables in VBA.

In VBA, a String is a “value type” akin to a number. A string is not a composite object with individual bits of data or related functions (range variables, for example, consist of data properties as well as various actions called methods that can act on that data or the document). The classification is a little muddled when using strings as arguments for functions, but that is the gist.

Store a plain text command phrase

We need some plain text to search which is usually stored in a String variable. We’ll call our variable SomeText for now.

Remember Dim is used in VBA to declare variables with specific data types. We assign plain text in double quotes to the variable using an equals sign = just like with regular numbers.

Basic form with Like

The basic form when using Like is:

We give the variable first, the Like VBA reserved word (meaning we can’t declare a VBA variable named Like), and lastly the plain text match pattern in double quotes.

Like statement result

The result of a Like statement is a True-False (Boolean) value which we can use in conditional statements to make decisions in the script (see previous article for a brief introduction). The above example statement is True if the text “paragraph” appears anywhere in the SomeText variable text.

Like with search pattern variables

The search pattern could also be another String variable which we assign like any other string variable.

However, in this article, we’ll be giving our search patterns explicitly with the Like statement as in the first example.

Wildcard characters

Each asterisk “*” in the search pattern above is a wildcard character that matches zero or more of any characters in its place—specifically before or after the word “paragraph”. In this case, we’re asking Like to look for the literal text “paragraph” in the SomeText variable while allowing any characters before or after it.

Be careful with search patterns

Valid matches can get a little tricky sometimes since leaving out either asterisk "*" changes the meaning of the search pattern. For example, this search pattern "paragraph*" looks basically the same …

This gives a result of False because the pattern does not match SomeText.

Huh?

Since this revised pattern omits the first "*", Like attempts to match the text "paragraph" but only when found at the beginning of the SomeText variable. That is, the search pattern indicates that we do not allow any characters to exist before "paragraph" in the string text. Conversely, leaving out the second asterisk in the search pattern as in "*paragraph" requires the "paragraph" text to be found at the end of the SomeText variable string.

Other wildcard characters (not used here)

Other possible wildcard characters for Like statements that are not used in this article include:

• A question mark ? indicates a single optional character (0 or 1 character) in that location of the pattern. If you are familiar with regular expression search patterns, a ? works differently there.
• A hashtag symbol # matches a single numerical digit in its pattern location. The digit is required to be present, so “##” requires a two-digit number. For example, “1” would not match the pattern “##”, but “23” would.

An upcoming article will cover a separate function to identify number keywords in a voice command phrase when using Like. If you need more specific or varied match criteria, look into regular expressions.

Using Like in conditional statements

We will repeatedly need a way to identify keywords in a command phrase and then store any respective result in another variable. Toward this end, we set up a VBA conditional statement in the form:

See this previous article for a brief review of conditional statements in VBA. We can use a Like statement as our condition since it returns a True or False result:

Like only tells us whether a match was found, so we need to manually store any needed result corresponding to the match inside the If statement.

Plural (and other) forms

This search includes standard plural word forms like “paragraphs” because it contains the singular form. For example, this is not necessary.

We’ll talk more about compound conditions in the next article, but the “*” at the end of the first search pattern catches the extra “s” in the plural form “paragraphs” automatically. Of course, if the plural form of a different word does not use the standard pluralization rule, then you would need to be more careful.

Detect which condition is True using ElseIf

If there are several important keywords, we need to distinguish between them. Once we know which match was found, we can take any necessary actions. One approach is to chain the necessary conditional matches together using ElseIf statements.

An ElseIf statement is basically a continued If statement. How you use it depends on the context.

Briefly, each ElseIf tests the condition and runs the code below the statement if the condition is True. If the current condition is False, it checks the next ElseIf statement until none are left. After any match is found, the overall If statement is ended. If no matches are found, then the steps under Else are run. Otherwise, nothing happens.

Getting the stated document element

Our first example of command parsing is to determine any document element stated in the spoken command. We expect matches for “paragraph”, “sentence”, “heading”, "word", and others; so we need to define two working variables.

Stored command phrase variable

In an upcoming article, we’ll cover how to access the spoken voice command phrase in Dragon Professional, but for now we’ll work with it as if it is already stored in a plain text String variable named sPhrase.

Document element variable

We mentioned earlier that Like searches only tell us if a match was found, so we’ll need to store the intended document element corresponding to the found match manually. We’ll call the result variable sElement which will contain the type of document element the user stated in the command.

Store stated document element

To discern which document element was stated in the sPhrase command, we’ll chain several ElseIf statements together using a series of sequential Like comparisons. Then inside each if statement, we’ll store the respective document element in sElement as a plain text value.

In a later article, we’ll use the identified element to run a specific Word macro. We cannot use a Select Case statement to accomplish the same element assignment because Like results in a True-False Boolean value rather than providing the specific matched text (regex does the latter).

Heading content case

The “heading content” keywords need to be checked before the simpler keyword “heading”. The first True result in an ElseIf chain is chosen, so any following conditions are ignored and skipped. Thus, if the search pattern “*heading*” were checked first, “heading content” would never be identified, because “*heading*” would result in a match.

But this is messy …

Unfortunately, copying this long If-ElseIf chain to every macro would be bulky and awkward. Since we’re doing the same checks over and over in related natural language commands, it is convenient and smart to extract the related steps and place them inside a function. Then we can just “call” the function and give it (called “passing”) the voice command phrase to parse. Afterward, we just store the result in the sElement variable.

Function Skeleton

Most of our keyword parsing functions are similar in structure, so we’ll use the following function skeleton:

Of course, each keyword identification function below will have it’s own unique name corresponding to the information it’s parsing from the command phrase.

What parameter?

Each function receives the command phrase as a string variable sPhrase.

I like to precede string variable names with an “s” to remind myself what type of data the variable stores. See the extension below where we include an additional default value parameter.

Return result

Since we’re encapsulating the parsing process inside a function, we no longer assign the sElement variable directly as we did above. We instead assign the result as the return value of the function. That is, we assign the return value to the function name anywhere inside the function.

If we do not find a match in the given phrase, then we return an empty string “” for simplicity.

See the extended content below with an improvement for a customizable default value.

Element phrase function

We use almost the same conditional statement as above with the chain of ElseIf statements. We’re just assigning the matched result to the function name instead. The function to parse the document element from the command phrase is:

Given the structure of the long If statement, we are guaranteed something is assigned as the returned value even if it is only an empty string "".

Using the function result

When using the function in a main voice command script, we’ll store the function result in the sElement variable:

After this step, you use sElement as needed in the main script. Nice and tidy.

Benefits of functions

The nice thing about this version is we can reuse the function in any voice command script. Using separate functions also allows us to mix and match them to create other more complex voice commands.

A small disadvantage of creating these functions is they make detailed customization a little more trouble. For example, if you wanted to exclude the document element “word” from a particular script, you can’t without modifying the function which half defeats the point of creating it. You would need to work around the excluded case within the main script.

No Dragon Professional library

On the other hand, we still run into an issue with Dragon Professional not allowing a local library of functions. We would need to use an external file for any common code, but as far as my research indicates, Dragon Professional scripts are interpreted meaning the file would be loaded every time you give a voice command.

Ummm … bad.

Dragon’s presumption seems to be that every script should be independent. I understand the intention, but it makes for clunky scripts. Including a customizable script/function library would be simple and make creating better, cleaner scripts much easier.