42.12. $nextCommandLineArg

$nextCommandLineArg is useful for processing command line arguments that may contain null (empty) arguments or arguments that contain whitespace characters.

If an argument contains blanks, tabs, or end-of-line or end-of-page characters, it must be enclosed in double quotes (it can be enclosed in double quotes even if it does not contain blank space). Double quotes inside a quoted argument must be doubled, as in a MAINSAIL STRING constant. Null arguments are specified as a pair of double quotes (like the MAINSAIL null STRING). In the absence of quotes, each argument is considered to be delimited by blank space (blanks or tabs).

For example, the following line consists of three arguments:

abc "" def

but the following consists of only one:

"abc """" def"

$nextCommandLineArg gets the next argument from a command STRING, e.g., as obtained from $getCommandLine.

If commandLine contains no arguments, $nextCommandLineArg returns FALSE. Otherwise, it parses and removes the next argument from commandLine, producing it in nextArg.

The only valid bit in ctrlBits is errorOK; if specified, it suppresses any error message that might otherwise be issued during parsing.

$lastCommandLineArg may be used to remove an argument from the end of a command line instead of from the beginning.