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

Lua html documentation fixes/improvements.

Browse source
This commit is contained in:
William S Fulton 2014-02-28 07:49:11 +00:00
commit e208f85bea
1 changed files with 39 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

65
Doc/Manual/Lua.html
View file

@ -357,8 +357,10 @@ creates a built-in function <tt>example.fact(n)</tt> that works exactly like you
&gt;
</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 @@ Hello World
<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 @@ This is 'effectively' converted into the following Lua code:
&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 @@ If <tt>-no-old-metatable-bindings</tt> option is not given, then in addition to
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 @@ However, in C mode, names of enums are not prefixed with names of structure. Thi
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 @@ It is not (currently) possible to access static members of an instance:
-- 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,37 +1330,38 @@ and the "<a href="Customization.html#Customization_exception">Exception handling
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
@ -1356,9 +1369,9 @@ Now, in Lua it could be used like this:
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>