Modules | Files | Inheritance Tree | Inheritance Graph | Name Index
module GNOME::Speech::Recognition
interface RuleGrammar
Files: GNOME_Speech.idl
GNOME-Speech-Recognition-RuleGrammar-inheritance GNOME-Speech-Recognition-Grammar.html GNOME-Speech-SpeechObject.html Bonobo-Unknown.html
Operations Summary:
 voidaddImport(in RuleName importName)
 voiddeleteRule(in string ruleName) raises
 RulegetRule(in string s)
 RulegetRuleInternal(in string ruleName)
 booleanisEnabledWithRuleName(in string ruleName) raises
 booleanisRulePublic(in string ruleName) raises
RuleNameArraylistImports()
StringArraylistRuleNames()
RuleParseparse(in string text, in string ruleName) raises
RuleParseparseNthBest(in FinalRuleResult finalRuleResult, in long nBest, in string ruleName) raises
RuleParseparseTokenSequence(in StringArray tokens, in string ruleName) raises
 voidremoveImport(in RuleName importName) raises
RuleNameresolve(in RuleName ruleName) raises
 RuleruleForGrammar(in string grammarText) raises
 voidsetEnabledForRule(in string ruleName, in boolean enabled) raises
 voidsetEnabledForRuleArray(in StringArray ruleNames, in boolean enabled) raises
 voidsetRule(in string ruleName, in Rule rule, in boolean isPublic) raises
 stringtoString()

Operations Inherited from Grammar
addGrammarListener, removeGrammarListener, addResultListener, removeResultListener, getActivationMode, getName, getRecognizer, isActive, isEnabled, setActivationMode, setEnabled

Operations Inherited from Bonobo::Unknown
ref, unref, queryInterface

Operation Details:
 void addImport(in RuleName importName)

Import all rules or a specified rule from another grammar. The RuleName should be in one these forms:

<package.grammar.ruleName>
<package.grammar.*>
<grammar.ruleName> 
<grammar.*>

which are equivalent to the following declarations in the Java Speech Grammar Format.

// import all public rules of a grammar
import <package.grammar.*>
import <grammar.*>

// import a specific public rule name of a grammar import <package.grammar.ruleName> import <grammar.ruleName>

The forms without a package are only legal when the full grammar name does not include a package name.

The addImport takes effect when grammar changes are committed. When changes are committed, all imports must be resolvable. Specifically, every RuleGrammar listed in an import must exist, and every fully qualified rulename listed in an import must exist. If any ommissions are found, the commitChanges method throws an exception and the changes do not take effect.

It is not an exception to import a rule or set of rules and not reference them.

Parameters:
importName - the name of the rule to import.
See Also:
listImports
removeImport
Recognizer#commitChanges


 void deleteRule(in string ruleName) raises (IllegalArgumentException)

Delete a rule from the grammar. The deletion only takes effect when grammar changes are next committed.

If the rule name contains both start/end angle brackets (e.g. "<ruleName>"), then the brackets are ignored.

Parameters:
ruleName - name of the defined rule to be deleted.
See Also:
Recognizer#commitChanges


 Rule getRule(in string s)

Returns a Rule object for a specified rulename. Returns null if the rule is unknown. The returned object is a copy of the recognizer's internal object so it can be modified in any way without affecting the recognizer. The setRule method should be called when a change to the returned rule object needs to be applied to the recognizer.

The Rule.toString method can be used to convert the return object to a printable string in Java Speech Grammar Format.

If there is a rule structure currently pending for a commitChanges that structure is returned. Otherwise, the current structure being used by the recognizer on incoming speech is returned.

If the rule name contains both start/end angle brackets (e.g. "<ruleName>"), then the brackets are ignored.

If fast, read-only access to the rule object is required (e.g. in parsing), then the application may use getRuleInternal.

Parameters:
ruleName - the rulename to be returned.
Return:
the definition of ruleName or null.
See Also:
setRule
getRuleInternal
Recognizer#commitChanges


 Rule getRuleInternal(in string ruleName)

Returns a reference to a recognizer's internal rule object identified by a rule name. The application should never modify the returned object. This method is intented for use by parsers and other software that needs to quickly analyse a recognizer's grammars without modifying them (without the overhead of making copies, as required by getRule). If the returned object is ever modified in any way, getRule and setRule should be used.

Returns null if the rule is unknown.

If there is a Rule structure currently pending for a commitChanges that structure is returned. Otherwise, the current structure being used by the recognizer on incoming speech is returned.

