NAME

Popt.xs

DESCRIPTION

Most people won't care about the internals, but for the sake of completness, here's what's going on:

struct poptContext_wrapper

This is a wrapper to hold the argv and options arrays.

• need to free the allocated arrays and keep their scalar refcounts accurate, because I think popt returns pointers to positions within the string?
• need to make a contiguous array of struct poptOptions to pass to popt, assembled out of the non-contiguous array of Getopt::Popt::Options
• need to hack at the copied options array to strip off argInfo bitop flags (see _new_blessed_poptContext() and _assign_argref())
• need to keep aliases around because their argv's are still used by popt, even if the alias object is undef'd and destroyed

struct poptAlias_wrapper

This wrapper holds the argv array so its refcount stays above 0. Stored as a scalar ref and blessed into Getopt::Popt::Alias

_new_blessed_poptAlias(xclass, longName, shortName, argv)

NOTE: parameters are expected to be validated before this function gets called, although some validation is performed.

_new_blessed_poptOption(xclass, longName, shortName, argInfo, arg, val, descrip, argDescrip)

Create a new poptOption struct; the tricky part here is creating arg based on argInfo.

NOTE: parameters are expected to be validated before this function gets called, although some validation is performed.

_assign_argref(self)

$self - blessed Getopt::Popt::Option

Called from a getNextOpt(), which calls the popt function poptGetNextOpt. popt should have assigned arg in the struct poptOption; this method grabs that value and assigns the user's scalar $arg to it.

get*(option_wrapper)

Not a big fan of this mixed-case function name business, especially since this file isn't very consistent; but the precedence has been set by libpopt.

_new_blessed_poptContext(xclass, name, argv, options, flags)

Creates a new popt context.

We need to increment refcounts to argv (because char *'s will probably point into it) and options (because they contain a reference to the scalar we want to assign). Though if somebody messes with elements in those arrays we could end up in a world of hurt, but it'd be their own damn fault.

We assume parameters have been validated before this function gets called, although some validation is performed.

The big hack here has to do with the fact that that popt wants the popt_options in a contiguous C-array of structs, but the perl code stores all that information as an array of scalars. So what we do is copy all the perl options into a new C-array, set the value of that option to the array index of the perl array, and then later in getNextOpt(), figure out where everything goes.

getNextOpt(self)

Perl wrapper to poptGetNextOpt().

stuffArgs(self,...)

Note: will push onto the argv originally passed to Getopt::Popt::new() (does this so that stuffed args won't get garbage collected);

XXX: allocates a _temporary_ char **argv, which may cause problems if popt's implementation changes.

TODO

callbacks, parseArgvString(), dupArgv()