By default, SWIG flattens all C++ namespaces into a single target language namespace, but as for Java and C#, the nspace feature is supported for D. If it is active, C++ namespaces are mapped to D packages/modules. Note, however, that like for the other languages, free variables and functions are not supported yet; currently, they are all allows written to the main proxy D module.
+By default, SWIG flattens all C++ namespaces into a flattened D module hierarchy, but as for Java and C#, the nspace feature is supported for D. +If the feature is active, C++ namespaces are mapped to D packages/modules. +This includes the nspace feature flag for mirroring the C++ namespaces into D namespaces as a scoped D module/package name. +It also includes %nspacemove for transforming a C++ namespace into a completely different scoped D module/package name. +Note, however, that like for the other languages, free variables and functions are not supported yet; currently, they are all available in the main proxy D module.
The default behaviour described above can be improved via the nspace feature. Note that it only works for classes, structs, unions and enums declared within a named C++ namespace. -When the nspace feature is used, the C++ namespaces are converted into Java packages of the same name. +When the nspace feature is used (either the nspace feature flag or %nspacemove), the C++ namespaces are converted into Java packages of the same name. Proxy classes are thus declared within a package and this proxy makes numerous calls to the JNI intermediary class which is declared in the unnamed package by default. As Java does not support types declared in a named package accessing types declared in an unnamed package, the -package commandline option described earlier generally should be used to provide a parent package. So if SWIG is run using the -package com.myco option, a wrapped class, MyWorld::Material::Color, can then be accessed as com.myco.MyWorld.Material.Color. diff --git a/Doc/Manual/Lua.html b/Doc/Manual/Lua.html index 54b81cce2..86b8e10df 100644 --- a/Doc/Manual/Lua.html +++ b/Doc/Manual/Lua.html @@ -1377,13 +1377,15 @@ add exception specification to functions or globally (respectively).
-Since SWIG-3.0.0 C++ namespaces are supported via the %nspace feature. +C++ namespaces are supported via the %nspace feature.
-Namespaces are mapped into Lua tables. Each of those tables contains names that were defined within appropriate namespace. Namespaces structure (a.k.a nested namespaces) is preserved. Consider the following C++ code: +
Namespaces are mapped into Lua tables. Each of those tables contains names that were defined within an appropriate namespace. Namespace hierarchies (a.k.a nested namespaces) are preserved. Consider the following C++ code:
-%module example -%nspace MyWorld::Nested::Dweller; ++%module example + %nspace MyWorld::World; +%nspace MyWorld::Nested::Dweller; int module_function() { return 7; } int module_variable = 9; @@ -1411,34 +1413,69 @@ Now, from Lua usage is as follows:+ +> print(example.module_function()) -7 +7.0 > print(example.module_variable) -9 +9.0 > print(example.MyWorld.World():create_world()) -17 -> print(example.MyWorld.World.world_max_count) -9 +17.0 +> print(example.MyWorld.World().world_max_count) +9.0 > print(example.MyWorld.Nested.Dweller.MALE) 0 > print(example.MyWorld.Nested.Dweller.count()) -19 -> +19.0+The hierarchies in Lua are the same as the C++ hierarchies when using %nspace, +however, we could instead completely change these hierarchies with %nspacemove. +Consider the code above with the two %nspace lines of code removed and replaced with the following: +
+ ++ ++%nspacemove(DifferentWorld::SubSpace1::SubSpace2) MyWorld::World; +%nspacemove(DifferentWorld) MyWorld::Nested::Dweller; ++The Lua code uses the completely modified hierarchies: +
+ +++> print(example.module_function()) +7.0 +> print(example.module_variable) +9.0 +> print(example.DifferentWorld.SubSpace1.SubSpace2.World():create_world()) +17.0 +> print(example.DifferentWorld.SubSpace1.SubSpace2.World().world_max_count) +9.0 +> print(example.DifferentWorld.Dweller.MALE) +0 +> print(example.DifferentWorld.Dweller.count()) +19.0 +29.3.17.1 Compatibility Note
++The nspace feature was first supported by the Lua module in SWIG-3.0.0 +
+If SWIG is running in a backwards compatible way, i.e. without the -no-old-metatable-bindings option, then additional old-style names are generated (notice the underscore):
+-9 > print(example.MyWorld.Nested.Dweller_MALE) 0 > print(example.MyWorld.Nested.Dweller_count()) -11 -> +19.0+The ability to move symbols into different namespaces via %nspacemove was introduced in SWIG-4.3.0. +
29.3.17.2 Names
diff --git a/Doc/Manual/SWIGPlus.html b/Doc/Manual/SWIGPlus.html index 0d037e845..53782cd6e 100644 --- a/Doc/Manual/SWIGPlus.html +++ b/Doc/Manual/SWIGPlus.html @@ -72,6 +72,11 @@- Namespaces
- Renaming templated types in namespaces
- Exception specifications @@ -4763,15 +4768,31 @@ More advanced handling of namespaces is discussed next.
-Some target languages provide support for the nspace feature. -The feature can be applied to any class, struct, union or enum declared within a named namespace. -The feature wraps the type within the target language specific concept of a namespace, -for example, a Java package or C# namespace. -Please see the language specific sections to see if the target language you are interested in supports the nspace feature. +The nspace feature operates in two modes. +Firstly, in a simple enable/disable mode to mirror the C++ namespaces into the target language specific concept of a C++ namespace. +Secondly, a complex mode for modifying, renaming or moving the hierarchies of the language specific concept of a C++ namespace.
-The feature is demonstrated below for C# using the following example: +The types of symbols that the feature can be applied to are any class, struct, union or enum declared within a named namespace. +This also includes templates of the aforementioned types. +The feature wraps the type within the target language specific concept of a namespace, +such as a Java package or C# namespace. +Only some target languages provide support for the nspace feature. +Please see the target language specific sections to see if the language you are interested in supports the nspace feature. +
+ +6.19.1.1 %nspace for mirroring namespace hierarchies
+ + ++In this simple mode the nspace feature works as a feature flag to enable or disable the feature for a given C++ symbol. +As described earlier, all namespace are flattened by default, hence the nspace feature is disabled by default. +When the feature is enabled, the C++ namespace hierarchies are mirrored into the target language concept of a namespace. +
+ ++The feature flag is demonstrated below using the following example:
@@ -4795,7 +4816,7 @@ namespace MyWorld {-Without the nspace feature directives above or %rename, you would get the following warning resulting in just one of the Color classes being available for use from the target language: +By default, without the above nspace feature flags (or an appropriate %rename), SWIG outputs the following warning resulting in just one of the Color classes being available for use from the target language:
@@ -4806,14 +4827,24 @@ example.i:5: Error: Previous declaration of 'Color'-With the nspace feature the two Color classes are wrapped into the equivalent C# namespaces. +Let's consider C# as the target language. +With the two nspace feature flags, the two C# Color proxy classes are generated into the equivalent C# namespaces that mirror the C++ namespace hierarchies. A fully qualified constructor call of each these two types in C# is then:
+ +-MyWorld.Material.Color materialColor = new MyWorld.Material.Color(); -MyWorld.Wrapping.Color wrappingColor = new MyWorld.Wrapping.Color(); +var materialColor = new MyWorld.Material.Color(); +var wrappingColor = new MyWorld.Wrapping.Color(); +++Without the nspace feature flag, no namespaces are available in C# and the fully qualified constructor call of the type in C# would simply be: +
++@@ -4837,9 +4868,186 @@ namespace MyWorld {+var materialColor = new Color();-Compatibility Note: The nspace feature was first introduced in SWIG-2.0.0. +Compatibility Note: The simple %nspace feature flag was first introduced in SWIG-2.0.0.
+6.19.1.2 %nspacemove for modifying namespace hierarchies
+ + ++The more complex mode for nspace provides the ability to move a type into a differently named target language equivalent of a namespace. +This allows a fully flexible approach to mapping C++ namespaces into a target language equivalent of a namespace, such as: +
+ +
+The nspace feature attaches to a C++ symbol and provides a target language namespace for that symbol to move to. +The %nspacemove directive is a macro for the nspace feature as follows: +
+ +
+#define %nspacemove(NAMESPACE) %feature("nspace", #NAMESPACE)
+
++where the target namespace is provided in NAMESPACE and is specified in valid C++ syntax, such as A::B::C. +Internally, SWIG converts the C++ namespace into a target language equivalent, +so this might for example, result in a C# namespace called A.B.C or a Java package named A.B.C. +Note that the target namespace does not have to actually exist in any of the C++ code that SWIG parses; it could be entirely made-up. +
+ ++Either the %nspacemove macro or the more verbose %feature syntax can be used. Please see the Features and the %feature directive section for more details of SWIG features. +
+ ++An example follows: +
+ +
+// Enable the nspace feature flag for all symbols
+%nspace;
+
+// Override the nspace feature for a subset of symbols by moving them into different namespaces
+%nspacemove(A) A::B::C::Struct1;
+%feature("nspace", "A::B::X") A::B::C::Struct2;
+%nspacemove(A::B::C::D) A::B::C::Struct4;
+%nspacemove(Somewhere::Else) A::B::C::Struct5;
+
+%inline %{
+namespace A {
+ namespace B {
+ namespace C {
+ struct Struct1 {
+ // ...
+ };
+ struct Struct2 {
+ // ...
+ };
+ struct Struct3 {
+ // ...
+ };
+ struct Struct4 {
+ // ...
+ };
+ struct Struct5 {
+ // ...
+ };
+ }
+ }
+}
+%}
+
++The C# code below constructs each of the above classes. +It shows the namespaces that the C# proxy classes have been moved into, +noting though that Struct4 merely exactly mirrors the C++ namespace hierarchy as it has the nspace feature flag attached to it. +
+ ++var s1 = new A.Struct1(); +var s2 = new A.B.X.Struct2(); +var s3 = new A.B.C.Struct3(); +var s4 = new A.B.C.D.Struct4(); +var s5 = new Somewhere.Else.Struct5(); ++
+When the nspace feature is attached to a class or enum, all contained symbols (members) are also automatically moved into the target language namespace. +Contained symbols include all enum values, static and non-static class members as well as nested classes. +There is no need for additional nspace features to be specified for all the contained symbols. +Below is an example showing this. +It also shows the nspace feature working for templates. +
+ +
+// Easy way to move all the Structure template instantiations into a different namespace
+%nspacemove(A::Different::Space) Space::Structure;
+
+%inline %{
+namespace Space {
+ template<typename T>
+ struct Structure {
+ static int Count;
+ static void StaticMethod(T t) {
+ // ...
+ }
+ struct NestedStruct {
+ // ...
+ };
+ };
+ template<typename T>
+ int Structure<T>::Count = 0;
+}
+%}
+%template(StructureInt) Space::Structure<int>;
+%template(StructureString) Space::Structure<const char *>;
+
++The C# code below shows the full C# namespace A.Different.Space being used as one would expect for all the contained symbols within a C# class. +
+ +
+var s = new A.Different.Space.StructureInt();
+int count = A.Different.Space.StructureInt.Count;
+var n = new A.Different.Space.StructureInt.NestedStruct();
+A.Different.Space.StructureInt.StaticMethod(99);
+A.Different.Space.StructureString.StaticMethod("hi");
+
++Any attempt to give a different namespace value to a nested class or enum will issue a warning. +For example, adding the following to the above in an attempt to move one of the instantiated nested classes into another namespace like this: +
+ ++%nspacemove(Bad::Space) Space::Structure<int>::NestedStruct; +... rest of example above ... ++
+will result in the following warning: +
+ ++Warning 406: Ignoring nspace setting (Bad::Space) for 'Space::Structure< int >::NestedStruct', +Warning 406: as it conflicts with the nspace setting (A::Different::Space) for outer class 'Space::Structure< int >'. ++
+Compatibility Note: Modifying namespace hierarchies via %nspacemove was first introduced in SWIG-4.3.0. +
+ + +