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