NAME

Filter::Include - Emulate the behaviour of the #include directive

SYNOPSIS

  use Filter::Include;

  include Foo::Bar;
  include "somefile.pl";

  ## or the C preprocessor directive style:

  #include Some::Class
  #include "little/library.pl"

DESCRIPTION

Take the #include preproccesor directive from C, stir in some perl semantics and we have this module. Only one keyword is used, include, which is really just a processor directive for the filter, which indicates the file to be included. The argument supplied to include will be handled like it would by require and use so @INC is searched accordingly and %INC is populated.

#include

For those who have not come across C's #include preprocessor directive this section shall explain briefly what it does.

When the C preprocessor sees the #include directive, it will include the given file straight into the source. The file is dumped directly to where #include previously stood, so becomes part of the source of the given file when it is compiled. This is used primarily for C's header files so function and data predeclarations can be nicely separated out.

So given a small script like this:

  ## conf.pl
  my $conf = { lots => 'of', configuration => 'info' };

We can pull this file directly in to the source of the following script using Filter::Include

  use Filter::Include;

  include 'conf.pl';
  print join(' ', map { $_, $conf->{$_} } reverse sort keys %$conf), "\n";

Once the filter is applied to the file above the source will look like this:

  ## conf.pl
  my $conf = { lots => 'of', configuration => 'info' };

  print join(' ', map { $_, $conf->{$_} } reverse sort keys %$conf), "\n";

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

Why not to use -P

To quote directly from perlrun:

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

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

HANDLERS

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 pre and after handlers (documented below).

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

pre/post

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

before/after

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

AUTHOR

Dan Brook <cpan@broquaint.com>

SEE ALSO

C, -P in perlrun, Filter::Simple, Filter::Macro