NAME
    Params::Smart - use both positional and named arguments in a subroutine

SYNOPSIS
      use Params::Smart;

      sub my_sub {
        %args = Params(qw( foo bar ?bo ?baz ))->args(@_);

        ...
      }

      my_sub( foo=> 1, bar=>2, bo=>3 );  # call with named arguments

      my_sub(1, 2, 3);                   # same, with positional args

DESCRIPTION
    This module allows you to have subroutines which take both named and
    positional arguments without having to use a changed syntax and source
    filters.

    Usage is as follows:

      %values = Params( @template )->( @args );

    @template specifies the names of parameters in the order that they
    should be given in subroutine calls. @args is the list of argument to be
    parsed: usually you just specify the void list @_.

        Paramaters are required by default. To change this behavior, add the
        following symbols before the names:

    ?   The parameter is optional, e.g. "?name".

    +   The parameter must only be specified as a named parameter. Note that
        it is not necessarily optional. You must explicitly state that, e.g.
        "+?name".

    *   The parameter "slurps" the rest of the arguments into an array
        reference, e.g. *name. It is not assumed to be optional unless there
        is a question-mark before it.

    %values contains the keys of specified arguments, with their values. It
    may also contain additional keys which begin with an underscore. These
    are internal/diagnostic values:

    _named
        True if the parameters were treated as named, false if positional.

CAVEATS
    *This is an experimental module, and the interface may change.* More
    likely additional features will be added.

    Because Perl5 treats hashes as lists, this module attempts to interpret
    the arguments as a hash of named parameters first. If some hash keys
    match, and some do not, then it assumes there has been an error. If no
    keys match, then it assumes that it the arguments are positional.

    In theory one can pass positional arguments where every other argument
    matches a hash key, or one can pass a hash with the wrong keys (possible
    if one copies/pastes code from the wrong call) and so it is treated as a
    positional argument.

    This is probably uncommon for most data, but subroutines should take
    extra care to check if values are within allowed ranges. There may even
    be security issues if users can blindly specify data that they know can
    cause this confusion. If the application is critical enough, then this
    may not be an appropriate module to use (at least not until the ability
    to distinguish between lists and hashes is improved).

    To diagnose potential bugs, or to enforce named or positional calling
    one can check the "_named" parameter.

SEE ALSO
    This module is similar in function to Getargs::Mixed but does not
    require named parameters to have an initial dash ('-'). It also has some
    additional features.

    The syntax of the paramater templates is inspired by Perl6::Subs, though
    not necessarily compatible. (See also *Apocalypse 6* in Perl6::Bible).

    Params::Validate is useful for (additional) parameter validation beyond
    what this module is capable of.

AUTHOR
    Robert Rothenberg <rrwo at cpan.org>

  Suggestions and Bug Reporting
    Feedback is always welcome. Please use the CPAN Request Tracker at
    <http://rt.cpan.org> to submit bug reports.

LICENSE
    Copyright (c) 2005 Robert Rothenberg. All rights reserved. This program
    is free software; you can redistribute it and/or modify it under the
    same terms as Perl itself.