.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ExtUtils::XSpp 3pm"
.TH ExtUtils::XSpp 3pm "2011-12-20" "perl v5.14.2" "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"
ExtUtils::XSpp \- XS for C++
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  xspp [\-\-typemap=typemap.xsp [\-\-typemap=typemap2.xsp]]
\&       [\-\-xsubpp[=/path/to/xsubpp] [\-\-xsubpp\-args="xsubpp args"]
\&       Foo.xsp
.Ve
.PP
or
.PP
.Vb 1
\&  perl \-MExtUtils::XSpp::Cmd \-e xspp \-\- <xspp options and arguments>
.Ve
.PP
In Foo.xs
.PP
.Vb 1
\&  INCLUDE_COMMAND: $^X \-MExtUtils::XSpp::Cmd \-e xspp \-\- <xspp options/arguments>
.Ve
.PP
Using \f(CW\*(C`ExtUtils::XSpp::Cmd\*(C'\fR is equivalent to using the \f(CW\*(C`xspp\*(C'\fR
command line script, except that there is no guarantee for \f(CW\*(C`xspp\*(C'\fR to
be installed in the system \s-1PATH\s0.
.SH "OVERVIEW"
.IX Header "OVERVIEW"
\&\s-1XS++\s0 is just a thin layer over plain \s-1XS\s0, hence to use it you
are supposed to know, at the very least, \*(C+ and \s-1XS\s0.
.PP
This means that you will need typemaps for \fBboth\fR the normal \s-1XS\s0
pre-processor \fIxsubpp\fR and the \s-1XS++\s0 pre-processor \fIxspp\fR.
.SH "COMMAND LINE"
.IX Header "COMMAND LINE"
.ie n .SS """\-\-typemap=/path/to/typemap.xsp"""
.el .SS "\f(CW\-\-typemap=/path/to/typemap.xsp\fP"
.IX Subsection "--typemap=/path/to/typemap.xsp"
Can be specified multiple times to process additional typemap files
before the main \s-1XS++\s0 input files.  Typemap files are processed the
same way as regular \s-1XS++\s0 files, except that output code is discarded.
.ie n .SS """\-\-xsubpp[=/path/to/xsubpp]"""
.el .SS "\f(CW\-\-xsubpp[=/path/to/xsubpp]\fP"
.IX Subsection "--xsubpp[=/path/to/xsubpp]"
If specified, \s-1XS++\s0 will run \fIxsubpp\fR after processing the \s-1XS++\s0 input
file.  If the path to \fIxsubpp\fR is not specified, \fIxspp\fR expects to
find it in the system \s-1PATH\s0.
.ie n .SS """\-\-xsubpp\-args=""extra xsubpp args"""""
.el .SS "\f(CW\-\-xsubpp\-args=``extra xsubpp args''\fP"
.IX Subsection "--xsubpp-args=""extra xsubpp args"""
Can be used to pass additional command line arguments to \fIxsubpp\fR.
.SH "TYPEMAPS"
.IX Header "TYPEMAPS"
There is nothing special about typemap files (i.e. you can put typemaps
directly in your .xsp file), but it is handy to have common typemaps in a
separate file, to avoid duplication.
.PP
.Vb 1
\&  %typemap{<C++ type>}{simple};
.Ve
.PP
Just let \s-1XS++\s0 know that this is a valid type, the type will be passed
unchanged to \s-1XS\s0 code \fBexcept\fR that any \f(CW\*(C`const\*(C'\fR qualifiers will be
stripped.
.PP
.Vb 1
\&  %typemap{<C++ reference type>}{reference};
.Ve
.PP
Handle \*(C+ references: the \s-1XS\s0 variable will be declared as a pointer,
and it will be explicitly dereferenced in the function call. If it is
used in the return value, the function will create \fBcopy\fR of the
returned value using a copy constructor.
.PP
As a shortcut for the common case of declaring both of the above
for a given type, you may use
.PP
.Vb 1
\&  %typemap{<C++ type>};
.Ve
.PP
Which has the same effect as:
.PP
.Vb 2
\&  %typemap{<C++ type>}{simple};
\&  %typemap{<C++ type>&}{reference};
.Ve
.PP
For more control over the type mapping, you can use the \f(CW\*(C`parsed\*(C'\fR
variant as follows.
.PP
.Vb 1
\&  %typemap{<C++ type 1>}{parsed}{%<C++ type 2>%};
.Ve
.PP
When \f(CW\*(C`C++ type 1\*(C'\fR is used, replace it with \f(CW\*(C`C++ type 2\*(C'\fR in the
generated \s-1XS\s0 code.
.PP
.Vb 5
\&  %typemap{<C++ type>}{parsed}{
\&      %cpp_type{%<C++ type 2>%};
\&      %call_function_code{% $CVar = new Foo( $Call ) %};
\&      %cleanup_code{% ... %};
\&      %precall_code{% ... %};
\&
\&      # use only one of the following
\&      %output_code{% $PerlVar = newSViv( $CVar ) %};
\&      %output_list{% PUTBACK; XPUSHi( $CVar ); SPAGAIN %};
\&  };
.Ve
.PP
Is a more flexible form for the \f(CW\*(C`parsed\*(C'\fR typemap.  All the parameters
are optional.
.IP "cpp_type" 4
.IX Item "cpp_type"
Specifies the \*(C+ type used for the variable declaration in the
generated \s-1XS\s0 code.
.Sp
If not specified defaults to the type specified in the typemap.
.IP "call_function_code" 4
.IX Item "call_function_code"
Used when the typemap applies to the return value of the function.
.Sp
Specifies the code to use in the function call.  The special variables
\&\f(CW$Call\fR and \f(CW$CVar\fR are replaced with the actual call code and the name of
the \*(C+ return variable.
.IP "output_code" 4
.IX Item "output_code"
Used when the typemap applies to the return value of the function.
See also \f(CW%output_list\fR.
.Sp
Specifies the code emitted right after the function call to convert
the \*(C+ return value into a Perl return value.  The special variable
\&\f(CW$CVar\fR is replaced with the \*(C+ return variable name.
.IP "cleanup_code" 4
.IX Item "cleanup_code"
Used when the typemap applies to the return value of the function.
.Sp
Specifies some code emitted after output value processing.  The
special variables \f(CW$PerlVar\fR and \f(CW$CVar\fR are replaced with the names of the
\&\*(C+ variables containing the Perl scalar and the corresponding \*(C+
value.
.IP "precall_code" 4
.IX Item "precall_code"
Used when the typemap applies to a parameter.
.Sp
Specifies some code emitted after argument processing and before
calling the \*(C+ method.  The special variables \f(CW$PerlVar\fR and \f(CW$CVar\fR are
replaced with the names of the \*(C+ variables containing the Perl
scalar and the corresponding \*(C+ value.
.IP "output_list" 4
.IX Item "output_list"
Used when the typemap applies to the return value of the function, as
an alternative to \f(CW%output_code\fR.
.Sp
Specifies some code that manipulates the Perl stack directly in order
to return a list.  The special variable \f(CW$CVar\fR is replaced with the \*(C+
name of the output variable.
.Sp
The code must use \s-1PUTBACK/SPAGAIN\s0 if appropriate.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Anything that does not look like a \s-1XS++\s0 directive or a class
declaration is passed verbatim to \s-1XS\s0. If you want \s-1XS++\s0 to ignore code
that looks like a \s-1XS++\s0 directive or class declaration, simply surround it with
a raw block delimiter like this:
.PP
.Vb 3
\&  %{
\&  XS++ won\*(Aqt interpret this
\&  %}
.Ve
.ie n .SS "%code"
.el .SS "\f(CW%code\fP"
.IX Subsection "%code"
See under \fBClasses\fR. Note that custom \f(CW%code\fR blocks are the only
exception to the exception handling. By specifying a custom \f(CW%code\fR
block, you forgo the automatic exception handlers.
.ie n .SS "%file"
.el .SS "\f(CW%file\fP"
.IX Subsection "%file"
.Vb 5
\&  %file{file/path.h};
\&  ...
\&  %file{file/path2};
\&  ...
\&  %file{\-}
.Ve
.PP
By default \s-1XS++\s0 output goes to standard output; to change this, use the
\&\f(CW%file\fR directive; use \f(CW\*(C`\-\*(C'\fR for standard output.
.ie n .SS "%module"
.el .SS "\f(CW%module\fP"
.IX Subsection "%module"
.Vb 1
\&  %module{Module::Name};
.Ve
.PP
Will be used to generate the \f(CW\*(C`MODULE=Module::Name\*(C'\fR \s-1XS\s0 directives.
It indirectly sets the name of the shared library that is generated
as well as the name of the module via which XSLoader will be
able to find/load it.
.ie n .SS "%name"
.el .SS "\f(CW%name\fP"
.IX Subsection "%name"
.Vb 2
\&  %name{Perl::Class} class MyClass { ... };
\&  %name{Perl::Func} int foo();
.Ve
.PP
Specifies the Perl name under which the \*(C+ class/function will be
accessible. By default, constructor names are mapped to \f(CW\*(C`new\*(C'\fR in Perl.
.ie n .SS "%typemap"
.el .SS "\f(CW%typemap\fP"
.IX Subsection "%typemap"
See \fB\s-1TYPEMAPS\s0\fR above.
.ie n .SS "%length"
.el .SS "\f(CW%length\fP"
.IX Subsection "%length"
When you need to pass a string from Perl to an \s-1XSUB\s0 that
takes the C string and its length as arguments,
you may have \s-1XS++\s0 pass the length of the string automatically.
For example, if you declare a method as follows,
.PP
.Vb 1
\&  void PrintLine( char* line, unsigned int %length{line} );
.Ve
.PP
you can call the method from Perl like this:
.PP
.Vb 1
\&  $object\->PrintLine( $string );
.Ve
.PP
This feature is also present in plain \s-1XS\s0. See also: perlxs.
.PP
If you use \f(CW\*(C`%length(line)\*(C'\fR in conjunction with any kind of
special code block such as \f(CW%code\fR, \f(CW%postcall\fR, etc.,
then you can refer to the length of the string
(here: \f(CW\*(C`line\*(C'\fR) \fIefficiently\fR as \f(CW\*(C`length(line)\*(C'\fR in the code.
.SS "Classes"
.IX Subsection "Classes"
.Vb 6
\&  %name{My::Class} class MyClass : public %name{My::Base} MyBase
\&  {
\&      // can be called in Perl as My::Class\->new( ... );
\&      MyClass( int arg );
\&      // My::Class\->newMyClass( ... );
\&      %name{newMyClass} MyClass( const char* str, int arg );
\&
\&      // standard DESTROY method
\&      ~MyClass();
\&
\&      int GetInt();
\&      void SetValue( int arg = \-1 );
\&
\&      %name{SetString} void SetValue( const char* string = NULL );
\&
\&      // Supply a C<CODE:> or C<CLEANUP:> block for the XS
\&      int MyMethod( int a, int b )
\&          %code{% RETVAL = a + b; %}
\&          %cleanup{% /* do something */ %};
\&  };
.Ve
.SS "Comments"
.IX Subsection "Comments"
\&\s-1XS++\s0 recognizes both C\-style comments \f(CW\*(C`/* ... */\*(C'\fR and \*(C+\-style
comments \f(CW\*(C`// ...\*(C'\fR.  Comments are removed from the \s-1XS\s0 output.
.SS "Exceptions"
.IX Subsection "Exceptions"
\&\*(C+ Exceptions are always caught and transformed to Perl \f(CW\*(C`croak()\*(C'\fR
calls. If the exception that was caught inherited from \f(CW\*(C`std::exception\*(C'\fR,
then the \f(CW\*(C`what()\*(C'\fR message is included in the Perl-level error message.
All other exceptions will result in the \f(CW\*(C`croak()\*(C'\fR message
\&\f(CW"Caught unhandled C++ exception of unknown type"\fR.
.PP
Note that if you supply a custom \f(CW%code\fR block for a function or method,
the automatic exception handling is turned off.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
The distribution contains an \fIexamples\fR directory. The
\&\fIexamples/XSpp\-Example\fR directory therein demonstrates
a particularly simple way of getting started with \s-1XS++\s0.
.SH "AUTHOR"
.IX Header "AUTHOR"
Mattia Barbon <mbarbon@cpan.org>
.SH "LICENSE"
.IX Header "LICENSE"
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.