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, and why it's being emulated here.

What

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.

Why

The why of this module is that I'd seen several requests on Perl Monks, but the one inparticular that inspired was this:

http://www.perlmonks.org/index.pl?node_id=254283

HANDLERS

If Filter::Include is called with the pre and/or post arguments their associated values can be installed as handlers e.g

use Filter::Include pre => sub {
                      my $include = shift;
                      print "Including $inc\n";
                    };

This will install the pre handler which is called before the include is parsed for further includes. If a post handler is passed in then it will be called after the include has been parsed and updated.

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.

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

AUTHOR

Dan Brook <cpan@broquaint.com>

SEE ALSO

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