= SHELL =
[[ArchivePage]]

The Shell is an extension to [source:/trunk/src/defs/debug.h debug.h], that allows
the output to be redirected to an opengl shell ontop of an application (orxonox). It is bidirectional to enable the user to
send commands to the application.

== Structure ==

http://www.orxonox.net/additionals/Shell.png

 * __Application__:
   * The Shell is communicating with the application (namely orxonox) through debug.h. E.g. all output can be redirected to the Shell's Buffer.
   * Commands can be executed, and the result is sent back to the application via Shell's Commands.
 * __Shell Input__:
   * Gets input from the user keyboard.
   * Command completion: on <TAB> the shell tries to complete either Classes, Objects or Commands
   * The input is structured as follows:
     * <Class> [Object] <functionCall> [argument1,[argument2,... ]] [[br]]
      -- <> MUST BE [[br]]
      -- [] optional, depending on the circumstances [[br]]
      -- [Object] must be defined, if there exist more than one instance of a certain Class.
 * __Display__:
   * Renders the Text to the screen (with a nice little background). This is not a Class itself, it is inside the Shell/Shell's Input.
 * __Shell Command__:
   * An entered Shell Command will be checked for integrity, quality attributes:
     1. Does an instance of the class exist?
     2. More than one -> object required!
     3. Does the function Exist
     4. Are any parameters supplied?
     5. Execute command


== Usage ==
Create a new Command: nothing easier than this, here an example:
Use the makro function SHELL_COMMENAD(argumen1, argument2, argument3)->describe(argument4);
{{{
#!cpp
SHELL_COMMAND(clear, Shell, clearShell)
   ->describe("Clears the shell's Buffer")
   ->setAlias("clear");
}}}
 * Argument 1: the name of the command in the shell (this is what you will enter in the shell), without "" (e.g. clear)
 * Argument 2: the name of the class that executes the command, without "" (e.g. Shell)
 * Argument 3: the name of the function (without any arguments) to execute on this command (e.g. clearShell)
 * Argument 4: (optional) add a little description: a nice little text for the help screen.
 * Argument 5: (optional) adds an Alias to this command, that can be used insted of ex. 'Shell clear'

To use the command: In the Shell type: "Shell clear" or "clear" [[br]]
This will execute the function Shell->clearShell(), which will clear the shell buffer.
As you may have noticed, the Names are !!NOT!! concatenated with any "", this is because the above mentioned method uses a MACRO to register the Command. Further, it is important to note, that {{{SHELL_COMMAND(...)}}} is not an object function, it is actually called within the class.


Background Knowledge: the macro unrolled:
{{{
#!cpp
#define SHELL_COMMAND(command, class, function) \
        ShellCommandBase* shell_command_##class##_##command = \
         ShellCommand<class>::registerCommand(#command, #class, &class::function)

/* MEANING:
   ShellCommandBase* someUniqueVarName = 
         ShellCommand<ClassName>::registerCommand("commandNameInShell", "ClassName", &ClassName::FunctionToCall);
*/
}}}
This can also be called with arguments, for default values (##FIXME##)


== Dependencies ==
  * [wiki:archive/TextEngine Text] -> [wiki:archive/Element2D Element2D] -> [wiki:archive/BaseObject BaseObject]
  * [wiki:archive/EventHandler EventHandler] (for input)
  * [wiki:archive/ClassList ClassList] (List)

== Responsible ==
  bensch (see source for email)