1ExtUtils::XSpp(3)     User Contributed Perl Documentation    ExtUtils::XSpp(3)
2
3
4

NAME

6       ExtUtils::XSpp - XS for C++
7

SYNOPSIS

9         xspp [--typemap=typemap.xsp [--typemap=typemap2.xsp]]
10              [--xsubpp[=/path/to/xsubpp] [--xsubpp-args="xsubpp args"]
11              Foo.xsp
12
13       or
14
15         perl -MExtUtils::XSpp::Cmd -e xspp -- <xspp options and arguments>
16
17       In Foo.xs
18
19         INCLUDE_COMMAND: $^X -MExtUtils::XSpp::Cmd -e xspp -- <xspp options/arguments>
20
21       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

OVERVIEW

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
29       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

COMMAND LINE

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
39   "--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
44   "--xsubpp-args="extra xsubpp args""
45       Can be used to pass additional command line arguments to xsubpp.
46

TYPEMAPS

48   Ordinary XS typemaps
49       To recap, ordinary XS typemaps do the following three things:
50
51       • Associate a C type with an identifier such as T_FOO or O_FOO (which
52         we'll call XS type here).
53
54       • Define an INPUT mapping for converting a Perl data structure to the
55         aforementioned C type.
56
57       • Define an OUTPUT mapping for converting the C data structure back
58         into a Perl data structure.
59
60       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
64   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
70         %typemap{<C++ type>}{simple};
71
72       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
76         %typemap{<C++ reference type>}{reference};
77
78       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
83       As a shortcut for the common case of declaring both of the above for a
84       given type, you may use
85
86         %typemap{<C++ type>};
87
88       Which has the same effect as:
89
90         %typemap{<C++ type>}{simple};
91         %typemap{<C++ type>&}{reference};
92
93       For more control over the type mapping, you can use the "parsed"
94       variant as follows.
95
96         %typemap{<C++ type 1>}{parsed}{%<C++ type 2>%};
97
98       When "C++ type 1" is used, replace it with "C++ type 2" in the
99       generated XS code.
100
101         %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
107             # use only one of the following
108             %output_code{% $PerlVar = newSViv( $CVar ) %};
109             %output_list{% PUTBACK; XPUSHi( $CVar ); SPAGAIN %};
110         };
111
112       Is a more flexible form for the "parsed" typemap.  All the parameters
113       are optional.
114
115       cpp_type
116           Specifies the C++ type used for the variable declaration in the
117           generated XS code.
118
119           If not specified defaults to the type specified in the typemap.
120
121       call_function_code
122           Used when the typemap applies to the return value of the function.
123
124           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
128       output_code
129           Used when the typemap applies to the return value of the function.
130           See also %output_list.
131
132           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
136       cleanup_code
137           Used when the typemap applies to the return value of the function.
138
139           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
144       precall_code
145           Used when the typemap applies to a parameter.
146
147           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
152       output_list
153           Used when the typemap applies to the return value of the function,
154           as an alternative to %output_code.
155
156           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
160           The code must use PUTBACK/SPAGAIN if appropriate.
161
162   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
168       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
177           %loadplugin{feature::default_xs_typemap};
178
179       in typemap.xsp (or near the top of every .xsp file).
180
181       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
185       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
189   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
194       There are multiple ways to override this default when needed.
195
196           %typemap{Foo *}{simple}{
197               %xs_type{O_MYMAP};
198               %xs_input_code{% ... %}; // optional
199               %xs_output_code{% ... %}; // optional
200           };
201
202       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
207           %typemap{_}{simple}{
208               %name{object};
209               %xs_type{O_MYMAP};
210               %xs_input_code{% ... %}; // optional
211               %xs_output_code{% ... %}; // optional
212           };
213
214       can be used to change the default typemap used for all classes.
215

DESCRIPTION

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
222         %{
223         XS++ won't interpret this
224         %}
225
226   %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
231   %file
232         %file{file/path.h};
233         ...
234         %file{file/path2};
235         ...
236         %file{-}
237
238       By default XS++ output goes to standard output; to change this, use the
239       %file directive; use "-" for standard output.
240
241   %module
242         %module{Module::Name};
243
244       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
249   %name
250         %name{Perl::Class} class MyClass { ... };
251         %name{Perl::Func} int foo();
252
253       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
256   %typemap
257       See "TYPEMAPS" above.
258
259   %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
265         void PrintLine( char* line, unsigned int %length{line} );
266
267       you can call the method from Perl like this:
268
269         $object->PrintLine( $string );
270
271       This feature is also present in plain XS. See also: perlxs.
272
273       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
277   %alias
278       Decorator for function/method declarations such as
279
280         double add(double a, double b)
281           %alias{subtract = 1} %alias{multiply = 2};
282
283       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
289       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
297   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
305             // standard DESTROY method
306             ~MyClass();
307
308             int GetInt();
309             void SetValue( int arg = -1 );
310
311             %name{SetString} void SetValue( const char* string = NULL );
312
313             // 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
318             // Expose class method as My::ClassMethod::ClassMethod($foo)
319             static void ClassMethod( double foo );
320
321             // Expose member variable as a pair of set_boolean/get_boolean accessors
322             bool boolean %get %set;
323         };
324
325   Comments
326       XS++ recognizes both C-style comments "/* ... */" and C++-style
327       comments "// ...".  Comments are removed from the XS output.
328
329   Exceptions
330       C++ Exceptions are always caught and transformed to Perl "croak()"
331       calls. If the exception that was caught inherited from
332       "std::exception", then the "what()" message is included in the Perl-
333       level error message.  All other exceptions will result in the "croak()"
334       message "Caught unhandled C++ exception of unknown type".
335
336       Note that if you supply a custom %code block for a function or method,
337       the automatic exception handling is turned off.
338
339   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
344       XS++ defaults to get_/set_ prefix for getters/setters.  This can be
345       overridden on an individual basis by using e.g.
346
347           int foo %get{readFoo} %set{writeFoo};
348
349       As an alternative, the class-level %accessors decorator sets the the
350       accessor style for the whole class:
351
352           %accessors{
353               %get_style{no_prefix};
354               %set_style{camelcase};
355           };
356
357       Available styles are
358
359       no_prefix   => foo
360       underscore  => get_foo, set_foo
361       camelcase   => getFoo, setFoo
362       uppercase   => GetFoo, SetFoo
363

EXAMPLES

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

AUTHOR

370       Mattia Barbon <mbarbon@cpan.org>
371

LICENSE

373       This program is free software; you can redistribute it and/or modify it
374       under the same terms as Perl itself.
375
376
377
378perl v5.32.1                      2021-01-27                 ExtUtils::XSpp(3)
Impressum