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

Nested classes support

Browse source 
Closes #89
Squash merge branch 'master' of https://github.com/wkalinin/swig into wkalinin-nested

By Vladimir Kalinin
* 'master' of https://github.com/wkalinin/swig:
  CPlusPlusOut mode for Octave
  nested class illustration
  fixed "Abstract" flag for nested classes added an example enabled anonymous nested structs runtime test
  porting
  warnings disabled
  porting fixes
  java runtime tests ported
  nested class closing bracket offset fixed
  removed double nested template (not supported by %template parsing)
  template_nested test extended
  parent field made public
  property access fixed
  replaced tabs with spaces
  warning W-reorder
  deprecated warnings removed, derived_nested runtime test added
  optimized string indenting
  Nested classes indenting
  nested classes docs
  fixed the order in which flattened inner classes are added after the outer
  Private nested classes were getting into the type table.
  Java getProxyName() fix for nested classes fixes the case when nested classes is forward declared
  Fix for a case when a nested class inherits from the same base as the outer. (Base class constructor declaration is found first in this case)
  merge fix
  nested C struct first immediate declaration incorrectly renamed sample fixed
  tests updated to reflect nested classes support
  Java nested classes support (1)
  flattening should remove the link to the outer class
  access mode correctly set/restored for nested classes
  nested templates should be skipped while flattening (template nodes themselves, not expanded versions) also non-public nested classes should be ignored
  If nested classes are not supported, default behaviour is flattening, not ignoring flag "nested" is preserved, so, the nested classes can be ignored by user
  nested workaround test updated
  template instantiated within a class is marked as nested for ignoring purposes
  %ignore not applied to the nested classed, because "nested" flag is set too late
  typedef name takes precedence over the real name (reason?)
  unnamed structs should be processed for all the languages
  nested C struct instances are wrapped as "immutable"
  tree building
  typedef declaration for unnamed C structures fixed
  nested classes "flattening"
  fixed %ignoring nested classes
  renamed "nested" attribute to "nested:outer" added "nested" flag, to be used with $ignore (it is not removed while flattening) added nestedClassesSupported() function to the Language interface
  renamed "nested" attribute to "nested:outer" added "nested" flag, to be used with $ignore (it is not removed while flattening) added nestedClassesSupported() function to the Language interface
  tree iteration fix
  dirclassname variable names unified memory issue fixed
  merge error
  ignore unnamed structs for C++
  unnamed nested C structs naming & unnesting
  class added to classes hash under typedef name
  private nested classes skipped
  test updated due to nested templates support
  anonymous structs with inheritance fixed nested_class test to allow anonymous structs w/o declarator
  tests updated: nested workaround removed from namespace_class.i propagated nested template declaration to the C++ file
  injected members scope
  nested tempplates fixes, nested structures in "C" mode parsing added utility function "appendSibling" (like "appendChild")
  nested unnamed structures parsing fixes, access mode restored on nested class end, tdname is properly patched with outer class name prefix
  memory management fixes
  nested templates (1)
  Nested unnamed structs
  Nested class support (1)
  Nested class support (1)
This commit is contained in:
Vladimir Kalinin 2013-11-28 07:32:23 +00:00 • committed by William S Fulton
commit b63c4839fe
39 changed files with 1449 additions and 1111 deletions
Download patch file Download diff file Expand all files Collapse all files

144
Doc/Manual/SWIGPlus.html
View file

