PP-INLINE(1p)

💖 PP-INLINE(1p) — aka Inline::Pdlpp 💖

okay bestie, welcome to the manual page for Inline::Pdlpp — the module that lets you write PDL subroutines inline with PDL::PP. buckle up, it's giving ✨compiler energy✨

---

🌸 NAME 🌸

Inline::Pdlpp — write PDL subroutines inline with PDL::PP 🫶

---

🦋 DESCRIPTION 🦋

okay so Inline::Pdlpp is a module that lets you write PDL subroutines in the PDL::PP style. the big glow-up compared to plain PDL::PP is that you can write these definitions inline in any old perl script — no more normal hassle of creating Makefiles, building, etc. literally the worst part, gone. 💅

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 ";)"). yes bestie the wink is load-bearing, I don't make the rules.

for more info on Inline in general, see Inline. 👑

some example scripts demonstrating Inline::Pdlpp usage can be found in the Example/InlinePdlpp directory. go peek, it's iconic.

Inline::Pdlpp is a subclass of Inline::C. most Kudos goes to Brian I. 🎀

✨ Usage ✨

not me telling you this: you never actually use Inline::Pdlpp directly. it's 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, here are a few quick examples that illustrate typical usage. fr fr.

🍓 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. 🧚

💜 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));',
);

---

🎀 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 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. (iykyk 💅)

🌸 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, they're gone otherwise. 😭

👑 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 bestie, 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. king behavior honestly. 👑

---

✨ AUTHOR ✨

Christian Soeller <soellermail@excite.com>

---

👀 SEE ALSO 👀

• PDL
• PDL::PP
• Inline
• Inline::C

---

💜 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 🌈

---

and that's a wrap bestie!! this was PP-INLINE(1p), straight from perl v5.38.2, dated 2024-04-10. go forth and write your inline PDL subroutines, you absolute icon. slay. 💅✨🎀