{CMDSEGMENT:} token behavior

[Pfeil]

The "{CMDSEGMENT:}" token allows you to retrieve a specific segment of a phrase that was spoken to trigger a command.

Note that this topic assumes you are already familiar with tokens. If not, this topic may be of use in addition to the official documentation.

Given that this token is specifically intended for use with commands that use dynamic command sections, understanding that feature is also a prerequisite.
Press F1 while VoiceAttack has focus to open VoiceAttackHelp.pdf in your default PDF viewer, and search for the "Dynamic command sections" subsection of the "1 - Command Input" subsection of the "Command Screen" section, if you have not read it already.


As an example, if your command's "When I say" field contains "Make me [1..3] tall glasses of [strawberry milkshake;cool refreshing water;bees] [please;]", the following values can be returned by the token:

• {CMDSEGMENT:0} will return "Make me"
• {CMDSEGMENT:1} can return "1", "2", or "3"
• {CMDSEGMENT:2} will return "tall glasses of"
• {CMDSEGMENT:3} can return "strawberry milkshake", "cool refreshing water", or "bees"
• {CMDSEGMENT:4} can return "please", or it can return "" (blank) if "please" was not spoken
• {CMDSEGMENT:5} and all subsequent indices (E.G. {CMDSEGMENT:6}, {CMDSEGMENT:7}, etc... will return "Not set", as there are no further segments of the spoken phrase

As shown in the example, a segment can consist of a static command section, or a dynamic command section, regardless of how many words or characters are within that specific section.


If you have multiple command phrases separated by semicolons in the "When I say" field, the available segment data depends on which of those phrases was spoken

E.G. if the "When I say field" contains "my phrase [with dynamic sections;];my other phrase [also with dynamic sections;] but with a third segment",

• {CMDSEGMENT:0} can return "my phrase" or "my other phrase"
• {CMDSEGMENT:1} can return "with dynamic sections", "also with dynamic sections", or it can return "" (blank) if neither was spoken
• {CMDSEGMENT:2} can return "but with a third segment" or "Not set", as the first phrase only has two segments
• {CMDSEGMENT:3} and all subsequent indices will return "Not set", as there are no further segments of the spoken phrase

Note that tokens, including the "{CMDSEGMENT:}" token, do not affect how a command is processed or recognized. E.G. in the example shown, you must still speak one of the following:
"my phrase with dynamic sections"
"my phrase"
"my other phrase also with dynamic sections but with a third segment"
"my other phrase but with a third segment"
I.E. it does not affect which permutations are available. Using a semicolon in the "When I say" field that is not part of a dynamic command section, creates a new, separate phrase.

If you are unsure which phrases you are generating, this command can be useful to show a list of all permutations.

As with any token, if you are unsure of which output the "{CMDSEGMENT:}" token will produce for a given index, you can use the "Write a Value to the Event Log" action to show that output in the log on VoiceAttack's main window.
E.G.

Code: [Select]

Write [Blue] '0 = "{CMDSEGMENT:0}", 1 = "{CMDSEGMENT:1}", 2 = "{CMDSEGMENT:2}", 3 = "{CMDSEGMENT:3}"' to log
or

Code: [Select]

Start Loop : Repeat From 0 to 3, using indexer [~i]
    Write [Blue] '|{CMDSEGMENT:{INT:~i}|} = "{CMDSEGMENT:{INT:~i}}"' to log
End Loop


Lastly, note that by default, the "{CMDSEGMENT:}" token is not available in composite commands (consisting of a prefix and a suffix command), for performance reasons.

While it can be enabled using the "Allow command segment info for composite commands" option on the "System / Advanced" tab of the VoiceAttack options window, it's worth considering alternatives to the "{CMDSEGMENT:}" token where possible instead.

E.G. if you have a prefix command where the "When I say" field contains "prefix [with dynamic sections;]", and a suffix command where the "When I say" field contains "suffix [also with dynamic sections;]", to the "{CMDSEGMENT:}" token that would be the equivalent of "prefix [with dynamic sections;]suffix [also with dynamic sections;]", provided the option to generate segment information is enabled.

However, if you want to check, for example, which suffix was spoken (assuming you have another suffix, E.G. where the "When I say" field contains "another suffix"), rather than using something like

Code: [Select]

Begin Text Compare : [{CMDSEGMENT:2}] Starts With 'suffix'
    Write [Blue] '"suffix" was spoken' to log
Else
    Write [Blue] '"another suffix" was spoken' to log
End Condition
you could use

Code: [Select]

Begin Text Compare : [{SUFFIX}] Starts With 'suffix'
    Write [Blue] '"suffix" was spoken' to log
Else
    Write [Blue] '"another suffix" was spoken' to log
End Condition
which does not require the "Allow command segment info for composite commands" option to be enabled.

Likewise, if you have a suffix, for example, with a number of dynamic segments, E.G. where the "When I say" field contains "[new;used][red;green;blue;][cars;bicycles;motorcycles]", and you want to check which permutation was spoken, rather than using

Code: [Select]

Begin Text Compare : [{CMDSEGMENT:3}] Equals 'red'
    Write [Red] '"red" was spoken' to log
Else If Text Compare : [{CMDSEGMENT:3}] Equals 'green'
    Write [Green] '"green" was spoken' to log
Else If Text Compare : [{CMDSEGMENT:3}] Equals 'green'
    Write [Blue] '"blue" was spoken' to log
Else
    Write [Green] 'No color was spoken' to log
End Condition
you could use

Code: [Select]

Begin Text Compare : [{SUFFIX}] Contains 'red'
    Write [Red] '"red" was spoken' to log
Else If Text Compare : [{SUFFIX}] Contains 'green'
    Write [Green] '"green" was spoken' to log
Else If Text Compare : [{SUFFIX}] Contains 'green'
    Write [Blue] '"blue" was spoken' to log
Else
    Write [Green] 'No color was spoken' to log
End Condition
which does not require the "Allow command segment info for composite commands" option to be enabled.

Or, if you have a suffix, for example, containing a number but also text, E.G. where the "When I say" field contains "[1..10][new;used][cars;bicycles;motorcycles]", and you want to retrieve the number by itself, rather than using

Code: [Select]

Write [Blue] '{CMDSEGMENT:2} items were requested' to log
you could use

Code: [Select]

Write [Blue] '{TXTNUM:"{SUFFIX}"} items were requested' to log
which does not require the "Allow command segment info for composite commands" option to be enabled.