Debian Codegraph @

README

raw
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