=head1 NAME

ExtUtils::XSpp - XS for C++

=head1 SYNOPSIS

  xspp [--typemap=typemap.xsp [--typemap=typemap2.xsp]] Foo.xsp

In Foo.xs (all in one line):

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

=head1 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 B<both> the normal XS
pre-processor I<xsubpp> and the XS++ pre-processor I<xspp>.

=head1 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 B<except> that any C<const> qualifiers will be
stripped.

  %typemap{<C++ type 1>}{parsed}{%<C++ type 2>%};

When C<C++ type 1> is used, replace it with C<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 B<copy> of the
returned value using a copy constructor.

=head1 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
  %}

=head2 %code

See under B<Classes>.

=head2 %file

  %file{file/path.h};
  ...
  %file{file/path2};
  ...
  %file{-}

By default XS++ output goes to standard output; to change this, use the
C<%file> directive; use C<-> for standard output.

=head2 %module

  %module{Module__Name};

Will be used to generate the C<MODULE=Module__Name> XS directives.

=head2 %name

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

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

=head2 %typemap

See B<TYPEMAPS> above.

=head2 %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: L<perlxs>

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

=head2 Comments

C-style C</* ... */> comments will be passed through unchanged.  C++-style
comments C<// ...> will be passed throug with the leading C<//> replaced
with C<##>.

=head1 AUTHOR

Mattia Barbon <mbarbon@cpan.org>

=head1 LICENSE

This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=cut

# local variables:
# mode: cperl
# end:
