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.

   Syntax peculiarities
       Note that this module inherits all the bugs of Filter::Simple and potentially adds some of
       its own.

       Slashes

       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.

       Size operator interpreted as replacement

       Filter::Simple sometimes will misinterpret the file size operator on the default
       filehandle "-s _" as the start of a replacement

           my $filesize = -s _;

       # Misinterpreted as

           my $filesize = -(s _;..._g);

       This will manifest itself through syntax errors appearing where everything seems in order.
       The hotfix is to indicate that "<_"> is a filehandle by prefixing it with "<*">:

           my $filesize = -s *_;

       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 expressisons
       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.

   Regular expression matches in default expressions
       To keep the argument parser simple, the parsing of regular expressions has been omitted.
       For Perl below 5.10, you cannot use regular expressions as default expressions. For higher
       Perl versions, this means that parentheses, curly braces and commas need to be explicitly
       escaped with a backslash when used as default expressions:

           sub foo( $x = /,/ ) { # WRONG!
           sub foo( $x = /\,/ ) { # GOOD!

           sub foo( $x = /[(]/ ) { # WRONG!
           sub foo( $x = /[\(]/ ) { # GOOD!

       The hotfix is to rewrite these default expressions with explicitly quoted commas,
       parentheses and curly braces. The better approach is to upgrade to Perl 5.20 or higher.

   Subroutine attributes
       Subroutine attributes are currently not supported at all.

   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.

USAGE WITHOUT SOURCE CODE MODIFICATION

       If you have a source file that was written for use with signatures and you cannot modify
       that source file, you can run it as follows:

         perl -Mlib=some/directory -MFilter::signatures=global myscript.pl

       This is intended as a quick-fix solution and is not very robust. If your script modifies
       @INC,  the filtering may not get a chance to modify the source code of the loaded module.

       This currently does not play well with (other) hooks in @INC as it only handles hooks that
       return a filehandle. Implementations for the rest are welcome.

SEE ALSO

       "Signatures" in perlsub

       App::sigfix, which transforms your source code directly between the different notations
       without employing a source filter

       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 Perl 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-2020 by Max Maischein "corion@cpan.org".

LICENSE

       This module is released under the same terms as Perl itself.