grammars — Grammar classes module

This module contains classes for compiling, importing from and matching JSpeech Grammar Format grammars.

Classes

class jsgf.grammars.Import(name)

Import objects used in grammar compilation and import resolution.

Import names must be fully qualified. This means they must be in the reverse domain name format that Java packages use. Wildcards may be used to import all public rules in a grammar.

The following are valid rule import names:

  • com.example.grammar.rule_name
  • grammar.rule_name
  • com.example.grammar.*
  • grammar.*

There are two reserved rule names: NULL and VOID. These reserved names cannot be used as import names. You can however change the case to ‘null’ or ‘void’ to use them, as names are case-sensitive.

grammar_name

The full name of the grammar to import from.

Returns:grammar name
Return type:str
resolve(memo=None, file_exts=None)

Resolve this import statement and return the imported Rule object(s).

This method attempts to parse grammar files in the working directory and its sub-directories. If a dictionary was passed for the memo argument, then that dictionary will be updated with the parsed grammar and rules.

Errors will be raised if the grammar could not be found and parsed, or if the import statement could not be resolved.

Parameters:
  • memo (dict) – dictionary of import names to grammar rules
  • file_exts (list | tuple) – list of grammar file extensions to check against (default: (".jsgf", ".jgram"))
Returns:

imported Rule or list of Rules

Return type:

Rule | list

Raises:

GrammarError | JSGFImportError

rule_name

The name of the rule to import from the grammar.

Returns:rule name
Return type:str
wildcard_import

Whether this import statement imports every grammar rule.

Returns:bool
Return type:bool
class jsgf.grammars.Grammar(name='default', case_sensitive=False)

Base class for JSGF grammars.

Grammar names can be either a qualified name with dots or a single name. A name is defined as a single word containing one or more alphanumeric Unicode characters and/or any of the following special characters: +-:;,=|/()[]@#%!^&~$

For example, the following are valid grammar names: com.example.grammar grammar

There are two reserved rule names: NULL and VOID. These reserved names cannot be used as grammar names. You can however change the case to ‘null’ or ‘void’ to use them, as names are case-sensitive.

add_import(_import)

Add an import statement to the grammar.

Parameters:_import – Import
add_imports(*imports)

Add multiple imports to the grammar.

Parameters:imports – imports
add_rule(rule)

Add a rule to the grammar.

This method will override the new rule’s case_sensitive value with the grammar’s case_sensitive value.

Parameters:rule – Rule
Raises:GrammarError
add_rules(*rules)

Add multiple rules to the grammar.

This method will override each new rule’s case_sensitive value with the grammar’s case_sensitive value.

Parameters:rules – rules
Raises:GrammarError
case_sensitive

Case sensitivity used when matching and compiling Literal rule expansions.

Setting this property will override the case_sensitive values for each Rule and Literal expansion in the grammar or in any newly added grammar rules.

Return type:bool
Returns:case sensitivity
compile()

Compile this grammar’s header, imports and rules into a string that can be recognised by a JSGF parser.

Returns:str
compile_as_root_grammar()

Compile this grammar with one public “root” rule containing rule references in an alternative set to every other rule as such:

public <root> = (<rule1>|<rule2>|..|<ruleN>);
<rule1> = ...;
<rule2> = ...;
.
.
.
<ruleN> = ...;

This is useful if you are using JSGF grammars with CMU Pocket Sphinx.

Returns:str
compile_grammar(charset_name='UTF-8', language_name='en', jsgf_version='1.0')

Compile this grammar’s header, imports and rules into a string that can be recognised by a JSGF parser.

This method is deprecated, use compile instead.

Parameters:
  • charset_name
  • language_name
  • jsgf_version
Returns:

str

compile_to_file(file_path, compile_as_root_grammar=False)

Compile this grammar by calling compile and write the result to the specified file.

Parameters:
  • file_path – str
  • compile_as_root_grammar – bool
disable_rule(rule)

