| 1 |
NAME |
| 2 |
ExtUtils::XSpp - XS for C++ |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
xspp [--typemap=typemap.xsp [--typemap=typemap2.xsp]] |
| 6 |
[--xsubpp[=/path/to/xsubpp] [--xsubpp-args="xsubpp args"] |
| 7 |
Foo.xsp |
| 8 |
|
| 9 |
or |
| 10 |
|
| 11 |
perl -MExtUtils::XSpp::Cmd -e xspp -- <xspp options and arguments> |
| 12 |
|
| 13 |
In Foo.xs |
| 14 |
|
| 15 |
INCLUDE_COMMAND: $^X -MExtUtils::XSpp::Cmd -e xspp -- <xspp options/arguments> |
| 16 |
|
| 17 |
Using "ExtUtils::XSpp::Cmd" is equivalent to using the "xspp" command |
| 18 |
line script, except that there is no guarantee for "xspp" to be |
| 19 |
installed in the system PATH. |
| 20 |
|
| 21 |
OVERVIEW |
| 22 |
XS++ is just a thin layer over plain XS, hence to use it you are |
| 23 |
supposed to know, at the very least, C++ and XS. |
| 24 |
|
| 25 |
This means that you will need typemaps for both the normal XS |
| 26 |
pre-processor *xsubpp* and the XS++ pre-processor *xspp*. |
| 27 |
|
| 28 |
COMMAND LINE |
| 29 |
"--typemap=/path/to/typemap.xsp" |
| 30 |
Can be specified multiple times to process additional typemap files |
| 31 |
before the main XS++ input files. Typemap files are processed the same |
| 32 |
way as regular XS++ files, except that output code is discarded. |
| 33 |
|
| 34 |
"--xsubpp[=/path/to/xsubpp]" |
| 35 |
If specified, XS++ will run xsubpp after processing the XS++ input file. |
| 36 |
If the path to xsubpp is not specified, xspp expects to find it in the |
| 37 |
system PATH. |
| 38 |
|
| 39 |
"--xsubpp-args="extra xsubpp args"" |
| 40 |
Can be used to pass additional command line arguments to xsubpp. |
| 41 |
|
| 42 |
TYPEMAPS |
| 43 |
There is nothing special about typemap files (i.e. you can put typemaps |
| 44 |
directly in your .xsp file), but it is handy to have common typemaps in |
| 45 |
a separate file, to avoid duplication. |
| 46 |
|
| 47 |
%typemap{<C++ type>}{simple}; |
| 48 |
|
| 49 |
Just let XS++ know that this is a valid type, the type will be passed |
| 50 |
unchanged to XS code except that any "const" qualifiers will be |
| 51 |
stripped. |
| 52 |
|
| 53 |
%typemap{<C++ reference type>}{reference}; |
| 54 |
|
| 55 |
Handle C++ references: the XS variable will be declared as a pointer, |
| 56 |
and it will be explicitly dereferenced in the function call. If it is |
| 57 |
used in the return value, the function will create copy of the returned |
| 58 |
value using a copy constructor. |
| 59 |
|
| 60 |
As a shortcut for the common case of declaring both of the above for a |
| 61 |
given type, you may use |
| 62 |
|
| 63 |
%typemap{<C++ type>}; |
| 64 |
|
| 65 |
Which has the same effect as: |
| 66 |
|
| 67 |
%typemap{<C++ type>}{simple}; |
| 68 |
%typemap{<C++ type>&}{reference}; |
| 69 |
|
| 70 |
For more control over the type mapping, you can use the "parsed" variant |
| 71 |
as follows. |
| 72 |
|
| 73 |
%typemap{<C++ type 1>}{parsed}{%<C++ type 2>%}; |
| 74 |
|
| 75 |
When "C++ type 1" is used, replace it with "C++ type 2" in the generated |
| 76 |
XS code. |
| 77 |
|
| 78 |
%typemap{<C++ type>}{parsed}{ |
| 79 |
%cpp_type{%<C++ type 2>%}; |
| 80 |
%call_function_code{% $CVar = new Foo( $Call ) %}; |
| 81 |
%cleanup_code{% ... %}; |
| 82 |
%precall_code{% ... %}; |
| 83 |
|
| 84 |
# use only one of the following |
| 85 |
%output_code{% $PerlVar = newSViv( $CVar ) %}; |
| 86 |
%output_list{% PUTBACK; XPUSHi( $CVar ); SPAGAIN %}; |
| 87 |
}; |
| 88 |
|
| 89 |
Is a more flexible form for the "parsed" typemap. All the parameters are |
| 90 |
optional. |
| 91 |
|
| 92 |
cpp_type |
| 93 |
Specifies the C++ type used for the variable declaration in the |
| 94 |
generated XS code. |
| 95 |
|
| 96 |
If not specified defaults to the type specified in the typemap. |
| 97 |
|
| 98 |
call_function_code |
| 99 |
Used when the typemap applies to the return value of the function. |
| 100 |
|
| 101 |
Specifies the code to use in the function call. The special |
| 102 |
variables $Call and $CVar are replaced with the actual call code and |
| 103 |
the name of the C++ return variable. |
| 104 |
|
| 105 |
output_code |
| 106 |
Used when the typemap applies to the return value of the function. |
| 107 |
See also %output_list. |
| 108 |
|
| 109 |
Specifies the code emitted right after the function call to convert |
| 110 |
the C++ return value into a Perl return value. The special variable |
| 111 |
$CVar is replaced with the C++ return variable name. |
| 112 |
|
| 113 |
cleanup_code |
| 114 |
Used when the typemap applies to the return value of the function. |
| 115 |
|
| 116 |
Specifies some code emitted after output value processing. The |
| 117 |
special variables $PerlVar and $CVar are replaced with the names of |
| 118 |
the C++ variables containing the Perl scalar and the corresponding |
| 119 |
C++ value. |
| 120 |
|
| 121 |
precall_code |
| 122 |
Used when the typemap applies to a parameter. |
| 123 |
|
| 124 |
Specifies some code emitted after argument processing and before |
| 125 |
calling the C++ method. The special variables $PerlVar and $CVar are |
| 126 |
replaced with the names of the C++ variables containing the Perl |
| 127 |
scalar and the corresponding C++ value. |
| 128 |
|
| 129 |
output_list |
| 130 |
Used when the typemap applies to the return value of the function, |
| 131 |
as an alternative to %output_code. |
| 132 |
|
| 133 |
Specifies some code that manipulates the Perl stack directly in |
| 134 |
order to return a list. The special variable $CVar is replaced with |
| 135 |
the C++ name of the output variable. |
| 136 |
|
| 137 |
The code must use PUTBACK/SPAGAIN if appropriate. |
| 138 |
|
| 139 |
DESCRIPTION |
| 140 |
Anything that does not look like a XS++ directive or a class declaration |
| 141 |
is passed verbatim to XS. If you want XS++ to ignore code that looks |
| 142 |
like a XS++ directive or class declaration, simply surround it with a |
| 143 |
raw block delimiter like this: |
| 144 |
|
| 145 |
%{ |
| 146 |
XS++ won't interpret this |
| 147 |
%} |
| 148 |
|
| 149 |
%code |
| 150 |
See under Classes. Note that custom %code blocks are the only exception |
| 151 |
to the exception handling. By specifying a custom %code block, you forgo |
| 152 |
the automatic exception handlers. |
| 153 |
|
| 154 |
%file |
| 155 |
%file{file/path.h}; |
| 156 |
... |
| 157 |
%file{file/path2}; |
| 158 |
... |
| 159 |
%file{-} |
| 160 |
|
| 161 |
By default XS++ output goes to standard output; to change this, use the |
| 162 |
%file directive; use "-" for standard output. |
| 163 |
|
| 164 |
%module |
| 165 |
%module{Module::Name}; |
| 166 |
|
| 167 |
Will be used to generate the "MODULE=Module::Name" XS directives. It |
| 168 |
indirectly sets the name of the shared library that is generated as well |
| 169 |
as the name of the module via which XSLoader will be able to find/load |
| 170 |
it. |
| 171 |
|
| 172 |
%name |
| 173 |
%name{Perl::Class} class MyClass { ... }; |
| 174 |
%name{Perl::Func} int foo(); |
| 175 |
|
| 176 |
Specifies the Perl name under which the C++ class/function will be |
| 177 |
accessible. By default, constructor names are mapped to "new" in Perl. |
| 178 |
|
| 179 |
%typemap |
| 180 |
See TYPEMAPS above. |
| 181 |
|
| 182 |
%length |
| 183 |
When you need to pass a string from Perl to an XSUB that takes the C |
| 184 |
string and its length as arguments, you may have XS++ pass the length of |
| 185 |
the string automatically. For example, if you declare a method as |
| 186 |
follows, |
| 187 |
|
| 188 |
void PrintLine( char* line, unsigned int %length{line} ); |
| 189 |
|
| 190 |
you can call the method from Perl like this: |
| 191 |
|
| 192 |
$object->PrintLine( $string ); |
| 193 |
|
| 194 |
This feature is also present in plain XS. See also: perlxs. |
| 195 |
|
| 196 |
If you use "%length(line)" in conjunction with any kind of special code |
| 197 |
block such as %code, %postcall, etc., then you can refer to the length |
| 198 |
of the string (here: "line") *efficiently* as "length(line)" in the |
| 199 |
code. |
| 200 |
|
| 201 |
%alias |
| 202 |
Decorator for function/method declarations such as |
| 203 |
|
| 204 |
double add(double a, double b) |
| 205 |
%alias{subtract = 1} %alias{multiply = 2}; |
| 206 |
|
| 207 |
Which will cause the generation of just a single XSUB using the XS |
| 208 |
"ALIAS" feature (see perlxs). It will be installed as all of "add", |
| 209 |
"subtract", and "multiply" on the Perl side and call either the C++ |
| 210 |
"add", "subtract", or "multiply" functions depending on which way it was |
| 211 |
called. |
| 212 |
|
| 213 |
Notes: If used in conjunction with %name{foo} to rename the function, |
| 214 |
then the %name will only affect the main function name (in the above |
| 215 |
example, "add" but not "subtract" or "multiply"). When used with the |
| 216 |
%code feature, the custom code will have to use the "ix" integer |
| 217 |
variable to decide which function to call. "ix" is set to 0 for the main |
| 218 |
function. Make sure to read up on the ALIAS feature of plain XS. |
| 219 |
Aliasing is not supported for constructors and destructors. |
| 220 |
|
| 221 |
Classes |
| 222 |
%name{My::Class} class MyClass : public %name{My::Base} MyBase |
| 223 |
{ |
| 224 |
// can be called in Perl as My::Class->new( ... ); |
| 225 |
MyClass( int arg ); |
| 226 |
// My::Class->newMyClass( ... ); |
| 227 |
%name{newMyClass} MyClass( const char* str, int arg ); |
| 228 |
|
| 229 |
// standard DESTROY method |
| 230 |
~MyClass(); |
| 231 |
|
| 232 |
int GetInt(); |
| 233 |
void SetValue( int arg = -1 ); |
| 234 |
|
| 235 |
%name{SetString} void SetValue( const char* string = NULL ); |
| 236 |
|
| 237 |
// Supply a C<CODE:> or C<CLEANUP:> block for the XS |
| 238 |
int MyMethod( int a, int b ) |
| 239 |
%code{% RETVAL = a + b; %} |
| 240 |
%cleanup{% /* do something */ %}; |
| 241 |
|
| 242 |
// Expose class method as My::ClassMethod::ClassMethod($foo) |
| 243 |
static void ClassMethod( double foo ); |
| 244 |
}; |
| 245 |
|
| 246 |
Comments |
| 247 |
XS++ recognizes both C-style comments "/* ... */" and C++-style comments |
| 248 |
"// ...". Comments are removed from the XS output. |
| 249 |
|
| 250 |
Exceptions |
| 251 |
C++ Exceptions are always caught and transformed to Perl "croak()" |
| 252 |
calls. If the exception that was caught inherited from "std::exception", |
| 253 |
then the "what()" message is included in the Perl-level error message. |
| 254 |
All other exceptions will result in the "croak()" message "Caught |
| 255 |
unhandled C++ exception of unknown type". |
| 256 |
|
| 257 |
Note that if you supply a custom %code block for a function or method, |
| 258 |
the automatic exception handling is turned off. |
| 259 |
|
| 260 |
EXAMPLES |
| 261 |
The distribution contains an examples directory. The |
| 262 |
examples/XSpp-Example directory therein demonstrates a particularly |
| 263 |
simple way of getting started with XS++. |
| 264 |
|
| 265 |
AUTHOR |
| 266 |
Mattia Barbon <[email protected]> |
| 267 |
|
| 268 |
LICENSE |
| 269 |
This program is free software; you can redistribute it and/or modify it |
| 270 |
under the same terms as Perl itself. |
| 271 |
|