Declaration of all argument completion functions and macros used to define them. More...

#include "core/CorePrereqs.h"
#include "ArgumentCompleter.h"

Namespaces
	orxonox
	Die Wagnis Klasse hat die folgenden Aufgaben:

	orxonox::autocompletion

Macros
#define	_ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_INTERNAL(functionname, bUseMultipleWords)
	Internal macro. More...

#define	ARGUMENT_COMPLETION_FUNCTION_CALL(functionname) acf_##functionname
	Calls an argument completion function. Used for functions that return the results of another argument completion function. More...

#define	ARGUMENT_COMPLETION_FUNCTION_DECLARATION(functionname)
	Used to declare an argument completion function with name functionname. More...

#define	ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(functionname) _ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_INTERNAL(functionname, false)
	Used to implement an argument completion function. More...

#define	ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_MULTI(functionname) _ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_INTERNAL(functionname, true)
	Used to implement an argument completion function which allows multiple words. More...

Functions
ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_MULTI()	orxonox::autocompletion::command (const std::string &fragment)
	Returns a list of commands and groups and also supports auto-completion of the arguments of these commands. More...

ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION()	orxonox::autocompletion::fallback ()
	Fallback implementation, returns an empty list. More...

ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION()	orxonox::autocompletion::files (const std::string &fragment)
	Returns possible files and directories and also supports files in arbitrary deeply nested subdirectories. More...

ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION()	orxonox::autocompletion::groupsandcommands (const std::string &fragment)
	Returns a list of all console command groups AND all console command shortcuts. More...

ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_MULTI()	orxonox::autocompletion::hiddencommand (const std::string &fragment)
	Returns a list of hidden commands and groups and also supports auto-completion of the arguments of these commands. More...

ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION()	orxonox::autocompletion::settingsentries (const std::string &fragment, const std::string &section)
	Returns the entries in a given section of the config file. More...

ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION()	orxonox::autocompletion::settingssections ()
	Returns the sections of the config file. More...

ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION()	orxonox::autocompletion::settingsvalue (const std::string &fragment, const std::string &entry, const std::string &section)
	Returns the current value of a given value in a given section of the config file. More...

ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION()	orxonox::autocompletion::subcommands (const std::string &fragment, const std::string &group)
	Returns a list of all console commands in a given group. More...

ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION()	orxonox::autocompletion::tclthreads ()
	Returns a list of indexes of the available Tcl threads (see TclThreadManager). More...

Detailed Description

Declaration of all argument completion functions and macros used to define them.

Argument completion functions are used to create a list of possible arguments for an orxonox::ConsoleCommand. These functions are usually wrapped by an instance of orxonox::ArgumentCompleter.

Argument completion functions can be declared and implemented by using the macros ARGUMENT_COMPLETION_FUNCTION_DECLARATION() and ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION() respectively. They are necessary because they don't simply define the function, but they also create a static helper function that returns an instance of orxonox::ArgumentCompleter which wraps the defined function. This allows easier referencing of argument completion functions by simply calling autocompletion::functionname().

Argument completion functions can take up to 5 arguments, all of type std::string. The first argument is always the current argument which is being entered by the user in the shell. The second argument is the argument before, so in fact arguments from the shell are sent in reversed order to the argument completion function. This is necessary because the number of arguments can be variable

Example: The user types the following into the shell:

$ commandname argument1 argument2 argum

Then he presses the tab key to print the possible arguments. Now the argument completion function for the third argument of commandname will be called in the following way:

list = argcompfunction3("argum", "argument2", "argument1");

Usually each argument is one word (without whitespaces in it), but some argument completion functions need more than one word. This can be achieved by using ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_MULTI(). In this case all supernumerous words are passed to the first (!) argument.

An example to show how to declare, implement, and use an argument completion function:

