jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

%feature("shadow") patch from Christoph Flamm

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@6210 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
William S Fulton 2004-09-02 20:23:48 +00:00
commit f2f49e600a
1 changed files with 42 additions and 15 deletions
Download patch file Download diff file Expand all files Collapse all files

57
SWIG/Doc/Manual/Perl5.html
View file

@ -61,8 +61,9 @@
<li><a href="#Perl5_nn41">Structure and class wrappers</a>
<li><a href="#Perl5_nn42">Object Ownership</a>
<li><a href="#Perl5_nn43">Nested Objects</a>
<li><a href="#Perl5_nn44">Shadow Functions</a>
<li><a href="#Perl5_nn44">Proxy Functions</a>
<li><a href="#Perl5_nn45">Inheritance</a>
<li><a href="#Perl5_nn46">Modifying the proxy methods</a>
</ul>
</ul>
<!-- INDEX -->
@ -2311,7 +2312,8 @@ For example:
<p>
Using the low-level procedural interface, SWIG can also construct a
high-level object oriented interface to C structures and C++ classes.
This is done by constructing a Perl proxy class that provides an OO wrapper
This is done by constructing a Perl proxy class (also known as a shadow class)
that provides an OO wrapper
to the underlying code. This section describes the implementation
details of the proxy interface.
</p>
@ -2319,12 +2321,12 @@ details of the proxy interface.
<H3><a name="Perl5_nn40"></a>23.9.1 Preliminaries</H3>
To generate proxy classes, you need to use the <tt>-proxy</tt> command line option.
Proxy classes, are generated by default. If you want to turn them off, use the <tt>-noproxy</tt> command line option.
For example:
<blockquote>
<pre>
$ swig -c++ -perl -proxy example.i
$ swig -c++ -perl -noproxy example.i
</pre>
</blockquote>
@ -2436,7 +2438,7 @@ internally and described shortly.
</p>
<p>
To use our new shadow class we can simply do the following:
To use our new proxy class we can simply do the following:
</p>
<blockquote><pre>
@ -2464,7 +2466,7 @@ $v-&gt;DESTROY();
<p>
In order for shadow classes to work properly, it is necessary for Perl
In order for proxy classes to work properly, it is necessary for Perl
to manage some mechanism of object ownership. Here's the crux of the
problem---suppose you had a function like this :
</p>
@ -2506,7 +2508,7 @@ of all of the objects that Perl knows that it has created. This
happens in two cases: (1) when the constructor has been called, and
(2) when a function implicitly creates a new object (as is done when
SWIG needs to return a complex datatype by value). When the
destructor is invoked, the Perl shadow class module checks the
destructor is invoked, the Perl proxy class module checks the
<tt>%OWNER</tt> hash to see if Perl created the object. If so, the
C/C++ destructor is invoked. If not, we simply destroy the Perl
object and leave the underlying C object alone (under the assumption
@ -2566,7 +2568,7 @@ struct Particle {
<p>
In this case, the members of the structure are complex objects that
have already been encapsulated in a Perl shadow class. To handle
have already been encapsulated in a Perl proxy class. To handle
these correctly, we use the <tt>%BLESSEDMEMBERS</tt> hash which would
look like this (along with some supporting code) :
</p>
@ -2600,12 +2602,12 @@ $p-&gt;{f}-&gt;{x} = 0.0;
%${$p-&gt;{v}} = ( x=&gt;0, y=&gt;0, z=&gt;0);
</pre></blockquote>
<H3><a name="Perl5_nn44"></a>23.9.5 Shadow Functions</H3>
<H3><a name="Perl5_nn44"></a>23.9.5 Proxy Functions</H3>
<p>
When functions take arguments involving a complex object, it is
sometimes necessary to write a shadow function. For example :
sometimes necessary to write a proxy function. For example :
</p>
<blockquote><pre>
@ -2613,7 +2615,7 @@ double dot_product(Vector *v1, Vector *v2);
</pre></blockquote>
<p>
Since Vector is an object already wrapped into a shadow class, we need
Since Vector is an object already wrapped into a proxy class, we need
to modify this function to accept arguments that are given in the form
of tied hash tables. This is done by creating a Perl function like
this :
@ -2696,13 +2698,13 @@ particular class. In this case, both the <tt>Circle</tt> and
<tt>Square</tt> classes inherit functions from <tt>Shape</tt> so we'll
want to look in the <tt>Shape</tt> base class for them. All classes
also inherit from the top-level module <tt>shapes</tt>. This is
because certain common operations needed to implement shadow classes
because certain common operations needed to implement proxy classes
are implemented only once and reused in the wrapper code for various
classes and structures.
</p>
<p>
Since SWIG shadow classes are implemented in Perl, it is easy to
Since SWIG proxy classes are implemented in Perl, it is easy to
subclass from any SWIG generated class. To do this, simply put the
name of a SWIG class in the <tt>@ISA</tt> array for your new
class. However, be forewarned that this is not a trivial problem. In
@ -2710,8 +2712,33 @@ particular, inheritance of data members is extremely tricky (and I'm
not even sure if it really works).
</p>
<hr>
<H3><a name="Perl5_nn46"></a>23.9.7 Modifying the proxy methods</H3>
It is possible to override the SWIG generated proxy/shadow methods, using <tt>%feature("shadow")</tt>.
It works like all the other <a href="Customization.html#features">%feature directives</a>.
Here is a simple example showing how to add some Perl debug code to the constructor:
<blockquote><pre>
/* Let's make the constructor of the class Square more verbose */
%feature("shadow") Square(double w)
%{
sub new {
my $pkg = shift;
my $self = examplec::new_Square(@_);
print STDERR "Constructed an @{[ref($self)]}\n";
bless $self, $pkg if defined($self);
}
%}
class Square {
public:
Square(double w);
...
};
</pre></blockquote>
<address>SWIG 1.3 - Last Modified : Feb 13, 2003</address>
</body>
</html>