Command-related functions inconsistency

[Pfeil]

Before the introduction of dynamic command sections and multiple phrases per command using semicolons, the contents of the "When I say" field could be considered the full command name, but with those features that term has become less clearly defined:


The "CommandExists" function will check whether a command *phrase* exists, rather than the contents of the "When I say" field.
I feel this is not made clear by the provided example:

CommandExists(string CommandName) – This Boolean function returns true if a command is available to the active profile with the name specified in CommandName.
if (vaProxy.CommandExists(“fire weapons”))
{
    vaProxy.ExecuteCommand(“fire weapons”);
}

The "ExecuteCommand" function also uses command phrases.

ExecuteCommand(string CommandName, optional Boolean WaitForReturn) – This method will execute a VoiceAttack command in the active profile by the name indicated in CommandName. The flow of execution will continue immediately if you pass in false (the default) for WaitForReturn. If you want the flow of execution to wait until the command completes, pass in true. If the command does not exist, the log will display an alert.

vaProxy.ExecuteCommand(“fire weapons”); //continues immediately (asynchronous)
vaProxy.ExecuteCommand(“fire weapons”, true); //waits until the command completes

The "CommandActive" function, however, does in fact use the contents of the "When I say" field, and will not work with command phrases at all.
The documentation for it doesn't actually use the term "command name" at all, but by not providing any other indication what value it does expect, that doesn't actually make its usage clearer.

CommandActive(string CommandName) – This Boolean function returns true if the indicated command is actively executing.
if (vaProxy.CommandActive(“fire weapons”) == false) //if command not active
{
    vaProxy.ExecuteCommand(“fire weapons”); //execute the command
}

which is actually inconsistent with the corresponding token:

{CMDACTIVE:name} - This provides a way to test if a command is currently active.
Simply provide the command name (spoken phrase), and the rendered value will be, ‘1’ if the command is active, or ‘0’ if not. Ex: {CMDACTIVE:fire weapon} will check to see if the command, ‘fire weapon’ is active.

Bold emphasis mine

The latter does clarify the intended definition of "command name".


EDIT: With the sub-categorizing of methods, the documentation has changed, though the use of the arguably ambiguous term, "name", remains:

Exists(string CommandName) – This Boolean function returns true if a command is
available to the active profile with the name specified in CommandName.
if (vaProxy.Command.Exists(“fire weapons”))
{
    vaProxy.Command.Execute(“fire weapons”);
}

Execute (string CommandName, optional Boolean WaitForReturn, optional Boolean
AsSubcommand, optional Action<Guid?> CompletedAction) - This method will execute a
VoiceAttack command in the active profile by the name indicated in CommandName. The
flow of execution will continue immediately if you pass in false (the default) for
WaitForReturn. If you want the flow of execution to wait until the command completes,
pass in true. Pass a true value as the AsSubcommand parameter to execute the
command in the context of a subcommand to the calling command. This will allow the
executed command to gain certain attributes of the calling command, such as command-
shared variables and also allows the command to execute if the calling command is called
synchronously. The optional parameter CompletedAction will allow you to specify a
function that is called when the command completes execution (that is, after all of its
actions have been invoked). What is returned to the function’s single nullable GUID
parameter will be the internal id of the command.
Notes - If the command does not exist, the log will display an alert. If you execute a
command using this method within a proxy or plugin initialization method or by clicking the,
‘Test’ button of the Inline Function editor, AsSubcommand will be ignored, since the
execution will not be within the context of an executing command.
vaProxy.Command.Execute(“fire weapons”); //continues immediately (asynchronous)
vaProxy.Command.Execute (“fire weapons”, true); //waits until the command com-
pletes
vaProxy.Command.Execute (“fire weapons”, true, true); //waits until the command
completes and also execute the command as a subcommand
//A quick example of how to use the, ‘CompletedAction’ parameter.
//First, we must set up the callback function (note the single parameter):
public void MyCompletedFunction(Guid? theInternalId)
{
    VA.WriteToLog(theInternalId.ToString() + “ completed”, “Orange”);
}
vaProxy.Command.Execute (“fire weapons”, true, true, MyCompletedFunction);
//this waits until the command completes, executes the command as a subcommand and
//executes, ‘MyCompletedFunction’ when it is finished.

Active(string CommandName) - This Boolean function returns true if the command
indicated by name in CommandName is actively executing (most likely long-running or
running in a loop).
if (vaProxy.Command.Active(“fire weapons”) == false) //if command not active
{
    vaProxy.Command.Execute(“fire weapons”); //execute the command
}

Retesting "Command.Active()" and its legacy equivalent "CommandActive()" in v1.8.3.21 shows they now take command phrases, and only command phrases (using the full contents of the "When I say" field will have them return False), which is consistent with the "{CMDACTIVE:}" token.


EDIT: Documentation adjusted with v1.8.3.22

[Gary]

I've replaced the CommandName parameters with CommandPhrase, and changed the text to read, 'spoken phrase' instead of, 'name'.  Hoping that might clear up some confusion.  Thank you for the rather involved description of what you were finding