Provided by: pdl_2.100-1_amd64 
NAME
Inline::Pdlpp - Write PDL Subroutines inline with PDL::PP
SYNOPSIS
use strict; use warnings;
use PDL;
use Inline Pdlpp => 'DATA';
# make data with: echo -n 'ATCGZATCG' >input.data
# use it with aa_to_int.pl input.data
my $file; ($file = shift, -f $file) || die "Usage: $0 filename";
my $size = -s $file;
my $pdl = zeroes(byte, $size);
${$pdl->get_dataref} = do { open my $fh, $file or die "$file: $!"; local $/; <$fh> };
$pdl->upd_data;
$pdl->inplace->aa_to_int;
print $pdl, "\n";
__DATA__
__Pdlpp__
pp_def('aa_to_int',
Pars => 'i();[o] o()',
GenericTypes => ['B'],
Inplace => 1,
Code => <<'EOF',
switch($i()) {
case 'A': $o() = 0; break;
case 'T': $o() = 1; break;
case 'C': $o() = 2; break;
case 'G': $o() = 3; break;
default: $o() = 255; break;
}
EOF
Doc => "=for ref\n\nConvert amino acid names to integers.\n",
);
DESCRIPTION
"Inline::Pdlpp" is a module that allows you to write PDL subroutines in the PDL::PP style. The big
benefit compared to plain "PDL::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 PDL::PP (or rather, it will once these docs are complete ";)".
For more information on Inline in general, see Inline.
Some example scripts demonstrating "Inline::Pdlpp" usage can be found in the Example/InlinePdlpp
directory.
"Inline::Pdlpp" is a subclass of Inline::C. Most Kudos goes to Brian I.
USAGE
You never actually use "Inline::Pdlpp" directly. It is just a support module for using "Inline.pm" with
"PDL::PP". So the usage is always:
use Inline Pdlpp => ...;
or
bind Inline Pdlpp => ...;
EXAMPLES
Pending availability of full docs a few quick examples that illustrate typical usage.
A simple example
# example script inlpp.pl
use PDL; # must be called before (!) 'use Inline Pdlpp' calls
use Inline Pdlpp; # the actual code is in the __Pdlpp__ block below
$x = sequence 10;
print $x->inc,"\n";
print $x->inc->dummy(1,10)->tcumul,"\n";
__DATA__
__Pdlpp__
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 PDL::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::Pdlpp" in general is similar to "Inline::C". In the absence of full docs for
"Inline::Pdlpp" you might want to compare Inline::C.
Use of PMCode
If you need to pre/post-process data around your new PDL operation, a quirk of this module is that it
makes a dynamic library that can be loaded in, but does not load in the PDL-generated Perl code. You can
work around that as follows:
use Inline Pdlpp => <<'EOF';
pp_def('collatz_pdl',
Pars => 'beg(); end(); [o]number(); [o]highest()',
GenericTypes => ['Q'],
PMCode => '', # trigger the _int but keep the Perl code in main body
Code => '
/*...*/
'
);
EOF
sub PDL::collatz_pdl {
PDL::_collatz_pdl_int(@_, my $n = PDL->null, my $h = PDL->null);
# Perl scalars because is across forked processes in MCE
map $_->sclr, $n, $h;
}
See <https://www.perlmonks.org/?node_id=11115392> for context.
Code that uses external libraries, etc
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".
use PDL; # this must be called before (!) 'use Inline Pdlpp' calls
use Inline Pdlpp => 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::Pdlpp code
BOOT => 'set_nr_err_handler(nr_barf);';
use Inline Pdlpp; # the actual code is in the __Pdlpp__ block below
$x = zeroes(10) + 30;;
print $x->poidev(5),"\n";
__DATA__
__Pdlpp__
pp_def('poidev',
Pars => 'xm(); [o] pd()',
GenericTypes => [L,F,D],
OtherPars => 'long idum',
Code => '$pd() = poidev((float) $xm(), &$COMP(idum));',
);
MAKING AN INSTALLABLE MODULE
It is possible, using Inline::Module, to create an installable .pm file with inline PDL code.
PDLA::IO::HDF is a working example. Here's how. You make a Perl module as usual, with a package
declaration in the normal way. Then (assume your package is "PDLA::IO::HDF::SD"):
package PDLA::IO::HDF::SD;
# ...
use FindBin;
use Alien::HDF4::Install::Files;
use PDLA::IO::HDF::SD::Inline Pdlapp => 'DATA',
package => __PACKAGE__, # if you have any pp_addxs - else don't bother
%{ Alien::HDF4::Install::Files->Inline('C') }, # EUD returns empty if !"C"
typemaps => "$FindBin::Bin/lib/PDLA/IO/HDF/typemap.hdf",
;
# ...
1;
__DATA__
__Pdlapp__
pp_addhdr(<<'EOH');
/* ... */
EOH
use FindBin;
use lib "$FindBin::Bin/../../../../../../..";
require 'buildfunc.noinst';
# etc
Note that for any files that you need to access for build purposes (they won't be touched during post-
install runtime), FindBin is useful, albeit slightly complicated.
In the main .pm body, FindBin will find the build directory, as illustrated above. However, in the
"inline" parts, "FindBin" will be within the Inline::Module build directory. At the time of writing, this
is under .inline within the build directory, in a subdirectory named after the package. The example shown
above has seven ..: two for .inline/build, and five more for PDLA/IO/HDF/SD/Inline.
The rest of the requirements are given in the Inline::Module documentation.
This technique avoids having to use PDL::Core::Dev, create a Makefile.PL, have one directory per .pd,
etc. It will even build / install faster, since unlike a build of an ExtUtils::MakeMaker distribution
with multiple directories, it can be built in parallel. This is because the EUMM build changes into each
directory, and waits for each one to complete. This technique can run concurrently without problems.
PDLPP CONFIGURATION OPTIONS
For information on how to specify Inline configuration options, see Inline. This section describes each
of the configuration options available for Pdlpp. Most of the options correspond either to MakeMaker or
XS options of the same name. See ExtUtils::MakeMaker and perlxs.
AUTO_INCLUDE
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.
use Inline Pdlpp => Config => AUTO_INCLUDE => '#include "yourheader.h"';
BLESS
Same as "pp_bless" command. Specifies the package (i.e. class) to which your new pp_defed methods will be
added. Defaults to "PDL" if omitted.
use Inline Pdlpp => Config => BLESS => 'PDL::MyPackage';
cf "PACKAGE", equivalent for "pp_addxs" in PDL::PP.
BOOT
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.
CC
Specify which compiler to use.
CCFLAGS
Specify extra compiler flags.
INC
Specifies an include path to use. Corresponds to the MakeMaker parameter.
use Inline Pdlpp => Config => INC => '-I/inc/path';
LD
Specify which linker to use.
LDDLFLAGS
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.
LIBS
Specifies external libraries that should be linked into your code. Corresponds to the MakeMaker
parameter.
use Inline Pdlpp => Config => LIBS => '-lyourlib';
or
use Inline Pdlpp => Config => LIBS => '-L/your/path -lyourlib';
MAKE
Specify the name of the 'make' utility to use.
MYEXTLIB
Specifies a user compiled object that should be linked in. Corresponds to the MakeMaker parameter.
use Inline Pdlpp => Config => MYEXTLIB => '/your/path/yourmodule.so';
OPTIMIZE
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.
PACKAGE
Controls into which package the created XSUBs from "pp_addxs" in PDL::PP go. E.g.:
use Inline Pdlpp => 'DATA', => PACKAGE => 'Other::Place';
will put the created routines into "Other::Place", not the calling package (which is the default). Note
this differs from "BLESS", which is where "pp_def" in PDL::PPs go.
TYPEMAPS
Specifies extra typemap files to use. Corresponds to the MakeMaker parameter.
use Inline Pdlpp => Config => TYPEMAPS => '/your/path/typemap';
NOISY
Show the output of any compilations going on behind the scenes. Turns on "BUILD_NOISY" in Inline::C.
BUGS
"do"ing inline scripts
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.
use PDL;
use Inline Pdlpp;
Inline->init;
# perl code
__DATA__
__Pdlpp__
# pp code
"PDL::NiceSlice" and "Inline::Pdlpp"
There is currently an undesired interaction between PDL::NiceSlice and "Inline::Pdlpp". Since PP code
generally contains expressions of the type $var() (to access ndarrays, etc) PDL::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 PDL::NiceSlice off before the section of
inlined Pdlpp code. For example:
use PDL::NiceSlice;
use Inline::Pdlpp;
$x = sequence 10;
$x(0:3)++;
$x->inc;
no PDL::NiceSlice;
__DATA__
__C__
ppdef (...); # your full pp definition here
ACKNOWLEDGEMENTS
Brian Ingerson for creating the Inline infrastructure.
AUTHOR
Christian Soeller <soellermail@excite.com>
SEE ALSO
PDL
PDL::PP
Inline
Inline::C
Inline::Module
COPYRIGHT
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 PDL
itself.
See http://pdl.perl.org
perl v5.40.1 2025-03-27 Inline::Pdlpp(3pm)