Index  |  Related pages  |  Classes  |  Functions  |  Entities  |  Function Sets  |  Groups

ClassCmdlineParser

class CmdlineParser

Provides simple and powerful parsing of the command line options. more...


Member list

Properties
lastParsed An integer representing the last item parsed in the argument array before exit the parsing loop.
Methods
expectValue Declares that current option needs a value.
onFree Called when the parser finds a free option.
onOption Called when the parser finds an option.
onSwitchOff Called when the parser finds a switch being turned off.
onValue Called when the parser finds a value for a given option.
parse Starts command line parsing.
terminate Requests the parser to terminate parsing.

Detailed description

Command line options are the simplest and most immediate mean to provide a stand-alone script with basic configuration, or to ask it to do something a bit more specific than just "operate".

Some embedding applications may provide the scripts with a command line too; in example, a "scanner" script in a FPS game may be provided with the objects to search for in a "command line", that may be actually the string that represents its configuration in the user interface.

Often, this important feature is neglected in scripts because bringing up a decent option parser is a bit of a nuisance, boring and repetitive, and above anything it may be considered a huge piece of code with respect to the needs of a simple script.

The CmdlineParser class, that is declared directly in the RTL module, provides a simple, efficient and flexible mean to implement command line option parsing that let on the script the essential duty to grab the given values and store them for later usage.

The command line parser knows the following option categories:

Short and long options may be parametric. The word (or string) following parametric option is considered the parameter of that option, and is not subject to parsing. In example, if "--terminator" is a parametric option, it is possible to write "./myprg.fal --terminator -opt". The parameter "-opt" will be passed as-is to the script as "terminator" option parameter. In case of short option chaining, if more than one chained option is parametric, the parameter following the chained options will be considered applied only to the last option, and the other ones will be ignored. If the sequence of parameters ends while waiting for the parameter of an option, the incomplete option is ignored.

On the script point of view, the parser can be configured by implementing callbacks in the CmdlineParser class. The parser will call the methods of the subclasses as it finds options in the argument vector; the callbacks will configure the application, report errors and mis-usage, terminate the program on fatal errors and communicate with the parser through member functions. In example, it is not necessary to declare in advance which are the parametric options; it's done on a per-option basis by calling the expectParam() method and returning to the parser.

To use this feature, it is just necessary to declare a subclass of CmdlineParser and instance it, or derive an object from it, and call the parse() method.

The CmdlineParser class is meant to be overloaded by scripts, so that the callbacks provided in the class can be called by the parse() method. Once called, parse() will scan the line and will call in turn onOption(), onFree() and onSwitchOff() callbacks, depending on what kind of arguments it finds in the argument list. If the parsed option should provide some value, the script implementing onOption() should call expectValue() and then return. The next element on the command line will be then passed to onValue(), which will receive the previously parsed option and the parsed value as parameters.

Calling the terminate() method from any callback routine will force parse() to terminate and pass the control back to the application. The last parsed element will be stored in the property lastParsed, that can be used as an index to read the args vector from the last parsed parameter.

Here is a working sample of implementation.

    object MyParser from CmdlineParser
 
       function onOption( option )
          switch option
             case "?", "help"
                self.usage()
             case "d", "m", "l", "long"
                // those options require a parameter; signal it
                self.expectValue()
             case "k"
                // set switch k ON
             case "n"
                // set switch n ON
             case "v", "version"
                // show version
             case "z", "sleep"
                self.terminate()
             default
                self.unrecognized( option )
          end
       end
 
       function onValue( option, value )
          switch option
             case "d"
                // set value for option d
             case "m"
                // set value for option m
             case "l", "long"
                // set value for option l
          end
          // can't be anything else, as this function call must
          // be authorized from onOption
       end
 
       function onFree( param )
          // record the free parameter
       end
 
       function onSwitchOff( sw )
          switch sw
             case "k"
                // set switch k OFF
             case "n"
                // set switch n OFF
             default
                self.unrecognized( sw )
          end
       end
 
       function unrecognized( option )
          // Signal some error
       end
 
       function usage()
          // say something relevant
       end
    end
 
    // And in the main program:
    MyParser.parse()

