.\" 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 3"
.TH Class::AutoClass 3 "2006-04-06" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.Vb 2
\&    1) get and set methods for simple attributes can be automatically
\&    generated
.Ve
.PP
.Vb 1
\&    2) argument lists are handled as described below
.Ve
.PP
.Vb 3
\&    3) the protocol for object creation and initialization is close to
\&    the 'textbook' approach generally suggested for object-oriented Perl
\&    (see below)
.Ve
.PP
.Vb 1
\&    4) object initialization is handled correctly in the presence of multiple inheritance
.Ve
.PP
.Vb 5
\&    @AUTO_ATTRIBUTES is a list of 'attribute' names: get and set methods
\&    are created for each attribute.  By default, the name of the method
\&    is identical to the attribute (but see $CASE below).  Values of
\&    attributes can be set via the 'new' constructor, %DEFAULTS, or the 
\&    'set' method as discussed below.
.Ve
.PP
.Vb 10
\&    @CLASS_ATTRIBUTES is a list of class attributes: get and set methods
\&    are created for each attribute. By default, the name of the method
\&    is identical to the attribute (but see $CASE below). Values of
\&    attributes can be set via the 'new' constructor, %DEFAULTS (initialized 
\&    at "declare time" (when the declare function is called) versus instance
\&    attributes, which are of course initialized at runtime), standard 
\&    class variable access syntax ($PackageName::AttributeName), or the 
\&    'set' method as discussed below. Normal inheritance rules apply to
\&    class attributes (but of course, instances of the same class share
\&        the same class variable).
.Ve
.PP
.Vb 3
\&    @OTHER_ATTRIBUTES is a list of attributes for which get and set
\&    methods are NOT generated, but whose values can be set via the 'new'
\&    constructor or the 'set' method as discussed below.
.Ve
.PP
.Vb 4
\&    %SYNONYMS is a hash that defines synonyms for attribues. Each entry
\&    is of the form 'new_attribute_name'=>'old_attribute_name'. get and
\&    set methods are generated for the new names; these methods simply
\&    call the method for the old name.
.Ve
.PP
.Vb 3
\&    %DEFAULTS is a hash that defines default values for attributes. Each 
\&    entry is of the form 'attribute_name'=>'default_value'. get and
\&    set methods are generated for each attributes.
.Ve
.PP
.Vb 4
\&    $CASE controls whether additional methods are generated with all
\&    upper or all lower case names.  It should be a string containing the
\&    strings 'upper' or 'lower' (case insenstive) if the desired case is
\&    desired.
.Ve
.PP
.Vb 2
\&    The declare function actually generates the method.
\&    This should be called once and no where else.
.Ve
.PP
.Vb 8
\&    AutoClass must be the first class in @ISA !! As usual, you create
\&    objects by calling 'new'. Since AutoClass is the first class in @ISA,
\&    it's 'new' method is the one that's called.  AutoClass's 'new'
\&examines the rest of @ISA and searches for a superclass that is
\&capable of creating the object.  If no such superclass is found,
\&AutoClass creates the object itself.  Once the object is created,
\&AutoClass arranges to have all subclasses run their initialization
\&methods (_init_self) in a top-down order.
.Ve
.Sh "Argument Processing"
.IX Subsection "Argument Processing"
We support positional and keyword argument lists, but we strongly urge 
that each method pick one form or the other, as the combination is inherently ambiguous (see below).
.PP
Consider a method, foo, that takes two arguments, a first name and a
last_name name.  The positional form might be
.PP
.Vb 1
\&  $object->foo('Nat', 'Goodman')
.Ve
.PP
while the keyword form might be
.PP
.Vb 1
\&  $object->foo(first_name=>'Nat', last_name=>'Goodman')
.Ve
.PP
In keyword form, keywords are insensitive to case and leading
dashes: the keywords
.PP
.Vb 1
\&  first_name, -first_name, -FIRST_NAME, --FIRST_NAME, First_Name, -First_Name
.Ve
.PP
are all equivalent.  Internally, for those who care, our convention is
to use uppercase, un-dashed keys for the attributes of an object.
.PP
We convert repeated keyword arguments into an \s-1ARRAY\s0 ref of the values. Thus:
.PP
.Vb 1
\&  $object->foo(first_name=>'Nat', first_name=>'Nathan')
.Ve
.PP
is equivalent to
.PP
.Vb 1
\&  $object->foo(first_name=>['Nat', 'Nathan'])
.Ve
.PP
Keyword arguments can be specified via \s-1ARRAY\s0 or \s-1HASH\s0
refs which are dereferenced back to their elements, e.g.,
.PP
.Vb 1
\&  $object->foo([first_name=>'Nat', last_name=>'Goodman'])
.Ve
.PP
.Vb 1
\&  $object->foo({first_name=>'Nat', last_name=>'Goodman'})
.Ve
.PP
are both equivalent to 
.PP
.Vb 1
\&  $object->foo(first_name=>'Nat', last_name=>'Goodman')
.Ve
.PP
We can get away with this, because we encourage method writers to
choose between positional and keyword argument lists.  If a method
uses positional arguments, it will interpret
.PP
.Vb 1
\&  $object->foo($array)
.Ve
.PP
as a call that is setting the first_name parameter to \f(CW$array\fR, while if
it uses keyword arguments, it will dereference the array to a list of
keyword, value pairs.
.PP
We also allow the argument list to be an object.  This is often used
in new to accomplish what a \*(C+ programmer would call a cast.  In
simple cases, the object is just treated as a \s-1HASH\s0 ref and its
attributes are passed to a the method as keyword, value pairs.
.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
\&  $object->foo(first_name=>'Nat', last_name=>'Goodman')
.Ve
.PP
is completely equivalent to 
.PP
.Vb 1
\&  $object->foo('first_name', 'Nat', 'last_name', 'Goodman')
.Ve
.PP
The ambiguity of allowing both positional and keyword forms should now
be apparent. In this example,
.PP
.Vb 1
\&  $object->foo('first_name', 'Nat')
.Ve
.PP
there is s no way to tell whether the program is calling foo with the
first_name parameter set to the value 'first_name' and the last_name
parameter set to 'Nat', vs. calling foo with the first_name parameter
set to 'Nat' and the last_name parameter left undefined.
.PP
If a program wishes to permit both forms, we suggest that keywords be 
required to start with '\-' (and that values do not start with '\-').  
Obviously, this is not fully general. We provide a method, _is_positional, 
that checks this convention. Subclasses are free to ignore this.
.Sh "Protocol for Object Creation and Initializaton"
.IX Subsection "Protocol for Object Creation and Initializaton"
We expect objects to be created by invoking new on its class.  For example
.PP
.Vb 1
\&  $object = new SomeClass(first=>'Nat', last=>'Goodman')
.Ve
.PP
To correctly initialize objects that participate in multiple inheritance, 
we use a technqiue described in Chapter 10 of Paul Fenwick's excellent 
    tutorial on Object Oriented Perl (see http://perltraining.com.au/notes/perloo.pdf).  
(We experimented with Damian Conway's interesting \s-1NEXT\s0
pseudo-pseudo-class discussed in Chapter 11 of Fenwick's tutorial
 available in \s-1CPAN\s0 at http://search.cpan.org/author/DCONWAY/NEXT\-0.50/lib/NEXT.pm, 
 but could not get it to traverse the inheritance structure in the correct,
 top-down order.)
.PP
.Vb 8
\&    AutoClass class provides a 'new' method that expects a keyword argument
\&    list.  This method processes the argument list as discussed in
\&    L<Argument Processing>: it figures out the syntactic form (list of
\&                                                               keyword, value pairs, vs. ARRAY ref vs. HASH ref, etc.).  It then
\&    converts the argument list into a canonical form, which is a list of
\&    keyword, value pairs with all keywords uppercased and de-dashed.  Once
\&    the argument list is in this form, subsequent code treats it as a HASH
\&    ref.
.Ve
.PP
AutoClass::new initializes the object's class structure from top to
bottom, and is careful to initialize each class exactly once even in
the presence of multiple inheritance.  The net effect is that objects
are initialized top-down as expected; a subclass object can assume
that all superior classes are initialized by the time subclass
initialization occurs.
.PP
AutoClass automatically initializes attributes and synonyms declared
when the class is defined.  If additional initialization is required,
the class writer can provide an _init_self method.  _init_self is
called after all superclasses are initialized and after the automatic
initialization for the class has been done.
.PP
AutoClass initializes attributes and synonyms by calling the set methods
for these elements with the like-named parameter \*(-- it does not simply
slam the parameter into a slot in the object''s \s-1HASH\s0.  This allows the
class writer implement non-standard initialization within the set
method.
.PP
The main case where a subclass needs its own 'new' method is if it
wishes to allow positional arguments. In this case, the subclass 'new'
is responsible for is responsible for recognizing that positional
arguments are being used (if the class permits keyword arguments
also), and converting the positional arguments into keyword, value
form.  At this point, the method can simply call AutoClass::new with
the converted argument list.
.PP
The subclass should not generally call SUPER::new as this would force
redundant argument processing in any super-class that also has its own
new.  It would also force the super-class new to be smart enough to
handle positional as well as keyword parameters, which as we've noted
    is inherently ambiguous.
.PP
.Vb 1
\&    =head1 KNOWN BUGS AND CAVEATS
.Ve
.PP
.Vb 1
\&    This is still a work in progress.
.Ve
.PP
.Vb 1
\&    =head2 Bugs, Caveats, and ToDos
.Ve
.PP
.Vb 3
\&    1) There is no way to manipulate the arguments that are sent to the
\&    real base class. There should be a way to specify a subroutine that
\&    reformats these if needed.
.Ve
.PP
.Vb 1
\&    2) DESTROY not handled
.Ve
.PP
.Vb 3
\&    3) Autogeneration of methods is hand crafted.  It may be better to
\&    use Class::MakeMethods or Damian Conway's Multimethod class for
\&  doing signature-based method dispatch
.Ve
.PP
.Vb 3
\&  4) Caveat: In order to specify that a class that uses AutoClass should return
\&  undef (versus an uninitialized (but blessed) object), one need to set:
\&  $self->{__NULLIFY__}=1;
.Ve
.SH "AUTHOR \- Nat Goodman"
.IX Header "AUTHOR - Nat Goodman"
Email natg@shore.net
.SH "MAINTAINER \- Christopher Cavnor"
.IX Header "MAINTAINER - Christopher Cavnor"
Email ccavnor@systemsbiology.net
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2003 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 "new"
.IX Subsection "new"
.Vb 8
\& Title   : new
\& Usage   : $object=new Foo(first_name=>'Nat', last_name=>'Goodman')
\&           where Foo is a subclass of AutoClass
\& Function: Create and initialize object
\& Returns : New object of class $class
\& Args    : Any arguments needed by subclasses
\&         -->> Arguments must be in keyword form.  See DESCRIPTION for more.
\& Notes   : Tries to invoke superclass to actually create the object
.Ve
.Sh "_init"
.IX Subsection "_init"
.Vb 9
\& Title   : _init
\& Usage   : $self->_init($class,$args)
\& Function: Initialize new object
\& Returns : nothing useful
\& Args    : $class -- lexical (static) class being initialized, not the
\&           actual (dynamic) class of $self
\&           $arg -- argument list in canonical keyword form
\& Notes   : Adapted from Chapter 10 of Paul Fenwick''s excellent tutorial on 
\&           Object Oriented Perl (see http://perltraining.com.au/notes/perloo.pdf).
.Ve
.Sh "set"
.IX Subsection "set"
.Vb 5
\& Title   : set
\& Usage   : $self->set(-first_name=>'Nat',-last_name=>'Goodman')
\& Function: Set multiple attributes in existing object
\& Args    : Parameter list in same format as for new
\& Returns : nothing
.Ve
.Sh "set_attributes"
.IX Subsection "set_attributes"
.Vb 7
\& Title   : set_attributes
\& Usage   : $self->set_attributes([qw(first_name last_name)],$args)
\& Function: Set multiple attributes from a Class::AutoClass::Args object
\&           Any attribute value that is present in $args is set
\& Args    : ARRAY ref of attributes
\&           Class::AutoClass::Args object
\& Returns : nothing
.Ve
.Sh "get"
.IX Subsection "get"
.Vb 5
\& Title   : get
\& Usage   : ($first,$last)=$self->get(qw(-first_name,-last_name))
\& Function: Get values for multiple attributes
\& Args    : Attribute names
\& Returns : List of attribute values
.Ve
.Sh "\s-1AUTO_ATTRIBUTES\s0"
.IX Subsection "AUTO_ATTRIBUTES"
.Vb 9
\& Title   : AUTO_ATTRIBUTES
\& Usage   : @auto_attributes=AUTO_ATTRIBUTES('SubClass')
\&           @auto_attributes=$self->AUTO_ATTRIBUTES();
\& Function: Get @AUTO_ATTRIBUTES for lexical class.
\&           @AUTO_ATTRIBUTES is defined by class writer. These are attributes for which get and set methods
\&           are automatically generated.  _init automatically
\&           initializes these attributes from like-named parameters in
\&           the argument list
\& Args : class
.Ve
.Sh "\s-1OTHER_ATTRIBUTES\s0"
.IX Subsection "OTHER_ATTRIBUTES"
.Vb 9
\& Title   : OTHER_ATTRIBUTES
\& Usage   : @other_attributes=OTHER_ATTRIBUTES('SubClass')
\&           @other_attributes=$self->OTHER_ATTRIBUTES();
\& Function: Get @OTHER_ATTRIBUTES for lexical class.
\&           @OTHER_ATTRIBUTES is defined by class writer. These are attributes for which get and set methods
\&           are not automatically generated.  _init automatically
\&           initializes these attributes from like-named parameters in
\&           the argument list
\& Args : class
.Ve
.Sh "\s-1SYNONYMS\s0"
.IX Subsection "SYNONYMS"
.Vb 10
\& Title   : SYNONYMS
\& Usage   : %synonyms=SYNONYMS('SubClass')
\&           %synonyms=$self->SYNONYMS();
\& Function: Get %SYNONYMS for lexical class.
\&           %SYNONYMS is defined by class writer. These are alternate names for attributes generally
\&           defined in superclasses.  get and set methods are
\&           automatically generated.  _init automatically initializes
\&           these attributes from like-named parameters in the argument
\&           list
\& Args : class
.Ve
.Sh "declare"
.IX Subsection "declare"
.Vb 13
\& Title   : declare
\& Usage   : @AUTO_ATTRIBUTES=qw(sex address dob);
\&           @OTHER_ATTRIBUTES=qw(age);
\&           %SYNONYMS=(name=>'id');
\&               AutoClass::declare(__PACKAGE__,'lower|upper');
\& Function: Generate get and set methods for simple attributes and synonyms.
\&           Method names are identical to the attribute names including case
\& Returns : nothing
\& Args    : lexical class being created -- should always be __PACKAGE__
\&           ARRAY ref of attributes
\&           HASH ref of synonyms. Keys are new names, values are old
\&           code that indicates whether method should also be generated
\&            with all lower or upper case names
.Ve
.Sh "_enumerate"
.IX Subsection "_enumerate"
.Vb 5
\& Title   : _enumerate
\& Usage   : _enumerate($class);
\& Function: locates classes that have a callable constructor
\& Args    : a class reference
\& Returns : list of internal classes, a class with a callable constructor
.Ve
.Sh "_fix_args"
.IX Subsection "_fix_args"
.Vb 3
\& Title   : _fix_args
\& Usage   : $args=_fix_args(-name=>'Nat',-name=>Goodman,address=>'Seattle')
\&           $args=$self->_fix_args(@args)
.Ve
.PP
.Vb 8
\& Function: Convert argument list into canonical form.  This is a HASH ref in 
\&           which keys are uppercase with no leading dash, and repeated
\&           keyword arguments are merged into an ARRAY ref.  In the
\&           example above, the argument list would be converted to this
\&           hash
\&              (NAME=>['Nat', 'Goodman'],ADDRESS=>'Seattle')
\& Returns : argument list in canonical form
\& Args    : argument list in any keyword form
.Ve
.Sh "_fix_keyword"
.IX Subsection "_fix_keyword"
.Vb 9
\& Title   : _fix_keyword
\& Usage   : $keyword=_fix_keyword('-name')
\&           @keywords=_fix_keyword('-name','-address');
\& Function: Convert a keyword or list of keywords into canonical form. This
\&           is uppercase with no leading dash.  In the example above,
\&           '-name' would be converted to 'NAME'. Non-scalars are left
\&           unchanged.
\& Returns : keyword or list of keywords in canonical form 
\& Args : keyword or list of keywords
.Ve
.Sh "_set_attributes"
.IX Subsection "_set_attributes"
.Vb 12
\& Title   : _set_attributes
\& Usage   :   my %synonyms=SYNONYMS($class);
\&             my $attributes=[AUTO_ATTRIBUTES($class),
\&                             OTHER_ATTRIBUTES($class),
\&                             keys %synonyms];
\&             $self->_set_attributes($attributes,$args);
\& Function: Set a list of simple attributes from a canonical argument list
\& Returns : nothing
\& Args    : $attributes -- ARRAY ref of attributes to be set
\&           $args -- argument list in canonical keyword (hash) form 
\& Notes   : The function calls the set method for each attribute passing 
\&           it the like-named parameter from the argument list
.Ve
.Sh "_is_positional"
.IX Subsection "_is_positional"
.Vb 15
\& Title   : _is_positional
\& Usage  : if (_is_positional(@args)) {
\&             ($arg1,$arg2,$arg3)=@args; 
\&           }
\& Function: Checks whether an argument list conforms to our convention 
\&           for positional arguments. 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
\& Notes   : As explained in DESCRIPTION, we recommend that methods not 
\&           support both positional and keyford argument lists, as this 
\&           is inherently ambiguous.
\& BUGS    : NOT YET TESTED in this version
.Ve
.Sh "set_class_defaults"
.IX Subsection "set_class_defaults"
.Vb 6
\& Title   : set_class_defaults
\& Usage   : $self->set_class_defaults($attributes,$class,$args);
\& Function: Set default values for class argument
\& Args    : reference to the class and a Class::AutoClass::Args object
\&           which contains the arguments to set
\& Returns : nothing
.Ve