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):

>cmdLineDemo.exe -help
cmdLineDemo.exe - Command Line Parser Demo
 
Usage:
 
    cmdLineDemo.exe [options] arguments
 
Options:
 
   -help        Displays the help message
   -test1       Run test1
   -test2       Run test2

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, <vp..._1</vp>, and <vp..._2</vp>:

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:

myProgram xxx.txt –log yyy.txt –nolog zzz.txt

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 @<file> (e.g. "@My Commands.txt") will cause the command line parser to read the <file> 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:

>program.exe /myfile.txt
 
Unknown option /myfile.txt

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.

program "filename with spaces.txt"

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.