ruleref Element

  • Article

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

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

  • <ruleref uri="#rulename"/>: Specifies a reference to a rule within the containing grammar.

  • <ruleref uri="grammarUri#rulename"/>: Specifies a reference to a specific rule within an external grammar.

  • <ruleref uri="grammarUri"/>: Specifies a reference to the root rule of an external grammar.

  • <ruleref uri="grammarUri#rulename" type="media-type"/>: Specifies a reference to an external named rule of a grammar, with an associated media type.

  • <ruleref uri="grammarUri" type="media-type"/>: Specifies a reference to the external root rule of a grammar, with an associated media type.

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:

  • NULL: Defines a rule that is automatically matched, meaning that the rule is matched without the user speaking any word.

  • VOID: Defines a rule that can never be spoken. Inserting VOID into a sequence automatically makes that sequence unspeakable.

  • GARBAGE: Defines a rule that can match any speech up until the next rule match, the content of the next token element, or until the end of spoken input.

Either the special or the uri attribute is required, but both cannot be used together.

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

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

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

<!-- 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

Semantic results:

  • First Course: Ice Cream

  • Main Course: Ribs

  • Dessert: Salad

<?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 "$".

<?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 and Using the tag Element.

For an example of an event handler that will retrieve semantic results, see SpeechRecognizedEventArgs.

See Also

Concepts

tag Element

Grammar Rule Reference Referencing