Operations Summary: | |
void | addImport(in RuleName importName) |
void | deleteRule(in string ruleName) raises |
Rule | getRule(in string s) |
Rule | getRuleInternal(in string ruleName) |
boolean | isEnabledWithRuleName(in string ruleName) raises |
boolean | isRulePublic(in string ruleName) raises |
RuleNameArray | listImports() |
StringArray | listRuleNames() |
RuleParse | parse(in string text, in string ruleName) raises |
RuleParse | parseNthBest(in FinalRuleResult finalRuleResult, in long nBest, in string ruleName) raises |
RuleParse | parseTokenSequence(in StringArray tokens, in string ruleName) raises |
void | removeImport(in RuleName importName) raises |
RuleName | resolve(in RuleName ruleName) raises |
Rule | ruleForGrammar(in string grammarText) raises |
void | setEnabledForRule(in string ruleName, in boolean enabled) raises |
void | setEnabledForRuleArray(in StringArray ruleNames, in boolean enabled) raises |
void | setRule(in string ruleName, in Rule rule, in boolean isPublic) raises |
string | toString() |
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: |
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.
listImports
removeImport
Recognizer#commitChanges
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.
Recognizer#commitChanges
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.
rulename
to be returned. ruleName
or null.setRule
getRuleInternal
Recognizer#commitChanges
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.
rulename
to be returned. setRule
getRule
Recognizer#commitChanges
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.
ruleName
is enabled, otherwise false.
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.
ruleName
is public.
Return a list of the current imports.
Returns zero length array if no RuleGrammars
are
imported.
addImport
removeImport
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.
RuleGrammar
.
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.
parseTokenSequence
parseNthBest
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.
FinalRuleResult
to parse.parse
parseTokenSequence
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.
parse
parseNthBest
Remove an import. The name follows the format of
addImport
.
The change in imports only takes effect when grammar changes are committed.
addImport
Recognizer#commitChanges
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.
Convert a string in partial grammar format to a Rule
object. The string can be any legal expansion from the supported
grammar language.
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.
ruleName
, false to disable. setEnabled
setEnabledForRuleArray
Recognizer#commitChanges
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.
Recognizer#commitChanges
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
orRuleTag
.
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).
RuleGrammar
).RuleGrammars
or enabled. ruleForGrammar
getRule
getRuleInternal
Recognizer#commitChanges
RuleAlternatives
RuleCount
RuleName
RuleSequence
RuleTag
RuleToken
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:
RuleGrammar
in the supported grammar format.