NAME

parser − command parser

SYNOPSIS

#include <saio/parser.h>

command_parser(cmd_table, prompt, search_path)
struct cmd_table *cmd_table;
char *prompt;
int search_path;

DESCRIPTION

Command_parser provides a general command line parser that may be used by any standalone program.  Using the command parser helps insure a consistent user interface among standalone programs.  The command parser reads from the system console and calls appropriate routines which implement commands as directed by a table passed to the parser when it is invoked. 

Cmd_table is a pointer to the first entry an array of struct Struct cmd_table has the following definition:

struct cmd_table {
char *ct_string;/* command name */
int (*ct_routine)();/* implementing routine */
char *ct_usage;/* syntax */
};

The fields of this structure have the following usage:

ct_string This character pointer points to a null terminated string which is the name of the command as it should be recognized on a command line.  The command name is the first word from the user-entered command. 

ct_routine This field is a pointer to a routine which implements the command.  This routine will be called when the command is recognized by the parser.  The routine will be called with two arguments as follows:

(*ct_routine)(argc, argv)
int argc;
char **argv;

Argc is the count of arguments on the command line, including the command name.  Argv is a pointer to a null-terminated array of null-terminated strings; each string is an argument from the command line.  The first string in the argv array is the command name.  The routine should return 1 if it desires to have the "usage" string (ct_usage) printed, and 0 otherwise. 

ct_usage This character pointer points to a string which describes the syntax for invoking the command.  This string is printed if the command routine returns non-zero or by the standard command help (described below). 

The second argument, prompt, is a pointer to a null-terminated string that will be printed as a prompt. The third argument affects the behavior of the command parser if the command entered by the user is not found in the command table passed to the command parser. If search_path, is non-zero the command_parser will attempt to load the file from each of the devices listed in the environment variable $path until the command is successfully loaded or the list exhausted. 

A standard command, help, is provided with the parser.  The help command when invoked by the user prints the usage lines for all commands passed to it as arguments, if no arguments are passed to help it prints all usage lines in the cmd_table. An appropriate cmd_table entry for the help command is:
extern int help(); { "help",help,"help:   help [COMMANDLIST] },

BUGS

This section man page should be called command_parser.3.