1Function::Parameters(3)User Contributed Perl DocumentatioFnunction::Parameters(3)
2
3
4

NAME

6       Function::Parameters - define functions and methods with parameter
7       lists ("subroutine signatures")
8

SYNOPSIS

10        use Function::Parameters;
11
12        # plain function
13        fun foo($x, $y, $z = 5) {
14            return $x + $y + $z;
15        }
16        print foo(1, 2), "\n";  # 8
17
18        # method with implicit $self
19        method bar($label, $n) {
20            return "$label: " . ($n * $self->scale);
21        }
22
23        # named arguments: order doesn't matter in the call
24        fun create_point(:$x, :$y, :$color) {
25            print "creating a $color point at ($x, $y)\n";
26        }
27        create_point(
28            color => "red",
29            x     => 10,
30            y     => 5,
31        );
32
33        package Derived {
34            use Function::Parameters qw(:std :modifiers);
35            use Moo;
36
37            extends 'Base';
38
39            has 'go_big' => (
40                is => 'ro',
41            );
42
43            # "around" method with implicit $orig and $self
44            around size() {
45                return $self->$orig() * 2 if $self->go_big;
46                return $self->$orig();
47            }
48        }
49

DESCRIPTION

51       This module provides two new keywords, "fun" and "method", for defining
52       functions and methods with parameter lists. At minimum this saves you
53       from having to unpack @_ manually, but this module can do much more for
54       you.
55
56       The parameter lists provided by this module are similar to the
57       "signatures" feature available in perl v5.20+. However, this module
58       supports all perl versions starting from v5.14, it offers far more
59       features than core signatures, and it is not experimental. The downside
60       is that you need a C compiler if you want to install it from source, as
61       it uses Perl's keyword plugin API in order to work reliably without
62       requiring a source filter.
63
64   Default functionality
65       This module is a lexically scoped pragma: If you "use
66       Function::Parameters" inside a block or file, the keywords won't be
67       available outside of that block or file.
68
69       You can also disable "Function::Parameters" within a block:
70
71        {
72            no Function::Parameters;  # disable all keywords
73            ...
74        }
75
76       Or explicitly list the keywords you want to disable:
77
78        {
79            no Function::Parameters qw(method);
80            # 'method' is a normal identifier here
81            ...
82        }
83
84       You can also explicitly list the keywords you want to enable:
85
86        use Function::Parameters qw(fun);  # provides 'fun' but not 'method'
87        use Function::Parameters qw(method);  # provides 'method' but not 'fun'
88
89       Simple parameter lists
90
91       By default you get two keywords, "fun" and "method" (but see
92       "Customizing and extending" below). "fun" is very similar to "sub". You
93       can use it to define both named and anonymous functions:
94
95        fun left_pad($str, $n) {
96            return sprintf '%*s', $n, $str;
97        }
98
99        print left_pad("hello", 10), "\n";
100
101        my $twice = fun ($x) { $x * 2 };
102        print $twice->(21), "\n";
103
104       In the simplest case the parameter list is just a comma-separated list
105       of zero or more scalar variables (enclosed in parentheses, following
106       the function name, if any).
107
108       "Function::Parameters" automatically validates the arguments your
109       function is called with. If the number of arguments doesn't match the
110       parameter list, an exception is thrown.
111
112       Apart from that, the parameter variables are defined and initialized as
113       if by:
114
115        sub left_pad {
116            sub left_pad;
117            my ($str, $n) = @_;
118            ...
119        }
120
121       In particular, @_ is still available in functions defined by "fun" and
122       holds the original argument list.
123
124       The inner "sub left_pad;" declaration is intended to illustrate that
125       the name of the function being defined is in scope in its own body,
126       meaning you can call it recursively without having to use parentheses:
127
128        fun fac($n) {
129            return 1 if $n < 2;
130            return $n * fac $n - 1;
131        }
132
133       In a normal "sub" the last line would have had to be written "return $n
134       * fac($n - 1);".
135
136       "method" is almost the same as "fun" but automatically creates a $self
137       variable as the first parameter (which is removed from @_):
138
139        method foo($x, $y) {
140           ...
141        }
142
143        # works like:
144        sub foo :method {
145           my $self = shift;
146           my ($x, $y) = @_;
147           ...
148        }
149
150       As you can see, the ":method" attribute is also added automatically
151       (see "method" in attributes for details).
152
153       In some cases (e.g. class methods) $self is not the best name for the
154       invocant of the method. You can override it on a case-by-case basis by
155       putting a variable name followed by a ":" (colon) as the first thing in
156       the parameter list:
157
158        method new($class: $x, $y) {
159            return bless { x => $x, y => $y }, $class;
160        }
161
162       Here the invocant is named $class, not $self. It looks a bit weird but
163       still works the same way if the remaining parameter list is empty:
164
165        method from_env($class:) {
166            return $class->new($ENV{x}, $ENV{y});
167        }
168
169       Default arguments
170
171       (Most of the following examples use "fun" only. Unless specified
172       otherwise everything applies to "method" as well.)
173
174       You can make some arguments optional by giving them default values.
175
176        fun passthrough($x, $y = 42, $z = []) {
177            return ($x, $y, $z);
178        }
179
180       In this example the first parameter $x is required but $y and $z are
181       optional.
182
183        passthrough('a', 'b', 'c', 'd')   # error: Too many arguments
184        passthrough('a', 'b', 'c')        # returns ('a', 'b', 'c')
185        passthrough('a', 'b')             # returns ('a', 'b', [])
186        passthrough('a', undef)           # returns ('a', undef, [])
187        passthrough('a')                  # returns ('a', 42, [])
188        passthrough()                     # error: Too few arguments
189
190       Default arguments are evaluated whenever a corresponding real argument
191       is not passed in by the caller. "undef" counts as a real argument; you
192       can't use the default value for parameter N and still pass a value for
193       parameter N+1.  "$z = []" means each call that doesn't pass a third
194       argument gets a new array reference (they're not shared between calls).
195
196       Default arguments are evaluated as part of the function body, allowing
197       for silliness such as:
198
199        fun weird($name = return "nope") {
200            print "Hello, $name!\n";
201            return $name;
202        }
203
204        weird("Larry");  # prints "Hello, Larry!" and returns "Larry"
205        weird();         # returns "nope" immediately; function body doesn't run
206
207       Preceding parameters are in scope for default arguments:
208
209        fun dynamic_default($x, $y = length $x) {
210           return "$x/$y";
211        }
212
213        dynamic_default("hello", 0)  # returns "hello/0"
214        dynamic_default("hello")     # returns "hello/5"
215        dynamic_default("abc")       # returns "abc/3"
216
217       If you just want to make a parameter optional without giving it a
218       special value, write "$param = undef". There is a special shortcut
219       syntax for this case: "$param = undef" can also be written "$param ="
220       (with no following expression).
221
222        fun foo($x = undef, $y = undef, $z = undef) {
223            # three arguments, all optional
224            ...
225        }
226
227        fun foo($x=, $y=, $z=) {
228            # shorter syntax, same meaning
229            ...
230        }
231
232       Optional parameters must come at the end. It is not possible to have a
233       required parameter after an optional one.
234
235       Slurpy/rest parameters
236
237       The last parameter of a function or method can be an array. This lets
238       you slurp up any number of arguments the caller passes (0 or more).
239
240        fun scale($factor, @values) {
241            return map { $_ * $factor } @values;
242        }
243
244        scale(10, 1 .. 4)  # returns (10, 20, 30, 40)
245        scale(10)          # returns ()
246
247       You can also use a hash, but then the number of arguments has to be
248       even.
249
250       Named parameters
251
252       As soon as your functions take more than three arguments, it gets
253       harder to keep track of what argument means what:
254
255        foo($handle, $w, $h * 2 + 15, 1, 24, 'icon');
256        # what do these arguments mean?
257
258       "Function::Parameters" offers an alternative for these kinds of
259       situations in the form of named parameters. Unlike the parameters
260       described previously, which are identified by position, these
261       parameters are identified by name:
262
263        fun create_point(:$x, :$y, :$color) {
264            ...
265        }
266
267        # Case 1
268        create_point(
269            x     => 50,
270            y     => 50,
271            color => 0xff_00_00,
272        );
273
274       To create a named parameter, put a ":" (colon) in front of it in the
275       parameter list. When the function is called, the arguments have to be
276       supplied in the form of a hash initializer (a list of alternating
277       keys/values). As with a hash, the order of key/value pairs doesn't
278       matter (except in the case of duplicate keys, where the last occurrence
279       wins):
280
281        # Case 2
282        create_point(
283            color => 0xff_00_00,
284            x     => 50,
285            y     => 50,
286        );
287
288        # Case 3
289        create_point(
290            x     => 200,
291            color => 0x12_34_56,
292            color => 0xff_00_00,
293            x     => 50,
294            y     => 50,
295        );
296
297       Case 1, Case 2, and Case 3 all mean the same thing.
298
299       As with positional parameters, you can make named parameters optional
300       by supplying a default argument:
301
302        fun create_point(:$x, :$y, :$color = 0x00_00_00) {
303            ...
304        }
305
306        create_point(x => 0, y => 64)  # color => 0x00_00_00 is implicit
307
308       If you want to accept any key/value pairs, you can add a rest parameter
309       (hashes are particularly useful):
310
311        fun accept_all_keys(:$name, :$age, %rest) {
312            ...
313        }
314
315        accept_all_keys(
316            age     => 42,
317            gender  => 2,
318            name    => "Jamie",
319            marbles => [],
320        );
321        # $name = "Jamie";
322        # $age = 42;
323        # %rest = (
324        #     gender  => 2,
325        #     marbles => [],
326        # );
327
328       You can combine positional and named parameters but all positional
329       parameters have to come first:
330
331        method output(
332           $data,
333           :$handle       = $self->output_handle,
334           :$separator    = $self->separator,
335           :$quote_fields = 0,
336        ) {
337            ...
338        }
339
340        $obj->output(["greetings", "from", "space"]);
341        $obj->output(
342           ["a", "random", "example"],
343           quote_fields => 1,
344           separator    => ";",
345        );
346
347       Unnamed parameters
348
349       If your function doesn't use a particular parameter at all, you can
350       omit its name and just write a sigil in the parameter list:
351
352        register_callback('click', fun ($target, $) {
353            ...
354        });
355
356       Here we're calling a hypothetical "register_callback" function that
357       registers our coderef to be called in response to a "click" event. It
358       will pass two arguments to the click handler, but the coderef only
359       cares about the first one ($target). The second parameter doesn't even
360       get a name (just a sigil, "$"). This marks it as unused.
361
362       This case typically occurs when your functions have to conform to an
363       externally imposed interface, e.g. because they're called by someone
364       else. It can happen with callbacks or methods that don't need all of
365       the arguments they get.
366
367       You can use unnamed slurpy parameters to accept and ignore all
368       following arguments. In particular, "fun foo(@)" is a lot like "sub
369       foo" in that it accepts and ignores any number of arguments (apart from
370       leaving them in @_).
371
372       Type constraints
373
374       It is possible to automatically check the types of arguments passed to
375       your function. There are two ways to do this.
376
377       1.
378            use Types::Standard qw(Str Int ArrayRef);
379
380            fun foo(Str $label, ArrayRef[Int] $counts) {
381                ...
382            }
383
384           In this variant you simply put the name of a type in front of a
385           parameter. The way this works is that "Function::Parameters" parses
386           the type using very simple rules:
387
388           ·   A type is a sequence of one or more simple types, separated by
389               "|" (pipe).  "|" is meant for union types (e.g. "Str |
390               ArrayRef[Int]" would accept either a string or reference to an
391               array of integers).
392
393           ·   A simple type is an identifier, optionally followed by a list
394               of one or more types, separated by "," (comma), enclosed in "["
395               "]" (square brackets).
396
397           "Function::Parameters" then resolves simple types by looking for
398           functions of the same name in your current package. A type
399           specification like "Str | ArrayRef[Int]" ends up running the Perl
400           code "Str() | ArrayRef([Int()])" (at compile time, while the
401           function definition is being processed). In other words,
402           "Function::Parameters" doesn't support any types natively; it
403           simply uses whatever is in scope.
404
405           You don't have to define these functions yourself. You can also
406           import them from a type library such as "Types::Standard" or
407           "MooseX::Types::Moose".
408
409           The only requirement is that the returned value (here referred to
410           as $tc, for "type constraint") is an object that provides
411           "$tc->check($value)" and "$tc->get_message($value)" methods.
412           "check" is called to determine whether a particular value is valid;
413           it should return a true or false value.  "get_message" is called on
414           values that fail the "check" test; it should return a string that
415           describes the error.
416
417       2.
418            my ($my_type, $some_other_type);
419            BEGIN {
420                $my_type = Some::Constraint::Class->new;
421                $some_other_type = Some::Other::Class->new;
422            }
423
424            fun foo(($my_type) $label, ($some_other_type) $counts) {
425                ...
426            }
427
428           In this variant you enclose an arbitrary Perl expression in "(" ")"
429           (parentheses) and put it in front of a parameter. This expression
430           is evaluated at compile time and must return a type constraint
431           object as described above.  (If you use variables here, make sure
432           they're defined at compile time.)
433
434       Method modifiers
435
436       "Function::Parameters" has support for method modifiers as provided by
437       "Moo" or "Moose". They're not exported by default, so you have to say
438
439        use Function::Parameters qw(:modifiers);
440
441       to get them. This line gives you method modifiers only; "fun" and
442       "method" are not defined. To get both the standard keywords and method
443       modifiers, you can either write two "use" lines:
444
445        use Function::Parameters;
446        use Function::Parameters qw(:modifiers);
447
448       or explicitly list the keywords you want:
449
450        use Function::Parameters qw(fun method :modifiers);
451
452       or add the ":std" import tag (which gives you the default import
453       behavior):
454
455        use Function::Parameters qw(:std :modifiers);
456
457       This defines the following additional keywords: "before", "after",
458       "around", "augment", "override". These work mostly like "method", but
459       they don't install the function into your package themselves. Instead
460       they invoke whatever "before", "after", "around", "augment", or
461       "override" function (respectively) is in scope to do the job.
462
463        before foo($x, $y, $z) {
464            ...
465        }
466
467       works like
468
469        &before('foo', method ($x, $y, $z) {
470            ...
471        });
472
473       "after", "augment", and "override" work the same way.
474
475       "around" is slightly different: Instead of shifting off the first
476       element of @_ into $self (as "method" does), it shifts off two values:
477
478        around foo($x, $y, $z) {
479            ...
480        }
481
482       works like
483
484        &around('foo', sub :method {
485            my $orig = shift;
486            my $self = shift;
487            my ($x, $y, $z) = @_;
488            ...
489        });
490
491       (except you also get the usual "Function::Parameters" features such as
492       checking the number of arguments, etc).
493
494       $orig and $self both count as invocants and you can override their
495       names like this:
496
497        around foo($original, $object: $x, $y, $z) {
498            # $original is a reference to the wrapped method;
499            # $object is the object we're being called on
500            ...
501        }
502
503       If you use ":" to pick your own invocant names in the parameter list of
504       "around", you must specify exactly two variables.
505
506       These modifiers also differ from "fun" and "method" (and "sub") in that
507       they require a function name (there are no anonymous method modifiers)
508       and they take effect at runtime, not compile time. When you say "fun
509       foo() {}", the "foo" function is defined right after the closing "}" of
510       the function body is parsed. But with e.g. "before foo() {}", the
511       declaration becomes a normal function call (to the "before" function in
512       the current package), which is performed at runtime.
513
514       Prototypes and attributes
515
516       You can specify attributes (see "Subroutine Attributes" in perlsub) for
517       your functions using the usual syntax:
518
519        fun deref($x) :lvalue {
520           ${$x}
521        }
522
523        my $silly;
524        deref(\$silly) = 42;
525
526       To specify a prototype (see "Prototypes" in perlsub), use the
527       "prototype" attribute:
528
529        fun mypush($aref, @values) :prototype(\@@) {
530            push @{$aref}, @values;
531        }
532
533       Introspection
534
535       The function "Function::Parameters::info" lets you introspect parameter
536       lists at runtime. It is not exported, so you have to call it by its
537       full name.
538
539       It takes a reference to a function and returns either "undef" (if it
540       knows nothing about the function) or an object that describes the
541       parameter list of the given function. See "Function::Parameters::Info"
542       for details.
543
544   Customizing and extending
545       Wrapping "Function::Parameters"
546
547       Due to its nature as a lexical pragma, importing from
548       "Function::Parameters" always affects the scope that is currently being
549       compiled. If you want to write a wrapper module that enables
550       "Function::Parameters" automatically, just call
551       "Function::Parameters->import" from your own "import" method (and
552       "Function::Parameters->unimport" from your "unimport", as required).
553
554       Gory details of importing
555
556       At the lowest layer "use Function::Parameters ..." takes a list of one
557       or more hash references. Each key is a keyword to be defined as
558       specified by the corresponding value, which must be another hash
559       reference containing configuration options.
560
561        use Function::Parameters
562            {
563                keyword_1 => { ... },
564                keyword_2 => { ... },
565            },
566            {
567                keyword_3 => { ... },
568            };
569
570       If you don't specify a particular option, its default value is used.
571       The available configuration options are:
572
573       "attributes"
574           (string) The attributes that every function declared with this
575           keyword should have (in the form of source code, with a leading
576           ":").
577
578           Default: nothing
579
580       "check_argument_count"
581           (boolean) Whether functions declared with this keyword should check
582           how many arguments they are called with. If false, omitting a
583           required argument sets it to "undef" and excess arguments are
584           silently ignored. If true, an exception is thrown if too few or too
585           many arguments are passed.
586
587           Default: 1
588
589       "check_argument_types"
590           (boolean) Whether functions declared with this keyword should check
591           the types of the arguments they are called with. If false, type
592           constraints are parsed but silently ignored. If true, an exception
593           is thrown if an argument fails a type check.
594
595           Default: 1
596
597       "default_arguments"
598           (boolean) Whether functions declared with this keyword should allow
599           default arguments in their parameter list. If false, default
600           arguments are a compile-time error.
601
602           Default: 1
603
604       "install_sub"
605           (sub name or reference) If this is set, named functions declared
606           with this keyword are not entered into the symbol table directly.
607           Instead the subroutine specified here (by name or reference) is
608           called with two arguments, the name of the function being declared
609           and a reference to its body.
610
611           Default: nothing
612
613       "invocant"
614           (boolean) Whether functions declared with this keyword should allow
615           explicitly specifying invocant(s) at the beginning of the parameter
616           list (as in "($invocant: ...)" or "($invocant1, $invocant2,
617           $invocant3: ...)").
618
619           Default: 0
620
621       "name"
622           (string) There are three possible values for this option.
623           'required' means functions declared with this keyword must have a
624           name. 'prohibited' means specifying a name is not allowed.
625           'optional' means this keyword can be used for both named and
626           anonymous functions.
627
628           Default: 'optional'
629
630       "named_parameters"
631           (boolean) Whether functions declared with this keyword should allow
632           named parameters. If false, named parameters are a compile-time
633           error.
634
635           Default: 1
636
637       "reify_type"
638           (coderef or 'auto' or 'moose') The code reference used to resolve
639           type constraints in functions declared with this keyword.  It is
640           called once for each type constraint that doesn't use the "( EXPR
641           )" syntax, with one argument, the text of the type in the parameter
642           list (e.g.  'ArrayRef[Int]'). The package the function declaration
643           is in is available through "caller".
644
645           The only requirement is that the returned value (here referred to
646           as $tc, for "type constraint") is an object that provides
647           "$tc->check($value)" and "$tc->get_message($value)" methods.
648           "check" is called to determine whether a particular value is valid;
649           it should return a true or false value.  "get_message" is called on
650           values that fail the "check" test; it should return a string that
651           describes the error.
652
653           Instead of a code reference you can also specify one of two
654           strings.
655
656           'auto' stands for a built-in type reifier that treats identifiers
657           as subroutine names, "[" "]" as an array reference, and "|" as
658           bitwise or. In other words, it parses and executes type constraints
659           (mostly) as if they had been Perl source code.
660
661           'moose' stands for a built-in type reifier that loads
662           "Moose::Util::TypeConstraints" and just forwards to
663           "find_or_create_isa_type_constraint".
664
665           Default: 'auto'
666
667       "runtime"
668           (boolean) Whether functions declared with this keyword should be
669           installed into the symbol table at runtime. If false, named
670           functions are defined (or their "install_sub" is invoked if
671           specified) immediately after their declaration is parsed (as with
672           "sub"). If true, function declarations become normal statements
673           that only take effect at runtime (similar to "*foo = sub { ... };"
674           or "$install_sub->('foo', sub { ... });", respectively).
675
676           Default: 0
677
678       "shift"
679           (string or arrayref) In its simplest form, this is the name of a
680           variable that acts as the default invocant (a required leading
681           argument that is removed from @_) for all functions declared with
682           this keyword (e.g.  '$self' for methods). You can also set this to
683           an array reference of strings, which lets you specify multiple
684           default invocants, or even to an array reference of array
685           references of the form "[ $name, $type ]" (where $name is the
686           variable name and $type is a type constraint object), which lets
687           you specify multiple default invocants with type constraints.
688
689           If you define any default invocants here and also allow individual
690           declarations to override the default (with "invocant => 1"), the
691           number of overridden invocants must match the default. For example,
692           "method" has a default invocant of $self, so "method foo($x, $y:
693           $z)" is invalid because it tries to define two invocants.
694
695           Default: "[]" (meaning no invocants)
696
697       "strict"
698           (boolean) Whether functions declared with this keyword should do
699           "strict" checks on their arguments. Currently setting this simply
700           sets "check_argument_count" to the same value with no other
701           effects.
702
703           Default: nothing
704
705       "types"
706           (boolean) Whether functions declared with this keyword should allow
707           type constraints in their parameter lists. If false, trying to use
708           type constraints is a compile-time error.
709
710           Default: 1
711
712       You can get the same effect as "use Function::Parameters;" by saying:
713
714        use Function::Parameters {
715            fun => {
716                # 'fun' uses default settings only
717            },
718            method => {
719                attributes => ':method',
720                shift      => '$self',
721                invocant   => 1,
722                # the rest is defaults
723            },
724        };
725
726       Configuration bundles
727
728       Because specifying all these configuration options from scratch each
729       time is a lot of writing, "Function::Parameters" offers configuration
730       bundles in the form of special strings. These strings can be used to
731       replace a configuration hash completely or as the value of the
732       "defaults" pseudo-option within a configuration hash. The latter lets
733       you use the configuration bundle behind the string to provide defaults
734       and tweak them with your own settings.
735
736       The following bundles are available:
737
738       "function_strict"
739           Equivalent to "{}", i.e. all defaults.
740
741       "function_lax"
742           Equivalent to:
743
744            {
745                defaults => 'function_strict',
746                strict   => 0,
747            }
748
749           i.e. just like "function_strict" but with "strict" checks turned
750           off.
751
752       "function"
753           Equivalent to "function_strict". This is what the default "fun"
754           keyword actually uses. (In version 1 of this module, "function" was
755           equivalent to "function_lax".)
756
757       "method_strict"
758           Equivalent to:
759
760            {
761                defaults   => 'function_strict',
762                attributes => ':method',
763                shift      => '$self',
764                invocant   => 1,
765            }
766
767       "method_lax"
768           Equivalent to:
769
770            {
771                defaults => 'method_strict',
772                strict   => 0,
773            }
774
775           i.e. just like "method_strict" but with "strict" checks turned off.
776
777       "method"
778           Equivalent to "method_strict". This is what the default "method"
779           keyword actually uses. (In version 1 of this module, "method" was
780           equivalent to "method_lax".)
781
782       "classmethod_strict"
783           Equivalent to:
784
785            {
786                defaults => 'method_strict',
787                shift    => '$class',
788            }
789
790           i.e. just like "method_strict" but the implicit first parameter is
791           called $class, not $self.
792
793       "classmethod_lax"
794           Equivalent to:
795
796            {
797                defaults => 'classmethod_strict',
798                strict   => 0,
799            }
800
801           i.e. just like "classmethod_strict" but with "strict" checks turned
802           off.
803
804       "classmethod"
805           Equivalent to "classmethod_strict". This is currently not used
806           anywhere within "Function::Parameters".
807
808       "around"
809           Equivalent to:
810
811            {
812                defaults    => 'method',
813                install_sub => 'around',
814                shift       => ['$orig', '$self'],
815                runtime     => 1,
816                name        => 'required',
817            }
818
819           i.e. just like "method" but with a custom installer ('around'), two
820           implicit first parameters, only taking effect at runtime, and a
821           method name is required.
822
823       "before"
824           Equivalent to:
825
826            {
827                defaults    => 'method',
828                install_sub => 'before',
829                runtime     => 1,
830                name        => 'required',
831            }
832
833           i.e. just like "method" but with a custom installer ('before'),
834           only taking effect at runtime, and a method name is required.
835
836       "after"
837           Equivalent to:
838
839            {
840                defaults    => 'method',
841                install_sub => 'after',
842                runtime     => 1,
843                name        => 'required',
844            }
845
846           i.e. just like "method" but with a custom installer ('after'), only
847           taking effect at runtime, and a method name is required.
848
849       "augment"
850           Equivalent to:
851
852            {
853                defaults    => 'method',
854                install_sub => 'augment',
855                runtime     => 1,
856                name        => 'required',
857            }
858
859           i.e. just like "method" but with a custom installer ('augment'),
860           only taking effect at runtime, and a method name is required.
861
862       "override"
863           Equivalent to:
864
865            {
866                defaults    => 'method',
867                install_sub => 'override',
868                runtime     => 1,
869                name        => 'required',
870            }
871
872           i.e. just like "method" but with a custom installer ('override'),
873           only taking effect at runtime, and a method name is required.
874
875       You can get the same effect as "use Function::Parameters;" by saying:
876
877        use Function::Parameters {
878            fun    => { defaults => 'function' },
879            method => { defaults => 'method' },
880        };
881
882       or:
883
884        use Function::Parameters {
885            fun    => 'function',
886            method => 'method',
887        };
888
889       Import tags
890
891       In addition to hash references you can also use special strings in your
892       import list. The following import tags are available:
893
894       'fun'
895           Equivalent to "{ fun => 'function' }".
896
897       'method'
898           Equivalent to "{ method => 'method' }".
899
900       'classmethod'
901           Equivalent to "{ classmethod => 'classmethod' }".
902
903       'before'
904           Equivalent to "{ before => 'before' }".
905
906       'after'
907           Equivalent to "{ after => 'after' }".
908
909       'around'
910           Equivalent to "{ around => 'around' }".
911
912       'augment'
913           Equivalent to "{ augment => 'augment' }".
914
915       'override'
916           Equivalent to "{ override => 'override' }".
917
918       ':strict'
919           Equivalent to "{ fun => 'function_strict', method =>
920           'method_strict' }" but that's just the default behavior anyway.
921
922       ':lax'
923           Equivalent to "{ fun => 'function_lax', method => 'method_lax' }",
924           i.e. it provides "fun" and "method" keywords that define functions
925           that don't check their arguments.
926
927       ':std'
928           Equivalent to 'fun', 'method'. This is what's used by default:
929
930            use Function::Parameters;
931
932           is the same as:
933
934            use Function::Parameters qw(:std);
935
936       ':modifiers'
937           Equivalent to 'before', 'after', 'around', 'augment', 'override'.
938
939       For example, when you say
940
941        use Function::Parameters qw(:modifiers);
942
943       ":modifiers" is an import tag that expands to
944
945        use Function::Parameters qw(before after around augment override);
946
947       Each of those is another import tag. Stepping through the first one:
948
949        use Function::Parameters qw(before);
950
951       is equivalent to:
952
953        use Function::Parameters { before => 'before' };
954
955       This says to define the keyword "before" according to the configuration
956       bundle "before":
957
958        use Function::Parameters {
959            before => {
960                defaults    => 'method',
961                install_sub => 'before',
962                runtime     => 1,
963                name        => 'required',
964            },
965        };
966
967       The "defaults => 'method'" part pulls in the contents of the 'method'
968       configuration bundle (which is the same as 'method_strict'):
969
970        use Function::Parameters {
971            before => {
972                defaults    => 'function_strict',
973                attributes  => ':method',
974                shift       => '$self',
975                invocant    => 1,
976                install_sub => 'before',
977                runtime     => 1,
978                name        => 'required',
979            },
980        };
981
982       This in turn uses the 'function_strict' configuration bundle (which is
983       empty because it consists of default values only):
984
985        use Function::Parameters {
986            before => {
987                attributes  => ':method',
988                shift       => '$self',
989                invocant    => 1,
990                install_sub => 'before',
991                runtime     => 1,
992                name        => 'required',
993            },
994        };
995
996       But if we wanted to be completely explicit, we could write this as:
997
998        use Function::Parameters {
999            before => {
1000                check_argument_count => 1,
1001                check_argument_types => 1,
1002                default_arguments    => 1,
1003                named_parameters     => 1,
1004                reify_type           => 'auto',
1005                types                => 1,
1006
1007                attributes  => ':method',
1008                shift       => '$self',
1009                invocant    => 1,
1010                install_sub => 'before',
1011                runtime     => 1,
1012                name        => 'required',
1013            },
1014        };
1015
1016   Incompatibilites with version 1 of "Function::Parameters"
1017       ·   Version 1 defaults to lax mode (no argument checks). To get the
1018           same behavior on both version 1 and version 2, explicitly write
1019           either "use Function::Parameters qw(:strict);" (the new default) or
1020           "use Function::Parameters qw(:lax);" (the old default). (Or write
1021           "use Function::Parameters 2;" to trigger an error if an older
1022           version of "Function::Parameters" is loaded.)
1023
1024       ·   Parameter lists used to be optional. The syntax "fun foo { ... }"
1025           would accept any number of arguments. This syntax has been removed;
1026           you now have to write "fun foo(@) { ... }" to accept (and ignore)
1027           all arguments. On the other hand, if you meant for the function to
1028           take no arguments, write "fun foo() { ... }".
1029
1030       ·   There used to be a shorthand syntax for prototypes: Using ":(...)"
1031           (i.e. an attribute with an empty name) as the first attribute was
1032           equivalent to ":prototype(...)". This syntax has been removed.
1033
1034       ·   The default type reifier used to be hardcoded to use "Moose" (as in
1035           "reify_type => 'moose'"). This has been changed to use whatever
1036           type functions are in scope ("reify_type => 'auto'").
1037
1038       ·   Type reifiers used to see the wrong package in "caller". As a
1039           workaround the correct calling package used to be passed as a
1040           second argument. This problem has been fixed and the second
1041           argument has been removed. (Technically this is a core perl bug (RT
1042           #129239 <https://rt.perl.org/Public/Bug/Display.html?id=129239>)
1043           that wasn't so much fixed as worked around in
1044           "Function::Parameters".)
1045
1046           If you want your type reifier to be compatible with both versions,
1047           you can do this:
1048
1049            sub my_reifier {
1050                my ($type, $package) = @_;
1051                $package //= caller;
1052                ...
1053            }
1054
1055           Or using "Function::Parameters" itself:
1056
1057            fun my_reifier($type, $package = caller) {
1058                ...
1059            }
1060

SUPPORT AND DOCUMENTATION

1062       After installing, you can find documentation for this module with the
1063       "perldoc" command.
1064
1065           perldoc Function::Parameters
1066
1067       You can also look for information at
1068       <https://metacpan.org/pod/Function::Parameters>.
1069
1070       To see a list of open bugs, visit
1071       <https://rt.cpan.org/Public/Dist/Display.html?Name=Function-Parameters>.
1072
1073       To report a new bug, send an email to "bug-Function-Parameters [at]
1074       rt.cpan.org".
1075

SEE ALSO

1077       Function::Parameters::Info, Moose, Moo, Type::Tiny
1078

AUTHOR

1080       Lukas Mai, "<l.mai at web.de>"
1081
1083       Copyright (C) 2010-2014, 2017 Lukas Mai.
1084
1085       This program is free software; you can redistribute it and/or modify it
1086       under the terms of either: the GNU General Public License as published
1087       by the Free Software Foundation; or the Artistic License.
1088
1089       See <http://dev.perl.org/licenses/> for more information.
1090
1091
1092
1093perl v5.30.1                      2020-01-30           Function::Parameters(3)
Impressum