
Object model
============================================================================

The core of Dragonfly is a language object model revolving 
around three types: grammars, rules, and elements.  This section 
describes that object model.


Grammars
----------------------------------------------------------------------------

A grammar is a collection of rules.  It manages the rules, 
loading and unloading them, activating and deactivating them, 
and taking care of all communications with the speech 
recognition engine.  When they recognition occurs, the 
associated grammar received 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 ``Grammar`` class and derived classes are described 
in section :ref:`RefGrammarClasses`.


Rules
----------------------------------------------------------------------------

A rule represents a voice command or part of one.  Its elements 
define exactly what its contents are, i.e. what can be said to 
activate this rule.  It has several attributes which determine, 
for example, whether it is a top-level "standalone" command 
which can be spoken directly, or whether it can only be 
referenced from a different top level rule.

Each rule has one root element which defines the language 
content of the rule.  Top-level rules have callback methods 
which are called when the rule is recognized.


Elements
----------------------------------------------------------------------------

Elements are the basic building blocks of the language model. 
The define exactly what can be said, inform 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.
 * ``RuleRef(...)`` -- a reference to another rule.
 * ``ListRef(...)`` -- a reference to a list, which is
   a dynamic language element which can be updated and
   modified without reloading the grammar.
 * ``Dictation(...)`` -- a free-form dictation element
   which allows the speaker to say one or more natural
   language words.

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 is 
therefore also a special element which constructs these basic 
element types from a string specification:

 * ``Compound(...)`` -- a special element which parses a string 
   spec to create a hierarchy of basic elements.  The format of 
   this spec is described :ref:`RefCompound`.
