1 package Function::Parameters;
10 our $VERSION = '1.0202';
14 sub _assert_valid_identifier {
15 my ($name, $with_dollar) = @_;
16 my $bonus = $with_dollar ? '\$' : '';
17 $name =~ /^${bonus}[^\W\d]\w*\z/
18 or confess qq{"$name" doesn't look like a valid identifier};
21 sub _assert_valid_attributes {
26 (?&ident) (?! [^\s:(] ) (?¶m)?+ \s*+
29 (?&ident) (?! [^\s:(] ) (?¶m)?+ \s*+
52 }sx or confess qq{"$attrs" doesn't look like valid attributes};
55 sub _reify_type_default {
56 require Moose::Util::TypeConstraints;
57 Moose::Util::TypeConstraints::find_or_create_isa_type_constraint($_[0])
61 my ($href, $key, $default) = @_;
62 exists $href->{$key} ? delete $href->{$key} : $default
65 my @bare_arms = qw(function method);
67 function => {}, # all default settings
69 defaults => 'function',
73 defaults => 'function',
74 attributes => ':method',
86 classmethod_strict => {
87 defaults => 'classmethod',
92 our @type_reifiers = \&_reify_type_default;
103 if (@_ == 1 && $_[0] eq ':strict') {
105 fun => 'function_strict',
106 method => 'method_strict',
109 if (@_ == 1 && ref($_[0]) eq 'HASH') {
110 @_ = map [$_, $_[0]{$_}], keys %{$_[0]};
117 my $item = ref $proto
119 : [$proto, $bare_arms[$bare++] || confess(qq{Don't know what to do with "$proto"})]
121 my ($name, $proto_type) = @$item;
122 _assert_valid_identifier $name;
124 $proto_type = {defaults => $proto_type} unless ref $proto_type;
126 my %type = %$proto_type;
127 while (my $defaults = delete $type{defaults}) {
128 my $base = $type_map{$defaults}
129 or confess qq["$defaults" doesn't look like a valid type (one of ${\join ', ', sort keys %type_map})];
130 %type = (%$base, %type);
135 $clean{name} = delete $type{name} // 'optional';
136 $clean{name} =~ /^(?:optional|required|prohibited)\z/
137 or confess qq["$clean{name}" doesn't look like a valid name attribute (one of optional, required, prohibited)];
139 $clean{shift} = delete $type{shift} // '';
140 _assert_valid_identifier $clean{shift}, 1 if $clean{shift};
142 $clean{attrs} = join ' ', map delete $type{$_} // (), qw(attributes attrs);
143 _assert_valid_attributes $clean{attrs} if $clean{attrs};
145 $clean{default_arguments} = _delete_default \%type, 'default_arguments', 1;
146 $clean{named_parameters} = _delete_default \%type, 'named_parameters', 1;
147 $clean{types} = _delete_default \%type, 'types', 1;
149 $clean{invocant} = _delete_default \%type, 'invocant', 0;
150 $clean{check_argument_count} = _delete_default \%type, 'check_argument_count', 0;
151 $clean{check_argument_types} = _delete_default \%type, 'check_argument_types', 0;
152 $clean{check_argument_count} = $clean{check_argument_types} = 1 if delete $type{strict};
154 if (my $rt = delete $type{reify_type}) {
155 ref $rt eq 'CODE' or confess qq{"$rt" doesn't look like a type reifier};
158 for my $i (0 .. $#type_reifiers) {
159 if ($type_reifiers[$i] == $rt) {
164 unless (defined $index) {
165 $index = @type_reifiers;
166 push @type_reifiers, $rt;
169 $clean{reify_type} = $index;
172 %type and confess "Invalid keyword property: @{[keys %type]}";
174 $spec{$name} = \%clean;
177 for my $kw (keys %spec) {
178 my $type = $spec{$kw};
181 $type->{name} eq 'prohibited' ? FLAG_ANON_OK :
182 $type->{name} eq 'required' ? FLAG_NAME_OK :
183 FLAG_ANON_OK | FLAG_NAME_OK
185 $flags |= FLAG_DEFAULT_ARGS if $type->{default_arguments};
186 $flags |= FLAG_CHECK_NARGS if $type->{check_argument_count};
187 $flags |= FLAG_CHECK_TARGS if $type->{check_argument_types};
188 $flags |= FLAG_INVOCANT if $type->{invocant};
189 $flags |= FLAG_NAMED_PARAMS if $type->{named_parameters};
190 $flags |= FLAG_TYPES_OK if $type->{types};
191 $^H{HINTK_FLAGS_ . $kw} = $flags;
192 $^H{HINTK_SHIFT_ . $kw} = $type->{shift};
193 $^H{HINTK_ATTRS_ . $kw} = $type->{attrs};
194 $^H{HINTK_REIFY_ . $kw} = $type->{reify_type} // 0;
195 $^H{+HINTK_KEYWORDS} .= "$kw ";
203 delete $^H{+HINTK_KEYWORDS};
208 $^H{+HINTK_KEYWORDS} =~ s/(?<![^ ])\Q$kw\E //g;
221 $positional_required,
222 $positional_optional,
230 declarator => $declarator,
231 invocant => defined $invocant ? [$invocant, $invocant_type] : undef,
232 slurpy => defined $slurpy ? [$slurpy , $slurpy_type ] : undef,
233 positional_required => $positional_required,
234 positional_optional => $positional_optional,
235 named_required => $named_required,
236 named_optional => $named_optional,
239 $metadata{$key} = $info;
244 my ($v, $t) = @{$pair || []} or return undef;
245 Function::Parameters::Param->new(
253 while (my ($v, $t) = splice @_, 0, 2) {
254 push @r, Function::Parameters::Param->new(
264 my $key = _cv_root $func or return undef;
265 my $info = $metadata{$key} or return undef;
266 require Function::Parameters::Info;
267 Function::Parameters::Info->new(
268 keyword => $info->{declarator},
269 invocant => _mkparam1($info->{invocant}),
270 slurpy => _mkparam1($info->{slurpy}),
271 (map +("_$_" => _mkparams @{$info->{$_}}), glob '{positional,named}_{required,optional}')
283 Function::Parameters - subroutine definitions with parameter lists
287 use Function::Parameters qw(:strict);
290 fun foo($bar, $baz) {
294 # function with prototype
295 fun mymap($fun, @args)
300 push @res, $fun->($_);
305 print "$_\n" for mymap { $_ * 2 } 1 .. 4;
307 # method with implicit $self
308 method set_name($name) {
309 $self->{name} = $name;
312 # method with explicit invocant
313 method new($class: %init) {
314 return bless { %init }, $class;
317 # function with optional parameters
318 fun search($haystack, $needle = qr/^(?!)/, $offset = 0) {
322 # method with named parameters
323 method resize(:$width, :$height) {
324 $self->{width} = $width;
325 $self->{height} = $height;
328 $obj->resize(height => 4, width => 5);
330 # function with named optional parameters
331 fun search($haystack, :$needle = qr/^(?!)/, :$offset = 0) {
335 my $results = search $text, offset => 200;
339 This module extends Perl with keywords that let you define functions with
340 parameter lists. It uses Perl's L<keyword plugin|perlapi/PL_keyword_plugin>
341 API, so it works reliably and doesn't require a source filter.
345 The anatomy of a function (as recognized by this module):
351 The keyword introducing the function.
355 The function name (optional).
359 The parameter list (optional).
363 The prototype (optional).
367 The attribute list (optional).
377 # (1) (2) (3) (4) (5) (6)
378 fun foo ($x, $y) :($$) :lvalue { ... }
383 In the following section I'm going to describe all parts in order from simplest to most complex.
387 This is just a normal block of statements, as with L<C<sub>|perlsub>. No surprises here.
391 If present, it specifies the name of the function being defined. As with
392 L<C<sub>|perlsub>, if a name is present, the whole declaration is syntactically
393 a statement and its effects are performed at compile time (i.e. at runtime you
394 can call functions whose definitions only occur later in the file). If no name
395 is present, the declaration is an expression that evaluates to a reference to
396 the function in question. No surprises here either.
400 Attributes are relatively unusual in Perl code, but if you want them, they work
401 exactly the same as with L<C<sub>|perlsub/Subroutine-Attributes>.
405 As with L<C<sub>|perlsub/Prototypes>, a prototype, if present, contains hints as to how
406 the compiler should parse calls to this function. This means prototypes have no
407 effect if the function call is compiled before the function declaration has
408 been seen by the compiler or if the function to call is only determined at
409 runtime (e.g. because it's called as a method or through a reference).
411 With L<C<sub>|perlsub>, a prototype comes directly after the function name (if
412 any). C<Function::Parameters> reserves this spot for the
413 L<parameter list|/"Parameter list">. To specify a prototype, put it as the
414 first attribute (e.g. C<fun foo :(&$$)>). This is syntactically unambiguous
415 because normal L<attributes|/Attributes> need a name after the colon.
417 =head3 Parameter list
419 The parameter list is a list of variables enclosed in parentheses, except it's
420 actually a bit more complicated than that. A parameter list can include the
421 following 6 parts, all of which are optional:
427 This is a scalar variable followed by a colon (C<:>) and no comma. If an
428 invocant is present in the parameter list, the first element of
429 L<C<@_>|perlvar/@ARG> is automatically L<C<shift>ed|perlfunc/shift> off and
430 placed in this variable. This is intended for methods:
432 method new($class: %init) {
433 return bless { %init }, $class;
436 method throw($self:) {
440 =item 2. Required positional parameters
442 The most common kind of parameter. This is simply a comma-separated list of
443 scalars, which are filled from left to right with the arguments that the caller
452 =item 3. Optional positional parameters
454 Parameters can be marked as optional by putting an equals sign (C<=>) and an
455 expression (the "default argument") after them. If no corresponding argument is
456 passed in by the caller, the default argument will be used to initialize the
459 fun scale($base, $factor = 2) {
460 return $base * $factor;
463 say scale(3, 5); # "15"
466 The default argument is I<not> cached. Every time a function is called with
467 some optional arguments missing, the corresponding default arguments are
468 evaluated from left to right. This makes no difference for a value like C<2>
469 but it is important for expressions with side effects, such as reference
470 constructors (C<[]>, C<{}>) or function calls.
472 Default arguments see not only the surrounding lexical scope of their function
473 but also any preceding parameters. This allows the creation of dynamic defaults
474 based on previous arguments:
476 method set_name($self: $nick = $self->default_nick, $real_name = $nick) {
477 $self->{nick} = $nick;
478 $self->{real_name} = $real_name;
481 $obj->set_name("simplicio"); # same as: $obj->set_name("simplicio", "simplicio");
483 Because default arguments are actually evaluated as part of the function body,
484 you can also do silly things like this:
486 fun foo($n = return "nope") {
490 say foo(2 + 2); # "you gave me 4"
493 =item 4. Required named parameters
495 By putting a colon (C<:>) in front of a parameter you can make it named
496 instead of positional:
498 fun rectangle(:$width, :$height) {
502 rectangle(width => 2, height => 5);
503 rectangle(height => 5, width => 2); # same thing!
505 That is, the caller must specify a key name in addition to the value, but in
506 exchange the order of the arguments doesn't matter anymore. As with hash
507 initialization, you can specify the same key multiple times and the last
510 rectangle(height => 1, width => 2, height => 2, height => 5);
511 # same as: rectangle(width => 2, height => 5);
513 You can combine positional and named parameters as long as the positional
514 parameters come first:
516 fun named_rectangle($name, :$width, :$height) {
520 named_rectangle("Avocado", width => 0.5, height => 1.2);
522 =item 5. Optional named parameters
524 As with positional parameters, you can make named parameters optional by
525 specifying a default argument after an equals sign (C<=>):
527 fun rectangle(:$width, :$height, :$color = "chartreuse") {
531 rectangle(height => 10, width => 5);
532 # same as: rectangle(height => 10, width => 5, color => "chartreuse");
538 fun get($url, :$cookie_jar = HTTP::Cookies->new(), :$referrer = $url) {
542 my $data = get "http://www.example.com/", referrer => undef; # overrides $referrer = $url
544 The above example shows that passing any value (even C<undef>) will override
545 the default argument.
547 =item 6. Slurpy parameter
549 Finally you can put an array or hash in the parameter list, which will gobble
550 up the remaining arguments (if any):
552 fun foo($x, $y, @rest) { ... }
554 foo "a", "b"; # $x = "a", $y = "b", @rest = ()
555 foo "a", "b", "c"; # $x = "a", $y = "b", @rest = ("c")
556 foo "a", "b", "c", "d"; # $x = "a", $y = "b", @rest = ("c", "d")
558 If you combine this with named parameters, the slurpy parameter will end up
559 containing all unrecognized keys:
561 fun bar(:$size, @whatev) { ... }
563 bar weight => 20, size => 2, location => [0, -3];
564 # $size = 2, @whatev = ('weight', 20, 'location', [0, -3])
568 Apart from the L<C<shift>|perlfunc/shift> performed by the L<invocant|/"1.
569 Invocant">, all of the above leave L<C<@_>|perlvar/@ARG> unchanged; and if you
570 don't specify a parameter list at all, L<C<@_>|perlvar/@ARG> is all you get.
574 The keywords provided by C<Function::Parameters> are customizable. Since
575 C<Function::Parameters> is actually a L<pragma|perlpragma>, the provided
576 keywords have lexical scope. The following import variants can be used:
580 =item C<use Function::Parameters ':strict'>
582 Provides the keywords C<fun> and C<method> (described below) and enables
583 argument checks so that calling a function and omitting a required argument (or
584 passing too many arguments) will throw an error.
586 =item C<use Function::Parameters>
588 Provides the keywords C<fun> and C<method> (described below) and enables
589 "lax" mode: Omitting a required argument sets it to C<undef> while excess
590 arguments are silently ignored.
592 =item C<< use Function::Parameters { KEYWORD1 => TYPE1, KEYWORD2 => TYPE2, ... } >>
594 Provides completely custom keywords as described by their types. A "type" is
595 either a string (one of the predefined types C<function>, C<method>,
596 C<classmethod>, C<function_strict>, C<method_strict>, C<classmethod_strict>) or
597 a reference to a hash with the following keys:
603 Valid values: One of the predefined types C<function>, C<method>,
604 C<classmethod>, C<function_strict>, C<method_strict>, C<classmethod_strict>.
605 This will set the defaults for all other keys from the specified type, which is
606 useful if you only want to override some properties:
608 use Function::Parameters { defmethod => { defaults => 'method', shift => '$this' } };
610 This example defines a keyword called C<defmethod> that works like the standard
611 C<method> keyword, but the implicit object variable is called C<$this> instead
614 Using the string types directly is equivalent to C<defaults> with no further
617 use Function::Parameters {
618 foo => 'function', # like: foo => { defaults => 'function' },
619 bar => 'function_strict', # like: bar => { defaults => 'function_strict' },
620 baz => 'method_strict', # like: baz => { defaults => 'method_strict' },
625 Valid values: C<optional> (default), C<required> (all functions defined with
626 this keyword must have a name), and C<prohibited> (functions defined with this
627 keyword must be anonymous).
631 Valid values: strings that look like scalar variables. This lets you specify a
632 default L<invocant|/"1. Invocant">, i.e. a function defined with this keyword
633 that doesn't have an explicit invocant in its parameter list will automatically
634 L<C<shift>|perlfunc/shift> its first argument into the variable specified here.
638 Valid values: booleans. If you set this to a true value, the keyword will
639 accept L<invocants|/"1. Invocant"> in parameter lists; otherwise specifying
640 an invocant in a function defined with this keyword is a syntax error.
644 Valid values: strings containing (source code for) attributes. This causes any
645 function defined with this keyword to have the specified
646 L<attributes|attributes> (in addition to any attributes specified in the
647 function definition itself).
649 =item C<default_arguments>
651 Valid values: booleans. This property is on by default; use
652 C<< default_arguments => 0 >> to turn it off. This controls whether optional
653 parameters are allowed. If it is turned off, using C<=> in parameter lists is
656 =item C<check_argument_count>
658 Valid values: booleans. If turned on, functions defined with this keyword will
659 automatically check that they have been passed all required arguments and no
660 excess arguments. If this check fails, an exception will by thrown via
661 L<C<Carp::croak>|Carp>.
663 =item C<check_argument_types>
665 Valid values: booleans. If turned on, functions defined with this keyword will
666 automatically check that the arguments they are passed pass the declared type
667 constraints (if any). See L</Experimental feature: Types> below.
671 Valid values: booleans. This turns on both C<check_argument_count> and
672 C<check_argument_types>.
676 Valid values: code references. The function specified here will be called to
677 turn type annotations into constraint objects (see
678 L</Experimental feature: Types> below). It will receive two arguments: a string
679 containing the type description, and the name of the current package.
681 The default type reifier is equivalent to:
684 require Moose::Util::TypeConstraints;
685 Moose::Util::TypeConstraints::find_or_create_isa_type_constraint($_[0])
690 The predefined type C<function> is equivalent to:
694 default_arguments => 1,
699 These are all default values, so C<function> is also equivalent to C<{}>.
701 C<method> is equivalent to:
704 defaults => 'function',
705 attributes => ':method',
711 C<classmethod> is equivalent to:
714 defaults => 'method',
718 C<function_strict>, C<method_strict>, and
719 C<classmethod_strict> are like C<function>, C<method>, and
720 C<classmethod>, respectively, but with C<< strict => 1 >>.
724 Plain C<use Function::Parameters> is equivalent to
725 C<< use Function::Parameters { fun => 'function', method => 'method' } >>.
727 C<use Function::Parameters qw(:strict)> is equivalent to
728 C<< use Function::Parameters { fun => 'function_strict', method => 'method_strict' } >>.
732 You can ask a function at runtime what parameters it has. This functionality is
733 available through the function C<Function::Parameters::info> (which is not
734 exported, so you have to call it by its full name). It takes a reference to a
735 function, and returns either C<undef> (if it knows nothing about the function)
736 or a L<Function::Parameters::Info> object describing the parameter list.
738 Note: This feature is implemented using L<Moo>, so you'll need to have L<Moo>
739 installed if you want to call C<Function::Parameters::info> (alternatively, if
740 L<Moose> is already loaded by the time C<Function::Parameters::info> is first
741 called, it will use that instead).
743 See L<Function::Parameters::Info> for examples.
745 =head2 Wrapping C<Function::Parameters>
747 If you want to write a wrapper around C<Function::Parameters>, you only have to
748 call its C<import> method. Due to its L<pragma|perlpragma> nature it always
749 affects the file that is currently being compiled.
751 package Some::Wrapper;
752 use Function::Parameters ();
754 Function::Parameters->import;
755 # or Function::Parameters->import(@custom_import_args);
758 =head2 Experimental feature: Types
760 An experimental feature is now available: You can annotate parameters with
761 types. That is, before each parameter you can put a type specification
762 consisting of identifiers (C<Foo>), unions (C<... | ...>), and parametric types
763 (C<...[...]>). Example:
765 fun foo(Int $n, ArrayRef[Str | CodeRef] $cb) { ... }
767 If you do this, the type reification function corresponding to the keyword will
768 be called to turn the type (a string) into a constraint object. The default
769 type reifier simply loads L<Moose> and forwards to
770 L<C<Moose::Util::TypeConstraints::find_or_parse_type_constraint>|Moose::Util::TypeConstraints/find_or_parse_type_constraint>,
771 which creates L<Moose types|Moose::Manual::Types>.
773 If you are in "lax" mode, nothing further happens and the types are ignored. If
774 you are in "strict" mode, C<Function::Parameters> generates code to make sure
775 any values passed in conform to the type (via
776 L<< C<< $constraint->check($value) >>|Moose::Meta::TypeConstraint/$constraint->check($value) >>).
778 In addition, these type constraints are inspectable through the
779 L<Function::Parameters::Info> object returned by
780 L<C<Function::Parameters::info>|/Introspection>.
782 =head2 Experimental experimental feature: Type expressions
784 An even more experimental feature is the ability to specify arbitrary
785 expressions as types. The syntax for this is like the literal types described
786 above, but with an expression wrapped in parentheses (C<( EXPR )>). Example:
788 fun foo(('Int') $n, ($othertype) $x) { ... }
790 Every type expression must return either a string (which is resolved as for
791 literal types), or a L<type constraint object|Moose::Meta::TypeConstraint>
792 (providing C<check> and C<get_message> methods).
794 Note that these expressions are evaluated (once) at parse time (similar to
795 C<BEGIN> blocks), so make sure that any variables you use are set and any
796 functions you call are defined at parse time.
800 The module is actually written in L<C|perlxs> and uses
801 L<C<PL_keyword_plugin>|perlapi/PL_keyword_plugin> to generate opcodes directly.
802 However, you can run L<C<perl -MO=Deparse ...>|B::Deparse> on your code to see
803 what happens under the hood. In the simplest case (no argument checks, possibly
804 an L<invocant|/"1. Invocant">, required positional/slurpy parameters only), the
805 generated code corresponds to:
807 fun foo($x, $y, @z) { ... }
809 sub foo { my ($x, $y, @z) = @_; sub foo; ... }
811 method bar($x, $y, @z) { ... }
813 sub bar :method { my $self = shift; my ($x, $y, @z) = @_; sub bar; ... }
815 =head1 SUPPORT AND DOCUMENTATION
817 After installing, you can find documentation for this module with the
820 perldoc Function::Parameters
822 You can also look for information at:
828 L<https://metacpan.org/module/Function%3A%3AParameters>
830 =item RT, CPAN's request tracker
832 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Function-Parameters>
834 =item AnnoCPAN, Annotated CPAN documentation
836 L<http://annocpan.org/dist/Function-Parameters>
840 L<http://cpanratings.perl.org/d/Function-Parameters>
844 L<http://search.cpan.org/dist/Function-Parameters/>
850 L<Function::Parameters::Info>
854 Lukas Mai, C<< <l.mai at web.de> >>
856 =head1 COPYRIGHT & LICENSE
858 Copyright 2010-2013 Lukas Mai.
860 This program is free software; you can redistribute it and/or modify it
861 under the terms of either: the GNU General Public License as published
862 by the Free Software Foundation; or the Artistic License.
864 See http://dev.perl.org/licenses/ for more information.