javax.speech.recognition
Class RuleParse

Object
  RuleComponent
      RuleParse

public class RuleParse
extends RuleComponent

Represents the parse structure of a Result or String against a RuleGrammar. The RuleParse object indicates how the Result or String matches to the Rules of the RuleGrammar and also any Rules referenced by that RuleGrammar.

A RuleParse is obtained using the parse methods of RuleGrammar or FinalRuleResult. The RuleParse structure returned by parse closely matches the structure of the RuleGrammar it is parsed against: if the RuleGrammar contains RuleTag, RuleSequence, RuleToken objects and so on, then the returned RuleParse will contain corresponding objects.

The mapping from RuleComponent objects in a RuleGrammar to RuleComponent objects in a RuleParse follows:

• RuleAlternatives: maps to a RuleAlternatives object containing a RuleComponent object for the entity in the set of alternatives that is matched.
• RuleCount: the RuleComponent within the RuleCount maps to a RuleSequence containing a RuleComponent for each match of the RuleComponent contained by RuleCount. The sequence may contain zero, one or multiple RuleComponent matches depending on the count. The min and max repeats are set to the count.
• RuleReference: maps to a RuleParse indicating how the RuleReference was matched with a parse.
• RuleSequence: maps to a RuleSequence with a matching RuleComponent for each RuleComponent in the original sequence.
• RuleLocale, RuleTag, RuleToken, and RuleSpecial: map to themselves.

The RuleParse object is not used in defining a RuleGrammar so it is never matched.

A RuleParse may represent more than one parse if, for example, more than one RuleAlternatives object matches. In this case, the most likely parse should appear first and an application may decide to choose among parses based on context.

Example

This example shows the resulting parse structure given a RuleGrammar, a RuleReference, and an array of Strings representing tokens.

Consider the following RuleGrammar defined in SRGS:

 <grammar root="command">
     <meta name="id" content="CommandGrammar"/>
     <rule id="command" scope="public">
         <ruleref uri="#action"/>
         <ruleref uri="#object"/>
         <item repeat="0-1">
             <ruleref uri="#polite"/>
         </item>
     </rule>
     <rule id="action">
         <one-of>
             <item>open <tag>OP</tag></item>
             <item>close <tag>CL</tag></item>
         </one-of>
     </rule>
     <rule id="object">
         <item repeat="0-1">
             <ruleref uri="#determiner"/>
         </item>
         <one-of>
             <item>window</item>
             <item>door</item>
         </one-of>
     </rule>
     <rule id="determiner">
         <one-of>
             <item>a</item>
             <item>the</item>
         </one-of>
     </rule>
     <rule id="polite">
         <one-of>
             <item>please</item>
             <item>kindly</item>
         </one-of>
     </rule>
 </grammar>
 

This same grammar may be defined programmatically as follows:

 RuleSequence commandRHS =
     new RuleSequence(new RuleComponent[] {
         new RuleReference("action"),
         new RuleReference("object"),
         new RuleCount(new RuleReference("polite"), 0, 1)});
 RuleAlternatives actionRHS =
     new RuleAlternatives(new RuleComponent[] {
         new RuleSequence(new RuleComponent[] {
             new RuleToken("open"),
             new RuleTag("OP")}),
         new RuleSequence(new RuleComponent[] {
             new RuleToken("close"),
             new RuleTag("CL")})});
 RuleSequence objectRHS =
     new RuleSequence(new RuleComponent[] {
         new RuleCount(new RuleReference("determiner"), 0, 1),
         new RuleAlternatives(new String[] {"window", "door"})});
 RuleAlternatives determinerRHS =
     new RuleAlternatives(new String[] {"a", "the"});
 RuleAlternatives politeRHS =
     new RuleAlternatives(new String[] {"please", "kindly"});
 
 Recognizer r = ...
 RuleGrammar rg = 
     r.getGrammarManager().createRuleGrammar("grammar:CommandGrammar", "command");
 rg.addRules(new Rule[] {
     new Rule("command", commandRHS, Rule.PUBLIC),
     new Rule("action", actionRHS),
     new Rule("object", objectRHS),
     new Rule("determiner", determinerRHS),
     new Rule("polite", politeRHS)});
 

Now we can create a parse for the sentence "close the door please" beginning with the root Rule as follows:

 RuleParse ruleParse =
     rg.parse(new String[] {"close", "the", "door", "please"}, "command");
 

