= !CommandExecutor =
[[TOC]]

== Description ==
!CommandExecutor is a parser that calls a function defined by a string. To do this, !CommandExecutor searches for a [wiki:ConsoleCommand] with the given name, parses the arguments and calls the command. !CommandExecutor is also able to give hints to a function (what the function does) and to complete classnames, functionnames and arguments (see [wiki:ArgumentCompleter]).

All existing !ConsoleCommands are stored in maps: Commands belonging to a class are stored in the Identifier of the class while shortcuts are stored in a map located in the !CommandExecutor itself.

Another feature: !CommandExecutor can evaluate a given command without calling it. To achieve this, !CommandExecutor returns a [wiki:CommandEvaluation], containing a pointer to the !ConsoleCommand and all arguments stored in [wiki:MultiType MultiTypes], already converted to the requested type. This allows you to execute an evaluated command really fast, which is of interest if you execute the same command over and over.

To execute more complex commands, !CommandExecutor uses [wiki:TclBind].

== Usage ==
=== execute() ===
'''execute('''''string''''')''' parses the string and searches a [wiki:ConsoleCommand] with the given name. Given arguments (separated by spaces) are used to execute the !ConsoleCommand.

''string'' has to be a complete !ConsoleCommand (complete in the sense that the command exists and all needed arguments are given), otherwise the !CommandExecutor returns false and sends an [wiki:Output error message] to the output.

 * Example 1:
{{{
CommandExecutor::execute("myfunction 10");
}}}
    This is equal to ''myfunction(10)'' provided that "myfunction" was declared as a !ConsoleCommand.

 * Example 2:
{{{
CommandExecutor::execute("MyClass myfunction 0.1 0.2 0.3");
}}}
    This is equal to ''MyClass::myfunction(0.1, 0.2, 0.3)'' provided that the function "myfunction" of the class "!MyClass" was declared as a !ConsoleCommand.

The execute function optionally takes a second argument: '''execute('''''string, bUseTcl''''')'''. If ''bUseTcl'' is set to true (this is the default!) a command is first passed to Tcl (see [wiki:TclBind] for more information). Tcl parses the command, executes all Tcl-related code and if it finds a !ConsoleCommand only known to Orxonox it passes the command back to CommandExecutor::execute with ''bUseTcl = false''.

 * Example 3:
{{{
CommandExecutor::execute("MyClass myfunction [expr 10+10]");
}}}
    This command will be sent to Tcl. Tcl first evaluates the subcommand within brackets ''expr 10+10'' which results ''20'' and then returns "!MyClass myfunction 20" back to Orxonox where it will be executed equivalent to ''MyClass::myfunction(20)''.

=== hint() ===
'''hint('''''string''''')''' returns a help message providing some information about an incomplete command (incomplete in the sense that not all possible arguments are yet given). This includes a list of the requested arguments and default-values (if any). If there's a description of the command, it is displayed too.

If ''string'' doesn't describe a unique !ConsoleCommand, hint returns a list of possible commands matching the already given fragment. It also returns a list of possible arguments if there's an [wiki:ArgumentCompleter] declared for the current argument.

 * Example 1 (function description, argument list, default values):
{{{
class MyClass
{
    static void myfunction(int value, bool condition, const std::string& name);
};

SetConsoleCommand(MyClass, myfunction, true)
    .defaultValue(1, false)     // 1 refers to the second argument (condition)
    .defaultValue(2, "Default") // 2 refers to the third argument (name)
    .description("This is a useless testfunction!");

// Get the hint:
CommandExecutor::hint("MyClass myfunction");

// Output:
 > This is a useless testfunction!
 > myfunction: {int} [bool=false] [string=Default]
}}}

 * Example 2 (possible classes and functions, possible arguments):
{{{
class MyClass
{
    static void myfunction(int value, bool condition, const std::string& name);
};

SetConsoleCommand(MyClass, myfunction, true)
    .defaultValue(1, false)     // 1 refers to the second argument (condition)
    .defaultValue(2, "Default") // 2 refers to the third argument (name)
    .description("This is a useless testfunction!")
    .argumentCompleter(2, autocompletion::mynames()); // argument completion for the name

// First try an empty string: We get a list of all possible classes and functions
CommandExecutor::hint("");
 > myfunction
 > MyClass

// Now start typing the classname: We get a list of all possible
// classnames (only MyClass in our example)
CommandExecutor::hint("mycl");
 > MyClasses

// We've finished the classname, now we get a list of all functions
// of this class (only myfunction in our example)
CommandExecutor::hint("MyClass ");
 > myfunction

// There's still only one possible function:
CommandExecutor::hint("MyClass myfunc");
 > myfunction

// Now we get the hint from example 1
CommandExecutor::hint("MyClass myfunction ");
 > This is a useless testfunction!
 > myfunction: {int} [bool=false] [string=Default]

// As soon as we start typing the third argument (notice the space after the
// second argument) we get a list of all possible arguments for "name" because
// we've added an ArgumentCompletor:
CommandExecutor::hint("MyClass myfunction 10 true ");
 > Adam Bernd Claude Default Eric Elton Fred Hank

// We start typing the third argument, the list of possible arguments reduces
// to arguments starting with the given letter:
CommandExecutor::hint("MyClass myfunction 10 true e");
 > Eric Elton

// We type another letter and the list reduces even more:
CommandExecutor::hint("MyClass myfunction 10 true er");
 > Eric
}}}

=== complete() ===
'''complete('''''string''''')''' looks at the list of possible classnames, functionnames and arguments (like hint() in example 2) and trys to complete the command if there's only one possibility.

Note: If there's only one possible class with only one function and only one possible argument, complete() returns the whole command.

 * Example 2:
{{{
// Existing functions:
// abc, function1, function2, test, temporary

CommandExecutor::complete("a");
// returns "abc" because it's the only possibility

CommandExecutor::complete("fun");
// returns "function" because function1 and function2 are possible and
// "function" is the common begin of both

CommandExecutor::complete("t");
// returns "te" because it's the common begin of "test" and "temporary"
}}}

 * Example 2:
{{{
// Existing classes:
// MyClass

// Existing functions in MyClass:
// myfunction

// Possible arguments of MyClass::myfunction:
// 10

CommandExecutor::complete("m");
// returns "MyClass myfunction 10"
}}}

=== evaluate() ===
'''evaluate('''''string''''')''' parses ''string'' just as execute() but doesn't execute the command. Instead an instance of [wiki:CommandEvaluation] is returned, containing the command split up into a a pointer to the [wiki:ConsoleCommand] and a list of all arguments stored in [wiki:MultiType MultiTypes] already converted to the desired type.

With this you can separate between parsing and execution of a command which is useful if you need good performance (for example if a command is [wiki:KeyBinder bound] to a key and pressed 20 times per second).

== Illustration ==
[[Image(CommandExecutor.png)]]

The illustration shows how the !CommandExecutor executes a [wiki:ConsoleCommand] by searching for the specified command in the shortcut list and the lists of all [wiki:Identifier Identifiers] and then executes the command by calling the [wiki:Functor]. At the end, it stores the returnvalue.