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.
"--xsubpp-args="extra xsubpp args""
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.
%alias
Decorator for function/method declarations such as
double add(double a, double b)
%alias{subtract = 1} %alias{multiply = 2};
Which will cause the generation of just a single XSUB using the XS
"ALIAS" feature (see perlxs). It will be installed as all of "add",
"subtract", and "multiply" on the Perl side and call either the C++
"add", "subtract", or "multiply" functions depending on which way it was
called.
Notes: If used in conjunction with %name{foo} to rename the function,
then the %name will only affect the main function name (in the above
example, "add" but not "subtract" or "multiply"). When used with the
%code feature, the custom code will have to use the "ix" integer
variable to decide which function to call. "ix" is set to 0 for the main
function. Make sure to read up on the ALIAS feature of plain XS.
Aliasing is not supported for constructors and destructors.
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 */ %};
// Expose class method as My::ClassMethod::ClassMethod($foo)
static void ClassMethod( double foo );
};
Comments
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.