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

Move %attribute documentation into the manual

Browse source 
It's fairly hidden where it is, put it where users can see it more
easily.

Fixes #2166
This commit is contained in:
Corey Minyard 2022-01-26 09:12:10 -06:00
commit f77af57bd7
3 changed files with 212 additions and 131 deletions
Download patch file Download diff file Expand all files Collapse all files

1
Doc/Manual/Contents.html
View file

@ -184,6 +184,7 @@
<li><a href="SWIG.html#SWIG_nn32">Typedef and structures</a> <li><a href="SWIG.html#SWIG_nn32">Typedef and structures</a>
<li><a href="SWIG.html#SWIG_nn33">Character strings and structures</a> <li><a href="SWIG.html#SWIG_nn33">Character strings and structures</a>
<li><a href="SWIG.html#SWIG_nn34">Array members</a> <li><a href="SWIG.html#SWIG_nn34">Array members</a>
<li><a href="SWIG.html#Attributes">Attributes and the %attribute directive</a>
<li><a href="SWIG.html#SWIG_structure_data_members">Structure data members</a> <li><a href="SWIG.html#SWIG_structure_data_members">Structure data members</a>
<li><a href="SWIG.html#SWIG_nn36">C constructors and destructors</a> <li><a href="SWIG.html#SWIG_nn36">C constructors and destructors</a>
<li><a href="SWIG.html#SWIG_adding_member_functions">Adding member functions to C structures</a> <li><a href="SWIG.html#SWIG_adding_member_functions">Adding member functions to C structures</a>

216
Doc/Manual/SWIG.html
View file

