Chapter 1: Base Application Classes



1.1: General Application

WBA_Application provides standard semantics for well-behaved applications. This is an abstract base class and must be extended prior to use.


A WBA_Application provides the following benefits:


A WBA_Application by default sets its logger to the global logger which is accessible through the macro GPL_LOGGER.


A WBA_Application by default sets its environment to the global environment WBA_ENV.


Virtual functions are provided as an interface for program name, version, build id, and usage. Derived classes should provide their own versions of GetName(), GetVersion(), GetParameterUsage(), and Process().


The member function Printf() provides a functionality similar to printf(3). However, Printf() make use of the osdOutput functionality in sending output to stderr. See osdOutput for details.


The base class WBA_Application provides execution semantics in the form of the following algorithm:

  1. Initialize()
  2. Process()
  3. Finalize()
The member virtual function Initialize() should be used for application initialization. The member virtual function Process() should be used for the main application functionality. The member virtual function Finalize() should be used for application finalization. The member function Exit() is also provided for premature but graceful exits.



1.1.1: Static Data and Convenience Macros

The macro WBA_APP depends on the existence of an application. However, they are also intended for use from anywhere in user application code. This makes it necessary to have the notion of a global way for code to reference an application. Hence WBA_Application registers itself with a global static pointer upon construction. Note that this means WBA_APP is invalid until a WBA_Application is created.




1.2: Daemon

WBA_Daemon is derived from WBA_Application and adds daemon-like semantics such as detaching from its parent. The virtual function Daemonize() is added and should only need to be overridden for specialized daemonization behavior. The execution semantics for a WBA_Daemon take the form of the following algorithm:
  1. Daemonize()
  2. Initialize()
  3. repeat Process() until SetContinueProcessing(FALSE) is called.
  4. Finalize()



1.3: Shell

WBA_Shell is derived from WBA_Application and adds shell semantics such as prompts and commands. The execution semantics for a WBA_Shell take the form of the following algorithm:
  1. Initialize()
  2. repeat until DoneProcessing() is called.
    1. print prompt
    2. get line of input
    3. check for command
    4. Process()
  3. Finalize()


When WBA_Shell checks a line of input for a command it checks to see if the first word matches a known command handler. If so the handler's HandleCommand() member function is called. Command handlers are classes in their own right and are derived from WBA_CommandHandler. Handlers are added and removed from a shell with the member functions AddCommand() and RemoveCommand().



1.3.1: WBA_CommandHandler

This is the base class for WBA_Shell commands. It provides uniform semantics to shell commands in a similar manner to the way WBA_Application provides uniform semantics to executables.


When a WBA_Shell processes a line it attempts to find a handler that has a name that matches the first word on the input line. The name(s) of a WBA_CommandHandler are the elements of WBA_CommandHandler::names which is an array of GPL_String objects.


If a match is found the handler's HandleCommand() member function is called with all the words of the input line put in the data member arguments.


Command handlers also have the notion of being hidden. A hidden command handler will not be listed in the help overview printed out by the command handler WBA_CommandHelp. This is useful when undocumented commands are desired so as to keep the apparent interface of a shell as simple as possible.



1.3.2: WBA Provided Command Handlers

This is a brief overview of some commands available from WBA. For up to date details on a particular command simply add the command to your shell along with the help command and then use the help command from within your shell. Otherwise, just look in wba/shell.h.




1.3.2.1: quit

WBA_CommandQuit calls DoneProcessing() to end execution of the shell. To add to your shell do
wba_shell_ptr->AddCommand(new WBA_CommandQuit());

1.3.2.2: echomode

WBA_CommandEchoMode sets the echo mode of the shell. If echo mode is on all commands will be echoed to the terminal. To add to your shell do
wba_shell_ptr->AddCommand(new WBA_CommandEchoMode());

1.3.2.3: interpremode

WBA_CommandInterpretMode sets the interpret mode of the shell. If it is on then the shell will interpret each input line with its WBA_LineInterpreter. See WBA_Shell::SetLineInterpreter(). To add to your shell do
wba_shell_ptr->AddCommand(new WBA_CommandInterpretMode());

1.3.2.4: echo

WBA_CommandEcho echos the rest of the line back to the terminal. To add to your shell do
wba_shell_ptr->AddCommand(new WBA_CommandEcho());

1.3.2.5: help

WBA_CommandHelp prints either an overview of all commands or details on specific commands. The overview is printed when no arguments are provided, otherwise help on the commands specified by the arguments is printed. To add to your shell do
wba_shell_ptr->AddCommand(new WBA_CommandHelp());

1.3.2.6: map

WBA_CommandSetMap actually creates a new command handler with the name of the first argument. The remaining arguments become the command line that is input every time the new command handler is run. To add to your shell do
wba_shell_ptr->AddCommand(new WBA_CommandSetMap());

1.3.2.7: include

WBA_CommandInclude includes a file. Every line in the file is processed as a line of input. To add to your shell do
wba_shell_ptr->AddCommand(new WBA_CommandInclude());