.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" 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 .\" .\" 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 "2020-12-29" "perl v5.32.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" 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 \-\- .Ve .PP In Foo.xs .PP .Vb 1 \& INCLUDE_COMMAND: $^X \-MExtUtils::XSpp::Cmd \-e xspp \-\- .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 may need typemaps for \fBboth\fR the normal \s-1XS\s0 pre-processor \fIxsubpp\fR and the \s-1XS++\s0 pre-processor \fIxspp\fR. More on that in the \fI\s-1TYPEMAPS\s0\fR section below. .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" .SS "Ordinary \s-1XS\s0 typemaps" .IX Subsection "Ordinary XS typemaps" To recap, \fIordinary\fR \s-1XS\s0 typemaps do the following three things: .IP "\(bu" 2 Associate a C type with an identifier such as T_FOO or O_FOO (which we'll call \fI\s-1XS\s0 type\fR here). .IP "\(bu" 2 Define an \s-1INPUT\s0 mapping for converting a Perl data structure to the aforementioned C type. .IP "\(bu" 2 Define an \s-1OUTPUT\s0 mapping for converting the C data structure back into a Perl data structure. .PP These are still required in the context of \s-1XS++.\s0 There are some helpers to take away the tedium, but I'll get to that later. For \s-1XS++,\s0 there's another layer of typemaps. The following section will discuss those. .SS "\s-1XS++\s0 typemaps" .IX Subsection "XS++ typemaps" There is nothing special about \s-1XS++\s0 typemap files (i.e. you can put typemaps directly in your \fI.xsp\fR file), but it is handy to have common typemaps in a separate file, typically called \fItypemap.xsp\fR to avoid duplication. .PP .Vb 1 \& %typemap{}{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{}{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{}; .Ve .PP Which has the same effect as: .PP .Vb 2 \& %typemap{}{simple}; \& %typemap{&}{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{}{parsed}{%%}; .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{}{parsed}{ \& %cpp_type{%%}; \& %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. .SS "Putting all the typemaps together" .IX Subsection "Putting all the typemaps together" In summary, the \s-1XS++\s0 typemaps (optionally) give you much more control over the type conversion code that's generated for your XSUBs. But you still need to let the \s-1XS\s0 compiler know how to map the C types to Perl and back using the \s-1XS\s0 typemaps. .PP Most of the time, you just need to convert basic C(++) types or the types that you define with your \*(C+ classes. For the former, \s-1XS++\s0 comes with a few default mappings for booleans, integers, floating point numbers, and strings. For classes, \s-1XS++\s0 can automatically create a mapping of type \f(CW\*(C`O_OBJECT\*(C'\fR which uses the de-facto standard way of storing a pointer to the C(++) object in the \s-1IV\s0 slot of a referenced/blessed scalar. Due to backwards compatibility, this must be explicitly enabled by adding .PP .Vb 1 \& %loadplugin{feature::default_xs_typemap}; .Ve .PP in \fItypemap.xsp\fR (or near the top of every \fI.xsp\fR file). .PP If you deal with any other types as arguments or return types, you still need to write both \&\s-1XS\s0 and \s-1XS++\s0 typemaps for these so that the systems know how to deal with them. .PP See either \*(L"Custom \s-1XS\s0 typemaps\*(R" below for a way to specify \s-1XS\s0 typemaps from \&\s-1XS++\s0 or perlxs for a discussion of inline \s-1XS\s0 typemaps that don't require the traditional \s-1XS\s0 \fItypemap\fR file. .SS "Custom \s-1XS\s0 typemaps" .IX Subsection "Custom XS typemaps" \&\s-1XS++\s0 provides a default mapping for object types to an \f(CW\*(C`O_OBJECT\*(C'\fR typemap with standard input and output glue code, which should be adequate for most uses. .PP There are multiple ways to override this default when needed. .PP .Vb 5 \& %typemap{Foo *}{simple}{ \& %xs_type{O_MYMAP}; \& %xs_input_code{% ... %}; // optional \& %xs_output_code{% ... %}; // optional \& }; .Ve .PP can be used to define a new type \-> \s-1XS\s0 typemap mapping, with optinal input/output code. Since \s-1XS\s0 typemap definitions are global, \s-1XS\s0 input/output code applies to all types with the same \f(CW%xs_type\fR, hence there is no need to repeat it. .PP .Vb 6 \& %typemap{_}{simple}{ \& %name{object}; \& %xs_type{O_MYMAP}; \& %xs_input_code{% ... %}; // optional \& %xs_output_code{% ... %}; // optional \& }; .Ve .PP can be used to change the default typemap used for all classes. .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 \*(L"\s-1TYPEMAPS\*(R"\s0 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. .ie n .SS "%alias" .el .SS "\f(CW%alias\fP" .IX Subsection "%alias" Decorator for function/method declarations such as .PP .Vb 2 \& double add(double a, double b) \& %alias{subtract = 1} %alias{multiply = 2}; .Ve .PP Which will cause the generation of just a single \s-1XSUB\s0 using the \&\s-1XS \*(L"ALIAS\*(R"\s0 feature (see perlxs). It will be installed as all of \&\f(CW\*(C`add\*(C'\fR, \f(CW\*(C`subtract\*(C'\fR, and \f(CW\*(C`multiply\*(C'\fR on the Perl side and call either the \*(C+ \f(CW\*(C`add\*(C'\fR, \f(CW\*(C`subtract\*(C'\fR, or \f(CW\*(C`multiply\*(C'\fR functions depending on which way it was called. .PP Notes: If used in conjunction with \f(CW%name{foo}\fR to rename the function, then the \f(CW%name\fR will only affect the main function name (in the above example, \f(CW\*(C`add\*(C'\fR but not \f(CW\*(C`subtract\*(C'\fR or \f(CW\*(C`multiply\*(C'\fR). When used with the \f(CW%code\fR feature, the custom code will have to use the \f(CW\*(C`ix\*(C'\fR integer variable to decide which function to call. \&\f(CW\*(C`ix\*(C'\fR is set to 0 for the main function. Make sure to read up on the \s-1ALIAS\s0 feature of plain \s-1XS.\s0 Aliasing is not supported for constructors and destructors. .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 or C block for the XS \& int MyMethod( int a, int b ) \& %code{% RETVAL = a + b; %} \& %cleanup{% /* do something */ %}; \& \& // Expose class method as My::ClassMethod::ClassMethod($foo) \& static void ClassMethod( double foo ); \& \& // Expose member variable as a pair of set_boolean/get_boolean accessors \& bool boolean %get %set; \& }; .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. .SS "Member variables" .IX Subsection "Member variables" By default, member variable declarations are ignored; the \f(CW%get\fR and \&\f(CW%set\fR decorators syntehsize a getter/setter named after the member variable (can be renamed using \f(CW%name\fR). .PP \&\s-1XS++\s0 defaults to get_/set_ prefix for getters/setters. This can be overridden on an individual basis by using e.g. .PP .Vb 1 \& int foo %get{readFoo} %set{writeFoo}; .Ve .PP As an alternative, the class-level \f(CW%accessors\fR decorator sets the the accessor style for the whole class: .PP .Vb 4 \& %accessors{ \& %get_style{no_prefix}; \& %set_style{camelcase}; \& }; .Ve .PP Available styles are .IP "no_prefix => foo" 4 .IX Item "no_prefix => foo" .PD 0 .IP "underscore => get_foo, set_foo" 4 .IX Item "underscore => get_foo, set_foo" .IP "camelcase => getFoo, setFoo" 4 .IX Item "camelcase => getFoo, setFoo" .IP "uppercase => GetFoo, SetFoo" 4 .IX Item "uppercase => GetFoo, SetFoo" .PD .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 .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.