1 package Function::Parameters;
12 our $VERSION = '0.06_01';
16 sub _assert_valid_identifier {
17 my ($name, $with_dollar) = @_;
18 my $bonus = $with_dollar ? '\$' : '';
19 $name =~ /^${bonus}[^\W\d]\w*\z/
20 or confess qq{"$name" doesn't look like a valid identifier};
23 sub _assert_valid_attributes {
25 $attrs =~ /^\s*:\s*[^\W\d]\w*\s*(?:(?:\s|:\s*)[^\W\d]\w*\s*)*(?:\(|\z)/
26 or confess qq{"$attrs" doesn't look like valid attributes};
29 my @bare_arms = qw(function method);
33 default_arguments => 1,
34 check_argument_count => 0,
38 default_arguments => 1,
39 check_argument_count => 0,
45 default_arguments => 1,
46 check_argument_count => 0,
47 attributes => ':method',
51 for my $k (keys %type_map) {
52 $type_map{$k . '_strict'} = {
54 check_argument_count => 1,
65 if (@_ == 1 && ref($_[0]) eq 'HASH') {
66 @_ = map [$_, $_[0]{$_}], keys %{$_[0]}
76 : [$proto, $bare_arms[$bare++] || confess(qq{Don't know what to do with "$proto"})]
78 my ($name, $proto_type) = @$item;
79 _assert_valid_identifier $name;
81 unless (ref $proto_type) {
82 # use '||' instead of 'or' to preserve $proto_type in the error message
83 $proto_type = $type_map{$proto_type}
84 || confess qq["$proto_type" doesn't look like a valid type (one of ${\join ', ', sort keys %type_map})];
87 my %type = %$proto_type;
90 $clean{name} = delete $type{name} || 'optional';
91 $clean{name} =~ /^(?:optional|required|prohibited)\z/
92 or confess qq["$clean{name}" doesn't look like a valid name attribute (one of optional, required, prohibited)];
94 $clean{shift} = delete $type{shift} || '';
95 _assert_valid_identifier $clean{shift}, 1 if $clean{shift};
97 $clean{attrs} = join ' ', map delete $type{$_} || (), qw(attributes attrs);
98 _assert_valid_attributes $clean{attrs} if $clean{attrs};
100 $clean{default_arguments} =
101 exists $type{default_arguments}
102 ? !!delete $type{default_arguments}
105 $clean{check_argument_count} = !!delete $type{check_argument_count};
107 %type and confess "Invalid keyword property: @{[keys %type]}";
109 $spec{$name} = \%clean;
112 for my $kw (keys %spec) {
113 my $type = $spec{$kw};
116 $type->{name} eq 'prohibited' ? FLAG_ANON_OK :
117 $type->{name} eq 'required' ? FLAG_NAME_OK :
118 FLAG_ANON_OK | FLAG_NAME_OK
120 $flags |= FLAG_DEFAULT_ARGS if $type->{default_arguments};
121 $flags |= FLAG_CHECK_NARGS if $type->{check_argument_count};
122 $^H{HINTK_FLAGS_ . $kw} = $flags;
123 $^H{HINTK_SHIFT_ . $kw} = $type->{shift};
124 $^H{HINTK_ATTRS_ . $kw} = $type->{attrs};
125 $^H{+HINTK_KEYWORDS} .= "$kw ";
133 delete $^H{+HINTK_KEYWORDS};
138 $^H{+HINTK_KEYWORDS} =~ s/(?<![^ ])\Q$kw\E //g;
151 Function::Parameters - subroutine definitions with parameter lists
155 use Function::Parameters;
158 fun foo($bar, $baz) {
162 # function with prototype
163 fun mymap($fun, @args) :(&@) {
166 push @res, $fun->($_);
171 print "$_\n" for mymap { $_ * 2 } 1 .. 4;
173 # method with implicit $self
174 method set_name($name) {
175 $self->{name} = $name;
178 # function with default arguments
179 fun search($haystack, $needle = qr/^(?!)/, $offset = 0) {
183 # method with default arguments
184 method skip($amount = 1) {
185 $self->{position} += $amount;
192 # use different keywords
193 use Function::Parameters {
198 my $f = proc ($x) { $x * 2 };
205 This module lets you use parameter lists in your subroutines. Thanks to
206 L<PL_keyword_plugin|perlapi/PL_keyword_plugin> it works without source filters.
208 WARNING: This is my first attempt at writing L<XS code|perlxs> and I have
209 almost no experience with perl's internals. So while this module might
210 appear to work, it could also conceivably make your programs segfault.
211 Consider this module alpha quality.
215 To use this new functionality, you have to use C<fun> instead of C<sub> -
216 C<sub> continues to work as before. The syntax is almost the same as for
217 C<sub>, but after the subroutine name (or directly after C<fun> if you're
218 writing an anonymous sub) you can write a parameter list in parentheses. This
219 list consists of comma-separated variables.
221 The effect of C<fun foo($bar, $baz) {> is as if you'd written
222 C<sub foo { my ($bar, $baz) = @_; >, i.e. the parameter list is simply
223 copied into L<my|perlfunc/my-EXPR> and initialized from L<@_|perlvar/"@_">.
225 In addition you can use C<method>, which understands the same syntax as C<fun>
226 but automatically creates a C<$self> variable for you. So by writing
227 C<method foo($bar, $baz) {> you get the same effect as
228 C<sub foo { my $self = shift; my ($bar, $baz) = @_; >.
230 =head2 Customizing the generated keywords
232 You can customize the names of the keywords injected into your scope. To do
233 that you pass a reference to a hash mapping keywords to types in the import
236 use Function::Parameters {
244 use Function::Parameters { proc => 'function', meth => 'method' }; # -or-
245 use Function::Parameters { proc => 'function' }; # -or-
246 use Function::Parameters { meth => 'method' }; # etc.
248 The first line creates two keywords, C<proc> and C<meth> (for defining
249 functions and methods, respectively). The last two lines only create one
250 keyword. Generally the hash keys (keywords) can be any identifiers you want
251 while the values (types) have to be either a hash reference (see below) or
252 C<'function'>, C<'method'>, C<'classmethod'>, C<'function_strict'>,
253 C<'method_strict'>, or C<'classmethod_strict'>. The main difference between
254 C<'function'> and C<'method'> is that C<'method'>s automatically
255 L<shift|perlfunc/shift> their first argument into C<$self> (C<'classmethod'>s
256 are similar but shift into C<$class>).
258 The following shortcuts are available:
260 use Function::Parameters;
262 use Function::Parameters { fun => 'function', method => 'method' };
268 The following shortcuts are deprecated and may be removed from a future version
272 use Function::Parameters 'foo';
274 use Function::Parameters { 'foo' => 'function' };
281 use Function::Parameters 'foo', 'bar';
283 use Function::Parameters { 'foo' => 'function', 'bar' => 'method' };
285 That is, if you want to pass arguments to L<Function::Parameters>, use a
286 hashref, not a list of strings.
288 You can customize the properties of the generated keywords even more by passing
289 a hashref instead of a string. This hash can have the following keys:
295 Valid values: C<optional> (default), C<required> (all uses of this keyword must
296 specify a function name), and C<prohibited> (all uses of this keyword must not
297 specify a function name). This means a C<< name => 'prohibited' >> keyword can
298 only be used for defining anonymous functions.
302 Valid values: strings that look like a scalar variable. Any function created by
303 this keyword will automatically L<shift|perlfunc/shift> its first argument into
304 a local variable whose name is specified here.
306 =item C<attributes>, C<attrs>
308 Valid values: strings that are valid source code for attributes. Any value
309 specified here will be inserted as a subroutine attribute in the generated
312 use Function::Parameters { sub_l => { attributes => ':lvalue' } };
323 It is recommended that you use C<attributes> in new code but C<attrs> is also
326 =item C<default_arguments>
328 Valid values: booleans. This property is on by default, so you have to pass
329 C<< default_arguments => 0 >> to turn it off. If it is disabled, using C<=> in
330 a parameter list causes a syntax error. Otherwise it lets you specify
331 default arguments directly in the parameter list:
333 fun foo($x, $y = 42, $z = []) {
340 my ($x, $y, $z) = @_;
346 You can even refer to previous parameters in the same parameter list:
348 print fun ($x, $y = $x + 1) { "$x and $y" }->(9); # "9 and 10"
350 This also works with the implicit first parameter of methods:
352 method scale($factor = $self->default_factor) {
353 $self->{amount} *= $factor;
356 =item C<check_argument_count>
358 Valid values: booleans. This property is off by default. If it is enabled, the
359 generated code will include checks to make sure the number of passed arguments
360 is correct (and otherwise throw an exception via L<Carp::croak|Carp>):
362 fun foo($x, $y = 42, $z = []) {
369 Carp::croak "Not enough arguments for fun foo" if @_ < 1;
370 Carp::croak "Too many arguments for fun foo" if @_ > 3;
371 my ($x, $y, $z) = @_;
379 Plain C<'function'> is equivalent to:
383 default_arguments => 1,
384 check_argument_count => 0,
387 (These are all default values so C<'function'> is also equivalent to C<{}>.)
389 C<'function_strict'> is like C<'function'> but with
390 C<< check_argument_count => 1 >>.
392 C<'method'> is equivalent to:
396 default_arguments => 1,
397 check_argument_count => 0,
398 attributes => ':method',
402 C<'method_strict'> is like C<'method'> but with
403 C<< check_argument_count => 1 >>.
405 C<'classmethod'> is equivalent to:
409 default_arguments => 1,
410 check_argument_count => 0,
411 attributes => ':method',
415 C<'classmethod_strict'> is like C<'classmethod'> but with
416 C<< check_argument_count => 1 >>.
418 =head2 Syntax and generated code
420 Normally, Perl subroutines are not in scope in their own body, meaning the
421 parser doesn't know the name C<foo> or its prototype while processing the body
422 of C<sub foo ($) { foo $bar[1], $bar[0]; }>, parsing it as
423 C<$bar-E<gt>foo([1], $bar[0])>. Yes. You can add parens to change the
424 interpretation of this code, but C<foo($bar[1], $bar[0])> will only trigger
425 a I<foo() called too early to check prototype> warning. This module attempts
426 to fix all of this by adding a subroutine declaration before the function body,
427 so the parser knows the name (and possibly prototype) while it processes the
428 body. Thus C<fun foo($x) :($) { $x }> really turns into
429 C<sub foo ($) { sub foo ($); my ($x) = @_; $x }>.
431 If you need L<subroutine attributes|perlsub/Subroutine-Attributes>, you can
432 put them after the parameter list with their usual syntax.
434 Syntactically, these new parameter lists live in the spot normally occupied
435 by L<prototypes|perlsub/"Prototypes">. However, you can include a prototype by
436 specifying it as the first attribute (this is syntactically unambiguous
437 because normal attributes have to start with a letter while a prototype starts
440 As an example, the following declaration uses every available feature
441 (subroutine name, parameter list, default arguments, prototype, default
442 attributes, attributes, argument count checks, and implicit C<$self>):
444 method foo($x, $y, $z = sqrt 5) :($$$;$) :lvalue :Banana(2 + 2) {
448 And here's what it turns into:
450 sub foo ($$$;$) :method :lvalue :Banana(2 + 2) {
452 Carp::croak "Not enough arguments for method foo" if @_ < 2;
453 Carp::croak "Too many arguments for method foo" if @_ > 4;
455 my ($x, $y, $z) = @_;
456 $z = sqrt 5 if @_ < 3;
462 my $coderef = fun ($p, $q) :(;$$)
468 And the generated code:
470 my $coderef = sub (;$$) :lvalue :Gazebo((>:O)) {
471 # vvv only if check_argument_count is enabled vvv
472 Carp::croak "Not enough arguments for fun (anon)" if @_ < 2;
473 Carp::croak "Too many arguments for fun (anon)" if @_ > 2;
479 =head2 Wrapping Function::Parameters
481 If you want to wrap L<Function::Parameters>, you just have to call its
482 C<import> method. It always applies to the file that is currently being parsed
483 and its effects are L<lexical|perlpragma> (i.e. it works like L<warnings> or
486 package Some::Wrapper;
487 use Function::Parameters ();
489 Function::Parameters->import;
490 # or Function::Parameters->import(@custom_import_args);
495 Lukas Mai, C<< <l.mai at web.de> >>
497 =head1 COPYRIGHT & LICENSE
499 Copyright 2010, 2011, 2012 Lukas Mai.
501 This program is free software; you can redistribute it and/or modify it
502 under the terms of either: the GNU General Public License as published
503 by the Free Software Foundation; or the Artistic License.
505 See http://dev.perl.org/licenses/ for more information.