@ -185,7 +185,6 @@ The following C++ features are not currently supported:</p>
<ul>
<li>Overloaded versions of certain operators (new, delete, etc.)
<li>Nested classes, see <a href="#SWIGPlus_nested_classes">Nested classes</a> for workarounds.
</ul>
<p>
@ -4965,143 +4964,40 @@ public:
<H2><a name="SWIGPlus_nested_classes"></a>6.27 Nested classes</H2>
<p>
There is some support for nested structs and unions when wrapping C code,
see <a href="SWIG.html#SWIG_nested_structs">Nested structures</a> for further details.
The added complexity of C++ compared to C means this approach does not work well for
C++ code (when using the -c++ command line option).
For C++, a nested class is treated much like an opaque pointer, so anything useful within the nested class, such as its
methods and variables, are not accessible from the target language.
True nested class support may be added to SWIG in the future, however,
until then some of the following workarounds can be applied to improve the situation.
If the target language supports the nested classes concept (like Java), the nested C++ classes
are wrapped as nested target language proxy classes. (In case of Java - "static" nested classes.)
Only public nested classes are wrapped. Otherwise there is little difference between nested and
normal classes.
</p>
<p>
It might be possible to use partial class information as often you can accept that the nested class is not needed,
especially if it is not actually used in any methods you need from the target language.
Imagine you are wrapping the following <tt>Outer</tt> class which contains a nested class <tt>Inner</tt>.
The easiest thing to do is turn a blind eye to the warning that SWIG generates, or simply suppress it:
If the target language doesn't support nested classes directly, or the support is not implemented in the
language module (like for python currently), then the visible nested classes are moved to the same name
space as the containing class (nesting hierarchy is "flattened"). The same behaviour may be turned on for
C# and Java by the %feature ("flatnested"); If there is a class with the same name in the outer namespace
the inner class (or the global one) may be renamed or ignored:
</p>
<div class="code">
<pre>
%warnfilter(SWIGWARN_PARSE_NAMED_NESTED_CLASS) Outer::Inner;
class Outer {
public:
class Inner {
public:
...
};
Inner getInner();
void useInner(const Inner&amp; inner);
...
};
</pre>
</div>
<p>
Note that if <tt>Inner</tt> can be used as an opaque type, the default wrapping approach suffices.
For example, if the nested class does not need to be created from the target language, but can be obtained via a method
call, such as the <tt>getInner()</tt> method above, the returned value can then be passed around, such as passed into the
<tt>useInner()</tt> method.
</p>
<p>
With some more effort the above situation can be improved somewhat and a nested class can be constructed and used
from the target language much like any other non-nested class. Assuming we have the <tt>Outer</tt> class in a header file:
</p>
<div class="code">
<pre>
// File outer.h
class Outer {
public:
class Inner {
public:
int var;
Inner(int v = 0) : var(v) {}
};
Inner getInner();
void useInner(const Inner&amp; inner);
};
</pre>
</div>
<p>
The following interface file works around the nested class limitations by redefining the nested class as a global class.
A typedef for the compiler and the <tt>nestedworkaround</tt>
<a href="Customization.html#Customization_feature_flags">feature flag</a> is also required in
order for the generated wrappers to compile. This flag simply removes all the type information from SWIG, so SWIG treats
the nested class as if it had not been parsed at all.
</p>
<div class="code">
<pre>
// File : example.i
%module example
// Redefine nested class in global scope in order for SWIG to generate
// a proxy class. Only SWIG parses this definition.
class Inner {
%rename (Bar_Foo) Bar::Foo;
class Foo {};
class Bar {
public:
int var;
Inner(int v = 0) : var(v) {}
};
%nestedworkaround Outer::Inner;
%{
#include "outer.h"
%}
%include "outer.h"
// We've fooled SWIG into thinking that Inner is a global class, so now we need
// to trick the C++ compiler into understanding this apparent global type.
%{
typedef Outer::Inner Inner;
%}
</pre>
</div>
<p>
The downside to this approach is a more complex interface file and having to maintain two definitions of <tt>Inner</tt>,
the real one and the one in the interface file that SWIG parses.
However, the upside is that all the methods/variables in the nested class are available from the target language
as a proxy class is generated instead of treating the nested class as an opaque type.
The proxy class can be constructed from the target language and passed into any methods accepting the nested class.
Also note that the original header file is parsed unmodified.
</p>
<p>
Finally, conditional compilation can be used as a workaround to comment out nested class definitions in the actual headers,
assuming you are able to modify them.
</p>
<div class="code">
<pre>
// File outer.h
class Outer {
public:
#ifndef SWIG
class Inner {
public:
...
};
#endif
...
class Foo {};
};
</pre>
</div>
<p>
This workaround used to be common when SWIG could not deal with nested classes particulary well.
This should just be a last resort for unusual corner cases now as SWIG can parse nested classes and even handle nested template classes fairly well.
</p>
<p>
<b>Compatibility Note:</b> SWIG-1.3.40 and earlier versions did not have the <tt>nestedworkaround</tt> feature
<b>Compatibility Note:</b>
In SWIG 2.0 and earlier, nested classes were treated as opaque pointers.
Also there was a workaround, implementing approximately the same behaviour as the
%feature ("flatnested") with an additional help from the user:
nested class had to be manually redeclared in the global scope, typedef name and %feature nestedworkaround
added for the inner class.
SWIG-1.3.40 and earlier versions did not have the <tt>nestedworkaround</tt> feature
and the generated code resulting from parsing nested classes did not always compile.
Nested class warnings could also not be suppressed using %warnfilter.
</p>