View source for Command Line Parser

From wiki.visual-prolog.com
You do not have permission to edit this page, for the following reasons:
The action you have requested is limited to users in the group: emailconfirmed.
You must confirm your email address before editing pages. Please set and validate your email address through your user preferences.
You can view and copy the source of this page.
The PFC class <vp>commandLineParser</vp> can be used to deal with command line arguments.

==== Example ====

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

<vip>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.</vip>

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

<source lang="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</source>

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

==== Defining and handling options ====

You define options with the predicates <vp>adoption_0</vp>, <vp..._1</vp>, and <vp..._2</vp>:

<vip>CLP:addOption_2("-user", "Username and password", "Username", "Password", mkHandler_2("user")),</vip>

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:

<source lang="text">myProgram xxx.txt –log yyy.txt –nolog zzz.txt</source>

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

<vip>onRegular("xxx.txt")
onLog()
onRegular("yyy.txt")
onNolog()
onRegular("zzz.txt")</vip>

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 <vp>optionChar</vp> property to another char (we only recommend '/' (for the "Windows style" options)) which will then be the option indicator:

<vip>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")),
        ...</vip>

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

<source lang="text">>program.exe /myfile.txt

Unknown option /myfile.txt</source>

==== 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 <vp>commandLineParser</vp> uses [http://msdn.microsoft.com/en-us/library/windows/desktop/bb776391(v=vs.85).aspx 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.

<source lang="text">program "filename with spaces.txt"</source>

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 [http://msdn.microsoft.com/en-us/library/windows/desktop/bb776391(v=vs.85).aspx CommandLineToArgvW] including the user comments.


[[Category:Tutorials]]
Return to Command Line Parser.
Retrieved from "https://wiki.visual-prolog.com/index.php?title=Command_Line_Parser"
View source for Command Line Parser

Search

Navigation

external links

collaboration

Personal tools

Views
