Getargs::Long 0.1
              Copyright (c) 2000-2001, Raphael Manfredi

------------------------------------------------------------------------
   This program is free software; you can redistribute it and/or modify
   it under the terms of the Artistic License, a copy of which can be
   found with perl.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   Artistic License for more details.
------------------------------------------------------------------------

========================================================================
This module is known to exercise a bug in perl 5.6.0.  Don't use that
version of perl: use 5.005_03, or try 5.6.1.

The interface of this module changed between 0.1.2 and 0.1.3, and is
NOT backward compatible.  That's why it's still called alpha software.
========================================================================

      *** This is alpha software -- use at your own risks ***

Name           DSLI  Description                                  Info
-----------    ----  -------------------------------------------- -----
Getargs::
::Long         adpf  Parses long function args f(-arg => value)   RAM

SYNOPSIS

    use Getargs::Long;                     # case sensitive
    use Getargs::Long qw(ignorecase);      # case insensitive

    # Simple, args mandatory
    my ($val, $other) = getargs(@_, qw(val other));

    # Simple, args optional (in [] means optional)
    my ($val, $other) = getargs(@_, [qw(val other)]);

    # Simple with typechecking, args mandatory
    my ($val, $other) = getargs(@_, qw(val=Class::X other=ARRAY));

    # Simple with typechecking, args optional
    my ($val, $other) = getargs(@_, [qw(val=Class::X other=ARRAY)]);

    # Faster version, building dedicated argument parsing routine
    my ($val, $other) = cgetargs(@_, qw(val other));

    # Other cases, use full specs:
    my ($x, $y, $z, $a, $b, $c) = xgetargs(@_,

       # Non-mandatory, defaults to undef unless specified otherwise
       'x'     => ['i'],                   # integer, no default
       'y'     => ['ARRAY', ['a', 'b']],   # Has a default
       'z'     => [],                      # No typecheck, can be anything

       # Mandatory arguments
       'a'     => 'i',                     # integer (scalar)
       'b'     => 'TYPE',                  # TYPE or any heir of TYPE
       'c'     => undef,                   # unspecified type but mandatory
    );

    # Extract remaining unparsed args in @extra
    my ($val, $other, @extra) = getargs(@_, { -strict => 0 }, qw(val other));

    # Alter behaviour of the getargs() routines via switches in hashref
    my ($val, $other) = getargs(@_,
       {
           -strict         => 1,       # unknown switches are fatal
           -ignorecase     => 1,       # override package's global
           -inplace        => 1,       # edit @_ inplace: remove parsed args
           -extra          => 0,       # suppress return of extra arguments
       },
       qw(val other)
    );

DESCRIPTION

Instead of duplicating the manual page, and because examples are better than
a long explaination, here are examples for common cases, showing the routine
argument sepecification and how various calling sequences are interpreted
by those specifications.

Example 1 -- All mandatory:

  sub f {
      my ($port, $server) = getargs(@_,
          qw(port=i server=HTTP::Server));
  }

  f(-server => $server, port => 80);  # or -port, since - is optional
  f(port => 80, server => $server);
  f(server => $server);               # WRONG: missing mandatory -port
  f(server => 80, port => 80);        # WRONG: -server not an HTTP::Server
  f(server => undef, port => 80);     # WRONG: -server cannot be undef

Example 2 -- All optional

  sub cmd {
      my ($a, $o) = getargs(@_, [qw(a o=s)]);
  }

  cmd();                      # OK
  cmd(-a => undef);           # OK -a accepts anything, even undef
  cmd(-a => 1, -o => "..");   # OK
  cmd(-a => 1, -o => undef);  # WRONG: -o does not accept undef
  cmd(-x => 1);               # WRONG: -x is not a known argument name

Example 3  -- Mixed optional / mandatory

  sub f {
      my ($x, $z) = xgetargs(@_,
          -x  => 'i',                 # -x mandatory integer
          -z  => ['n', -20.4],        # -z optional, defaults to -20.4
      );
  }

  f(x => 1, z => {});     # WRONG: z is not a numerical value
  f(z => 1, x => -2);     # OK
  f(-z => 1);             # WRONG: mandatory x is missing
  f(-z => undef);         # WRONG: z cannot be undef

Example 4 -- Parsing options

  sub f {
      my ($x, $z) = xgetargs(@_,
          { -strict => 0, -ignorecase => 1 },
          -x  => 'i',                 # -x mandatory integer
          -z  => ['n', -20.4],        # -z optional, defaults to -20.4
      );
  }

  f(x => 1, foo => {});   # OK, -foo ignored since not strict
  f(-X => 1);             # OK, -X actually specifies -x with ignorecase

-- Raphael Manfredi <[email protected]>

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.