Note
Please see Azure Cognitive Services for Speech documentation for the latest supported speech solutions.
Referencing Grammar Rule Variables (Microsoft.Speech)
ECMAScript expressions that are contained in tag elements generate semantic values that are associated with the Rule Variable of a rule element. A rule variable is a container for values generated in the evaluation of a rule, including a basic scalar return value for the rule, attributes explicitly set by scripts in the rule, and other attributes automatically filled when the rule matches words, regardless of scripts. There are two forms of reference to Rule Variables:
Grammar Rule Name Referencing (Microsoft.Speech). Use script expressions to evaluate or assign semantic values that are associated with the Rule Variable of the containing rule element.
Grammar Rule Reference Referencing (Microsoft.Speech). Use script expressions to evaluate semantic values that are associated with the Rule Variable of a separate rule element that is the target of a ruleref element within the containing rule element.
The required form of reference for a script expression depends on whether the expression refers to the Rule Variable of the containing rule element or to the Rule Variable of a rule element that is referenced by a ruleref element. To reference the Rule Variable of the containing rule element, use script assignments of the form out = value; or out.Property = value;. The first assignment statement assigns a value to the Rule Variable. The second assignment statement assigns a value to the property (named Property) on the Rule Variable.
To reference the Rule Variable of a rule element that is outside of the containing rule, use the rules object. Every semantic interpretation script has access to this object, which can be used to access the value of any visible Rule Variable. For example, the semantic interpretation script out = rules.RuleName; provides access to the value of a rule named RuleName.
You can also use an alternate syntax, created by Microsoft, to reference the Rule Variable of a rule element that is outside of the containing rule. To use this syntax, set tag-format="semantics-ms/1.0" in the grammar element. See Support for Semantic Markup (Microsoft.Speech).
Illustration of Rule Name Referencing versus Rule Reference Referencing
The following example illustrates the appropriate use of both forms of referencing. In this example, the root rule named Time contains references to two other rules named Ordinal and Month. The Time rule also contains a list in a one-of element with the items "Saturday" and "Sunday". The example includes line numbers to simplify locating code elements that the comments identify.
Rule Name Referencing
Lines 12 and 13 illustrate Rule Name Referencing. In both of these lines, the item element contains a tag element. Script expressions contained in these tag elements assign values to the Ordinal and Weekday properties of the Rule Variable belonging to the rule named Time. The Weekday property is not assigned a value, as such. Instead, it acts as the parent of two other properties (dayNumber and dayAbbrev) that are assigned values.
Note
The script expression contained by the tag element on line 7 constructs the Weekday property as an empty object. This causes Weekday to be represented as a separate node in the Semantic Markup Language (SML) output and allows for the possibility of creating grandchild properties. The rest of the script expression on this line initializes the two child properties of Weekday (grandchildren of the Rule Variable for the rule named Time).
1 <?xml version="1.0" encoding="UTF-8" ?>
2 <grammar version="1.0" xml:lang="en-US" mode="voice" root= "Time"
3 xmlns="http://www.w3.org/2001/06/grammar" tag-format="semantics/1.0">
4
5 <rule id="Time" scope="public">
6 <example> The first Saturday in January </example>
7 <tag> out.Weekday=new Object(); out.Weekday.dayNumber=-1; out.Weekday.dayAbbrev="Noneday"; </tag>
8 <item> The </item>
9 <ruleref uri="#Ordinal" />
10 <tag> out.Ordinal=rules.Ordinal; </tag>
11 <one-of>
12 <item> Saturday <tag> out.Weekday.dayNumber=6; out.Weekday.dayAbbrev="Sat"; </tag></item>
13 <item> Sunday <tag> out.Weekday.dayNumber=0; out.Weekday.dayAbbrev="Sun"; </tag></item>
14 </one-of>
15 <item> in </item>
16 <ruleref uri="#Month" /><tag> out.Month=rules.Month; </tag>
17 </rule>
18
19 <rule id="Ordinal">
20 <one-of>
21 <item> first <tag> out = 1; </tag> </item>
22 <item> second <tag> out = 2; </tag> </item>
23 <item> third <tag> out = 3; </tag> </item>
24 </one-of>
25 </rule>
26
27 <rule id="Month">
28 <one-of>
29 <item> January <tag> out = 1; </tag> </item>
30 <item> February <tag> out = 2; </tag> </item>
31 <item> March <tag> out = 3; </tag> </item>
32 </one-of>
33 </rule>
34 </grammar>
Rule Reference Referencing
Lines 10 and 16 illustrate Rule Reference Referencing. On line 10, a tag element that points to the rule named Ordinal immediately follows the ruleref element on line 9. The script expression contained in the tag element on line 10 evaluates the semantic value associated with the Ordinal rule, and assigns this value to the Ordinal property on the Rule Variable. The script expression contained in the tag element on line 16 evaluates the semantic value associated with the rule element named Month, and assigns this value to the Month property on the Rule Variable. Alternatively, the script assignment on line 10 could have been written as out.Ordinal = rules.latest();. This form uses the latest() function to return the last semantic value returned by one of the visible Rule Variables.
Note
The script expressions in a tag element can refer only to semantic values associated with the immediately preceding rule and not any subsequently referenced rules. For example, the script expressions in the tag element on line 10 cannot refer to semantic values associated with the rule named Month because the semantic interpreter finishes parsing the script expressions on line 10 before parsing the ruleref to Month on line 16.
Using the syntax of semantics-ms/1.0, the example above can be written as follows:
1 <?xml version="1.0" encoding="UTF-8" ?>
2 <grammar version="1.0" xml:lang="en-US" mode="voice" root= "Time"
3 xmlns="http://www.w3.org/2001/06/grammar" tag-format="semantics-ms/1.0">
4
5 <rule id="Time" scope="public">
6 <example> The first Saturday in January </example>
7 <tag> $.Weekday=new Object(); $.Weekday.dayNumber=-1; $.Weekday.dayAbbrev="Noneday"; </tag>
8 <item> The </item>
9 <ruleref uri="#Ordinal" />
10 <tag> $.Ordinal=$Ordinal; </tag>
11 <one-of>
12 <item> Saturday <tag> $.Weekday.dayNumber=6; $.Weekday.dayAbbrev="Sat"; </tag></item>
13 <item> Sunday <tag> $.Weekday.dayNumber=0; $.Weekday.dayAbbrev="Sun"; </tag></item>
14 </one-of>
15 <item> in </item>
16 <ruleref uri="#Month" /><tag> $.Month=$Month; </tag>
17 </rule>
18
19 <rule id="Ordinal">
20 <one-of>
21 <item> first <tag> $ = 1; </tag> </item>
22 <item> second <tag> $ = 2; </tag> </item>
23 <item> third <tag> $ = 3; </tag> </item>
24 </one-of>
25 </rule>
26
27 <rule id="Month">
28 <one-of>
29 <item> January <tag> $ = 1; </tag> </item>
30 <item> February <tag> $ = 2; </tag> </item>
31 <item> March <tag> $ = 3; </tag> </item>
32 </one-of>
33 </rule>
34 </grammar>
See Also
Concepts
Using the tag Element (Microsoft.Speech)
tag Element (Microsoft.Speech)
ruleref Element (Microsoft.Speech)