Synopsis

PDX_MSGT ugn_ParseCommandLine(long option, UGN_OPTS *opts, int *argc, char *argv[])

Purpose

Parse command line options

Description

This function parses command line options according to a specification provided in the opts structure. The command line options must all start with a dash ("-") character. The parser operates by comparing each option in the argv array to the list of supported options in the opts structure. When a match is found, the value (if any) for the option is parsed and stored in a variable specified in the opts structure. If an option is specified twice, an error will be reported. Parsing will continue until an argument is found which does not start with a dash or the end of the argv array is found. At this point, any remaining arguments in argv will be moved to argv[1], the program name will be left in argv[0], and argc will be updated accordingly.

The opts structure contains entries for each command line option. The typedef of the structure and description of each field follows:

.nf typedef struct { char *name; char *type; char *val_name; void *variable; char *desc; } .fi .IP name 9 Contains the name of the option (without a leading dash). The name is case-sensitive and must consist of alphanumeric characters. The end of the opts structure is marked by an option name of NULL and the other fields in the entry are ignored. Groups of options can be specified using the special names "[" and "]". All options defined between the "[" and "]" entries are considered group and an error is generated if more than one is specified in the argv array. When name is "[" or "]", the other fields in the entry are ignored.

.IP type Defines the data type of the option. It is specified as a string containing a letter key from the list below:

.RS 12 .IP d 4 double .IP f flag (no value specified) .IP i integer .IP l long integer .IP m MDA_PTR specified in the form #:# to specify both a model and index or just # to only specify an index (the returned MDA_PTR will have a model number of MDA_NULL_MODEL). .IP s string .IP t DDF_TF specified in the form #:# .LP .RE .RS 9 If the letter is followed by a plus ("+") character, the option is considered "required" and an error will be issued if it is not found. For clarity when calling ugn_PrintUsage, required options should be defined first in the opts structure. Options in an option group can not be marked as required. .RE

.IP val_name Contains the name used for the value place holder when printing the usage statement. For "f" type fields the field may be NULL.

.IP variable Contains the address of the variable which will be set to the value of the option. For "f" type fields, variable must be the address of a PDX_BOOL. For "s" type fields, variable must be the address of a char *. For the other types of fields, variable is the address of an appropriately typed variable.

If the variable field is NULL, the option will not be parsed. This can be used to support options which you want ugn_ParseCommandLine to ignore (such as those which may be repeated on the command line) by preserving the options in argv for the caller to process. .IP desc The desc field specifies a short (typically 50 characters or less) description of the field which is used when printing the usage statement. No wrapping of the description is done so it is up to the caller to ensure that the desc field is not too long. .LP

\fBExample\fR

.nf PDX_MSGT rc; static int debug = 0; static double tol = .001; static PDX_BOOL polyline = PDX_FALSE; static PDX_BOOL nurbs = PDX_FALSE; static PDX_BOOL help = PDX_FALSE;

static UGN_OPTS opts[] = { { "tol", "d+", "tolerance", &tol, "Tolerance" }, { "debug", "i", "dbg_level", &debug, "Debug level" }, { "help", "f", NULL, &help, "Print usage" }, { "[", NULL, NULL, NULL, NULL }, { "polyline", "f", NULL, &polyline, "Use polylines" }, { "nurbs", "f", NULL, &nurbs, "Use NURBS" }, { "]", NULL, NULL, NULL, NULL }, { NULL, NULL, NULL, NULL, NULL } }; static char *desc[] = { "This is the first line of the description for this sample.n", "And this is the second line.n", NULL }; . . . rc = ugn_ParseCommandLine (UGN_NOOPT, opts, &argc, argv); if (rc != UGN_NOERR || help) { ugn_PrintUsage (UGN_NOOPT, opts, argv[0], NULL, desc); } .fi

Input

option

Options (not used)

argc

Count of argument strings in argv

argv

Array of character strings for the command line arguments. The first argument is assumed to be the program name.

opts

Options specification structure

Output

argc

Possibly modified count of strings in argv

argv

Possibly modified array of arguments

Return

      UGN_OPTS_REPEATED_OPTION
      UGN_OPTS_VALUE_MISSING
      UGN_OPTS_ILLEGAL_TYPE
      UGN_OPTS_UNKNOWN_OPTION
      UGN_OPTS_INVALID_TF
      UGN_OPTS_INVALID_NAME
      UGN_OPTS_INVALID_TYPE
      UGN_OPTS_INVALID_GROUP
      UGN_OPTS_CONFLICT
      UGN_OPTS_REQUIRED_IN_GROUP
      UGN_OPTS_REQUIRED_NOT_FOUND
      Low level error return
      .fi