Changes between Version 3 and Version 4 of code/doc/CommandExecutor

Timestamp:

Oct 7, 2008, 6:22:07 PM (16 years ago)

Author:

landauf

Comment:

—

code/doc/CommandExecutor

@@ -14 +14 @@
 == 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:Debug 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.
+
+
 === 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''''')'''
+
 === evaluate() ===