NAME

Sub::Import - safely import subroutines from any file

SYNOPSIS

use Sub::Import qw( file_with_subs.pl );

sub_from_file( @ARGV );

my $imp = Sub::Import->new( exclude => qr/^_/ );
my @public_subs = $imp->match_file( 'a_module.pm' );

DESCRIPTION

Ever wanted to require() a file just for it's subroutines but had to end up copying and pasting because the file executed code? If the answer to the previous question was /^yes!?/i then this is the module for you! It will cleanly extract subroutines from a given file and import them into the current package.

USAGE

You can extract subroutines from files in the following ways

use() a list

This will extract all the subroutines in the given files and import them into the current package.

use Sub::Import qw(list)

use() a hash ref

Provide a hash ref which has the key files pointing to an array of files. If there are any rules in the hash ref they will also be applied.

use Sub::Import { files => [], %rules }

OO interface

Use the OO interface provided. Although remember that importing like this won't be processed until runtime, unlike the use.

use Sub::Import;
my $imp = Sub::Import->new( { files => [], %rules } );
$imp->import();

# or

my $imp = Sub::Import->new();
$imp->import( @files );

METHODS

new($options)

The class constructor method. It takes one parameter which is a hash ref of options which can consist of the following

{
  files   => [],        # files to be processed
  # NOTE - these are mentioned above as rules
  include => 'pattern', # include subs whose names match 'pattern'
  exclude => 'pattern', # reverse of include
}

import([ $hashref | @files ])

Will import given subs with a touch of DWIM

use Sub::Import qw( files );    # process files
use Sub::Import { %options };   # process $options{files}

my $imp1 = Sub::Import->new($options);
$imp1->import();                # process $imp1->{files}
my $imp2 = Sub::Import->new();
$imp->import( @files );         # process @files

match_file($filename)

Returns a list of subroutines (as strings) extracted from $filename

match_string($string)

Same as match_file() but processes the given $string

EXAMPLE

Say you have some legacy code and would like to use but fear require()ing forsooth it breaketh your wonderful new program. If the subs aren't dependent on anything else in the code then you can safely bring them into your current program like so

{
  package Legacy;
  use Sub::Import qw ( /usr/local/lib/perl4/LegacyCode.ph );
}

my $handle = Legacy::get_database(@args);

Now you have your old code nicely encapsulated in it's own package, hurrah!

BUGS

If you have an unbalanced ending bracket in a HERE doc within a sub the extractor breaks and returns an incomplete subroutine e.g

sub buggy {
  print <<"    TXT";
  devil face is bad }:->
  TXT
}

The returned sub will end at the beginning of the emoticon.

TODO

x

Try to import variables that the imported subroutines rely upon, and maybe prove the Riemann Hypothesis while I'm at it.

x

Get _prepare_code() to deal with HERE docs.

THANKS

Thanks again to Damian Conway's marvellous Filter::Simple (used in _prepare_code() and _restore_code()

AUTHOR

Dan Brook <broquaint@hotmail.com>

COPYRIGHT

Copyright (c) 2002, Dan Brook. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.