1ExtUtils::XSpp(3) User Contributed Perl Documentation ExtUtils::XSpp(3)
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 will need typemaps for both the normal XS pre-
30 processor xsubpp and the XS++ pre-processor xspp.
31
33 "--typemap=/path/to/typemap.xsp"
34 Can be specified multiple times to process additional typemap files
35 before the main XS++ input files. Typemap files are processed the same
36 way as regular XS++ files, except that output code is discarded.
37 "--xsubpp[=/path/to/xsubpp]"
39 If specified, XS++ will run xsubpp after processing the XS++ input
40 file. If the path to xsubpp is not specified, xspp expects to find it
41 in the system PATH.
42 "--xsubpp-args="extra xsubpp args""
44 Can be used to pass additional command line arguments to xsubpp.
45
47 There is nothing special about typemap files (i.e. you can put typemaps
48 directly in your .xsp file), but it is handy to have common typemaps in
49 a separate file, to avoid duplication.
50 %typemap{<C++ type>}{simple};
52 Just let XS++ know that this is a valid type, the type will be passed
54 unchanged to XS code except that any "const" qualifiers will be
55 stripped.
56 %typemap{<C++ reference type>}{reference};
58 Handle C++ references: the XS variable will be declared as a pointer,
60 and it will be explicitly dereferenced in the function call. If it is
61 used in the return value, the function will create copy of the returned
62 value using a copy constructor.
63 As a shortcut for the common case of declaring both of the above for a
65 given type, you may use
66 %typemap{<C++ type>};
68 Which has the same effect as:
70 %typemap{<C++ type>}{simple};
72 %typemap{<C++ type>&}{reference};
73 For more control over the type mapping, you can use the "parsed"
75 variant as follows.
76 %typemap{<C++ type 1>}{parsed}{%<C++ type 2>%};
78 When "C++ type 1" is used, replace it with "C++ type 2" in the
80 generated XS code.
81 %typemap{<C++ type>}{parsed}{
83 %cpp_type{%<C++ type 2>%};
84 %call_function_code{% $CVar = new Foo( $Call ) %};
85 %cleanup_code{% ... %};
86 %precall_code{% ... %};
87 # use only one of the following
89 %output_code{% $PerlVar = newSViv( $CVar ) %};
90 %output_list{% PUTBACK; XPUSHi( $CVar ); SPAGAIN %};
91 };
92 Is a more flexible form for the "parsed" typemap. All the parameters
94 are optional.
95 cpp_type
97 Specifies the C++ type used for the variable declaration in the
98 generated XS code.
99 If not specified defaults to the type specified in the typemap.
101 call_function_code
103 Used when the typemap applies to the return value of the function.
104 Specifies the code to use in the function call. The special
106 variables $Call and $CVar are replaced with the actual call code
107 and the name of the C++ return variable.
108 output_code
110 Used when the typemap applies to the return value of the function.
111 See also %output_list.
112 Specifies the code emitted right after the function call to convert
114 the C++ return value into a Perl return value. The special
115 variable $CVar is replaced with the C++ return variable name.
116 cleanup_code
118 Used when the typemap applies to the return value of the function.
119 Specifies some code emitted after output value processing. The
121 special variables $PerlVar and $CVar are replaced with the names of
122 the C++ variables containing the Perl scalar and the corresponding
123 C++ value.
124 precall_code
126 Used when the typemap applies to a parameter.
127 Specifies some code emitted after argument processing and before
129 calling the C++ method. The special variables $PerlVar and $CVar
130 are replaced with the names of the C++ variables containing the
131 Perl scalar and the corresponding C++ value.
132 output_list
134 Used when the typemap applies to the return value of the function,
135 as an alternative to %output_code.
136 Specifies some code that manipulates the Perl stack directly in
138 order to return a list. The special variable $CVar is replaced
139 with the C++ name of the output variable.
140 The code must use PUTBACK/SPAGAIN if appropriate.
142
144 Anything that does not look like a XS++ directive or a class
145 declaration is passed verbatim to XS. If you want XS++ to ignore code
146 that looks like a XS++ directive or class declaration, simply surround
147 it with a raw block delimiter like this:
148 %{
150 XS++ won't interpret this
151 %}
152 %code
154 See under Classes. Note that custom %code blocks are the only exception
155 to the exception handling. By specifying a custom %code block, you
156 forgo the automatic exception handlers.
157 %file
159 %file{file/path.h};
160 ...
161 %file{file/path2};
162 ...
163 %file{-}
164 By default XS++ output goes to standard output; to change this, use the
166 %file directive; use "-" for standard output.
167 %module
169 %module{Module::Name};
170 Will be used to generate the "MODULE=Module::Name" XS directives. It
172 indirectly sets the name of the shared library that is generated as
173 well as the name of the module via which XSLoader will be able to
174 find/load it.
175 %name
177 %name{Perl::Class} class MyClass { ... };
178 %name{Perl::Func} int foo();
179 Specifies the Perl name under which the C++ class/function will be
181 accessible. By default, constructor names are mapped to "new" in Perl.
182 %typemap
184 See TYPEMAPS above.
185 %length
187 When you need to pass a string from Perl to an XSUB that takes the C
188 string and its length as arguments, you may have XS++ pass the length
189 of the string automatically. For example, if you declare a method as
190 follows,
191 void PrintLine( char* line, unsigned int %length{line} );
193 you can call the method from Perl like this:
195 $object->PrintLine( $string );
197 This feature is also present in plain XS. See also: perlxs.
199 If you use "%length(line)" in conjunction with any kind of special code
201 block such as %code, %postcall, etc., then you can refer to the length
202 of the string (here: "line") efficiently as "length(line)" in the code.
203 Classes
205 %name{My::Class} class MyClass : public %name{My::Base} MyBase
206 {
207 // can be called in Perl as My::Class->new( ... );
208 MyClass( int arg );
209 // My::Class->newMyClass( ... );
210 %name{newMyClass} MyClass( const char* str, int arg );
211 // standard DESTROY method
213 ~MyClass();
214 int GetInt();
216 void SetValue( int arg = -1 );
217 %name{SetString} void SetValue( const char* string = NULL );
219 // Supply a C<CODE:> or C<CLEANUP:> block for the XS
221 int MyMethod( int a, int b )
222 %code{% RETVAL = a + b; %}
223 %cleanup{% /* do something */ %};
224 };
225 Comments
227 XS++ recognizes both C-style comments "/* ... */" and C++-style
228 comments "// ...". Comments are removed from the XS output.
229 Exceptions
231 C++ Exceptions are always caught and transformed to Perl "croak()"
232 calls. If the exception that was caught inherited from
233 "std::exception", then the "what()" message is included in the Perl-
234 level error message. All other exceptions will result in the "croak()"
235 message "Caught unhandled C++ exception of unknown type".
236 Note that if you supply a custom %code block for a function or method,
238 the automatic exception handling is turned off.
239
241 The distribution contains an examples directory. The
242 examples/XSpp-Example directory therein demonstrates a particularly
243 simple way of getting started with XS++.
244
246 Mattia Barbon <mbarbon@cpan.org>
247
249 This program is free software; you can redistribute it and/or modify it
250 under the same terms as Perl itself.
251perl v5.12.3 2011-03-09 ExtUtils::XSpp(3)