expansions
— Expansion classes and functions module¶
This module contains classes for compiling and matching JSpeech Grammar Format rule expansions.
Classes¶
-
class
jsgf.expansions.
AlternativeSet
(*expansions)¶ Class for a set of expansions, one of which can be spoken.
-
generate
()¶ Generate a matching string for this alternative set.
Each alternative has an equal chance of being chosen for string generation.
If weights are set, then the probability of an alternative is its weight over the sum of all weights:
p = w / sum(weights)
-
set_weight
(child, weight)¶ Set the weight of a child.
The weight determines how likely it is that an alternative was spoken.
Higher values are more likely, lower values are less likely. A value of 0 means that the alternative will never be matched. Negative weights are not allowed.
Note: weights are compiled as floating-point numbers accurate to 4 decimal places, e.g. 5.0001.
Parameters: - child (Expansion|int|str) – child/list index/compiled child to set the weight for.
- weight (float|int) – weight value - must be >= 0
-
weights
¶ The dictionary of alternatives to their weights.
Return type: dict
-
-
class
jsgf.expansions.
ChildList
(expansion, seq=())¶ List wrapper class for expansion child lists.
The
parent
attribute of each child will be set appropriately when they added or removed from lists.-
clear
()¶ Remove all expansions from this list and unset their parent attributes.
-
orphan_children
()¶ Set each child’s parent to None.
-
-
class
jsgf.expansions.
Expansion
(children)¶ Expansion base class.
-
_make_matcher_element
()¶ Method used by the matcher_element property to create ParserElements.
Subclasses should implement this method for speech matching functionality.
-
children
¶ List of children.
Returns: ChildList
-
collect_leaves
(order=0, shallow=False)¶ Collect all descendants of an expansion that have no children. This can include self if it has no children. RuleRefs are also counted as leaves.
Parameters: - order – tree traversal order (default 0: pre-order)
- shallow – whether to not collect leaves from trees of referenced rules
Returns: list
-
compiled_tag
¶ Get the compiled tag for this expansion if it has one. The empty string is returned if there is no tag set.
Returns: str
-
copy
(shallow=False)¶ Make a copy of this expansion. This returns a deep copy by default. Neither referenced rules or their expansions will be deep copied.
Parameters: shallow – whether to create a shallow copy (default: False) Returns: Expansion
-
current_match
¶ Currently matched speech value for this expansion.
If the expansion hasn’t been matched, this will be None (if required) or ‘’ (if optional).
Returns: str | None
-
generate
()¶ Generate a string matching this expansion.
-
had_match
¶ Whether this expansion has a
current_match
value that is not ‘’ or None. This will also check if this expansion was part of a complete repetition if it has a Repeat or KleeneStar ancestor.Returns: bool
-
invalidate_calculations
()¶ Invalidate calculations stored in the lookup tables that involve this expansion. This only effects
mutually_exclusive_of
andis_descendant_of
, neither of which are used in compiling or matching rules.This should be called if a child is added to an expansion or if an expansion’s parent is changed outside of what
JointTreeContext
does.Some changes may also require invalidating descendants, the
map_expansion
function can be used with this method to accomplish that:map_expansion(self, Expansion.invalidate_calculations)
-
invalidate_matcher
()¶ Method to invalidate the parser element used for matching this expansion. This is method is called automatically when a parent is set or a ChildList is modified. The parser element will be recreated again when required.
This only needs to be called manually if modifying an expansion tree after matching with a Dictation expansion.
-
is_alternative
¶ Whether or not this expansion has an AlternativeSet ancestor with more than one child.
Returns: bool
-
is_descendant_of
(other)¶ Whether this expansion is a descendant of another expansion.
Parameters: other – Expansion Returns: bool
-
is_optional
¶ Whether or not this expansion has an optional ancestor.
Returns: bool
-
leaves
¶ Collect all descendants of an expansion that have no children. This can include self if it has no children. RuleRefs are also counted as leaves.
Parameters: - order – tree traversal order (default 0: pre-order)
- shallow – whether to not collect leaves from trees of referenced rules
Returns: list
-
leaves_after
¶ Generator function for leaves after this one (if any).
Returns: generator
-
static
make_expansion
(e)¶ Take an object, turn it into an Expansion if it isn’t one and return it.
Parameters: e – str | Expansion Returns: Expansion
-
matchable_leaves_after
¶ Generator function yielding all leaves after self that are not mutually exclusive of it.
Returns: generator
-
matcher_element
¶ Lazily initialised pyparsing
ParserElement
used to match speech to expansions. It will also setcurrent_match
values.Returns: pyparsing.ParserElement
-
matches
(speech)¶ Match speech with this expansion, set
current_match
to the first matched substring and return the remainder of the string.Matching ambiguous rule expansions is not supported because it not worth the performance hit. Ambiguous rule expansions are defined as some optional literal x followed by a required literal x. For example, successfully matching
'test'
for the following rule is not supported:<rule> = [test] test;
Parameters: speech – str Returns: str
-
matching_slice
¶ Slice of the last speech string matched. This will be
None
initially.Return type: slice
-
mutually_exclusive_of
(other)¶ Whether this expansion cannot be spoken with another expansion.
Parameters: other – Expansion Returns: bool
-
parent
¶ This expansion’s parent, if it has one.
Setting the parent will call
Expansion.invalidate_matcher
as necessary on the new and old parents.Returns: Expansion | None
-
repetition_ancestor
¶ This expansion’s closest Repeat or KleeneStar ancestor, if it has one.
Returns: Expansion
-
reset_for_new_match
()¶ Call
reset_match_data
for this expansion and all of its descendants.
-
reset_match_data
()¶ Reset any members or properties this expansion uses for matching speech, i.e.
current_match
values.This does not invalidate
matcher_element
.
-
root_expansion
¶ Traverse to the root expansion r and return it.
Returns: Expansion
-
tag
¶ JSGF tag for this expansion.
Set to
None
for no tag and the empty string for no tag text.Returns: str
-
validate_compilable
()¶ Check that the expansion is compilable. If it isn’t, this method should raise a
CompilationError
.Raises: CompilationError
-
-
class
jsgf.expansions.
JointTreeContext
(root_expansion)¶ Class that temporarily joins an expansion tree with the expansion trees of all referenced rules by setting the parent relationships.
This is useful when it is necessary to view an expansion tree and the expansion trees of referenced rules as one larger tree. E.g. when determining mutual exclusivity of two expansions, if an expansion is optional or used for repetition in the context of other trees, etc.
Note: this class will reduce the matching performance if used, but will only be noticeable with larger grammars.
On
__exit__
, the trees will be detached recursively.This class can be used with Python’s
with
statement.-
static
detach_tree
(x)¶ If x is a NamedRuleRef, detach its referenced rule’s expansion from this tree.
Parameters: x – Expansion
-
static
join_tree
(x)¶ If x is a NamedRuleRef, join its referenced rule’s expansion to this tree.
Parameters: x – Expansion
-
static
-
class
jsgf.expansions.
KleeneStar
(expansion)¶ JSGF Kleene star operator for allowing zero or more repeats of an expansion.
For example:
<kleene> = (please)* don't crash;
-
generate
()¶ Generate a string matching this expansion.
This method can generate zero or more repetitions of the child expansion, zero repetitions meaning the empty string (“”) will be returned.
Return type: str
-
-
class
jsgf.expansions.
Literal
(text, case_sensitive=False)¶ Expansion class for literals.
-
case_sensitive
¶ Case sensitivity used when matching and compiling
Literal
rule expansions.This property can be
True
orFalse
. Matching and compilation will be case-sensitive ifTrue
and case-insensitive ifFalse
. The default value isFalse
.Return type: bool Returns: literal case sensitivity
-
generate
()¶ Generate a string matching this expansion’s text.
This will just return the value of
text
.Return type: str
-
matching_regex_pattern
¶ A regex pattern for matching this expansion.
This property has been left in for backwards compatibility. The
Expansion.matches
method now uses thematcher_element
property instead.Returns: regex pattern object
-
text
¶ Text to match/compile.
This will return lowercase text if
case_sensitive
is notTrue
.Return type: str Returns: text
-
validate_compilable
()¶ Check that the expansion is compilable. If it isn’t, this method should raise a
CompilationError
.Raises: CompilationError
-
-
class
jsgf.expansions.
NamedRuleRef
(name)¶ Class used to reference rules by name.
-
generate
()¶ Generate a string matching the referenced rule’s expansion.
Return type: str
-
referenced_rule
¶ Find and return the rule this expansion references in the grammar.
This raises an error if the referenced rule cannot be found using
self.rule.grammar
or if there is no link to a grammar.Raises: GrammarError Returns: Rule
-
-
class
jsgf.expansions.
NullRef
¶ Reference expansion for the special NULL rule.
The NULL rule always matches speech. If this reference is used by a rule, that part of the rule expansion requires no speech substring to match.
-
class
jsgf.expansions.
OptionalGrouping
(expansion)¶ Class for expansions that can be optionally spoken in a rule.
-
generate
()¶ Generate a string matching this expansion.
-
-
class
jsgf.expansions.
Repeat
(expansion)¶ JSGF plus operator for allowing one or more repeats of an expansion.
For example:
<repeat> = (please)+ don't crash;
-
generate
()¶ Generate a string matching this expansion.
This method can generate one or more repetitions of the child expansion.
Return type: str
-
get_expansion_matches
(e)¶ Get a list of an expansion’s
current_match
values for each repetition.Returns: list
-
get_expansion_slices
(e)¶ Get a list of an expansion’s
matching_slice
values for each repetition.Returns: list
-
repetitions_matched
¶ The number of repetitions last matched.
Returns: int
-
reset_match_data
()¶ Reset any members or properties this expansion uses for matching speech, i.e.
current_match
values.This does not invalidate
matcher_element
.
-
-
class
jsgf.expansions.
RequiredGrouping
(*expansions)¶ Subclass of
Sequence
for wrapping multiple expansions in parenthesises.
-
class
jsgf.expansions.
RuleRef
(referenced_rule)¶ Subclass of
NamedRuleRef
for referencing another rule with a Rule object.Parameters: referenced_rule –
-
class
jsgf.expansions.
Sequence
(*expansions)¶ Class for expansions to be spoken in sequence.
-
class
jsgf.expansions.
VoidRef
¶ Reference expansion for the special VOID rule.
The VOID rule can never be spoken. If this reference is used by a rule, then it will not match unless the reference it is optional.
Functions¶
-
jsgf.expansions.
filter_expansion
(e, func=<function <lambda>>, order=0, shallow=False)¶ Find all expansions in an expansion tree for which func(x) == True.
Parameters: - e – Expansion
- func – callable (default: the identity function, f(x)->x)
- order – int
- shallow – whether to not process trees of referenced rules (default False)
Returns: list
-
jsgf.expansions.
find_expansion
(e, func=<function <lambda>>, order=0, shallow=False)¶ Find the first expansion in an expansion tree for which func(x) is True and return it. Otherwise return None.
This function will stop searching once a matching expansion is found, unlike the other top-level functions in this module.
Parameters: - e – Expansion
- func – callable (default: the identity function, f(x)->x)
- order – int
- shallow – whether to not process trees of referenced rules (default False)
Returns: Expansion | None
-
jsgf.expansions.
flat_map_expansion
(e, func=<function <lambda>>, order=0, shallow=False)¶ Call map_expansion with the arguments and return a single flat list.
Parameters: - e – Expansion
- func – callable (default: the identity function, f(x)->x)
- order – int
- shallow – whether to not process trees of referenced rules (default False)
Returns: list
-
jsgf.expansions.
map_expansion
(e, func=<function <lambda>>, order=0, shallow=False)¶ Traverse an expansion tree and call func on each expansion returning a tuple structure with the results.
Parameters: - e – Expansion
- func – callable (default: the identity function, f(x)->x)
- order – int
- shallow – whether to not process trees of referenced rules (default False)
Returns: tuple
-
jsgf.expansions.
matches_overlap
(m1, m2)¶ Check whether two regex matches overlap.
Returns: bool
-
jsgf.expansions.
restore_current_matches
(e, values, override_none=True)¶ Traverse an expansion tree and restore matched data using the values dictionary.
Parameters: - e – Expansion
- values – dict
- override_none – bool
-
jsgf.expansions.
save_current_matches
(e)¶ Traverse an expansion tree and return a dictionary populated with each descendant
Expansion
and its match data.This will also include
e
.Parameters: e – Expansion Returns: dict