.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Class::AutoClass::Args 3"
.TH Class::AutoClass::Args 3 "2006-04-06" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  use Class::AutoClass::Args;
\&  my $args=new Class::AutoClass::Args(name=>'Joe',-sex=>'male',
\&                                      HOBBIES=>'hiking',hobbies=>'cooking');
.Ve
.PP
.Vb 4
\&  # access argument values as HASH slots
\&  my $name=$args->{name};
\&  my $sex=$args->{sex};
\&  my $hobbies=$args->{hobbies};
.Ve
.PP
.Vb 4
\&  # access argument values via methods
\&  my $name=$args->name;
\&  my $sex=$args->sex;
\&  my $hobbies=$args->hobbies;
.Ve
.PP
.Vb 3
\&  # set local variables from argument values -- two equivalent ways
\&  my($name,$sex,$hobbies)=$args->get_args(qw(name sex hobbies));
\&  my($name,$sex,$hobbies)=@$args{qw(name sex hobbies)}
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class simplifies the handling of keyword argument lists.
.PP
The 'new' method accepts an array, \s-1ARRAY\s0, or \s-1HASH\s0 of keyword=>value
pairs. It normalizes the keywords to ignore case and leading dashes
('\-').  In other words, the following keywords are all equivalent:
.PP
.Vb 2
\&  first_name, -first_name, -FIRST_NAME, --FIRST_NAME, First_Name,
\&  -First_Name
.Ve
.PP
Internally  we convert keywords to lowercase with no leading dash.
.PP
Repeated keyword arguments are converted into an \s-1ARRAY\s0 of the values.
Thus
.PP
.Vb 1
\& new Class::AutoClass::Args(first_name=>'Joe', first_name=>'Joseph')
.Ve
.PP
is equivalent to
.PP
.Vb 1
\&  new Class::AutoClass::Args(first_name=>['Joe', 'Joseph'])
.Ve
.PP
Since argument lists can be provided as ARRAYs or HASHes, the following
.PP
.Vb 2
\&   new Class::AutoClass::Args([first_name=>'John', last_name=>'Doe'])
\&   new Class::AutoClass::Args({first_name=>'John', last_name=>'Doe'})
.Ve
.PP
are both equivalent to 
.PP
.Vb 1
\&   new Class::AutoClass::Args(first_name=>'John', last_name=>'Doe')
.Ve
.SH "KNOWN BUGS AND CAVEATS"
.IX Header "KNOWN BUGS AND CAVEATS"
This is still a work in progress.  
.Sh "Bugs, Caveats, and ToDos"
.IX Subsection "Bugs, Caveats, and ToDos"
See caveats about accessing arguments via AUTOLOADed methods.
.SH "AUTHOR \- Nat Goodman, Chris Cavnor"
.IX Header "AUTHOR - Nat Goodman, Chris Cavnor"
Email natg@shore.net
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2004 Institute for Systems Biology (\s-1ISB\s0). All Rights Reserved.
.PP
This module is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation describes the methods.  Note that
internal methods are preceded with _
.Sh "Constructors"
.IX Subsection "Constructors"
.Vb 14
\& Title   : new
\& Usage   : $args=new Class::AutoClass::Args
\&              (name=>'Joe',-sex=>'male',HOBBIES=>'hiking',hobbies=>'cooking')
\&           -- OR --
\&          $args=new Class::AutoClass::Args
\&              ([name=>'Joe',-sex=>'male',HOBBIES=>'hiking',hobbies=>'cooking'])
\&           -- OR --
\&          $args=new Class::AutoClass::Args
\&              ({name=>'Joe',-sex=>'male',HOBBIES=>'hiking',hobbies=>'cooking'})
\& Function: Create a normalized argument list
\& Returns : Class::AutoClass::Args object that represents the given arguments
\& Args    : Argument list in keyword=>value form
\&           This can be an array (as in form 1 above).  This is the ususal case.
\&           Or it can be a single ARRAY or HASH as in forms 2 and 3
.Ve
.Sh "Getting and setting argument values from object"
.IX Subsection "Getting and setting argument values from object"
One simple way to get and set argument values is to treat the object
as a \s-1HASH\s0 and access the argument as a hash entry, eg,
.PP
$name=$args\->{name};
\&\f(CW$args\fR\->{name}='Joseph'.
.PP
While this approach is generally frowned upon in object-oriented
programming (because it breaks object encapsulation), we deem it to be
acceptable here since AutoArgs is such a lightweight class and its
very purpose is to _simplify_ access to argument lists.  Bear in mind
that the hash key you use must be normalized per our rules: lowercase
with no leading dashes.  The fix_keyword method is provided to
accomplish this if you need it.
.PP
A second simple approach is to invoke a method with the name of the
keyword.  Eg,
.PP
$args\->name;
\&\f(CW$args\fR\->name('Joseph');   # sets name to 'Joseph'
.PP
The method name is normalized exactly as in 'new'.
.PP
\&\s-1CAVEAT:\s0 The second approach uses \s-1AUTOLOAD\s0 to simulate the existence of
a method with the same name as the keyword.  This will not work if
AutoArgs contains a method with that name.  For example 'new'.  One
solution is to use uppercase names for methods.  Or you can use the
first approach and just access the data directly.
.PP
The class also provides two methods for wholesale manipulation of arguments.
.PP
.Vb 5
\& Title   : get_args
\& Usage   : ($first,$last)=$args->get_args(qw(-first_name last_name))
\& Function: Get values for multiple keywords
\& Args    : array or ARRAY of keywords. These are normalized exactly as in 'new'
\& Returns : array or ARRAY of attribute values
.Ve
.PP
.Vb 5
\& Title   : set_args
\& Usage   : $args->set_args(-first_name=>'John',-last_name=>'Doe')
\& Function: Set multiple attributes in existing object
\& Args    : Parameter list in same format as for 'new'
\& Returns : nothing
.Ve
.PP
.Vb 5
\&  Title   : getall_args
\& Usage   : %args=$args->get_args;
\& Function: Get a list of all key,values
\& Args    : none
\& Returns : hash or HASH of key, value pairs.
.Ve
.PP
.Vb 5
\& Title   : set_args
\& Usage   : $args->set_args(-first_name=>'John',-last_name=>'Doe')
\& Function: Set multiple attributes in existing object
\& Args    : Parameter list in same format as for 'new'
\& Returns : nothing
.Ve
.Sh "Methods to normalize keywords.  These are class methods"
.IX Subsection "Methods to normalize keywords.  These are class methods"
These methods normalize keywords as explained in the \s-1DESCRIPTION\s0.  
.PP
.Vb 7
\& Title   : fix_keyword
\& Usage   : $keyword=Class::AutoClass::Args::fix_keyword('-NaMe')
\&           -- OR --
\&           @keywords=Class::AutoClass::Args::fix_keyword('-NaMe','---sex');
\& Function: Normalizes each keyword to lowercase with no leading dashes.
\& Args    : array of one or more strings
\& Returns : array of normalized strings
.Ve
.PP
.Vb 7
\& Title   : fix_keywords
\& Usage   : $keyword=Class::AutoClass::Args::fix_keywords('-NaMe')
\&           -- OR --
\&           @keywords=Class::AutoClass::Args::fix_keywords('-NaMe','---sex');
\& Function: Synonym for fix_keyword
\& Args    : array of one or more strings
\& Returns : array of normalized strings
.Ve
.Sh "Methods to check format of argument list. These are class methods."
.IX Subsection "Methods to check format of argument list. These are class methods."
These following methods can be used in a class (typically it's 'new'
method) that wishes to support both keyword and positional argument
lists.  We strongly discourage this for the reasons discussed below.
.PP
.Vb 11
\& Title   : is_keyword
\& Usage   : if (Class::AutoClass::Args::is_keyword(@args)) {
\&             $args=new Class::AutoClass::Args::is_keyword(@args);
\&           }
\& Function: Checks whether an argument list looks like it is in keyword form.
\&           The function returns true if 
\&           (1) the argument list has an even number of elements, and
\&           (2) the first argument starts with a dash ('-').
\&           Obviously, this is not fully general.
\& Returns : boolean
\& Args    : argument list as given
.Ve
.PP
.Vb 11
\& Title   : is_positional
\& Usage  : if (Class::AutoClass::Argsis_positional(@args)) {
\&             ($arg1,$arg2,$arg3)=@args; 
\&           }
\& Function: Checks whether an argument list looks like it is in positional form.
\&           The function returns true if 
\&           (1) the argument list has an odd number of elements, or
\&           (2) the first argument starts with a dash ('-').
\&           Obviously, this is not fully general.
\& Returns : boolean
\& Args    : argument list as given
.Ve
.Sh "Why the Combination of Positional and Keyword Forms is Ambiguous"
.IX Subsection "Why the Combination of Positional and Keyword Forms is Ambiguous"
The keyword => value notation is just a Perl shorthand for stating two
list members with the first one quoted.  Thus,
.PP
.Vb 1
\&  @list=(first_name=>'John', last_name=>'Doe')
.Ve
.PP
is completely equivalent to 
.PP
.Vb 1
\&  @list=('first_name', 'John', 'last_name', 'Doe')
.Ve
.PP
The ambiguity of allowing both positional and keyword forms should now
be apparent. In this example,
.PP
.Vb 1
\&  new Class::AutoClass::Args ('first_name', 'John')
.Ve
.PP
there is s no way to tell whether the program is specifying a keyword
argument list with the parameter 'first_name' set to the value "John'
or a positional argument list with the values ''first_name' and 'John'
being passed to the first two parameters.
.PP
If a program wishes to permit both forms, we suggest the convention
used in BioPerl that keywords be required to start with '\-' (and that
values do not start with '\-').  Obviously, this is not fully general.
.PP
The methods 'is_keyword' and 'is_positional' check  this convention.