X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FFunction%2FParameters.pm;h=5a4234489a6a61bc4d9b6019e6b7798020bafd65;hb=59016bfbf00d500121a167cd7fdac1d15aae541d;hp=50fb348beefabfbf722e1f7283aa5d2aadce6043;hpb=db81d362a1901dbeccf6063a39e86b35b2838875;p=p5sagit%2FFunction-Parameters.git diff --git a/lib/Function/Parameters.pm b/lib/Function/Parameters.pm index 50fb348..5a42344 100644 --- a/lib/Function/Parameters.pm +++ b/lib/Function/Parameters.pm @@ -1,17 +1,17 @@ package Function::Parameters; +use v5.14.0; + use strict; use warnings; use XSLoader; BEGIN { - our $VERSION = '0.05_01'; + our $VERSION = '0.06'; XSLoader::load; } -use B::Hooks::EndOfScope qw(on_scope_end); use Carp qw(confess); -use bytes (); sub _assert_valid_identifier { my ($name, $with_dollar) = @_; @@ -20,16 +20,34 @@ sub _assert_valid_identifier { or confess qq{"$name" doesn't look like a valid identifier}; } +sub _assert_valid_attributes { + my ($attrs) = @_; + $attrs =~ /^\s*:\s*[^\W\d]\w*\s*(?:(?:\s|:\s*)[^\W\d]\w*\s*)*(?:\(|\z)/ + or confess qq{"$attrs" doesn't look like valid attributes}; +} + my @bare_arms = qw(function method); my %type_map = ( function => { name => 'optional' }, - method => { name => 'optional', shift => '$self' }, + method => { + name => 'optional', + shift => '$self', + attrs => ':method', + }, + classmethod => { + name => 'optional', + shift => '$class', + attrs => ':method', + }, ); sub import { my $class = shift; - @_ or @_ = ('fun', 'method'); + @_ or @_ = { + fun => 'function', + method => 'method', + }; if (@_ == 1 && ref($_[0]) eq 'HASH') { @_ = map [$_, $_[0]{$_}], keys %{$_[0]} or return; @@ -43,30 +61,38 @@ sub import { ? $proto : [$proto, $bare_arms[$bare++] || confess(qq{Don't know what to do with "$proto"})] ; - my ($name, $type) = @$item; + my ($name, $proto_type) = @$item; _assert_valid_identifier $name; - unless (ref $type) { - # use '||' instead of 'or' to preserve $type in the error message - $type = $type_map{$type} - || confess qq["$type" doesn't look like a valid type (one of ${\join ', ', sort keys %type_map})]; - } - $type->{name} ||= 'optional'; - $type->{name} =~ /^(?:optional|required|prohibited)\z/ - or confess qq["$type->{name}" doesn't look like a valid name attribute (one of optional, required, prohibited)]; - if ($type->{shift}) { - _assert_valid_identifier $type->{shift}, 1; - bytes::length($type->{shift}) < SHIFT_NAME_LIMIT - or confess qq["$type->{shift}" is longer than I can handle]; + unless (ref $proto_type) { + # use '||' instead of 'or' to preserve $proto_type in the error message + $proto_type = $type_map{$proto_type} + || confess qq["$proto_type" doesn't look like a valid type (one of ${\join ', ', sort keys %type_map})]; } + + my %type = %$proto_type; + my %clean; + + $clean{name} = delete $type{name} || 'optional'; + $clean{name} =~ /^(?:optional|required|prohibited)\z/ + or confess qq["$clean{name}" doesn't look like a valid name attribute (one of optional, required, prohibited)]; + + $clean{shift} = delete $type{shift} || ''; + _assert_valid_identifier $clean{shift}, 1 if $clean{shift}; + + $clean{attrs} = delete $type{attrs} || ''; + _assert_valid_attributes $clean{attrs} if $clean{attrs}; - $spec{$name} = $type; + %type and confess "Invalid keyword property: @{[keys %type]}"; + + $spec{$name} = \%clean; } for my $kw (keys %spec) { my $type = $spec{$kw}; - $^H{HINTK_SHIFT_ . $kw} = $type->{shift} || ''; + $^H{HINTK_SHIFT_ . $kw} = $type->{shift}; + $^H{HINTK_ATTRS_ . $kw} = $type->{attrs}; $^H{HINTK_NAME_ . $kw} = $type->{name} eq 'prohibited' ? FLAG_NAME_PROHIBITED : $type->{name} eq 'required' ? FLAG_NAME_REQUIRED : @@ -89,17 +115,13 @@ sub unimport { } } -sub _fini { - on_scope_end { - xs_fini; - }; -} - 'ok' __END__ +=encoding UTF-8 + =head1 NAME Function::Parameters - subroutine definitions with parameter lists @@ -130,7 +152,10 @@ Function::Parameters - subroutine definitions with parameter lists =pod - use Function::Parameters 'proc', 'meth'; + use Function::Parameters { + proc => 'function', + meth => 'method', + }; my $f = proc ($x) { $x * 2 }; meth get_age() { @@ -140,7 +165,7 @@ Function::Parameters - subroutine definitions with parameter lists =head1 DESCRIPTION This module lets you use parameter lists in your subroutines. Thanks to -L it works without source filters. +L it works without source filters. WARNING: This is my first attempt at writing L and I have almost no experience with perl's internals. So while this module might @@ -166,19 +191,20 @@ C. =head2 Customizing the generated keywords -You can customize the names of the keywords injected in your package. To do that -you pass a hash reference in the import list: +You can customize the names of the keywords injected into your scope. To do +that you pass a hash reference in the import list: use Function::Parameters { proc => 'function', meth => 'method' }; # -or- use Function::Parameters { proc => 'function' }; # -or- - use Function::Parameters { meth => 'method' }; + use Function::Parameters { meth => 'method' }; # etc. The first line creates two keywords, C and C (for defining functions and methods, respectively). The last two lines only create one keyword. Generally the hash keys can be any identifiers you want while the -values have to be either C, C, or a hash reference (see -below). The difference between C and C is that Cs -automatically L their first argument into C<$self>. +values have to be either C, C, C or a hash +reference (see below). The difference between C and C is that +Cs automatically L their first argument into +C<$self> (Cs are similar but shift into C<$class>). The following shortcuts are available: @@ -190,6 +216,10 @@ The following shortcuts are available: =pod +The following shortcuts are deprecated and may be removed from a future version +of the module: + + # DEPRECATED use Function::Parameters 'foo'; # is equivalent to # use Function::Parameters { 'foo' => 'function' }; @@ -198,10 +228,14 @@ The following shortcuts are available: =pod + # DEPRECATED use Function::Parameters 'foo', 'bar'; # is equivalent to # use Function::Parameters { 'foo' => 'function', 'bar' => 'method' }; +That is, if you want to pass arguments to L, use a +hashref, not a list of strings. + You can customize things even more by passing a hashref instead of C or C. This hash can have the following keys: @@ -218,18 +252,38 @@ only be used for defining anonymous functions. Valid values: strings that look like a scalar variable. Any function created by this keyword will automatically L its first argument into -a local variable with the name specified here. +a local variable whose name is specified here. + +=item C + +Valid values: strings that are valid source code for attributes. Any value +specified here will be inserted as a subroutine attribute in the generated +code. Thus: + + use Function::Parameters { sub_l => { attrs => ':lvalue' } }; + sub_l foo() { + ... + } + +turns into + + sub foo :lvalue { + ... + } =back -Plain C is equivalent to C<< { name => 'optional' } >>, and plain -C is equivalent to C<< { name => 'optional', shift => '$self'} >>. +Plain C<'function'> is equivalent to C<< { name => 'optional' } >>, plain +C<'method'> is equivalent to +C<< { name => 'optional', shift => '$self', attrs => ':method' } >>, and plain +C<'classmethod'> is equivalent to +C<< { name => 'optional', shift => '$class', attrs => ':method' } >>. -=head2 Other advanced stuff +=head2 Syntax and generated code Normally, Perl subroutines are not in scope in their own body, meaning the -parser doesn't know the name C or its prototype while processing -C, parsing it as +parser doesn't know the name C or its prototype while processing the body +of C, parsing it as C<$bar-Efoo([1], $bar[0])>. Yes. You can add parens to change the interpretation of this code, but C will only trigger a I warning. This module attempts @@ -244,18 +298,49 @@ put them after the parameter list with their usual syntax. Syntactically, these new parameter lists live in the spot normally occupied by L. However, you can include a prototype by specifying it as the first attribute (this is syntactically unambiguous -because normal attributes have to start with a letter). +because normal attributes have to start with a letter while a prototype starts +with C<(>). + +As an example, the following declaration uses every feature available +(subroutine name, parameter list, prototype, attributes, and implicit +C<$self>): + + method foo($x, $y, @z) :($;$@) :lvalue :Banana(2 + 2) { + ... + } + +And here's what it turns into: + + sub foo ($;$@); sub foo ($;$@) :lvalue :Banana(2 + 2) { my $self = shift; my ($x, $y, @z) = @_; + ... + } + +Another example: + + my $coderef = fun ($p, $q) :(;$$) + :lvalue + :Gazebo((>:O)) { + ... + }; + +And the generated code: + + my $coderef = sub (;$$) :lvalue :Gazebo((>:O)) { my ($p, $q) = @_; + ... + }; + +=head2 Wrapping Function::Parameters If you want to wrap L, you just have to call its C method. It always applies to the file that is currently being parsed -and its effects are lexical (i.e. it works like L or L); - - package Some::Wrapper; - use Function::Parameters (); - sub import { - Function::Parameters->import; - # or Function::Parameters->import(@other_import_args); - } +and its effects are lexical (i.e. it works like L or L): + + package Some::Wrapper; + use Function::Parameters (); + sub import { + Function::Parameters->import; + # or Function::Parameters->import(@other_import_args); + } =head1 AUTHOR