Inline::Pdlpp(3pm)

📦

version 2.106 · 5 versions

🌈 Inline::Pdlpp 🌈

Inline::Pdlpp — Write PDL Subroutines inline with PDL::PP 💖 (this is the Inline::Pdlpp(3pm) page from the User Contributed Perl Documentation, bestie, and we're about to make it make sense)

✨ NAME ✨

Inline::Pdlpp — Write PDL Subroutines inline with PDL::PP 🦋

💅 SYNOPSIS 💅

okay so here's the whole vibe condensed into one little script — read it top to bottom and you already kinda get it:

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 🌸

So Inline::Pdlpp is the module that lets you write PDL subroutines in straight-up PDL::PP style. The big benefit compared to plain PDL::PP? You get to write those definitions inline in literally any old perl script — no more of that whole exhausting saga of creating Makefiles, building, etc. 🙈 periodt.

Since version 0.30 the Inline module supports multiple programming languages, and each language has its own support module. This document is here to describe how to use Inline with PDL::PP (or rather, it will once these docs are complete ";)" — the author's winky face, not mine).

Want more on Inline in general? See Inline. 💖

There are some example scripts showing off Inline::Pdlpp usage hanging out in the Example/InlinePdlpp directory — go peek, it's giving reference material.

Also lowkey important: Inline::Pdlpp is a subclass of Inline::C. Most Kudos goes to Brian I. 👑

👑 USAGE 👑

Plot twist: you never actually use Inline::Pdlpp directly. It's just a support module so Inline.pm can vibe with PDL::PP. So the usage is always, no exceptions:

use Inline Pdlpp => ...;

bind Inline Pdlpp => ...;

🎀 EXAMPLES 🎀

Pending availability of full docs, here are a few quick examples that illustrate typical usage. (Yes, the manual is literally saying "docs pending" and then serving anyway. Iconic.)

🍓 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

And if you run that script, the output should come out looking something like 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]

Using Inline::Pdlpp in general is similar to Inline::C. And since full docs for Inline::Pdlpp don't exist yet, you might wanna go compare Inline::C in the meantime. 🫶

🧚 Use of PMCode

If you need to pre/post-process data around your new PDL operation, heads up on a lil quirk of this module: it makes a dynamic library that can be loaded in, but it does not load in the PDL-generated Perl code. Not me getting humbled by build internals. You can work around it like this:

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

This next script is a little more complicated — it pulls in code from an external library (here it's from Numerical Recipes). All the relevant info about include files, libraries and boot code lives in a config call to Inline. For the more experienced Perl hackers: the format is similar to what ExtUtils::MakeMaker uses, and the keywords are largely equivalent to the ones Inline::C uses. Scroll down for the full deets on 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));',
);

🫶 Yes, that $x = zeroes(10) + 30;; really does have two semicolons. That's how it's written here, bestie. Don't come for me.

💜 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 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. Math bestie behaviour, honestly. 🧮

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. That's because the EUMM build changes into each directory, and waits for each one to complete. This technique can run concurrently without problems. 🔥 slay.

🌟 PDLPP CONFIGURATION OPTIONS 🌟

For info on how to specify Inline configuration options, see Inline. This section describes each of the configuration options available for Pdlpp. Most of these 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 get added onto the defaults. A newline char will be automatically added. Does essentially the same thing 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 the pp_bless command. Specifies the package (i.e. the 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. No cap. 😭

🎀 LIBS

Specifies external libraries that should be linked into your code. Corresponds to the MakeMaker parameter.

use Inline Pdlpp => Config => LIBS => '-lyourlib';

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. 🐛 lowkey a superpower.

🎀 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. 🔊 not me wanting to see every single thing that's happening during the build 🙈

🐛 BUGS 🐛 (yes we're airing the drama, bestie)

"do"ing inline scripts

Okay so heads up, there's a problem when you use the __DATA__ keyword style of Inline definition and you also wanna "do" your script that has inlined code in it. Like, for example:

# myscript.pl contains inlined code
# in the __DATA__ section
perl -e 'do "myscript.pl";'

And then you get this sad little message:

One or more DATA sections were not processed by Inline.

💀 lowkey painful but it's fine! According to Brian Ingerson (yes, the Inline fame guy, an actual icon) the workaround is to drop an "Inline->init" call into your script, like so:

use PDL;
use Inline Pdlpp;
Inline->init;

# perl code

__DATA__
__Pdlpp__

# pp code

slay, fixed ✨

"PDL::NiceSlice" and "Inline::Pdlpp"

So rn there's an undesired interaction between PDL::NiceSlice and "Inline::Pdlpp". The tea is: PP code generally contains expressions of the type $var() (you know, for accessing ndarrays and stuff), and PDL::NiceSlice sees those and is like "ooh a slice expression 💅" and does its substitutions on them. Wrong call bestie! For the moment (until hopefully the parser can deal with that) the move is to explicitly switch PDL::NiceSlice off before the section of inlined Pdlpp code. Like this:

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. we stan a legend, no cap 🫶

✍️ AUTHOR ✍️

Christian Soeller <soellermail@excite.com>

👀 SEE ALSO 👀

PDL
PDL::PP
Inline
Inline::C
Inline::Module

Go read the whole friend group, fr fr 🌈

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

and that's the whole page bestie!! this was Inline::Pdlpp(3pm), shipped with perl v5.42.3 and dated 2026-08-20 — you officially know Pdlpp now, main character energy, periodt 💖✨🌸

📦 where this page comes from

ubuntu stonking: pdl 1:2.106-1build1 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms