Changeset 82

Show
Ignore:
Timestamp:
01/13/07 23:24:17 (2 years ago)
Author:
KirkMcDonald
Message:

Completed docs. Small bugfix in Help action.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • misc/optparse.d

    r80 r82  
    2626 
    2727import std.stdio : writefln, writef; 
    28 import std.string : split, find, toupper; 
     28import std.string : find, toupper; 
    2929import std.c.stdlib : exit, EXIT_FAILURE, EXIT_SUCCESS; 
    3030import std.conv : toInt, ConvError; 
    31 import std.path : getName, getBaseName; 
     31import std.path : getBaseName; 
    3232import std.utf : toUTF8, toUTF32; 
    3333 
    …… 
    441441    } 
    442442    char[] get_program_name(char[] path) { 
    443         char[] result; 
    444443        version(Windows) { 
    445444            // (Unicode note: ".exe" only contains 4 code units, so this slice 
    …… 
    447446            // this code actually is.) 
    448447            assert(path[$-4 .. $] == ".exe"); 
    449             result = path[0 .. $-4]; 
    450         } 
    451         return getBaseName(result); 
     448            path = path[0 .. $-4]; 
     449        } 
     450        return getBaseName(path); 
    452451    } 
    453452    Options parse_args(char[][] args) { 

  • misc/optparse.html

    r81 r82  
    5353 
    5454<ul> 
    55 <li>Store 
    56 <li>Append 
    57 <li>StoreConst 
    58 <li>AppendConst 
    59 <li>SetTrue 
    60 <li>SetFalse 
    61 <li>Count 
    62 <li>Callback 
    63 <li>CallbackFancy 
    64 <li>Help 
     55<li>Store</li> 
     56<li>Append</li> 
     57<li>StoreConst</li> 
     58<li>AppendConst</li> 
     59<li>SetTrue</li> 
     60<li>SetFalse</li> 
     61<li>Count</li> 
     62<li>Callback</li> 
     63<li>CallbackFancy</li> 
     64<li>Help</li> 
    6565</ul> 
    6666 
    …… 
    8888<li><tt>Option add_option(char[][] options, void delegate(Options, inout char[][], inout int, char[], char[]) dg)</tt></li> 
    8989<li><tt>Option add_option(char[][] options, void delegate(Options, inout char[][], inout int, char[], int) dg)</tt></li> 
    90 <li><tt>Option add_option(char[][] options, char[], void delegate(Options, inout char[][], inout int, char[]) dg)</tt></li> 
    91 <li><tt>Option add_option(char[][] options, char[], void delegate(Options, inout char[][], inout int, char[], char[]) dg)</tt></li> 
    92 <li><tt>Option add_option(char[][] options, char[], void delegate(Options, inout char[][], inout int, char[], int) dg)</tt></li> 
     90<li><tt>Option add_option(char[][] options, char[] name, void delegate(Options, inout char[][], inout int, char[]) dg)</tt></li> 
     91<li><tt>Option add_option(char[][] options, char[] name, void delegate(Options, inout char[][], inout int, char[], char[]) dg)</tt></li> 
     92<li><tt>Option add_option(char[][] options, char[] name, void delegate(Options, inout char[][], inout int, char[], int) dg)</tt></li> 
    9393</ul> 
    9494 
    …… 
    261261 
    262262<h3><a name="ActionSetTrueFalse">Action.SetTrue and Action.SetFalse</a></h3> 
    263 <h4>Methods</h4> 
    264 <h4>Results</h4> 
    265 <h4>Example</h4> 
     263<p>Flag options may be implemented with these actions. The <tt>SetTrue</tt> action will set a flag to true, and <tt>SetFalse</tt> will set it to false.</p> 
     264 
     265<h4>Methods</h4> 
     266<ul> 
     267<li><tt>Option add_option(char[][] options, Action action)</tt></li> 
     268<li><tt>Option add_option(char[][] options, char[] name, Action action)</tt></li> 
     269</ul> 
     270 
     271<h4>Results</h4> 
     272<p>The flag is retrieved using the <tt>flag</tt> method of the <tt>Options</tt> class.</p> 
     273 
     274<blockquote><tt>bool flag = options.flag("flag");</tt></blockquote> 
     275 
     276<p>If the flag was not specified, it defaults to false.</p> 
     277 
     278<h4>Example</h4> 
     279<blockquote><pre>void main(char[][] args) { 
     280    auto parser = new OptionParser(); 
     281    parser.add_option(["--enable"], "flag", Action.SetTrue); 
     282    parser.add_option(["--disable"], "flag", Action.SetFalse); 
     283    auto options = parser.parse_args(args); 
     284    writefln("flag: %s", options.flag("flag")); 
     285}</pre></blockquote> 
     286 
     287<p>This produces the following on the command-line:</p> 
     288 
     289<blockquote><pre>$ myapp --enable 
     290flag: true 
     291$ myapp --enable --disable 
     292flag: false 
     293$ myapp 
     294flag: false</pre></blockquote> 
    266295 
    267296<h3><a name="ActionCount">Action.Count</a></h3> 
    268 <h4>Methods</h4> 
    269 <h4>Results</h4> 
    270 <h4>Example</h4> 
     297<p>The <tt>Count</tt> action simply counts the number of times the option occurs on the command-line.</p> 
     298 
     299<h4>Methods</h4> 
     300<ul> 
     301<li><tt>Option add_option(char[][] options, Action action)</tt></li> 
     302<li><tt>Option add_option(char[][] options, char[] name, Action action)</tt></li> 
     303</ul> 
     304 
     305<h4>Results</h4> 
     306<p>The count may be retrieved from the <tt>count</tt> method of <tt>Options</tt>.</p> 
     307 
     308<blockquote><tt>int c = options.count("verbosity");</tt></blockquote> 
     309 
     310<h4>Example</h4> 
     311<blockquote><pre>void main(char[][] args) { 
     312    auto parser = new OptionParser(); 
     313    parser.add_option(["-v", "--verbose"], "verbosity", Action.Count); 
     314    auto options = parser.parse_args(args); 
     315    writefln("verbosity: %s", options.count("verbosity")); 
     316}</pre></blockquote> 
     317 
     318<p>This produces the following on the command-line:</p> 
     319 
     320<blockquote><pre>$ myapp -vvv 
     321verbosity: 3 
     322$ myapp -v --verbose 
     323verbosity: 2 
     324$ myapp 
     325verbosity: 0</pre></blockquote> 
    271326 
    272327<h3><a name="ActionCallback">Action.Callback</a></h3> 
    273 <h4>Methods</h4> 
    274 <h4>Results</h4> 
    275 <h4>Example</h4> 
     328<p>Sometimes, the above actions aren't enough. To extend <tt>optparse</tt>, users may provide a callback as an option's action. A callback option may accept an argument. Whether it accepts an argument is determined by the type of the callback.</p> 
     329 
     330<p><strong>Important note:</strong> A callback is called as soon as it is encountered in the argument list. This means that <tt>optparse</tt> may still exit with an error if it finds malformed or invalid options on the command line, after the callback is run. For this reason, users should not place actual program logic inside of callbacks, and should only use them to store option data for later use.</p> 
     331 
     332<h4>Methods</h4> 
     333<ul> 
     334<li><tt>Option add_option(char[][] options, void delegate() dg)</tt></li> 
     335<li><tt>Option add_option(char[][] options, void delegate(char[]) dg)</tt></li> 
     336<li><tt>Option add_option(char[][] options, void delegate(int) dg)</tt></li> 
     337</ul> 
     338<h4>Results</h4> 
     339<p>The results of a callback option are not stored anywhere by <tt>optparse</tt>. It is assumed the user will keep any information about the callback themselves.</p> 
     340 
     341<h4>Example</h4> 
     342<blockquote><pre>void main(char[][] args) { 
     343    auto parser = new OptionParser(); 
     344    parser.add_option(["--callback"], { 
     345        writefln("Callback encountered!"); 
     346    }); 
     347    auto options = parser.parse_args(args); 
     348    writefln("Done."); 
     349}</pre></blockquote> 
     350 
     351<p>This produces the following on the command-line:</p> 
     352 
     353<blockquote><pre>$ myapp --callback 
     354Callback encountered! 
     355Done. 
     356$ myapp 
     357Done.</pre></blockquote> 
    276358 
    277359<h3><a name="ActionCallbackFancy">Action.CallbackFancy</a></h3> 
    278 <h4>Methods</h4> 
    279 <h4>Results</h4> 
    280 <h4>Example</h4> 
     360<p>If client code wants to handle the parsing process at a lower level, <tt>optparse</tt> provides these advanced callbacks.</p> 
     361 
     362<p>The first four arguments to these callbacks have the following types and meanings:</p> 
     363 
     364<dl> 
     365<dt><tt>Options</tt></dt> <dd>The current results of parsing the command-line, up to when the callback was encountered.</dd> 
     366 
     367<dt><tt>inout char[][]</tt></dt> <dd>The args array. This is mostly identical to the array originally passed to <tt>parse_args</tt>, with the following differences: 
     368    <ol> 
     369    <li>The first element, with the executable name, has been removed.</li> 
     370    <li>Options of the form "<tt>--option=argument</tt>" preceeding (or including) this option have been parsed apart into two elements, as in <tt>[--option,argument]</tt>. Elements of the array after the current option have not been touched, yet.</li> 
     371    </ol> 
     372It is useful to note that this argument is declared <tt>inout</tt>, meaning callbacks are free to modify the array.</dd> 
     373 
     374<dt><tt>inout int</tt></dt> <dd>The index in the args array of this option; or, if this option accepts an argument, of the option's argument. Note that this is declared <tt>inout</tt>. When the callback returns, parsing will resume with the element of args following this <tt>int</tt>. If this argument is advanced beyond the end of the args array, parsing will quietly terminate.</dd> 
     375 
     376<dt><tt>char[]</tt></dt> <dd>The name of this option.</dd> 
     377</dl> 
     378 
     379<p>The fifth argument to the callback, if it exists, controls the type of the argument to the option.</p> 
     380 
     381<h4>Methods</h4> 
     382<ul> 
     383<li><tt>Option add_option(char[][] options, void delegate(Options, inout char[][], inout int, char[]) dg)</tt></li> 
     384<li><tt>Option add_option(char[][] options, void delegate(Options, inout char[][], inout int, char[], char[]) dg)</tt></li> 
     385<li><tt>Option add_option(char[][] options, void delegate(Options, inout char[][], inout int, char[], int) dg)</tt></li> 
     386<li><tt>Option add_option(char[][] options, char[] name, void delegate(Options, inout char[][], inout int, char[]) dg)</tt></li> 
     387<li><tt>Option add_option(char[][] options, char[] name, void delegate(Options, inout char[][], inout int, char[], char[]) dg)</tt></li> 
     388<li><tt>Option add_option(char[][] options, char[] name, void delegate(Options, inout char[][], inout int, char[], int) dg)</tt></li> 
     389</ul> 
     390<h4>Results</h4> 
     391<p>As with regular callbacks, <tt>optparse</tt> does not store the results of advanced callbacks.</p> 
     392 
     393<h4>Example</h4> 
     394<blockquote><pre>void main(char[][] args) { 
     395    auto parser = new OptionParser(); 
     396    parser.add_option( 
     397        ["--adv-callback"], 
     398        (Options o, inout char[][] a, inout int i, char[] name) { 
     399            // Skip the next argument, whatever it is. 
     400            ++i; 
     401        } 
     402    ); 
     403    parser.add_option(["-c"], Action.Count); 
     404    auto options = parser.parse_args(args); 
     405    writefln("count: %s", options.count("c")); 
     406}</pre></blockquote> 
     407 
     408<p>This produces the following on the command-line:</p> 
     409 
     410<blockquote><pre>$ myapp -c --adv-callback -cc 
     411count: 1</pre></blockquote> 
    281412 
    282413<h3><a name="ActionHelp">Action.Help</a></h3> 
    283 <h4>Methods</h4> 
    284 <h4>Results</h4> 
    285 <h4>Example</h4> 
     414<p>The <tt>Help</tt> action prints out a listing of the options in the parser.</p> 
     415 
     416<p>The listing begins with a header like the following:</p> 
     417 
     418<blockquote><pre>Usage: myapp [options] args... 
     419A short description of myapp. 
     420 
     421Options:</pre></blockquote> 
     422 
     423<p>This header is customizable in two ways:</p> 
     424<ul> 
     425<li>The "<tt>[options] args...</tt>" portion is contained in the <tt>argdesc</tt> member variable of the <tt>OptionParser</tt> class. Users may change this member to whatever they like in their instance.</li> 
     426<li>The short description should be provided to the <tt>OptionParser</tt> constructor.</li> 
     427</ul> 
     428 
     429<p>Additionally, the name of the application is derived directly from the first element of the args array.</p> 
     430 
     431<p>Options are printed in the following form. Given these options:</p> 
     432 
     433<blockquote><pre>parser.add_option("-f", "--file").help("The file to operate on.") 
     434parser.add_option(["--enable"], Action.SetTrue).help("Enables the option.")</pre></blockquote> 
     435 
     436<p><tt>Help</tt> produces the following:</p> 
     437 
     438<blockquote><pre>  -f, --file=FILE The file to operate on. 
     439  --enable        Enables the option.</pre></blockquote> 
     440 
     441<p>The <tt>help</tt> method of the <tt>Option</tt> class provides the description used in the listing. Notice also the "<tt>=FILE</tt>" in the first option above. This indicates that the option accepts an argument. If you wanted to have this say "<tt>=FILENAME</tt>" instead, you would instead define the <tt>--file</tt> option as:</p> 
     442 
     443<blockquote<tt>parser.add_option("-f", "--file").help("The file to operate on.").argName("filename");</tt></blockquote> 
     444 
     445<p>The <tt>argName</tt> method of <tt>Option</tt> class defines this string, which otherwise defaults to the option's name. Note that it always converts the argument's name to all-caps.</p> 
     446 
     447<h4>Methods</h4> 
     448<ul> 
     449<li><tt>Option add_option(char[][] options, Action action)</tt></li> 
     450</ul> 
     451 
     452<h4>Results</h4> 
     453<p><tt>Help</tt> terminates the program when found.</p> 
     454 
     455<h4>Example</h4> 
     456<p>Bringing it all together, we get this:</p> 
     457 
     458<blockquote><pre>void main(char[][] args) { 
     459    auto parser = new OptionParser("Testing the Help action."); 
     460    parser.argdesc = "[options]"; 
     461    parser.add_option("-f", "--file").help("Defines the file to use.").argName("filename"); 
     462    parser.add_option(["-n", "--number"], ArgType.Integer).help("Specifies the number."); 
     463    parser.add_option(["--blue"], "color", Action.AppendConst, "blue").help("Adds the color blue."); 
     464    parser.add_option(["--green"], "color", Action.AppendConst, "green").help("Adds the color green."); 
     465    parser.add_option(["--help"], Action.Help).help("Displays this help message."); 
     466    auto options = parser.parse_args(args); 
     467    writefln("Done."); 
     468}</pre></blockquote> 
     469 
     470<p>This produces the following on the command-line:</p> 
     471 
     472<blockquote><pre>$ myapp --help 
     473Usage: myapp [options] 
     474Testing the Help action. 
     475 
     476Options: 
     477  -f, --file=FILENAME Defines the file to use. 
     478  -n, --number=NUMBER Specifies the number. 
     479  --blue              Adds the color blue. 
     480  --green             Adds the color green. 
     481  --help              Displays this help message. 
     482$ myapp 
     483Done.</pre></blockquote> 
    286484 
    287485<hr /> 
    …… 
    311509 
    312510<pre>class OptionParser { 
     511    Option[] options; 
    313512    char[] argdesc; 
    314513    this(char[] desc=""); 
    …… 
    335534    Option add_option(char[][] options, OptionCallbackFancyArg dg); 
    336535    Option add_option(char[][] options, OptionCallbackFancyInt dg); 
    337     Option add_option(char[][] options, char[], OptionCallbackFancy dg); 
    338     Option add_option(char[][] options, char[], OptionCallbackFancyArg dg); 
    339     Option add_option(char[][] options, char[], OptionCallbackFancyInt dg); 
     536    Option add_option(char[][] options, char[] name, OptionCallbackFancy dg); 
     537    Option add_option(char[][] options, char[] name, OptionCallbackFancyArg dg); 
     538    Option add_option(char[][] options, char[] name, OptionCallbackFancyInt dg); 
    340539}</pre> 
    341540 
    …… 
    354553 
    355554The "<tt>[options] args...</tt>" part of this message is contained in <tt>argdesc</tt>, and may be overidden by client code. (The "<tt>myapp</tt>" part of the message is automatically derived from the first element of the <tt>args</tt> array.)</dd> 
     555 
     556<dt><tt>Option[] options;</tt></dt> <dd>This array holds all of the instances of <tt>Option</tt> known by the parser.</dd> 
    356557</dl> 
    357558 
    …… 
    385586    int value(char[] name); 
    386587    char[][] list(char[] name); 
    387     char[] value_list(char[] name); 
     588    int[] value_list(char[] name); 
    388589    int count(char[] name); 
    389590    bool flag(char[] name); 
     591    char[][] args; 
    390592}</pre> 
    391593 
    …… 
    395597<dt><tt>int value(char[] name);</tt></dt> <dd>The results of the <tt>Store</tt> action may be retrieved here when the type is <tt>Integer</tt>.</dd> 
    396598 
    397 <dt><tt>char[][] list(char[] name);</tt></dt> <dd>The results or the <tt>Append</tt> and <tt>AppendConst</tt> actions may be retrieved from here. (<tt>Append</tt> only when the type is <tt>String</tt>.)</dd> 
     599<dt><tt>char[][] list(char[] name);</tt></dt> <dd>The results of the <tt>Append</tt> and <tt>AppendConst</tt> actions may be retrieved from here. (<tt>Append</tt> only when the type is <tt>String</tt>.)</dd> 
     600 
     601<dt><tt>int[] value_list(char[] name);</tt></dt> <dd>The results of the <tt>Append</tt> action may be retrieved from here when its type is <tt>Integer</tt>.</dd> 
     602 
     603<dt><tt>int count(char[] name);</tt></dt> <dd>The results of the <tt>Count</tt> action may be retrieved from here.</dd> 
     604 
     605<dt><tt>bool flag(char[] name);</tt></dt> <dd>The results of the <tt>SetTrue</tt> and <tt>SetFalse</tt> actions may be retrieved from here.</dd> 
     606 
     607<dt><tt>char[][] args;</tt></dt> <dd>By default, leftover args are simply added to this array when they are encountered. (See also the <tt>leftover_callback</tt> method of <tt>OptionParser</tt>, however.)</dd> 
    398608</dl> 
    399609