Grammar sub-package¶

Dragonfly’s core is a language object model containing the following objects:

Grammars – these represent collections of rules.

Rules – these implement complete or partial voice commands, and contain a hierarchy of elements.

Elements – these form the language building blocks of voice commands, and represent literal words, element sequences, references to other rules, etc.

To illustrate this language model, we discuss an example grammar which contains 2 voice commands: “command one” and “(second command | command two) [test]”.

Grammar: container for the two voice commands

Rule: first voice command rule “command one”

Literal element: element for the literal words “command one”. This element is the root-element of the first command rule

Rule: second voice command rule “(second command | command two) [test]”

Sequence element: root-element of the second command rule

Alternative element: first child element of the sequence

Literal element: element for the literal words “second command”

Literal element: element for the literal words “command two”

Optional element: second child element of the sequence

Literal element: element for the literal words “test”

All of these different objects are described below.

Grammar classes¶

Grammar class¶

class Grammar(name, description=None, context=None, engine=None)¶

Grammar class for managing a set of rules.

This base grammar class takes care of the communication between Dragonfly’s object model and the backend speech recognition engine. This includes compiling rules and elements, loading them, activating and deactivating them, and unloading them. It may, depending on the engine, also include receiving recognition results and dispatching them to the appropriate rule.

name – name of this grammar

description (str, default: None) – description for this grammar

context (Context, default: None) – context within which to be active. If None, the grammar will always be active.

name¶: A grammar’s name.

engine¶: A grammar’s SR engine.

rules¶: List of a grammar’s rules.

lists¶: List of a grammar’s lists.

load()¶: Load this grammar into its SR engine.

unload()¶: Unload this grammar from its SR engine.

loaded¶: Whether a grammar is loaded into its SR engine or not.

enable()¶: Enable this grammar so that it is active to receive recognitions.

disable()¶: Disable this grammar so that it is not active to receive recognitions.

enabled¶: Whether a grammar is active to receive recognitions or not.

process_begin(executable, title, handle)¶

Start of phrase callback.

This method is called when the speech recognition engine detects that the user has begun to speak a phrase.

Arguments:

executable – the full path to the module whose window is currently in the foreground.
title – window title of the foreground window.
handle – window handle to the foreground window.

_process_begin(executable, title, handle)¶

Start of phrase callback.

This usually the method which should be overridden to give derived grammar classes custom behavior.

This method is called when the speech recognition engine detects that the user has begun to speak a phrase. This method is only called when this grammar’s context does match positively. It is called by the Grammar.process_begin method.

Arguments:

executable – the full path to the module whose window is currently in the foreground.
title – window title of the foreground window.
handle – window handle to the foreground window.

enter_context()¶

Enter context callback.

This method is called when a phrase-start has been detected. It is only called if this grammar’s context previously did not match but now does match positively.

exit_context()¶

Exit context callback.

This method is called when a phrase-start has been detected. It is only called if this grammar’s context previously did match but now doesn’t match positively anymore.

ConnectionGrammar class¶

class ConnectionGrammar(name, description=None, context=None, app_name=None)¶

Grammar class for maintaining a COM connection well within a given context. This is useful for controlling applications through COM while they are in the foreground. This grammar class will take care of dispatching the correct COM interface when the application comes to the foreground, and releasing it when the application is no longer there.

name – name of this grammar.

description – description for this grammar.

context – context within which to maintain the COM connection.

app_name – COM name to dispatch.

application¶: COM handle to the application.

connection_up()¶

Method called immediately after entering this instance’s context and successfully setting up its connection.

By default this method doesn’t do anything. This method should be overridden by derived classes if they need to synchronize some internal state with the application. The COM connection is available through the self.application attribute.

connection_down()¶

Method called immediately after exiting this instance’s context and disconnecting from the application.

By default this method doesn’t do anything. This method should be overridden by derived classes if they need to clean up after disconnection.

Rule classes¶

This section describes the following classes:

dragonfly.grammar.rule_base.Rule – the base rule class

dragonfly.grammar.rule_compound.CompoundRule – a rule class of which the root element is a dragonfly.grammar.element_compound.Compound element.

dragonfly.grammar.rule_mapping.MappingRule – a rule class for creating multiple spoken-form -> semantic value voice-commands.

Rule class¶

class Rule(name=None, element=None, context=None, imported=False, exported=False)¶

Rule class for implementing complete or partial voice-commands.

This rule class represents a voice-command or part of a voice- command. It contains a root element, which defines the language construct of this rule.

Constructor arguments:

