All decryption filters work on the principle of "security through
obscurity." Regardless of how well you write a decryption filter and
-how strong your encryption algorithm, anyone determined enough can
+how strong your encryption algorithm is, anyone determined enough can
retrieve the original source code. The reason is quite simple - once
the decryption filter has decrypted the source back to its original
form, fragments of it will be stored in the computer's memory as Perl
decryption filter in C and statically link the decryption module into
the Perl binary. For further tips to make life difficult for the
potential cracker, see the file I<decrypt.pm> in the source filters
-module.
+distribution.
=back
An alternative to writing the filter in C is to create a separate
executable in the language of your choice. The separate executable
reads from standard input, does whatever processing is necessary, and
-writes the filtered data to standard output. C<Filter:cpp> is an
+writes the filtered data to standard output. C<Filter::cpp> is an
example of a source filter implemented as a separate executable - the
executable is the C preprocessor bundled with your C compiler.
task: C<Filter::exec> and C<Filter::sh>. Both allow you to run any
external executable. Both use a coprocess to control the flow of data
into and out of the external executable. (For details on coprocesses,
-see Stephens, W.R. "Advanced Programming in the UNIX Environment."
+see Stephens, W.R., "Advanced Programming in the UNIX Environment."
Addison-Wesley, ISBN 0-210-56317-7, pages 441-445.) The difference
between them is that C<Filter::exec> spawns the external command
directly, while C<Filter::sh> spawns a shell to execute the external
1;
+=for apidoc filter_add
+=for apidoc filter_read
+
All Perl source filters are implemented as Perl classes and have the
same basic structure as the example above.
}
## DEBUG_END
-When the C<DEBUG> environment variable exists, the filter ensures that
-Perl parses only the code between the C<DEBUG_BEGIN> and C<DEBUG_END>
-markers. That means that when C<DEBUG> does exist, the code above
+The filter ensures that Perl parses the code between the <DEBUG_BEGIN>
+and C<DEBUG_END> markers only when the C<DEBUG> environment variable
+exists. That means that when C<DEBUG> does exist, the code above
should be passed through the filter unchanged. The marker lines can
also be passed through as-is, because the Perl parser will see them as
comment lines. When C<DEBUG> isn't set, we need a way to disable the
you know. The tricky bit will be choosing how much knowledge of Perl's
syntax you want your filter to have.
+=head1 LIMITATIONS
+
+Source filters only work on the string level, thus are highly limited
+in its ability to change source code on the fly. It cannot detect
+comments, quoted strings, heredocs, it is no replacement for a real
+parser.
+The only stable usage for source filters are encryption, compression,
+or the byteloader, to translate binary code back to source code.
+
+See for example the limitations in L<Switch>, which uses source filters,
+and thus is does not work inside a string eval, the presence of
+regexes with embedded newlines that are specified with raw C</.../>
+delimiters and don't have a modifier C<//x> are indistinguishable from
+code chunks beginning with the division operator C</>. As a workaround
+you must use C<m/.../> or C<m?...?> for such patterns. Also, the presence of
+regexes specified with raw C<?...?> delimiters may cause mysterious
+errors. The workaround is to use C<m?...?> instead. See
+L<https://search.cpan.org/perldoc?Switch#LIMITATIONS>
+
+Currently the content of the C<__DATA__> block is not filtered.
+
+Currently internal buffer lengths are limited to 32-bit only.
+
+
=head1 THINGS TO LOOK OUT FOR
=over 5
When using these source filters you cannot rely on this handle, nor expect
any particular kind of behavior when operating on it. Filters based on
Filter::Util::Call (and therefore Filter::Simple) do not alter the C<DATA>
-filehandle.
+filehandle, but on the other hand totally ignore the text after C<__DATA__>.
=back
Paul Marquess E<lt>Paul.Marquess@btinternet.comE<gt>
+Reini Urban E<lt>rurban@cpan.orgE<gt>
+
=head1 Copyrights
-This article originally appeared in The Perl Journal #11, and is
-copyright 1998 The Perl Journal. It appears courtesy of Jon Orwant and
-The Perl Journal. This document may be distributed under the same terms
-as Perl itself.
+The first version of this article originally appeared in The Perl
+Journal #11, and is copyright 1998 The Perl Journal. It appears
+courtesy of Jon Orwant and The Perl Journal. This document may be
+distributed under the same terms as Perl itself.