# HG changeset patch # User Rob Landley # Date 1379791646 18000 # Node ID 3c0e653070d8a4c3235cb559f0eaa74579fd09a5 # Parent 7a45b9b54d3d82643698338c8a8da9136ad752ac Update lib/args.c docs. diff -r 7a45b9b54d3d -r 3c0e653070d8 www/code.html --- 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 @@
  • toys.optflags = 13; // -a = 8 | -b = 4 | -d = 1
  • toys.optargs[0] = "walrus"; // leftover argument
  • toys.optargs[1] = NULL; // end of list
    • -
  • toys.optc=1; // there was 1 leftover argument
    • +
  • toys.optc = 1; // there was 1 leftover argument
  • toys.argv[] = {"-b", "fruit", "-d", "walrus", "-a", "42"}; // The original command line arguments

    • @@ -737,6 +737,12 @@ with the array position. Right to left in the optflags string corresponds to top to bottom in GLOBALS().

    +

    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.

    +

    long toys.optflags

    Each option in the optflags string corresponds to a bit position in @@ -769,31 +775,31 @@

  • * - plus a string argument, appended to a linked list.
  • @ - plus an occurrence counter (stored in a long)
  • # - plus a signed long argument. +
  • - - plus a signed long argument defaulting to negative (start argument with + to force a positive value).
  • . - plus a floating point argument (if CFG_TOYBOX_FLOAT).
    • - -

    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.

    +

    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"

    + +

    GLOBALS

    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.

    +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.

    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.

    +

    See toys/other/hello.c for a longer example of parsing options into the +GLOBALS block.

    +

    char *toys.optargs[]

    Command line arguments in argv[] which are not consumed by option parsing @@ -839,10 +848,6 @@

    The following may be appended to a float or double:

    @@ -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).

    +

    [groups]

    + +

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

    + +

    The first character of the group defines the type, the remaining +characters are options it applies to:

    + + + +

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

    + +

    whitespace

    + +

    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.

    + +

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

    + +

    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".

    + +

    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.

    +

    lib/dirtree.c

    The directory tree traversal code should be sufficiently generic