1ExtUtils::XSpp(3pm) User Contributed Perl Documentation ExtUtils::XSpp(3pm)
2
6 ExtUtils::XSpp - XS for C++
7
9 xspp [--typemap=typemap.xsp [--typemap=typemap2.xsp]]
10 [--xsubpp[=/path/to/xsubpp] [--xsubpp-args="xsubpp args"]
11 Foo.xsp
12 or
14 perl -MExtUtils::XSpp::Cmd -e xspp -- <xspp options and arguments>
16 In Foo.xs
18 INCLUDE_COMMAND: $^X -MExtUtils::XSpp::Cmd -e xspp -- <xspp options/arguments>
20 Using "ExtUtils::XSpp::Cmd" is equivalent to using the "xspp" command
22 line script, except that there is no guarantee for "xspp" to be
23 installed in the system PATH.
24
26 XS++ is just a thin layer over plain XS, hence to use it you are
27 supposed to know, at the very least, C++ and XS.
28 This means that you may need typemaps for both the normal XS pre-
30 processor xsubpp and the XS++ pre-processor xspp. More on that in the
31 TYPEMAPS section below.
32
34 "--typemap=/path/to/typemap.xsp"
35 Can be specified multiple times to process additional typemap files
36 before the main XS++ input files. Typemap files are processed the same
37 way as regular XS++ files, except that output code is discarded.
38 "--xsubpp[=/path/to/xsubpp]"
40 If specified, XS++ will run xsubpp after processing the XS++ input
41 file. If the path to xsubpp is not specified, xspp expects to find it
42 in the system PATH.
43 "--xsubpp-args="extra xsubpp args""
45 Can be used to pass additional command line arguments to xsubpp.
46
48 Ordinary XS typemaps
49 To recap, ordinary XS typemaps do the following three things:
50 • Associate a C type with an identifier such as T_FOO or O_FOO (which
52 we'll call XS type here).
53 • Define an INPUT mapping for converting a Perl data structure to the
55 aforementioned C type.
56 • Define an OUTPUT mapping for converting the C data structure back
58 into a Perl data structure.
59 These are still required in the context of XS++. There are some helpers
61 to take away the tedium, but I'll get to that later. For XS++, there's
62 another layer of typemaps. The following section will discuss those.
63 XS++ typemaps
65 There is nothing special about XS++ typemap files (i.e. you can put
66 typemaps directly in your .xsp file), but it is handy to have common
67 typemaps in a separate file, typically called typemap.xsp to avoid
68 duplication.
69 %typemap{<C++ type>}{simple};
71 Just let XS++ know that this is a valid type, the type will be passed
73 unchanged to XS code except that any "const" qualifiers will be
74 stripped.
75 %typemap{<C++ reference type>}{reference};
77 Handle C++ references: the XS variable will be declared as a pointer,
79 and it will be explicitly dereferenced in the function call. If it is
80 used in the return value, the function will create copy of the returned
81 value using a copy constructor.
82 As a shortcut for the common case of declaring both of the above for a
84 given type, you may use
85 %typemap{<C++ type>};
87 Which has the same effect as:
89 %typemap{<C++ type>}{simple};
91 %typemap{<C++ type>&}{reference};
92 For more control over the type mapping, you can use the "parsed"
94 variant as follows.
95 %typemap{<C++ type 1>}{parsed}{%<C++ type 2>%};
97 When "C++ type 1" is used, replace it with "C++ type 2" in the
99 generated XS code.
100 %typemap{<C++ type>}{parsed}{
102 %cpp_type{%<C++ type 2>%};
103 %call_function_code{% $CVar = new Foo( $Call ) %};
104 %cleanup_code{% ... %};
105 %precall_code{% ... %};
106 # use only one of the following
108 %output_code{% $PerlVar = newSViv( $CVar ) %};
109 %output_list{% PUTBACK; XPUSHi( $CVar ); SPAGAIN %};
110 };
111 Is a more flexible form for the "parsed" typemap. All the parameters
113 are optional.
114 cpp_type
116 Specifies the C++ type used for the variable declaration in the
117 generated XS code.
118 If not specified defaults to the type specified in the typemap.
120 call_function_code
122 Used when the typemap applies to the return value of the function.
123 Specifies the code to use in the function call. The special
125 variables $Call and $CVar are replaced with the actual call code
126 and the name of the C++ return variable.
127 output_code
129 Used when the typemap applies to the return value of the function.
130 See also %output_list.
131 Specifies the code emitted right after the function call to convert
133 the C++ return value into a Perl return value. The special
134 variable $CVar is replaced with the C++ return variable name.
135 cleanup_code
137 Used when the typemap applies to the return value of the function.
138 Specifies some code emitted after output value processing. The
140 special variables $PerlVar and $CVar are replaced with the names of
141 the C++ variables containing the Perl scalar and the corresponding
142 C++ value.
143 precall_code
145 Used when the typemap applies to a parameter.
146 Specifies some code emitted after argument processing and before
148 calling the C++ method. The special variables $PerlVar and $CVar
149 are replaced with the names of the C++ variables containing the
150 Perl scalar and the corresponding C++ value.
151 output_list
153 Used when the typemap applies to the return value of the function,
154 as an alternative to %output_code.
155 Specifies some code that manipulates the Perl stack directly in
157 order to return a list. The special variable $CVar is replaced
158 with the C++ name of the output variable.
159 The code must use PUTBACK/SPAGAIN if appropriate.
161 Putting all the typemaps together
163 In summary, the XS++ typemaps (optionally) give you much more control
164 over the type conversion code that's generated for your XSUBs. But you
165 still need to let the XS compiler know how to map the C types to Perl
166 and back using the XS typemaps.
167 Most of the time, you just need to convert basic C(++) types or the
169 types that you define with your C++ classes. For the former, XS++ comes
170 with a few default mappings for booleans, integers, floating point
171 numbers, and strings. For classes, XS++ can automatically create a
172 mapping of type "O_OBJECT" which uses the de-facto standard way of
173 storing a pointer to the C(++) object in the IV slot of a
174 referenced/blessed scalar. Due to backwards compatibility, this must be
175 explicitly enabled by adding
176 %loadplugin{feature::default_xs_typemap};
178 in typemap.xsp (or near the top of every .xsp file).
180 If you deal with any other types as arguments or return types, you
182 still need to write both XS and XS++ typemaps for these so that the
183 systems know how to deal with them.
184 See either "Custom XS typemaps" below for a way to specify XS typemaps
186 from XS++ or perlxs for a discussion of inline XS typemaps that don't
187 require the traditional XS typemap file.
188 Custom XS typemaps
190 XS++ provides a default mapping for object types to an "O_OBJECT"
191 typemap with standard input and output glue code, which should be
192 adequate for most uses.
193 There are multiple ways to override this default when needed.
195 %typemap{Foo *}{simple}{
197 %xs_type{O_MYMAP};
198 %xs_input_code{% ... %}; // optional
199 %xs_output_code{% ... %}; // optional
200 };
201 can be used to define a new type -> XS typemap mapping, with optinal
203 input/output code. Since XS typemap definitions are global, XS
204 input/output code applies to all types with the same %xs_type, hence
205 there is no need to repeat it.
206 %typemap{_}{simple}{
208 %name{object};
209 %xs_type{O_MYMAP};
210 %xs_input_code{% ... %}; // optional
211 %xs_output_code{% ... %}; // optional
212 };
213 can be used to change the default typemap used for all classes.
215
217 Anything that does not look like a XS++ directive or a class
218 declaration is passed verbatim to XS. If you want XS++ to ignore code
219 that looks like a XS++ directive or class declaration, simply surround
220 it with a raw block delimiter like this:
221 %{
223 XS++ won't interpret this
224 %}
225 %code
227 See under Classes. Note that custom %code blocks are the only exception
228 to the exception handling. By specifying a custom %code block, you
229 forgo the automatic exception handlers.
230 %file
232 %file{file/path.h};
233 ...
234 %file{file/path2};
235 ...
236 %file{-}
237 By default XS++ output goes to standard output; to change this, use the
239 %file directive; use "-" for standard output.
240 %module
242 %module{Module::Name};
243 Will be used to generate the "MODULE=Module::Name" XS directives. It
245 indirectly sets the name of the shared library that is generated as
246 well as the name of the module via which XSLoader will be able to
247 find/load it.
248 %name
250 %name{Perl::Class} class MyClass { ... };
251 %name{Perl::Func} int foo();
252 Specifies the Perl name under which the C++ class/function will be
254 accessible. By default, constructor names are mapped to "new" in Perl.
255 %typemap
257 See "TYPEMAPS" above.
258 %length
260 When you need to pass a string from Perl to an XSUB that takes the C
261 string and its length as arguments, you may have XS++ pass the length
262 of the string automatically. For example, if you declare a method as
263 follows,
264 void PrintLine( char* line, unsigned int %length{line} );
266 you can call the method from Perl like this:
268 $object->PrintLine( $string );
270 This feature is also present in plain XS. See also: perlxs.
272 If you use %length(line) in conjunction with any kind of special code
274 block such as %code, %postcall, etc., then you can refer to the length
275 of the string (here: "line") efficiently as length(line) in the code.
276 %alias
278 Decorator for function/method declarations such as
279 double add(double a, double b)
281 %alias{subtract = 1} %alias{multiply = 2};
282 Which will cause the generation of just a single XSUB using the XS
284 "ALIAS" feature (see perlxs). It will be installed as all of "add",
285 "subtract", and "multiply" on the Perl side and call either the C++
286 "add", "subtract", or "multiply" functions depending on which way it
287 was called.
288 Notes: If used in conjunction with %name{foo} to rename the function,
290 then the %name will only affect the main function name (in the above
291 example, "add" but not "subtract" or "multiply"). When used with the
292 %code feature, the custom code will have to use the "ix" integer
293 variable to decide which function to call. "ix" is set to 0 for the
294 main function. Make sure to read up on the ALIAS feature of plain XS.
295 Aliasing is not supported for constructors and destructors.
296 Classes
298 %name{My::Class} class MyClass : public %name{My::Base} MyBase
299 {
300 // can be called in Perl as My::Class->new( ... );
301 MyClass( int arg );
302 // My::Class->newMyClass( ... );
303 %name{newMyClass} MyClass( const char* str, int arg );
304 // standard DESTROY method
306 ~MyClass();
307 int GetInt();
309 void SetValue( int arg = -1 );
310 %name{SetString} void SetValue( const char* string = NULL );
312 // Supply a C<CODE:> or C<CLEANUP:> block for the XS
314 int MyMethod( int a, int b )
315 %code{% RETVAL = a + b; %}
316 %cleanup{% /* do something */ %};
317 // Expose class method as My::ClassMethod::ClassMethod($foo)
319 static void ClassMethod( double foo );
320 // Expose member variable as a pair of set_boolean/get_boolean accessors
322 bool boolean %get %set;
323 };
324 Comments
326 XS++ recognizes both C-style comments "/* ... */" and C++-style
327 comments "// ...". Comments are removed from the XS output.
328 Exceptions
330 C++ Exceptions are always caught and transformed to Perl croak() calls.
331 If the exception that was caught inherited from "std::exception", then
332 the what() message is included in the Perl-level error message. All
333 other exceptions will result in the croak() message "Caught unhandled
334 C++ exception of unknown type".
335 Note that if you supply a custom %code block for a function or method,
337 the automatic exception handling is turned off.
338 Member variables
340 By default, member variable declarations are ignored; the %get and %set
341 decorators syntehsize a getter/setter named after the member variable
342 (can be renamed using %name).
343 XS++ defaults to get_/set_ prefix for getters/setters. This can be
345 overridden on an individual basis by using e.g.
346 int foo %get{readFoo} %set{writeFoo};
348 As an alternative, the class-level %accessors decorator sets the the
350 accessor style for the whole class:
351 %accessors{
353 %get_style{no_prefix};
354 %set_style{camelcase};
355 };
356 Available styles are
358 no_prefix => foo
360 underscore => get_foo, set_foo
361 camelcase => getFoo, setFoo
362 uppercase => GetFoo, SetFoo
363
365 The distribution contains an examples directory. The
366 examples/XSpp-Example directory therein demonstrates a particularly
367 simple way of getting started with XS++.
368
370 Mattia Barbon <mbarbon@cpan.org>
371
373 This program is free software; you can redistribute it and/or modify it
374 under the same terms as Perl itself.
375perl v5.38.0 2023-07-20 ExtUtils::XSpp(3pm)