Inline::Wrapper(3) User Contributed Perl Documentation Inline::Wrapper(3)NAMEInline::Wrapper - Convenient module wrapper/loader routines for
Inline.pm
SYNOPSIS
sample.pl:
use Inline::Wrapper;
my $inline = Inline::Wrapper->new(
language => 'C',
base_dir => '.',
);
my @symbols = $inline->load( 'answer' );
my @retvals = $inline->run( 'answer', 'the_answer', 3, 56 );
print "The answer is: ", $retvals[0], "\n";
exit(0);
answer.c:
int the_answer( int arg1, int arg2 ) {
return ( arg1 * arg2 ) >> 2;
}
DESCRIPTIONInline::Wrapper provides wrapper routines around Inline to make
embedding functions from another language into a Perl application much
more convenient.
Instead of having to include the external code in a Perl source file
after the __END__ directive, Inline::Wrapper allows you to have
separate, individually-configurable module repositories to more easily
manage all of your external application code.
FEATURESInline::Wrapper provides the following features:
· Support for all languages supported by Inline.
· A single, unified interface for loading and running module
functions.
· Loading of files containing pure source code, only in their
respective languages, so you can isolate maintenance and management
of these modules.
· Individually-configurable module directories.
· Automatic, run-time module reloading upon file modification time
detection.
· No more namespace pollution. All module symbols are loaded into
their own individual, private namespaces, so they won't collide
with your code or each other.
CONSTRUCTORnew()
my $wrapper = Inline::Wrapper->new(
language => 'C',
base_dir => 'src/code/C',
auto_reload => 1,
);
Create a new Inline::Wrapper object, with the appropriate attributes
(if specified).
ARGUMENTS:
All arguments are of the hash form Var => Value. "new()" will
complain and croak if they do not follow this form.
The arguments to "new()" become the defaults used by "load()". You can
individually configure loaded modules using "load()", as well.
language [ default: 'Lua' ]
Optional. Set to the default language for which you wish to load
modules, if not explicitly specified via "load()".
NOTE: It defaults to Lua because that is what I wrote this module
for. Just pass in the argument if you don't like that.
ALSO NOTE: Currently only a couple of "known" languages are hard-
coded into this module. If you wish to use others, don't pass this
argument, and use the "add_language()" method after the object has
been instantiated.
auto_reload [ default: FALSE ]
Optional. Set to a TRUE value to default to automatically checking
if modules have been changed since the last "load()", and reload
them if necessary.
base_dir [ default: '.' ]
Optional. Set to the default base directory from which you wish to
load all modules.
RETURNS: blessed $object, or undef on failure.
METHODSinitialize()
$obj->initialize();
Initialize arguments. If you are subclassing, overload this, not
"new()".
Generally only called from within "new()".
load()
my @functions = $obj->load( $modname, %arguments );
The workhorse. Loads the actual module referred to by $modname,
imports its symbols into a private namespace, and makes them available
to call via "run()".
ARGUMENTS:
$modname is REQUIRED. It corresponds to the base filename, without
extension, loaded from the base_dir. See the "Details of steps taken
by load()" section, Step 3, for clarification of how pathname
resolution is done. $modname is also how you will refer to this
particular module from your program, so keep track of it.
This method accepts all of the same arguments as "new()". Thus, you
can set the defaults via "new()", yet still individually configure
module components differently from the defaults, if desired.
Returns a list of @functions made available by loading $modname, or
warns and returns an empty list if unsuccessful.
Details of steps taken by load()
Since this is the real guts of this module, here are the exact steps
taken when loading the module, doing pathname resolution, etc.
1. Checks to see if the specified module has already been loaded, and
if so, returns the list of functions loaded and available in that
module immediately.
2. Creates a new Inline::Wrapper::Module container object with any
supplied %arguments, or the defaults you specified with "new()".
3. Constructs a path to the specified $modname, roughly as follows:
join( $PATH_SEP, $base_dir , $modname . $lang_ext );
$base_dir is taken either from the default created with "new()", or
the explicitly supplied base_dir argument to "load()".
$path_separator is just the appropriate path separator for your OS.
$modname is your supplied module name. Note that this means that
you can supply your own subdirectories, as well; i.e. 'foo' is just
as valid as 'foo/bar/baz'.
$lang_ext is taken from a data structure that defaults to common
filename extensions on a per-language basis. Any of these can be
overridden via the "add_language()" method.
4. Attempts to open the file at the path constructed above, and if
successful, slurps in the entire source file.
5. Attempts to bind() (compile and set symbols) it with the
Inline->bind() method into a private namespace.
6. If step 5 was successful, set the load time, and return the list of
loaded, available functions provided by the module.
7. If step 5 failed, warn and return an empty list.
unload()
$obj->unload( $modname );
Completely unload the module identified by $modname, and render its
functions uncallable.
This will actually go destroy the Inline::Wrapper::Module object, as
well as the code module's corresponding private namespace.
Returns $modname (TRUE) upon success, carps and returns undef on
failure.
run()
my @retvals = $obj->run( $modname, $function, @arguments );
Run the named $function that you loaded from $modname, with the
specified @arguments (if any).
NOTE: If the auto_reload option is TRUE, run() will also attempt to
reload the source script from disk before running the function, if the
ctime of the file has changed since the last run.
Assuming a successful compilation (you are checking for errors,
right?), this will execute the function provided by the loaded module.
Call syntax and everything is up to the function provided. This simply
executes the sub that Inline loaded as-is, but in its own private
namespace to keep your app clean.
Returns @retvals, consisting of the actual return values provided by
the module function itself. Whatever the function returns, that's what
you get.
modules()
my @modules = $obj->modules();
Returns a list of loaded module names, or the empty list if no modules
have been (successfully) loaded.
functions()
my @functions = $obj->functions( $modname );
Returns a list of loaded @functions, which were made available by
loading $modname.
ACCESSORS
Various accessors that allow you to inspect or change the default
settings after creating the object.
base_dir()
my $base_dir = $obj->base_dir();
Returns the default base_dir attribute from the object.
set_base_dir()
$obj->set_base_dir( '/some/path' );
Sets the default base_dir attribute of the object, and returns whatever
it ended up being set to.
NOTE: Only affects modules loaded after this setting was made.
auto_reload()
my $bool = $obj->auto_reload();
Returns a $boolean as to whether or not the default auto_reload setting
is enabled for new modules.
set_auto_reload()
$obj->set_auto_reload( 1 );
Sets the default auto_reload attribute of the object, and returns
whatever it ended up being set to.
NOTE: Only affects modules loaded after this setting was made.
language()
my $lang = $obj->language();
Returns the default language attribute of the object.
set_language()
$obj->set_language( 'C' );
Sets the default language attribute of the object, and returns whatever
it ended up being set to.
NOTE: Only affects modules loaded after this setting was made.
ALSO NOTE: This checks for "valid" languages via a pretty naive method.
Currently only a couple are hard-coded. However, you can add your own
languages via the "add_language()" method.
add_language()
$obj->add_language( 'Lojban' => '.xkcd' );
Adds a language to the "known languages" table, allowing you to later
use "set_language()".
This can also be used to set a new file extension for an existing
language.
REQUIRES a $language name (e.g. 'Python') and a filename $extension
(e.g. '.py'), which will be used in pathname resolution, as described
under "load()".
Returns TRUE if successful, carps and returns FALSE otherwise.
SEE ALSO
Inline::Wrapper::Module
The Inline documentation.
The Inline-FAQ list.
The examples/ directory of this module's distribution.
ACKNOWLEDGEMENTS
Thank you, kennethk and ikegami for your assistance on perlmonks.
<http://perlmonks.org/index.pl?node_id=732598>
AUTHOR
Please kindly read through this documentation and the examples/
thoroughly, before emailing me with questions. Your answer is likely
in here.
Also, please make sure that your issue is actually with Inline::Wrapper
and not with Inline itself.
Jason McManus (INFIDEL) -- "infidel AT cpan.org"
LICENSE
Copyright (c) Jason McManus
This module may be used, modified, and distributed under the same terms
as Perl itself. Please see the license that came with your Perl
distribution for details.
perl v5.16.2 2010-03-10 Inline::Wrapper(3)
