NSPR 2.0: Command line option processing

The Mozilla Organization
	At A Glance
	Feedback
	Get Involved
	Newsgroups
	License Terms
	Newsbot

Developer Docs
	Roadmap
	Projects
	Ports
	Module Owners
	Hacking
	Get the Source
	Build It

Testing
	Download
	Bugzilla
	Bug Writing

Tools
	View Source
	Tree Status
	New Checkins
	Submit A Bug

FAQ
Search

NSPR 2.0: Command line option processing

NSPR provides a mechanism to process command line options. This facility is similar to that available on many UNIX platforms known as getopt(see UNIX man getopt). The NSPR version of this capability allows processing based on the standard C language main() function definition's argc and argv. There are no modifications to values of those symbols during the processing.

The syntax of the command line is generically as follows:

> command -abc value naked -xyz

In this example, 'a', 'b', 'c', 'x', 'y' and 'z' are options. "abc" are clustered behind a single '-' as are "xyz". This command line is identical in semantics to

> command -a -b -c value naked -x -y -z

The string "value" is associated with the option 'c'. The options 'a', 'b', 'x', 'y' and 'z' have no associated values.
The token "naked" is not associated with any option (and is therefore naked). Any number of naked values may be included in the command line. Since they have no known option association, they are position dependent, but none the less, useful.

An object is created by the client to hold the state of the options processing. Sharing that handle with other threads may produce non-deterministic results. Having multiple such state objects, each accessed by a different thread, is supported (though we struggle for a reason why).

PLOptState *PL_CreateOptState(
    PRIntn argc, char **argv, const char *options);

If the function fails to return a valid handle the reason for the failure will be contained in the calling thread's error structure (see PR_GetError()). A non-NULL return pointer will point to an object of type PLOptState. The pointer will remain valid until it is destroyed by calling PL_DestroyOptState() and is required for all subsequent processing.

`argc`	The number of arguments on the command line. This is the same value as that the C program's `main()` function argument, `argc`.
`argv`	The pointer to a vector of strings that represent the arguments provided on the command line. For instance, `argv[0`] is a string representation of the program's execution name.
`options`	The string that defines the options expected on the command line. All options are single characters and case sensitive. If an option has an associated value, the option identifier must be followed by a ':' in the options string.

Given the example cited earlier for the command line, a complete options list to parse the command line might be written as "ABC:XYZ". The order of specification of the options strings to PL_CreateOptState() is not significant. The order that the options are specified on the command line may be, particularly if one is using naked values.

typedef struct PLOptState
{
    char option;
    const char *value;
    PLOptionInternal *internal;
} PLOptState;

The object PLOptState not only allows the implementation to record the progress of the processing, it is also used as the area where the majority of the results are made available to the client. The actual value returned from the option processing function only indicates the validity of the values stored in this object.

`option`	The value of the option on the command line just processed. Processing of the command line progresses from left to right. The value of this field will be either one of those specified in the options string of `PL_CreateOptState` a nul (0) if the option is naked.
`value`	This field contains the option's associated value or `NULL` if the option has no associated value.
`internal`	A reference to the implementation's private (and opaque) state processing object.

The PL_CreateOptState function returns one of three values from the enumerated byte PLOptStatus.

typedef enum {PL_OPT_OK, PL_OPT_EOL, PL_OPT_BAD } PLOptStatus;

`PL_OPT_OK`	The processing completed normally.
`PL_OPT_EOL`	All the tokens from the command line have been processed.
`PL_OPT_BAD`	The option is invalid.

Once the options processing has run to completion, the state object allocated by PL_CreateOptState() must be dismissed. That is accomplished by calling DestroyOptState().

void PL_DestroyOptState(PLOptState *opt);

Last updated: Tue Mar 10 10:02:19 PST 1998