NAME

Inline::SWIG - Write Perl in C/C++/Objective-C using SWIG. (v0.00)

SYNOPSIS

 use Inline SWIG => 'int meaning() { return 42; }';
 print &meaning();

 use Inline SWIG => <<"END_CODE", SWIG_ARGS => '-c++ -shadow', CC => "c++";
 class Foo {
   public:
     int meaning() { return 42; };
 };
 END_CODE
 my $o = new Foo();
 print $o->meaning(),"\n";

DESCRIPTION

Inline::SWIG is like Inline::C (or Inline::CPP), but uses SWIG (www.swig.org) to do the parsing and glue code generation.

See the Inline::C manpage, Inline, http://www.swig.org/, and the Inline::SWIG homepage http://www.vendian.org/mncharity/dir3/inline/swig/.

I suggest using Inline::C or Inline::CPP instead of this module, unless you really want/need SWIG's glue.

SWIG's support of perl is currently (ver 1.3.15, 2002-Sep) in flux. For example, the -shadow of the ``-c++ -shadow'' idiom is required, and is used in SWIG's perl Examples, but it is no longer a documented swig command line argument. Sigh.

CONFIGURATION

CC

Inline::C configuration options (such as ``CC'') can be used. But those which control glue generation, now being done by SWIG, are ignored.

    ..., CC => 'c++';  # Use c++ instead of cc.

SWIG_ARGS

A string of swig command line arguments. See SWIG documentation. ``-c++'' enables C++ processing.

    ..., SWIG_ARGS => '-c++';

SWIG_INTERFACE

SWIG .i code. A SWIG_INTERFACE code string is placed in a SWIG .i file. Swig is run on it, instead of the source code.

A ``%module mumblepackage'' declaration (optional) loads the code into package mumblepackage, instead of into the package enclosing the ``use Inline SWIG'' statement.

    use Inline SWIG => '... .c code ...', SWIG_INTERFACE => '... .i code ...';

    use Inline SWIG => ' ', SWIG_INTERFACE => '... .i code ...';

    BEGIN { $header = '... .h code ...'; }
    use Inline SWIG => $header.' ', SWIG_INTERFACE => <<'END';
    %{
    $header
    %}
    ... .i code, including perhaps another copy of $header ...
    END

SWIG_COMMAND

    Defaults to "swig -perl5";

EXAMPLES

Using a combination of code and interface strings

If one uses both code and interface strings, which end up as separate code and interface files, one may need to have common header information. Here is one way to handle it.

The BEGIN makes the $foo_h variable available at Perl ``compile''-time, which is when the ``use Inline'' happens.

  BEGIN {
    $foo_h = <<"  END_OF_H";
    class Foo {
      public: 
          int meaning();
    };
    END_OF_H
  }
  use Inline SWIG => <<"END_OF_CODE", SWIG_INTERFACE => <<"END_OF_I", SWIG_ARGS => '-c++ -shadow', CC => "c++";

  $foo_h
  int Foo::meaning() { return 42; }

  END_OF_CODE

  %{
  $foo_h
  %}
  %module example
  $foo_h

  END_OF_I

  my $o = new example::Foo();
  print $o->meaning(),"\n";

Dynamic code generation

  Inline::SWIG can also be invoked at Perl "run"-time.

  use Inline;
  sub make_adder {
    my $n = shift;
    my $function_name = "f".int(rand(1000000));
    my $code = "int ${function_name}(int x) { return x + $n; }";
    Inline->bind(SWIG => $code);
    return \&$function_name;
  }
  my $add3 = &make_adder(3);
  print $add3->(2); # -> 5

IMPLEMENTATION NOTES

Inline::SWIG isa Inline::C. To compile code, it runs swig, edits the result, and then hands them off to Inline::C.

Inline::SWIG edits the SWIG generated mumble_wrap.c and mumble.pm files. It separates the naming of library boot code from the naming of packages. Thus making the library files compatible with Inline, while retaining the desired package names.

Normally, a SWIG .pm file loads the associated library. To avoid fighting with Inline, Inline::SWIG instead loads the .pm file from the library. The .pm file is renamed, its loading code removed, and a ``require'' inserted into the mumble_wrap.c initialization code.

BUGS AND CAUTIONS

This package is a kludge on top of two unstable codebases.

Inline::SWIG v0.00 was tested with SWIG v1.3.15, and Inline v0.43.

Inline::SWIG does regex substitutions into the SWIG's output code. And SWIG's perl support is currently (ver 1.3.15, 2002-Sep) in a state of flux. And even SWIG command line options are unstable. So new versions of SWIG are likely to break Inline::SWIG.

Inline::SWIG inherits from Inline::C, which is part of Inline. So changes to Inline and Inline::C may cause problems.

Testing has been very limited. It follows that bugs are very common.

AUTHOR

Mitchell N Charity <[email protected]>

COPYRIGHT

 Copyright (c) 2002, Mitchell N Charity. 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)