1 package Function::Parameters;
11 our $VERSION = '1.00';
15 sub _assert_valid_identifier {
16 my ($name, $with_dollar) = @_;
17 my $bonus = $with_dollar ? '\$' : '';
18 $name =~ /^${bonus}[^\W\d]\w*\z/
19 or confess qq{"$name" doesn't look like a valid identifier};
22 sub _assert_valid_attributes {
24 $attrs =~ /^\s*:\s*[^\W\d]\w*\s*(?:(?:\s|:\s*)[^\W\d]\w*\s*)*(?:\(|\z)/
25 or confess qq{"$attrs" doesn't look like valid attributes};
28 my @bare_arms = qw(function method);
32 default_arguments => 1,
33 check_argument_count => 0,
34 named_parameters => 1,
38 default_arguments => 1,
39 check_argument_count => 0,
40 named_parameters => 1,
47 default_arguments => 1,
48 check_argument_count => 0,
49 named_parameters => 1,
50 attributes => ':method',
55 for my $k (keys %type_map) {
56 $type_map{$k . '_strict'} = {
58 check_argument_count => 1,
71 if (@_ == 1 && $_[0] eq ':strict') {
73 fun => 'function_strict',
74 method => 'method_strict',
77 if (@_ == 1 && ref($_[0]) eq 'HASH') {
78 @_ = map [$_, $_[0]{$_}], keys %{$_[0]};
87 : [$proto, $bare_arms[$bare++] || confess(qq{Don't know what to do with "$proto"})]
89 my ($name, $proto_type) = @$item;
90 _assert_valid_identifier $name;
92 unless (ref $proto_type) {
93 # use '||' instead of 'or' to preserve $proto_type in the error message
94 $proto_type = $type_map{$proto_type}
95 || confess qq["$proto_type" doesn't look like a valid type (one of ${\join ', ', sort keys %type_map})];
98 my %type = %$proto_type;
101 $clean{name} = delete $type{name} || 'optional';
102 $clean{name} =~ /^(?:optional|required|prohibited)\z/
103 or confess qq["$clean{name}" doesn't look like a valid name attribute (one of optional, required, prohibited)];
105 $clean{shift} = delete $type{shift} || '';
106 _assert_valid_identifier $clean{shift}, 1 if $clean{shift};
108 $clean{attrs} = join ' ', map delete $type{$_} || (), qw(attributes attrs);
109 _assert_valid_attributes $clean{attrs} if $clean{attrs};
111 $clean{default_arguments} =
112 exists $type{default_arguments}
113 ? !!delete $type{default_arguments}
116 $clean{check_argument_count} = !!delete $type{check_argument_count};
117 $clean{invocant} = !!delete $type{invocant};
118 $clean{named_parameters} = !!delete $type{named_parameters};
120 %type and confess "Invalid keyword property: @{[keys %type]}";
122 $spec{$name} = \%clean;
125 for my $kw (keys %spec) {
126 my $type = $spec{$kw};
129 $type->{name} eq 'prohibited' ? FLAG_ANON_OK :
130 $type->{name} eq 'required' ? FLAG_NAME_OK :
131 FLAG_ANON_OK | FLAG_NAME_OK
133 $flags |= FLAG_DEFAULT_ARGS if $type->{default_arguments};
134 $flags |= FLAG_CHECK_NARGS if $type->{check_argument_count};
135 $flags |= FLAG_INVOCANT if $type->{invocant};
136 $flags |= FLAG_NAMED_PARAMS if $type->{named_parameters};
137 $^H{HINTK_FLAGS_ . $kw} = $flags;
138 $^H{HINTK_SHIFT_ . $kw} = $type->{shift};
139 $^H{HINTK_ATTRS_ . $kw} = $type->{attrs};
140 $^H{+HINTK_KEYWORDS} .= "$kw ";
148 delete $^H{+HINTK_KEYWORDS};
153 $^H{+HINTK_KEYWORDS} =~ s/(?<![^ ])\Q$kw\E //g;
165 $positional_required,
166 $positional_optional,
172 my $blob = pack '(Z*)*',
175 join(' ', @$positional_required),
176 join(' ', @$positional_optional),
177 join(' ', @$named_required),
178 join(' ', @$named_optional),
182 $metadata{$key} = $blob;
187 my $key = _cv_root $func or return undef;
188 my $blob = $metadata{$key} or return undef;
189 my @info = unpack '(Z*)*', $blob;
190 require Function::Parameters::Info;
191 Function::Parameters::Info->new(
193 invocant => $info[1] || undef,
194 _positional_required => [split ' ', $info[2]],
195 _positional_optional => [split ' ', $info[3]],
196 _named_required => [split ' ', $info[4]],
197 _named_optional => [split ' ', $info[5]],
198 slurpy => $info[6] || undef,
210 Function::Parameters - subroutine definitions with parameter lists
214 use Function::Parameters qw(:strict);
217 fun foo($bar, $baz) {
221 # function with prototype
222 fun mymap($fun, @args)
227 push @res, $fun->($_);
232 print "$_\n" for mymap { $_ * 2 } 1 .. 4;
234 # method with implicit $self
235 method set_name($name) {
236 $self->{name} = $name;
239 # method with explicit invocant
240 method new($class: %init) {
241 return bless { %init }, $class;
244 # function with optional parameters
245 fun search($haystack, $needle = qr/^(?!)/, $offset = 0) {
249 # method with named parameters
250 method resize(:$width, :$height) {
251 $self->{width} = $width;
252 $self->{height} = $height;
255 $obj->resize(height => 4, width => 5);
257 # function with named optional parameters
258 fun search($haystack, :$needle = qr/^(?!)/, :$offset = 0) {
262 my $results = search $text, offset => 200;
266 This module extends Perl with keywords that let you define functions with
267 parameter lists. It uses Perl's L<keyword plugin|perlapi/PL_keyword_plugin>
268 API, so it works reliably and doesn't require a source filter.
272 The anatomy of a function (as recognized by this module):
278 The keyword introducing the function.
282 The function name (optional).
286 The parameter list (optional).
290 The prototype (optional).
294 The attribute list (optional).
304 # (1) (2) (3) (4) (5) (6)
305 fun foo ($x, $y) :($$) :lvalue { ... }
310 In the following section I'm going to describe all parts in order from simplest to most complex.
314 This is just a normal block of statements, as with L<C<sub>|perlsub>. No surprises here.
318 If present, it specifies the name of the function being defined. As with
319 L<C<sub>|perlsub>, if a name is present, the whole declaration is syntactically
320 a statement and its effects are performed at compile time (i.e. at runtime you
321 can call functions whose definitions only occur later in the file). If no name
322 is present, the declaration is an expression that evaluates to a reference to
323 the function in question. No surprises here either.
327 Attributes are relatively unusual in Perl code, but if you want them, they work
328 exactly the same as with L<C<sub>|perlsub/Subroutine-Attributes>.
332 As with L<C<sub>|perlsub/Prototypes>, a prototype, if present, contains hints as to how
333 the compiler should parse calls to this function. This means prototypes have no
334 effect if the function call is compiled before the function declaration has
335 been seen by the compiler or if the function to call is only determined at
336 runtime (e.g. because it's called as a method or through a reference).
338 With L<C<sub>|perlsub>, a prototype comes directly after the function name (if
339 any). C<Function::Parameters> reserves this spot for the
340 L<parameter list|/"Parameter list">. To specify a prototype, put it as the
341 first attribute (e.g. C<fun foo :(&$$)>). This is syntactically unambiguous
342 because normal L<attributes|/Attributes> need a name after the colon.
344 =head3 Parameter list
346 The parameter list is a list of variables enclosed in parentheses, except it's
347 actually a bit more complicated than that. A parameter list can include the
348 following 6 parts, all of which are optional:
354 This is a scalar variable followed by a colon (C<:>) and no comma. If an
355 invocant is present in the parameter list, the first element of
356 L<C<@_>|perlvar/@ARG> is automatically L<C<shift>ed|perlfunc/shift> off and
357 placed in this variable. This is intended for methods:
359 method new($class: %init) {
360 return bless { %init }, $class;
363 method throw($self:) {
367 =item 2. Required positional parameters
369 The most common kind of parameter. This is simply a comma-separated list of
370 scalars, which are filled from left to right with the arguments that the caller
379 =item 3. Optional positional parameters
381 Parameters can be marked as optional by putting an equals sign (C<=>) and an
382 expression (the "default argument") after them. If no corresponding argument is
383 passed in by the caller, the default argument will be used to initialize the
386 fun scale($base, $factor = 2) {
387 return $base * $factor;
390 say scale(3, 5); # "15"
393 The default argument is I<not> cached. Every time a function is called with
394 some optional arguments missing, the corresponding default arguments are
395 evaluated from left to right. This makes no difference for a value like C<2>
396 but it is important for expressions with side effects, such as reference
397 constructors (C<[]>, C<{}>) or function calls.
399 Default arguments see not only the surrounding lexical scope of their function
400 but also any preceding parameters. This allows the creation of dynamic defaults
401 based on previous arguments:
403 method set_name($self: $nick = $self->default_nick, $real_name = $nick) {
404 $self->{nick} = $nick;
405 $self->{real_name} = $real_name;
408 $obj->set_name("simplicio"); # same as: $obj->set_name("simplicio", "simplicio");
410 Because default arguments are actually evaluated as part of the function body,
411 you can also do silly things like this:
413 fun foo($n = return "nope") {
417 say foo(2 + 2); # "you gave me 4"
420 =item 4. Required named parameters
422 By putting a colon (C<:>) in front of a parameter you can make it named
423 instead of positional:
425 fun rectangle(:$width, :$height) {
429 rectangle(width => 2, height => 5);
430 rectangle(height => 5, width => 2); # same thing!
432 That is, the caller must specify a key name in addition to the value, but in
433 exchange the order of the arguments doesn't matter anymore. As with hash
434 initialization, you can specify the same key multiple times and the last
437 rectangle(height => 1, width => 2, height => 2, height => 5;
438 # same as: rectangle(width => 2, height => 5);
440 You can combine positional and named parameters as long as the positional
441 parameters come first:
443 fun named_rectangle($name, :$width, :$height) {
447 named_rectangle("Avocado", width => 0.5, height => 1.2);
449 =item 5. Optional named parameters
451 As with positional parameters, you can make named parameters optional by
452 specifying a default argument after an equals sign (C<=>):
454 fun rectangle(:$width, :$height, :$color = "chartreuse") {
458 rectangle(height => 10, width => 5);
459 # same as: rectangle(height => 10, width => 5, color => "chartreuse");
465 fun get($url, :$cookie_jar = HTTP::Cookies->new(), :$referrer = $url) {
469 my $data = get "http://www.example.com/", referrer => undef; # overrides $referrer = $url
471 The above example shows that passing any value (even C<undef>) will override
472 the default argument.
474 =item 6. Slurpy parameter
476 Finally you can put an array or hash in the parameter list, which will gobble
477 up the remaining arguments (if any):
479 fun foo($x, $y, @rest) { ... }
481 foo "a", "b"; # $x = "a", $y = "b", @rest = ()
482 foo "a", "b", "c"; # $x = "a", $y = "b", @rest = ("c")
483 foo "a", "b", "c", "d"; # $x = "a", $y = "b", @rest = ("c", "d")
485 If you combine this with named parameters, the slurpy parameter will end up
486 containing all unrecognized keys:
488 fun bar(:$size, @whatev) { ... }
490 bar weight => 20, size => 2, location => [0, -3];
491 # $size = 2, @whatev = ('weight', 20, 'location', [0, -3])
495 Apart from the L<C<shift>|perlfunc/shift> performed by the L<invocant|/"1.
496 Invocant">, all of the above leave L<C<@_>|perlvar/@ARG> unchanged; and if you
497 don't specify a parameter list at all, L<C<@_>|perlvar/@ARG> is all you get.
501 The keywords provided by C<Function::Parameters> are customizable. Since
502 C<Function::Parameters> is actually a L<pragma|perlpragma>, the provided
503 keywords have lexical scope. The following import variants can be used:
507 =item C<use Function::Parameters ':strict'>
509 Provides the keywords C<fun> and C<method> (described below) and enables
510 argument checks so that calling a function and omitting a required argument (or
511 passing too many arguments) will throw an error.
513 =item C<use Function::Parameters>
515 Provides the keywords C<fun> and C<method> (described below) and enables
516 "lax" mode: Omitting a required argument sets it to C<undef> while excess
517 arguments are silently ignored.
519 =item C<< use Function::Parameters { KEYWORD1 => TYPE1, KEYWORD2 => TYPE2, ... } >>
521 Provides completely custom keywords as described by their types. A "type" is
522 either a string (one of the predefined types C<function>, C<method>,
523 C<classmethod>, C<function_strict>, C<method_strict>, C<classmethod_strict>) or
524 a reference to a hash with the following keys:
530 Valid values: C<optional> (default), C<required> (all functions defined with
531 this keyword must have a name), and C<prohibited> (functions defined with this
532 keyword must be anonymous).
536 Valid values: strings that look like scalar variables. This lets you specify a
537 default L<invocant|/"1. Invocant">, i.e. a function defined with this keyword
538 that doesn't have an explicit invocant in its parameter list will automatically
539 L<C<shift>|perlfunc/shift> its first argument into the variable specified here.
543 Valid values: booleans. If you set this to a true value, the keyword will
544 accept L<invocants|/"1. Invocant"> in parameter lists; otherwise specifying
545 an invocant in a function defined with this keyword is a syntax error.
549 Valid values: strings containing (source code for) attributes. This causes any
550 function defined with this keyword to have the specified
551 L<attributes|attributes> (in addition to any attributes specified in the
552 function definition itself).
554 =item C<default_arguments>
556 Valid values: booleans. This property is on by default; use
557 C<< default_arguments => 0 >> to turn it off. This controls whether optional
558 parameters are allowed. If it is turned off, using C<=> in parameter lists is
561 =item C<check_argument_count>
563 Valid values: booleans. If turned on, functions defined with this keyword will
564 automatically check that they have been passed all required arguments and no
565 excess arguments. If this check fails, an exception will by thrown via
566 L<C<Carp::croak>|Carp>.
570 The predefined type C<function> is equivalent to:
575 default_arguments => 1,
576 check_argument_count => 0,
579 These are all default values, so C<function> is also equivalent to C<{}>.
581 C<method> is equivalent to:
587 attributes => ':method',
588 default_arguments => 1,
589 check_argument_count => 0,
593 C<classmethod> is equivalent to:
599 attributes => ':method',
600 default_arguments => 1,
601 check_argument_count => 0,
604 C<function_strict>, C<method_strict>, and
605 C<classmethod_strict> are like C<function>, C<method>, and
606 C<classmethod>, respectively, but with C<< check_argument_count => 1 >>.
610 Plain C<use Function::Parameters> is equivalent to
611 C<< use Function::Parameters { fun => 'function', method => 'method' } >>.
613 C<use Function::Parameters qw(:strict)> is equivalent to
614 C<< use Function::Parameters { fun => 'function_strict', method => 'method_strict' } >>.
616 =head2 Wrapping C<Function::Parameters>
618 If you want to write a wrapper around C<Function::Parameters>, you only have to
619 call its C<import> method. Due to its L<pragma|perlpragma> nature it always
620 affects the file that is currently being compiled.
622 package Some::Wrapper;
623 use Function::Parameters ();
625 Function::Parameters->import;
626 # or Function::Parameters->import(@custom_import_args);
631 The module is actually written in L<C|perlxs> and uses
632 L<C<PL_keyword_plugin>|perlapi/PL_keyword_plugin> to generate opcodes directly.
633 However, you can run L<C<perl -MO=Deparse ...>|B::Deparse> on your code to see
634 what happens under the hood. In the simplest case (no argument checks, possibly
635 an L<invocant|/"1. Invocant">, required positional/slurpy parameters only), the
636 generated code corresponds to:
638 fun foo($x, $y, @z) { ... }
640 sub foo { my ($x, $y, @z) = @_; sub foo; ... }
642 method bar($x, $y, @z) { ... }
644 sub bar :method { my $self = shift; my ($x, $y, @z) = @_; sub bar; ... }
648 Lukas Mai, C<< <l.mai at web.de> >>
650 =head1 COPYRIGHT & LICENSE
652 Copyright 2010, 2011, 2012 Lukas Mai.
654 This program is free software; you can redistribute it and/or modify it
655 under the terms of either: the GNU General Public License as published
656 by the Free Software Foundation; or the Artistic License.
658 See http://dev.perl.org/licenses/ for more information.