// ArgumentCompletionFunctions.h:
// ------------------------------
// Declaration of the function:
ARGUMENT_COMPLETION_FUNCTION_DECLARATION(month)(const std::string& fragment);
// ArgumentCompletionFunctions.cc:
// -------------------------------
// Implementation of the function
ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION(month)(const std::string& fragment)
{
    ArgumentCompletionList list;
    // check if the first part of the argument is a number - if yes, the user likely wants to enter the month as a number
    if (isNumber(fragment))
    {
        for (int month = 1; month <= 12; ++month)
            list.emplace_back(multi_cast<std::string>(month));
    }
    else
    {
        list.emplace_back("January",   "january");
        list.emplace_back("February",  "february");
        list.emplace_back("March",     "march");
        list.emplace_back("April",     "april");
        list.emplace_back("May",       "may");
        list.emplace_back("June",      "june");
        list.emplace_back("July",      "july");
        list.emplace_back("August",    "august");
        list.emplace_back("September", "september");
        list.emplace_back("October",   "october");
        list.emplace_back("November",  "november");
        list.emplace_back("December",  "december");
    }
    return list;
}
// SomeFile:
// ---------
// A class to manage the date:
class Date
{
    public:
        static void setDate(int day, const std::string& month, int year);
};
// Define a console command that needs a date. Add argument completion for the month:
SetConsoleCommand("setDate", &Date::setDate).argumentCompleter(1, autocompletion::month());

This example defines an argument completion function that returns a list of possible months. If the first part of the argument is a number, it returns the numbers 1-12, otherwise the name of the months are returned. Note how the list is composed by instances of orxonox::ArgumentCompletionListElement. For the name of the months, two strings are provided, one in normal case and one in lower case. See the documentation of orxonox::ArgumentCompletionListElement for more information about this.

Also note that the argument completion list is assigned to the console command by using argumentCompleter(). The first argument is the index of the argument:

0 is the first argument (day)
1 is the second argument (month)
2 is the third argument (year)

day and year don't need an argument completion function as they are just integers.

The function autocompletion::month() is automatically created by the macros ARGUMENT_COMPLETION_FUNCTION_DECLARATION() and ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION() and returns an orxonox::ArgumentCompleter that wraps the defined argument completion function.

The implemented argument completion function uses only one argument, the fragment of the currently entered argument. More complex functions can also use the previous arguments to return different arguments depending on the other arguments (for example to list the members of a class, where the class-name is the first argument and the member the second).

Macro Definition Documentation

#define _ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_INTERNAL	(	functionname,
		bUseMultipleWords
	)

Value:

ArgumentCompleter* functionname() \
    { \
        static ArgumentCompleter completer = ArgumentCompleter(&acf_##functionname, bUseMultipleWords); \
        return &completer; \
    } \
    \
    ArgumentCompletionList acf_##functionname

Internal macro.

#define ARGUMENT_COMPLETION_FUNCTION_CALL ( functionname ) acf_##functionname

Calls an argument completion function. Used for functions that return the results of another argument completion function.

#define ARGUMENT_COMPLETION_FUNCTION_DECLARATION ( functionname )

Value:

ArgumentCompleter* functionname(); \

ArgumentCompletionList acf_##functionname

orxonox::ArgumentCompletionList

std::list< ArgumentCompletionListElement > ArgumentCompletionList

Definition: ArgumentCompletionListElement.h:49

Used to declare an argument completion function with name functionname.

Parameters

functionname The name of the function, will also be used for the implementation of the function.

The macro also defines a static function that returns an orxonox::ArgumentCompleter which wraps the defined function. This can be accessed by calling autocompletion::functionname();

#define ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION ( functionname ) _ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_INTERNAL(functionname, false)

Used to implement an argument completion function.

Parameters

functionname The name of the function

#define ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_MULTI ( functionname ) _ARGUMENT_COMPLETION_FUNCTION_IMPLEMENTATION_INTERNAL(functionname, true)

Used to implement an argument completion function which allows multiple words.

Parameters

functionname The name of the function

Namespaces

Macros

Functions

Detailed Description

Macro Definition Documentation