/ 
ExtUtils-XSpp-0.05
River stage three • 24 direct dependents • 168 total dependents
/ ExtUtils::XSpp

NAME

ExtUtils::XSpp - XS for C++

SYNOPSIS

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

or

perl -MExtUtils::XSpp::Cmd -e xspp -- <xspp options and arguments>

In Foo.xs

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

INCLUDE: perl -MExtUtils::XSpp::Cmd -e xspp -- <xspp options and 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.

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.

%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
{
    // 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

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

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.