Permalink
Browse files

Lua html documentation fixes/improvements.

  • Loading branch information...
1 parent 52c106d commit e208f85beaac946c5e8536e088b148a880856f37 @wsfulton wsfulton committed Feb 28, 2014
Showing with 39 additions and 26 deletions.
  1. +39 −26 Doc/Manual/Lua.html
View
65 Doc/Manual/Lua.html
@@ -357,8 +357,10 @@
>
</pre></div>
<p>
-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.
</p>
<div class="targetlang"><pre>
&gt; for k,v in pairs(example) do _G[k]=v end
@@ -502,12 +504,12 @@
<H4>Constants/enums and classes/structures</H4>
<p>
-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:
</p>
<div class="code"><pre>%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;
};
</pre></div>
@@ -522,9 +524,10 @@
&gt; print(example.Test.ICONST)
12
</pre></div>
-<H4>Backward compatibility</H4>
+
<p>
-If <tt>-no-old-metatable-bindings</tt> option is not given, then in addition to previously described bindings, the old-style ones are generated:
+<b>Compatibility Note:</b> 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:
</p>
<div class="targetlang"><pre>
&gt; print(example.Test_TEST1)
@@ -533,7 +536,11 @@
12
</pre></div>
<p>
-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 <tt>-no-old-metatable-bindings</tt> option is used, then these old-style bindings are not generated.
+</p>
+<p>
+However, in C mode, names of enums are not prefixed with names of structure. This is the due to the C Standard.
</p>
<div class="targetlang"><pre>
&gt; print(example.TEST1)
@@ -542,7 +549,7 @@
12
</pre></div>
<p>
-It worth mentioning, that <tt>example.Test.TEST1</tt> and <tt>example.Test_TEST1</tt> are different entities and changind one wouldn't change another.
+It is worth mentioning, that <tt>example.Test.TEST1</tt> and <tt>example.Test_TEST1</tt> 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.
</p>
<H3><a name="Lua_nn12"></a>26.3.5 Pointers</H3>
@@ -747,13 +754,18 @@
-- does NOT work
</pre></div>
-<H4>Backward compatibility</H4>
-<p> If <tt>-no-old-metatable-bindings</tt> option is not given, then backward compatible names are generated in addition to ordinary ones: </p>
+<b>Compatibility Note:</b> In versions prior to SWIG-3.0.0 only the following names would work:
<div class="code"><pre>
&gt; example.Spam_foo() -- calling Spam::foo()
&gt; a=example.Spam_bar -- reading Spam::bar
&gt; example.Spam_bar=b -- writing to Spam::bar
</pre></div>
+
+<p>
+Both style names are generated by default now.
+However, if the <tt>-no-old-metatable-bindings</tt> option is used, then the backward compatible names are not generated in addition to ordinary ones.
+</p>
+
<H3><a name="Lua_nn15"></a>26.3.8 C++ inheritance</H3>
@@ -1318,47 +1330,48 @@
add exception specification to functions or globally (respectively).
</p>
-<H3><a name ="Lua_nn23_5"></a>26.3.17 Namespaces </H3>
+<H3><a name ="Lua_namespaces"></a>26.3.17 Namespaces </H3>
<p>
-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.
</p>
-<p> 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:
+<p> 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:
</p>
<div class="code"><pre>%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
- }
+ };
}
}
</pre></div>
-Now, in Lua it could be used like this:
+Now, from Lua usage is as follows:
<div class="targetlang"><pre>
-&gt; example.module_function()
+&gt; print(example.module_function())
7
&gt; print(example.module_variable)
8
&gt; print(example.MyWorld.World():create_world())
17
&gt; print(example.MyWorld.World.world_max_count)
9
-&gt; print(example.MyWordl.Nested.Dweller.MALE)
+&gt; print(example.MyWorld.Nested.Dweller.MALE)
0
-&gt; print(example.MyWordl.Nested.Dweller().food_count)
+&gt; print(example.MyWorld.Nested.Dweller().food_count)
11
&gt;
</pre></div>

0 comments on commit e208f85

Please sign in to comment.