Now the parse will have the same structure as follows:

 RuleParse ruleParse =
   new RuleParse(
     new RuleReference("command"),
     new RuleSequence(new RuleComponent[] {            // Parse for "command"
       new RuleParse(
         new RuleReference("action"),
         new RuleAlternatives(new RuleComponent[] {    // Parse for "action"
           new RuleSequence(new RuleComponent[] {      // The chosen alternative
             new RuleToken("close"),
             new RuleTag("CL")})})),
       new RuleParse(
         new RuleReference("object"),
         new RuleSequence(new RuleComponent[] {        // Parse for "object"
           new RuleCount(                              // RuleComponent argument
             new RuleSequence(new RuleComponent[] {    //   becomes RuleSequence
               new RuleParse(                          // One item per match
                 new RuleReference("determiner"),
                 new RuleAlternatives(new RuleComponent[] { // "determiner" parse
                   new RuleToken("the")}))}),          // RuleToken from String
             1, 1),                                    // 1 and only 1
           new RuleAlternatives(new RuleComponent[] {
             new RuleToken("door")})})),               // The chosen alternative
       new RuleCount(                                  // Option chosen
         new RuleSequence(new RuleComponent[] {        //   with one repeat
           new RuleParse(
             new RuleReference("polite"),
             new RuleAlternatives(new RuleComponent[] { // Parse for "polite"
               new RuleToken("please")}))}),           // The chosen alternative
         1, 1)}));                                     // 1 and only 1
 

Completing the cycle, ruleParse.toString will take the parse structure back to a grammar text String. In this case, the information represented by each RuleParse instance is represented by a corresponding ruleref element with the corresponding parse included as the content of the element. The ruleref element does not normally include content, so the resulting String only represents a parse, not valid grammar text.

 <ruleref uri="#command">
     <ruleref uri="#action">
         <one-of>
             <item>
                 <token>close</token>
                 <tag>CL</tag>
             </item>
         </one-of>
     </ruleref>
     <ruleref uri="#object">
         <item repeat="1-1">
             <ruleref uri="#determiner">
                 <one-of>
                     <item>
                         <token>the</token>
                     </item>
                 </one-of>
             </ruleref>
         </item>
         <one-of>
             <item>
                 <token>door</token>
             </item>
         </one-of>
     </ruleref>
     <item repeat="1-1">
         <ruleref uri="#polite">
             <one-of>
                 <item>
                     <token>please</token>
                 </item>
             </one-of>
         </ruleref>
     </item>
 </ruleref>
 

See Also:

RuleGrammar, parse, FinalRuleResult, parse, RuleComponent, RuleAlternatives, RuleCount, RuleReference, RuleSequence, RuleSpecial, RuleTag, RuleToken, RuleLocale

Constructor Summary

RuleParse(RuleReference ruleReference, RuleComponent parse)
Constructs a RuleParse object associating a RuleReference with a parse structure for that RuleReference.

Method Summary

RuleComponent	getParse() Returns the parse associated with (or below) the RuleReference.
RuleReference	getRuleReference() Returns the matched RuleReference (or root) for this RuleParse.
Object[]	getTags() Returns the tags matched in this RuleParse.
String	toString() Converts a RuleParse to a String with a style similar to the grammar text.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RuleParse

public RuleParse(RuleReference ruleReference,
                 RuleComponent parse)

Constructs a RuleParse object associating a RuleReference with a parse structure for that RuleReference.

Viewing a parse as a tree, the RuleParse created by this constructor represents the entire tree with RuleReference as the root and the parse parameter as the subtrees below the root.

Parameters:

ruleReference - a RuleReference within a Grammar

parse - a parse for ruleReference

See Also:

getRuleReference, getParse, parse

Method Detail

getParse

public RuleComponent getParse()

Returns the parse associated with (or below) the RuleReference.

Returns:

the associated parse

See Also:

getRuleReference

getRuleReference

public RuleReference getRuleReference()

Returns the matched RuleReference (or root) for this RuleParse. This RuleReference represents the root of this parse tree. The rest of this parse (subparse) is returned by getParse.

Returns:

the matched RuleReference

See Also:

getParse

getTags

public Object[] getTags()

Returns the tags matched in this RuleParse.

Tags are listed in the order of tokens (from start to end) and from the lowest to highest attachment. The FinalRuleResult.getTags method provides an example.

The tags returned correspond to the most likely parse if more than one parse is represented. Tags for other parses may be retrieved by walking the parse structure in a top-down, left-to-right manner.

Returns:

an array of tags

See Also:

getTags

toString

public String toString()

Converts a RuleParse to a String with a style similar to the grammar text.

Note that a parse for a RuleAlternatives object will contain only the one matching alternative from within that object. A singleton RuleAlternatives object is not normally useful other than for this purpose.

Overrides:

toString in class RuleComponent

Returns:

a parse structure represented using the grammar text

See Also:

RuleComponent, Rule