NAME

XSpp - XS for C++

SYNOPSIS

In Foo.xs (all in one line):

  INCLUDE: perl -S wxperl_xspp --typemap=typemap.xsp
           Foo.xsp |

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 xsubpp and xsubppp.

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

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.

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

%name

  %name{Perl::Class} class MyClass { ... };
  %name{Perl::Func} int foo();

Specifies the perl name under which the C++ class/function will be accessible.

%typemap

See TYPEMAPS above.

Classes

  %name{My::Class} class MyClass
  {
      // 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 */ %};
  };