"--typemap=/path/to/typemap.xsp"

"--xsubpp[=/path/to/xsubpp]"

"--xsubpp-args="extra xsubpp args""

Ordinary XS typemaps

• 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.

XS++ typemaps

  %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.

Putting all the typemaps together

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.

Custom XS typemaps

There are multiple ways to override this default when needed.

    %typemap{Foo *}{simple}{
        %xs_type{O_MYMAP};
        %xs_input_code{% ... %}; // optional
        %xs_output_code{% ... %}; // optional
    };

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.

    %typemap{_}{simple}{
        %name{object};
        %xs_type{O_MYMAP};
        %xs_input_code{% ... %}; // optional
        %xs_output_code{% ... %}; // optional
    };

can be used to change the default typemap used for all classes.

%code

%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

%length

  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

  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 );

      // Expose member variable as a pair of set_boolean/get_boolean accessors
      bool boolean %get %set;
  };

Comments

Exceptions

Note that if you supply a custom %code block for a function or method, the automatic exception handling is turned off.

Member variables

XS++ defaults to get_/set_ prefix for getters/setters. This can be overridden on an individual basis by using e.g.

    int foo %get{readFoo} %set{writeFoo};

As an alternative, the class-level %accessors decorator sets the the accessor style for the whole class:

    %accessors{
        %get_style{no_prefix};
        %set_style{camelcase};
    };

Available styles are

no_prefix => foo

underscore => get_foo, set_foo

camelcase => getFoo, setFoo

uppercase => GetFoo, SetFoo