SHELL

The Shell is an extension to 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,… ]]
      — ≠ MUST BE
      — [] optional, depending on the circumstances
      — [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);

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"
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:

#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

• Text? → Element2D? → BaseObject?
• EvenentListener (for input)
• ClassList? (List)

Responsible

bensch (see source for email)