Museum

PARSER(3spp)       Systems Programmer's Manual       PARSER(3spp)



NAME
     parser - command parser

SYNOPSIS
     #include <saio/parser.h>

     int 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 ensure a consistent user interface among stan-
     dalone programs.  The command parser reads from the system
     console and calls appropriate routines, which implement com-
     mands 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 ter-
                    minated string that is the name of the com-
                    mand 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 that
                    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 argu-
                    ment 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.



                         Printed 1/6/92 standalone library Page 1

PARSER(3spp)       Systems Programmer's Manual       PARSER(3spp)



     ct_usage       This character pointer points to a string
                    that describes the syntax for invoking the
                    command.  This string is printed if the com-
                    mand routine returns non-zero or by the stan-
                    dard 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 com-
     mand is:
          extern int help();

          { "help", help,     "help":   help [COMMANDLIST] },

BUGS
     This section man page should be called command_parser.3.



























standalone library Page 2Printed 1/6/92