view release on metacpan or  search on metacpan

lib/Filter/Include.pm  view on Meta::CPAN

So unlike C<perl>'s native file include functions C<Filter::Include> pulls the
source of the file to be included I<directly> into the caller's source without
any code evaluation.

=head2 Why not to use C<-P>

To quote directly from L<perlrun>:

  NOTE: Use of -P is strongly discouraged because of its inherent problems,
  including poor portability.

So while you can use the C<#include> natively in C<perl> it comes with the
baggage of the C<C> preprocessor.

=head1 HANDLERS

C<Filter::Include> has a facility to install handlers at various points of the
filtering process. These handlers can be installed by passing in the name of the
handler and an associated subroutine e.g

  use Filter::Include pre => sub {
                        my $include = shift;
                        print "Including $inc\n";
                      },
                      after => sub {
                        my $code = shift;
                        print "The resulting source looks like:\n$code\n";
                      };

This will install the C<pre> and C<after> handlers (documented below).

These handlers are going to be most suited for debugging purposes but could also
be useful for tracking module usage.

=over 4

=item pre/post

Both handlers take two positional arguments - the current include e.g
C<library.pl> or C<Legacy::Code>, and the source of the include which in the
case of the C<pre> handler is the source before it is parsed and in the case of
the C<post> handler it is the source after it has been parsed and updated as
appropriate.

=item before/after

Both handlers take a single argument - a string representing the relevant
source code. The C<before> handler is called I<before> any filtering is
performed so it will get the pre-filtered source as its first argument. The
C<after> handler is called I<after> the filtering has been performed so will
get the source post-filtered as its first argument.

=back

=head1 AUTHOR

Dan Brook C<< <cpan@broquaint.com> >>

=head1 SEE ALSO

C<C>, -P in L<perlrun>, L<Filter::Simple>, L<Filter::Macro>

=cut