.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Filter::signatures 3pm" .TH Filter::signatures 3pm "2020-10-23" "perl v5.30.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Filter::signatures \- very simplistic signatures for Perl < 5.20 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& use Filter::signatures; \& no warnings \*(Aqexperimental::signatures\*(Aq; # does not raise an error \& use feature \*(Aqsignatures\*(Aq; # this now works on <5.20 as well \& \& sub hello( $name ) { \& print "Hello $name\en"; \& } \& \& hello("World"); \& \& sub hello2( $name="world" ) { \& print "Hello $name\en"; \& } \& hello2(); # Hello world .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module implements a backwards compatibility shim for formal Perl subroutine signatures that were introduced to the Perl core with Perl 5.20. .SH "CAVEATS" .IX Header "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. .PP The module also implements default values for unnamed parameters by splitting the formal parameters on \f(CW\*(C`/,/\*(C'\fR and assigning the values if \f(CW@_\fR 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. .SS "Syntax peculiarities" .IX Subsection "Syntax peculiarities" Note that this module inherits all the bugs of Filter::Simple and potentially adds some of its own. .PP \fISlashes\fR .IX Subsection "Slashes" .PP Most notable is that Filter::Simple sometimes will misinterpret the division operator \f(CW\*(C`/\*(C'\fR as a leading character to starting a regex match: .PP .Vb 1 \& my $wait_time = $needed / $supply; .Ve .PP This will manifest itself through syntax errors appearing where everything seems in order. The hotfix is to add a comment to the code that \*(L"closes\*(R" the misinterpreted regular expression: .PP .Vb 1 \& my $wait_time = $needed / $supply; # / for Filter::Simple .Ve .PP 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. .PP \fISize operator interpreted as replacement\fR .IX Subsection "Size operator interpreted as replacement" .PP Filter::Simple sometimes will misinterpret the file size operator on the default filehandle \f(CW\*(C`\-s _\*(C'\fR as the start of a replacement .PP .Vb 1 \& my $filesize = \-s _; .Ve .PP # Misinterpreted as .PP .Vb 1 \& my $filesize = \-(s _;..._g); .Ve .PP This will manifest itself through syntax errors appearing where everything seems in order. The hotfix is to indicate that \f(CW\*(C`<_\*(C'\fR> is a filehandle by prefixing it with \f(CW\*(C`<*\*(C'\fR>: .PP .Vb 1 \& my $filesize = \-s *_; .Ve .PP 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. .SS "Parentheses in default expressisons" .IX Subsection "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 .PP .Vb 2 \& sub foo ($timestamp = time()) { \& } .Ve .PP The hotfix is to rewrite these function signatures to not use parentheses. The better approach is to upgrade to Perl 5.20 or higher. .SS "Regular expression matches in default expressions" .IX Subsection "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: .PP .Vb 2 \& sub foo( $x = /,/ ) { # WRONG! \& sub foo( $x = /\e,/ ) { # GOOD! \& \& sub foo( $x = /[(]/ ) { # WRONG! \& sub foo( $x = /[\e(]/ ) { # GOOD! .Ve .PP 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. .SS "Subroutine attributes" .IX Subsection "Subroutine attributes" Subroutine attributes are currently not supported at all. .SS "Line Numbers" .IX Subsection "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. .PP If you spread your formal signatures across multiple lines, the line numbers may also go out of sync with the original document. .ie n .SS """eval""" .el .SS "\f(CWeval\fP" .IX Subsection "eval" Filter::Simple does not trigger when using code such as .PP .Vb 3 \& eval <<\*(AqPERL\*(Aq; \& use Filter::signatures; \& use feature \*(Aqsignatures\*(Aq; \& \& sub foo (...) { \& } \& PERL .Ve .PP So, creating subroutines with signatures from strings won't work with this module. The workaround is to upgrade to Perl 5.20 or higher. .SS "Deparsing" .IX Subsection "Deparsing" The generated code does not deparse identically to the code generated on a Perl with native support for signatures. .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" If you want to force the use of this module even under versions of Perl that have native support for signatures, set \&\f(CW$ENV{FORCE_FILTER_SIGNATURES}\fR to a true value before the module is imported. .SH "USAGE WITHOUT SOURCE CODE MODIFICATION" .IX Header "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: .PP .Vb 1 \& perl \-Mlib=some/directory \-MFilter::signatures=global myscript.pl .Ve .PP This is intended as a quick-fix solution and is not very robust. If your script modifies \f(CW@INC\fR, the filtering may not get a chance to modify the source code of the loaded module. .PP This currently does not play well with (other) hooks in \f(CW@INC\fR as it only handles hooks that return a filehandle. Implementations for the rest are welcome. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\*(L"Signatures\*(R" in perlsub .PP App::sigfix, which transforms your source code directly between the different notations without employing a source filter .PP signatures \- a module that doesn't use a source filter but optree modification instead .PP Sub::Signatures \- uses signatures to dispatch to different subroutines based on which subroutine matches the signature .PP Method::Signatures \- this module implements subroutine signatures closer to Perl 6, but requires \s-1PPI\s0 and Devel::Declare .PP 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+. .SH "REPOSITORY" .IX Header "REPOSITORY" The public repository of this module is . .SH "SUPPORT" .IX Header "SUPPORT" The public support forum of this module is . .SH "BUG TRACKER" .IX Header "BUG TRACKER" Please report bugs in this module via the \s-1RT CPAN\s0 bug queue at or via mail to filter\-signatures\-Bugs@rt.cpan.org. .SH "AUTHOR" .IX Header "AUTHOR" Max Maischein \f(CW\*(C`corion@cpan.org\*(C'\fR .SH "COPYRIGHT (c)" .IX Header "COPYRIGHT (c)" Copyright 2015\-2020 by Max Maischein \f(CW\*(C`corion@cpan.org\*(C'\fR. .SH "LICENSE" .IX Header "LICENSE" This module is released under the same terms as Perl itself.