Inline::Pdlapp - Write PDLA Subroutines inline with PDLA::PP
Inline::Pdlapp is a module that allows you to write PDLA subroutines in the PDLA::PP style. The big benefit compared to plain PDLA::PP is that you can write these definitions inline in any old perl script (without the normal hassle of creating Makefiles, building, etc). Since version 0.30 the Inline module supports multiple programming languages and each language has its own support module. This document describes how to use Inline with PDLA::PP (or rather, it will once these docs are complete ;).
Inline::Pdlapp
PDLA::PP
;)
For more information on Inline in general, see Inline.
Some example scripts demonstrating Inline::Pdlapp usage can be found in the Example/InlinePdlapp directory.
Inline::Pdlapp is a subclass of Inline::C. Most Kudos goes to Brian I.
You never actually use Inline::Pdlapp directly. It is just a support module for using Inline.pm with PDLA::PP. So the usage is always:
Inline.pm
use Inline Pdlapp => ...;
or
bind Inline Pdlapp => ...;
Pending availability of full docs a few quick examples that illustrate typical usage.
# example script inlpp.pl use PDLA; # must be called before (!) 'use Inline Pdlapp' calls use Inline Pdlapp; # the actual code is in the __Pdlapp__ block below $a = sequence 10; print $a->inc,"\n"; print $a->inc->dummy(1,10)->tcumul,"\n"; __DATA__ __Pdlapp__ pp_def('inc', Pars => 'i();[o] o()', Code => '$o() = $i() + 1;', ); pp_def('tcumul', Pars => 'in(n);[o] mul()', Code => '$mul() = 1; loop(n) %{ $mul() *= $in(); %}', ); # end example script
If you call this script it should generate output similar to this:
prompt> perl inlpp.pl Inline running PDLA::PP version 2.2... [1 2 3 4 5 6 7 8 9 10] [3628800 3628800 3628800 3628800 3628800 3628800 3628800 3628800 3628800 3628800]
Usage of Inline::Pdlapp in general is similar to Inline::C. In the absence of full docs for Inline::Pdlapp you might want to compare Inline::C.
Inline::C
The script below is somewhat more complicated in that it uses code from an external library (here from Numerical Recipes). All the relevant information regarding include files, libraries and boot code is specified in a config call to Inline. For more experienced Perl hackers it might be helpful to know that the format is similar to that used with ExtUtils::MakeMaker. The keywords are largely equivalent to those used with Inline::C. Please see below for further details on the usage of INC, LIBS, AUTO_INCLUDE and BOOT.
Inline
INC
LIBS
AUTO_INCLUDE
BOOT
use PDLA; # this must be called before (!) 'use Inline Pdlapp' calls use Inline Pdlapp => Config => INC => "-I$ENV{HOME}/include", LIBS => "-L$ENV{HOME}/lib -lnr -lm", # code to be included in the generated XS AUTO_INCLUDE => <<'EOINC', #include <math.h> #include "nr.h" /* for poidev */ #include "nrutil.h" /* for err_handler */ static void nr_barf(char *err_txt) { fprintf(stderr,"Now calling croak...\n"); croak("NR runtime error: %s",err_txt); } EOINC # install our error handler when loading the Inline::Pdlapp code BOOT => 'set_nr_err_handler(nr_barf);'; use Inline Pdlapp; # the actual code is in the __Pdlapp__ block below $a = zeroes(10) + 30;; print $a->poidev(5),"\n"; __DATA__ __Pdlapp__ pp_def('poidev', Pars => 'xm(); [o] pd()', GenericTypes => [L,F,D], OtherPars => 'long idum', Code => '$pd() = poidev((float) $xm(), &$COMP(idum));', );
For information on how to specify Inline configuration options, see Inline. This section describes each of the configuration options available for Pdlapp. Most of the options correspond either to MakeMaker or XS options of the same name. See ExtUtils::MakeMaker and perlxs.
Specifies extra statements to automatically included. They will be added onto the defaults. A newline char will be automatically added. Does essentially the same as a call to pp_addhdr. For short bits of code AUTO_INCLUDE is probably syntactically nicer.
pp_addhdr
use Inline Pdlapp => Config => AUTO_INCLUDE => '#include "yourheader.h"';
Same as pp_bless command. Specifies the package (i.e. class) to which your new pp_defed methods will be added. Defaults to PDLA if omitted.
pp_bless
PDLA
use Inline Pdlapp => Config => BLESS => 'PDLA::Complex';
Specifies C code to be executed in the XS BOOT section. Corresponds to the XS parameter. Does the same as the pp_add_boot command. Often used to execute code only once at load time of the module, e.g. a library initialization call.
pp_add_boot
Specify which compiler to use.
Specify extra compiler flags.
Specifies an include path to use. Corresponds to the MakeMaker parameter.
use Inline Pdlapp => Config => INC => '-I/inc/path';
Specify which linker to use.
Specify which linker flags to use.
NOTE: These flags will completely override the existing flags, instead of just adding to them. So if you need to use those too, you must respecify them here.
Specifies external libraries that should be linked into your code. Corresponds to the MakeMaker parameter.
use Inline Pdlapp => Config => LIBS => '-lyourlib';
use Inline Pdlapp => Config => LIBS => '-L/your/path -lyourlib';
Specify the name of the 'make' utility to use.
Specifies a user compiled object that should be linked in. Corresponds to the MakeMaker parameter.
use Inline Pdlapp => Config => MYEXTLIB => '/your/path/yourmodule.so';
This controls the MakeMaker OPTIMIZE setting. By setting this value to '-g', you can turn on debugging support for your Inline extensions. This will allow you to be able to set breakpoints in your C code using a debugger like gdb.
Specifies extra typemap files to use. Corresponds to the MakeMaker parameter.
use Inline Pdlapp => Config => TYPEMAPS => '/your/path/typemap';
Show the output of any compilations going on behind the scenes. Turns on BUILD_NOISY in Inline::C.
BUILD_NOISY
do
Beware that there is a problem when you use the __DATA__ keyword style of Inline definition and want to do your script containing inlined code. For example
# myscript.pl contains inlined code # in the __DATA__ section perl -e 'do "myscript.pl";' One or more DATA sections were not processed by Inline.
According to Brian Ingerson (of Inline fame) the workaround is to include an Inline->init call in your script, e.g.
Inline->init
use PDLA; use Inline Pdlapp; Inline->init; # perl code __DATA__ __Pdlapp__ # pp code
PDLA::NiceSlice
There is currently an undesired interaction between PDLA::NiceSlice and Inline::Pdlapp. Since PP code generally contains expressions of the type $var() (to access piddles, etc) PDLA::NiceSlice recognizes those incorrectly as slice expressions and does its substitutions. For the moment (until hopefully the parser can deal with that) it is best to explicitly switch PDLA::NiceSlice off before the section of inlined Pdlapp code. For example:
$var()
use PDLA::NiceSlice; use Inline::Pdlapp; $a = sequence 10; $a(0:3)++; $a->inc; no PDLA::NiceSlice; __DATA__ __C__ ppdef (...); # your full pp definition here
Brian Ingerson for creating the Inline infrastructure.
Christian Soeller <soellermail@excite.com>
Copyright (c) 2001. Christian Soeller. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as PDLA itself.
See http://pdl.perl.org
To install PDLA::Core, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PDLA::Core
CPAN shell
perl -MCPAN -e shell install PDLA::Core
For more information on module installation, please visit the detailed CPAN module installation guide.