1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
[](https://travis-ci.org/Corion/Filter-signatures)
[](https://ci.appveyor.com/project/Corion/Filter-signatures)
# 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](https://metacpan.org/pod/Filter%3A%3ASimple), which removes them for
the application of this filter.
## Syntax peculiarities
Note that this module inherits all the bugs of [Filter::Simple](https://metacpan.org/pod/Filter%3A%3ASimple) 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](https://metacpan.org/pod/Filter%3A%3ASimple) 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](https://metacpan.org/pod/perlsub#Signatures)
[App::sigfix](https://metacpan.org/pod/App%3A%3Asigfix), which transforms your source code directly between
the different notations without employing a source filter
[signatures](https://metacpan.org/pod/signatures) - a module that doesn't use a source filter but optree
modification instead
[Sub::Signatures](https://metacpan.org/pod/Sub%3A%3ASignatures) - uses signatures to dispatch to different subroutines
based on which subroutine matches the signature
[Method::Signatures](https://metacpan.org/pod/Method%3A%3ASignatures) - this module implements subroutine signatures
closer to Perl 6, but requires [PPI](https://metacpan.org/pod/PPI) and [Devel::Declare](https://metacpan.org/pod/Devel%3A%3ADeclare)
[Function::Parameters](https://metacpan.org/pod/Function%3A%3AParameters) - 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](http://github.com/Corion/filter-signatures).
# SUPPORT
The public support forum of this module is
[https://perlmonks.org/](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](https://rt.cpan.org/Public/Dist/Display.html?Name=Filter-signatures)
or via mail to [filter-signatures-Bugs@rt.cpan.org](https://metacpan.org/pod/filter-signatures-Bugs%40rt.cpan.org).
# AUTHOR
Max Maischein `corion@cpan.org`
# COPYRIGHT (c)
Copyright 2015-2023 by Max Maischein `corion@cpan.org`.
# LICENSE
This module is released under the same terms as Perl itself.
|
