%feature("shadow") patch from Christoph Flamm

git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@6210 626c5289-ae23-0410-ae9c-e8d60b6d4f22

SWIG/Doc/Manual/Perl5.html

@@ -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>