Mercurial > hg > toybox
changeset 1073:3c0e653070d8 draft
Update lib/args.c docs.
author | Rob Landley <rob@landley.net> |
---|---|
date | Sat, 21 Sep 2013 14:27:26 -0500 |
parents | 7a45b9b54d3d |
children | 82c5eb459a91 |
files | www/code.html |
diffstat | 1 files changed, 67 insertions(+), 19 deletions(-) [+] |
line wrap: on
line diff
--- a/www/code.html Sat Sep 21 13:46:44 2013 -0500 +++ b/www/code.html Sat Sep 21 14:27:26 2013 -0500 @@ -709,7 +709,7 @@ <li>toys.optflags = 13; // -a = 8 | -b = 4 | -d = 1</li> <li>toys.optargs[0] = "walrus"; // leftover argument</li> <li>toys.optargs[1] = NULL; // end of list</li> -<li>toys.optc=1; // there was 1 leftover argument</li> +<li>toys.optc = 1; // there was 1 leftover argument</li> <li>toys.argv[] = {"-b", "fruit", "-d", "walrus", "-a", "42"}; // The original command line arguments </ul> <p></li> @@ -737,6 +737,12 @@ with the array position. Right to left in the optflags string corresponds to top to bottom in GLOBALS().</p> +<p>Put globals not filled out by the option parsing logic at the end of the +GLOBALS block. Common practice is to list the options one per line (to +make the ordering explicit, first to last in globals corresponds to right +to left in the option string), then leave a blank line before any non-option +globals.</p> + <p><b>long toys.optflags</b></p> <p>Each option in the optflags string corresponds to a bit position in @@ -769,31 +775,31 @@ <li><b>*</b> - plus a string argument, appended to a linked list.</li> <li><b>@</b> - plus an occurrence counter (stored in a long)</li> <li><b>#</b> - plus a signed long argument. +<li><b>-</b> - plus a signed long argument defaulting to negative (start argument with + to force a positive value).</li> <li><b>.</b> - plus a floating point argument (if CFG_TOYBOX_FLOAT).</li> <ul>The following can be appended to a float or double: <li><b><123</b> - error if argument is less than this</li> <li><b>>123</b> - error if argument is greater than this</li> <li><b>=123</b> - default value if argument not supplied</li> </ul> -<ul><li>Option parsing only understands <>= after . when CFG_TOYBOX_FLOAT -is enabled. (Otherwise the code to determine where floating point constants -end drops out. When disabled, it can reserve a global data slot for the -argument so offsets won't change, but will never fill it out.). You can handle -this by using the USE_BLAH() macros with C string concatenation, ala: -"abc." USE_TOYBOX_FLOAT("<1.23>4.56=7.89") "def"</li></ul> </ul> -<p>Arguments may occur with or without a space (I.E. "-a 42" or "-a42"). -The command line argument "-abc" may be interepreted many different ways: -the optflags string "cba" sets toys.optflags = 7, "c:ba" sets toys.optflags=4 -and saves "ba" as the argument to -c, and "cb:a" sets optflags to 6 and saves -"c" as the argument to -b.</p> +<p>A note about "." and CFG_TOYBOX_FLOAT: option parsing only understands <>= +after . when CFG_TOYBOX_FLOAT +is enabled. (Otherwise the code to determine where floating point constants +end drops out; it requires floating point). When disabled, it can reserve a +global data slot for the argument (so offsets won't change in your +GLOBALS[] block), but will never fill it out. You can handle +this by using the USE_BLAH() macros with C string concatenation, ala: +"abc." USE_TOYBOX_FLOAT("<1.23>4.56=7.89") "def"</p> + +<p><b>GLOBALS</b></p> <p>Options which have an argument fill in the corresponding slot in the global union "this" (see generated/globals.h), treating it as an array of longs -with the rightmost saved in this[0]. Again using "a*b:c#d", "-c 42" would set -this[0]=42; and "-b 42" would set this[1]="42"; each slot is left NULL if -the corresponding argument is not encountered.</p> +with the rightmost saved in this[0]. As described above, using "a*b:c#d", +"-c 42" would set this[0] = 42; and "-b 42" would set this[1] = "42"; each +slot is left NULL if the corresponding argument is not encountered.</p> <p>This behavior is useful because the LP64 standard ensures long and pointer are the same size. C99 guarantees structure members will occur in memory @@ -801,6 +807,9 @@ consecutive variables of register size. Thus the first few entries can be longs or pointers corresponding to the saved arguments.</p> +<p>See toys/other/hello.c for a longer example of parsing options into the +GLOBALS block.</p> + <p><b>char *toys.optargs[]</b></p> <p>Command line arguments in argv[] which are not consumed by option parsing @@ -839,10 +848,6 @@ <ul> <li><b>^</b> - stop parsing options after encountering this option, everything else goes into optargs.</li> <li><b>|</b> - this option is required. If more than one marked, only one is required.</li> -<li><b>+X</b> enabling this option also enables option X (switch bit on).</li> -<li><b>~X</b> enabling this option disables option X (switch bit off).</li> -<li><b>!X</b> this option cannot be used in combination with X (die with error).</li> -<li><b>[yz]</b> this option requires at least one of y or z to also be enabled.</li> </ul> <p>The following may be appended to a float or double:</p> @@ -878,6 +883,49 @@ each "bare longopt" (ala "(one)(two)abc" before any option characters) always sets its own bit (although you can group them with +X).</p> +<p><b>[groups]</b></p> + +<p>At the end of the option string, square bracket groups can define +relationships between existing options. (This only applies to short +options, bare --longopts can't participate.)</p> + +<p>The first character of the group defines the type, the remaining +characters are options it applies to:</p> + +<ul> +<li><b>-</b> - Exclusive, switch off all others in this group.</li> +<li><b>+</b> - Inclusive, switch on all others in this group.</li> +<li><b>!</b> - Error, fail if more than one defined.</li> +</ul> + +<p>So "abc[-abc]" means -ab = -b, -ba = -a, -abc = -c. "abc[+abc]" +means -ab=-abc, -c=-abc, and "abc[!abc] means -ab calls error_exit("no -b +with -a"). Note that [-] groups clear the GLOBALS option slot of +options they're switching back off, but [+] won't set options it didn't see +(just the optflags).</p> + +<p><b>whitespace</b></p> + +<p>Arguments may occur with or without a space (I.E. "-a 42" or "-a42"). +The command line argument "-abc" may be interepreted many different ways: +the optflags string "cba" sets toys.optflags = 7, "c:ba" sets toys.optflags=4 +and saves "ba" as the argument to -c, and "cb:a" sets optflags to 6 and saves +"c" as the argument to -b.</p> + +<p>Note that & changes whitespace handling, so that the command line +"tar cvfCj outfile.tar.bz2 topdir filename" is parsed the same as +"tar filename -c -v -j -f outfile.tar.bz2 -C topdir". Note that "tar -cvfCj +one two three" would equal "tar -c -v -f Cj one two three". (This matches +historical usage.)</p> + +<p>Appending a space to the option in the option string ("a: b") makes it +require a space, I.E. "-ab" is interpreted as "-a" "-b". That way "kill -stop" +differs from "kill -s top".</p> + +<p>Appending ; to a longopt in the option string makes its argument optional, +and only settable with =, so in ls "(color):;" can accept "ls --color" and +"ls --color=auto" without complaining that the first has no argument.</p> + <a name="lib_dirtree"><h3>lib/dirtree.c</h3> <p>The directory tree traversal code should be sufficiently generic