ConsoleCommandIncludes.h File Reference

Declaration the SetConsoleCommand() macro. More...

#include "core/CorePrereqs.h"
#include "ConsoleCommand.h"
#include "ConsoleCommandManager.h"
#include "util/VA_NARGS.h"
#include "core/module/StaticallyInitializedInstance.h"

Go to the source code of this file.

Classes
class	orxonox::StaticallyInitializedConsoleCommand

Namespaces
	orxonox
	Die Wagnis Klasse hat die folgenden Aufgaben:

Macros
#define	DeclareConsoleCommand(...)   BOOST_PP_EXPAND(BOOST_PP_CAT(DeclareConsoleCommand, ORXONOX_VA_NARGS(__VA_ARGS__))(__VA_ARGS__))
	Declares a console command. More...
#define	DeclareConsoleCommand2(name, functionpointer)   DeclareConsoleCommandGeneric("", name, orxonox::createFunctor(functionpointer))
	This macro is executed if you call DeclareConsoleCommand() with 2 arguments. More...
#define	DeclareConsoleCommand3(group, name, functionpointer)   DeclareConsoleCommandGeneric(group, name, orxonox::createFunctor(functionpointer))
	This macro is executed if you call DeclareConsoleCommand() with 3 arguments. More...
#define	DeclareConsoleCommandGeneric(group, name, functor)
	Internal macro. More...
#define	SetConsoleCommand(...)   BOOST_PP_EXPAND(BOOST_PP_CAT(SetConsoleCommand, ORXONOX_VA_NARGS(__VA_ARGS__))(__VA_ARGS__))
	Defines a console command. More...
#define	SetConsoleCommand2(name, functionpointer)   SetConsoleCommandGeneric("", name, orxonox::createFunctor(functionpointer))
	This macro is executed if you call SetConsoleCommand() with 2 arguments. More...
#define	SetConsoleCommand3(group, name, functionpointer)   SetConsoleCommandGeneric(group, name, orxonox::createFunctor(functionpointer))
	This macro is executed if you call SetConsoleCommand() with 3 arguments. More...
#define	SetConsoleCommand4(group, name, functionpointer, object)   SetConsoleCommandGeneric(group, name, orxonox::createFunctor(functionpointer, object))
	This macro is executed if you call SetConsoleCommand() with 4 arguments. More...
#define	SetConsoleCommandGeneric(group, name, functor)
	Internal macro. More...

Typedefs
typedef StaticallyInitializedConsoleCommand	orxonox::SI_CC

Functions
ConsoleCommand::ConsoleCommandManipulator	orxonox::ModifyConsoleCommand (const std::string &name)
	Returns a manipulator for a command with the given name. More...
ConsoleCommand::ConsoleCommandManipulator	orxonox::ModifyConsoleCommand (const std::string &group, const std::string &name)
	Returns a manipulator for a command with the given group and name. More...

Detailed Description

Declaration the SetConsoleCommand() macro.

Console commands can be used to write scripts, use key-bindings or simply to be entered into the shell by the user. Instances of orxonox::ConsoleCommand define the function of a command, and also more information like, for example, if it is active, default values, and possible arguments.

Commands need to be registered to the system statically on startup by using the SetConsoleCommand() or DeclareConsoleCommand() macros outside of a function. This ensures that commands are known to the system at any time, so they can be evaluated (see orxonox::CommandExecutor::evaluate()), for example for key-bindings.

Example:

void myCoutFunction(const std::string& text)        // Define a static function
{
    orxout() << "Text: " << text << endl;           // Print the text to the console
}

SetConsoleCommand("cout", &myCoutFunction);         // Register the function as command with name "cout"

Now you can open the shell and execute the command:

$ cout Hello World

Internally this command is now passed to orxonox::CommandExecutor::execute():

CommandExecutor::execute("cout HelloWorld");

CommandExecutor searches for a command with name "cout" and passes the arguments "Hello World" to it. Because we registered myCoutFunction() with this command, as a result the following text will be printed to the console:

Text: Hello World

