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.

Associate a C type with an identifier such as T_FOO or O_FOO (which we'll call XS type here).

Define an INPUT mapping for converting a Perl data structure to the aforementioned C type.

Define an OUTPUT mapping for converting the C data structure back into a Perl data structure.

These are still required in the context of XS++. There are some helpers to take away the tedium, but I'll get to that later. For XS++, there's another layer of typemaps. The following section will discuss those.

There is nothing special about XS++ 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, typically called typemap.xsp 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.

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.

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.

In summary, the XS++ typemaps (optionally) give you much more control over the type conversion code that's generated for your XSUBs. But you still need to let the XS compiler know how to map the C types to Perl and back using the XS typemaps.

Most of the time, you just need to convert basic C(++) types or the types that you define with your C++ classes. For the former, XS++ comes with a few default mappings for booleans, integers, floating point numbers, and strings. For classes, XS++ can automatically create a mapping of type O_OBJECT which uses the de-facto standard way of storing a pointer to the C(++) object in the IV slot of a referenced/blessed scalar. Due to backwards compatibility, this must be explicitly enabled by adding

%loadplugin{feature::default_xs_typemap};

in typemap.xsp (or near the top of every .xsp file).

If you deal with any other types as arguments or return types, you still need to write both XS and XS++ typemaps for these so that the systems know how to deal with them.

See either "Custom XS typemaps" below for a way to specify XS typemaps from XS++ or perlxs for a discussion of inline XS typemaps that don't require the traditional XS typemap file.

can be used to define a new type -> XS typemap mapping, with optinal input/output code. Since XS typemap definitions are global, XS input/output code applies to all types with the same %xs_type, hence there is no need to repeat it.

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:

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.

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,

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.

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.

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.