/ 
Inline-Wrapper-0.02
River stage zero No dependents
/ Inline::Wrapper

NAME

Inline::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( 'sample_module' );

my @retvals = $inline->run( 'sample_module', 'sample_func', 2, 3 );

print $retvals[0], "\n";

exit(0);

sample_module.c:

int sample_func( int arg1, int arg2 ) {
    return arg1 * arg2;
}

DESCRIPTION

Inline::Wrapper provides wrapper routines to make embedding another language into a Perl application more convenient.

Instead of having to include the external code in after __END__ in Perl source code, you can have separate, individually configurable language module directories to contain all of your code.

FEATURES

Inline::Wrapper provides the following:

  • Support for all languages that Inline.pm supports.

  • A single, unified interface to running loaded module functions.

  • Loading of files containing pure source code, only in their respective language.

  • Individually configurable module directories.

  • Automatic, run-time module reloading upon file modification time detection.

  • No more namespace pollution.

CONSTRUCTOR

$obj = new( [ var => value, ... ] )

Create a new Inline::Wrapper object, with the appropriate attributes (if specified).

RETURNS: blessed $object, or undef on failure.

ARGUMENTS:

All arguments are of the hash form Var => Value. new() will complain and croak if they do not follow this form.

NOTE: The arguments to new() become the defaults used by load(). You can individually configure loaded modules using load(), as well.

language [ default: Lua ]

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, documented below, after the object has been instantiated.

auto_reload [ default: FALSE ]

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: '.' ]

Set to the default base directory from which you wish to load all modules.

Example

my $wrapper = Inline::Wrapper->new(
       language        => 'C',
       base_dir        => 'src/code/C',
       auto_reload     => 1,
);

METHODS

initialize( )

Initialize arguments. If you are subclassing, overload this, not new().

Returns nothing.

load( $modname [, %arguments ] )

The workhorse. Loads the actual module itself, importing its symbols into a private namespace, and making them available to call via run().

$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, a few lines down for clarification of how pathname resolution is done. It is also how you will refer to this particular module from your program.

This method accepts all of the same arguments as new(). Thus, you can set the DEFAULTS via new(), yet still individually configure module components different 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 available functions in that module immediately.
2. Creates a new Inline::Wrapper::Module container object with any supplied %arguments, or the defaults you specified with Inline::Wrapper-new()>.
3. Constructs a path to the specified $modname, as follows:
$base_dir + $path_separator + $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. 'foo' is just as valid as 'foo/bar/baz'.
$lang_ext is taken from a data structure that defaults to common-sense 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.
run( $modname, $function [, @args ] )

Run the named $function that you loaded from $modname, with the specified @arguments (if any).

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 @list of actual return values provided by the module itself. Whatever the module returns in its native language, you get back.

modules( )

Returns @list of available, loaded and ready module names, or the empty list if no modules have been loaded.

functions( $modname )

Returns @list of functions provided by $modname, or the empty list.

ACCESSORS

Various accessors that allow you to inspect or change the default settings after creating the object.

base_dir( )

Returns the base_dir attribute from the object.

set_base_dir( $path )

Sets the 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( )

Returns a $boolean as to whether or not the current DEFAULT auto_reload() setting is enabled.

set_auto_reload( $boolean )

Sets the 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( )

Returns the language attribute of the object.

set_language( $lang )

Sets the 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, described next.

add_language( $language = $extension> )

Adds a language to the "known languages" table, allowing you to later use set_language( $lang ).

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, issues warnings and returns FALSE otherwise.

NOTE:If you CHANGE a language filename extension with a module already loaded with auto_reload enabled, and don't rename the underlying file, it'll probably freak during dynamic pathname construction, thinking the file has been removed. I'll fix this in a later version. For now, Don't Do That(tm).

SEE ALSO

Inline::Wrapper::Module

The Inline documentation.

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.

Jason McManus (INFIDEL) -- infidel@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.