You can add more attributes to the ConsoleCommand, by using the command-chain feature of SetConsoleCommand(). For example like this:

SetConsoleCommand("cout", &myCoutFunction)
    .addGroup("output", "text")
    .accessLevel(AccessLevel::Offline)
    .defaultValues("no text");

Open the shell again and try it:

$ cout Hello World
Text: Hello World
$ output text Hello World
Text: Hello World
$ cout
Text: no text

If you execute it online (note: the access level is "Offline"), you will see the following (or something similar):

$ cout Hello World
Error: Can't execute command "cout", access denied.

If a command is executed, the arguments are passed to an underlying function, whitch is wrapped by an orxonox::Functor which again is wrapped by an orxonox::Executor. The Functor contains the function-pointer, as well as the object-pointer in case of a non-static member-function. The executor stores possible default-values for each argument of the function.

The function of a command can be changed at any time. It's possible to just exchange the function-pointer of the underlying Functor if the headers of the functions are exactly the same. But you can also exchange the Functor itself or even completely replace the Executor. Also the other attributes of a ConsoleCommand can be modified during the game, for example it can be activated or deactivated.

To do so, the function ModifyConsoleCommand() has to be used. It returns an instance of orxonox::ConsoleCommand::ConsoleCommandManipulator which has an interface similar to orxonox::ConsoleCommand, but with slight differences. You can use it the same way like SetConsoleCommand(), meaning you can use command-chains to change different attributes at the same time. ModifyConsoleCommand() must not be executed statically, but rather in a function at some point of the execution of the program.

Example:

void myOtherCoutFunction(const std::string& text)                       // Define a new static function
{
    orxout() << "Uppercase: " << getUppercase(text) << endl;            // Print the text in uppercase to the console
}

{
    // ...                                                              // somewhere in the code

    ModifyConsoleCommand("cout").setFunction(&myOtherCoutFunction);     // Modify the underlying function of the command

    // ...
}

If you now enter the command into the shell, you'll see a different behavior:

$ cout Hello World
Uppercase: HELLO WORLD
$ cout
Uppercase: NO TEXT

A few important notes about changing functions:

Instead of changing the function with setFunction(), you can also create a command-stack by using pushFunction() and popFunction(). It's important to note a few things about that, because the underlying structure of Executor and Functor has a few pitfalls:

• If you push a new function-pointer, the same executor as before will be used (and, if the headers match, even the same functor can be used, which is very fast)
• If you push a new Functor, the same executor as before will be used
• If you push a new Executor, everything is changed

Note that the executor contains the default values, so if you just exchange the Functor, the default values remain the same. However if you decide to change the default values at any point of the stack, this will also change the default values on all other stack-levels that share the same executor. If you don't like this behavior, you have to explicitly push a new executor before changing the default values, either by calling pushFunction(executor) or by calling pushFunction(void) which pushes a copy of the current executor to the stack.

Another important point are object pointers in case of non-static member-functions. Whenever you set or push a new function, you must add the object pointer again because objects are stored in the Functor which is usually exchanged if you change the function.

You can also use a stack for objects, but note that this object-stack is different for each function - so if you set a new function, the object-stack will be cleared. If you push a new function, the old object-stack is stored in the stack, so it can be restored if you pop the function.

DeclareConsoleCommand():

Appart from SetConsoleCommand() you can also call DeclareConsoleCommand(). In contrast to SetConsoleCommand(), this doesn't assign a function to the command. Indeed you have to pass a function-pointer to DeclareConsoleCommand(), but it is only used to determine the header of the future command-function. This allows to declare a command statically, thus it's possible to evaluate key-bindings of this command, but the actual function can be assigned at a later point.

Example:

DeclareConsoleCommand("cout", &prototype::void__string);

If you try to execute the command now, you see the following (or something similar):

$ cout Hello World
Error: Can't execute command "cout", command is not active.

You first have to assign a function to use the command:

{
    // ...

    ModifyConsoleCommand("cout").setFunction(&myCoutFunction);

    // ...
}

Now you can use it:

$ cout Hello World
Text: Hello World

