.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Pdlpp 3pm"
.TH Pdlpp 3pm "2023-06-17" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Inline::Pdlpp \- Write PDL Subroutines inline with PDL::PP
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Inline::Pdlpp\*(C'\fR is a module that allows you to write \s-1PDL\s0 subroutines
in the \s-1PDL::PP\s0 style. The big benefit compared to plain \f(CW\*(C`PDL::PP\*(C'\fR 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 \s-1PDL::PP\s0 (or rather, it will once
these docs are complete \f(CW\*(C`;)\*(C'\fR.
.PP
For more information on Inline in general, see Inline.
.PP
Some example scripts demonstrating \f(CW\*(C`Inline::Pdlpp\*(C'\fR usage can be
found in the \fIExample/InlinePdlpp\fR directory.
.PP
\&\f(CW\*(C`Inline::Pdlpp\*(C'\fR is a subclass of Inline::C. Most Kudos goes to Brian I.
.SH "Usage"
.IX Header "Usage"
You never actually use \f(CW\*(C`Inline::Pdlpp\*(C'\fR directly. It is just a support module
for using \f(CW\*(C`Inline.pm\*(C'\fR with \f(CW\*(C`PDL::PP\*(C'\fR. So the usage is always:
.PP
.Vb 1
\&    use Inline Pdlpp => ...;
.Ve
.PP
or
.PP
.Vb 1
\&    bind Inline Pdlpp => ...;
.Ve
.SH "Examples"
.IX Header "Examples"
Pending availability of full docs a few quick examples
that illustrate typical usage.
.SS "A simple example"
.IX Subsection "A simple example"
.Vb 2
\&   # example script inlpp.pl
\&   use PDL; # must be called before (!) \*(Aquse Inline Pdlpp\*(Aq calls
\&
\&   use Inline Pdlpp; # the actual code is in the _\|_Pdlpp_\|_ block below
\&
\&   $x = sequence 10;
\&   print $x\->inc,"\en";
\&   print $x\->inc\->dummy(1,10)\->tcumul,"\en";
\&
\&   _\|_DATA_\|_
\&
\&   _\|_Pdlpp_\|_
\&
\&   pp_def(\*(Aqinc\*(Aq,
\&          Pars => \*(Aqi();[o] o()\*(Aq,
\&          Code => \*(Aq$o() = $i() + 1;\*(Aq,
\&         );
\&
\&   pp_def(\*(Aqtcumul\*(Aq,
\&          Pars => \*(Aqin(n);[o] mul()\*(Aq,
\&          Code => \*(Aq$mul() = 1;
\&                   loop(n) %{
\&                     $mul() *= $in();
\&                   %}\*(Aq,
\&   );
\&   # end example script
.Ve
.PP
If you call this script it should generate output similar to this:
.PP
.Vb 4
\&   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]
.Ve
.PP
Usage of \f(CW\*(C`Inline::Pdlpp\*(C'\fR in general is similar to \f(CW\*(C`Inline::C\*(C'\fR.
In the absence of full docs for \f(CW\*(C`Inline::Pdlpp\*(C'\fR you might want to compare
Inline::C.
.SS "Code that uses external libraries, etc"
.IX Subsection "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 \f(CW\*(C`Inline\*(C'\fR. 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 \f(CW\*(C`Inline::C\*(C'\fR. Please
see below for further details on the usage of \f(CW\*(C`INC\*(C'\fR,
\&\f(CW\*(C`LIBS\*(C'\fR, \f(CW\*(C`AUTO_INCLUDE\*(C'\fR and \f(CW\*(C`BOOT\*(C'\fR.
.PP
.Vb 1
\&   use PDL; # this must be called before (!) \*(Aquse Inline Pdlpp\*(Aq 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 => <<\*(AqEOINC\*(Aq,
\&   #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...\en");
\&     croak("NR runtime error: %s",err_txt);
\&   }
\&   EOINC
\&   # install our error handler when loading the Inline::Pdlpp code
\&   BOOT => \*(Aqset_nr_err_handler(nr_barf);\*(Aq;
\&
\&   use Inline Pdlpp; # the actual code is in the _\|_Pdlpp_\|_ block below
\&
\&   $x = zeroes(10) + 30;;
\&   print $x\->poidev(5),"\en";
\&
\&   _\|_DATA_\|_
\&
\&   _\|_Pdlpp_\|_
\&
\&   pp_def(\*(Aqpoidev\*(Aq,
\&           Pars => \*(Aqxm(); [o] pd()\*(Aq,
\&           GenericTypes => [L,F,D],
\&           OtherPars => \*(Aqlong idum\*(Aq,
\&           Code => \*(Aq$pd() = poidev((float) $xm(), &$COMP(idum));\*(Aq,
\&   );
.Ve
.SH "Pdlpp Configuration Options"
.IX Header "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
\&\s-1XS\s0 options of the same name. See ExtUtils::MakeMaker and perlxs.
.SS "\s-1AUTO_INCLUDE\s0"
.IX Subsection "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 \f(CW\*(C`pp_addhdr\*(C'\fR. For short
bits of code \f(CW\*(C`AUTO_INCLUDE\*(C'\fR is probably syntactically nicer.
.PP
.Vb 1
\&    use Inline Pdlpp => Config => AUTO_INCLUDE => \*(Aq#include "yourheader.h"\*(Aq;
.Ve
.SS "\s-1BLESS\s0"
.IX Subsection "BLESS"
Same as \f(CW\*(C`pp_bless\*(C'\fR command. Specifies the package (i.e. class)
to which your new \fIpp_def\fRed methods will be added. Defaults
to \f(CW\*(C`PDL\*(C'\fR if omitted.
.PP
.Vb 1
\&    use Inline Pdlpp => Config => BLESS => \*(AqPDL::MyPackage\*(Aq;
.Ve
.PP
cf \*(L"\s-1PACKAGE\*(R"\s0, equivalent for \*(L"pp_addxs\*(R" in \s-1PDL::PP\s0.
.SS "\s-1BOOT\s0"
.IX Subsection "BOOT"
Specifies C code to be executed in the \s-1XS BOOT\s0 section. Corresponds to
the \s-1XS\s0 parameter. Does the same as the \f(CW\*(C`pp_add_boot\*(C'\fR command. Often used
to execute code only once at load time of the module, e.g. a library
initialization call.
.SS "\s-1CC\s0"
.IX Subsection "CC"
Specify which compiler to use.
.SS "\s-1CCFLAGS\s0"
.IX Subsection "CCFLAGS"
Specify extra compiler flags.
.SS "\s-1INC\s0"
.IX Subsection "INC"
Specifies an include path to use. Corresponds to the MakeMaker parameter.
.PP
.Vb 1
\&    use Inline Pdlpp => Config => INC => \*(Aq\-I/inc/path\*(Aq;
.Ve
.SS "\s-1LD\s0"
.IX Subsection "LD"
Specify which linker to use.
.SS "\s-1LDDLFLAGS\s0"
.IX Subsection "LDDLFLAGS"
Specify which linker flags to use.
.PP
\&\s-1NOTE:\s0 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.
.SS "\s-1LIBS\s0"
.IX Subsection "LIBS"
Specifies external libraries that should be linked into your
code. Corresponds to the MakeMaker parameter.
.PP
.Vb 1
\&    use Inline Pdlpp => Config => LIBS => \*(Aq\-lyourlib\*(Aq;
.Ve
.PP
or
.PP
.Vb 1
\&    use Inline Pdlpp => Config => LIBS => \*(Aq\-L/your/path \-lyourlib\*(Aq;
.Ve
.SS "\s-1MAKE\s0"
.IX Subsection "MAKE"
Specify the name of the 'make' utility to use.
.SS "\s-1MYEXTLIB\s0"
.IX Subsection "MYEXTLIB"
Specifies a user compiled object that should be linked in. Corresponds
to the MakeMaker parameter.
.PP
.Vb 1
\&    use Inline Pdlpp => Config => MYEXTLIB => \*(Aq/your/path/yourmodule.so\*(Aq;
.Ve
.SS "\s-1OPTIMIZE\s0"
.IX Subsection "OPTIMIZE"
This controls the MakeMaker \s-1OPTIMIZE\s0 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.
.SS "\s-1PACKAGE\s0"
.IX Subsection "PACKAGE"
Controls into which package the created XSUBs from \*(L"pp_addxs\*(R" in \s-1PDL::PP\s0
go. E.g.:
.PP
.Vb 1
\&    use Inline Pdlpp => \*(AqDATA\*(Aq, => PACKAGE => \*(AqOther::Place\*(Aq;
.Ve
.PP
will put the created routines into \f(CW\*(C`Other::Place\*(C'\fR, not the calling
package (which is the default). Note this differs from \*(L"\s-1BLESS\*(R"\s0, which
is where \*(L"pp_def\*(R" in \s-1PDL::PP\s0s go.
.SS "\s-1TYPEMAPS\s0"
.IX Subsection "TYPEMAPS"
Specifies extra typemap files to use. Corresponds to the MakeMaker parameter.
.PP
.Vb 1
\&    use Inline Pdlpp => Config => TYPEMAPS => \*(Aq/your/path/typemap\*(Aq;
.Ve
.SS "\s-1NOISY\s0"
.IX Subsection "NOISY"
Show the output of any compilations going on behind the scenes. Turns
on \f(CW\*(C`BUILD_NOISY\*(C'\fR in Inline::C.
.SH "BUGS"
.IX Header "BUGS"
.ie n .SS """do""ing inline scripts"
.el .SS "\f(CWdo\fPing inline scripts"
.IX Subsection "doing inline scripts"
Beware that there is a problem when you use
the _\|_DATA_\|_ keyword style of Inline definition and
want to \f(CW\*(C`do\*(C'\fR your script containing inlined code. For example
.PP
.Vb 4
\&   # myscript.pl contains inlined code
\&   # in the _\|_DATA_\|_ section
\&   perl \-e \*(Aqdo "myscript.pl";\*(Aq
\& One or more DATA sections were not processed by Inline.
.Ve
.PP
According to Brian Ingerson (of Inline fame) the workaround is
to include an \f(CW\*(C`Inline\->init\*(C'\fR call in your script, e.g.
.PP
.Vb 3
\&  use PDL;
\&  use Inline Pdlpp;
\&  Inline\->init;
\&
\&  # perl code
\&
\&  _\|_DATA_\|_
\&  _\|_Pdlpp_\|_
\&
\&  # pp code
.Ve
.ie n .SS """PDL::NiceSlice"" and ""Inline::Pdlpp"""
.el .SS "\f(CWPDL::NiceSlice\fP and \f(CWInline::Pdlpp\fP"
.IX Subsection "PDL::NiceSlice and Inline::Pdlpp"
There is currently an undesired interaction between
PDL::NiceSlice and \f(CW\*(C`Inline::Pdlpp\*(C'\fR.
Since \s-1PP\s0 code generally contains expressions
of the type \f(CW\*(C`$var()\*(C'\fR (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:
.PP
.Vb 2
\&  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
.Ve
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Brian Ingerson for creating the Inline infrastructure.
.SH "AUTHOR"
.IX Header "AUTHOR"
Christian Soeller <soellermail@excite.com>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1PDL\s0
.PP
\&\s-1PDL::PP\s0
.PP
Inline
.PP
Inline::C
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2001. Christian Soeller. All rights reserved.
.PP
This program is free software; you can redistribute it and/or
modify it under the same terms as \s-1PDL\s0 itself.
.PP
See http://pdl.perl.org