name (str) – name of this rule. If None, a unique name will automatically be generated.
element (Element) – root element for this rule
context (Context, default: None) – context within which to be active. If None, the rule will always be active when its grammar is active.
imported (boolean, default: False) – if true, this rule is imported from outside its grammar
exported (boolean, default: False) – if true, this rule is a complete top-level rule which can be spoken by the user. This should be True for voice-commands that the user can speak.

The self._log logger objects should be used in methods of derived classes for logging purposes. It is a standard logger object from the logger module in the Python standard library.

active¶: Read-only access to a rule’s active state.

disable()¶: Disable this grammar so that it is not active to receive recognitions.

element¶: This rule’s root element. (Read-only)

enable()¶: Enable this grammar so that it is active to receive recognitions.

enabled¶: Whether a grammar is active to receive recognitions or not.

exported¶: Read-only access to a rule’s exported state.

grammar¶: This rule’s grammar object. (Set once)

imported¶: This rule’s imported status. (Read-only)

name¶: This rule’s name. (Read-only)

process_begin(executable, title, handle)¶

Start of phrase callback.

This method is called when the speech recognition engine detects that the user has begun to speak a phrase. It is called by the rule’s containing grammar if the grammar and this rule are active.

The default implementation of this method checks whether this rule’s context matches, and if it does this method calls _process_begin().

Arguments:

executable – the full path to the module whose window is currently in the foreground
title – window title of the foreground window
handle – window handle to the foreground window

process_recognition(node)¶

Rule recognition callback.

This method is called when the user has spoken words matching this rule’s contents. This method is called only once for each recognition, and only for the matching top-level rule.

The default implementation of this method does nothing.

Note

This is generally the method which developers should override in derived rule classes to give them custom functionality when a top-level rule is recognized.

value(node)¶

Start of phrase callback.

This method is called to obtain the semantic value associated with a particular recognition. It could be called from another rule’s value() if that rule references this rule. If also be called from this rule’s process_recognition() if that method has been overridden to do so in a derived class.

The default implementation of this method returns the value of this rule’s root element.

Note

This is generally the method which developers should override in derived rule classes to change the default semantic value of a recognized rule.

CompoundRule class¶

The CompoundRule class is designed to make it very easy to create a rule based on a single compound spec.

This rule class has the following parameters to customize its behavior:

spec – compound specification for the rule’s root element

extras – extras elements referenced from the compound spec

defaults – default values for the extras

exported – whether the rule is exported

context – context in which the rule will be active

Each of these parameters can be passed as a (keyword) arguments to the constructor, or defined as a class attribute in a derived class.

Example usage¶

The CompoundRule class can be used to define a voice-command as follows:

class ExampleRule(CompoundRule):

    spec = "I want to eat <food>"
    extras = [Choice("food", {
                              "(an | a juicy) apple": "good",
                              "a [greasy] hamburger": "bad",
                             }
                    )
             ]

    def _process_recognition(self, node, extras):
        good_or_bad = extras["food"]
        print "That is a %s idea!" % good_or_bad

rule = ExampleRule()
grammar.add_rule(rule)

Class reference¶

class CompoundRule(name=None, spec=None, extras=None, defaults=None, exported=None, context=None)¶

Rule class based on the compound element.

Constructor arguments:

name (str) – the rule’s name
spec (str) – compound specification for the rule’s root element
extras (sequence) – extras elements referenced from the compound spec
defaults (dict) – default values for the extras
exported (boolean) – whether the rule is exported
context (Context) – context in which the rule will be active

process_recognition(node)¶

Process a recognition of this rule.

This method is called by the containing Grammar when this rule is recognized. This method collects information about the recognition and then calls self._process_recognition.

node – The root node of the recognition parse tree.

MappingRule class¶

The MappingRule class is designed to make it very easy to create a rule based on a mapping of spoken-forms to semantic values.

This class has the following parameters to customize its behavior:

mapping – mapping of spoken-forms to semantic values

extras – extras elements referenced from the compound spec

defaults – default values for the extras

exported – whether the rule is exported

context – context in which the rule will be active

Each of these parameters can be passed as a (keyword) arguments to the constructor, or defined as a class attribute in a derived class.

Example usage¶

The MappingRule class can be used to define a voice-command as follows:

