<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Class CmdlineParser - Class CmdlineParser</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./funset.html"><span>Function sets</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./globals.html"><span>Globals</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Class CmdlineParser</h1>
<p class="faldoc_brief">Provides simple and powerful parsing of the command line options. </p>
<p class="faldoc_funcdecl">
<b>class</b> CmdlineParser
</p>
<p class="faldoc_brief"><a href="#more">more...</a></p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#lastParsed">lastParsed</a></td><td>An integer representing the last item parsed in the argument array before exit the parsing loop.</td></tr>
<tr><td><a href="#expectValue">expectValue()</a></td><td>Declares that current option needs a value. </td></tr>
<tr><td><a href="#onFree">onFree()</a></td><td>Called when the parser finds a free option. </td></tr>
<tr><td><a href="#onOption">onOption()</a></td><td>Called when the parser finds an option. </td></tr>
<tr><td><a href="#onSwitchOff">onSwitchOff()</a></td><td>Called when the parser finds a switch being turned off. </td></tr>
<tr><td><a href="#onValue">onValue()</a></td><td>Called when the parser finds a value for a given option. </td></tr>
<tr><td><a href="#parse">parse()</a></td><td>Starts command line parsing. </td></tr>
<tr><td><a href="#terminate">terminate()</a></td><td>Requests the parser to terminate parsing. </td></tr>
</table>
<a name="more"><h2 class="faldoc_title">Detailed description</h2></a>
<p class="faldoc_funcdecl">
<b>class</b> CmdlineParser
</p>
<table class="faldoc_function">
</table>
<br/>
<p class="item_brief">Provides simple and powerful parsing of the command line options. </p>
<p class="faldoc_text">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". </p>
<p class="faldoc_text">Some embedding applications may provide the scripts with a command line too; for 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. </p>
<p class="faldoc_text">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. </p>
<p class="faldoc_text">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. </p>
<p class="faldoc_text">The command line parser knows the following option categories: </p>
<ul>
<li><b>short</b><b>options</b>: options consisting of a single character, case sensitive, following a single "-". For example, "-a", "-B", "-x". Short options may be chained in sequences of characters as, for example "-aBx" which is equivalent to "-a -B -x". Short options may have also the special "switch off" semantic; if they are followed by a "-" sign, the parser interprets it as a will to turn off some feature; for example, the sequence "-B-" means that the "B" option should be turned off. The semantic can be expressed also in chained options as "-aB-x". </li><li><b>long</b><b>options</b>: they consists of two minus followed by a word of any length, as for example "--parameter", "--config", "--elements". Long options are usually (but not necessarily) meant to receive a parameter, for example "--debug off". </li><li><b>free</b><b>options</b>: they are strings not leaded by any "-" sign. Usually the semantic of a command gives free options a special meaning; for example the "cp" unix command accept an arbitrary amount of free options, where the first N-1 options are the name of the files to copy, and the Nth option is the copy destination. A single "-" not followed by any letter is considered a free option (i.e. it often means "stdout/stdin" in many UNIX commands). </li><li><b>option</b><b>parsing</b><b>terminator</b>: The special sequence "--" followed by a whitespace is considered as the terminator of option parsing; after that element, all the other options are considered free options and given to the parser "as is". If you want to pass a free parameter starting with a "-", (i.e. a file named "-strangename"), it must follow the "--" sign. </li>
</ul>
<p class="faldoc_text">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. For 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. </p>
<p class="faldoc_text">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. For 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. </p>
<p class="faldoc_text">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. </p>
<p class="faldoc_text">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. </p>
<p class="faldoc_text">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. </p>
<p class="faldoc_text">Here is a working sample of implementation. </p>
<pre class="faldoc_code">
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()
</pre>
<p class="faldoc_text"><b>Notice</b>: 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. </p>
<h2 class="faldoc_title">Properties</h2>
<h3 class="faldoc_funcname"><a name="lastParsed">lastParsed</a></h3>
<p class="item_brief">An integer representing the last item parsed in the argument array before exit the parsing loop.</p>
<h2 class="faldoc_title">Methods</h2>
<h3 class="faldoc_funcname"><a name="expectValue">expectValue()</a></h3>
<p class="item_brief">Declares that current option needs a value. </p>
<p class="faldoc_funcdecl">CmdlineParser.expectValue( )</p>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
<p class="faldoc_text">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. </p>
</p>
<h3 class="faldoc_funcname"><a name="onFree">onFree()</a></h3>
<p class="item_brief">Called when the parser finds a free option. </p>
<p class="faldoc_funcdecl">CmdlineParser.onFree( opt )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">opt</td><td class="faldoc_paramdesc">The free option being read. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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(). </p>
<p class="faldoc_text">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. </p>
</p>
<h3 class="faldoc_funcname"><a name="onOption">onOption()</a></h3>
<p class="item_brief">Called when the parser finds an option. </p>
<p class="faldoc_funcdecl">CmdlineParser.onOption( opt )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">opt</td><td class="faldoc_paramdesc">The option being read. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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(). </p>
<p class="faldoc_text">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. </p>
<p class="faldoc_text">If the incoming option requires a parameter, this callback should call expectOption() before returning. </p>
</p>
<h3 class="faldoc_funcname"><a name="onSwitchOff">onSwitchOff()</a></h3>
<p class="item_brief">Called when the parser finds a switch being turned off. </p>
<p class="faldoc_funcdecl">CmdlineParser.onSwitchOff( opt )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">opt</td><td class="faldoc_paramdesc">The switch being turned off. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This callback method gets called by parse() when a short option is immediately followed by a "-", indicating a "switch off" semantic. </p>
<p class="faldoc_text">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(). </p>
<p class="faldoc_text">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. </p>
</p>
<h3 class="faldoc_funcname"><a name="onValue">onValue()</a></h3>
<p class="item_brief">Called when the parser finds a value for a given option. </p>
<p class="faldoc_funcdecl">CmdlineParser.onValue( opt, value )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">opt</td><td class="faldoc_paramdesc">The option being parsed. </td></tr><tr><td class="faldoc_param">value</td><td class="faldoc_paramdesc">The given value for that option. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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(). </p>
<p class="faldoc_text">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. </p>
</p>
<h3 class="faldoc_funcname"><a name="parse">parse()</a></h3>
<p class="item_brief">Starts command line parsing. </p>
<p class="faldoc_funcdecl">CmdlineParser.parse( [args] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">args</td><td class="faldoc_optparamdesc">A specific string array that will be used as arguments to be parsed. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if the parsing is complete, false on error. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Start the parsing process. If args parameter is not provided, the method gets the content of the <a href="./globals.html#args">args</a> global vector defined in the Core module. </p>
<p class="faldoc_text">Returns true if the parsing was complete, and false on error (for example, if some element in the array wasn't a string). </p>
</p>
<h3 class="faldoc_funcname"><a name="terminate">terminate()</a></h3>
<p class="item_brief">Requests the parser to terminate parsing. </p>
<p class="faldoc_funcdecl">CmdlineParser.terminate( )</p>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
</p>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./funset.html">Function sets</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./globals.html">Globals</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
