documenting attribute.i

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

CHANGES.current

@@ -1,6 +1,50 @@
 Version 1.3.27 (October 15, 2005)
 =================================
 
+10/26/2005: mmatus
+
+	  - Added the attribute.i file to the global library director.
+	    Now it can be used from other languages that do not use
+	    the unified typemap library as well.
+
+	    So, if you have something like:
+
+	       %include attribute.i
+
+               %attribute(A, int, a, get_a, set_a);
+	       				      	  
+	       struct A			      	  
+	       {    				  
+	         int get_a() const; 		  
+	         void set_a(int aa); 		  
+	       };				  
+
+               %attribute_ref(B, int, c);
+	       				
+	       struct B			
+	       {    			
+	         int& c(); 		
+	       }; 
+
+	    then in the target language the 'A.a' and 'B.c' attributes will
+	    be visible, ie, you can access them as plain variables:
+
+               f   = A()
+               f.a = 3
+               g   = B()
+               g.c = 3 
+           
+	       h   = f.a + g.c
+
+	    and the proper get/set methods will be dispatched. See
+	    attribute.i for more info.
+   
+          - More cleanups around and adding more test-cases. The
+            DISOWN typemap now is tested and working in all the
+            languages that use the unified typemap library, ie, tcl,
+            ruby, perl and python.
+	    
+
 10/25/2005: mmatus
 
 	    - Perl, complete the DISOWN typemap.

Lib/attribute.i

@@ -1,3 +1,71 @@
+/*
+  Attribute implementation using JOHN E LENZ ideas.
+
+  The following macros convert a pair of set/get methods
+  into a "native" attribute.
+
+  Use %attribute when you have a pair of get/set methods
+  like in:
+
+      %attribute(A, int, a, get_a, set_a);
+      				      
+      struct A			      
+      {    				      
+        int get_a() const; 		      
+        void set_a(int aa); 		      
+      };				      
+
+  If you don't provide a 'set' method, a 'read-only' attribute
+  is generated, ie, like in:
+
+      %attribute(A, int, c, get_c);
+
+
+  Use %attribute_ref when you have const/non-const reference
+  access methods, like in:
+
+      %attribute_ref(A, int, b);	   
+      				   
+      struct A			   
+      {    				   
+        const int& b() const; 	   
+        int& b(); 			   
+      };				   
+      				   
+      %attribute_ref(B, int, c);	   
+      				   
+      struct B			   
+      {    				   
+        int& c(); 			   
+      };                               
+
+  You can also use
+
+      %attribute_ref(class, type, refname, attr);
+  
+  if the internal C++ reference methods have a different name from the
+  attribute you want.
+  
+  Then you can use the instances like:
+
+      x = A() 			     
+      x.a = 3        # calls A::set_a    
+      print x.a      # calls A::get_a    
+      				     
+      x.b = 3        # calls A::b()      
+      print x.b      # calls A::b() const
+
+  NOTE: remember that if the type contains commas, such as
+  'std::pair<int,int>', you need to use the macro like:
+
+  %attribute_ref(A, %arg(std::pair<int,int>), pval);
+
+  where %arg() 'normalize' the type to be understood as a single
+  argument, otherwise the macro will get confused (see the 'cpp'
+  documentation).
+
+*/
+
 /* we use a simple exception warning here */
 %{
 #include <stdio.h>

Lib/typemaps/attribute.swg

@@ -7,60 +7,53 @@
   Use %attribute when you have a pair of get/set methods
   like in:
 
-  %attribute(A, int, a, get_a, set_a);
+      %attribute(A, int, a, get_a, set_a);
-
+      				      
-  struct A
+      struct A			      
-  {    
+      {    				      
-    int get_a() const 
+        int get_a() const; 		      
-    {
+        void set_a(int aa); 		      
-      return _a;
+      };				      
-    }
-    
-    void set_a(int aa) 
-    {
-      _a = aa;
-    }
-  };
 
   If you don't provide a 'set' method, a 'read-only' attribute
   is generated, ie, like in:
 
-  %attribute(A, int, c, get_c);
+      %attribute(A, int, c, get_c);
 
 
   Use %attribute_ref when you have const/non-const reference
   access methods, like in:
 
-  %attribute_ref(A, int, b);
+      %attribute_ref(A, int, b);	   
-
+      				   
-  struct A
+      struct A			   
-  {    
+      {    				   
-    const int& b() const 
+        const int& b() const; 	   
-    {
+        int& b(); 			   
-      return _b;
+      };				   
-    }
+      				   
-    
+      %attribute_ref(B, int, c);	   
-    int& b() 
+      				   
-    {
+      struct B			   
-      return _b;
+      {    				   
-    }
+        int& c(); 			   
-  };
+      };                               
 
   You can also use
 
-  %attribute_ref(class, type, refname, attr);
+      %attribute_ref(class, type, refname, attr);
   
   if the internal C++ reference methods have a different name from the
   attribute you want.
   
   Then you can use the instances like:
 
-  x = A() 
+      x = A() 			     
-  x.a = 3        # calls A::set_a
+      x.a = 3        # calls A::set_a    
-  print x.a      # calls A::get_a 
+      print x.a      # calls A::get_a    
-
+      				     
-  x.b = 3        # calls A::b() 
+      x.b = 3        # calls A::b()      
-  print x.b      # calls A::b() const
+      print x.b      # calls A::b() const
 
   NOTE: remember that if the type contains commas, such as
   'std::pair<int,int>', you need to use the macro like: