Natlinkutils

The natlinkutils module contains the basic Grammar Classes of “raw” Natlink (not Dragonfly) and a few utility functions

natlinkutils.py

Python Macro Language for Dragon NaturallySpeaking

(c) Copyright 1999 by Joel Gould Portions (c) Copyright 1999 by Dragon Systems, Inc.

This file contains utility classes and functions for grammar files.

Grammar classes

GrammarBase - base class for all command and control grammars.

See documentation below just before the class definition.

DictGramBase - base class for all pure dictation grammars.

See documentation below just before the class definition.

SelectGramBase - base class for all selection grammars.

See documentation below just before the class definition.

Functions

among others, see below:

buttonClick( btnName=’left’,count=1 )

This function simulates a button click or button double click. Pass in the button name (‘left’,’right’ or ‘middle’) and the count (1 or 2)

matchWindow( moduleInfo, modName, wndText )

A utility function which determines whether moduleInfo matches a specified module name and window title. Returns window handle on match and None on mismatch. Note that moduleInfo may be (“”,””,0) which we should handle cleanly.

class DictGramBase

This base class is similar to GrammarBase except that it is used for real dictation grammars. A real dictation grammar allows a client application to get raw dictation results from the recognizer. It is very similat to creating a command and control grammar with the <dgndictation> rule except that you have the added ability to set the dictation context (words to consider as having been spoken juct before the current recognition).

Here are the functions which derived classes can call:

load( allResults=0, hypothesis=0 )

Creates the dictation grammar. See GrammarBase class for definition of flags.

unload()

Unload reset the state of the grammar. Any SAPI objects will be freed and all callbacks will be terminated.

You need to activate the grammar before it can be recognized. Activation of a dictation grammar is simplier than a command grammar because there are no named rules.

activate( window=0, exclusive=None )

noError=1 will suppress the error message when you try to activate

a rule which is already active

window=N will activate this rule conditionally when the window

whose window handle is X is the foreground window. This is the normal case. Use window=0 to activate a global rule.

deactivate()

Deactivates the grammar.

setExclusive( exclusive ):

Set or reset the exclusive flag for this grammar (see comments under activate method of GrammarBase).

Dictation gramars have a special method which allows you to indicate what text should be considered to been recognized just before this dictation result, and after this dictation result.

setContext( beforeText=’’, afterText=’’ )

Note current version of Dragon NaturallySpeaking ignore the afterText but the before text is critical to increasing recognition accuracy.

Derived classes should defined callback functions if they want recognition results. The following callback functions can be defined:

gotBegin( moduleInfo )

called when speech is detected before recognition begins. The parameter is the same value returned by getCurrentModule.

gotResultsObject( recogType, resObj )

called when results are available (before any of the other results callbacks). The first parameter is one of ‘self’,’other’ or ‘reject’ where the second two types are only possible if the allResults flag was set on the load call. The second parameter is the results object.

gotResults( words )

called when results are available for this grammar.

words = list of recognized words

gotHypothesis( words )

only called when the hypothesis flag is set on load, this callback contains the partial recognition hypothesis during recognition.

class GramClassBase

shared base class for all Grammar base classes.

Do not use this class directly. See GrammarBase, DictGramBase or SelectGramBase.

class GrammarBase

This is the basic grammar class.

All user grammar classes should use this as the base class.

Here are the functions which derived classes can call:

load( gramSpec, allResults=0, hypothesis=0 )

This function will takes a textual representation of a grammar, either as a single string or as a list of strings and load that grammar into Dragon NaturallySpeaking.

allResults=1 will make it so this grammar see every recognition

result even if it is for another grammar,

hypothesis=1 means that the gotHypothesis callback will be made.

Otherwise, that callback is not made to avoid too much overhead.

unload()

Unload reset the state of the grammar. Any SAPI objects will be freed and all callbacks will be terminated.

You need to activate rules before they will be recognized. You activate rules by name. Any rule which is “exported” in the grammar can be activated. This base class offers a number of was to activate rules depending on what is convient.

activate( ruleName, window=0, exclusive=None, noError=0 )

Activate a single rule by name.

noError=1 will suppress the error message when you try to activate

a rule which is already active

window=N will activate this rule conditionally when the window

whose window handle is X is the foreground window. This is the normal case. Use window=0 to activate a global rule.

exclusive=1 will make this grammar exclusive which means that no

other grammars will be included in recognition when this grammar is active unless they are also exclusive

activateSet( ruleNames, window=0, exclusive=None )

This is the most efficient way to activate rules, it takes a list of rules and makes sure that all those rules and only those rules are active. Do not use this function to change the window handle if you have already activates some rules with a different window handle.