If the rule name contains both start/end angle brackets (e.g. "<ruleName>"), then the brackets are ignored.

Parameters:
ruleName - the rulename to be returned.
See Also:
setRule
getRule
Recognizer#commitChanges


 boolean isEnabledWithRuleName(in string ruleName) raises (IllegalArgumentException)

Test whether recognition of a specified rule of this RuleGrammar is enabled. If ruleName is null, the method is equivalent to isEnabled.

If the rule name contains both start/end angle brackets (e.g. "<ruleName>"), then the brackets are ignored.

Parameters:
ruleName - the name of the rule being tested.
Return:
true if ruleName is enabled, otherwise false.


 boolean isRulePublic(in string ruleName) raises (IllegalArgumentException)

Test whether a rule is public. Public rules may be enabled to be activated for recognition and/or may be imported into other RuleGrammars.

If the rule name contains both start/end angle brackets (e.g. "<ruleName>"), then the brackets are ignored.

Parameters:
ruleName - the name of the rule being tested.
Return:
true if ruleName is public.


RuleNameArray listImports()

Return a list of the current imports. Returns zero length array if no RuleGrammars are imported.

Return:
a list of the current imports
See Also:
addImport
removeImport


StringArray listRuleNames()

List the names of all rules defined in this RuleGrammar. If any rules are pending deletion they are not listed (between a call to deleteRule and a commitChanges taking effect).

The returned names do not include the <> symbols.

Return:
the names of all rules defined in this RuleGrammar.


RuleParse parse(in string text, in string ruleName) raises (GrammarException)

Parse a string against a RuleGrammar. Parsing is the process of matching the text against the rules that are defined in the grammar. The text is tokenized as a Java Speech Grammar Format string (white-spacing and quotes are significant).

The string is parsed against the rule identified by ruleName, which may identify any defined rule of this rule grammar (public or private, enabled or disabled). If the ruleName is null, the string is parsed against all enabled rules of the grammar.

The method returns a RuleParse object. The documentation RuleParse describes how the parse structure and grammar structure correspond.

If parse fails, then the return value is null. To succeed, the parse must match the complete input string.

For some grammars and strings, multiple parses are legal. The parse method returns only one. It is not defined which of the legal parses should be returned. Development tools will help to analyse grammars for such ambiguities. Also grammar libraries can be used to parse results to check for these ambiguities.

Parameters:
text - the text string to parse.
ruleName - the rule to parse against, or null.
See Also:
parseTokenSequence
parseNthBest


RuleParse parseNthBest(in FinalRuleResult finalRuleResult, in long nBest, in string ruleName) raises (GrammarException)

Parse the nth best result of a FinalRuleResult against a RuleGrammar. In other respects this parse method is equivalent to the parse method described above.

A rejected result (REJECTED state) is not guaranteed to parse. Also, if the RuleGrammar has been modified since the result was issued, parsing is not guaranteed to succeed.

Parameters:
finalRuleResult - the FinalRuleResult to parse.
nBest - the nth best value.
ruleName - the rule to parse against, or null.
See Also:
parse
parseTokenSequence


RuleParse parseTokenSequence(in StringArray tokens, in string ruleName) raises (GrammarException)

Parse a sequence of tokens against a RuleGrammar. In all other respects this parse method is equivalent to the parse(String text, String ruleName) method except that the string is pre-tokenized.

Parameters:
tokens - the sequence of tokens to parse.
ruleName - the rule to parse against, or null.
See Also:
parse
parseNthBest


 void removeImport(in RuleName importName) raises (IllegalArgumentException)

Remove an import. The name follows the format of addImport.

The change in imports only takes effect when grammar changes are committed.

Parameters:
importName - the name of the import to remove.
See Also:
addImport
Recognizer#commitChanges


RuleName resolve(in RuleName ruleName) raises (GrammarException)

Resolve a rulename reference within a RuleGrammar to a fully-qualified rulename. The input rulename may be a simple rulename, qualified or fully-qualified. If the rulename cannot be resolved, the method returns null.

If the rulename being resolved is a local reference, the return value is a fully-qualified rulename with its grammar part being the name of this RuleGrammar.

Example: in a grammar that imports the rule <number> from the grammar "com.sun.examples", the following would return the fully-qualified rulename com.sun.examples.number.

gram.resolve(new RuleName("number"));

