Copyright 2002-2015 Rick Mohr
 

By using alternative words and optional parts you can write a single command which is invoked by different phrases and whose behavior depends on the phrase spoken.

For example, you might want to be able to say either "Switch View" or "Next View" to switch between views in an application:

Vocola: (Switch | Next) View = {Ctrl+Tab};

Say: Switch View  Sent: {Ctrl+Tab}

Here the alternative term (Switch | Next) allows you to say either.

In many cases you want the actions invoked by a command to depend on which alternative was spoken. For example, you might want to move the cursor in one of four directions by saying "Move Left", "Move Down", etc.:

Vocola: Move (Left | Right | Up | Down) = {$1};

Say: Move Left  Sent: {Left}

Say: Move Down  Sent: {Down}

Here the reference $1 specifies that the first variable term should be substituted. So, when you say "Move Left" the value of the first variable term is "Left" and the keystroke {Left} is sent.

References may appear anywhere in a sequence of actions (i.e. on the right hand side of an "="), even inside quoted strings. If you want to insert the literal text "$1", use the escape sequence \$1.

Number ranges

Often you will want to specify a range of numbers as alternatives in a command. This can be specified concisely in Vocola, as in the following example:

Vocola: Move Down 1..9 = {Down_$1};

Say: Move Down 1  Sent: {Down_1}

Say: Move Down 6  Sent: {Down_6}

Here the syntax 1..9 is shorthand for (1|2|3|4|5|6|7|8|9). On the right hand side we substitute the spoken number (e.g. 6) to construct the syntax for a repeated keystroke ({Down_6}) and we have a command which moves the cursor down a specified number of lines.

In real life it's very useful to control the arrow keys by saying simply "1 Down", "3 Left", "6 Up", etc. Here's how to write it in Vocola:

Vocola: 1..99 (Left | Right | Up | Down) = {$2_$1};

Say: 3 Left   Sent: {Left_3}

Say: 12 Down  Sent: {Down_12}

This command has two variable terms. On the right-hand side the second term (which direction to move) is substituted first and the first term (how many times) is substituted second, to create the necessary keystroke syntax.

Note that large number ranges such as 1..9999 can cause recognition problems. One solution is to define more than one smaller range to denote a larger range, as for example in these commands to go to a particular line number in Visual Studio:

Vocola: Line 1..100        = {Ctrl+g} $1      {Enter};

        Line 1..99 Oh 1..9 = {Ctrl+g} $1 0 $2 {Enter};
        Line 1..99 10..99  = {Ctrl+g} $1 $2   {Enter};

Say: Line Sixty One Oh Nine  Sent: {Ctrl+g}6109{Enter}

Say: Line Eight Forty Three  Sent: {Ctrl+g}843{Enter}

Optional parts

You may want different ways of saying the same command; perhaps a longer form which is easy to remember and a shorter form for everyday use. For example, you might want to be able to say either "Kill Back 3" or just "Back 3" to delete 3 characters before the insertion point:

Vocola: [Kill] Back 1..99 = {Backspace_$1};

Say: Kill Back 3  Sent: {Backspace_3}

Say: Back 3       Sent: {Backspace_3}

Enclosing the word "Kill" in square brackets does the trick, making it an optional word. Note that references refer only to alternative terms so $1 here refers to the range 1..99, not the optional word Kill.

More generally, you can make almost any part of your command optional by enclosing it in square brackets. For example, here is a different way of approaching the large number problem:

Vocola: Line 1..9 [0..9 [0..9 [0..9]]] = {Ctrl+g} $1$2$3$4 {Enter};

            

Say: Line Six One Zero Nine  Sent: {Ctrl+g}6109{Enter}

Say: Line Eight Four Three  Sent: {Ctrl+g}843{Enter}

Here, the word "Line" can be followed by 1 to 4 digits. A reference to an alternative term that has not been supplied (e.g., $4 in the 843 case) evaluates to "". Thus, $1$2$3$4 evaluates to the actual line number being given.

Optional parts are often used to allow omitting parameters in favor of defaults. For example, we could make Kill Back's number of characters to move backwards optional, defaulting to 1:

Vocola: [Kill] Back [1..99] = {Backspace_ When($1,$1,1)};

Say: Kill Back  Sent: {Backspace_1}

Say: Back 3     Sent: {Backspace_3}

Here, we use the built-in When to provide a different default than the built in one of "". The idiom When($1,$1,default) evaluates the same as $1 except with default default instead of "".

Currently Vocola 2 implements optional parts by splitting a command with an optional part into two versions, one where the optional part is not optional and another where the optional part isn't present. This is done recursively so that commands with many independent optional parts can turn into exponentially many simpler commands. Accordingly, we recommend restraint when using many optional parts.