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.
"foo|f"
A long option of "foo" and a short option of "f" is set to Boolean.
"foo"
A long option of "foo" is set to Boolean.
"f"
A short option of "f" is set to Boolean.
"f=s"
A short option of "f" is set to String. Use i for Integer, f for Float, @ for an Array, and % for a Hash.
"foo:s"
A long option of "foo" is set to String, with "optarg" set to a true value.
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 correct type.
Boolean
A true/false value, the default.For a short argument, it's simply -f. Groups of Boolean's tied together, such as -foobar, if -f, -o, -b, -a, and -r are all Boolean values, then each will be set. If -f is a Boolean but one of the others is not, an exception is thrown.For a long argument, it takes the form --foo. Usage such as --foo=this or --foo= are allowed, but it just sets it to true, so no difference.
String
A string. This can take the form of --foo=bar, -f bar, or -fbar.
Integer
An integer, --foo=3.14 is stored as 3. Type conversions are done by Parrot. Same forms as for String.
Float
A float. Same forms apply here as well.
Array
An array, done via multiple arguments. For something such as -I./include -I./src/include for example, I will be an array of ./include and ./src/include. If only used once, it's a one sized array.
Hash
A hash, such as defines. For a short argument, the form is -Dfoo=bar, -Dfoo, and --define=foo=bar(both equal signs required).
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

BUGS

AUTHOR

Joshua Isom - loneowl@ritalin.shout.net

SEE ALSO

The library/Getopt/Long.pir Parrot library.

t/library/getopt_obj.t

COPYRIGHT

Copyright (C) 2006-2008, Parrot Foundation.