Rules

This section describes the following classes:

Rule class

class Rule(name=None, element=None, context=None, imported=False, exported=False)[source]

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

This rule’s active state. (Read-only)

disable()[source]

Disable this grammar so that it is never active to receive recognitions, regardless of whether its context matches or not.

element

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

enable()[source]

Enable this grammar so that it is active to receive recognitions when its context matches.

enabled

This rule’s enabled state. An enabled rule is active when its context matches, a disabled rule is never active regardless of context. (Read-only)

exported

This rule’s exported status. See Exported rules for more info. (Read-only)

grammar

This rule’s grammar object. (Set once)

imported

This rule’s imported status. See Imported rules for more info. (Read-only)

name

This rule’s name. (Read-only)

process_begin(executable, title, handle)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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.