-
Notifications
You must be signed in to change notification settings - Fork 73
/
object_model.txt
218 lines (168 loc) · 8.85 KB
/
object_model.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
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.
.. toctree::
:hidden:
grammar
rules
lists
elements
context
recobs
Grammars
============================================================================
A :ref:`grammar <RefGrammar>` 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.
The :class:`~dragonfly.grammar.grammar_base.Grammar` class and derived
classes are described in the :ref:`RefGrammarClasses` section.
.. _RefObjectModelRules:
Rules
============================================================================
:ref:`Rules <RefRuleClasses>` represent voice commands or parts of voice
commands. Each rule has a single root :ref:`element
<RefObjectModelElements>`, 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.
The :class:`~dragonfly.grammar.rule_base.Rule` class and derived
classes are described in the :ref:`RefRuleClasses` section.
.. _RefObjectModelRulesExported:
Exported rules
----------------------------------------------------------------------------
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
(``SRATopLevel``).
* 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 (:meth:`~dragonfly.grammar.rule_base.Rule.enable`,
:meth:`~dragonfly.grammar.rule_base.Rule.disable`).
* Exported rules have callbacks which are called when recognition
occurs (:meth:`~dragonfly.grammar.rule_base.Rule.process_begin`,
:meth:`~dragonfly.grammar.rule_base.Rule.process_recognition`).
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).
.. _RefObjectModelRulesImported:
Imported rules
----------------------------------------------------------------------------
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
:class:`~dragonfly.grammar.elements_basic.Dictation` element
.. _RefObjectModelLists:
Lists
============================================================================
:ref:`Lists <RefListClasses>` are dynamic language elements which can be
updated and modified without reloading a grammar. There are two list types:
* :class:`~dragonfly.grammar.list.List`
-- sub-class of Python's built-in ``list`` type
* :class:`~dragonfly.grammar.list.DictList`
-- sub-class of Python's built-in ``dict`` type
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
:class:`~dragonfly.grammar.elements_basic.ListRef` and
:class:`~dragonfly.grammar.elements_basic.DictListRef` elements. The engine
is automatically notified when lists are modified.
The :class:`~dragonfly.grammar.list.ListBase` class and derived classes are
described in the :ref:`RefListClasses` section. See the
:ref:`RefGrammarListDocTests` for usage examples.
.. _RefObjectModelElements:
Elements
============================================================================
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:
* :class:`~dragonfly.grammar.elements_basic.Literal`
-- one or more literal words
* :class:`~dragonfly.grammar.elements_basic.Sequence`
-- a series of other elements
* :class:`~dragonfly.grammar.elements_basic.Alternative`
-- a choice of other elements, only one of which can be said
within a single recognition
* :class:`~dragonfly.grammar.elements_basic.Optional`
-- an element container which makes its single child element
optional
* :class:`~dragonfly.grammar.elements_basic.Repetition`
-- an element class representing a repetition of one child element
* :class:`~dragonfly.grammar.elements_basic.RuleRef`
-- a reference to another rule
* :class:`~dragonfly.grammar.elements_basic.RuleWrap`
-- an element class used to wrap a Dragonfly element into a new private
rule to be referenced by the same element or other
:class:`~dragonfly.grammar.elements_basic.RuleRef` elements
* :class:`~dragonfly.grammar.elements_basic.ListRef`
-- a reference to a Dragonfly :class:`~dragonfly.grammar.list.List`
* :class:`~dragonfly.grammar.elements_basic.DictListRef`
-- a reference to a Dragonfly :class:`~dragonfly.grammar.list.DictList`
* :class:`~dragonfly.grammar.elements_basic.Dictation`
-- a free-form dictation element which allows the speaker to say
one or more natural language words
* :class:`~dragonfly.grammar.elements_basic.Modifier`
-- a special element that allows direct modification of the output of
another element at recognition time
* :class:`~dragonfly.grammar.elements_basic.Impossible`
-- a special element that cannot be recognized
* :class:`~dragonfly.grammar.elements_basic.Empty`
-- a special element that is always recognized, similar to children of
:class:`~dragonfly.grammar.elements_basic.Optional` elements
See the :ref:`RefElementBasicDocTests` 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:
* :class:`~dragonfly.grammar.elements_compound.Compound`
-- a special element which parses a string
spec to create a hierarchy of basic elements.
* :class:`~dragonfly.grammar.elements_compound.Choice`
-- a special element taking a :code:`choice` dictionary argument,
interpreting keys as
:class:`~dragonfly.grammar.elements_compound.Compound` string
specifications and values for what to return when compound specs are
successfully decoded during the recognition process.
The :code:`choice` argument may also be a list or tuple of strings, in
which case the strings are also interpreted as
:class:`~dragonfly.grammar.elements_compound.Compound` string
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.
See the :ref:`RefElementCompoundDocTests` for
:class:`~dragonfly.grammar.elements_compound.Compound` usage examples and
see the :ref:`RefElementClasses` section for class references and further
documentation on each element class.