Command Line Parser

The PFC class commandLineParser can be used to deal with command line arguments.

Example
This little code fragment (from the accompanying demo program) shows the basic operation:

class facts test1 : boolean := false. test2 : boolean := false.

clauses run :- CLP = commandLineParser::new, CLP:addOption_help("-help"), CLP:addOption_0("-test1", "Run test1", { :- test1 := true }), CLP:addOption_0("-test2", "Run test2", { :- test2 := true }), if some(ErrorMessage) = CLP:parse then write(ErrorMessage) else % command line parsed successfully run2(CLP) end if.

Your program:
 * creates an instance of the commandLineParser class
 * define the options your program accept
 * invoke the parse predicate
 * handle errors or continues with normal operation

The parser cannot only parse the command line it can (and will) also format a help description. If you invoke the program with the help option (which is defined to be "-help" in the demo) you will receive a description like this (as an error text):

The program description will by default be taken from the programs version info resource.

Defining and handling options
You define options with the predicates adoption_0, , and :

CLP:addOption_2("-user", "Username and password", "Username", "Password", mkHandler_2("user")),

You state
 * the option
 * a description
 * names of formal parameters, and
 * a callback predicate

The callback is invoked when the parser parse the corresponding option. The callback receives the actual parameters from the command line as arguments.

Callbacks will be invoked in the order corresponding to the command line (left-to-right).

Handling regular arguments
Arguments that are not part of options can be handled in two different ways.

The commandLineParser object have an arguments property, which (after parsing) contains all the arguments (left-to-right) that are not part of options.

You can also set the onRegular property to a callback that will be invoked when a regular (i.e. non-option) argument is meet (left-to-right).

Using onRegular and the options callbacks you can deal with the sequence of options:

Assuming that –log and –nolog are zero arguments options you will receive the following callback sequence:

onRegular("xxx.txt") onLog onRegular("yyy.txt") onNolog onRegular("zzz.txt")

so logging can be active for yyy.txt, but not for the other two files.

Command files
An argument of the form @ (e.g. "@My Commands.txt") will cause the command line parser to read the and parse its contents as command line arguments. After that it will continue parsing the remainder of the original command line.

optionChar
By default options follow the "Unix style" with '-' (minus) as option indicator, but you can set the optionChar property to another char (we only recommend '/' (for the "Windows style" options)) which will then be the option indicator:

clauses run :- CLP = commandLineParser::new, CLP:description := "Demo of '/' options", CLP:onRegular := mkHandler_1("regular"), CLP:optionChar := '/', CLP:addOption_help("/?"), CLP:addOption_0("/t", "Run in test mode",mkHandler_0("test")), CLP:addOption_1("/f", "The file to process", "File", mkHandler_1("file")), CLP:addOption_2("/u", "Username and password", "Username", "Password", mkHandler_2("user")), ...

Notice that all arguments that start with the optionChar treated as options and will give an error if they are not really an option:

Sanity Checks
The commandLineParser will raise exceptions if you register the same option twice (also if it have different number of arguments). It will also validate that added options starts with the optionChar. (Changing optionChar and adding options with different option indicators will give bad results).

Double Quotes
In hope of being compatible with cmd.exe and thus cmd/bat scripts the commandLineParser uses CommandLineToArgvW to do the actual parsing, especially the handling of double quote ("). By default the parser splits arguments at the space character, but double quotes can be used to create arguments with space in.

The parser will treat this as a single argument without any quotes: filename with spaces.txt. I.e. the quotes are removed by the parser.

For a detailed description of quote handling please read the MSDN documentation CommandLineToArgvW including the user comments.