If the input rulename is a fully-qualified rulename, then the method checks whether that rulename exists (and could therefore be successfully referenced in this RuleGrammar). If the rulename exists, then the return value is the same as the input value, otherwise the method returns null.

Parameters:
ruleName - reference to rulename to be resolved.
Return:
the fully-qualified reference to a rulename.


 Rule ruleForGrammar(in string grammarText) raises (GrammarException)

Convert a string in partial grammar format to a Rule object. The string can be any legal expansion from the supported grammar language.

Parameters:
grammarText - string in partial grammar format.


 void setEnabledForRule(in string ruleName, in boolean enabled) raises (IllegalArgumentException)

Set the enabled property for a specified public rule. This method behaves the same as the setEnabled method except that it affects only a single public rule. The enabled state of other rules is unchanged.

Individual rules of a RuleGrammar may be individually enabled and disabled. Once any rule is enabled, the RuleGrammar is considered to be enabled. If all rules are disabled, then the RuleGrammar is considered disabled.

A change in the enabled property of a Rule or a RuleGrammar only takes effect when grammar changes are next committed.

If the rule name contains both start/end angle brackets (e.g. "<ruleName>"), then the brackets are ignored.

Parameters:
ruleName - name of the rule to be enabled or disabled.
enabled - true to enable ruleName, false to disable.
See Also:
setEnabled
setEnabledForRuleArray
Recognizer#commitChanges


 void setEnabledForRuleArray(in StringArray ruleNames, in boolean enabled) raises (IllegalArgumentException)

Set the enabled property for a set of public rules of a RuleGrammar. This method behaves the same as the setEnabled method except that it only affects a defined single public rule. This call does not affect the enabled state of other public rules of the RuleGrammar.

If any one or more rules are enabled, the RuleGrammar is considered to be enabled. If all rules are disabled, then the RuleGrammar is considered disabled.

A change in the enabled property of Rules or a RuleGrammar only takes effect when grammar changes are next committed.

If any rule name contains both start/end angle brackets (e.g. "<ruleName>"), then the brackets are ignored.

Parameters:
ruleNames - the set of rulenames to be enabled or disabled.
enabled - true to enabled rulenames, false to disable.
See Also:
Recognizer#commitChanges


 void setRule(in string ruleName, in Rule rule, in boolean isPublic) raises (NullPointerException, IllegalArgumentException)

Set a rule in the grammar either by creating a new rule or updating an existing rule. The rule being set is identified by its "ruleName" and defined by the Rule object and its isPublic flag. The setRule method is equivalent to a rule definition in the Java supported markup language.

The change in the RuleGrammar takes effect when grammar changes are committed.

The rule object represents the expansion of a grammar formatted definition (the right hand side). It may be a

RuleToken,
RuleName,
RuleAlternatives,
RuleSequence,
RuleCount or
RuleTag.

Each of these 6 object types is an extension of the Rule object. (The rule object cannot be an instance of RuleParse which is also an extension of Rule.)

A rule is most easily created from Java Speech Grammar Format text using the ruleForGrammar method. e.g.

gram.setRule(ruleName, 
gram.ruleForGrammar("open the <object>"), true);

The isPublic flag defines whether this rule may be enabled and active for recognition and/or imported into other rule grammars. It is equivalent to the public declaration in the supported grammar format language.

If the Rule object contains a fully-qualified reference to a rule of another RuleGrammar, an import is automatically generated for that rule if it is not already imported. A subsequent call to listImports will return that import statement.

If the rule name contains both start/end angle brackets (e.g. "<ruleName>"), then they are automatically stripped.

The Rule object passed to the RuleGrammar is copied before being applied to recognizer. Thus, an application can modify and re-use a rule object without unexpected side-effects. Also, a different object will be returned by the getRule and getRuleInternal methods (although it will contain the same information).

Parameters:
ruleName - unique name of rule being defined (unique for this RuleGrammar).
rule - logical expansion for the rulename.
isPublic - true if this rule can be imported into other RuleGrammars or enabled.
See Also:
ruleForGrammar
getRule
getRuleInternal
Recognizer#commitChanges
RuleAlternatives
RuleCount
RuleName
RuleSequence
RuleTag
RuleToken


 string toString()

Return a string containing a specification for this RuleGrammar in Java Speech Grammar Format. The string includes the grammar name declaration, import statements and all the rule definitions. When sending grammar formatted text to a stream (e.g. a file) the application should prepend the header line with the appropriate character encoding information:

Return:
a string containing a specification for this RuleGrammar in the supported grammar format.