activateAll( window=0, exclusive=None, exceptlist=None )

This will activate every exported rule. can optionally add a list of rules NOT to activate (QH, 2010)

deactivate( ruleName, noError=0 )

Deactivates a single rule by name.

noError=1 will suppress the error message when you try to deactivate

a rule which is not active

deactivateAll():

This will deactivate every currently active rule.

setExclusive( exclusive ):

Set or reset the exclusive flag for this grammar (see comments under activate method).

Lists are part of SAPI. They are list subrules except that they can be changed while the grammar is loaded. Also, the list a word comes from is not available in recognition results, you only see the innermost rule name in recognition results.

emptyList( listName )

This will remove all words currently in a names list.

appendList( listName, words )

This will add one word (phrase) or a list of words (phrases) to a named list.

setList( listName, words )

This function is an efficient way to set the contents of a list in one operation to a list of words or phrases.

Derived classes should defined callback functions if they want recognition results. The following callback functions can be defined:

gotBegin( moduleInfo )

called when speech is detected before recognition begins. The parameter is the same value returned by getCurrentModule.

gotResultsObject( recogType, resObj )

called when results are available (before any of the other results callbacks). The first parameter is one of ‘self’,’other’ or ‘reject’ where the second two types are only possible if the allResults flag was set on the load call. The second parameter is the results object.

gotResultsInit( words, fullResults )

called when results are available for this grammar before any calls to gotResults_XXX. Parameters are a list of the recognized words and a list of word,ruleName pairs.

gotResults_XXX( words, fullResults )

called when results are available. The XXX refers to the rule name in the grammar. This function is called once for each sequential series of words in the results which come from the same rule in the grammar. The first parameter is the sequential series of words and the second parameter is a list of word,ruleName pairs.

gotResults( words, fullResults )

called when results are available for this grammar before any calls to gotResults_XXX. Parameters are a list of the recognized words and the same value a list of word,ruleName pairs.

gotHypothesis( words)

only called when the hypothesis flag is set on load, this callback contains the partial recognition hypothesis during recognition.

Here is an example of how the callbacks work. Assume the following grammar:

<start> exported = this <ruleOne> is {list} <ruleOne> = big <ruleTwo> object <ruleTwo> = red | blue

And assume that {list} contains the words “good” and “bad”.

Now if “this big red object is good” is recognized, the following callbacks will be made (in the order indicated).

activateAll(window=0, exclusive=None, exceptlist=None)

activate all rules

as experiment first deactivate all rules before doing so

activateSet(ruleNames, window=0, exclusive=None)

activate a set of rules.

dpi16: deactivate all and activate the new rules.

callRuleResultsFunctions(seqsAndRules, fullResults)

call the rule functions, can be overloaded (eg in DocstringGrammar)

Also give self.nextRule (the name) self.nextWords, self.prevRule, self.prevWords so the result of the adjacent rules are known

deactivateAll()

deactivate all rules and reset explicit the exclusive state of the grammar

isActive()

return True is active (rules activated), False if loaded, but no rules active return None if grammar is not loaded (yet)

isExclusive()

return True if exclusive, False if non-exclusive (most of the time)

isLoaded()

return True if grammar is loaded

resultsCallback(wordsAndNums, resObj)

when a recognition for this grammar occurs, this function gets called

by GramObj (it is set as the callback in GrammarBase.load).

if the allResults flag is set it is possible that the first parameter will be a string instead of a data structure. We compute the recognition type from this parameter

setExclusive(exclusive)

call into gramObj directly maintain self.exclusiveState

class SelectGramBase

This base class is used for select XYZ grammars.

This base class is similar to GrammarBase except that it is used for A select XYZ grammar is a special grammar which recognizes an utterance of the form “<verb> <text> [ through <text> ]” where <verb> is specified and <text> is an arbitrary sequence of words in a specified text buffer.

Here are the functions which derived classes can call:

make default select and through words “select” and “through” (lower case) Quintijn december 2010 adapt to throughWords as well, for future enhancement VoiceCode Quintijn August, 2009

load( selectWords=[‘Select’], throughWord=’Through’, throughWords=None, allResults=0, hypothesis=0 )

selectWords is a list of words or phrases which can introduce a

comand of this type. For example, you can pass in a list like [‘Select’,’Correct’,’Insert Before’,’Insert After’] to simulate some of NatSpeak’s behavior.

throughWord is a single word which is used between the two parts of

the command as in “Select <text> Through <text>”. Pass in None or an empty string to disable two part commands.

