Pdlpp(3pm)

1Pdlpp(3)              User Contributed Perl Documentation             Pdlpp(3)
2
3
4

NAME

6       Inline::Pdlpp - Write PDL Subroutines inline with PDL::PP
7

DESCRIPTION

9       "Inline::Pdlpp" is a module that allows you to write PDL subroutines in
10       the PDL::PP style. The big benefit compared to plain "PDL::PP" is that
11       you can write these definitions inline in any old perl script (without
12       the normal hassle of creating Makefiles, building, etc).  Since version
13       0.30 the Inline module supports multiple programming languages and each
14       language has its own support module. This document describes how to use
15       Inline with PDL::PP (or rather, it will once these docs are complete
16       ";)".
17
18       For more information on Inline in general, see Inline.
19
20       Some example scripts demonstrating "Inline::Pdlpp" usage can be found
21       in the Example/InlinePdlpp directory.
22
23       "Inline::Pdlpp" is a subclass of Inline::C. Most Kudos goes to Brian I.
24

Usage

26       You never actually use "Inline::Pdlpp" directly. It is just a support
27       module for using "Inline.pm" with "PDL::PP". So the usage is always:
28
29           use Inline Pdlpp => ...;
30
31       or
32
33           bind Inline Pdlpp => ...;
34

Examples

36       Pending availability of full docs a few quick examples that illustrate
37       typical usage.
38
39   A simple example
40          # example script inlpp.pl
41          use PDL; # must be called before (!) 'use Inline Pdlpp' calls
42
43          use Inline Pdlpp; # the actual code is in the __Pdlpp__ block below
44
45          $x = sequence 10;
46          print $x->inc,"\n";
47          print $x->inc->dummy(1,10)->tcumul,"\n";
48
49          __DATA__
50
51          __Pdlpp__
52
53          pp_def('inc',
54                 Pars => 'i();[o] o()',
55                 Code => '$o() = $i() + 1;',
56                );
57
58          pp_def('tcumul',
59                 Pars => 'in(n);[o] mul()',
60                 Code => '$mul() = 1;
61                          loop(n) %{
62                            $mul() *= $in();
63                          %}',
64          );
65          # end example script
66
67       If you call this script it should generate output similar to this:
68
69          prompt> perl inlpp.pl
70          Inline running PDL::PP version 2.2...
71          [1 2 3 4 5 6 7 8 9 10]
72          [3628800 3628800 3628800 3628800 3628800 3628800 3628800 3628800 3628800 3628800]
73
74       Usage of "Inline::Pdlpp" in general is similar to "Inline::C".  In the
75       absence of full docs for "Inline::Pdlpp" you might want to compare
76       Inline::C.
77
78   Code that uses external libraries, etc
79       The script below is somewhat more complicated in that it uses code from
80       an external library (here from Numerical Recipes). All the relevant
81       information regarding include files, libraries and boot code is
82       specified in a config call to "Inline". For more experienced Perl
83       hackers it might be helpful to know that the format is similar to that
84       used with ExtUtils::MakeMaker. The keywords are largely equivalent to
85       those used with "Inline::C". Please see below for further details on
86       the usage of "INC", "LIBS", "AUTO_INCLUDE" and "BOOT".
87
88          use PDL; # this must be called before (!) 'use Inline Pdlpp' calls
89
90          use Inline Pdlpp => Config =>
91            INC => "-I$ENV{HOME}/include",
92            LIBS => "-L$ENV{HOME}/lib -lnr -lm",
93            # code to be included in the generated XS
94            AUTO_INCLUDE => <<'EOINC',
95          #include <math.h>
96          #include "nr.h"    /* for poidev */
97          #include "nrutil.h"  /* for err_handler */
98
99          static void nr_barf(char *err_txt)
100          {
101            fprintf(stderr,"Now calling croak...\n");
102            croak("NR runtime error: %s",err_txt);
103          }
104          EOINC
105          # install our error handler when loading the Inline::Pdlpp code
106          BOOT => 'set_nr_err_handler(nr_barf);';
107
108          use Inline Pdlpp; # the actual code is in the __Pdlpp__ block below
109
110          $x = zeroes(10) + 30;;
111          print $x->poidev(5),"\n";
112
113          __DATA__
114
115          __Pdlpp__
116
117          pp_def('poidev',
118                  Pars => 'xm(); [o] pd()',
119                  GenericTypes => [L,F,D],
120                  OtherPars => 'long idum',
121                  Code => '$pd() = poidev((float) $xm(), &$COMP(idum));',
122          );
123

Pdlpp Configuration Options

125       For information on how to specify Inline configuration options, see
126       Inline. This section describes each of the configuration options
127       available for Pdlpp. Most of the options correspond either to MakeMaker
128       or XS options of the same name. See ExtUtils::MakeMaker and perlxs.
129
130   AUTO_INCLUDE
131       Specifies extra statements to automatically included. They will be
132       added onto the defaults. A newline char will be automatically added.
133       Does essentially the same as a call to "pp_addhdr". For short bits of
134       code "AUTO_INCLUDE" is probably syntactically nicer.
135
136           use Inline Pdlpp => Config => AUTO_INCLUDE => '#include "yourheader.h"';
137
138   BLESS
139       Same as "pp_bless" command. Specifies the package (i.e. class) to which
140       your new pp_defed methods will be added. Defaults to "PDL" if omitted.
141
142           use Inline Pdlpp => Config => BLESS => 'PDL::MyPackage';
143
144       cf "PACKAGE", equivalent for "pp_addxs" in PDL::PP.
145
146   BOOT
147       Specifies C code to be executed in the XS BOOT section. Corresponds to
148       the XS parameter. Does the same as the "pp_add_boot" command. Often
149       used to execute code only once at load time of the module, e.g. a
150       library initialization call.
151
152   CC
153       Specify which compiler to use.
154
155   CCFLAGS
156       Specify extra compiler flags.
157
158   INC
159       Specifies an include path to use. Corresponds to the MakeMaker
160       parameter.
161
162           use Inline Pdlpp => Config => INC => '-I/inc/path';
163
164   LD
165       Specify which linker to use.
166
167   LDDLFLAGS
168       Specify which linker flags to use.
169
170       NOTE: These flags will completely override the existing flags, instead
171       of just adding to them. So if you need to use those too, you must
172       respecify them here.
173
174   LIBS
175       Specifies external libraries that should be linked into your code.
176       Corresponds to the MakeMaker parameter.
177
178           use Inline Pdlpp => Config => LIBS => '-lyourlib';
179
180       or
181
182           use Inline Pdlpp => Config => LIBS => '-L/your/path -lyourlib';
183
184   MAKE
185       Specify the name of the 'make' utility to use.
186
187   MYEXTLIB
188       Specifies a user compiled object that should be linked in. Corresponds
189       to the MakeMaker parameter.
190
191           use Inline Pdlpp => Config => MYEXTLIB => '/your/path/yourmodule.so';
192
193   OPTIMIZE
194       This controls the MakeMaker OPTIMIZE setting. By setting this value to
195       '-g', you can turn on debugging support for your Inline extensions.
196       This will allow you to be able to set breakpoints in your C code using
197       a debugger like gdb.
198
199   PACKAGE
200       Controls into which package the created XSUBs from "pp_addxs" in
201       PDL::PP go. E.g.:
202
203           use Inline Pdlpp => 'DATA', => PACKAGE => 'Other::Place';
204
205       will put the created routines into "Other::Place", not the calling
206       package (which is the default). Note this differs from "BLESS", which
207       is where "pp_def" in PDL::PPs go.
208
209   TYPEMAPS
210       Specifies extra typemap files to use. Corresponds to the MakeMaker
211       parameter.
212
213           use Inline Pdlpp => Config => TYPEMAPS => '/your/path/typemap';
214
215   NOISY
216       Show the output of any compilations going on behind the scenes. Turns
217       on "BUILD_NOISY" in Inline::C.
218

BUGS

220   "do"ing inline scripts
221       Beware that there is a problem when you use the __DATA__ keyword style
222       of Inline definition and want to "do" your script containing inlined
223       code. For example
224
225          # myscript.pl contains inlined code
226          # in the __DATA__ section
227          perl -e 'do "myscript.pl";'
228        One or more DATA sections were not processed by Inline.
229
230       According to Brian Ingerson (of Inline fame) the workaround is to
231       include an "Inline->init" call in your script, e.g.
232
233         use PDL;
234         use Inline Pdlpp;
235         Inline->init;
236
237         # perl code
238
239         __DATA__
240         __Pdlpp__
241
242         # pp code
243
244   "PDL::NiceSlice" and "Inline::Pdlpp"
245       There is currently an undesired interaction between PDL::NiceSlice and
246       "Inline::Pdlpp".  Since PP code generally contains expressions of the
247       type $var() (to access ndarrays, etc) PDL::NiceSlice recognizes those
248       incorrectly as slice expressions and does its substitutions. For the
249       moment (until hopefully the parser can deal with that) it is best to
250       explicitly switch PDL::NiceSlice off before the section of inlined
251       Pdlpp code. For example:
252
253         use PDL::NiceSlice;
254         use Inline::Pdlpp;
255
256         $x = sequence 10;
257         $x(0:3)++;
258         $x->inc;
259
260         no PDL::NiceSlice;
261
262         __DATA__
263
264         __C__
265
266         ppdef (...); # your full pp definition here
267

ACKNOWLEDGEMENTS

269       Brian Ingerson for creating the Inline infrastructure.
270

AUTHOR

272       Christian Soeller <soellermail@excite.com>
273

COPYRIGHT

284       Copyright (c) 2001. Christian Soeller. All rights reserved.
285
286       This program is free software; you can redistribute it and/or modify it
287       under the same terms as PDL itself.
288
289       See http://pdl.perl.org
290
291
292
293perl v5.36.0                      2023-01-20                          Pdlpp(3)