Note that the initial function prototype::void__string is defined in the namespace orxonox::prototype. If there's no function with the desired header, you can extend the collection of functions or simply use another function that has the same header.

Macro Definition Documentation

#define DeclareConsoleCommand

(

...

)

BOOST_PP_EXPAND(BOOST_PP_CAT(DeclareConsoleCommand, ORXONOX_VA_NARGS(__VA_ARGS__))(__VA_ARGS__))

Declares a console command.

The macro is overloaded for 2-3 parameters.

This is an overloaded macro. Depending on the number of arguments a different overloaded implementation of the macro will be chosen.

Console commands created with DeclareConsoleCommand() don't use the the given function-pointer to execute the command, it is only used to define the header of the future command-function. The command is inactive until you manually set a function with orxonox::ModifyConsoleCommand(). You can use a different function-pointer than in the final command, as long as it has the same header.

#define DeclareConsoleCommand2	(		name,
			functionpointer
	)		DeclareConsoleCommandGeneric("", name, orxonox::createFunctor(functionpointer))

This macro is executed if you call DeclareConsoleCommand() with 2 arguments.

Parameters

name	The name (string) of the console command
functionpointer	The function-pointer of an arbitrary function that has the same header as the final function

#define DeclareConsoleCommand3	(		group,
			name,
			functionpointer
	)		DeclareConsoleCommandGeneric(group, name, orxonox::createFunctor(functionpointer))

This macro is executed if you call DeclareConsoleCommand() with 3 arguments.

Parameters

group	The group (string) of the console command
name	The name (string) of the console command
functionpointer	The function-pointer of an arbitrary function that has the same header as the final function

#define DeclareConsoleCommandGeneric	(		group,
			name,
			functor
	)

Value:

static orxonox::ConsoleCommand& BOOST_PP_CAT(__consolecommand_, __UNIQUE_NUMBER__) \
        = (new orxonox::SI_CC(new orxonox::ConsoleCommand(group, name, orxonox::createExecutor(functor), false)))->getCommand()

Internal macro.

#define SetConsoleCommand

(

...

)

BOOST_PP_EXPAND(BOOST_PP_CAT(SetConsoleCommand, ORXONOX_VA_NARGS(__VA_ARGS__))(__VA_ARGS__))

Defines a console command.

The macro is overloaded for 2-4 parameters.

This is an overloaded macro. Depending on the number of arguments a different overloaded implementation of the macro will be chosen.

Console commands created with SetConsoleCommand() become active immediately and the given function-pointer (and optionally the object) will be used to execute the command.

#define SetConsoleCommand2	(		name,
			functionpointer
	)		SetConsoleCommandGeneric("", name, orxonox::createFunctor(functionpointer))

This macro is executed if you call SetConsoleCommand() with 2 arguments.

Parameters

name	The name (string) of the console command
functionpointer	The function-pointer of the corresponding command-function

#define SetConsoleCommand3	(		group,
			name,
			functionpointer
	)		SetConsoleCommandGeneric(group, name, orxonox::createFunctor(functionpointer))

This macro is executed if you call SetConsoleCommand() with 3 arguments.

Parameters

group	The group (string) of the console command
name	The name (string) of the console command
functionpointer	The function-pointer of the corresponding command-function

#define SetConsoleCommand4	(		group,
			name,
			functionpointer,
			object
	)		SetConsoleCommandGeneric(group, name, orxonox::createFunctor(functionpointer, object))

This macro is executed if you call SetConsoleCommand() with 4 arguments.

Parameters

group	The group (string) of the console command
name	The name (string) of the console command
functionpointer	The function-pointer of the corresponding command-function
object	The object that will be assigned to the command. Used for member-functions.

#define SetConsoleCommandGeneric	(		group,
			name,
			functor
	)

Value:

static orxonox::ConsoleCommand& BOOST_PP_CAT(__consolecommand_, __UNIQUE_NUMBER__) \
        = (new orxonox::SI_CC(new orxonox::ConsoleCommand(group, name, orxonox::createExecutor(functor))))->getCommand()

Internal macro.