A grammar consists of a list of rules.
A rule consists of a list of words and slots. For example: MY_RULE = "My name is $name" where "name" is a slot
Words, Nametags may be added or removed from slots. Upon adding and removing words, the grammar needs to be recompiled for the changes to take place. However, the original CompiledGrammar remains valid even if compilation never takes place.
Two types of slots exist: word slots and nametag slots
Data Structures | |||||||
struct | SR_Grammar | ||||||
Grammar compilation | |||||||
Categories:
IMPORTANT NOTE: There are two main approaches to grammar activation in a recognizer.
SREC supports 1. but not 2. CREC supports 2 but not 1. Both approaches are covered by this interface. Pre-compiled grammars inherently refer to models. It is therefore important to ensure consistency of model usage between all activated grammars. This can be done prior to grammar rule activation in the Recognizer (see SR_RecognizerCheckGrammarConsistency()). A Grammar may consist of one or more rules. Rules are given as expressions (this interface is independent of the format). A rule may contain other rules. Before a rule can be used in recognition it must be compiled (or loaded), setup by a recognizer and activated.
Once a Grammar is setup by a recognizer it is not permissible to modify its rules Thus, in order to be able to support a combination of a static rule and one that requires changing, it is most efficient to separate these rules into two Grammar objects.
NOTE: The modification/setup constraint ensures consistency between the rule definitions in the Grammar and the setup rules. It would be possible to remove this constraint and allow rules that had no dependents to be modified while the grammar was setup. This makes the API freer but also less consistent and more susceptible to error. There would be no footprint cost with having two grammars in place of one grammar with two rules unless the rules overlapped. If there was overlap then it might have been possible to minimize the shared parts | |||||||
SREC_GRAMMAR_API ESR_ReturnCode | SR_GrammarCompile (SR_Grammar *self) | ||||||
Special "Slot"-based Grammar functions | |||||||
Slots are points in a pre-compiled grammar where a simple extension of the grammar may be made. They support the insertion of words or nametags into a pr-defined position in the Grammar. Slots are first declared in an expression which is compiled and saved for re-loading. The names of these slots are used in a similar way as rule names. | |||||||
SREC_GRAMMAR_API ESR_ReturnCode | SR_GrammarAddWordToSlot (SR_Grammar *self, const LCHAR *slot, const LCHAR *word, const LCHAR *pronunciation, int weight, const LCHAR *tag) | ||||||
SREC_GRAMMAR_API ESR_ReturnCode | SR_GrammarResetAllSlots (SR_Grammar *self) | ||||||
SREC_GRAMMAR_API ESR_ReturnCode | SR_GrammarAddNametagToSlot (SR_Grammar *self, const LCHAR *slot, const struct SR_Nametag_t *nametag, int weight, const LCHAR *tag) | ||||||
Grammar Setup functions | |||||||
The Grammar object needs an association with several objects:
| |||||||
SREC_GRAMMAR_API ESR_ReturnCode | SR_GrammarSetupVocabulary (SR_Grammar *self, SR_Vocabulary *vocabulary) | ||||||
SREC_GRAMMAR_API ESR_ReturnCode | SR_GrammarSetupRecognizer (SR_Grammar *self, struct SR_Recognizer_t *recognizer) | ||||||
SREC_GRAMMAR_API ESR_ReturnCode | SR_GrammarUnsetupRecognizer (SR_Grammar *self) | ||||||
Basic Grammar functions | |||||||
Returns AcousticModels associated with a Grammar.
| |||||||
SREC_GRAMMAR_API ESR_ReturnCode | SR_GrammarCreate (SR_Grammar **self) | ||||||
SREC_GRAMMAR_API ESR_ReturnCode | SR_GrammarDestroy (SR_Grammar *self) | ||||||
SREC_GRAMMAR_API ESR_ReturnCode | SR_GrammarLoad (const LCHAR *filename, SR_Grammar **self) | ||||||
SREC_GRAMMAR_API ESR_ReturnCode | SR_GrammarSave (SR_Grammar *self, const LCHAR *filename) | ||||||
SREC_GRAMMAR_API ESR_ReturnCode | SR_GrammarSetDispatchFunction (SR_Grammar *self, const LCHAR *name, void *userData, SR_GrammarDispatchFunction function) | ||||||
SREC_GRAMMAR_API ESR_ReturnCode | SR_GrammarSetParameter (SR_Grammar *self, const LCHAR *key, void *value) | ||||||
SREC_GRAMMAR_API ESR_ReturnCode | SR_GrammarSetSize_tParameter (SR_Grammar *self, const LCHAR *key, size_t value) | ||||||
SREC_GRAMMAR_API ESR_ReturnCode | SR_GrammarGetParameter (SR_Grammar *self, const LCHAR *key, void **value) | ||||||
SREC_GRAMMAR_API ESR_ReturnCode | SR_GrammarGetSize_tParameter (SR_Grammar *self, const LCHAR *key, size_t *value) | ||||||
SREC_GRAMMAR_API ESR_ReturnCode | SR_GrammarCheckParse (SR_Grammar *self, const LCHAR *transcription, SR_SemanticResult **result, size_t *resultCount) | ||||||
Typedefs | |||||||
typedef ESR_ReturnCode(* | SR_GrammarDispatchFunction )(LCHAR *functionName, LCHAR **argv, size_t argc, void *value, LCHAR *result, size_t *resultSize) |
typedef ESR_ReturnCode(* SR_GrammarDispatchFunction)(LCHAR *functionName, LCHAR **argv, size_t argc, void *value, LCHAR *result, size_t *resultSize) |
Grammar dispatch function. Used for symantic processing.
functionName | Name of function that was invoked | |
argv | Argument values passed to function | |
argc | Number of arguments passed to function | |
value | Dispatch value (specified using SR_GrammarSetDispatchValue) | |
result | Result of function operation. Caller passes in this buffer, function fills it. | |
resultSize | Size of result buffer. If the passed in buffer was not large enough to hold the result, this value is updated with the required length. |
SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarAddNametagToSlot | ( | SR_Grammar * | self, | |
const LCHAR * | slot, | |||
const struct SR_Nametag_t * | nametag, | |||
int | weight, | |||
const LCHAR * | tag | |||
) |
Adds word to rule slot.
self | SR_Grammar handle | |
slot | Slot name | |
nametag | Nametag to be added to the slot | |
weight | value to associate with nametag when adding to grammar; use to determine cost when parsing | |
tag | eScript semantic expression (tag) for the nametag |
SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarAddWordToSlot | ( | SR_Grammar * | self, | |
const LCHAR * | slot, | |||
const LCHAR * | word, | |||
const LCHAR * | pronunciation, | |||
int | weight, | |||
const LCHAR * | tag | |||
) |
Adds word to rule slot.
self | SR_Grammar handle | |
slot | Slot name | |
word | Word to be added to the slot | |
pronunciation | Word pronunciation (optional). Pass NULL to omit. | |
weight | value to associate with word when adding to grammar; use to determine cost when parsing | |
tag | eScript semantic expression for the word. In other words, eScript will execute "MEANING=<tag>" |
SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarCheckParse | ( | SR_Grammar * | self, | |
const LCHAR * | transcription, | |||
SR_SemanticResult ** | result, | |||
size_t * | resultCount | |||
) |
Checks if transcription is parsable by the grammar.
self | SR_Grammar handle | |
transcription | transcription to be checked | |
result | should be NULL | |
resultCount | used to return the number of valid parses |
SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarCompile | ( | SR_Grammar * | self | ) |
Compiles the grammar. In the case of a precompiled grammar, the function compiles those portions of the grammar that were dynamically added since the last compilation.
self | SR_Grammar handle |
SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarCreate | ( | SR_Grammar ** | self | ) |
SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarDestroy | ( | SR_Grammar * | self | ) |
Destroys a grammar.
self | SR_Grammar handle |
SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarGetParameter | ( | SR_Grammar * | self, | |
const LCHAR * | key, | |||
void ** | value | |||
) |
Returns grammar parameter value.
self | SR_Grammar handle | |
key | Parameter name | |
value | Parameter value |
SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarGetSize_tParameter | ( | SR_Grammar * | self, | |
const LCHAR * | key, | |||
size_t * | value | |||
) |
Return copy of unsigned int grammar parameter. This is a convenience function.
self | SR_Grammar handle | |
key | Parameter name | |
value | [out] Used to hold the parameter value |
SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarLoad | ( | const LCHAR * | filename, | |
SR_Grammar ** | self | |||
) |
Loads a compiled grammar from a file or an image. If the filename has extention .g2g then it will be loaded as an image. Otherwise, provide only a basename (i.e. without file extensions), and a set of text-based grammar files will be loaded.
filename | File to read grammar from | |
self | SR_Grammar handle |
SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarResetAllSlots | ( | SR_Grammar * | self | ) |
Removes all elements from all slots.
self | SR_Grammar handle |
SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarSave | ( | SR_Grammar * | self, | |
const LCHAR * | filename | |||
) |
Saves a compiled grammar to a file.
self | SR_Grammar handle | |
filename | File to write grammar into |
SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarSetDispatchFunction | ( | SR_Grammar * | self, | |
const LCHAR * | name, | |||
void * | userData, | |||
SR_GrammarDispatchFunction | function | |||
) |
Sets user dispatch function (used for parsed callback, etc)
self | SR_Grammar handle | |
name | The name of the function which will trigger this callback when encountered during grammar parsing. | |
userData | The user data to be referenced in the callback implementation later on. | |
function | The dispatch function |
SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarSetParameter | ( | SR_Grammar * | self, | |
const LCHAR * | key, | |||
void * | value | |||
) |
Sets grammar parameter, overriding session defaults.
self | SR_Grammar handle | |
key | Parameter name | |
value | Parameter value |
SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarSetSize_tParameter | ( | SR_Grammar * | self, | |
const LCHAR * | key, | |||
size_t | value | |||
) |
Sets grammar parameters. This is a convenience function.
self | SR_Grammar handle | |
key | Parameter name | |
value | Parameter value |
SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarSetupRecognizer | ( | SR_Grammar * | self, | |
struct SR_Recognizer_t * | recognizer | |||
) |
Associates Grammar with a Recognizer (eg. such that word additions can take place).
self | SR_Grammar handle | |
models | The recognizer to associate |
SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarSetupVocabulary | ( | SR_Grammar * | self, | |
SR_Vocabulary * | vocabulary | |||
) |
Configures a vocabulary with the grammar.
self | SR_Grammar handle | |
vocabulary | The vocabulary to associate with |
SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarUnsetupRecognizer | ( | SR_Grammar * | self | ) |
Dissociate Grammar from a Recognizer.
self | SR_Grammar handle |