Documentation, examples, tutorials and more

<<

NAME

Smash::CommandLineParser - Specialized command line parser for Smash

SYNOPSIS

        use Smash::CommandLineParser qw(parse_options check_required_options);

        my @expected = qw(name=s number=f verbose);
        my @required = qw(name number);

        my ($status, %options) = parse_options(\@expected);
        if ($status != 1) {
                die "Error parsing command-line!";
        }

        my ($cstatus, $missing) = check_required_options(\%options, \@required);
        if ($cstatus != 1) {
                die "Missing argument: $missing";
        }

        printf "name=%s\n", $options{name};
        printf "number=%f\n", $options{number};

DESCRIPTION

Smash::CommandLineParser is an attempt to avoid several lines of code for command-line parsing using Getopt::Long and its robust function GetOptions(). Every script in Smash needs to parse command line and I wanted to make it a simpler process. The design is simple:

  1. command line arguments should populate a hash

  2. option name-value pairs should be converted to hash key-value pairs

  3. a list of expected options should be sent to the parser, so it can ignore others

  4. for this list of expected options, they should exist in the hash even if no value was specified in the command line (this is to avoid an exists() check on every option to be clean)

  5. (optionally) a list of required options can be tested for their presence in the hash

  6. the caller function should know if every call went ok

Smash::CommandLineParser implements it in a series of functions described below.

FUNCTIONS

parse_options

This function takes a (reference to a) list of allowed options and parses the command line and creates a hash where the option name-value pairs are converted into key-value pairs. It is analogous to a similar option in Getopt::Long where you pass a reference to a hash to GetOptions, but slightly better since it brings to existence an entry for every option in the list. If the option is not set, then the value for that key is undefined, but it still exists. This makes sure that every option can be tested without worrying about testing it with exists() or defined().

Returns a status code (1 for success, and others for failure) and the hash itself. The return values should be handled like so:

        ($status, %options) = parse_options([qw(name=s file=s)]);
check_required_options

This function takes a reference to a list of required options and a reference to a hash. It checks if each of the options is defined in the hash and quits on the first that does not.

It returns a status code (1 for success, 0 if one of the options is missing). The missing options is also returned as the second entry in the return array. For example,

        ($status, $missing) = check_required_options([qw(name=s file=s)], \%options);
will return (0, 'file') if --file was not set in the command line.

print_options

This is a utility function that prints option name-value pairs. Useful for debugging purposes.

<<