NAME¶
ExtUtils::XSpp - XS for C++
SYNOPSIS¶
xspp [--typemap=typemap.xsp [--typemap=typemap2.xsp]]
[--xsubpp[=/path/to/xsubpp] [--xsubpp-args="xsubpp args"]
Foo.xsp
or
perl -MExtUtils::XSpp::Cmd -e xspp -- <xspp options and arguments>
In Foo.xs
INCLUDE_COMMAND: $^X -MExtUtils::XSpp::Cmd -e xspp -- <xspp options/arguments>
Using "ExtUtils::XSpp::Cmd" is equivalent to using the
"xspp" command line script, except that there is no guarantee for
"xspp" to be installed in the system PATH.
OVERVIEW¶
XS++ is just a thin layer over plain XS, hence to use it you are supposed to
know, at the very least, C++ and XS.
This means that you will need typemaps for
both the normal XS
pre-processor
xsubpp and the XS++ pre-processor
xspp.
COMMAND LINE¶
"--typemap=/path/to/typemap.xsp"¶
Can be specified multiple times to process additional typemap files before the
main XS++ input files. Typemap files are processed the same way as regular
XS++ files, except that output code is discarded.
"--xsubpp[=/path/to/xsubpp]"¶
If specified, XS++ will run
xsubpp after processing the XS++ input file.
If the path to
xsubpp is not specified,
xspp expects to find it
in the system PATH.
Can be used to pass additional command line arguments to
xsubpp.
TYPEMAPS¶
There is nothing special about typemap files (i.e. you can put typemaps directly
in your .xsp file), but it is handy to have common typemaps in a separate
file, to avoid duplication.
%typemap{<C++ type>}{simple};
Just let XS++ know that this is a valid type, the type will be passed unchanged
to XS code
except that any "const" qualifiers will be
stripped.
%typemap{<C++ reference type>}{reference};
Handle C++ references: the XS variable will be declared as a pointer, and it
will be explicitly dereferenced in the function call. If it is used in the
return value, the function will create
copy of the returned value using
a copy constructor.
As a shortcut for the common case of declaring both of the above for a given
type, you may use
%typemap{<C++ type>};
Which has the same effect as:
%typemap{<C++ type>}{simple};
%typemap{<C++ type>&}{reference};
For more control over the type mapping, you can use the "parsed"
variant as follows.
%typemap{<C++ type 1>}{parsed}{%<C++ type 2>%};
When "C++ type 1" is used, replace it with "C++ type 2" in
the generated XS code.
%typemap{<C++ type>}{parsed}{
%cpp_type{%<C++ type 2>%};
%call_function_code{% $CVar = new Foo( $Call ) %};
%cleanup_code{% ... %};
%precall_code{% ... %};
# use only one of the following
%output_code{% $PerlVar = newSViv( $CVar ) %};
%output_list{% PUTBACK; XPUSHi( $CVar ); SPAGAIN %};
};
Is a more flexible form for the "parsed" typemap. All the parameters
are optional.
- cpp_type
- Specifies the C++ type used for the variable declaration in
the generated XS code.
If not specified defaults to the type specified in the typemap.
- call_function_code
- Used when the typemap applies to the return value of the
function.
Specifies the code to use in the function call. The special variables $Call
and $CVar are replaced with the actual call code and the name of the C++
return variable.
- output_code
- Used when the typemap applies to the return value of the
function. See also %output_list.
Specifies the code emitted right after the function call to convert the C++
return value into a Perl return value. The special variable $CVar is
replaced with the C++ return variable name.
- cleanup_code
- Used when the typemap applies to the return value of the
function.
Specifies some code emitted after output value processing. The special
variables $PerlVar and $CVar are replaced with the names of the C++
variables containing the Perl scalar and the corresponding C++ value.
- precall_code
- Used when the typemap applies to a parameter.
Specifies some code emitted after argument processing and before calling the
C++ method. The special variables $PerlVar and $CVar are replaced with the
names of the C++ variables containing the Perl scalar and the
corresponding C++ value.
- output_list
- Used when the typemap applies to the return value of the
function, as an alternative to %output_code.
Specifies some code that manipulates the Perl stack directly in order to
return a list. The special variable $CVar is replaced with the C++ name of
the output variable.
The code must use PUTBACK/SPAGAIN if appropriate.
DESCRIPTION¶
Anything that does not look like a XS++ directive or a class declaration is
passed verbatim to XS. If you want XS++ to ignore code that looks like a XS++
directive or class declaration, simply surround it with a raw block delimiter
like this:
%{
XS++ won't interpret this
%}
%code¶
See under
Classes. Note that custom %code blocks are the only exception
to the exception handling. By specifying a custom %code block, you forgo the
automatic exception handlers.
%file¶
%file{file/path.h};
...
%file{file/path2};
...
%file{-}
By default XS++ output goes to standard output; to change this, use the %file
directive; use "-" for standard output.
%module¶
%module{Module::Name};
Will be used to generate the "MODULE=Module::Name" XS directives. It
indirectly sets the name of the shared library that is generated as well as
the name of the module via which XSLoader will be able to find/load it.
%name¶
%name{Perl::Class} class MyClass { ... };
%name{Perl::Func} int foo();
Specifies the Perl name under which the C++ class/function will be accessible.
By default, constructor names are mapped to "new" in Perl.
%typemap¶
See
TYPEMAPS above.
%length¶
When you need to pass a string from Perl to an XSUB that takes the C string and
its length as arguments, you may have XS++ pass the length of the string
automatically. For example, if you declare a method as follows,
void PrintLine( char* line, unsigned int %length{line} );
you can call the method from Perl like this:
$object->PrintLine( $string );
This feature is also present in plain XS. See also: perlxs.
If you use "%length(line)" in conjunction with any kind of special
code block such as %code, %postcall, etc., then you can refer to the length of
the string (here: "line")
efficiently as
"length(line)" in the code.
Classes¶
%name{My::Class} class MyClass : public %name{My::Base} MyBase
{
// can be called in Perl as My::Class->new( ... );
MyClass( int arg );
// My::Class->newMyClass( ... );
%name{newMyClass} MyClass( const char* str, int arg );
// standard DESTROY method
~MyClass();
int GetInt();
void SetValue( int arg = -1 );
%name{SetString} void SetValue( const char* string = NULL );
// Supply a C<CODE:> or C<CLEANUP:> block for the XS
int MyMethod( int a, int b )
%code{% RETVAL = a + b; %}
%cleanup{% /* do something */ %};
};
XS++ recognizes both C-style comments "/* ... */" and C++-style
comments "// ...". Comments are removed from the XS output.
Exceptions¶
C++ Exceptions are always caught and transformed to Perl "croak()"
calls. If the exception that was caught inherited from
"std::exception", then the "what()" message is included in
the Perl-level error message. All other exceptions will result in the
"croak()" message "Caught unhandled C++ exception of unknown
type".
Note that if you supply a custom %code block for a function or method, the
automatic exception handling is turned off.
EXAMPLES¶
The distribution contains an
examples directory. The
examples/XSpp-Example directory therein demonstrates a particularly
simple way of getting started with XS++.
AUTHOR¶
Mattia Barbon <mbarbon@cpan.org>
LICENSE¶
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.