1 package Function::Parameters;
12 our $VERSION = '0.06';
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',
59 if (@_ == 1 && ref($_[0]) eq 'HASH') {
60 @_ = map [$_, $_[0]{$_}], keys %{$_[0]}
70 : [$proto, $bare_arms[$bare++] || confess(qq{Don't know what to do with "$proto"})]
72 my ($name, $proto_type) = @$item;
73 _assert_valid_identifier $name;
75 unless (ref $proto_type) {
76 # use '||' instead of 'or' to preserve $proto_type in the error message
77 $proto_type = $type_map{$proto_type}
78 || confess qq["$proto_type" doesn't look like a valid type (one of ${\join ', ', sort keys %type_map})];
81 my %type = %$proto_type;
84 $clean{name} = delete $type{name} || 'optional';
85 $clean{name} =~ /^(?:optional|required|prohibited)\z/
86 or confess qq["$clean{name}" doesn't look like a valid name attribute (one of optional, required, prohibited)];
88 $clean{shift} = delete $type{shift} || '';
89 _assert_valid_identifier $clean{shift}, 1 if $clean{shift};
91 $clean{attrs} = join ' ', map delete $type{$_} || (), qw(attributes attrs);
92 _assert_valid_attributes $clean{attrs} if $clean{attrs};
94 $clean{default_arguments} =
95 exists $type{default_arguments}
96 ? !!delete $type{default_arguments}
99 $clean{check_argument_count} = !!delete $type{check_argument_count};
101 %type and confess "Invalid keyword property: @{[keys %type]}";
103 $spec{$name} = \%clean;
106 for my $kw (keys %spec) {
107 my $type = $spec{$kw};
110 $type->{name} eq 'prohibited' ? FLAG_ANON_OK :
111 $type->{name} eq 'required' ? FLAG_NAME_OK :
112 FLAG_ANON_OK | FLAG_NAME_OK
114 $flags |= FLAG_DEFAULT_ARGS if $type->{default_arguments};
115 $flags |= FLAG_CHECK_NARGS if $type->{check_argument_count};
116 $^H{HINTK_FLAGS_ . $kw} = $flags;
117 $^H{HINTK_SHIFT_ . $kw} = $type->{shift};
118 $^H{HINTK_ATTRS_ . $kw} = $type->{attrs};
119 $^H{+HINTK_KEYWORDS} .= "$kw ";
127 delete $^H{+HINTK_KEYWORDS};
132 $^H{+HINTK_KEYWORDS} =~ s/(?<![^ ])\Q$kw\E //g;
145 Function::Parameters - subroutine definitions with parameter lists
149 use Function::Parameters;
152 fun foo($bar, $baz) {
156 # function with prototype
157 fun mymap($fun, @args) :(&@) {
160 push @res, $fun->($_);
165 print "$_\n" for mymap { $_ * 2 } 1 .. 4;
167 # method with implicit $self
168 method set_name($name) {
169 $self->{name} = $name;
172 # function with default arguments
173 fun search($haystack, $needle = qr/^(?!)/, $offset = 0) {
177 # method with default arguments
178 method skip($amount = 1) {
179 $self->{position} += $amount;
186 # use different keywords
187 use Function::Parameters {
192 my $f = proc ($x) { $x * 2 };
199 This module lets you use parameter lists in your subroutines. Thanks to
200 L<PL_keyword_plugin|perlapi/PL_keyword_plugin> it works without source filters.
202 WARNING: This is my first attempt at writing L<XS code|perlxs> and I have
203 almost no experience with perl's internals. So while this module might
204 appear to work, it could also conceivably make your programs segfault.
205 Consider this module alpha quality.
209 To use this new functionality, you have to use C<fun> instead of C<sub> -
210 C<sub> continues to work as before. The syntax is almost the same as for
211 C<sub>, but after the subroutine name (or directly after C<fun> if you're
212 writing an anonymous sub) you can write a parameter list in parentheses. This
213 list consists of comma-separated variables.
215 The effect of C<fun foo($bar, $baz) {> is as if you'd written
216 C<sub foo { my ($bar, $baz) = @_; >, i.e. the parameter list is simply
217 copied into L<my|perlfunc/my-EXPR> and initialized from L<@_|perlvar/"@_">.
219 In addition you can use C<method>, which understands the same syntax as C<fun>
220 but automatically creates a C<$self> variable for you. So by writing
221 C<method foo($bar, $baz) {> you get the same effect as
222 C<sub foo { my $self = shift; my ($bar, $baz) = @_; >.
224 =head2 Customizing the generated keywords
226 You can customize the names of the keywords injected into your scope. To do
227 that you pass a reference to a hash mapping keywords to types in the import
230 use Function::Parameters {
238 use Function::Parameters { proc => 'function', meth => 'method' }; # -or-
239 use Function::Parameters { proc => 'function' }; # -or-
240 use Function::Parameters { meth => 'method' }; # etc.
242 The first line creates two keywords, C<proc> and C<meth> (for defining
243 functions and methods, respectively). The last two lines only create one
244 keyword. Generally the hash keys (keywords) can be any identifiers you want
245 while the values (types) have to be either C<'function'>, C<'method'>,
246 C<'classmethod'>, or a hash reference (see below). The main difference between
247 C<'function'> and C<'method'> is that C<'method'>s automatically
248 L<shift|perlfunc/shift> their first argument into C<$self> (C<'classmethod'>s
249 are similar but shift into C<$class>).
251 The following shortcuts are available:
253 use Function::Parameters;
255 use Function::Parameters { fun => 'function', method => 'method' };
261 The following shortcuts are deprecated and may be removed from a future version
265 use Function::Parameters 'foo';
267 use Function::Parameters { 'foo' => 'function' };
274 use Function::Parameters 'foo', 'bar';
276 use Function::Parameters { 'foo' => 'function', 'bar' => 'method' };
278 That is, if you want to pass arguments to L<Function::Parameters>, use a
279 hashref, not a list of strings.
281 You can customize the properties of the generated keywords even more by passing
282 a hashref instead of a string. This hash can have the following keys:
288 Valid values: C<optional> (default), C<required> (all uses of this keyword must
289 specify a function name), and C<prohibited> (all uses of this keyword must not
290 specify a function name). This means a C<< name => 'prohibited' >> keyword can
291 only be used for defining anonymous functions.
295 Valid values: strings that look like a scalar variable. Any function created by
296 this keyword will automatically L<shift|perlfunc/shift> its first argument into
297 a local variable whose name is specified here.
299 =item C<attributes>, C<attrs>
301 Valid values: strings that are valid source code for attributes. Any value
302 specified here will be inserted as a subroutine attribute in the generated
305 use Function::Parameters { sub_l => { attributes => ':lvalue' } };
316 It is recommended that you use C<attributes> in new code but C<attrs> is also
319 =item C<default_arguments>
321 Valid values: booleans. This property is on by default, so you have to pass
322 C<< default_arguments => 0 >> to turn it off. If it is disabled, using C<=> in
323 a parameter list causes a syntax error. Otherwise it lets you specify
324 default arguments directly in the parameter list:
326 fun foo($x, $y = 42, $z = []) {
333 my ($x, $y, $z) = @_;
339 except that none of the parameters are in scope in the expressions that specify
340 default values. Thus:
344 fun foo($var, $wat = $var) {
345 # $wat will default to "outer", not to what was passed
346 # as the first argument!
350 This may change in a future version of this module.
352 =item C<check_argument_count>
354 Valid values: booleans. This property is off by default. If it is enabled, the
355 generated code will include checks to make sure the number of passed arguments
356 is correct (and otherwise throw an exception via L<Carp::croak|Carp>):
358 fun foo($x, $y = 42, $z = []) {
365 Carp::croak "Not enough arguments for fun foo" if @_ < 1;
366 Carp::croak "Too many arguments for fun foo" if @_ > 3;
367 my ($x, $y, $z) = @_;
375 Plain C<'function'> is equivalent to:
379 default_arguments => 1,
380 check_argument_count => 0,
383 (These are all default values so C<'function'> is also equivalent to C<{}>.)
385 C<'method'> is equivalent to:
389 default_arguments => 1,
390 check_argument_count => 0,
391 attributes => ':method',
395 C<'classmethod'> is equivalent to:
399 default_arguments => 1,
400 check_argument_count => 0,
401 attributes => ':method',
405 =head2 Syntax and generated code
407 Normally, Perl subroutines are not in scope in their own body, meaning the
408 parser doesn't know the name C<foo> or its prototype while processing the body
409 of C<sub foo ($) { foo $bar[1], $bar[0]; }>, parsing it as
410 C<$bar-E<gt>foo([1], $bar[0])>. Yes. You can add parens to change the
411 interpretation of this code, but C<foo($bar[1], $bar[0])> will only trigger
412 a I<foo() called too early to check prototype> warning. This module attempts
413 to fix all of this by adding a subroutine declaration before the function body,
414 so the parser knows the name (and possibly prototype) while it processes the
415 body. Thus C<fun foo($x) :($) { $x }> really turns into
416 C<sub foo ($) { sub foo ($); my ($x) = @_; $x }>.
418 If you need L<subroutine attributes|perlsub/Subroutine-Attributes>, you can
419 put them after the parameter list with their usual syntax.
421 Syntactically, these new parameter lists live in the spot normally occupied
422 by L<prototypes|perlsub/"Prototypes">. However, you can include a prototype by
423 specifying it as the first attribute (this is syntactically unambiguous
424 because normal attributes have to start with a letter while a prototype starts
427 As an example, the following declaration uses every available feature
428 (subroutine name, parameter list, default arguments, prototype, default
429 attributes, attributes, argument count checks, and implicit C<$self>):
431 method foo($x, $y, $z = sqrt 5) :($$$;$) :lvalue :Banana(2 + 2) {
435 And here's what it turns into:
437 sub foo ($$$;$) :method :lvalue :Banana(2 + 2) {
439 Carp::croak "Not enough arguments for method foo" if @_ < 2;
440 Carp::croak "Too many arguments for method foo" if @_ > 4;
442 my ($x, $y, $z) = @_;
443 $z = sqrt 5 if @_ < 3;
449 my $coderef = fun ($p, $q) :(;$$)
455 And the generated code:
457 my $coderef = sub (;$$) :lvalue :Gazebo((>:O)) {
458 # vvv only if check_argument_count is enabled vvv
459 Carp::croak "Not enough arguments for fun (anon)" if @_ < 2;
460 Carp::croak "Too many arguments for fun (anon)" if @_ > 2;
465 =head2 Wrapping Function::Parameters
467 If you want to wrap L<Function::Parameters>, you just have to call its
468 C<import> method. It always applies to the file that is currently being parsed
469 and its effects are L<lexical|perlpragma> (i.e. it works like L<warnings> or
472 package Some::Wrapper;
473 use Function::Parameters ();
475 Function::Parameters->import;
476 # or Function::Parameters->import(@custom_import_args);
481 Lukas Mai, C<< <l.mai at web.de> >>
483 =head1 COPYRIGHT & LICENSE
485 Copyright 2010, 2011, 2012 Lukas Mai.
487 This program is free software; you can redistribute it and/or modify it
488 under the terms of either: the GNU General Public License as published
489 by the Free Software Foundation; or the Artistic License.
491 See http://dev.perl.org/licenses/ for more information.