NAME
    CmdArguments - Module to process arguments passed on command line

SYNOPSIS
        # program name args.pl
        use CmdArguments;

        my $var1 = 10;          # initialize variable
        my $var2 = 0;           # with default values.
        my @var3 = ( 1, 2, 3);  # well, if you like to.
        my @var4;               # but, not necessary

        my $parse_ref = [
                         [ "arg1", \$var1 ], # argTypeScalar is assumed
                         [ "arg2", \$var2,
                           {TYPE => argTypeSwitch}], # explicit argTypeSwitch
                         [ "arg3", \@var3 ], # argTypeArray assumed
                         [ "arg4", \@var4,
                           {UNIQUE => 1}], # argTypeArray assumed
                        ];

        CmdArguments::parse(@ARGV, $parse_ref);

        print "var1 = $var1\n";
        print "var2 = $var2\n";
        print "var3 = @var3\n";
        print "var4 = @var4\n";

        exit 0;

    test command ...

        args.pl -arg1 23 -arg2 -arg3 2 4 3 2 5 -arg4 2 4 3 2 4

    should generate following output...

        var1 = 23
        var2 = 1
        var3 = 2 4 3 2 5
        var4 = 2 4 3

DESCRIPTION
    This module provides some handy functions to process command line
    options.

    When this module is included it introduces following constants in the
    calling program namespace...

        argTypeScalar = 0
        argTypeArray  = 1
        argTypeSwitch = 2

    CmdArguments::parse
     Simplest way to use this program is to call parse (static function).

     Calling syntax is...

     *parse(@arguments, $array_ref, *$text_or_func1*, *$text_or_func2*)*

     *@arguments*
       array of command line arguments. So, @ARGV could be passed instead.

     *$array_ref*
       reference to an array containing information about how to parse data
       in @arguments.

       basic structure of $array_ref is...

       $array_ref = [ *$array_ref_for_individual_tag*, ...];

       $array_ref_for_individual_tag = [*$option_tag* , *$ref_of_variable*,
       *$hash_ref*]; # $hash_ref is optional

       *$hash_ref*
          reference to a hash containing supplementary information about
          $option_tag

            $hash_ref = {
              TYPE   => argType..., # argTypeSwitch
                                    # argTypeArray or argTypeScalar

              UNIQUE => 1,          # 1 or 0

              USAGE  => "help information", # try giving -h or -help
                                            # on command line

              FUNC   => sub { eval $_[0] }
            };

          TYPE
              this specifies what kind of variable reference is passed in
              $ref_of_variable. If TYPE is argTypeScalar or argTypeSwitch it
              assumes reference to a scalar. If TYPE is argTypeArray it
              assumes reference to an array.

              if TYPE tag is not provided then ...

              1. *argTypeScalar* is assumed if $ref_of_variable is a scalar
              reference

              2. *argTypeArray* is assumed if $ref_of_variable is an array
              reference

              What is argType...?

                   argTypeSwitch
                         on command line you can not provide value for an
                         option.

                   argTypeScalar
                         on command line you must provide one and only one
                         value

                   argTypeArray
                         on command line you can provide zero or more values

          UNIQUE
              this tag is applicable for option type *argTypeArray* only. it
              can be 0 or 1. 1 means make unique array. So, if an option is
              defined as UNIQUE then on command line if you give say 2 3 4 5
              3 4 6 7 then array will hold 2 3 4 5 6 7. If it was not unique
              then it will hold 2 3 4 5 3 4 6 7.

          FUNC
              Holds a reference to a function. Function should take a scalar
              argument and return a scalar if option is argTypeScalar and
              return an array if option is argTypeArray. This is not used
              for option type argTypeSwitch.

              Example: if option type is an argTypeArray. and function is
              defined like

              FUNC => sub { eval $_[0] }

              and if on the command line something like 1..3 or 1,2,3 is
              passed then it will generate an array having values 1 2 3.

       *$ref_of_variable*
          Can pass reference of a scalar or an array variable depending on
          what require from command line.

       *$option_tag*
          It is the name of the option tag. if option tag is *opt* then on
          command line you have to specify option like *-opt*.

     $text_or_func1
     $text_or_func2
       pass text or reference to a function. If function is passed it should
       return text or should itself print message on STDERR. Try
       experimenting by passing -h or -help in the argument. $text_or_func1
       is printed after the help text is printed and $text_or_func1 is used
       before printing helptext.

AUTHOR
    Navneet Kumar, <navneet_k@hotmail.com>