Parse command-line options
The principal routine of this file,
parses and removes the processing options specified on a command line.
It is designed to work in concert with the
ParseOptions loops through all the argv entries (ignoring argv). It stops the loop in three cases.
- The end of the argv array is reached.
- The argv value does not begin with a hyphen (-)
- The argv value consists only of a single hyphen (which is assumed to represent standard input as the "file")
On each pass of the loop, ParseOptions() calls the callback function, passing it the current argc value and a modified argv array. argv is set to the caller argument passed to ParseOptions. This allows the callback function to display more meaningful messages. argv is always set to the current position in the argv array, whether it is at the beginning of an original argv value or somewhere in the middle of one (this is the case when several single-character options can be collected into one string). ParseOptions always sets the first character of argv to be a hyphen.
It is the responsibility of the callback routine to advance the argv pointer. This allows the callback routine to determine what is the legitimate format for an option, i.e.
- whether single-character options can occur in one string starting with a hyphen
- whether an option can take one or more option values
- whether those option values need to be separated from the option specifier by white space
ParseOptions() manipulates the argv array. It sets the argv value to the caller argument and also modifies argv as the callback routine processes its values. It keeps the argc count in sync with argv and uses the new argc value as its return value. The array pointed to by argv is modified; all options are removed leaving only filename strings in the array for filter() to handle.
If the callback routine detects an error it should return a NULL pointer to indicate this. ParseOptions() will then print an error message and return 0 (which is not a legitimate value for argc).