@ -59,6 +59,7 @@
<li><a href="#SWIG_nn32">Typedef and structures</a> <li><a href="#SWIG_nn32">Typedef and structures</a>
<li><a href="#SWIG_nn33">Character strings and structures</a> <li><a href="#SWIG_nn33">Character strings and structures</a>
<li><a href="#SWIG_nn34">Array members</a> <li><a href="#SWIG_nn34">Array members</a>
<li><a href="#Attributes">Attributes and the %attribute directive</a>
<li><a href="#SWIG_structure_data_members">Structure data members</a> <li><a href="#SWIG_structure_data_members">Structure data members</a>
<li><a href="#SWIG_nn36">C constructors and destructors</a> <li><a href="#SWIG_nn36">C constructors and destructors</a>
<li><a href="#SWIG_adding_member_functions">Adding member functions to C structures</a> <li><a href="#SWIG_adding_member_functions">Adding member functions to C structures</a>
@ -2635,7 +2636,212 @@ discussed in a later chapter. In many cases, the warning message is
harmless. harmless.
</p> </p>
<H3><a name="SWIG_structure_data_members">5.5.4 Structure data members</a></H3> <H3><a name="Attributes">5.5.4 Attributes and the %attribute directive</a></H3>
<p>
Use <tt>%attribute</tt> when you have a pair of get/set methods to a
primitive type like in:
</p>
<div class="code">
<pre>
%attribute(A, int, a, get_a, set_a);
struct A
{
int get_a() const;
void set_a(int aa);
};
</pre>
</div>
<p>
and you want to provide that variable as an attribute in the target
langage. This examples only works for primitive types, not derived
types. If you don't provide a 'set' method, a 'read-only' attribute
is generated, ie, like in:
</p>
<div class="code">
<pre>
%attribute(A, int, c, get_c);
</pre>
</div>
<p>
Use <tt>%attributeref</tt> when you have const/non-const reference
access methods for primitive types or class/structs, like in:
</p>
<div class="code">
<pre>
%attributeref(A, int, b);
struct A
{
const int& b() const;
int& b();
};
%attributeref(B, int, c);
struct B
{
int& c();
};
</pre>
</div>
<p>
You can also use
</p>
<div class="code">
<pre>
%attributeref(Class, AttributeType, AttributeName, AccessorMethod)
</pre>
</div>
<p>
if the internal C++ reference methods have a different name from the
attribute you want, so
</p>
<div class="code">
<pre>
%attributeref(B, int, d, c);
</pre>
</div>
<p>
is the same as the last example, but instead of the attribute 'c' being
called 'c', it is called 'd'.
</p>
<p>
Now you can use the attributes like so:
</p>
<div class="code">
<pre>
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
</pre>
</div>
<p>
Use <tt>%attribute2</tt> instead of <tt>%attribute</tt> to indicate
that reference-pointer translation is required. You
use <tt>%attribute2</tt> instead of <tt>%attribute</tt> in cases like
this:
</p>
<div class="code">
<pre>
%attribute2(MyClass, MyFoo, Foo, GetFoo, SetFoo);
%inline %{
struct MyFoo {
int x;
};
class MyClass {
MyFoo foo;
public:
MyFoo& GetFoo() { return foo; }
void SetFoo(const MyFoo& other) { foo = other; }
};
%}
</pre>
</div>
<p>
Here, the data type of the property is a wrapped type (MyFoo) and on
the C++ side it is passed by reference. The problem is that the SWIG
wrapper will pass around a pointer (MyFoo *) which is not compatible
with the reference type of the accessors (MyFoo &). Therefore, if you
use <tt>%attribute</tt>, you'll get an error from your C/C++
compiler. <tt>%attribute2</tt> translates between a pointer and a
reference to eliminate the error. In case you're confused, let's make
it simple: just use <tt>%attribute</tt> at first, but if the C/C++
compiler gives an error while compiling the wrapper,
try <tt>%attribute2</tt> instead.
</p>
<p>
NOTE: remember that if the type contains commas, such as
'std::pair<int,int>', you need to use the macro like:
</p>
<div class="code">
<pre>
%attributeref(A, %arg(std::pair<int,int>), pval);
</pre>
</div>
<p>
where <tt>%arg()</tt> 'normalizes' the type to be understood as a single
argument, otherwise the macro will get confused by the comma.
</p>
<p>
The <tt>%attributeval</tt> is the same as <tt>%attribute</tt>, but
should be used when the type is a class/struct (ie a non-primitive
type) and when the get and set methods return/pass by value. The
following is very similar to the above example, but note that the
access is by value rather than reference.
</p>
<div class="code">
<pre>
%attributeval(MyClassVal, MyFoo, ReadWriteFoo, GetFoo, SetFoo);
%attributeval(MyClassVal, MyFoo, ReadOnlyFoo, GetFoo);
%inline %{
class MyClassVal {
MyFoo foo;
public:
MyFoo GetFoo() { return foo; }
void SetFoo(MyFoo other) { foo = other; }
};
%}
</pre>
</div>
<p>
The <tt>%attributestring</tt> is the same as <tt>%attributeval</tt>,
but should be used for string class types, which are unusual as they
are a class on the C++ side, but normally an immutable/primitive type
in the target language. Example usage for std::string:
</p>
<div class="code">
<pre>
%include <std_string.i>
%attributestring(MyStringyClass, std::string, ReadWriteString, GetString, SetString);
%attributestring(MyStringyClass, std::string, ReadOnlyString, GetString);
%inline %{
class MyStringyClass {
std::string str;
public:
MyStringyClass(const std::string &val) : str(val) {}
std::string GetString() { return str; }
void SetString(std::string other) { str = other; }
};
%}
</pre>
</div>
<p>
The <tt>%attributestring</tt> also works for class types that
have <tt>%naturalvar</tt> turned on and so is also useful for
shared_ptr which has <tt>%naturalvar</tt> turned on in
<tt>%shared</tt>_ptr.
</p>
<H3><a name="SWIG_structure_data_members">5.5.5 Structure data members</a></H3>
<p> <p>
@ -2741,7 +2947,7 @@ class, or union. This is unlikely to break existing code. However, if you need
datatype is really a struct, simply use a forward struct declaration such as <tt>"struct Foo;"</tt>. datatype is really a struct, simply use a forward struct declaration such as <tt>"struct Foo;"</tt>.
</p> </p>
<H3><a name="SWIG_nn36">5.5.5 C constructors and destructors</a></H3> <H3><a name="SWIG_nn36">5.5.6 C constructors and destructors</a></H3>
<p> <p>
@ -2830,7 +3036,7 @@ the target languages, and it is highly recommended you don't use them.
</p> </p>
<H3><a name="SWIG_adding_member_functions">5.5.6 Adding member functions to C structures</a></H3> <H3><a name="SWIG_adding_member_functions">5.5.7 Adding member functions to C structures</a></H3>
<p> <p>
@ -3103,7 +3309,7 @@ be used to extend a structure with more than just methods, a more suitable
directive name has been chosen. directive name has been chosen.
</p> </p>
<H3><a name="SWIG_nested_structs">5.5.7 Nested structures</a></H3> <H3><a name="SWIG_nested_structs">5.5.8 Nested structures</a></H3>
<p> <p>
@ -3187,7 +3393,7 @@ Finally, note that nesting is handled differently in C++ mode,
see <a href="SWIGPlus.html#SWIGPlus_nested_classes">Nested classes</a>. see <a href="SWIGPlus.html#SWIGPlus_nested_classes">Nested classes</a>.
</p> </p>
<H3><a name="SWIG_nn39">5.5.8 Other things to note about structure wrapping</a></H3> <H3><a name="SWIG_nn39">5.5.9 Other things to note about structure wrapping</a></H3>
<p> <p>

