From b63c4839fe60b8192809ef94d078ef07305144c5 Mon Sep 17 00:00:00 2001 From: Vladimir Kalinin Date: Thu, 28 Nov 2013 07:32:23 +0000 Subject: Nested classes support 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) --- Doc/Manual/SWIGPlus.html | 144 +++++++---------------------------------------- 1 file changed, 20 insertions(+), 124 deletions(-) (limited to 'Doc/Manual') diff --git a/Doc/Manual/SWIGPlus.html b/Doc/Manual/SWIGPlus.html index 2713725d7..2ec98f33a 100644 --- a/Doc/Manual/SWIGPlus.html +++ b/Doc/Manual/SWIGPlus.html @@ -185,7 +185,6 @@ The following C++ features are not currently supported:

@@ -4965,143 +4964,40 @@ public:

6.27 Nested classes

- -

-There is some support for nested structs and unions when wrapping C code, -see Nested structures 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. -

-

-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 Outer class which contains a nested class Inner. -The easiest thing to do is turn a blind eye to the warning that SWIG generates, or simply suppress it: +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.

- -
-
-%warnfilter(SWIGWARN_PARSE_NAMED_NESTED_CLASS) Outer::Inner;
-
-class Outer {
-public:
-  class Inner {
-    public:
-      ...
-  };
-  Inner getInner();
-  void useInner(const Inner& inner);
-  ...
-};
-
-
- -

-Note that if Inner 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 getInner() method above, the returned value can then be passed around, such as passed into the -useInner() method. -

- -

-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 Outer class in a header file: -

- -
-
-// File outer.h
-class Outer {
-public:
-  class Inner {
-    public:
-      int var;
-      Inner(int v = 0) : var(v) {}
-  };
-  Inner getInner();
-  void useInner(const Inner& inner);
-};
-
-
-

-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 nestedworkaround -feature flag 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. +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: 

-// 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;
-%}
-
-
- -

-The downside to this approach is a more complex interface file and having to maintain two definitions of Inner, -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. -

- -

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

- -
-
-// File outer.h
-class Outer {
-public:
-#ifndef SWIG
-  class Inner {
-    public:
-      ...
-  };
-#endif
-  ...
+  class Foo {};
 };
-

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

-Compatibility Note: SWIG-1.3.40 and earlier versions did not have the nestedworkaround feature +Compatibility Note: +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 nestedworkaround feature and the generated code resulting from parsing nested classes did not always compile. Nested class warnings could also not be suppressed using %warnfilter.

-- cgit v1.2.3 From 0f4ceaf5923fd9a30eb9201048cd285a9bba8084 Mon Sep 17 00:00:00 2001 From: William S Fulton Date: Fri, 13 Dec 2013 08:11:17 +0000 Subject: Deprecation of the 'nestedworkaround' feature Also add in macros for the flatnested feature which can be used in place of the nestedworkaround feature --- Doc/Manual/SWIGPlus.html | 26 +++++++++++++++++++++----- Doc/Manual/Warnings.html | 1 + 2 files changed, 22 insertions(+), 5 deletions(-) (limited to 'Doc/Manual') diff --git a/Doc/Manual/SWIGPlus.html b/Doc/Manual/SWIGPlus.html index 2ec98f33a..20c03cc71 100644 --- a/Doc/Manual/SWIGPlus.html +++ b/Doc/Manual/SWIGPlus.html @@ -4992,11 +4992,27 @@ class Bar {

Compatibility Note: -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. +Prior to SWIG-3.0.0, there was limited nested class support. Nested classes were treated as opaque pointers. +However, there was a workaround for nested class support in these older versions requiring the user to replicate +the nested class in the global scope, adding in a typedef for the nested class in the global scope and +using the "nestedworkaround" feature on the nested class. This resulted in approximately the +same behaviour as the "flatnested" feature. With proper nested class support now available in SWIG-3.0.0, this +feature has been deprecated and no longer works requiring code changes. If you see the following warning: +

+ +
+
+example.i:8: Warning 126: The nestedworkaround feature is deprecated
+
+
+ +

+consider using the "flatnested" feature discussed above which generates a non-nested proxy class, like the +"nestedworkaround" feature did. Alternatively, use the default nested class code generation, which may generate an +equivalent to a nested proxy class in the target language, depending on the target language support. +

+ +

SWIG-1.3.40 and earlier versions did not have the nestedworkaround feature and the generated code resulting from parsing nested classes did not always compile. Nested class warnings could also not be suppressed using %warnfilter. diff --git a/Doc/Manual/Warnings.html b/Doc/Manual/Warnings.html index e0debe41c..b4d27872c 100644 --- a/Doc/Manual/Warnings.html +++ b/Doc/Manual/Warnings.html @@ -382,6 +382,7 @@ example.i(4) : Syntax error in input.

  • 119. Deprecated %typemap(ignore).
  • 120. Deprecated command line option (-runtime, -noruntime).
  • 121. Deprecated %name directive. +
  • 126. The 'nestedworkaround' feature is deprecated.

    14.9.2 Preprocessor (200-299)

    -- cgit v1.2.3