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

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.
_copy_sequence(sequence, name, item_types=None)[source]

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.

_get_children()[source]

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.

children

Iterable of child elements. (Read-only)

decode(state)[source]

Attempt to decode the recognition stored in the given state.

dependencies(memo)[source]

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.

element_tree_string()[source]

Returns a formatted multi-line string representing this element and its children.

gstring()[source]

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.

value(node)[source]

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()).

Sequence class

class Sequence(children=(), name=None, default=None)[source]

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

_get_children()[source]

Returns the child elements contained within the sequence.

children

Iterable of child elements. (Read-only)

value(node)[source]

The value of a Sequence is a list containing the values of each of its children.

Alternative class

class Alternative(children=(), name=None, default=None)[source]

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.

_get_children()[source]

Returns the alternative child elements.

children

Iterable of child elements. (Read-only)

value(node)[source]

The value of an Alternative is the value of its child that matched the recognition.

Optional class

class Optional(child, name=None, default=None)[source]

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.

_get_children()[source]

Returns the optional child element.

children

Iterable of child elements. (Read-only)

value(node)[source]

The value of a Optional is the value of its child, if the child did match the recognition. Otherwise the value is None.

Repetition class

class Repetition(child, min=1, max=None, name=None, default=None)[source]

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.

children

Iterable of child elements. (Read-only)

get_repetitions(node)[source]

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

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.

Literal class

class Literal(text, name=None, value=None, default=None)[source]
children

Iterable of child elements. (Read-only)

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.

RuleRef class

class RuleRef(rule, name=None, default=None)[source]
children

Iterable of child elements. (Read-only)

ListRef class

class ListRef(name, list, key=None, default=None)[source]
children

Iterable of child elements. (Read-only)

DictListRef class

class DictListRef(name, dict, key=None, default=None)[source]
children

Iterable of child elements. (Read-only)

Dictation class

class Dictation(name=None, format=True, default=None)[source]
children

Iterable of child elements. (Read-only)

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.

Compound class

class Compound(spec, extras=None, actions=None, name=None, value=None, value_func=None, elements=None, default=None)[source]

Choice class

class Choice(name, choices, extras=None, default=None)[source]