SR_Grammar API functions


Detailed Description

Contains recognition grammar.

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:
  • Initialization
  • Compile from expressions (not supported by SREC) or load pre-compiled grammars
  • Dynamic modification; slots
  • Support functions (isExtant, etc)
  • Use in recognition; activation

IMPORTANT NOTE: There are two main approaches to grammar activation in a recognizer.

  • 1. Load a pre-compiler grammar setup. This is not just the set of expressions but is also an image of the actual model components network that fully describes the recognizer task. This type of Grammar can be extended with single arcs at pre-defined points called slots.

  • 2. Create a network dynamically from a set of regular expressions.

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.

  • The Grammar_CompileRule() step combines all sub-rule expressions into a single underlying member of Grammar.
  • The Recognizer_ActivateRule() step simply raises a flat to make a compiled rule available for recognition.

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:
  • A Grammar object must use one and only one Vocabulary object.
  • A Grammar object may use one and only one Nametags object. (The Nametags object can however be used by more than one Grammar. A Nametags collection object must be used before nametags can be added to Grammar slots.)

See also:
Nametags_Add() and associated functions for Nametags management.


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.

Parameters:
self SR_Grammar handle
models Associated models
Returns:
ESR_INVALID_ARGUMENT if self or models are null


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 Documentation

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.

Parameters:
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.


Function Documentation

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.

Parameters:
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
Returns:
ESR_INVALID_ARGUMENT if self is null; ESR_INVALID_STATE if the grammar is active, if the vocabulary is missing, if OSI logging fails; ESR_OUT_OF_MEMORY if word cannot be added to the grammar (addWords=X is too small); ESR_NOT_SUPPORTED if homonyms are added to the grammar

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.

Parameters:
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>"
Returns:
ESR_INVALID_ARGUMENT if self is null; ESR_INVALID_STATE if the grammar is active, if the vocabulary is missing, if OSI logging fails; ESR_OUT_OF_MEMORY if word cannot be added to the grammar (addWords=X is too small); ESR_NOT_SUPPORTED if homonyms are added to the grammar

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.

Parameters:
self SR_Grammar handle
transcription transcription to be checked
result should be NULL
resultCount used to return the number of valid parses
Returns:
ESR_INVALID_ARGUMENT if self, transcription are null; ESR_INVALID_STATE if an internal error has occured.

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.

Parameters:
self SR_Grammar handle
Returns:
ESR_INVALID_ARGUMENT if self is null; ESR_SUCCESS if compilation succeeded, ESR_FATAL_ERROR otherwise.

SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarCreate ( SR_Grammar **  self  ) 

Create a new grammar.

Parameters:
self SR_Grammar handle

SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarDestroy ( SR_Grammar self  ) 

Destroys a grammar.

Parameters:
self SR_Grammar handle
Returns:
ESR_INVALID_ARGUMENT if self is null, ESR_INVALID_STATE if OSI logging fails

SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarGetParameter ( SR_Grammar self,
const LCHAR key,
void **  value 
)

Returns grammar parameter value.

Parameters:
self SR_Grammar handle
key Parameter name
value Parameter value
Returns:
ESR_NOT_IMPLEMENTED

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.

Parameters:
self SR_Grammar handle
key Parameter name
value [out] Used to hold the parameter value
Returns:
ESR_INVALID_ARGUMENT if self is null; ESR_INVALID_RESULT_TYPE if the property type is not size_t; ESR_NO_MATCH_ERROR if property is not set

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.

Parameters:
filename File to read grammar from
self SR_Grammar handle
Returns:
ESR_INVALID_ARGUMENT if self or the value it points to are null. If the filename load property (i.e. addWords=X) is unknown; ESR_OUT_OF_MEMORY if system is out of memory; ESR_READ_ERROR if grammar file be read

SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarResetAllSlots ( SR_Grammar self  ) 

Removes all elements from all slots.

Parameters:
self SR_Grammar handle
Returns:
ESR_INVALID_ARGUMENT if self is null; ESR_INVALID_STATE if resetting the slots or OSI logging fails

SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarSave ( SR_Grammar self,
const LCHAR filename 
)

Saves a compiled grammar to a file.

Parameters:
self SR_Grammar handle
filename File to write grammar into
Returns:
ESR_INVALID_ARGUMENT if self or filename are null; ESR_INVALID_STATE if could not save the grammar

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)

Parameters:
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
Returns:
ESR_SUCCESS

SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarSetParameter ( SR_Grammar self,
const LCHAR key,
void *  value 
)

Sets grammar parameter, overriding session defaults.

Parameters:
self SR_Grammar handle
key Parameter name
value Parameter value
Returns:
ESR_NOT_IMPLEMENTED

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.

Parameters:
self SR_Grammar handle
key Parameter name
value Parameter value
Returns:
ESR_INVALID_RESULT_TYPE if the property is already set and its type is size_t

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

Parameters:
self SR_Grammar handle
models The recognizer to associate
Returns:
ESR_INVALID_ARGUMENT if self or recognizer are null

SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarSetupVocabulary ( SR_Grammar self,
SR_Vocabulary vocabulary 
)

Configures a vocabulary with the grammar.

Parameters:
self SR_Grammar handle
vocabulary The vocabulary to associate with
Returns:
ESR_INVALID_ARGUMENT if self or vocabulary are null

SREC_GRAMMAR_API ESR_ReturnCode SR_GrammarUnsetupRecognizer ( SR_Grammar self  ) 

Dissociate Grammar from a Recognizer.

Parameters:
self SR_Grammar handle
Returns:
ESR_INVALID_ARGUMENT if self is null


Generated on Thu May 1 15:37:26 2008 for SREC by  doxygen 1.5.3