From e208f85beaac946c5e8536e088b148a880856f37 Mon Sep 17 00:00:00 2001 From: William S Fulton Date: Fri, 28 Feb 2014 07:49:11 +0000 Subject: [PATCH] Lua html documentation fixes/improvements. --- Doc/Manual/Lua.html | 65 +++++++++++++++++++++++++++------------------ 1 file changed, 39 insertions(+), 26 deletions(-) diff --git a/Doc/Manual/Lua.html b/Doc/Manual/Lua.html index 379fdfc94..f2dd45197 100644 --- a/Doc/Manual/Lua.html +++ b/Doc/Manual/Lua.html @@ -357,8 +357,10 @@ creates a built-in function example.fact(n) that works exactly like you >

-To avoid name collisions, SWIG create a Lua table which it keeps all the functions, constants, classes and global variables in. It is possible to copy the functions, constants and classes (but not variables) out of this and into the global environment with the following code. This can easily overwrite existing functions, so this must be used with care. -This option is considered deprecated and will be removed in near future. +To avoid name collisions, SWIG create a Lua table which keeps all the functions, constants, classes and global variables in. +It is possible to copy the functions, constants and classes (but not variables) out of this and into the global environment with the following code. +This can easily overwrite existing functions, so this must be used with care. +This option is considered deprecated and will be removed in the near future. 

 > for k,v in pairs(example) do _G[k]=v end
@@ -502,12 +504,12 @@ Hello World
 
 
Constants/enums and classes/structures

 

-Unlike previous version of bindings, enums are now exported into class table. For example, given some enums:
+Enums are exported into a class table. For example, given some enums:
 

 
%module example
-enum Days{SUNDAY = 0,MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY};
-class Test {
-    enum { TEST1 = 10, TEST2 = 10 }
+enum Days { SUNDAY = 0, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY };
+struct Test {
+    enum { TEST1 = 10, TEST2 = 20 };
     static const int ICONST = 12;
 };
 

@@ -522,9 +524,10 @@ This is 'effectively' converted into the following Lua code:
 > print(example.Test.ICONST)
 12
-

Backward compatibility

+

-If -no-old-metatable-bindings option is not given, then in addition to previously described bindings, the old-style ones are generated: +Compatibility Note: Versions of SWIG prior to SWIG-3.0.0 did not generate the class table members above. +The following code was the only way to access these constants/enums: 

 > print(example.Test_TEST1)
@@ -533,7 +536,11 @@ If -no-old-metatable-bindings option is not given, then in addition to
 12

-However, in C mode, names of enums are not prefixed with names of structure. This is the due to C Standard. +The old-style bindings are still generated in addition to the new ones. +If the -no-old-metatable-bindings option is used, then these old-style bindings are not generated. +

+

+However, in C mode, names of enums are not prefixed with names of structure. This is the due to the C Standard. 

 > print(example.TEST1)
@@ -542,7 +549,7 @@ However, in C mode, names of enums are not prefixed with names of structure. Thi
 12

-It worth mentioning, that example.Test.TEST1 and example.Test_TEST1 are different entities and changind one wouldn't change another. +It is worth mentioning, that example.Test.TEST1 and example.Test_TEST1 are different entities and changing one does not change the other. Given the fact, that these are constantes and they are not supposed to be changed, it is up to you to avoid such issues.

26.3.5 Pointers

@@ -747,13 +754,18 @@ It is not (currently) possible to access static members of an instance: -- does NOT work -

Backward compatibility

-

If -no-old-metatable-bindings option is not given, then backward compatible names are generated in addition to ordinary ones:

+Compatibility Note: In versions prior to SWIG-3.0.0 only the following names would work: 
 > example.Spam_foo()            -- calling Spam::foo()
 > a=example.Spam_bar            -- reading Spam::bar 
 > example.Spam_bar=b            -- writing to Spam::bar
+ +

+Both style names are generated by default now. +However, if the -no-old-metatable-bindings option is used, then the backward compatible names are not generated in addition to ordinary ones. +

+

26.3.8 C++ inheritance

@@ -1318,37 +1330,38 @@ and the "Exception handling add exception specification to functions or globally (respectively).

-

26.3.17 Namespaces

+

26.3.17 Namespaces

-Since SWIG 3.0 C++ namespaces are supported. You can enabled handling namespaces with %nspace feature. Everything below is valid only after you enabled %nspace. +Since SWIG-3.0.0 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 appropriate namespace. Namespaces structure (a.k.a nested namespaces) is preserved. Consider the following C++ code: 

%module example
 %nspace MyWorld::Nested::Dweller;
 %nspace MyWorld::World;
-/* and so on */
-int module_function() { return 7;}
-int module_variable; // = 9
+
+int module_function() { return 7; }
+int module_variable = 9;
+
 namespace MyWorld {
   class World {
   public:
-    int create_world() { return 17;}
+    int create_world() { return 17; }
     const int world_max_count = 9;
   };
   namespace Nested {
     class Dweller {
-      enum Gender {MALE, FEMALE;
+      enum Gender { MALE, FEMALE };
       static int populate_cave() { return 19; }
-      int create_cave() { return 13;}
+      int create_cave() { return 13; }
       int food_count; // = 11
-    }
+    };
   }
 }
-Now, in Lua it could be used like this: +Now, from Lua usage is as follows: 
-> example.module_function()
+> print(example.module_function())
 7
 > print(example.module_variable)
 8
@@ -1356,9 +1369,9 @@ Now, in Lua it could be used like this:
 17
 > print(example.MyWorld.World.world_max_count)
 9
-> print(example.MyWordl.Nested.Dweller.MALE)
+> print(example.MyWorld.Nested.Dweller.MALE)
 0
-> print(example.MyWordl.Nested.Dweller().food_count)
+> print(example.MyWorld.Nested.Dweller().food_count)
 11
 >