Notice: Callback methods in the instance are called in Virtual Machine atomic mode. The called methods cannot be interrupted by external kind requests, they won't honor periodic callback requests and and they will be forbidden to sleep or yield the execution to other coroutines. Parsing of the whole command line happens in an atomic context, so it's not possible to wait for other coroutines in anyone of the callback methods. It is also advisable that methods are simple and straight to the point to minimize the time in which the VM is unresponsive to kind requests and time scheduling.


Class properties

lastParsed
An integer representing the last item parsed in the argument array before exit the parsing loop.


Class methods

expectValue()

Declares that current option needs a value.

CmdlineParser.expectValue( )

This method is to be called only from the onOption callback. When called, it suggests the parser that the received option requires a parameter, that should immediately follow.

As the same option received by onOption() will be reported later on to onValue(), it is not necessary for the application to take note of the event. Simply, when receiving an option that needs a parameter, the application should call self.expectValue() and return.

onFree()

Called when the parser finds a free option.

CmdlineParser.onFree( opt )
opt

The free option being read.

This callback method gets called by parse() when a command line parameter not being bound with any option is found. The overloaded method should check for this value respecting the host program command line semantic. In case the free option cannot be accepted, the method should either signal error and exit the application, ignore it or set an error indicator and request the parser to terminate by calling terminate().

The parser won't signal error to the calling application, so, in case this free value cannot be accepted, an error state should be set in the application or in the parser object.

onOption()

Called when the parser finds an option.

CmdlineParser.onOption( opt )
opt

The option being read.

This callback method gets called by parse() when an option is found. The overloaded method should check for the option being valid; in case it is not valid, it may either signal error and exit the application, ignore it or set an error indicator and request the parser to terminate by calling terminate().

The parser won't signal error to the calling application, so, in case an invalid option is received, an error state should be set in the application or in the parser object.

If the incoming option requires a parameter, this callback should call expectOption() before returning.

onSwitchOff()

Called when the parser finds a switch being turned off.

CmdlineParser.onSwitchOff( opt )
opt

The switch being turned off.

This callback method gets called by parse() when a short option is immediately followed by a "-", indicating a "switch off" semantic.

The overloaded method should check for the option being valid and being possibly target of a "switch off"; if not, it may either signal error and exit the application, ignore it or set an error indicator and request the parser to terminate by calling terminate().

The parser won't signal error to the calling application, so, in case an invalid option is received, an error state should be set in the application or in the parser object.

onValue()

Called when the parser finds a value for a given option.

CmdlineParser.onValue( opt, value )
opt

The option being parsed.

value

The given value for that option.

This callback method gets called by parse() when the parameter for a parametric option is read. The overloaded method should check for the option being valid; in case it is not valid, it may either signal error and exit the application, ignore it or set an error indicator and request the parser to terminate by calling terminate().

The parser won't signal error to the calling application, so, in case an invalid option is received, an error state should be set in the application or in the parser object.

parse()

Starts command line parsing.

CmdlineParser.parse( [args] )
args

A specific string array that will be used as arguments to be parsed.

Returns:

true if the parsing is complete, false on error.

Start the parsing process. If args parameter is not provided, the method gets the content of the args global vector defined in the Core module.

Returns true if the parsing was complete, and false on error (in example, if some element in the array wasn't a string).

terminate()

Requests the parser to terminate parsing.

CmdlineParser.terminate( )

This method should be called from inside one of the CmdlineParser class callbacks. Once called, the parser will immediately return true. The calling application can know the position of the last parsed parameter by accessing the lastParsed property, and handle the missing parameters as it prefers.


Index  |  Related pages  |  Classes  |  Functions  |  Entities  |  Function Sets  |  Groups
Made with Faldoc 1.0.0