cmdscan.h

This interface exports a simple command-line scanner.
Types
CommandScanner The CommandScanner type offers a simple command-scanning abstraction that is primarily used to construct test programs.
CommandFn This type represents the space of functions that can be used as commands.
Functions
newCommandScanner() Allocates a new command scanner.
freeCommandScanner(cs) Frees the specified command scanner.
defineCommand(cs, cmdName, cmdFn) Adds an entry to the internal command table for the command scanner by associating the specified command name with the corresponding function.
commandLoop(cs, prompt) Executes a loop that reads and executes commands from the user.
executeCommand(cs, line) Executes a command line as if it were entered by the user.
setCommandData(cs, data) Associates a data block with the command scanner.
getCommandData(cs) Returns the data block associated with the command scanner.
readCommandToken(cs) Reads the next token from the command line, which is returned as a string.
getCommandLine(cs) Returns the current command line.
getCommandName(cs) Returns the current command name.
getTokenScanner(cs) Returns the TokenScanner used internally to parse tokens.
quitCommand() This callback function exits from the command scanner.

Type detail

typedef struct CommandScannerCDT *CommandScanner;
The CommandScanner type offers a simple command-scanning abstraction that is primarily used to construct test programs. The typical pattern of use requires the following steps:
  1. Call newCommandScanner to create an empty command scanner.
  2. Call defineCommand to associate commands with functions.
  3. Call commandLoop to execute a command loop.
Command scanners are implemented as a collection type, so that iterating over the scanner returns the name of each command in lexicographic order. 
typedef void CommandFn(*CommandFn)(CommandScanner cs);
This type represents the space of functions that can be used as commands. Each command takes the entire command scanner as an argument, which gives the callback function access to the various data fields associated with the scanner.

Function detail

CommandScanner newCommandScanner(void);
Allocates a new command scanner.

Usage:

cs = newCommandScanner();

void freeCommandScanner(CommandScanner cs);
Frees the specified command scanner.

Usage:

freeCommandScanner(cs);

void defineCommand(CommandScanner cs, string cmdName, CommandFn cmdFn);
Adds an entry to the internal command table for the command scanner by associating the specified command name with the corresponding function.

Usage:

defineCommand(cs, cmdName, cmdFn);

void commandLoop(CommandScanner cs, string prompt);
Executes a loop that reads and executes commands from the user. On each cycle, commandLoop performs the following operations:

  1. Prints the specified prompt
  2. Reads in a line from the user
  3. Checks to see if the first token on the line is a command
  4. Executes the function associated with that command

If a command is undefined, commandLoop displays a message to that effect and allows the user to enter a new command. If any errors occur in the command processing, they are caught by the command loop.

Usage:

commandLoop(cs, prompt);

bool executeCommand(CommandScanner cs, string line);
Executes a command line as if it were entered by the user. The function returns true if the command is defined, and false otherwise.

Usage:

ok = executeCommand(cs, line);

void setCommandData(CommandScanner cs, void *data);
Associates a data block with the command scanner. The pointer to the data block is passed to the callback functions for the various commands.

Usage:

setCommandData(cs, data);

void *getCommandData(CommandScanner cs);
Returns the data block associated with the command scanner.

Usage:

data = getCommandData(cs);

string readCommandToken(CommandScanner cs);
Reads the next token from the command line, which is returned as a string. If no more tokens exist, readCommandToken returns the empty string.

Usage:

token = readCommandToken(cs);

string getCommandLine(CommandScanner cs);
Returns the current command line.

Usage:

line = getCommandLine(cs);

string getCommandName(CommandScanner cs);
Returns the current command name.

Usage:

name = getCommandName(cs);

TokenScanner getTokenScanner(CommandScanner cs);
Returns the TokenScanner used internally to parse tokens.

Usage:

scanner = getTokenScanner(cs);

void quitCommand(CommandScanner cs);
This callback function exits from the command scanner.

Usage:

defineCommand(cs, "quit", quitCommand);