.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Inline::Wrapper 3" .TH Inline::Wrapper 3 "2010-03-10" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Inline::Wrapper \- Convenient module wrapper/loader routines for Inline.pm .SH "SYNOPSIS" .IX Header "SYNOPSIS" sample.pl: .PP .Vb 1 \& use Inline::Wrapper; \& \& my $inline = Inline::Wrapper\->new( \& language => \*(AqC\*(Aq, \& base_dir => \*(Aq.\*(Aq, \& ); \& \& my @symbols = $inline\->load( \*(Aqanswer\*(Aq ); \& \& my @retvals = $inline\->run( \*(Aqanswer\*(Aq, \*(Aqthe_answer\*(Aq, 3, 56 ); \& \& print "The answer is: ", $retvals[0], "\en"; \& \& exit(0); .Ve .PP answer.c: .PP .Vb 3 \& int the_answer( int arg1, int arg2 ) { \& return ( arg1 * arg2 ) >> 2; \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBInline::Wrapper\fR provides wrapper routines around Inline to make embedding functions from another language into a Perl application much more convenient. .PP Instead of having to include the external code in a Perl source file after the _\|_END_\|_ directive, \fBInline::Wrapper\fR allows you to have separate, individually-configurable module repositories to more easily manage all of your external application code. .SH "FEATURES" .IX Header "FEATURES" \&\fBInline::Wrapper\fR provides the following features: .IP "\(bu" 4 Support for all languages supported by Inline. .IP "\(bu" 4 A single, unified interface for loading and running module functions. .IP "\(bu" 4 Loading of files containing pure source code, only in their respective languages, so you can isolate maintenance and management of these modules. .IP "\(bu" 4 Individually-configurable module directories. .IP "\(bu" 4 Automatic, run-time module reloading upon file modification time detection. .IP "\(bu" 4 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. .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" .SS "\fBnew()\fP" .IX Subsection "new()" .Vb 5 \& my $wrapper = Inline::Wrapper\->new( \& language => \*(AqC\*(Aq, \& base_dir => \*(Aqsrc/code/C\*(Aq, \& auto_reload => 1, \& ); .Ve .PP Create a new \fBInline::Wrapper\fR object, with the appropriate attributes (if specified). .PP \&\fB\s-1ARGUMENTS:\s0\fR .PP All arguments are of the hash form Var => Value. \*(L"\fBnew()\fR\*(R" will complain and croak if they do not follow this form. .PP The arguments to \*(L"\fBnew()\fR\*(R" become the defaults used by \*(L"\fBload()\fR\*(R". You can individually configure loaded modules using \*(L"\fBload()\fR\*(R", as well. .IP "\fIlanguage\fR [ default: \fB'Lua'\fR ]" 4 .IX Item "language [ default: 'Lua' ]" Optional. Set to the default language for which you wish to load modules, if not explicitly specified via \*(L"\fBload()\fR\*(R". .Sp \&\fB\s-1NOTE\s0\fR: It defaults to Lua because that is what I wrote this module for. Just pass in the argument if you don't like that. .Sp \&\fB\s-1ALSO NOTE:\s0\fR Currently only a couple of \*(L"known\*(R" languages are hard-coded into this module. If you wish to use others, don't pass this argument, and use the \*(L"\fBadd_language()\fR\*(R" method after the object has been instantiated. .IP "\fIauto_reload\fR [ default: \fB\s-1FALSE\s0\fR ]" 4 .IX Item "auto_reload [ default: FALSE ]" Optional. Set to a \s-1TRUE\s0 value to default to automatically checking if modules have been changed since the last \*(L"\fBload()\fR\*(R", and reload them if necessary. .IP "\fIbase_dir\fR [ default: \fB'.'\fR ]" 4 .IX Item "base_dir [ default: '.' ]" Optional. Set to the default base directory from which you wish to load all modules. .PP \&\fB\s-1RETURNS\s0\fR: blessed \f(CW$object\fR, or undef on failure. .SH "METHODS" .IX Header "METHODS" .SS "\fBinitialize()\fP" .IX Subsection "initialize()" .Vb 1 \& $obj\->initialize(); .Ve .PP Initialize arguments. If you are subclassing, overload this, not \*(L"\fBnew()\fR\*(R". .PP Generally only called from within \*(L"\fBnew()\fR\*(R". .SS "\fBload()\fP" .IX Subsection "load()" .Vb 1 \& my @functions = $obj\->load( $modname, %arguments ); .Ve .PP The workhorse. Loads the actual module referred to by \fI\f(CI$modname\fI\fR, imports its symbols into a private namespace, and makes them available to call via \*(L"\fBrun()\fR\*(R". .PP \&\fB\s-1ARGUMENTS:\s0\fR .PP \&\fI\f(CI$modname\fI\fR is \s-1REQUIRED.\s0 It corresponds to the base filename, without extension, loaded from the \fIbase_dir\fR. See the \&\*(L"Details of steps taken by \fBload()\fR\*(R" section, Step 3, for clarification of how pathname resolution is done. \fI\f(CI$modname\fI\fR is also how you will refer to this particular module from your program, so keep track of it. .PP This method accepts all of the same arguments as \*(L"\fBnew()\fR\*(R". Thus, you can set the defaults via \*(L"\fBnew()\fR\*(R", yet still individually configure module components differently from the defaults, if desired. .PP Returns a list of \f(CW@functions\fR made available by loading \fI\f(CI$modname\fI\fR, or warns and returns an empty list if unsuccessful. .PP \fIDetails of steps taken by \f(BIload()\fI\fR .IX Subsection "Details of steps taken by load()" .PP Since this is the real guts of this module, here are the exact steps taken when loading the module, doing pathname resolution, etc. .IP "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." 4 .IX Item "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." .PD 0 .ie n .IP "2. Creates a new Inline::Wrapper::Module container object with any supplied %arguments, or the defaults you specified with ""\fBnew()\fR""." 4 .el .IP "2. Creates a new Inline::Wrapper::Module container object with any supplied \f(CW%arguments\fR, or the defaults you specified with ``\fBnew()\fR''." 4 .IX Item "2. Creates a new Inline::Wrapper::Module container object with any supplied %arguments, or the defaults you specified with new()." .ie n .IP "3. Constructs a path to the specified $modname, roughly as follows:" 4 .el .IP "3. Constructs a path to the specified \f(CW$modname\fR, roughly as follows:" 4 .IX Item "3. Constructs a path to the specified $modname, roughly as follows:" .PD .Vb 1 \& join( $PATH_SEP, $base_dir , $modname . $lang_ext ); .Ve .RS 4 .ie n .IP "\fI\f(CI$base_dir\fI\fR is taken either from the default created with ""\fBnew()\fR"", or the explicitly supplied \fIbase_dir\fR argument to ""\fBload()\fR""." 4 .el .IP "\fI\f(CI$base_dir\fI\fR is taken either from the default created with ``\fBnew()\fR'', or the explicitly supplied \fIbase_dir\fR argument to ``\fBload()\fR''." 4 .IX Item "$base_dir is taken either from the default created with new(), or the explicitly supplied base_dir argument to load()." .PD 0 .IP "\fI\f(CI$path_separator\fI\fR is just the appropriate path separator for your \s-1OS.\s0" 4 .IX Item "$path_separator is just the appropriate path separator for your OS." .IP "\fI\f(CI$modname\fI\fR is your supplied module name. Note that this means that you can supply your own subdirectories, as well; i.e. \fI'foo'\fR is just as valid as \fI'foo/bar/baz'\fR." 4 .IX Item "$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'." .ie n .IP "\fI\f(CI$lang_ext\fI\fR 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 ""\fBadd_language()\fR"" method." 4 .el .IP "\fI\f(CI$lang_ext\fI\fR 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 ``\fBadd_language()\fR'' method." 4 .IX Item "$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." .RE .RS 4 .RE .IP "4. Attempts to open the file at the path constructed above, and if successful, slurps in the entire source file." 4 .IX Item "4. Attempts to open the file at the path constructed above, and if successful, slurps in the entire source file." .IP "5. Attempts to \fBbind()\fR (compile and set symbols) it with the Inline\->\fBbind()\fR method into a private namespace." 4 .IX Item "5. Attempts to bind() (compile and set symbols) it with the Inline->bind() method into a private namespace." .IP "6. If step 5 was successful, set the load time, and return the list of loaded, available functions provided by the module." 4 .IX Item "6. If step 5 was successful, set the load time, and return the list of loaded, available functions provided by the module." .IP "7. If step 5 failed, warn and return an empty list." 4 .IX Item "7. If step 5 failed, warn and return an empty list." .PD .SS "\fBunload()\fP" .IX Subsection "unload()" .Vb 1 \& $obj\->unload( $modname ); .Ve .PP Completely unload the module identified by \fI\f(CI$modname\fI\fR, and render its functions uncallable. .PP This will actually go destroy the Inline::Wrapper::Module object, as well as the code module's corresponding private namespace. .PP Returns \fI\f(CI$modname\fI\fR (\s-1TRUE\s0) upon success, carps and returns undef on failure. .SS "\fBrun()\fP" .IX Subsection "run()" .Vb 1 \& my @retvals = $obj\->run( $modname, $function, @arguments ); .Ve .PP Run the named \fI\f(CI$function\fI\fR that you loaded from \fI\f(CI$modname\fI\fR, with the specified \fI\f(CI@arguments\fI\fR (if any). .PP \&\fB\s-1NOTE:\s0\fR If the \fIauto_reload\fR option is \s-1TRUE,\s0 \fBrun()\fR 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. .PP 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. .PP Returns \fI\f(CI@retvals\fI\fR, consisting of the actual return values provided by the module function itself. Whatever the function returns, that's what you get. .SS "\fBmodules()\fP" .IX Subsection "modules()" .Vb 1 \& my @modules = $obj\->modules(); .Ve .PP Returns a list of loaded module names, or the empty list if no modules have been (successfully) loaded. .SS "\fBfunctions()\fP" .IX Subsection "functions()" .Vb 1 \& my @functions = $obj\->functions( $modname ); .Ve .PP Returns a list of loaded \fI\f(CI@functions\fI\fR, which were made available by loading \&\fI\f(CI$modname\fI\fR. .SH "ACCESSORS" .IX Header "ACCESSORS" Various accessors that allow you to inspect or change the default settings after creating the object. .SS "\fBbase_dir()\fP" .IX Subsection "base_dir()" .Vb 1 \& my $base_dir = $obj\->base_dir(); .Ve .PP Returns the default \fIbase_dir\fR attribute from the object. .SS "\fBset_base_dir()\fP" .IX Subsection "set_base_dir()" .Vb 1 \& $obj\->set_base_dir( \*(Aq/some/path\*(Aq ); .Ve .PP Sets the default \fIbase_dir\fR attribute of the object, and returns whatever it ended up being set to. .PP \&\fB\s-1NOTE:\s0\fR Only affects modules loaded \fIafter\fR this setting was made. .SS "\fBauto_reload()\fP" .IX Subsection "auto_reload()" .Vb 1 \& my $bool = $obj\->auto_reload(); .Ve .PP Returns a \f(CW$boolean\fR as to whether or not the default \fIauto_reload\fR setting is enabled for new modules. .SS "\fBset_auto_reload()\fP" .IX Subsection "set_auto_reload()" .Vb 1 \& $obj\->set_auto_reload( 1 ); .Ve .PP Sets the default \fIauto_reload\fR attribute of the object, and returns whatever it ended up being set to. .PP \&\fB\s-1NOTE:\s0\fR Only affects modules loaded \fIafter\fR this setting was made. .SS "\fBlanguage()\fP" .IX Subsection "language()" .Vb 1 \& my $lang = $obj\->language(); .Ve .PP Returns the default \fIlanguage\fR attribute of the object. .SS "\fBset_language()\fP" .IX Subsection "set_language()" .Vb 1 \& $obj\->set_language( \*(AqC\*(Aq ); .Ve .PP Sets the default \fIlanguage\fR attribute of the object, and returns whatever it ended up being set to. .PP \&\fB\s-1NOTE:\s0\fR Only affects modules loaded \fIafter\fR this setting was made. .PP \&\fB\s-1ALSO NOTE:\s0\fR This checks for \*(L"valid\*(R" languages via a pretty naive method. Currently only a couple are hard-coded. However, you can add your own languages via the \*(L"\fBadd_language()\fR\*(R" method. .SS "\fBadd_language()\fP" .IX Subsection "add_language()" .Vb 1 \& $obj\->add_language( \*(AqLojban\*(Aq => \*(Aq.xkcd\*(Aq ); .Ve .PP Adds a language to the \*(L"known languages\*(R" table, allowing you to later use \&\*(L"\fBset_language()\fR\*(R". .PP This can also be used to set a new file extension for an existing language. .PP \&\s-1REQUIRES\s0 a \fI\f(CI$language\fI\fR name (e.g. 'Python') and a filename \fI\f(CI$extension\fI\fR (e.g. '.py'), which will be used in pathname resolution, as described under \&\*(L"\fBload()\fR\*(R". .PP Returns \s-1TRUE\s0 if successful, carps and returns \s-1FALSE\s0 otherwise. .SH "SEE ALSO" .IX Header "SEE ALSO" Inline::Wrapper::Module .PP The Inline documentation. .PP The Inline-FAQ list. .PP The examples/ directory of this module's distribution. .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" Thank you, kennethk and ikegami for your assistance on perlmonks. .PP .SH "AUTHOR" .IX Header "AUTHOR" Please kindly read through this documentation and the \fBexamples/\fR thoroughly, before emailing me with questions. Your answer is likely in here. .PP Also, please make sure that your issue is actually with \fBInline::Wrapper\fR and not with Inline itself. .PP Jason McManus (\s-1INFIDEL\s0) \*(-- \f(CW\*(C`infidel AT cpan.org\*(C'\fR .SH "LICENSE" .IX Header "LICENSE" Copyright (c) Jason McManus .PP 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.