NAME

library/Getopt/Obj.pir - parse long and short command line options

SYNOPSIS

 .sub main :main
     .param pmc argv
     .local string prog_name
     prog_name = shift argv
     load_bytecode "Getopt/Obj.pir"
     .local pmc getopts
     getopts = new "Getopt::Obj"
     getopts."notOptStop"(1)

     # these two are identical, with the exception of the call to name

     push getopts, "foo|f:s"

     $P0 = getopts."add"()
     $P0."name"("FooBar")
     $P0."long"("foo")
     $P0."short"("f")
     $P0."optarg"(1)
     $P0."type"('String')

     # these two are identical

     push getopts, "bar|b=s"

     $P0 = getopts."add"()
     $P0."long"("bar")
     $P0."short"("b")
     $P0."type"('String')

     .local pmc opts
     opts = getopts."get_options"(argv)
     .local string foo
     foo = opts["Foobar"]
 .end

DESCRIPTION

This library parses options from the command line. Options may take and of these forms, currently:

 --foo=bar         Set foo to bar
 -f bar            Set f to bar (with conditions)
 -fthis=that       If f is a Hash, set key 'this' to 'that'
 -f this=that      If f is a Hash, set key 'this' to 'that'
 -f                Set f (if it's Boolean or has an optional argument)
 -fbar             Set f to bar if it's not a Boolean
 -abc              If -a -b and -c are all Booleans, set them all
 --foo=this=that   If foo is a Hash, set key 'this' to 'that'
                   Both equal signs are required
 --                Stop processing args, -- is removed from argv

SUBROUTINES

__load(): States that Getopt::Obj and Getopt::Obj::Spec are classes to use and defines the attributes they'll use.

Class Getopt::Obj

Our nice little module.

init(): Creates the Specs and notOptStop attribute, interal stuff.
HASH get_options(ARRAY ARGV): Parses ARGV, modifying it inplace, and returns a hash with the keys and values wanted.
__push_string(STRING format): A vtable method, invoked by e.g. push getopts, "foo|f=s". The format is as such.
Getopt::Obj::Spec add(): Adds a new option to the parsing. You don't need to know what class it is (internal data), just that you get an object to invoke methods on.
STRING getNameForKey(STRING key): Given a key, maybe long or short, or when storing, the name itself perhaps, return the name for the key.
INT self."notOptStop"()
INT self."notOptStop"(INT val): Boolean method, so setting it to 2 is no different than setting it to 1. If notOptStop is set to a true value, then get_options will stop after it reaches an argument not specified by the program. This is either an unrecognized option, such as a mistyped argument, or an argument means to be passed on again later. Or of course, it's not an argument at all and perhaps a filename.
MissingRequired(STRING arg): When a required argument is missing, throws an exception with the message "Missing a required argument for option 'foo'".

Class Getopt::Obj::Spec

Interal use only, at least don't do any new "Getopt::Obj::Spec" yourself... This makes an easy holder for each possible match.

init(): Set the defaults to all our attributes, more internal stuff. Sets the default "type" to Boolean.
STRING self."name"()
STRING self."name"(STRING val): If val is given, set the name to that. If val is not given, return either name, long, or short, in that order. Used for the return key. So if you define only a short option, but want a long name returned, set this. The partial intent of the method is to easily allow having an option have multiple long/short arguments instead of one of each.
STRING self."long"()
STRING self."long"(STRING val): If val is given, set the long value to that. If val is not given, return the string set as the long.
STRING self."short"()
STRING self."short"(STRING val): If val is given, set the short value to that. If val is not given, return the string set as the short.; NOTE: There is no checking to ensure that short is only one character.
INT self."type"()
INT self."type"(INT val): If val is given, set the type to that. If val is not given, return the int set as the type.; NOTE: It doesn't verify it's a corrent type.; Do not hard code the integer values in, for the same reason as the rest of your code. There's no guarantees they won't be reassigned.
INT self."optarg"()
INT self."optarg"(INT val): Boolean method, with explicit setting. If optarg is set to a true value, then the argument, e.g. bar in --foo=bar, is not mandatory. In -fbar, -f is set to bar. In -f bar it is NOT set.

TODO

Actually check what's being passed instead of using type conversions?

Sub type, call a sub for a given argument, with argv and return.

How to handle an unknown arg, currently kept in argv.

Should a lonesome hyphen be a permited value as not an option. Currently kept in argv in case the program wants it, such as indicating stdin or stdout.

For an arg to a short arg, e.g. -C -d, will put -d as the value for -C so long as -C is not a Boolean. Should it be an error?

CAVEAT EMPTOR

It's new, not well tested, etc...

BUGS

If an option is considered optional, then with the short name, the next value is not checked for at all. If it's not optional, it's checked and all's well, as described for obj."type"().

Not positive this is a bug... And relates to the -f -b issue where if the argument to -f is required, it will be given '-b'.

Bundling of options will only work for Boolean options. So my little "perl pie" annoyance isn't handled, perl -pie "code", although perl doesn't handle it in a DWIM manner...

And it doesn't have good error correction....

AUTHOR

Joshua Isom - loneowl@ritalin.shout.net