NAME
Filter::signatures - very simplistic signatures for Perl < 5.20
SYNOPSIS
use Filter::signatures;
no warnings 'experimental::signatures'; # does not raise an error
use feature 'signatures'; # this now works on <5.20 as well
sub hello( $name ) {
print "Hello $name\n";
}
hello("World");
sub hello2( $name="world" ) {
print "Hello $name\n";
}
hello2(); # Hello world
DESCRIPTION
This module implements a backwards compatibility shim for formal Perl subroutine signatures that were introduced to the Perl core with Perl 5.20.
CAVEATS
The technique used is a very simplistic transform to allow for using very simplistic named formal arguments in subroutine declarations. This module does not implement warning if more or fewer parameters than expected are passed in.
The module also implements default values for unnamed parameters by
splitting the formal parameters on /,/
and assigning the values
if @_
contains fewer elements than expected. Function calls
as default values may work by accident. Commas within default values happen
to work due to the design of Filter::Simple, which removes them for
the application of this filter.
Note that this module inherits all the bugs of Filter::Simple and potentially
adds some of its own. Most notable is that Filter::Simple sometimes will
misinterpret the division operator /
as a leading character to starting
a regex match:
my $wait_time = $needed / $supply;
This will manifest itself through syntax errors appearing where everything seems in order. The hotfix is to add a comment to the code that "closes" the misinterpreted regular expression:
my $wait_time = $needed / $supply; # / for Filter::Simple
A better hotfix is to upgrade to Perl 5.20 or higher and use the native signatures support there. No other code change is needed, as this module will disable its functionality when it is run on a Perl supporting signatures.
Parentheses in default assignments
Ancient versions of Perl before version 5.10 do not have recursive regular expressions. These will not be able to properly handle statements such as
sub foo ($timestamp = time()) {
}
The hotfix is to rewrite these function signatures to not use parentheses. The better approach is to upgrade to Perl 5.20 or higher.
Line Numbers
Due to a peculiarity of how Filter::Simple treats here documents in some versions, line numbers may get out of sync if you use here documents.
If you spread your formal signatures across multiple lines, the line numbers may also go out of sync with the original document.
eval
Filter::Simple does not trigger when using code such as
eval <<'PERL';
use Filter::signatures;
use feature 'signatures';
sub foo (...) {
}
PERL
So, creating subroutines with signatures from strings won't work with this module. The workaround is to upgrade to Perl 5.20 or higher.
Deparsing
The generated code does not deparse identically to the code generated on a Perl with native support for signatures.
ENVIRONMENT
If you want to force the use of this module even under versions of
Perl that have native support for signatures, set
$ENV{FORCE_FILTER_SIGNATURES}
to a true value before the module is
imported.
SEE ALSO
signatures - a module that doesn't use a source filter but optree modification instead
Sub::Signatures - uses signatures to dispatch to different subroutines based on which subroutine matches the signature
Method::Signatures - this module implements subroutine signatures closer to Perl 6, but requires PPI and Devel::Declare
Function::Parameters - adds two new keywords for declaring subroutines and parses their signatures. It supports more features than core Perl, closer to Perl 6, but requires a C compiler and Pelr 5.14+.
REPOSITORY
The public repository of this module is http://github.com/Corion/filter-signatures.
SUPPORT
The public support forum of this module is https://perlmonks.org/.
BUG TRACKER
Please report bugs in this module via the RT CPAN bug queue at https://rt.cpan.org/Public/Dist/Display.html?Name=Filter-signatures or via mail to filter-signatures-Bugs@rt.cpan.org.
AUTHOR
Max Maischein corion@cpan.org
COPYRIGHT (c)
Copyright 2015-2018 by Max Maischein corion@cpan.org
.
LICENSE
This module is released under the same terms as Perl itself.