[Swig-cvs] SWIG/Doc/Manual Perl5.html,1.12,1.13

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 454-5900

Update of /cvsroot/swig/SWIG/Doc/Manual
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv19497/Doc/Manual

Modified Files:
	Perl5.html 
Log Message:
%feature("shadow") patch from Christoph Flamm

Index: Perl5.html
===================================================================
RCS file: /cvsroot/swig/SWIG/Doc/Manual/Perl5.html,v
retrieving revision 1.12
retrieving revision 1.13
diff -C2 -d -r1.12 -r1.13
*** Perl5.html	24 Aug 2004 22:21:15 -0000	1.12
--- Perl5.html	2 Sep 2004 20:23:48 -0000	1.13
***************
*** 62,67 ****
  <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_nn45">Inheritance</a>
  </ul>
  </ul>
--- 62,68 ----
  <li><a href="#Perl5_nn42">Object Ownership</a>
  <li><a href="#Perl5_nn43">Nested Objects</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>
***************
*** 2312,2316 ****
  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
  to the underlying code.  This section describes the implementation
  details of the proxy interface.
--- 2313,2318 ----
  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 (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.
***************
*** 2320,2329 ****

! To generate proxy classes, you need to use the <tt>-proxy</tt> command line option.
 For example:

  <blockquote>
  <pre>
! $ swig -c++ -perl -proxy example.i
  </pre>
  </blockquote>
--- 2322,2331 ----

! 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 -noproxy example.i
  </pre>
  </blockquote>
***************
*** 2437,2441 ****

! To use our new shadow class we can simply do the following:

--- 2439,2443 ----

! To use our new proxy class we can simply do the following:

***************
*** 2465,2469 ****

  <p>
! In order for shadow 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 :
--- 2467,2471 ----

  <p>
! 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 :
***************
*** 2507,2511 ****
  (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
  <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
--- 2509,2513 ----
  (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 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
***************
*** 2567,2571 ****
  <p>
  In this case, the members of the structure are complex objects that
! have already been encapsulated in a Perl shadow class.  To handle
  these correctly, we use the <tt>%BLESSEDMEMBERS</tt> hash which would
  look like this (along with some supporting code) :
--- 2569,2573 ----
  <p>
  In this case, the members of the structure are complex objects that
! 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) :
***************
*** 2601,2610 ****
  </pre></blockquote>

! <H3><a name="Perl5_nn44"></a>23.9.5 Shadow Functions</H3>

When functions take arguments involving a complex object, it is
! sometimes necessary to write a shadow function. For example :

--- 2603,2612 ----
  </pre></blockquote>

! <H3><a name="Perl5_nn44"></a>23.9.5 Proxy Functions</H3>

When functions take arguments involving a complex object, it is
! sometimes necessary to write a proxy function. For example :

***************
*** 2614,2618 ****

  <p>
! Since Vector is an object already wrapped into a shadow 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
--- 2616,2620 ----

  <p>
! 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
***************
*** 2697,2701 ****
  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
  are implemented only once and reused in the wrapper code for various
  classes and structures.
--- 2699,2703 ----
  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 proxy classes
  are implemented only once and reused in the wrapper code for various
  classes and structures.
***************
*** 2703,2707 ****

  <p>
! Since SWIG shadow 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
--- 2705,2709 ----

! 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
***************
*** 2711,2717 ****

! <hr>

- <address>SWIG 1.3 - Last Modified : Feb 13, 2003</address>
  </body>
  </html>
--- 2713,2744 ----
  </p>

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

  </body>
  </html>

[Swig-cvs] SWIG/Doc/Manual Perl5.html,1.12,1.13

A code generator for connecting C/C++ with other programming languages

[Swig-cvs] SWIG/Doc/Manual Perl5.html,1.12,1.13