The ruleref element specifies a reference by the containing rule to another rule, either in the same grammar or in an external grammar. The referenced rule defines user input that must be matched for successful recognition of the containing rule. This element is especially useful for reusing using rules and grammars that contain content which does not change frequently, such as a list of cities or a rule for recognizing phone numbers.
Syntax
| XML |
Copy Code
|
|---|---|
<ruleref uri = "ruleLocation" special = (NULL | VOID | GARBAGE) type = "media-type" </ruleref> |
|
Attributes
|
Attribute |
Description |
|---|---|
|
uri |
Optional. Specifies the location of the rule to be referenced. A rule can be referenced using one of the following forms:
Either the uri or the special attribute is required, but both cannot be used together. |
|
special |
Optional. Specifies a reference to a rule that has specific interpretation and processing by a speech recognizer. A grammar must not redefine these special rule names. The special rule names are as follows:
Either the special or the uri attribute is required, but both cannot be used together. |
|
type |
Optional. Specifies the media type of the grammar containing the reference. Consider using this attribute only as a last choice. For example, using this attribute can be appropriate when a grammar is retrieved through HTTP and both of the following are true:
|
Remarks
The ruleref element is an empty element that allows authors to reuse rules and grammars. For example, a grammar author can develop a series of grammars that support mathematic operations and numbers. The grammars can be redistributed using either a Web site or a compiled grammar. Other authors can use the distributed grammars by adding a ruleref element to their own grammar referencing the appropriate file or resource location. By reusing existing rules, authors can more quickly build complex grammars.
You can also use ruleref elements to structure semantic properties into a hierarchy. See Grammar Example: Solitaire (Microsoft.Speech) for an example of a grammar that uses ruleref elements to build and organize a grammar.
Examples
The following are examples of typical uses for the ruleref element in grammar authoring.
Rule Reference within a Grammar
The following example demonstrates using a ruleref element to reference the rule named city in the containing grammar "CityList.grxml".
| XML |
Copy Code
|
|---|---|
<!-- Grammar file "cityList.grxml" -->
<?xml version="1.0" encoding="utf-8"?>
<grammar version="1.0" xml:lang="en-US" mode="voice" root="location"
xmlns="http://www.w3.org/2001/06/grammar" tag-format="semantics/1.0">
<rule id="location">
<item> Fly me to <\item>
<ruleref uri="#city"/>
</rule>
<rule id="city">
<one-of>
<item> Boston </item>
<item> Madrid </item>
</one-of>
</rule>
</grammar>
|
|
Rule Reference Outside a Grammar
The following example uses a ruleref element in the grammar file "Locations.grxml" to reference the external grammar file "StateList.grxml". Because the ruleref element does not specify a rule name, the reference points to the root rule in "StateList.grxml", which has the identifier states.
| XML |
Copy Code
|
|---|---|
<!-- Grammar file "locations.grxml" -->
<?xml version="1.0" encoding="utf-8"?>
<grammar version="1.0" xml:lang="en-US" mode="voice" root="getState"
xmlns="http://www.w3.org/2001/06/grammar" tag-format="semantics/1.0">
<rule id="getState">
<item> My home state is </item>
<ruleref uri="c:\Grammars\stateList.grxml"/>
</rule>
</grammar>
<!-- Grammar file "stateList.grxml" -->
<?xml version="1.0" encoding="utf-8"?>
<grammar root="states" version="1.0" xmlns="http://www.w3.org/2001/06/grammar"
xml:lang="en-US" tag-format="semantics/1.0">
<rule id="states" scope="public">
<one-of>
<item> Alabama </item>
<item> Alaska </item>
<item> Arizona </item>
<item> Arkansas </item>
...
</one-of>
</rule>
</grammar>
|
|
Rule References to Public and Private External Rules
The following example uses two ruleref elements in the grammar file "FindFood.grxml" to reference two external rules contained in the grammar file "restaurantInfo.grxml". The grammar "restaurantInfo.grxml" does not specify a root rule, so it cannot be loaded by a speech recognition engine. However, the rules in the grammar can be imported by other grammars, using the ruleref element, but only if the value of a rule's scope attribute is public. Note that the uri attribute of the ruleref elements includes the name of the grammar and the name of the rule.
| XML |
Copy Code
|
|---|---|
<!-- Grammar file "FindFood.grxml" -->
<?xml version="1.0" encoding="utf-8"?>
<grammar version="1.0" xml:lang="en-US" mode="voice" root="getRestaurantInfo"
xmlns="http://www.w3.org/2001/06/grammar" tag-format="semantics/1.0">
<rule id="getRestaurantInfo">
<item repeat="0-1"> Find </item>
<ruleref uri="restaurantInfo.grxml#food"/>
<item repeat="0-1"> food near </item>
<ruleref uri="restaurantInfo.grxml#location"/>
</rule>
</grammar>
<!-- Grammar file "restaurantInfo.grxml" -->
<?xml version="1.0" encoding="utf-8"?>
<grammar version="1.0" xml:lang="en-US" mode="voice"
xmlns="http://www.w3.org/2001/06/grammar" tag-format="semantics/1.0">
<rule id="food" scope="public">
<one-of>
<item> Italian </item>
<item> Thai </item>
<item> Fast </item>
</one-of>
</rule>
<rule id="location" scope="public">
<one-of>
<item> Bellevue </item>
<item> Redmond </item>
<item> Seattle </item>
</one-of>
</rule>
</grammar>
|
|
Rule References with Semantics
Ruleref elements are often used in conjunction with tag elements to assign semantic meaning to the recognition result from the referenced rule.
The following example presents a grammar for ordering a meal from a menu. Diners can order any item for a first course, a main course, or for dessert.
The example consists of a root rule (menuOrder) that contains rule references to a second rule that holds the menu items (menu). In the tag element following each ruleref element, the example creates a property for the Rule Variable (identified by "out") of the root rule of the grammar. The properties are named "firstCourse", "mainCourse", and "dessert". Each tag element assigns the recognition result from the referenced rule to the created property. The property serves as a semantic key that identifies the recognition result from the rule named menu as a first course, main course, or dessert.
The speech recognition engine will return the recognition result from each rule reference and tag it with the property name. You can use the property name as a semantic key to retrieve the recognition result for each rule reference. For example, here is a typical recognition result for the grammar that follows:
Recognized phrase: I want to start with Ice Cream followed by Ribs and then the Salad
First Course: Ice Cream
Main Course: Ribs
Dessert: Salad
|
Copy Code
|
|
|---|---|
<?xml version="1.0" encoding="utf-8"?>
<grammar xml:lang="en-US" root="menuOrder"
tag-format="semantics/1.0" version="1.0"
xmlns="http://www.w3.org/2001/06/grammar">
<rule id="menuOrder">
<item> I want to start with </item>
<ruleref uri="#menu" /><tag> out.firstCourse=rules.latest(); </tag>
<item> followed by </item>
<ruleref uri="#menu" /><tag> out.mainCourse=rules.latest(); </tag>
<item> and then the </item>
<ruleref uri="#menu" /><tag> out.dessert=rules.latest(); </tag>
</rule>
<rule id="menu">
<one-of>
<item> Salad </item>
<item> Soup </item>
<item> Cheese </item>
<item> Ribs </item>
<item> Fish </item>
<item> Pasta </item>
<item> Ice Cream </item>
<item> Cake </item>
<item> Pie </item>
</one-of>
</rule>
</grammar>
|
|
The preceding example uses the latest() function on the rules object to reference the last ruleref element to be used in the rule that matches the utterance.
The following example is the same as the preceding example, but uses the syntax of tag-format="semantics-ms/1.0". In the syntax of semantics-ms/1.0, the result from the latest referenced rule that matches the utterance can be represented by the shorthand symbol "$$". The Rule Variable in semantics-ms\1.0 is identified by "$".
|
Copy Code
|
|
|---|---|
<?xml version="1.0" encoding="utf-8"?>
<grammar xml:lang="en-US" root="menuOrder"
tag-format="semantics-ms/1.0" version="1.0"
xmlns="http://www.w3.org/2001/06/grammar">
<rule id="menuOrder">
<item> I want to start with </item>
<ruleref uri="#menu" /><tag> $.firstCourse=$$; </tag>
<item> followed by </item>
<ruleref uri="#menu" /><tag> $.mainCourse=$$; </tag>
<item> and then the </item>
<ruleref uri="#menu" /><tag> $.dessert=$$; </tag>
</rule>
<rule id="menu">
<one-of>
<item> Salad </item>
<item> Soup </item>
<item> Cheese </item>
<item> Ribs </item>
<item> Fish </item>
<item> Pasta </item>
<item> Ice Cream </item>
<item> Cake </item>
<item> Pie </item>
</one-of>
</rule>
</grammar>
|
|
For more information about attaching semantics to rule references, see Grammar Rule Reference Referencing (Microsoft.Speech) and Using the tag Element (Microsoft.Speech).
For an example of an event handler that will retrieve semantic results, see SpeechRecognizedEventArgs.
See Also