allResults=1 will make it so this grammar see every recognition

result even if it is for another grammar,

hypothesis=1 means that the gotHypothesis callback will be made.

Otherwise, that callback is not made to avoid too much overhead.

unload()

Unload reset the state of the grammar. Any SAPI objects will be freed and all callbacks will be terminated.

You need to activate the grammar before it can be recognized. Activation of a dictation grammar is simplier than a command grammar because there are no named rules.

activate( window=0, exclusive=None )

noError=1 will suppress the error message when you try to activate

a rule which is already active

window=N will activate this rule conditionally when the window

whose window handle is X is the foreground window. This is the normal case. Use window=0 to activate a global rule.

deactivate()

Deactivates the grammar.

setExclusive( exclusive ):

Set or reset the exclusive flag for this grammar (see comments under activate method of GrammarBase).

Selection gramars work on a text buffer which you pass to the grammar. The speech recognition engine maintains a copy of this text and performs all selection on its copy. Then when the grammar is recognized, you can find out the range of text which is effected.

setSelectText(text)

Pass in a block of text (string).

getSelectText()

Returns the text buffer contents currently stored in the speech recognition engine.

Derived classes should defined callback functions if they want recognition results. The following callback functions can be defined:

gotBegin( moduleInfo )

called when speech is detected before recognition begins. The parameter is the same value returned by getCurrentModule.

gotResultsObject( recogType, resObj )

called when results are available (before any of the other results callbacks). The first parameter is one of ‘self’,’other’ or ‘reject’ where the second two types are only possible if the allResults flag was set on the load call. The second parameter is the results object.

gotResults( words, start, end )

called when results are available for this grammar.

words = list of recognized words

the first word will be one of the words or phrases in selectWords (passed in when the grammar was created).

start = index into getSelectText of the start of the selection

end = index into getSelectText of the end of the selection

gotHypothesis( words )

only called when the hypothesis flag is set on load, this callback contains the partial recognition hypothesis during recognition.

makeGrammar(selectWords, throughWords)

make a selection grammar, which is similar to a Microsoft SAPI grammar.

Uses the routines in gramparser.py to build the grammar just like with command grammars.

selectWords and throughWords are lists or words.

buttonClick(btnName='left', count=1, modifiers=None)

This function simulates a button click or button double click.

Pass in the button name (‘left’,’right’ or ‘middle’) and the count (1 or 2)

without parameters: a single left click

accepted values:

• btnName: ‘left’, ‘right’ or ‘middle’, or 1, 2, 3

• count: 1 or 2 or 3 (3 not fully tested)

• modifiers: ‘shift’, ‘ctrl’, ‘alt’, ‘menu’ (‘alt’ and ‘menu’ are identical)

  (see function getModifierKeyCodes below) (if you want more modifiers, separate by “+” or “ “, eg. “shift+ctrl”)

convertResults(fullResults)

This utility routine converts a fullResults parameter into a dictionary

[ ('red','color'), ('flower','object'), ('and','conj'), ('green','color') ]
Becomes:
{ 'color':['red','green'], 'object':['flower'], 'conj':['and'] }

debug_print(msg)

depends on variable debugLoad at top of module

getBaseName(name)

Utility subroutine. This returns the base module name from a complete path

getCurrentApplicationName(moduleInfo)

get the module name from currentModule info

normally: the application name from currentModule[0]

if this is applicationframehost, try from title in above dict, ApplicationFrameHostTitles

getModifierKeyCodes(modifiers)

return a list with keycodes for modifiers

input can be a list of valid modifiers (ctrl, shift or menu == alt ), either in a sequence or as single string. If string contains the + symbol or a space, the string is split before searching the keycodes

if no modifiers are given, an empty list is returned

Invalid input raises a KeyError. Testing in unittestNatLink, see testNatlinkUtilsFunctions

matchWindow(moduleInfo, modName, wndText)

A utility function which determines whether moduleInfo matches a specified module name and window title.

Returns window handle on match and None on mismatch.

Note that moduleInfo may be (“”, “”, 0) which we should handle cleanly.

playString(keys, hooks=None)

natlink.playString was deprecated, but is repaired via a python function with version 5.4.0

Therefore this function in natlinkutils is obsolete.

playString outputs a string of (keyboard) characters, including control characters (like {ctrl+c} or {right 3}) to the foreground window.

It is implemented via the sendkeys function in repository dtactions.

So you can either do:

from dtactions.sendkeys import sendkeys
(...)
sendkeys('hello world')

or:

from natlink import playString
(...)
playString('hello world again')

And forget about natlinkutils.playString!!