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

Pdlpp Configuration Options

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

BUGS

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

ACKNOWLEDGEMENTS

258       Brian Ingerson for creating the Inline infrastructure.
259

AUTHOR

261       Christian Soeller <soellermail@excite.com>
262

COPYRIGHT

273       Copyright (c) 2001. Christian Soeller. All rights reserved.
274
275       This program is free software; you can redistribute it and/or modify it
276       under the same terms as PDL itself.
277
278       See http://pdl.perl.org
279
280
281
282perl v5.12.3                      2011-03-31                      PP-INLINE(1)