PDL::PP-Inline(1)

1PP-INLINE(1)          User Contributed Perl Documentation         PP-INLINE(1)
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 mostly a shameless rip-off of "Inline::C".  Most
24       Kudos goes to Brian I.
25

Usage

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

Examples

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

Pdlpp Configuration Options

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

BUGS

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

ACKNOWLEDGEMENTS

276       Brian Ingerson for creating the Inline infrastructure.
277

AUTHOR

279       Christian Soeller <soellermail@excite.com>
280

COPYRIGHT

291       Copyright (c) 2001. Christian Soeller. All rights reserved.
292
293       This program is free software; you can redistribute it and/or modify it
294       under the same terms as PDL itself.
295
296       See http://pdl.perl.org
297
298
299
300perl v5.8.8                       2003-05-21                      PP-INLINE(1)