Object model (Grammar sub-package)¶
The core of Dragonfly is a language object model revolving around three object types: grammars, rules, and elements. This section describes that object model.
A grammar is a collection of rules. It manages the rules, loading and unloading them, activating and deactivating them, and it takes care of all communications with the speech recognition engine. When a recognition occurs, the associated grammar receives the recognition event and dispatches it to the appropriate rule.
Normally a grammar is associated with a particular context or functionality. Normally the rules within a grammar are somehow related to each other. However, neither of these is strictly necessary, they are just common use patterns.
Rules represent voice commands or parts of voice commands. Each rule has a single root element, the basis of a tree structure of elements defining how the rule is built up out of speakable parts. The element tree determines what a user must say to cause this rule to be recognized.
Rules can be exported or not exported. Whether a rule is exported or not is defined when the rule is created.
Only exported rules can be spoken directly by the user. In other words, they form the entry points into a grammar, causing things to happen (callbacks to be called) when appropriate words are recognized.
WSR distinguishes between top-level rules, which can be recognized directly, and exported rules, which can be referenced from rules in other grammars. NatLink doesn’t allow inter-grammar rule referencing and uses exported to refer to directly recognizable rules. Dragonfly follows NatLink in functionality and terminology on this topic.
Properties of exported rules:
- Exported rules are known as a top-level rules for WSR (
- Exported rules can be spoken by the user directly.
- Exported rules can be referenced from other rules within the same grammar.
- Exported rules can be referenced from rules in other grammars (only possible for WSR).
- Exported rules can be enabled and disabled to receive recognitions or not (
- Exported rules have callbacks which are called when recognition occurs (
Non-exported rules cannot be recognized directly but only as parts of other rules that reference them.
Properties of non-exported rules:
- Non-exported rules can’t be spoken by the user directly.
- Non-exported rules can be referenced from other rules within the same grammar.
- Non-exported rules can’t be referenced from rules in other grammars (never possible for DNS).
Rules can be imported, i.e. defined outside the grammar referencing them, or not imported, i.e. defined within the grammar. Whether a rule is imported or not is defined when the rule is created.
NatLink in general doesn’t allow rules from one grammar to be imported into another grammar, i.e. inter-grammar rule referencing. However, it does provide the following three built-in rules which can be imported:
dgnletters– All the letters of the alphabet for spelling
dgnwords– All words active during dictation
dgndictation– A special rule which corresponds to free-form dictation; imported by Dragonfly for its
Lists are dynamic language elements which can be updated and modified without reloading a grammar. There are two list types:
Lists of either type can be instantiated and used like normal lists /
dictionaries. They are meant to be used in Dragonfly rules via the special
DictListRef elements. The engine
is automatically notified when lists are modified.
Elements are the basic building blocks of the language model. They define exactly what can be said and thereby form the content of rules. The most common elements are:
Literal– one or more literal words
Sequence– a series of other elements
Alternative– a choice of other elements, only one of which can be said within a single recognition
Optional– an element container which makes its single child element optional
Repetition– an element class representing a repetition of one child element
RuleRef– a reference to another rule
RuleWrap– an element class used to wrap a Dragonfly element into a new private rule to be referenced by the same element or other
ListRef– a reference to a Dragonfly
DictListRef– a reference to a Dragonfly
Dictation– a free-form dictation element which allows the speaker to say one or more natural language words
Modifier– a special element that allows direct modification of the output of another element at recognition time
Impossible– a special element that cannot be recognized
Empty– a special element that is always recognized, similar to children of
See the Doctests for the fundamental element classes for element usage examples.
The above mentioned element types are at the heart of Dragonfly’s object model. But of course using them all the time to specify every grammar would be quite tedious. There are therefore also special elements which construct these basic element types from string specifications:
Compound– a special element which parses a string spec to create a hierarchy of basic elements.
Choice– a special element taking a
choicedictionary argument, interpreting keys as
Compoundstring specifications and values for what to return when compound specs are successfully decoded during the recognition process.
choiceargument may also be a list or tuple of strings, in which case the strings are also interpreted as
Compoundstring specifications. However, the values returned when compound specs are successfully decoded during the recognition process are the recognized words. Note: these values will be matching part(s) of the compound specs.