Disable a rule in this grammar, preventing it from appearing in the compile method output or being matched with the find_matching_rules method.

Parameters:rule – Rule object or the name of a rule in this grammar
Raises:GrammarError
enable_rule(rule)

Enable a rule in this grammar, allowing it to appear in the compile method output and to be matched with the find_matching_rules method.

Rules are enabled by default.

Parameters:rule – Rule object or the name of a rule in this grammar
Raises:GrammarError
find_matching_rules(speech)

Find each visible rule in this grammar that matches the speech string.

Parameters:speech – str
Returns:list
find_tagged_rules(tag, include_hidden=False)

Find each rule in this grammar that has the specified JSGF tag.

Parameters:
  • tag – str
  • include_hidden – whether to include hidden rules (default False).
Returns:

list

get_rule(name)

Get a rule object with the specified name if one exists in the grammar or its imported rules.

If name is a fully-qualified rule name, then this method will attempt to import it.

Parameters:name – str
Returns:Rule
Raises:GrammarError | TypeError | JSGFImportError
get_rule_from_name(name)

Get a rule object with the specified name if one exists in the grammar or its imported rules.

If name is a fully-qualified rule name, then this method will attempt to import it.

Parameters:name – str
Returns:Rule
Raises:GrammarError | TypeError | JSGFImportError
get_rules(*names)

Get rule objects with the specified names, if they exist in the grammar.

Parameters:names – str
Returns:list
Raises:GrammarError
get_rules_from_names(*names)

Get rule objects with the specified names, if they exist in the grammar.

Parameters:names – str
Returns:list
Raises:GrammarError
import_environment

A dictionary of imported rules and their grammars that functions as the import environment of this grammar.

The import environment dictionary is updated internally by the resolve_imports() method.

Return type:dict
Returns:dictionary of import names to grammar rules
import_names

The import names associated with this grammar.

Returns:list
imports

Get the imports for this grammar.

Returns:list
jsgf_header

The JSGF header string for this grammar. By default this is:

#JSGF V1.0;
Returns:str
match_rules

The rules that the find_matching_rules method will match against.

Returns:list
remove_import(_import)

Remove an Import from the grammar.

Parameters:_import – Import
remove_imports(*imports)

Remove multiple imports from the grammar.

Parameters:imports – imports
remove_rule(rule, ignore_dependent=False)

Remove a rule from this grammar.

Parameters:
  • rule – Rule object or the name of a rule in this grammar
  • ignore_dependent – whether to check if the rule has dependent rules
Raises:

GrammarError

resolve_imports(memo=None, file_exts=None)

Resolve each import statement in the grammar and make the imported Rule object(s) available for referencing and matching.

This method attempts to parse grammar files in the working directory and its sub-directories. If a dictionary was passed for the memo argument, then that dictionary will be updated with the parsed grammars and rules.

Errors will be raised if a grammar could not be found and parsed, or if an import statement could not be resolved.

Parameters:
  • memo (dict) – dictionary of import names to grammar rules
  • file_exts (list | tuple) – list of grammar file extensions to check against (default: (".jsgf", ".jgram"))
Returns:

dictionary of import names to grammar rules

Return type:

dict

Raises:

GrammarError | JSGFImportError

rule_names

The rule names of each rule in this grammar.

Returns:list
rules

Get the rules added to this grammar.

Returns:list
visible_rules

The rules in this grammar which have the visible attribute set to True.

Returns:list
class jsgf.grammars.RootGrammar(rules=None, name='root', case_sensitive=False)

A grammar with one public “root” rule containing rule references in an alternative set to every other rule as such:

public <root> = (<rule1>|<rule2>|..|<ruleN>);
<rule1> = ...;
<rule2> = ...;
.
.
.
<ruleN> = ...;

This is useful if you are using JSGF grammars with CMU Pocket Sphinx.

compile()

Compile this grammar’s header, imports and rules into a string that can be recognised by a JSGF parser.

This method will compile the grammar using compile_as_root_grammar.

Returns:str