vcs.maemo.org Git - pkg-perl/blob - deb-src/libextutils-xspp-perl/libextutils-xspp-perl-0.07/lib/ExtUtils/XSpp.pod

   1 =head1 NAME
   2
   3 ExtUtils::XSpp - XS for C++
   4
   5 =head1 SYNOPSIS
   6
   7   xspp [--typemap=typemap.xsp [--typemap=typemap2.xsp]]
   8        [--xsubpp[=/path/to/xsubpp] [--xsubpp-args="xsubpp args"]
   9        Foo.xsp
  10
  11 or
  12
  13   perl -MExtUtils::XSpp::Cmd -e xspp -- <xspp options and arguments>
  14
  15 In Foo.xs
  16
  17   INCLUDE_COMMAND: $^X -MExtUtils::XSpp::Cmd -e xspp -- <xspp options/arguments>
  18
  19 Using C<ExtUtils::XSpp::Cmd> is equivalent to using the C<xspp>
  20 command line script, except that there is no guarantee for C<xspp> to
  21 be installed in the system PATH.
  22
  23 =head1 OVERVIEW
  24
  25 XS++ is just a thin layer over plain XS, hence to use it you
  26 are supposed to know, at the very least, C++ and XS.
  27
  28 This means that you will need typemaps for B<both> the normal XS
  29 pre-processor I<xsubpp> and the XS++ pre-processor I<xspp>.
  30
  31 =head1 COMMAND LINE
  32
  33 =head2 C<--typemap=/path/to/typemap.xsp>
  34
  35 Can be specified multiple times to process additional typemap files
  36 before the main XS++ input files.  Typemap files are processed the
  37 same way as regular XS++ files, except that output code is discarded.
  38
  39 =head2 C<--xsubpp[=/path/to/xsubpp]>
  40
  41 If specified, XS++ will run F<xsubpp> after processing the XS++ input
  42 file.  If the path to F<xsubpp> is not specified, F<xspp> expects to
  43 find it in the system PATH.
  44
  45 =head2 C<--xsubpp-args="extra xsubpp args">
  46
  47 Can be used to pass additional command line arguments to F<xsubpp>.
  48
  49 =head1 TYPEMAPS
  50
  51 There is nothing special about typemap files (i.e. you can put typemaps
  52 directly in your .xsp file), but it is handy to have common typemaps in a
  53 separate file, to avoid duplication.
  54
  55   %typemap{<C++ type>}{simple};
  56
  57 Just let XS++ that this is a valid type, the type will be passed
  58 unchanged to XS code B<except> that any C<const> qualifiers will be
  59 stripped.
  60
  61   %typemap{<C++ type 1>}{parsed}{%<C++ type 2>%};
  62
  63 When C<C++ type 1> is used, replace it with C<C++ type 2> in the
  64 generated XS code.
  65
  66   %typemap{<C++ reference type>}{reference};
  67
  68 Handle C++ references: the XS variable will be declared as a pointer,
  69 and it will be explicitly dereferenced in the function call. If it is
  70 used in the return value, the function will create B<copy> of the
  71 returned value using a copy constructor.
  72
  73 =head1 DESCRIPTION
  74
  75 Anything that does not look like a XS++ directive or a class
  76 declaration is passed verbatim to XS. If you want XS++ to ignore code
  77 that looks like a XS++ directive or class declaration, simply surround it with
  78 a raw block delimiter like this:
  79
  80   %{
  81   XS++ won't interpret this
  82   %}
  83
  84 =head2 %code
  85
  86 See under B<Classes>.
  87
  88 =head2 %file
  89
  90   %file{file/path.h};
  91   ...
  92   %file{file/path2};
  93   ...
  94   %file{-}
  95
  96 By default XS++ output goes to standard output; to change this, use the
  97 C<%file> directive; use C<-> for standard output.
  98
  99 =head2 %module
 100
 101   %module{Module__Name};
 102
 103 Will be used to generate the C<MODULE=Module__Name> XS directives.
 104
 105 =head2 %name
 106
 107   %name{Perl::Class} class MyClass { ... };
 108   %name{Perl::Func} int foo();
 109
 110 Specifies the perl name under which the C++ class/function will be
 111 accessible.
 112
 113 =head2 %typemap
 114
 115 See B<TYPEMAPS> above.
 116
 117 =head2 %length
 118
 119 When you need to pass a string from Perl to an XSUB that
 120 takes the C string and its length as arguments,
 121 you may have XS++ pass the length of the string automatically.
 122 For example, if you declare a method as follows,
 123
 124   void PrintLine( char* line, unsigned int %length{line} );
 125
 126 you can call the method from Perl like this:
 127
 128   $object->PrintLine( $string );
 129
 130 This feature is also present in plain XS. See also: L<perlxs>
 131
 132 =head2 Classes
 133
 134   %name{My::Class} class MyClass : public %name{My::Base} MyBase
 135   {
 136       // can be called in Perl as My::Class->new( ... );
 137       MyClass( int arg );
 138       // My::Class->newMyClass( ... );
 139       %name{newMyClass} MyClass( const char* str, int arg );
 140
 141       // standard DESTROY method
 142       ~MyClass();
 143
 144       int GetInt();
 145       void SetValue( int arg = -1 );
 146
 147       %name{SetString} void SetValue( const char* string = NULL );
 148
 149       // Supply a C<CODE:> or C<CLEANUP:> block for the XS
 150       int MyMethod( int a, int b )
 151           %code{% RETVAL = a + b; %}
 152           %cleanup{% /* do something */ %};
 153   };
 154
 155 =head2 Comments
 156
 157 XS++ recognizes both C-style comments C</* ... */> and C++-style
 158 comments C<// ...>.  Comments are removed from the XS output.
 159
 160 =head1 AUTHOR
 161
 162 Mattia Barbon <mbarbon@cpan.org>
 163
 164 =head1 LICENSE
 165
 166 This program is free software; you can redistribute it and/or
 167 modify it under the same terms as Perl itself.
 168
 169 =cut
 170
 171 # local variables:
 172 # mode: cperl
 173 # end: