1 package Function::Parameters;
10 our $VERSION = '0.05_03';
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);
31 function => { name => 'optional' },
51 if (@_ == 1 && ref($_[0]) eq 'HASH') {
52 @_ = map [$_, $_[0]{$_}], keys %{$_[0]}
62 : [$proto, $bare_arms[$bare++] || confess(qq{Don't know what to do with "$proto"})]
64 my ($name, $proto_type) = @$item;
65 _assert_valid_identifier $name;
67 unless (ref $proto_type) {
68 # use '||' instead of 'or' to preserve $proto_type in the error message
69 $proto_type = $type_map{$proto_type}
70 || confess qq["$proto_type" doesn't look like a valid type (one of ${\join ', ', sort keys %type_map})];
73 my %type = %$proto_type;
76 $clean{name} = delete $type{name} || 'optional';
77 $clean{name} =~ /^(?:optional|required|prohibited)\z/
78 or confess qq["$clean{name}" doesn't look like a valid name attribute (one of optional, required, prohibited)];
80 $clean{shift} = delete $type{shift} || '';
81 _assert_valid_identifier $clean{shift}, 1 if $clean{shift};
83 $clean{attrs} = delete $type{attrs} || '';
84 _assert_valid_attributes $clean{attrs} if $clean{attrs};
86 %type and confess "Invalid keyword property: @{[keys %type]}";
88 $spec{$name} = \%clean;
91 for my $kw (keys %spec) {
92 my $type = $spec{$kw};
94 $^H{HINTK_SHIFT_ . $kw} = $type->{shift};
95 $^H{HINTK_ATTRS_ . $kw} = $type->{attrs};
96 $^H{HINTK_NAME_ . $kw} =
97 $type->{name} eq 'prohibited' ? FLAG_NAME_PROHIBITED :
98 $type->{name} eq 'required' ? FLAG_NAME_REQUIRED :
101 $^H{+HINTK_KEYWORDS} .= "$kw ";
109 delete $^H{+HINTK_KEYWORDS};
114 $^H{+HINTK_KEYWORDS} =~ s/(?<![^ ])\Q$kw\E //g;
127 Function::Parameters - subroutine definitions with parameter lists
131 use Function::Parameters;
133 fun foo($bar, $baz) {
137 fun mymap($fun, @args) :(&@) {
140 push @res, $fun->($_);
145 print "$_\n" for mymap { $_ * 2 } 1 .. 4;
147 method set_name($name) {
148 $self->{name} = $name;
155 use Function::Parameters {
160 my $f = proc ($x) { $x * 2 };
167 This module lets you use parameter lists in your subroutines. Thanks to
168 L<PL_keyword_plugin|perlapi/PL_keyword_plugin> it works without source filters.
170 WARNING: This is my first attempt at writing L<XS code|perlxs> and I have
171 almost no experience with perl's internals. So while this module might
172 appear to work, it could also conceivably make your programs segfault.
173 Consider this module alpha quality.
177 To use this new functionality, you have to use C<fun> instead of C<sub> -
178 C<sub> continues to work as before. The syntax is almost the same as for
179 C<sub>, but after the subroutine name (or directly after C<fun> if you're
180 writing an anonymous sub) you can write a parameter list in parentheses. This
181 list consists of comma-separated variables.
183 The effect of C<fun foo($bar, $baz) {> is as if you'd written
184 C<sub foo { my ($bar, $baz) = @_; >, i.e. the parameter list is simply
185 copied into C<my> and initialized from L<@_|perlvar/"@_">.
187 In addition you can use C<method>, which understands the same syntax as C<fun>
188 but automatically creates a C<$self> variable for you. So by writing
189 C<method foo($bar, $baz) {> you get the same effect as
190 C<sub foo { my $self = shift; my ($bar, $baz) = @_; >.
192 =head2 Customizing the generated keywords
194 You can customize the names of the keywords injected into your scope. To do
195 that you pass a hash reference in the import list:
197 use Function::Parameters { proc => 'function', meth => 'method' }; # -or-
198 use Function::Parameters { proc => 'function' }; # -or-
199 use Function::Parameters { meth => 'method' }; # etc.
201 The first line creates two keywords, C<proc> and C<meth> (for defining
202 functions and methods, respectively). The last two lines only create one
203 keyword. Generally the hash keys can be any identifiers you want while the
204 values have to be either C<function>, C<method>, C<classmethod> or a hash
205 reference (see below). The difference between C<function> and C<method> is that
206 C<method>s automatically L<shift|perlfunc/shift> their first argument into
207 C<$self> (C<classmethod>s are similar but shift into C<$class>).
209 The following shortcuts are available:
211 use Function::Parameters;
213 use Function::Parameters { fun => 'function', method => 'method' };
219 The following shortcuts are deprecated and may be removed from a future version
223 use Function::Parameters 'foo';
225 use Function::Parameters { 'foo' => 'function' };
232 use Function::Parameters 'foo', 'bar';
234 use Function::Parameters { 'foo' => 'function', 'bar' => 'method' };
236 That is, if you want to pass arguments to L<Function::Parameters>, use a
237 hashref, not a list of strings.
239 You can customize things even more by passing a hashref instead of C<function>
240 or C<method>. This hash can have the following keys:
246 Valid values: C<optional> (default), C<required> (all uses of this keyword must
247 specify a function name), and C<prohibited> (all uses of this keyword must not
248 specify a function name). This means a C<< name => 'prohibited' >> keyword can
249 only be used for defining anonymous functions.
253 Valid values: strings that look like a scalar variable. Any function created by
254 this keyword will automatically L<shift|perlfunc/shift> its first argument into
255 a local variable whose name is specified here.
259 Valid values: strings that are valid source code for attributes. Any value
260 specified here will be inserted as a subroutine attribute in the generated
263 use Function::Parameters { sub_l => { attrs => ':lvalue' } };
276 Plain C<'function'> is equivalent to C<< { name => 'optional' } >>, plain
277 C<'method'> is equivalent to
278 C<< { name => 'optional', shift => '$self', attrs => ':method' } >>, and plain
279 C<'classmethod'> is equivalent to
280 C<< { name => 'optional', shift => '$class', attrs => ':method' } >>.
282 =head2 Syntax and generated code
284 Normally, Perl subroutines are not in scope in their own body, meaning the
285 parser doesn't know the name C<foo> or its prototype while processing the body
286 of C<sub foo ($) { foo $bar[1], $bar[0]; }>, parsing it as
287 C<$bar-E<gt>foo([1], $bar[0])>. Yes. You can add parens to change the
288 interpretation of this code, but C<foo($bar[1], $bar[0])> will only trigger
289 a I<foo() called too early to check prototype> warning. This module attempts
290 to fix all of this by adding a subroutine declaration before the definition,
291 so the parser knows the name (and possibly prototype) while it processes the
292 body. Thus C<fun foo($x) :($) { $x }> really turns into
293 C<sub foo ($); sub foo ($) { my ($x) = @_; $x }>.
295 If you need L<subroutine attributes|perlsub/"Subroutine Attributes">, you can
296 put them after the parameter list with their usual syntax.
298 Syntactically, these new parameter lists live in the spot normally occupied
299 by L<prototypes|perlsub/"Prototypes">. However, you can include a prototype by
300 specifying it as the first attribute (this is syntactically unambiguous
301 because normal attributes have to start with a letter while a prototype starts
304 As an example, the following declaration uses every feature available
305 (subroutine name, parameter list, prototype, attributes, and implicit
308 method foo($x, $y, @z) :($;$@) :lvalue :Banana(2 + 2) {
312 And here's what it turns into:
314 sub foo ($;$@); sub foo ($;$@) :lvalue :Banana(2 + 2) { my $self = shift; my ($x, $y, @z) = @_;
320 my $coderef = fun ($p, $q) :(;$$)
326 And the generated code:
328 my $coderef = sub (;$$) :lvalue :Gazebo((>:O)) { my ($p, $q) = @_;
332 =head2 Wrapping Function::Parameters
334 If you want to wrap L<Function::Parameters>, you just have to call its
335 C<import> method. It always applies to the file that is currently being parsed
336 and its effects are lexical (i.e. it works like L<warnings> or L<strict>):
338 package Some::Wrapper;
339 use Function::Parameters ();
341 Function::Parameters->import;
342 # or Function::Parameters->import(@other_import_args);
347 Lukas Mai, C<< <l.mai at web.de> >>
349 =head1 COPYRIGHT & LICENSE
351 Copyright 2010, 2011, 2012 Lukas Mai.
353 This program is free software; you can redistribute it and/or modify it
354 under the terms of either: the GNU General Public License as published
355 by the Free Software Foundation; or the Artistic License.
357 See http://dev.perl.org/licenses/ for more information.