/ 
Inline-CPP-0.14
River stage two • 6 direct dependents • 13 total dependents
/ Inline::CPP

NAME

Inline::CPP - Write Perl subroutines and classes in C++.

SYNOPSIS

print "9 + 16 = ", add(9, 16), "\n";
print "9 - 16 = ", subtract(9, 16), "\n";

use Inline CPP => <<'END_OF_CPP_CODE';

int add(int x, int y) { 
   return x + y;
}

int subtract(int x, int y) {
   return x - y;
}

END_OF_CPP_CODE

DESCRIPTION

The Inline::CPP module allows you to put C++ source code directly "inline" in a Perl script or module. You code classes or functions in C++, and you can use them as if they were written in Perl.

Using Inline::CPP

Inline::CPP is very similar to Inline::C. It uses a grammar to parse your C++ code, and binds to functions or classes which are recognized. If a function is recognized, it will be available from Perl space. If the function's signature is not recognized, it will not be available from Perl space, but will be available from other functions in C++.

Inline::CPP binds to functions using the same grammar as Inline::C. However, it contains an extended grammar for dealing with classes. Several features of C++ are simply not supported, such as template classes and inline function definitions.

The following example shows how C++ snippets map into the Perl namespace:

Example 1:

use Inline CPP => <<'END';

int doodle() { }

class Foo {
  public:
    Foo();
    ~Foo();

    int get_data();
    void set_data(int a);
  private:
    int data;
};

Foo::Foo() { cout << "creating a Foo()" << endl; }
Foo::~Foo() { cout << "deleting a Foo()" << endl; }

int Foo::get_data() { return data; }
int Foo::set_data(int a) { data = a; }

END

After running the code above, Perl's namespace would look similar to if following code had been run:

sub main::doodle { }

package main::Foo;

sub new { print "creating a Foo()\n"; bless {}, shift }
sub DESTROY { print "deleting a Foo()\n" }

sub get_data { my $o=shift; $o->{data} }
sub set_data { my $o=shift; $o->{data} = shift }

The difference, of course, is that in the latter, Perl does the work. In the Inline::CPP example, all function calls get sent off to your C++ code. That means that things like this won't work:

my $obj = new Foo;
$obj->{extrafield} = 10;

It doesn't work because $obj is not a blessed hash. It's a blessed reference to a C++ object (and anyway, C++ wouldn't let you do that either, since extrafield wasn't defined).

C++ Configuration Options

For information on how to specify Inline configuration options, see Inline. This section describes each of the configuration options available for C. Most of the options correspond either the MakeMaker or XS options of the same name. See ExtUtils::MakeMaker and perlxs.

AUTO_INCLUDE

Specifies extra statements to be automatically included. They will be added on to the defaults. A newline char will automatically be added.

use Inline CPP => Config => AUTO_INCLUDE => '#include "something.h"';

BOOT

Specifies code to be run when your code is loaded. May not contain any blank lines. See perlxs for more information.

use Inline CPP => Config => BOOT => 'foo();';

CC

Specifies which compiler to use.

CCFLAGS

Specifies extra compiler flags. Corresponds to the MakeMaker option.

INC

Specifies extra include directories. Corresponds to the MakeMaker parameter.

use Inline CPP => Config => INC => '-I/my/path';

LD

Specifies the linker to use.

LDDLFLAGS

Specifies which linker flags to use.

NOTE: These flags will completely override the existing flags, instead of just adding to them. So if you need to use those too, you must respecify them here.

LIBS

Specifies external libraries that should be linked into your code. Corresponds to the MakeMaker parameter.

use Inline CPP => Config => LIBS => '-L/your/path -lyourlib';

MAKE

Specifies the name of the 'make' utility to use.

MYEXTLIB

Specifies a user compiled object that should be linked in. Corresponds to the MakeMaker parameter.

use Inline CPP => Config => MYEXTLIB => '/your/path/something.o';

PREFIX

Specifies a prefix that will automatically be stripped from C++ functions when they are bound to Perl. Less useful than in C, because C++ mangles its function names so they don't conflict with C functions of the same name.

use Inline CPP => Config => PREFIX => 'ZLIB_';

TYPEMAPS

Specifies extra typemap files to use. These types will modify the behaviour of C++ parsing. Corresponds to the MakeMaker parameter.

use Inline CPP => Config => TYPEMAPS => '/your/path/typemap';

C++-Perl Bindings

This section describes how the Perl variables get mapped to C++ variables and back again.

Perl uses a stack to pass arguments back and forth to subroutines. When a sub is called, it pops off all its arguments from the stack; when it's done, it pushes its return values back onto the stack.

XS (Perl's language for creating C or C++ extensions for Perl) uses "typemaps" to turn SVs into C types and back again. This is done through various XS macro calls, casts, and the Perl API. XS also allows you to define your own mappings.

Inline::CPP uses a much simpler approach. It parses the system's typemap files and only binds to functions with supported types. You can tell Inline::CPP about custom typemap files too.

If you have very complicated data structures in either C++ or Perl, you should just pass them as an SV* and do the conversion yourself in your C++ function.

SEE ALSO

For general information about how Inline binds code to Perl, see Inline.

For information on using C with Perl, see Inline::C and Inline::C-Cookbook. For WMTYEWTK, see perlxs, perlxstut, perlapi, and perlguts.

BUGS AND DEFICIENCIES

When reporting a bug, please do the following:

- Put "use Inline REPORTBUG;" at the top of your code, or 
  use the command line option "perl -MInline=REPORTBUG ...".
- Run your code.
- Follow the printed instructions.

Here are some things to watch out for:

  1. The grammar used for parsing C++ is very simple, and does not allow several important features of C++:

    o templates;
o inheritance; and,
o inline class methods.

    Other grammar problems will probably be noticed quickly.

AUTHOR

Neil Watkiss <NEILW@cpan.org>

Brian Ingerson <INGY@cpan.org> is the author of Inline, Inline::C and Inline::CPR. His antics with object-oriented Perl using C convinced me it was time to add support for C++. He was responsible for much encouragement and many suggestions throughout the development of Inline::CPP.

COPYRIGHT

Copyright (c) 2000 - 2001, Neil Watkiss.

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the terms of the Perl Artistic License.

See http://www.perl.com/perl/misc/Artistic.html