class ExampleRule(MappingRule):

    mapping  = {
                "[feed] address [bar]":                Key("a-d"),
                "subscribe [[to] [this] feed]":        Key("a-u"),
                "paste [feed] address":                Key("a-d, c-v, enter"),
                "feeds | feed (list | window | win)":  Key("a-d, tab:2, s-tab"),
                "down [<n>] (feed | feeds)":           Key("a-d, tab:2, s-tab, down:%(n)d"),
                "up [<n>] (feed | feeds)":             Key("a-d, tab:2, s-tab, up:%(n)d"),
                "open [item]":                         Key("a-d, tab:2, c-s"),
                "newer [<n>]":                         Key("a-d, tab:2, up:%(n)d"),
                "older [<n>]":                         Key("a-d, tab:2, down:%(n)d"),
                "mark all [as] read":                  Key("cs-r"),
                "mark all [as] unread":                Key("cs-u"),
                "search [bar]":                        Key("a-s"),
                "search [for] <text>":                 Key("a-s") + Text("%(text)s\n"),
               }
    extras   = [
                Integer("n", 1, 20),
                Dictation("text"),
               ]
    defaults = {
                "n": 1,
               }

    rule = ExampleRule()
    grammar.add_rule(rule)

Class reference¶

class MappingRule(name=None, mapping=None, extras=None, defaults=None, exported=None, context=None)¶

Rule class based on a mapping of spoken-forms to semantic values.

Constructor arguments:

name (str) – the rule’s name
mapping (dict) – mapping of spoken-forms to semantic values
extras (sequence) – extras elements referenced from the spoken-forms in mapping
defaults (dict) – default values for the extras
exported (boolean) – whether the rule is exported
context (Context) – context in which the rule will be active

process_recognition(node)¶

Process a recognition of this rule.

This method is called by the containing Grammar when this rule is recognized. This method collects information about the recognition and then calls MappingRule._process_recognition.

node – The root node of the recognition parse tree.

Element classes¶

Fundamental element classes¶

Dragonfly grammars are built up out of a small set of fundamental building blocks. These building blocks are implemented by the following element classes:

ElementBase – the base class from which all other element classes are derived

Sequence – sequence of child elements which must all match in the order given

Alternative – list of possibilities of which only one will be matched

Optional – wrapper around a child element which makes the child element optional

Repetition – repetition of a child element

Literal – literal word which must be said exactly by the speaker as given

RuleRef – reference to a dragonfly.grammar.rule_base.Rule object; this element allows a rule to include (i.e. reference) another rule

ListRef – reference to a dragonfly.grammar.list.List object

The following element classes are built up out of the fundamental classes listed above:

Dictation – free-form dictation; this element matches any words the speaker says, and includes facilities for formatting the spoken words with correct spacing and capitalization

DictListRef – reference to a dragonfly.all.DictList object; this element is similar to the dragonfly.all.ListRef element, except that it returns the value associated with the spoken words instead of the spoken words themselves

ElementBase class¶

class ElementBase(name=None, default=None)¶

Base class for all other element classes.

Constructor argument:

name (str, default: None) – the name of this element; can be used when interpreting complex recognition for retrieving elements by name.

dependencies(memo)¶

Returns an iterable containing the dependencies of this element and of this element’s children.

The dependencies are the objects that are necessary for this element. These include lists and other rules.

gstring()¶

Returns a formatted grammar string of the contents of this element and its children.

The grammar string is of a format similar to that used by Natlink to define its grammars.

decode(state)¶: Attempt to decode the recognition stored in the given state.

value(node)¶

Determine the semantic value of this element given the recognition results stored in the node.

Argument:

node – a dragonfly.grammar.state.Node instance representing this element within the recognition parse tree

The default behavior of this method is to return an iterable containing the recognized words matched by this element (i.e. node.words()).

children¶: Iterable of child elements. (Read-only)

_get_children()¶

Returns an iterable of this element’s children.

This method is used by the children() property, and should be overloaded by any derived classes to give the correct children element.

By default, this method returns an empty tuple.

element_tree_string()¶: Returns a formatted multi-line string representing this element and its children.

_copy_sequence(sequence, name, item_types=None)¶: Utility function for derived classes that checks that a given object is a sequence, copies its contents into a new tuple, and checks that each item is of a given type.

Sequence class¶

class Sequence(children=(), name=None, default=None)¶

Element class representing a sequence of child elements which must all match a recognition in the correct order.

Constructor arguments:

children (iterable, default: ()) – the child elements of this element
name (str, default: None) – the name of this element

For a recognition to match, all child elements must match the recognition in the order that they were given in the children constructor argument.

Example usage: >>> from dragonfly.test import ElementTester >>> seq = Sequence([Literal(“hello”), Literal(“world”)]) >>> test_seq = ElementTester(seq) >>> test_seq.recognize(“hello world”) [‘hello’, ‘world’] >>> test_seq.recognize(“hello universe”) RecognitionFailure

value(node)¶: The value of a Sequence is a list containing the values of each of its children.

children¶: Iterable of child elements. (Read-only)

_get_children()¶: Returns the child elements contained within the sequence.

Alternative class¶

class Alternative(children=(), name=None, default=None)¶

Element class representing several child elements of which only one will match.

Constructor arguments:

children (iterable, default: ()) – the child elements of this element
name (str, default: None) – the name of this element

For a recognition to match, at least one of the child elements must match the recognition. The first matching child is used. Child elements are searched in the order they are given in the children constructor argument.

value(node)¶: The value of an Alternative is the value of its child that matched the recognition.

children¶: Iterable of child elements. (Read-only)

_get_children()¶: Returns the alternative child elements.

Optional class¶

class Optional(child, name=None, default=None)¶

Element class representing an optional child element.

Constructor arguments:

child (ElementBase) – the child element of this element
name (str, default: None) – the name of this element

Recognitions always match this element. If the child element does match the recognition, then that result is used. Otherwise, this element itself does match but the child is not processed.

value(node)¶: The value of a Optional is the value of its child, if the child did match the recognition. Otherwise the value is None.

children¶: Iterable of child elements. (Read-only)

_get_children()¶: Returns the optional child element.

Repetition class¶

class Repetition(child, min=1, max=None, name=None, default=None)¶

Element class representing a repetition of one child element.

Constructor arguments:

child (ElementBase) – the child element of this element
min (int, default: 1) – the minimum number of times that the child element must be recognized; may be 0
max (int, default: None) – the maximum number of times that the child element must be recognized; if None, the child element must be recognized exactly min times (i.e. max = min + 1)
name (str, default: None) – the name of this element

For a recognition to match, at least one of the child elements must match the recognition. The first matching child is used. Child elements are searched in the order they are given in the children constructor argument.

value(node)¶

The value of a Repetition is a list containing the values of its child.

The length of this list is equal to the number of times that the child element was recognized.

children¶: Iterable of child elements. (Read-only)

get_repetitions(node)¶

Returns a list containing the nodes associated with each repetition of this element’s child element.

Argument:

node (Node) – the parse tree node associated with this repetition element; necessary for searching for child elements within the parse tree

Literal class¶

class Literal(text, name=None, value=None, default=None)¶

dependencies(memo)¶

Returns an iterable containing the dependencies of this element and of this element’s children.

The dependencies are the objects that are necessary for this element. These include lists and other rules.

children¶: Iterable of child elements. (Read-only)

RuleRef class¶

class RuleRef(rule, name=None, default=None)¶

children¶: Iterable of child elements. (Read-only)

ListRef class¶

class ListRef(name, list, key=None, default=None)¶

children¶: Iterable of child elements. (Read-only)

DictListRef class¶

class DictListRef(name, dict, key=None, default=None)¶

children¶: Iterable of child elements. (Read-only)

Dictation class¶

class Dictation(name=None, format=True, default=None)¶

dependencies(memo)¶

Returns an iterable containing the dependencies of this element and of this element’s children.

The dependencies are the objects that are necessary for this element. These include lists and other rules.

children¶: Iterable of child elements. (Read-only)

Compound class¶

class Compound(spec, extras=None, actions=None, name=None, value=None, value_func=None, elements=None, default=None)¶

Choice class¶

class Choice(name, choices, extras=None, default=None)¶

Table Of Contents

Previous topic

Next topic

This Page

Grammar sub-package¶

Grammar classes¶

Grammar class¶

ConnectionGrammar class¶

Rule classes¶

Rule class¶

CompoundRule class¶

Example usage¶

Class reference¶

MappingRule class¶

Example usage¶

Class reference¶

Element classes¶

Fundamental element classes¶

ElementBase class¶

Sequence class¶

Alternative class¶

Optional class¶

Repetition class¶

Literal class¶

RuleRef class¶

ListRef class¶

DictListRef class¶

Dictation class¶

Compound class¶

Choice class¶

Navigation

Table Of Contents

Previous topic

Next topic

This Page

Quick search

Grammar sub-package¶

Grammar classes¶

Grammar class¶

ConnectionGrammar class¶

Rule classes¶

Rule class¶

CompoundRule class¶

Example usage¶

Class reference¶

MappingRule class¶

Example usage¶

Class reference¶

Element classes¶

Fundamental element classes¶

ElementBase class¶

Sequence class¶

Alternative class¶

Optional class¶

Repetition class¶

Literal class¶

RuleRef class¶

ListRef class¶

DictListRef class¶

Dictation class¶

Compound class¶

Choice class¶

Navigation