NAME

HLL::CommandLine - command line parsing tools

SYNOPSIS

my $parser := HLL::CommandLine::Parser.new([
    'verbose',
    'target=s',
    'e=s'
]);

# treat the first non-option argument as the program name,
# and everything after that as arguments to the program
$parser.stop-after-first-arg;

# -e "program" also treats everything after it as arguments
# to the program:
$paser.add-stopper('-e');

my $results := $parser.parse(@*ARGS);
my %options := $parser.options;
my @args    := $pasre.arguments; # remaining arguments from @*ARGS

DESCRIPTION

HLL::CommandLine::Parser stores a specification of command line options and other behavior, and uses that to parse an array of command line directives.

It classifies the directives as options (usually of the form -f or --foo) and arguments (ie. non-options). The result of a .parse(RPA) call is an HLL::CommandLine::Result object (or an exception thrown), which makes the options and arguments available via the methods options and arguments.

HLL::CommandLine::Parser

new(Array)

The .new method and constructor expects an array with option specifications. Such a specification is the name of an option, optionally followed by the = equals sign and a single character describing the kind of value it expects. Missing value specification or b stand for bool, ie the option does not expect a value. s stands for a string value. Optional values are only supported for string values so far. For the value specified with s? the value will default to ''.

add-stopper(String)

Adds a stopper. A stopper is a special value that, when encountered in the command line arguments, terminates the processing, and classifies the rest of the strings as arguments, independently of their form. -- is a pre-defined stopper. If an option is used a stopper, that option itself is still processed.

Examples:

yourprogram -a --bar b -- c --foo
# options:   a = 1, bar = 1
# arguments: b, c, --foo

# with stopper -e, and -e expecting a value:
yourprogram -a -e foo --bar baz
# options:   -a = 1, -e = foo
# arguments: --bar, baz

parse(Array)

Parses the array as command line strings, and returns a HLL::CommandLine::Result object (or thrown an exception on error).

HLL::CommandLine::Result

An object of this type holds the options and arguments from a successful command line parse.

options

Returns a hash of options

arguments

Return an array of arguments.