126
Lib/typemaps/attribute.swg
View file

@ -7,132 +7,6 @@
/* /*
The following macros convert a pair of set/get methods The following macros convert a pair of set/get methods
into a "native" attribute. into a "native" attribute.
Use %attribute when you have a pair of get/set methods to a primitive type
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 %attributeref when you have const/non-const reference access methods
for primitive types or class/structs, like in:
%attributeref(A, int, b);
struct A
{
const int& b() const;
int& b();
};
%attributeref(B, int, c);
struct B
{
int& c();
};
You can also use
%attributeref(Class, AttributeType, AttributeName, AccessorMethod)
if the internal C++ reference methods have a different name from the
attribute you want, so
%attributeref(B, int, d, c);
is the same as the last example, but instead of the attribute 'c' being
called 'c', it is called 'd'.
Now you can use the attributes like so:
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
Use %attribute2 instead of %attribute to indicate that reference-pointer
translation is required. You use %attribute2 instead of %attribute in
cases like this:
%attribute2(MyClass, MyFoo, Foo, GetFoo, SetFoo);
%inline %{
struct MyFoo {
int x;
};
class MyClass {
MyFoo foo;
public:
MyFoo& GetFoo() { return foo; }
void SetFoo(const MyFoo& other) { foo = other; }
};
%}
Here, the data type of the property is a wrapped type (MyFoo) and on the
C++ side it is passed by reference. The problem is that the SWIG wrapper will
pass around a pointer (MyFoo *) which is not compatible with the reference
type of the accessors (MyFoo &). Therefore, if you use %attribute, you'll get
an error from your C/C++ compiler. %attribute2 translates between a pointer
and a reference to eliminate the error. In case you're confused, let's make it
simple: just use %attribute at first, but if the C/C++ compiler gives an error
while compiling the wrapper, try %attribute2 instead.
NOTE: remember that if the type contains commas, such as 'std::pair<int,int>',
you need to use the macro like:
%attributeref(A, %arg(std::pair<int,int>), pval);
where %arg() 'normalizes' the type to be understood as a single
argument, otherwise the macro will get confused by the comma.
The %attributeval is the same as %attribute, but should be used when the type
is a class/struct (ie a non-primitive type) and when the get and set methods
return/pass by value. The following is very similar to the above example, but
note that the access is by value rather than reference.
%attributeval(MyClassVal, MyFoo, ReadWriteFoo, GetFoo, SetFoo);
%attributeval(MyClassVal, MyFoo, ReadOnlyFoo, GetFoo);
%inline %{
class MyClassVal {
MyFoo foo;
public:
MyFoo GetFoo() { return foo; }
void SetFoo(MyFoo other) { foo = other; }
};
%}
The %attributestring is the same as %attributeval, but should be used for string
class types, which are unusual as they are a class on the C++ side, but normally an
immutable/primitive type in the target language. Example usage for std::string:
%include <std_string.i>
%attributestring(MyStringyClass, std::string, ReadWriteString, GetString, SetString);
%attributestring(MyStringyClass, std::string, ReadOnlyString, GetString);
%inline %{
class MyStringyClass {
std::string str;
public:
MyStringyClass(const std::string &val) : str(val) {}
std::string GetString() { return str; }
void SetString(std::string other) { str = other; }
};
%}
The %attributestring also works for class types that have %naturalvar turned
on and so is also useful for shared_ptr which has %naturalvar turned on in %shared_ptr.
*/ */
// //