From 34e3e3fd25b09000d052b329f764f39d490fd280 Mon Sep 17 00:00:00 2001 From: William S Fulton Date: Thu, 2 Sep 2004 20:23:48 +0000 Subject: [PATCH] %feature("shadow") patch from Christoph Flamm git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@6210 626c5289-ae23-0410-ae9c-e8d60b6d4f22 --- Doc/Manual/Perl5.html | 57 +++++++++++++++++++++++++++++++------------ 1 file changed, 42 insertions(+), 15 deletions(-) diff --git a/Doc/Manual/Perl5.html b/Doc/Manual/Perl5.html index b144d8874..313e2aa2c 100644 --- a/Doc/Manual/Perl5.html +++ b/Doc/Manual/Perl5.html @@ -61,8 +61,9 @@
  • Structure and class wrappers
  • Object Ownership
  • Nested Objects -
  • Shadow Functions +
  • Proxy Functions
  • Inheritance +
  • Modifying the proxy methods @@ -2311,7 +2312,8 @@ For example:

    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.

    @@ -2319,12 +2321,12 @@ details of the proxy interface.

    23.9.1 Preliminaries

    -To generate proxy classes, you need to use the -proxy command line option. +Proxy classes, are generated by default. If you want to turn them off, use the -noproxy command line option. For example: 
    -$ swig -c++ -perl -proxy example.i
+$ swig -c++ -perl -noproxy example.i
    @@ -2436,7 +2438,7 @@ internally and described shortly.

    -To use our new shadow class we can simply do the following: +To use our new proxy class we can simply do the following: 

    @@ -2464,7 +2466,7 @@ $v->DESTROY();
 
 
 
    
-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 :
 
    
@@ -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
 %OWNER 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 {
 
 
    
 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 %BLESSEDMEMBERS hash which would
 look like this (along with some supporting code) :
 
    
@@ -2600,12 +2602,12 @@ $p->{f}->{x} = 0.0;
 %${$p->{v}} = ( x=>0, y=>0, z=>0);
    -

    23.9.5 Shadow Functions

    +

    23.9.5 Proxy Functions

    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 : 

    @@ -2613,7 +2615,7 @@ double dot_product(Vector *v1, Vector *v2);

    -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 Circle and Square classes inherit functions from Shape so we'll want to look in the Shape base class for them. All classes also inherit from the top-level module shapes. 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.

    -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 @ISA 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).

    -
    +

    23.9.7 Modifying the proxy methods

    + + +It is possible to override the SWIG generated proxy/shadow methods, using %feature("shadow"). +It works like all the other %feature directives. +Here is a simple example showing how to add some Perl debug code to the constructor: + +
    +/* 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);
+  ...
+};
+
    + + -
    SWIG 1.3 - Last Modified : Feb 13, 2003