Include Statements

Sometimes it's helpful to use a set of Vocola definitions in more than one command file. The Vocola $include statement allows you to put such shared definitions in a single file, and include that file in each of several command files.

For example, many applications need to navigate the file system to find specific files or folders. But speaking pathnames can be difficult, as can navigating through folder hierarchies by voice. What you'd really like is a single list of shortcuts to interesting folders, available in any program which needs to navigate the file system.

Create a file called folders.vch ("vch" stands for "Vocola header") to contain your list of interesting folders, defined as a Vocola variable:

<folder> := 
 ( Home              = C:\Users\Pat
 | Downloads         = C:\Users\Pat\Downloads
 | Pictures          = C:\Users\Pat\Pictures
 | [Vocola] Commands = C:\Users\Pat\Documents\Vocola3\Commands
 | Program Files     ="C:\Program Files"
 | Temp              = C:\Temp
 );

With the $include statement this list can be used in several Vocola command files, such as the one for Windows Explorer:

So for example, saying "Folder Downloads" to Windows Explorer switches to the folder C:\Users\Pat\Downloads.

The folder list is also useful in a Command Prompt (DOS box), where saying for example "Folder Temp" performs the command cd "C:\Temp":

Last and also useful is the following global command to move quickly to a specific folder in a "File Open" dialog box:

$include folders.vch;
$if Open | New | Save | File | Attachment | Browse | Directory;
  Folder <folder> = $1\{Enter};
$end

This global contextual command is active when the window title of any application contains one of the words shown. For example, when saving an attachment in Microsoft Outlook the window title is "Save Attachment", so saying "Folder Temp" switches the dialog's current folder to C:\Temp.

File name is an action sequence

Note that the filename following $include is actually a Vocola action sequence. That means the filename text uses the same rules for quotes and whitespace that apply to Vocola keystroke actions. In particular you must use quotes if the filename text contains a space character, but may omit quotes if it does not.

That also means you can call library functions to help construct the $include statement's filename. For example, you might have a different set of interesting folders at home than at work, and so want to include a different file depending on which machine you are currently using. Since the environment variable COMPUTERNAME contains the name of your machine, you could say:

On the computer named "venus" this translates to $include folders_venus.vch. If your work machine were called "venus" and your home machine were called "family", you would define your list of interesting folders in two separate files, folders_venus.vch and folders_family.vch.

Note that because $include statements are processed before other statements in a file you cannot call a user-defined function to help construct an include file name.