1 package Function::Parameters;
11 our $VERSION = '1.00_02';
12 our $XS_VERSION = $VERSION;
13 $VERSION = eval $VERSION;
17 sub _assert_valid_identifier {
18 my ($name, $with_dollar) = @_;
19 my $bonus = $with_dollar ? '\$' : '';
20 $name =~ /^${bonus}[^\W\d]\w*\z/
21 or confess qq{"$name" doesn't look like a valid identifier};
24 sub _assert_valid_attributes {
26 $attrs =~ /^\s*:\s*[^\W\d]\w*\s*(?:(?:\s|:\s*)[^\W\d]\w*\s*)*(?:\(|\z)/
27 or confess qq{"$attrs" doesn't look like valid attributes};
30 my @bare_arms = qw(function method);
34 default_arguments => 1,
35 check_argument_count => 0,
36 named_parameters => 1,
41 default_arguments => 1,
42 check_argument_count => 0,
43 named_parameters => 1,
51 default_arguments => 1,
52 check_argument_count => 0,
53 named_parameters => 1,
55 attributes => ':method',
60 for my $k (keys %type_map) {
61 $type_map{$k . '_strict'} = {
63 check_argument_count => 1,
76 if (@_ == 1 && $_[0] eq ':strict') {
78 fun => 'function_strict',
79 method => 'method_strict',
82 if (@_ == 1 && ref($_[0]) eq 'HASH') {
83 @_ = map [$_, $_[0]{$_}], keys %{$_[0]};
92 : [$proto, $bare_arms[$bare++] || confess(qq{Don't know what to do with "$proto"})]
94 my ($name, $proto_type) = @$item;
95 _assert_valid_identifier $name;
97 unless (ref $proto_type) {
98 # use '||' instead of 'or' to preserve $proto_type in the error message
99 $proto_type = $type_map{$proto_type}
100 || confess qq["$proto_type" doesn't look like a valid type (one of ${\join ', ', sort keys %type_map})];
103 my %type = %$proto_type;
106 $clean{name} = delete $type{name} || 'optional';
107 $clean{name} =~ /^(?:optional|required|prohibited)\z/
108 or confess qq["$clean{name}" doesn't look like a valid name attribute (one of optional, required, prohibited)];
110 $clean{shift} = delete $type{shift} || '';
111 _assert_valid_identifier $clean{shift}, 1 if $clean{shift};
113 $clean{attrs} = join ' ', map delete $type{$_} || (), qw(attributes attrs);
114 _assert_valid_attributes $clean{attrs} if $clean{attrs};
116 $clean{default_arguments} =
117 exists $type{default_arguments}
118 ? !!delete $type{default_arguments}
121 $clean{check_argument_count} = !!delete $type{check_argument_count};
122 $clean{invocant} = !!delete $type{invocant};
123 $clean{named_parameters} = !!delete $type{named_parameters};
124 $clean{types} = !!delete $type{types};
126 %type and confess "Invalid keyword property: @{[keys %type]}";
128 $spec{$name} = \%clean;
131 for my $kw (keys %spec) {
132 my $type = $spec{$kw};
135 $type->{name} eq 'prohibited' ? FLAG_ANON_OK :
136 $type->{name} eq 'required' ? FLAG_NAME_OK :
137 FLAG_ANON_OK | FLAG_NAME_OK
139 $flags |= FLAG_DEFAULT_ARGS if $type->{default_arguments};
140 $flags |= FLAG_CHECK_NARGS | FLAG_CHECK_TARGS if $type->{check_argument_count};
141 $flags |= FLAG_INVOCANT if $type->{invocant};
142 $flags |= FLAG_NAMED_PARAMS if $type->{named_parameters};
143 $flags |= FLAG_TYPES_OK if $type->{types};
144 $^H{HINTK_FLAGS_ . $kw} = $flags;
145 $^H{HINTK_SHIFT_ . $kw} = $type->{shift};
146 $^H{HINTK_ATTRS_ . $kw} = $type->{attrs};
147 $^H{+HINTK_KEYWORDS} .= "$kw ";
155 delete $^H{+HINTK_KEYWORDS};
160 $^H{+HINTK_KEYWORDS} =~ s/(?<![^ ])\Q$kw\E //g;
173 $positional_required,
174 $positional_optional,
182 declarator => $declarator,
183 invocant => defined $invocant ? [$invocant, $invocant_type] : undef,
184 slurpy => defined $slurpy ? [$slurpy , $slurpy_type ] : undef,
185 positional_required => $positional_required,
186 positional_optional => $positional_optional,
187 named_required => $named_required,
188 named_optional => $named_optional,
191 $metadata{$key} = $info;
196 my ($v, $t) = @{$pair || []} or return undef;
197 Function::Parameters::Param->new(
205 while (my ($v, $t) = splice @_, 0, 2) {
206 push @r, Function::Parameters::Param->new(
216 my $key = _cv_root $func or return undef;
217 my $info = $metadata{$key} or return undef;
218 require Function::Parameters::Info;
219 Function::Parameters::Info->new(
220 keyword => $info->{declarator},
221 invocant => _mkparam1($info->{invocant}),
222 slurpy => _mkparam1($info->{slurpy}),
223 (map +("_$_" => _mkparams @{$info->{$_}}), glob '{positional,named}_{required,optional}')
235 Function::Parameters - subroutine definitions with parameter lists
239 use Function::Parameters qw(:strict);
242 fun foo($bar, $baz) {
246 # function with prototype
247 fun mymap($fun, @args)
252 push @res, $fun->($_);
257 print "$_\n" for mymap { $_ * 2 } 1 .. 4;
259 # method with implicit $self
260 method set_name($name) {
261 $self->{name} = $name;
264 # method with explicit invocant
265 method new($class: %init) {
266 return bless { %init }, $class;
269 # function with optional parameters
270 fun search($haystack, $needle = qr/^(?!)/, $offset = 0) {
274 # method with named parameters
275 method resize(:$width, :$height) {
276 $self->{width} = $width;
277 $self->{height} = $height;
280 $obj->resize(height => 4, width => 5);
282 # function with named optional parameters
283 fun search($haystack, :$needle = qr/^(?!)/, :$offset = 0) {
287 my $results = search $text, offset => 200;
291 This module extends Perl with keywords that let you define functions with
292 parameter lists. It uses Perl's L<keyword plugin|perlapi/PL_keyword_plugin>
293 API, so it works reliably and doesn't require a source filter.
297 The anatomy of a function (as recognized by this module):
303 The keyword introducing the function.
307 The function name (optional).
311 The parameter list (optional).
315 The prototype (optional).
319 The attribute list (optional).
329 # (1) (2) (3) (4) (5) (6)
330 fun foo ($x, $y) :($$) :lvalue { ... }
335 In the following section I'm going to describe all parts in order from simplest to most complex.
339 This is just a normal block of statements, as with L<C<sub>|perlsub>. No surprises here.
343 If present, it specifies the name of the function being defined. As with
344 L<C<sub>|perlsub>, if a name is present, the whole declaration is syntactically
345 a statement and its effects are performed at compile time (i.e. at runtime you
346 can call functions whose definitions only occur later in the file). If no name
347 is present, the declaration is an expression that evaluates to a reference to
348 the function in question. No surprises here either.
352 Attributes are relatively unusual in Perl code, but if you want them, they work
353 exactly the same as with L<C<sub>|perlsub/Subroutine-Attributes>.
357 As with L<C<sub>|perlsub/Prototypes>, a prototype, if present, contains hints as to how
358 the compiler should parse calls to this function. This means prototypes have no
359 effect if the function call is compiled before the function declaration has
360 been seen by the compiler or if the function to call is only determined at
361 runtime (e.g. because it's called as a method or through a reference).
363 With L<C<sub>|perlsub>, a prototype comes directly after the function name (if
364 any). C<Function::Parameters> reserves this spot for the
365 L<parameter list|/"Parameter list">. To specify a prototype, put it as the
366 first attribute (e.g. C<fun foo :(&$$)>). This is syntactically unambiguous
367 because normal L<attributes|/Attributes> need a name after the colon.
369 =head3 Parameter list
371 The parameter list is a list of variables enclosed in parentheses, except it's
372 actually a bit more complicated than that. A parameter list can include the
373 following 6 parts, all of which are optional:
379 This is a scalar variable followed by a colon (C<:>) and no comma. If an
380 invocant is present in the parameter list, the first element of
381 L<C<@_>|perlvar/@ARG> is automatically L<C<shift>ed|perlfunc/shift> off and
382 placed in this variable. This is intended for methods:
384 method new($class: %init) {
385 return bless { %init }, $class;
388 method throw($self:) {
392 =item 2. Required positional parameters
394 The most common kind of parameter. This is simply a comma-separated list of
395 scalars, which are filled from left to right with the arguments that the caller
404 =item 3. Optional positional parameters
406 Parameters can be marked as optional by putting an equals sign (C<=>) and an
407 expression (the "default argument") after them. If no corresponding argument is
408 passed in by the caller, the default argument will be used to initialize the
411 fun scale($base, $factor = 2) {
412 return $base * $factor;
415 say scale(3, 5); # "15"
418 The default argument is I<not> cached. Every time a function is called with
419 some optional arguments missing, the corresponding default arguments are
420 evaluated from left to right. This makes no difference for a value like C<2>
421 but it is important for expressions with side effects, such as reference
422 constructors (C<[]>, C<{}>) or function calls.
424 Default arguments see not only the surrounding lexical scope of their function
425 but also any preceding parameters. This allows the creation of dynamic defaults
426 based on previous arguments:
428 method set_name($self: $nick = $self->default_nick, $real_name = $nick) {
429 $self->{nick} = $nick;
430 $self->{real_name} = $real_name;
433 $obj->set_name("simplicio"); # same as: $obj->set_name("simplicio", "simplicio");
435 Because default arguments are actually evaluated as part of the function body,
436 you can also do silly things like this:
438 fun foo($n = return "nope") {
442 say foo(2 + 2); # "you gave me 4"
445 =item 4. Required named parameters
447 By putting a colon (C<:>) in front of a parameter you can make it named
448 instead of positional:
450 fun rectangle(:$width, :$height) {
454 rectangle(width => 2, height => 5);
455 rectangle(height => 5, width => 2); # same thing!
457 That is, the caller must specify a key name in addition to the value, but in
458 exchange the order of the arguments doesn't matter anymore. As with hash
459 initialization, you can specify the same key multiple times and the last
462 rectangle(height => 1, width => 2, height => 2, height => 5;
463 # same as: rectangle(width => 2, height => 5);
465 You can combine positional and named parameters as long as the positional
466 parameters come first:
468 fun named_rectangle($name, :$width, :$height) {
472 named_rectangle("Avocado", width => 0.5, height => 1.2);
474 =item 5. Optional named parameters
476 As with positional parameters, you can make named parameters optional by
477 specifying a default argument after an equals sign (C<=>):
479 fun rectangle(:$width, :$height, :$color = "chartreuse") {
483 rectangle(height => 10, width => 5);
484 # same as: rectangle(height => 10, width => 5, color => "chartreuse");
490 fun get($url, :$cookie_jar = HTTP::Cookies->new(), :$referrer = $url) {
494 my $data = get "http://www.example.com/", referrer => undef; # overrides $referrer = $url
496 The above example shows that passing any value (even C<undef>) will override
497 the default argument.
499 =item 6. Slurpy parameter
501 Finally you can put an array or hash in the parameter list, which will gobble
502 up the remaining arguments (if any):
504 fun foo($x, $y, @rest) { ... }
506 foo "a", "b"; # $x = "a", $y = "b", @rest = ()
507 foo "a", "b", "c"; # $x = "a", $y = "b", @rest = ("c")
508 foo "a", "b", "c", "d"; # $x = "a", $y = "b", @rest = ("c", "d")
510 If you combine this with named parameters, the slurpy parameter will end up
511 containing all unrecognized keys:
513 fun bar(:$size, @whatev) { ... }
515 bar weight => 20, size => 2, location => [0, -3];
516 # $size = 2, @whatev = ('weight', 20, 'location', [0, -3])
520 Apart from the L<C<shift>|perlfunc/shift> performed by the L<invocant|/"1.
521 Invocant">, all of the above leave L<C<@_>|perlvar/@ARG> unchanged; and if you
522 don't specify a parameter list at all, L<C<@_>|perlvar/@ARG> is all you get.
526 The keywords provided by C<Function::Parameters> are customizable. Since
527 C<Function::Parameters> is actually a L<pragma|perlpragma>, the provided
528 keywords have lexical scope. The following import variants can be used:
532 =item C<use Function::Parameters ':strict'>
534 Provides the keywords C<fun> and C<method> (described below) and enables
535 argument checks so that calling a function and omitting a required argument (or
536 passing too many arguments) will throw an error.
538 =item C<use Function::Parameters>
540 Provides the keywords C<fun> and C<method> (described below) and enables
541 "lax" mode: Omitting a required argument sets it to C<undef> while excess
542 arguments are silently ignored.
544 =item C<< use Function::Parameters { KEYWORD1 => TYPE1, KEYWORD2 => TYPE2, ... } >>
546 Provides completely custom keywords as described by their types. A "type" is
547 either a string (one of the predefined types C<function>, C<method>,
548 C<classmethod>, C<function_strict>, C<method_strict>, C<classmethod_strict>) or
549 a reference to a hash with the following keys:
555 Valid values: C<optional> (default), C<required> (all functions defined with
556 this keyword must have a name), and C<prohibited> (functions defined with this
557 keyword must be anonymous).
561 Valid values: strings that look like scalar variables. This lets you specify a
562 default L<invocant|/"1. Invocant">, i.e. a function defined with this keyword
563 that doesn't have an explicit invocant in its parameter list will automatically
564 L<C<shift>|perlfunc/shift> its first argument into the variable specified here.
568 Valid values: booleans. If you set this to a true value, the keyword will
569 accept L<invocants|/"1. Invocant"> in parameter lists; otherwise specifying
570 an invocant in a function defined with this keyword is a syntax error.
574 Valid values: strings containing (source code for) attributes. This causes any
575 function defined with this keyword to have the specified
576 L<attributes|attributes> (in addition to any attributes specified in the
577 function definition itself).
579 =item C<default_arguments>
581 Valid values: booleans. This property is on by default; use
582 C<< default_arguments => 0 >> to turn it off. This controls whether optional
583 parameters are allowed. If it is turned off, using C<=> in parameter lists is
586 =item C<check_argument_count>
588 Valid values: booleans. If turned on, functions defined with this keyword will
589 automatically check that they have been passed all required arguments and no
590 excess arguments. If this check fails, an exception will by thrown via
591 L<C<Carp::croak>|Carp>.
595 The predefined type C<function> is equivalent to:
600 default_arguments => 1,
601 check_argument_count => 0,
604 These are all default values, so C<function> is also equivalent to C<{}>.
606 C<method> is equivalent to:
612 attributes => ':method',
613 default_arguments => 1,
614 check_argument_count => 0,
618 C<classmethod> is equivalent to:
624 attributes => ':method',
625 default_arguments => 1,
626 check_argument_count => 0,
629 C<function_strict>, C<method_strict>, and
630 C<classmethod_strict> are like C<function>, C<method>, and
631 C<classmethod>, respectively, but with C<< check_argument_count => 1 >>.
635 Plain C<use Function::Parameters> is equivalent to
636 C<< use Function::Parameters { fun => 'function', method => 'method' } >>.
638 C<use Function::Parameters qw(:strict)> is equivalent to
639 C<< use Function::Parameters { fun => 'function_strict', method => 'method_strict' } >>.
643 You can ask a function at runtime what parameters it has. This functionality is
644 available through the function C<Function::Parameters::info> (which is not
645 exported, so you have to call it by its full name). It takes a reference to a
646 function, and returns either C<undef> (if it knows nothing about the function)
647 or a L<Function::Parameters::Info> object describing the parameter list.
649 See L<Function::Parameters::Info> for examples.
651 =head2 Wrapping C<Function::Parameters>
653 If you want to write a wrapper around C<Function::Parameters>, you only have to
654 call its C<import> method. Due to its L<pragma|perlpragma> nature it always
655 affects the file that is currently being compiled.
657 package Some::Wrapper;
658 use Function::Parameters ();
660 Function::Parameters->import;
661 # or Function::Parameters->import(@custom_import_args);
664 =head2 Experimental feature: Types
666 An experimental feature is now available: You can annotate parameters with
667 L<Moose types|Moose::Manual::Types>. That is, before each parameter you can put
668 a type specification consisting of identifiers (C<Foo>), unions (C<... | ...>),
669 and parametric types (C<...[...]>). Example:
671 fun foo(Int $n, ArrayRef[String | CodeRef] $cb) { ... }
673 If you do this, L<Moose> will be loaded automatically (if that hasn't happened
674 yet). These specifications are parsed and validated using
675 L<C<Moose::Util::TypeConstraints::find_or_parse_type_constraint>|Moose::Util::TypeConstraints/find_or_parse_type_constraint>.
677 If you are in "lax" mode, nothing further happens and the types are ignored. If
678 you are in "strict" mode, C<Function::Parameters> generates code to make sure
679 any values passed in conform to the type (via
680 L<< C<< $constraint->check($value) >>|Moose::Meta::TypeConstraint/$constraint->check($value) >>.
682 In addition, these type constraints are inspectable through the
683 L<Function::Parameters::Info> object returned by
684 L<C<Function::Parameters::info>|/Introspection>.
686 =head2 Experimental experimental feature: Type expressions
688 An even more experimental feature is the ability to specify arbitrary
689 expressions as types. The syntax for this is like the literal types described
690 above, but with an expression wrapped in parentheses (C<( EXPR )>). Example:
692 fun foo(('Int') $n, ($othertype) $x) { ... }
694 Every type expression must return either a string (which is resolved as for
695 literal types), or a L<type constraint object|Moose::Meta::TypeConstraint>
696 (providing C<check> and C<get_message> methods).
698 Note that these expressions are evaluated (once) at parse time (similar to
699 C<BEGIN> blocks), so make sure that any variables you use are set and any
700 functions you call are defined at parse time.
704 The module is actually written in L<C|perlxs> and uses
705 L<C<PL_keyword_plugin>|perlapi/PL_keyword_plugin> to generate opcodes directly.
706 However, you can run L<C<perl -MO=Deparse ...>|B::Deparse> on your code to see
707 what happens under the hood. In the simplest case (no argument checks, possibly
708 an L<invocant|/"1. Invocant">, required positional/slurpy parameters only), the
709 generated code corresponds to:
711 fun foo($x, $y, @z) { ... }
713 sub foo { my ($x, $y, @z) = @_; sub foo; ... }
715 method bar($x, $y, @z) { ... }
717 sub bar :method { my $self = shift; my ($x, $y, @z) = @_; sub bar; ... }
719 =head1 SUPPORT AND DOCUMENTATION
721 After installing, you can find documentation for this module with the
724 perldoc Function::Parameters
726 You can also look for information at:
732 L<https://metacpan.org/module/Function%3A%3AParameters>
734 =item RT, CPAN's request tracker
736 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Function-Parameters>
738 =item AnnoCPAN, Annotated CPAN documentation
740 L<http://annocpan.org/dist/Function-Parameters>
744 L<http://cpanratings.perl.org/d/Function-Parameters>
748 L<http://search.cpan.org/dist/Function-Parameters/>
754 L<Function::Parameters::Info>
758 Lukas Mai, C<< <l.mai at web.de> >>
760 =head1 COPYRIGHT & LICENSE
762 Copyright 2010, 2011, 2012 Lukas Mai.
764 This program is free software; you can redistribute it and/or modify it
765 under the terms of either: the GNU General Public License as published
766 by the Free Software Foundation; or the Artistic License.
768 See http://dev.perl.org/licenses/ for more information.