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

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

  %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

  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 */ %};
      };

  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.

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.

