NAME

Getopt::ApacheCommonsCLI - Perl extension for parsing arguments similar to Apache Commons CLI Java library.

SYNOPSIS

DESCRIPTION

Getopt::ApacheCommonsCLI - Perl extension for parsing arguments similar to Apache Commons CLI Java library.

use Getopt::ApacheCommonsCLI qw(GetOptionsApacheCommonsCLI);

http://commons.apache.org/proper/commons-cli/

The Apache Commons CLI Java library implements options parsing according to at least 3 different standards:

- Unix
- POSIX (bundling, enabled with OPTIONS_BUNDLING=1 flag)
- Java (-D options with right-to-left argument precedence, enabled with JAVA_DOPTS=1)

Certainly there will be parsing ambiguities. An example is that single-character option bundling and non-spaced single-character option args can be parsed in multiple ways for the same input.

If you need 100% compatibility, then it would be advisable to use the original Apache Commons CLI Java library. However, if "pretty close" is adequate, then use this module, or consider submitting a bug report or patch.

Also, as the Getopt::Long module says, "Note: Using option bundling can easily lead to unexpected results, especially when mixing long options and bundles. Caveat emptor."

Here are some definitions for the purpose of this module:

- 'single-character option' (ie. -a)
- 'long option' is the longest option name or alias for an option (ie. --password) 
- 'short option' is the shortest option name or alias for an option (usually a single-character option) (ie. -pw)
- 'Java option' is a single-character option starting with '-D' or '--D' and contains '=' (ie. -Dabc=xyz)
- 'bundling' is combining multiple single-character options after a single dash or double dash. (ie. ls -lat)

This Perl module implements:

- options can have both a long and short name
- space or = for trailing option arguments
- allows single-character options to have a non-spaced trailing arg
- options that are seen but don't take an arg have their value set to 1.
- does not enable POSIX single-character options bundling by default, defined in OPTIONS_BUNDLING
- argument assignment precedence is defined in LEFT_TO_RIGHT_ARGS flag, default is from left to right (Java standard is right-to-left)
- Java options parsing is defined with JAVA_DOPTS, default is disabled
- customized error message subroutine for missing args.

For multiple-value arguments, either quote or comma-separate them. Read Getopt::Long documentation for more information.

Input specification format is: "(long-option)|(short-option)[:=]([fios])".

my $result = GetOptionsApacheCommonsCLI(\@spec, \%opts, \%options, \&do_err);

$opts{'__argv__'}   is the string remaining after GetOpt::Long processing.
$opts{'__errors__'} is the list of parsing errors.

%options may contain:

AMBIGUITIES (reserved for future use in disambiguating short option names)
BUNDLING (default=0, enabled=1 activates Getopt::Long's bundling_override)
DEBUG (default=0, enabled=1)
JAVA_DOPTS (default=0, enabled=1, implies post-processing with OPT_PREC_RIGHT_TO_LEFT for matching options)
OPT_PRECEDENCE (default=OPT_PREC_UNIQUE, also OPT_PREC_LEFT_TO_RIGHT and OPT_PREC_RIGHT_TO_LEFT)

EXAMPLE

#!/usr/bin/perl

# Program: nodetool_parser.pl
# Purpose: parse command line arguments like Cassandra nodetool to build a mock object for testing
# Author: James Briggs
# Env: Perl5
# Date: 2014 09 25

use strict;
use diagnostics;

use Getopt::ApacheCommonsCLI qw(GetOptionsApacheCommonsCLI OPT_PREC_UNIQUE OPT_PREC_LEFT_TO_RIGHT OPT_PREC_RIGHT_TO_LEFT);

use Data::Dumper;

  my $DEBUG = 1;

 # input spec format is: "longest-option|(short-option)(:[fios])"

  my @spec = ("include-all-sstables|a",
              "column-family|cf:s",
              "compact|c",
              "in-dc|dc:s",
              "host|h:s",
              "hosts|in-host:s",
              "ignore|i",
              "local|in-local",
              "no-snapshot|ns",
              "parallel|par",
              "partitioner-range|pr",
              "port|p:i",
              "resolve-ip|r",
              "skip-corrupted|s",
              "tag|t:s",
              "tokens|T",
              "username|u:s",
              "password|pw:s",
              "start-token|st:s",
              "end-token|et:s",
  );

  my %opts; # output hash with tokenized long options and args

  my $result = GetOptionsApacheCommonsCLI(\@spec, \%opts, { DEBUG => $DEBUG, JAVA_DOPTS => 0, OPT_PRECEDENCE => OPT_PREC_UNIQUE, BUNDLING => 1, } , \&do_err) ||
     warn "parsing error. see \$opts{__errors__} for a list, ";

  print Dumper(\%opts) if $DEBUG;

sub do_err {
  my ($option, $value) = @_;

  if (not defined $value or $value eq '') {
     print "Missing argument for option:$option\n";
  }
  else {
     print "Incorrect value, precedence or duplicate option for option:$option:$value\n";
  }

  return 0;
}

EXPORT

None by default.

The following symbols can be imported:

GetOptionsApacheCommonsCLI
OPT_PREC_UNIQUE
OPT_PREC_LEFT_TO_RIGHT
OPT_PREC_RIGHT_TO_LEFT

SEE ALSO

Getopt::Long

AUTHOR

James Briggs, <james.briggs@yahoo.com>

COPYRIGHT AND LICENSE

Copyright (C) 2014 by James Briggs

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

cpanm Getopt::ApacheCommonsCLI

perl -MCPAN -e shell
install Getopt::ApacheCommonsCLI