1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>SWIG and Lua</title>
<link rel="stylesheet" type="text/css" href="style.css">
</head>
<body bgcolor="#ffffff">
<H1><a name="Lua"></a>26 SWIG and Lua</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Lua_nn2">Preliminaries</a>
<li><a href="#Lua_nn3">Running SWIG</a>
<ul>
<li><a href="#Lua_commandline">Additional command line options</a>
<li><a href="#Lua_nn4">Compiling and Linking and Interpreter</a>
<li><a href="#Lua_nn5">Compiling a dynamic module</a>
<li><a href="#Lua_nn6">Using your module</a>
</ul>
<li><a href="#Lua_nn7">A tour of basic C/C++ wrapping</a>
<ul>
<li><a href="#Lua_nn8">Modules</a>
<li><a href="#Lua_nn9">Functions</a>
<li><a href="#Lua_nn10">Global variables</a>
<li><a href="#Lua_nn11">Constants and enums</a>
<li><a href="#Lua_nn12">Pointers</a>
<li><a href="#Lua_nn13">Structures</a>
<li><a href="#Lua_nn14">C++ classes</a>
<li><a href="#Lua_nn15">C++ inheritance</a>
<li><a href="#Lua_nn16">Pointers, references, values, and arrays</a>
<li><a href="#Lua_nn17">C++ overloaded functions</a>
<li><a href="#Lua_nn18">C++ operators</a>
<li><a href="#Lua_nn19">Class extension with %extend</a>
<li><a href="#Lua_nn20">Using %newobject to release memory</a>
<li><a href="#Lua_nn21">C++ templates</a>
<li><a href="#Lua_nn22">C++ Smart Pointers</a>
<li><a href="#Lua_nn23">C++ Exceptions</a>
</ul>
<li><a href="#Lua_nn24">Typemaps</a>
<ul>
<li><a href="#Lua_nn25">What is a typemap?</a>
<li><a href="#Lua_nn26">Using typemaps</a>
<li><a href="#Lua_nn27">Typemaps and arrays</a>
<li><a href="#Lua_nn28">Typemaps and pointer-pointer functions</a>
</ul>
<li><a href="#Lua_nn29">Writing typemaps</a>
<ul>
<li><a href="#Lua_nn30">Typemaps you can write</a>
<li><a href="#Lua_nn31">SWIG's Lua-C API</a>
</ul>
<li><a href="#Lua_nn32">Customization of your Bindings</a>
<ul>
<li><a href="#Lua_nn33">Writing your own custom wrappers</a>
<li><a href="#Lua_nn34">Adding additional Lua code</a>
</ul>
<li><a href="#Lua_nn35">Details on the Lua binding</a>
<ul>
<li><a href="#Lua_nn36">Binding global data into the module.</a>
<li><a href="#Lua_nn37">Userdata and Metatables</a>
<li><a href="#Lua_nn38">Memory management</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<p>
Lua is an extension programming language designed to support general procedural programming with data description facilities. It also offers good support for object-oriented programming, functional programming, and data-driven programming. Lua is intended to be used as a powerful, light-weight configuration language for any program that needs one. Lua is implemented as a library, written in clean C (that is, in the common subset of ANSI C and C++). It's also a <em>really</em> tiny language, less than 6000 lines of code, which compiles to <100 kilobytes of binary code. It can be found at <a href="http://www.lua.org">http://www.lua.org</a>
</p>
<p>
eLua stands for Embedded Lua (can be thought of as a flavor of Lua) and offers the full implementation of the Lua programming language to the embedded world, extending it with specific features for efficient and portable software embedded development. eLua runs on smaller devices like microcontrollers and provides the full features of the regular Lua desktop version. More information on eLua can be found here: <a href="http://www.eluaproject.net">http://www.eluaproject.net</a>
</p>
<H2><a name="Lua_nn2"></a>26.1 Preliminaries</H2>
<p>
The current SWIG implementation is designed to work with Lua 5.0.x, 5.1.x and 5.2.x. It should work with later versions of Lua, but certainly not with Lua 4.0 due to substantial API changes. It is possible to either static link or dynamic link a Lua module into the interpreter (normally Lua static links its libraries, as dynamic linking is not available on all platforms). SWIG also has support for eLua starting from eLua 0.8. Due to substantial changes between SWIG 2.x and SWIG 3.0 and unavailability of testing platform, eLua status was downgraded to 'experimental'.
</p>
<H2><a name="Lua_nn3"></a>26.2 Running SWIG</H2>
<p>
Suppose that you defined a SWIG module such as the following:
</p>
<div class="code"><pre>
%module example
%{
#include "example.h"
%}
int gcd(int x, int y);
extern double Foo;
</pre></div>
<p>
To build a Lua module, run SWIG using the <tt>-lua</tt> option.
</p>
<div class="shell"><pre>
$ swig -lua example.i
</pre></div>
<p>
If building a C++ extension, add the <tt>-c++</tt> option:
</p>
<div class="shell"><pre>
$ swig -c++ -lua example.i
</pre></div>
<p>
This creates a C/C++ source file <tt>example_wrap.c</tt> or <tt>example_wrap.cxx</tt>. The generated C source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application to create an extension module.
</p>
<p>
The name of the wrapper file is derived from the name of the input file. For example, if the input file is <tt>example.i</tt>, the name of the wrapper file is <tt>example_wrap.c</tt>. To change this, you can use the -o option. The wrapped module will export one function <tt>"int luaopen_example(lua_State* L)"</tt> which must be called to register the module with the Lua interpreter. The name "luaopen_example" depends upon the name of the module.
</p>
<p>
To build an eLua module, run SWIG using <tt>-lua</tt> and add either <tt>-elua</tt> or <tt>-eluac</tt>.
</p>
<div class="shell"><pre>
$ swig -lua -elua example.i
</pre></div>
<p>
or
</p>
<div class="shell"><pre>
$ swig -lua -eluac example.i
</pre></div>
<p>
The <tt>-elua</tt> option puts all the C function wrappers and variable get/set wrappers in rotables. It also generates a metatable which will control the access to these variables from eLua. It also offers a significant amount of module size compression. On the other hand, the <tt>-eluac</tt> option puts all the wrappers in a single rotable. With this option, no matter how huge the module, it will consume no additional microcontroller SRAM (crass compression). There is a catch though: Metatables are not generated with <tt>-eluac</tt>. To access any value from eLua, one must directly call the wrapper function associated with that value.
</p>
<H3><a name="Lua_commandline"></a>26.2.1 Additional command line options</H3>
<p>
The following table list the additional commandline options available for the Lua module. They can also be seen by using:
</p>
<div class="code"><pre>
swig -lua -help
</pre></div>
<table summary="Lua specific options">
<tr>
<th>Lua specific options</th>
</tr>
<tr>
<td>-elua</td>
<td>Generates LTR compatible wrappers for smaller devices running elua.</td>
</tr>
<tr>
<td>-eluac</td>
<td>LTR compatible wrappers in "crass compress" mode for elua.</td>
</tr>
<tr>
<td>-nomoduleglobal</td>
<td>Do not register the module name as a global variable but return the module table from calls to require.</td>
</tr>
<tr>
<td>-no-old-metatable-bindings</td>
<td>Disable backward compatibility: old-style binding names generations and a few other things. Explanations are included into appropriate sections.</td>
</tr>
<tr>
<td>-squash-bases</td>
<td>Squashes symbols from all inheritance tree of a given class into itself. Emulates pre-SWIG3.0 inheritance. Insignificantly speeds things up, but increases memory consumption.</td>
</tr>
</table>
<H3><a name="Lua_nn4"></a>26.2.2 Compiling and Linking and Interpreter</H3>
<p>
Normally Lua is embedded into another program and will be statically linked. An extremely simple stand-alone interpreter (<tt>min.c</tt>) is given below:
</p>
<div class="code"><pre>
#include <stdio.h>
#include "lua.h"
#include "lualib.h"
#include "lauxlib.h"
extern int luaopen_example(lua_State* L); // declare the wrapped module
int main(int argc,char* argv[])
{
lua_State *L;
if (argc<2)
{
printf("%s: <filename.lua>\n",argv[0]);
return 0;
}
L=lua_open();
luaopen_base(L); // load basic libs (eg. print)
luaopen_example(L); // load the wrapped module
if (luaL_loadfile(L,argv[1])==0) // load and run the file
lua_pcall(L,0,0,0);
else
printf("unable to load %s\n",argv[1]);
lua_close(L);
return 0;
}
</pre></div>
<p>
A much improved set of code can be found in the Lua distribution <tt>src/lua/lua.c</tt>. Include your module, just add the external declaration & add a <tt>#define LUA_EXTRALIBS {"example",luaopen_example}</tt>, at the relevant place.
</p>
<p>
The exact commands for compiling and linking vary from platform to platform. Here is a possible set of commands of doing this:
</p>
<div class="shell"><pre>
$ swig -lua example.i -o example_wrap.c
$ gcc -I/usr/include/lua -c min.c -o min.o
$ gcc -I/usr/include/lua -c example_wrap.c -o example_wrap.o
$ gcc -c example.c -o example.o
$ gcc -I/usr/include/lua -L/usr/lib/lua min.o example_wrap.o example.o -o my_lua
</pre></div>
<p>
For eLua, the source must be built along with the wrappers generated by SWIG. Make sure the eLua source files <tt>platform_conf.h</tt> and <tt>auxmods.h</tt> are updated with the entries of your new module. Please note: <tt>"mod"</tt> is the module name.
</p>
<div class="code"><pre>
/* Sample platform_conf.h */
#define LUA_PLATFORM_LIBS_ROM\
_ROM( AUXLIB_PIO, luaopen_pio, pio_map )\
_ROM( AUXLIB_TMR, luaopen_tmr, tmr_map )\
_ROM( AUXLIB_MOD, luaopen_mod, mod_map )\
....
</pre></div>
<div class="code"><pre>
/* Sample auxmods.h */
#define AUXLIB_PIO "pio"
LUALIB_API int ( luaopen_pio )(lua_State *L );
#define AUXLIB_MOD "mod"
LUALIB_API int ( luaopen_mod )(lua_State *L );
....
</pre></div>
<p>
More information on building and configuring eLua can be found here: <a href="http://www.eluaproject.net/doc/v0.8/en_building.html">http://www.eluaproject.net/doc/v0.8/en_building.html</a>
</p>
<H3><a name="Lua_nn5"></a>26.2.3 Compiling a dynamic module</H3>
<p>
Most, but not all platforms support the dynamic loading of modules (Windows & Linux do). Refer to the Lua manual to determine if your platform supports it. For compiling a dynamically loaded module the same wrapper can be used. Assuming you have code you need to link to in a file called <tt>example.c</tt>, the commands will be something like this:
</p>
<div class="shell"><pre>
$ swig -lua example.i -o example_wrap.c
$ gcc -fPIC -I/usr/include/lua -c example_wrap.c -o example_wrap.o
$ gcc -fPIC -c example.c -o example.o
$ gcc -shared -I/usr/include/lua -L/usr/lib/lua example_wrap.o example.o -o example.so
</pre></div>
<p>
The wrappers produced by SWIG can be compiled and linked with Lua 5.1.x and later. The loading is extremely simple.
</p>
<div class="targetlang"><pre>
require("example")
</pre></div>
<p>
For those using Lua 5.0.x, you will also need an interpreter with the loadlib function (such as the default interpreter compiled with Lua). In order to dynamically load a module you must call the loadlib function with two parameters: the filename of the shared library, and the function exported by SWIG. Calling loadlib should return the function, which you then call to initialise the module
</p>
<div class="targetlang"><pre>
my_init=loadlib("example.so","luaopen_example") -- for Unix/Linux
--my_init=loadlib("example.dll","luaopen_example") -- for Windows
assert(my_init) -- make sure it's not nil
my_init() -- call the init fn of the lib
</pre></div>
<p>
Or can be done in a single line of Lua code
</p>
<div class="targetlang"><pre>
assert(loadlib("example.so","luaopen_example"))()
</pre></div>
<p>
If the code didn't work, don't panic. The best thing to do is to copy the module and your interpreter into a single directory and then execute the interpreter and try to manually load the module (take care, all this code is case sensitive).
</p>
<div class="targetlang"><pre>
a,b,c=package.loadlib("example.so","luaopen_example") -- for Unix/Linux
--a,b,c=package.loadlib("example.dll","luaopen_example") -- for Windows
print(a,b,c)
</pre></div>
<p>
Note: for Lua 5.0:<br>
The loadlib() function is in the global namespace, not in a package. So it's just loadlib().
</p>
<p>
if 'a' is a function, this is all working fine, all you need to do is call it
</p>
<div class="targetlang"><pre>
a()
</pre></div>
<p>
to load your library which will add a table 'example' with all the functions added.
</p>
<p>
If it doesn't work, look at the error messages, in particular message 'b'<br>
<tt> The specified module could not be found.</tt><br>
Means that is cannot find the module, check your the location and spelling of the module.<br>
<tt> The specified procedure could not be found.</tt><br>
Means that it loaded the module, but cannot find the named function. Again check the spelling, and if possible check to make sure the functions were exported correctly.<br>
<tt> 'loadlib' not installed/supported</tt><br>
Is quite obvious (Go back and consult the Lua documents on how to enable loadlib for your platform).
</p>
<H3><a name="Lua_nn6"></a>26.2.4 Using your module</H3>
<p>
Assuming all goes well, you will be able to this:
</p>
<div class="targetlang"><pre>
$ ./my_lua
> print(example.gcd(4,6))
2
> print(example.Foo)
3
> example.Foo=4
> print(example.Foo)
4
>
</pre></div>
<H2><a name="Lua_nn7"></a>26.3 A tour of basic C/C++ wrapping</H2>
<p>
By default, SWIG tries to build a very natural Lua interface to your C/C++ code. This section briefly covers the essential aspects of this wrapping.
</p>
<H3><a name="Lua_nn8"></a>26.3.1 Modules</H3>
<p>
The SWIG module directive specifies the name of the Lua module. If you specify `module example', then everything is wrapped into a Lua table 'example' containing all the functions and variables. When choosing a module name, make sure you don't use the same name as a built-in Lua command or standard module name.
</p>
<H3><a name="Lua_nn9"></a>26.3.2 Functions</H3>
<p>
Global functions are wrapped as new Lua built-in functions. For example,
</p>
<div class="code"><pre>
%module example
int fact(int n);</pre></div>
<p>
creates a built-in function <tt>example.fact(n)</tt> that works exactly like you think it does:
</p>
<div class="targetlang"><pre>
> print example.fact(4)
24
>
</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.
</p>
<div class="targetlang"><pre>
> for k,v in pairs(example) do _G[k]=v end
> print(fact(4))
24
>
</pre></div>
<p>
It is also possible to rename the module with an assignment.
</p>
<div class="targetlang"><pre>
> e=example
> print(e.fact(4))
24
> print(example.fact(4))
24
</pre></div>
<H3><a name="Lua_nn10"></a>26.3.3 Global variables</H3>
<p>
Global variables (which are linked to C code) are supported, and appear to be just another variable in Lua. However the actual mechanism is more complex. Given a global variable:
</p>
<div class="code"><pre>%module example
extern double Foo;
</pre></div>
<p>
SWIG will effectively generate two functions <tt>example.Foo_set()</tt> and <tt>example.Foo_get()</tt>. It then adds a metatable to the table 'example' to call these functions at the correct time (when you attempt to set or get examples.Foo). Therefore if you were to attempt to assign the global to another variable, you will get a local copy within the interpreter, which is no longer linked to the C code.
</p>
<div class="targetlang"><pre>
> print(example.Foo)
3
> c=example.Foo -- c is a COPY of example.Foo, not the same thing
> example.Foo=4
> print(c)
3
> c=5 -- this will not effect the original example.Foo
> print(example.Foo,c)
4 5
</pre></div>
<p>
It is therefore not possible to 'move' the global variable into the global namespace as it is with functions. It is however, possible to rename the module with an assignment, to make it more convenient.
</p>
<div class="targetlang"><pre>
> e=example
> -- e and example are the same table
> -- so e.Foo and example.Foo are the same thing
> example.Foo=4
> print(e.Foo)
4
</pre></div>
<p>
If a variable is marked with the %immutable directive then any attempts to set this variable will cause a Lua error. Given a global variable:
</p>
<div class="code"><pre>%module example
%immutable;
extern double Foo;
%mutable;
</pre></div>
<p>
SWIG will allow the reading of <tt>Foo</tt> but when a set attempt is made, an error function will be called.
</p>
<div class="targetlang"><pre>
> print(e.Foo) -- reading works ok
4
> example.Foo=40 -- but writing does not
This variable is immutable
stack traceback:
[C]: ?
[C]: ?
stdin:1: in main chunk
[C]: ?
</pre></div>
<p>
For those people who would rather that SWIG silently ignore the setting of immutables (as previous versions of the Lua bindings did), adding a <tt>-DSWIGLUA_IGNORE_SET_IMMUTABLE</tt> compile option will remove this.
</p>
<p>
Unlike earlier versions of the binding, it is now possible to add new functions or variables to the module, just as if it were a normal table. This also allows the user to rename/remove existing functions and constants (but not linked variables, mutable or immutable). Therefore users are recommended to be careful when doing so.
</p>
<div class="targetlang"><pre>
> -- example.PI does not exist
> print(example.PI)
nil
> example.PI=3.142 -- new value added
> print(example.PI)
3.142
</pre></div>
<p>
If you have used the <tt>-eluac</tt> option for your eLua module, you will have to follow a different approach while manipulating global variables. (This is not applicable for wrappers generated with <tt>-elua</tt>)
</p>
<div class="targetlang"><pre>
> -- Applicable only with -eluac. (num is defined)
> print(example.num_get())
20
> example.num_set(50) -- new value added
> print(example.num_get())
50
</pre></div>
<p>
In general, functions of the form <tt>"variable_get()"</tt> and <tt>"variable_set()"</tt> are automatically generated by SWIG for use with <tt>-eluac</tt>.
</p>
<H3><a name="Lua_nn11"></a>26.3.4 Constants and enums</H3>
<p>
Because Lua doesn't really have the concept of constants, C/C++ constants are not really constant in Lua. They are actually just a copy of the value into the Lua interpreter. Therefore they can be changed just as any other value. For example given some constants:
</p>
<div class="code"><pre>%module example
%constant int ICONST=42;
#define SCONST "Hello World"
enum Days{SUNDAY,MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY};
</pre></div>
<p>
This is 'effectively' converted into the following Lua code:
</p>
<div class="targetlang"><pre>
example.ICONST=42
example.SCONST="Hello World"
example.SUNDAY=0
....
</pre></div>
<p>
Constants are not guaranteed to remain constant in Lua. The name of the constant could be accidentally reassigned to refer to some other object. Unfortunately, there is no easy way for SWIG to generate code that prevents this. You will just have to be careful.
</p>
<p>
If you're using eLua and have used <tt>-elua</tt> or <tt>-eluac</tt> to generate your wrapper, macro constants and enums should be accessed through a rotable called <tt>"const"</tt>. In eLua, macro constants and enums are guaranteed to remain constants since they are all contained within a rotable. A regular C constant is accessed from eLua just as if it were a regular global variable, just that the property of value immutability is demonstrated if an attempt at modifying a C constant is made.
</p>
<div class="targetlang"><pre>
> print(example.ICONST)
10
> print(example.const.SUNDAY)
0
> print(example.const.SCONST)
Hello World
</pre></div>
<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:
</p>
<div class="code"><pre>%module example
enum Days{SUNDAY = 0,MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY};
class Test {
enum { TEST1 = 10, TEST2 = 10 }
static const int ICONST = 12;
};
</pre></div>
<p>
This is 'effectively' converted into the following Lua code:
</p>
<div class="targetlang"><pre>
> print(example.const.SUNDAY)
0
> print(example.Test.TEST1)
10
> 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:
</p>
<div class="targetlang"><pre>
> print(example.Test_TEST1)
10
> print(example.Test_ICONST)
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.
</p>
<div class="targetlang"><pre>
> print(example.TEST1)
10
> print(example.ICONST)
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.
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>
<p>
C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with incomplete type information. Given a wrapping of the <file.h> interface:
</p>
<div class="code"><pre>%module example
FILE *fopen(const char *filename, const char *mode);
int fputs(const char *, FILE *);
int fclose(FILE *);
</pre></div>
<p>
When wrapped, you will be able to use the functions in a natural way from Lua. For example:
</p>
<div class="targetlang"><pre>
> f=example.fopen("junk","w")
> example.fputs("Hello World",f)
> example.fclose(f)
</pre></div>
<p>
Unlike many scripting languages, Lua has had support for pointers to C/C++ object built in for a long time. They are called 'userdata'. Unlike many other SWIG versions which use some kind of encoded character string, all objects will be represented as a userdata. The SWIG-Lua bindings provides a special function <tt>swig_type()</tt>, which if given a userdata object will return the type of object pointed to as a string (assuming it was a SWIG wrapped object).
</p>
<div class="targetlang"><pre>
> print(f)
userdata: 003FDA80
> print(swig_type(f))
FILE * -- it's a FILE*
</pre></div>
<p>
Lua enforces the integrity of its userdata, so it is virtually impossible to corrupt the data. But as the user of the pointer, you are responsible for freeing it, or closing any resources associated with it (just as you would in a C program). This does not apply so strictly to classes & structs (see below). One final note: if a function returns a NULL pointer, this is not encoded as a userdata, but as a Lua nil.
</p>
<div class="targetlang"><pre>
> f=example.fopen("not there","r") -- this will return a NULL in C
> print(f)
nil
</pre></div>
<H3><a name="Lua_nn13"></a>26.3.6 Structures</H3>
<p>
If you wrap a C structure, it is also mapped to a Lua userdata. By adding a metatable to the userdata, this provides a very natural interface. For example,
</p>
<div class="code"><pre>struct Point{
int x,y;
};
</pre></div>
<p>
is used as follows:
</p>
<div class="targetlang"><pre>
> p=example.new_Point()
> p.x=3
> p.y=5
> print(p.x,p.y)
3 5
>
</pre></div>
<p>
Similar access is provided for unions and the data members of C++ classes.<br>
C structures can be created using a function <tt>new_Point()</tt>, and both C structures and C++ classes can be created using just the name <tt>Point()</tt>.
</p>
<p>
If you print out the value of p in the above example, you will see something like this:
</p>
<div class="targetlang"><pre>
> print(p)
userdata: 003FA320
</pre></div>
<p>
Like the pointer in the previous section, this is held as a userdata. However, additional features have been added to make this more usable. SWIG effectively creates some accessor/mutator functions to get and set the data. These functions will be added to the userdata's metatable. This provides the natural access to the member variables that were shown above (see end of the document for full details).
</p>
<p>
<tt>const</tt> members of a structure are read-only. Data members can also be forced to be read-only using the immutable directive. As with other immutables, setting attempts will be cause an error. For example:
</p>
<div class="code"><pre>struct Foo {
...
%immutable;
int x; // Read-only members
char *name;
%mutable;
...
};
</pre></div>
<p>
The mechanism for managing char* members as well as array members is similar to other languages. It is somewhat cumbersome and should probably be better handled by defining of typemaps (described later).
</p>
<p>
When a member of a structure is itself a structure, it is handled as a pointer. For example, suppose you have two structures like this:
</p>
<div class="code"><pre>struct Foo {
int a;
};
struct Bar {
Foo f;
};
</pre></div>
<p>
Now, suppose that you access the f attribute of Bar like this:
</p>
<div class="targetlang"><pre>
> b = Bar()
> x = b.f
</pre></div>
<p>
In this case, x is a pointer that points to the Foo that is inside b. This is the same value as generated by this C code:
</p>
<div class="code"><pre>
Bar b;
Foo *x = &b->f; // Points inside b
</pre></div>
<p>
Because the pointer points inside the structure, you can modify the contents and everything works just like you would expect. For example:
</p>
<div class="targetlang"><pre>
> b = Bar()
> b.f.a = 3 -- Modify attribute of structure member
> x = b.f
> x.a = 3 -- Modifies the same structure
</pre></div>
<p>
For eLua with the <tt>-eluac</tt> option, structure manipulation has to be performed with specific structure functions generated by SWIG. Let's say you have the following structure definition:
</p>
<div class="code"><pre>struct data {
int x, y;
double z;
};
> --From eLua
> a = example.new_data()
> example.data_x_set(a, 10)
> example.data_y_set(a, 20)
> print(example.data_x_get(a), example.data_y_get(a))
10 20
</pre></div>
<p>
In general, functions of the form <tt>"new_struct()"</tt>, <tt>"struct_member_get()"</tt>, <tt>"struct_member_set()"</tt> and <tt>"free_struct()"</tt> are automatically generated by SWIG for each structure defined in C. (Please note: This doesn't apply for modules generated with the <tt>-elua</tt> option)
</p>
<H3><a name="Lua_nn14"></a>26.3.7 C++ classes</H3>
<p>
C++ classes are wrapped by a Lua userdata as well. For example, if you have this class,
</p>
<div class="code"><pre>class List {
public:
List();
~List();
int search(char *item);
void insert(char *item);
void remove(char *item);
char *get(int n);
int length;
};
</pre></div>
<p>
you can use it in Lua like this:
</p>
<div class="targetlang"><pre>
> l = example.List()
> l:insert("Ale")
> l:insert("Stout")
> l:insert("Lager")
> print(l:get(1))
Stout
> print(l:length)
3
>
</pre></div>
<p>
(Note: for calling methods of a class, you use <tt>class:method(args)</tt>, not <tt>class.method(args)</tt>, it's an easy mistake to make. However for data attributes it is <tt>class.attribute</tt>)
</p>
<p>
Class data members are accessed in the same manner as C structures. Static class members present a special problem for Lua, as Lua doesn't have support for such features. Therefore, SWIG generates wrappers that try to work around some of these issues. To illustrate, suppose you have a class like this:
</p>
<div class="targetlang"><pre>class Spam {
public:
static void foo();
static int bar;
};
</pre></div>
<p>
In Lua, the static members can be accessed as follows:
</p>
<div class="code"><pre>
> example.Spam.foo() -- calling Spam::foo()
> a=example.Spam.bar -- reading Spam::bar
> example.Spam.bar=b -- writing to Spam::bar
</pre></div>
<p>
It is not (currently) possible to access static members of an instance:
</p>
<div class="targetlang"><pre>
> s=example.Spam() -- s is a Spam instance
> s.foo() -- Spam::foo() via 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>
<div class="code"><pre>
> example.Spam_foo() -- calling Spam::foo()
> a=example.Spam_bar -- reading Spam::bar
> example.Spam_bar=b -- writing to Spam::bar
</pre></div>
<H3><a name="Lua_nn15"></a>26.3.8 C++ inheritance</H3>
<p>
SWIG is fully aware of issues related to C++ inheritance. Therefore, if you have classes like this
</p>
<div class="code"><pre>class Foo {
...
};
class Bar : public Foo {
...
};
</pre></div>
<p>
And if you have functions like this
</p>
<div class="code"><pre>void spam(Foo *f);
</pre></div>
<p>
then the function <tt>spam()</tt> accepts a Foo pointer or a pointer to any class derived from Foo.
</p>
<p>
It is safe to use multiple inheritance with SWIG.
</p>
<H3><a name="Lua_nn16"></a>26.3.9 Pointers, references, values, and arrays</H3>
<p>
In C++, there are many different ways a function might receive and manipulate objects. For example:
</p>
<div class="code"><pre>void spam1(Foo *x); // Pass by pointer
void spam2(Foo &x); // Pass by reference
void spam3(Foo x); // Pass by value
void spam4(Foo x[]); // Array of objects
</pre></div>
<p>
In SWIG, there is no detailed distinction like this--specifically, there are only "objects". There are no pointers, references, arrays, and so forth. Because of this, SWIG unifies all of these types together in the wrapper code. For instance, if you actually had the above functions, it is perfectly legal to do this:
</p>
<div class="targetlang"><pre>
> f = Foo() -- Create a Foo
> spam1(f) -- Ok. Pointer
> spam2(f) -- Ok. Reference
> spam3(f) -- Ok. Value.
> spam4(f) -- Ok. Array (1 element)
</pre></div>
<p>
Similar behaviour occurs for return values. For example, if you had functions like this,
</p>
<div class="code"><pre>Foo *spam5();
Foo &spam6();
Foo spam7();
</pre></div>
<p>
then all three functions will return a pointer to some Foo object. Since the third function (spam7) returns a value, newly allocated memory is used to hold the result and a pointer is returned (Lua will release this memory when the return value is garbage collected). The other two are pointers which are assumed to be managed by the C code and so will not be garbage collected.
</p>
<H3><a name="Lua_nn17"></a>26.3.10 C++ overloaded functions</H3>
<p>
C++ overloaded functions, methods, and constructors are mostly supported by SWIG. For example, if you have two functions like this:
</p>
<div class="code"><pre>void foo(int);
void foo(char *c);
</pre></div>
<p>
You can use them in Lua in a straightforward manner:
</p>
<div class="targetlang"><pre>
> foo(3) -- foo(int)
> foo("Hello") -- foo(char *c)
</pre></div>
<p>
However due to Lua's coercion mechanism is can sometimes do strange things.
</p>
<div class="targetlang"><pre>
> foo("3") -- "3" can be coerced into an int, so it calls foo(int)!
</pre></div>
<p>
As this coercion mechanism is an integral part of Lua, there is no easy way to get around this other than renaming of functions (see below).
</p>
<p>
Similarly, if you have a class like this,
</p>
<div class="code"><pre>class Foo {
public:
Foo();
Foo(const Foo &);
...
};
</pre></div>
<p>
you can write Lua code like this:
</p>
<div class="targetlang"><pre>
> f = Foo() -- Create a Foo
> g = Foo(f) -- Copy f
</pre></div>
<p>
Overloading support is not quite as flexible as in C++. Sometimes there are methods that SWIG can't disambiguate. For example:
</p>
<div class="code"><pre>void spam(int);
void spam(short);
</pre></div>
<p>
or
</p>
<DIV CLASS="CODE"><PRE>VOID FOO(bAR *B);
void foo(Bar &b);
</pre></div>
<p>
If declarations such as these appear, you will get a warning message like this:
</p>
<div class="shell"><pre>
example.i:12: Warning 509: Overloaded method spam(short) effectively ignored,
example.i:11: Warning 509: as it is shadowed by spam(int).
</pre></div>
<p>
To fix this, you either need to ignore or rename one of the methods. For example:
</p>
<div class="code"><pre>%rename(spam_short) spam(short);
...
void spam(int);
void spam(short); // Accessed as spam_short
</pre></div>
<p>
or
</p>
<div class="code"><pre>%ignore spam(short);
...
void spam(int);
void spam(short); // Ignored
</pre></div>
<p>
SWIG resolves overloaded functions and methods using a disambiguation scheme that ranks and sorts declarations according to a set of type-precedence rules. The order in which declarations appear in the input does not matter except in situations where ambiguity arises--in this case, the first declaration takes precedence.
</p>
<p>
Please refer to the "SWIG and C++" chapter for more information about overloading.
</p>
<p>
Dealing with the Lua coercion mechanism, the priority is roughly (integers, floats, strings, userdata). But it is better to rename the functions rather than rely upon the ordering.
</p>
<H3><a name="Lua_nn18"></a>26.3.11 C++ operators</H3>
<p>
Certain C++ overloaded operators can be handled automatically by SWIG. For example, consider a class like this:
</p>
<div class="code"><pre>class Complex {
private:
double rpart, ipart;
public:
Complex(double r = 0, double i = 0) : rpart(r), ipart(i) { }
Complex(const Complex &c) : rpart(c.rpart), ipart(c.ipart) { }
Complex &operator=(const Complex &c);
Complex operator+(const Complex &c) const;
Complex operator-(const Complex &c) const;
Complex operator*(const Complex &c) const;
Complex operator-() const;
double re() const { return rpart; }
double im() const { return ipart; }
};
</pre></div>
<p>
When wrapped, it works like you expect:
</p>
<div class="targetlang"><pre>
> c = Complex(3,4)
> d = Complex(7,8)
> e = c + d
> e:re()
10.0
> e:im()
12.0
</pre></div>
<p>
One restriction with operator overloading support is that SWIG is not able to fully handle operators that aren't defined as part of the class. For example, if you had code like this
</p>
<div class="targetlang"><pre>class Complex {
...
friend Complex operator+(double, const Complex &c);
...
};
</pre></div>
<p>
then SWIG doesn't know what to do with the friend function--in fact, it simply ignores it and issues a warning. You can still wrap the operator, but you may have to encapsulate it in a special function. For example:
</p>
<div class="targetlang"><pre>%rename(Complex_add_dc) operator+(double, const Complex &);
...
Complex operator+(double, const Complex &c);
</pre></div>
<p>
There are ways to make this operator appear as part of the class using the <tt>%extend</tt> directive. Keep reading.
</p>
<p>
Also, be aware that certain operators don't map cleanly to Lua, and some Lua operators don't map cleanly to C++ operators. For instance, overloaded assignment operators don't map to Lua semantics and will be ignored, and C++ doesn't support Lua's concatenation operator (<tt>..</tt>).
</p>
<p>
In order to keep maximum compatibility within the different languages in SWIG, the Lua bindings uses the same set of operator names as python. Although internally it renames the functions to something else (on order to work with Lua).
<p>
The current list of operators which can be overloaded (and the alternative function names) are:<ul>
<li><tt>__add__</tt> operator+
<li><tt>__sub__</tt> operator-
<li><tt>__mul__</tt> operator *
<li><tt>__div__</tt> operator/
<li><tt>__neg__</tt> unary minus
<li><tt>__call__</tt> operator<tt>()</tt> (often used in functor classes)
<li><tt>__pow__</tt> the exponential fn (no C++ equivalent, Lua uses <tt>^</tt>)
<li><tt>__concat__</tt> the concatenation operator (SWIG maps C++'s <tt>~</tt> to Lua's <tt>..</tt>)
<li><tt>__eq__</tt> operator<tt>==</tt>
<li><tt>__lt__</tt> operator<tt><</tt>
<li><tt>__le__</tt> operator<tt><=</tt>
</ul>
<p>
Note: in Lua, only the equals, less than, and less than equals operators are defined. The other operators (!=,>,>=) are achieved by using a logical not applied to the results of other operators.
</p>
<p>
The following operators cannot be overloaded (mainly because they are not supported in Lua)<ul>
<li>++ and --<li>+=,-=,*= etc<li>% operator (you have to use math.mod)<li>assignment operator<li>all bitwise/logical operations</ul>
<p>
SWIG also accepts the <tt>__str__()</tt> member function which converts an object to a string. This function should return a const char*, preferably to static memory. This will be used for the <tt>print()</tt> and <tt>tostring()</tt> functions in Lua. Assuming the complex class has a function
</p>
<div class="code"><pre>const char* __str__()
{
static char buffer[255];
sprintf(buffer,"Complex(%g,%g)",this->re(),this->im());
return buffer;
}
</pre></div>
<p>
Then this will support the following code in Lua
</p>
<div class="targetlang"><pre>
> c = Complex(3,4)
> d = Complex(7,8)
> e = c + d
> print(e)
Complex(10,12)
> s=tostring(e) -- s is the number in string form
> print(s)
Complex(10,12)
</pre></div>
<p>
It is also possible to overload the operator<tt>[]</tt>, but currently this cannot be automatically performed. To overload the operator<tt>[]</tt> you need to provide two functions, <tt>__getitem__()</tt> and <tt>__setitem__()</tt>
</p>
<div class="code"><pre>class Complex
{
//....
double __getitem__(int i)const; // i is the index, returns the data
void __setitem__(int i,double d); // i is the index, d is the data
};
</pre></div>
<H3><a name="Lua_nn19"></a>26.3.12 Class extension with %extend</H3>
<p>
One of the more interesting features of SWIG is that it can extend structures and classes with new methods. In the previous section, the Complex class would have benefited greatly from an __str__() method as well as some repairs to the operator overloading. It can also be used to add additional functions to the class if they are needed.
</p>
<p>
Take the original Complex class
</p>
<div class="code"><pre>class Complex {
private:
double rpart, ipart;
public:
Complex(double r = 0, double i = 0) : rpart(r), ipart(i) { }
Complex(const Complex &c) : rpart(c.rpart), ipart(c.ipart) { }
Complex &operator=(const Complex &c);
Complex operator+(const Complex &c) const;
Complex operator-(const Complex &c) const;
Complex operator*(const Complex &c) const;
Complex operator-() const;
double re() const { return rpart; }
double im() const { return ipart; }
};
</pre></div>
<p>
Now we extend it with some new code
</p>
<div class="code"><pre>%extend Complex {
const char *__str__() {
static char tmp[1024];
sprintf(tmp,"Complex(%g,%g)", $self->re(),$self->im());
return tmp;
}
bool operator==(const Complex& c)
{ return ($self->re()==c.re() && $self->im()==c.im();}
};
</pre></div>
<p>
Now, in Lua
</p>
<div class="targetlang"><pre>
> c = Complex(3,4)
> d = Complex(7,8)
> e = c + d
> print(e) -- print uses __str__ to get the string form to print
Complex(10,12)
> print(e==Complex(10,12)) -- testing the == operator
true
> print(e!=Complex(12,12)) -- the != uses the == operator
true
</pre></div>
<p>
Extend works with both C and C++ code, on classes and structs. It does not modify the underlying object in any way---the extensions only show up in the Lua interface. The only item to take note of is the code has to use the '$self' instead of 'this', and that you cannot access protected/private members of the code (as you are not officially part of the class).
</p>
<H3><a name="Lua_nn20"></a>26.3.13 Using %newobject to release memory</H3>
<p> If you have a function that allocates memory like this,</p>
<div class="code">
<pre>char *foo() {
char *result = (char *) malloc(...);
...
return result;
}
</pre>
</div>
<p> then the SWIG generated wrappers will have a memory leak--the
returned data will be copied into a string object and the old contents
ignored.</p>
<p> To fix the memory leak, use the <a href="Customization.html#Customization_ownership">%newobject directive</a>.</p>
<div class="code">
<pre>%newobject foo;
...
char *foo();
</pre>
</div>
<p> This will release the allocated memory.</p>
<H3><a name="Lua_nn21"></a>26.3.14 C++ templates</H3>
<p>
C++ templates don't present a huge problem for SWIG. However, in order to create wrappers, you have to tell SWIG to create wrappers for a particular template instantiation. To do this, you use the template directive. For example:
</p>
<div class="code"><pre>%module example
%{
#include "pair.h"
%}
template<class T1, class T2>
struct pair {
typedef T1 first_type;
typedef T2 second_type;
T1 first;
T2 second;
pair();
pair(const T1&, const T2&);
~pair();
};
%template(pairii) pair<int,int>;
</pre></div>
<p>
In Lua:
</p>
<div class="targetlang"><pre>
> p = example.pairii(3,4)
> print(p.first,p.second)
3 4
</pre></div>
<p>
Obviously, there is more to template wrapping than shown in this example. More details can be found in the SWIG and C++ chapter. Some more complicated examples will appear later.
</p>
<H3><a name="Lua_nn22"></a>26.3.15 C++ Smart Pointers</H3>
<p>
In certain C++ programs, it is common to use classes that have been wrapped by so-called "smart pointers." Generally, this involves the use of a template class that implements operator->() like this:
</p>
<div class="code"><pre>template<class T> class SmartPtr {
...
T *operator->();
...
}
</pre></div>
<p>
Then, if you have a class like this,
</p>
<div class="code"><pre>class Foo {
public:
int x;
int bar();
};
</pre></div>
<p>
A smart pointer would be used in C++ as follows:
</p>
<div class="code"><pre>SmartPtr<Foo> p = CreateFoo(); // Created somehow (not shown)
...
p->x = 3; // Foo::x
int y = p->bar(); // Foo::bar
</pre></div>
<p>
To wrap this, simply tell SWIG about the SmartPtr class and the low-level Foo object. Make sure you instantiate SmartPtr using template if necessary. For example:
</p>
<div class="code"><pre>%module example
...
%template(SmartPtrFoo) SmartPtr<Foo>;
...
</pre></div>
<p>
Now, in Lua, everything should just "work":
</p>
<div class="targetlang"><pre>
> p = example.CreateFoo() -- Create a smart-pointer somehow
> p.x = 3 -- Foo::x
> print(p:bar()) -- Foo::bar
</pre></div>
<p>
If you ever need to access the underlying pointer returned by <tt>operator->()</tt> itself, simply use the <tt>__deref__()</tt> method. For example:
</p>
<div class="targetlang"><pre>
> f = p:__deref__() -- Returns underlying Foo *
</pre></div>
<H3><a name="Lua_nn23"></a>26.3.16 C++ Exceptions</H3>
<p>
Lua does not natively support exceptions, but it has errors which are similar. When a Lua function terminates with an error
it returns one value back to the caller. SWIG automatically maps any basic type which is thrown into a Lua error.
Therefore for a function:
</p>
<div class="code"><pre>
int message() throw(const char *) {
throw("I died.");
return 1;
}
</pre></div>
<p>
SWIG will automatically convert this to a Lua error.
</p>
<div class="targetlang"><pre>
> message()
I died.
stack traceback:
[C]: in function 'message'
stdin:1: in main chunk
[C]: ?
>
</pre></div>
<p>
If you want to catch an exception, you must use either pcall() or xpcall(), which are documented in the Lua manual.
Using xpcall will allow you to obtain additional debug information (such as a stacktrace).
</p>
<div class="targetlang"><pre>
> function a() b() end -- function a() calls function b()
> function b() message() end -- function b() calls C++ function message(), which throws
> ok,res=pcall(a) -- call the function
> print(ok,res)
false I died.
> ok,res=xpcall(a,debug.traceback) -- call the function
> print(ok,res)
false I died.
stack traceback:
[C]: in function 'message'
runme.lua:70: in function 'b'
runme.lua:67: in function <runme.lua:66>
[C]: in function 'xpcall'
runme.lua:95: in main chunk
[C]: ?
</pre></div>
<p>
SWIG is able to throw numeric types, enums, chars, char*'s and std::string's without problem. It has also written typemaps for std::exception and its derived classes, which convert the exception into an error string. </p>
<p>
However it's not so simple to throw other types of objects.
Thrown objects are not valid outside the 'catch' block. Therefore they cannot be
returned to the interpreter.
The obvious ways to overcome this would be to either return a copy of the object, or to convert the object to a string and
return that. Though it seems obvious to perform the former, in some cases this is not possible, most notably when
SWIG has no information about the object, or the object is not copyable/creatable.
</p>
<p>
Therefore by default SWIG converts all thrown object into strings and returns them. So given a function:
</p>
<div class="code"><pre>
void throw_A() throw(A*) {
throw new A();
}
</pre></div>
<p>
SWIG will just convert it (poorly) to a string and use that as its error. (This is not that useful, but it always works).
</p>
<div class="targetlang"><pre>
> throw_A()
object exception:A *
stack traceback:
[C]: in function 'unknown'
stdin:1: in main chunk
[C]: ?
>
</pre></div>
<p>
To get a more useful behaviour out of SWIG you must either: provide a way to convert your exceptions into strings, or
throw objects which can be copied.
</p>
<p>
If you have your own class which you want output as a string you will need to add a typemap something like this:
</p>
<div class="code"><pre>
%typemap(throws) my_except
%{
lua_pushstring(L,$1.what()); // assuming my_except::what() returns a const char* message
SWIG_fail; // trigger the error handler
%}
</pre></div>
<p>
If you wish your exception to be returned to the interpreter, it must firstly be copyable. Then you must have an additional
<tt>%apply</tt> statement, to tell SWIG to return a copy of this object to the interpreter. For example:
</p>
<div class="code"><pre>
%apply SWIGTYPE EXCEPTION_BY_VAL {Exc}; // tell SWIG to return Exc by value to interpreter
class Exc {
public:
Exc(int c, const char *m) {
code = c;
strncpy(msg,m,256);
}
int code;
char msg[256];
};
void throw_exc() throw(Exc) {
throw(Exc(42,"Hosed"));
}
</pre></div>
<p>
Then the following code can be used (note: we use pcall to catch the error so we can process the exception).
</p>
<div class="targetlang"><pre>
> ok,res=pcall(throw_exc)
> print(ok)
false
> print(res)
userdata: 0003D880
> print(res.code,res.msg)
42 Hosed
>
</pre></div>
<p>
Note: it is also possible (though tedious) to have a function throw several different kinds of exceptions. To process this
will require a pcall, followed by a set of if statements checking the type of the error.
</p>
<p>
All of this code assumes that your C++ code uses exception specification (which a lot doesn't).
If it doesn't consult the "<a href="SWIGPlus.html#SWIGPlus_catches">Exception handling with %catches</a>" section
and the "<a href="Customization.html#Customization_exception">Exception handling with %exception</a>" section, for more details on how to
add exception specification to functions or globally (respectively).
</p>
<H3><a name ="Lua_nn23_5"></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.
</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>
<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
namespace MyWorld {
class World {
public:
int create_world() { return 17;}
const int world_max_count = 9;
};
namespace Nested {
class Dweller {
enum Gender {MALE, FEMALE;
static int populate_cave() { return 19; }
int create_cave() { return 13;}
int food_count; // = 11
}
}
}
</pre></div>
Now, in Lua it could be used like this:
<div class="targetlang"><pre>
> example.module_function()
7
> print(example.module_variable)
8
> print(example.MyWorld.World():create_world())
17
> print(example.MyWorld.World.world_max_count)
9
> print(example.MyWordl.Nested.Dweller.MALE)
0
> print(example.MyWordl.Nested.Dweller().food_count)
11
>
</pre></div>
<H4> Backward compatibility </H4>
<p>
If SWIG is running in backward compatible way, i.e. without <tt>-no-old-metatable-bindings</tt> option, then additional old-style names are generated(notice the underscore):
</p>
<div class="targetlang"><pre>
9
> print(example.MyWorld.Nested.Dweller_MALE)
0
> print(example.MyWorld.Nested.Dweller_populate_cave())
11
>
</pre></div>
<H3> Backward compatibility </H3>
<H4> Names </H4>
<p> If SWIG is launched without <tt>-no-old-metatable-bindings</tt> option, then it enters backward-compatible mode. While in this mode, it tries
to generate additional names for static functions, class static constants and class enums.
Those names are in a form <tt>$classname_$symbolname</tt> and are added to the scope surrounding the class.
If %nspace is enabled, then class namespace is taken as scope. If there is no namespace, or %nspace is disabled,
then module is considered a class namespace.</p>
<p> Consider the following C++ code </p>
<div class="code"><pre>%module example
%nspace MyWorld::Test;
namespace MyWorld {
class Test {
public:
enum { TEST1 = 10, TEST2 }
static const int ICONST = 12;
};
class Test2 {
public:
enum { TEST3 = 20, TEST4 }
static const int ICONST2 = 23;
}
</pre></div>
<p> When in backward compatible mode, in addition to usual names, the following ones will be generated (notice the underscore):</p>
<div class="targetlang"><pre>
9
> print(example.MyWorld.Test_TEST1) -- Test has %nspace enabled
10
> print(example.MyWorld.Test_ICONST) -- Test has %nspace enabled
12
> print(example.Test2_TEST3) -- Test2 doesn't have %nspace enabled
20
> print(example.Test2_ICONST2) -- Test2 doesn't have %nspace enabled
23
>
</pre></div>
<p> There is a slight difference with enums when in C mode. As per C standard, enums from C structures are exported to
surrounding scope without any prefixing. Pretending that Test2 is a struct, not class, that would be:</p>
<div class="targetlang"><pre>
> print(example.TEST3) -- NOT Test2_TEST3
20
>
</pre></div>
<H4> Inheritance </H4>
<p> The internal organization of inheritance has changed.
Consider the following C++ code:</p>
<div class="code"><pre>%module example
class Base {
public:
int base_func()
};
class Derived : public Base {
public:
int derived_func()
}
</pre></div>
<p>Lets assume for a moment that class member functions are stored in <tt>.fn</tt> table. Previously, when classes
were exported to Lua during module initialization, for every derived class all service tables <tt>ST(i.e. ".fn")</tt>
were squashed and added to corresponding derived class <tt>ST</tt>: Everything from <tt>.fn</tt> table of class Base
was copied to <tt>.fn</tt> table of class Derived and so on. This was a recursive procedure, so in the end the whole
inheritance tree of derived class was squashed into derived class. </p>
<p> That means that any changes done to class Base after module initialization wouldn't affect class Derived:</p>
<div class="targetlang"><pre>
base = example.Base()
der = example.Derived()
> print(base.base_func)
function: 0x1367940
> getmetatable(base)[".fn"].new_func = function (x) return x -- Adding new function to class Base (to class, not to an instance!)
> print(base.new_func) -- Checking this function
function
> print(der.new_func) -- Wouldn't work. Derived doesn't check Base any more.
nil
>
</pre></div>
<p> This behaviour was changed. Now unless -squash-bases option is provided, Derived store a list of it's bases and if some symbol is not found in it's own service tables
then its bases are searched for it. Option -squash-bases will effectively return old behaviour.
<div class="targetlang"><pre>
> print(der.new_func) -- Now it works
function
>
</pre></div>
<H2><a name="Lua_nn24"></a>26.4 Typemaps</H2>
<p>This section explains what typemaps are and how to use them. The default wrapping behaviour of SWIG is enough in most cases. However sometimes SWIG may need a little additional assistance to know which typemap to apply to provide the best wrapping. This section will be explaining how to use typemaps to best effect</p>
<H3><a name="Lua_nn25"></a>26.4.1 What is a typemap?</H3>
<p>A typemap is nothing more than a code generation rule that is attached to a specific C datatype. For example, to convert integers from Lua to C, you might define a typemap like this:</p>
<div class="code"><pre>%module example
%typemap(in) int {
$1 = (int) lua_tonumber(L,$input);
printf("Received an integer : %d\n",$1);
}
%inline %{
extern int fact(int n);
%}
</pre></div>
<p><i>Note: you shouldn't use this typemap, as SWIG already has a typemap for this task. This is purely for example.</i></p>
<p>Typemaps are always associated with some specific aspect of code generation. In this case, the "in" method refers to the conversion of input arguments to C/C++. The datatype int is the datatype to which the typemap will be applied. The supplied C code is used to convert values. In this code a number of special variable prefaced by a $ are used. The $1 variable is placeholder for a local variable of type int. The $input is the index on the Lua stack for the value to be used.</p>
<p>When this example is compiled into a Lua module, it operates as follows:</p>
<div class="targetlang"><pre>> require "example"
> print(example.fact(6))
Received an integer : 6
720
</pre></div>
<H3><a name="Lua_nn26"></a>26.4.2 Using typemaps</H3>
<p>There are many ready written typemaps built into SWIG for all common types (int, float, short, long, char*, enum and more), which SWIG uses automatically, with no effort required on your part.</p>
<p>However for more complex functions which use input/output parameters or arrays, you will need to make use of <typemaps.i>, which contains typemaps for these situations. For example, consider these functions:</p>
<div class="code"><pre>void add(int x, int y, int *result) {
*result = x + y;
}
int sub(int *x1, int *y1) {
return *x1-*y1;
}
void swap(int *sx, int *sy) {
int t=*sx;
*sx=*sy;
*sy=t;
}
</pre></div>
<p>It is clear to the programmer, that 'result' is an output parameter, 'x1' and 'y1' are input parameters and 'sx' and 'sy' are input/output parameters. However is not apparent to SWIG, so SWIG must to informed about which kind they are, so it can wrapper accordingly.</p>
<p>One means would be to rename the argument name to help SWIG, eg <tt>void add(int x, int y, int *OUTPUT)</tt>, however it is easier to use the <tt>%apply</tt> to achieve the same result, as shown below.</p>
<div class="code"><pre>%include <typemaps.i>
%apply int* OUTPUT {int *result}; // int *result is output
%apply int* INPUT {int *x1, int *y1}; // int *x1 and int *y1 are input
%apply int* INOUT {int *sx, int *sy}; // int *sx and int *sy are input and output
void add(int x, int y, int *result);
int sub(int *x1, int *y1);
void swap(int *sx, int *sy);
</pre></div>
<p>When wrapped, it gives the following results:</p>
<div class="targetlang"><pre>> require "example"
> print(example.add(1,2))
3
> print(demo.sub(1,2))
-1
> a,b=1,2
> c,d=demo.swap(a,b)
> print(a,b,c,d)
1 2 2 1
</pre></div>
<p>Notice, that 'result' is not required in the arguments to call the function, as it an output parameter only. For 'sx' and 'sy' they must be passed in (as they are input), but the original value is not modified (Lua does not have a pass by reference feature). The modified results are then returned as two return values. All INPUT/OUTPUT/INOUT arguments will behave in a similar manner.</p>
<p>Note: C++ references must be handled exactly the same way. However SWIG will automatically wrap a <tt>const int&</tt> as an input parameter (since that it obviously input).</p>
<H3><a name="Lua_nn27"></a>26.4.3 Typemaps and arrays</H3>
<p>Arrays present a challenge for SWIG, because like pointers SWIG does not know whether these are input or output values, nor
does SWIG have any indication of how large an array should be. However with the proper guidance SWIG can easily wrapper
arrays for convenient usage.</p>
<p>Given the functions:</p>
<div class="code"><pre>extern void sort_int(int* arr, int len);
extern void sort_double(double* arr, int len);
</pre></div>
<p>There are basically two ways that SWIG can deal with this. The first way, uses the <tt><carrays.i></tt> library
to create an array in C/C++ then this can be filled within Lua and passed into the function. It works, but it's a bit tedious.
More details can be found in the <a href="Library.html#Library_carrays">carrays.i</a> documentation.</p>
<p>The second and more intuitive way, would be to pass a Lua table directly into the function, and have SWIG automatically convert between Lua-table and C-array. Within the <tt><typemaps.i></tt> file there are typemaps ready written to perform this task. To use them is again a matter of using %apply in the correct manner.</p>
<p>The wrapper file below, shows both the use of carrays as well as the use of the typemap to wrap arrays. </p>
<div class="code"><pre>// using the C-array
%include <carrays.i>
// this declares a batch of function for manipulating C integer arrays
%array_functions(int,int)
extern void sort_int(int* arr, int len); // the function to wrap
// using typemaps
%include <typemaps.i>
%apply (double *INOUT,int) {(double* arr,int len)};
extern void sort_double(double* arr, int len); // the function to wrap
</pre></div>
<p>Once wrapped, the functions can both be called, though with different ease of use:</p>
<div class="targetlang"><pre>require "example"
ARRAY_SIZE=10
-- passing a C array to the sort_int()
arr=example.new_int(ARRAY_SIZE) -- create the array
for i=0,ARRAY_SIZE-1 do -- index 0..9 (just like C)
example.int_setitem(arr,i,math.random(1000))
end
example.sort_int(arr,ARRAY_SIZE) -- call the function
example.delete_int(arr) -- must delete the allocated memory
-- use a typemap to call with a Lua-table
-- one item of note: the typemap creates a copy, rather than edit-in-place
t={} -- a Lua table
for i=1,ARRAY_SIZE do -- index 1..10 (Lua style)
t[i]=math.random(1000)/10
end
t=example.sort_double(t) -- replace t with the result
</pre></div>
<p>Obviously the first version could be made less tedious by writing a Lua function to perform the conversion from a table
to a C-array. The <tt>%luacode</tt> directive is good for this. See SWIG\Examples\lua\arrays for an example of this.</p>
<p><b>Warning:</b> in C indexes start at ZERO, in Lua indexes start at ONE. SWIG expects C-arrays to be filled for 0..N-1
and Lua tables to be 1..N, (the indexing follows the norm for the language). In the typemap when it converts the table to an array it quietly changes the indexing accordingly. Take note of this behaviour if you have a C function which returns indexes.</p>
<p>Note: SWIG also can support arrays of pointers in a similar manner.</p>
<H3><a name="Lua_nn28"></a>26.4.4 Typemaps and pointer-pointer functions</H3>
<p>Several C++ libraries use a pointer-pointer functions to create its objects. These functions require a pointer to a pointer which is then filled with the pointer to the new object. Microsoft's COM and DirectX as well as many other libraries have this kind of function. An example is given below:</p>
<div class="code"><pre>struct iMath; // some structure
int Create_Math(iMath** pptr); // its creator (assume it mallocs)
</pre></div>
<p>Which would be used with the following C code:</p>
<div class="code"><pre>iMath* ptr;
int ok;
ok=Create_Math(&ptr);
// do things with ptr
//...
free(ptr); // dispose of iMath
</pre></div>
<p>SWIG has a ready written typemap to deal with such a kind of function in <typemaps.i>. It provides the correct wrapping as well as setting the flag to inform Lua that the object in question should be garbage collected. Therefore the code is simply:</p>
<div class="code"><pre>%include <typemaps.i>
%apply SWIGTYPE** OUTPUT{iMath **pptr }; // tell SWIG it's an output
struct iMath; // some structure
int Create_Math(iMath** pptr); // its creator (assume it mallocs)
</pre></div>
<p>The usage is as follows:</p>
<div class="targetlang"><pre>ok,ptr=Create_Math() -- ptr is an iMath* which is returned with the int (ok)
ptr=nil -- the iMath* will be GC'ed as normal
</pre></div>
<H2><a name="Lua_nn29"></a>26.5 Writing typemaps</H2>
<p>This section describes how you can modify SWIG's default wrapping behavior for various C/C++ datatypes using the <tt>%typemap</tt> directive. This is an advanced topic that assumes familiarity with the Lua C API as well as the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter.</p>
<p>Before proceeding, it should be stressed that writing typemaps is rarely needed unless you want to change some aspect of the wrapping, or to achieve an effect which in not available with the default bindings.</p>
<p>Before proceeding, you should read the previous section on using typemaps, and look at the existing typemaps found in luatypemaps.swg and typemaps.i. These are both well documented and fairly easy to read. You should not attempt to write your own typemaps until you have read and can understand both of these files (they may well also give you an idea to base your work on).</p>
<H3><a name="Lua_nn30"></a>26.5.1 Typemaps you can write</H3>
<p>There are many different types of typemap that can be written, the full list can be found in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. However the following are the most commonly used ones.</p>
<ul>
<li><tt>in</tt> this is for input arguments to functions</li>
<li><tt>out</tt> this is for return types from functions</li>
<li><tt>argout</tt> this is for a function argument which is actually returning something</li>
<li><tt>typecheck</tt> this is used to determine which overloaded function should be called
(the syntax for the typecheck is different from the typemap, see typemaps for details).</li>
</ul>
<H3><a name="Lua_nn31"></a>26.5.2 SWIG's Lua-C API</H3>
<p>This section explains the SWIG specific Lua-C API. It does not cover the main Lua-C api, as this is well documented and not worth covering.</p>
<p><tt>int SWIG_ConvertPtr(lua_State* L,int index,void** ptr,swig_type_info *type,int flags);</tt></p>
<div class="indent">
This is the standard function used for converting a Lua userdata to a void*. It takes the value at the given index in the Lua state and converts it to a userdata. It will then provide the necessary type checks, confirming that the pointer is compatible with the type given in 'type'. Then finally setting '*ptr' to the pointer.
If flags is set to SWIG_POINTER_DISOWN, this is will clear any ownership flag set on the object.<br>
The returns a value which can be checked with the macro SWIG_IsOK()
</div>
<p><tt>void SWIG_NewPointerObj(lua_State* L,void* ptr,swig_type_info *type,int own);</tt></p>
<div class="indent">
This is the opposite of SWIG_ConvertPtr, as it pushes a new userdata which wrappers the pointer 'ptr' of type 'type'.
The parameter 'own' specifies if the object is owned be Lua and if it is 1 then Lua will GC the object when the userdata is disposed of.
</div>
<p><tt>void* SWIG_MustGetPtr(lua_State* L,int index,swig_type_info *type,int flags,int argnum,const char* func_name);</tt></p>
<div class="indent">
This function is a version of SWIG_ConvertPtr(), except that it will either work, or it will trigger a lua_error() with a text error message. This function is rarely used, and may be deprecated in the future.
</div>
<p><tt>SWIG_fail</tt></p>
<div class="indent">
This macro, when called within the context of a SWIG wrapped function, will jump to the error handler code. This will call any cleanup code (freeing any temp variables) and then triggers a lua_error.<br>
A common use for this code is:<br><pre>
if (!SWIG_IsOK(SWIG_ConvertPtr( .....)){
lua_pushstring(L,"something bad happened");
SWIG_fail;
}</pre></div>
<p><tt>SWIG_fail_arg(char* func_name,int argnum,char* type)</tt></p>
<div class="indent">
This macro, when called within the context of a SWIG wrapped function, will display the error message and jump to the error handler code. The error message is of the form
<pre>
"Error in <i>func_name</i> (arg <i>argnum</i>), expected '<i>type</i>' got '<i>whatever the type was</i>'"
</pre></div>
<p><tt>SWIG_fail_ptr(const char* fn_name,int argnum,swig_type_info* type);</tt></p>
<div class="indent">
Similar to SWIG_fail_arg, except that it will display the swig_type_info information instead.</div>
<H2><a name="Lua_nn32"></a>26.6 Customization of your Bindings</H2>
<p>
This section covers adding of some small extra bits to your module to add the last finishing touches.
</p>
<H3><a name="Lua_nn33"></a>26.6.1 Writing your own custom wrappers</H3>
<p>
Sometimes, it may be necessary to add your own special functions, which bypass the normal SWIG wrapper method, and just use the native Lua API calls. These 'native' functions allow direct adding of your own code into the module. This is performed with the <tt>%native</tt> directive as follows:
</p>
<div class="code"><pre>%native(my_func) int native_function(lua_State*L); // registers native_function() with SWIG
...
%{
int native_function(lua_State*L) // my native code
{
...
}
%}
</pre></div>
<p>
The <tt>%native</tt> directive in the above example, tells SWIG that there is a function <tt>int native_function(lua_State*L);</tt> which is to be added into the module under the name '<tt>my_func</tt>'. SWIG will not add any wrapper for this function, beyond adding it into the function table. How you write your code is entirely up to you.
</p>
<H3><a name="Lua_nn34"></a>26.6.2 Adding additional Lua code</H3>
<p>
As well as adding additional C/C++ code, it's also possible to add your own Lua code to the module as well.
This code is executed once all other initialisation, including the %init code has been called.
</p>
<p>
The directive <tt>%luacode</tt> adds code into the module which is executed upon loading. Normally you would
use this to add your own functions to the module. Though you could easily perform other tasks.
</p>
<div class="code"><pre>%module example;
%luacode {
function example.greet()
print "hello world"
end
print "Module loaded ok"
}
...
%}
</pre></div>
<p>
Notice that the code is not part of the module table. Therefore any references to the module must have the
module name added.
</p>
<p>
Should there be an error in the Lua code, this will <em>not</em> stop loading of the module.
The default behaviour of SWIG is to print an error message to stderr and then continue.
It is possible to change this behaviour by using a <tt>#define SWIG_DOSTRING_FAIL(STR)</tt> to
define a different behaviour should the code fail.
</p>
<p>
Good uses for this feature is adding of new code, or writing helper functions to simplify some of the code.
See Examples/lua/arrays for an example of this code.
</p>
<H2><a name="Lua_nn35"></a>26.7 Details on the Lua binding</H2>
<p>
In the previous section, a high-level view of Lua wrapping was presented. Obviously a lot of stuff happens behind the scenes to make this happen. This section will explain some of the low-level details on how this is achieved.
</p>
<p>
<i>If you just want to use SWIG and don't care how it works, then stop reading here. This is going into the guts of the code and how it works. It's mainly for people who need to know what's going on within the code.
</i>
</p>
<H3><a name="Lua_nn36"></a>26.7.1 Binding global data into the module.</H3>
<p>
Assuming that you had some global data that you wanted to share between C and Lua. How does SWIG do it?
</p>
<div class="code"><pre>%module example;
extern double Foo;
</pre></div>
<p>
SWIG will effectively generate the pair of functions
</p>
<div class="code"><pre>void Foo_set(double);
double Foo_get();
</pre></div>
<p>
At initialisation time, it will then add to the interpreter a table called 'example', which represents the module. It will then add all its functions to the module. (Note: older versions of SWIG actually added the Foo_set() and Foo_get() functions, current implementation does not add these functions any more.) But it also adds a metatable to this table, which has two functions (<tt>__index</tt> and <tt>__newindex</tt>) as well as two tables (<tt>.get</tt> and <tt>.set</tt>) The following Lua code will show these hidden features.
</p>
<div class="targetlang"><pre>
> print(example)
table: 003F8F90
> m=getmetatable(example)
> table.foreach(m,print)
.set table: 003F9088
.get table: 003F9038
__index function: 003F8FE0
__newindex function: 003F8FF8
> g=m['.get']
> table.foreach(g,print)
Foo function: 003FAFD8
>
</pre></div>
<p>
The .get and .set tables are lookups connecting the variable name 'Foo' to the accessor/mutator functions (Foo_set,Foo_get)
</p>
<p>
The Lua equivalent of the code for the <tt>__index</tt> and <tt>__newindex</tt> looks a bit like this
</p>
<div class="targetlang"><pre>
function __index(mod,name)
local g=getmetatable(mod)['.get'] -- gets the table
if not g then return nil end
local f=g[name] -- looks for the function
-- calls it & returns the value
if type(f)=="function" then return f() end
return nil
end
function __newindex(mod,name,value)
local s=getmetatable(mod)['.set'] -- gets the table
if not s then return end
local f=s[name] -- looks for the function
-- calls it to set the value
if type(f)=="function" then f(value)
else rawset(mod,name,value) end
end
</pre></div>
<p>
That way when you call '<tt>a=example.Foo</tt>', the interpreter looks at the table 'example' sees that there is no field 'Foo' and calls __index. This will in turn check in '.get' table and find the existence of 'Foo' and then return the value of the C function call 'Foo_get()'. Similarly for the code '<tt>example.Foo=10</tt>', the interpreter will check the table, then call the __newindex which will then check the '.set' table and call the C function 'Foo_set(10)'.
</p>
<H3><a name="Lua_nn37"></a>26.7.2 Userdata and Metatables</H3>
<p>
As mentioned earlier, classes and structures, are all held as pointer, using the Lua 'userdata' structure. This structure is actually a pointer to a C structure 'swig_lua_userdata', which contains the pointer to the data, a pointer to the swig_type_info (an internal SWIG struct) and a flag which marks if the object is to be disposed of when the interpreter no longer needs it. The actual accessing of the object is done via the metatable attached to this userdata.
</p>
<p>
The metatable is a Lua 5.0 feature (which is also why SWIG cannot wrap Lua 4.0). It's a table which holds a list of functions, operators and attributes. This is what gives the userdata the feeling that it is a real object and not just a hunk of memory.
</p>
<p>
Given a class
</p>
<div class="code"><pre>%module excpp;
class Point
{
public:
int x,y;
Point(){x=y=0;}
~Point(){}
virtual void Print(){printf("Point @%p (%d,%d)\n",this,x,y);}
};
</pre></div>
<p>
SWIG will create a module excpp, with all the various functions inside. However to allow the intuitive use of the userdata, SWIG also creates up a set of metatables. As seen in the above section on global variables, use of the metatables allows for wrappers to be used intuitively. To save effort, the code creates one metatable per class and stores it inside Lua's registry. Then when a new object is instantiated, the metatable is found in the registry and the userdata associated with the metatable. Currently, derived classes make a complete copy of the base class' table and then add on their own additional functions.
</p>
<p>
Some of the internals can be seen by looking at the metatable of a class:
</p>
<div class="targetlang"><pre>
> p=excpp.Point()
> print(p)
userdata: 003FDB28
> m=getmetatable(p)
> table.foreach(m,print)
.type Point
__gc function: 003FB6C8
__newindex function: 003FB6B0
__index function: 003FB698
.get table: 003FB4D8
.set table: 003FB500
.fn table: 003FB528
</pre></div>
<p>
The '.type' attribute is the name of the class. The '.get' and '.set' tables work in a similar manner to the modules, the main difference is the '.fn' table which also holds all the member functions. (The '__gc' function is the class' destructor function)
</p>
<p>
The Lua equivalent of the code for enabling functions looks a little like this
</p>
<div class="targetlang"><pre>
function __index(obj,name)
local m=getmetatable(obj) -- gets the metatable
if not m then return nil end
local g=m['.get'] -- gets the attribute table
if not g then return nil end
local f=g[name] -- looks for the get_attribute function
-- calls it & returns the value
if type(f)=="function" then return f() end
-- ok, so it not an attribute, maybe it's a function
local fn=m['.fn'] -- gets the function table
if not fn then return nil end
local f=fn[name] -- looks for the function
-- if found the fn then return the function
-- so the interpreter can call it
if type(f)=="function" then return f end
return nil
end
</pre></div>
<p>
So when 'p:Print()' is called, the __index looks on the object metatable for a 'Print' attribute, then looks for a 'Print' function. When it finds the function, it returns the function, and then interpreter can call 'Point_Print(p)'
</p>
<p>
In theory, you can play with this usertable & add new features, but remember that it is a shared table between all instances of one class, and you could very easily corrupt the functions in all the instances.
</p>
<p>
Note: Both the opaque structures (like the FILE*) and normal wrapped classes/structs use the same 'swig_lua_userdata' structure. Though the opaque structures has do not have a metatable attached, or any information on how to dispose of them when the interpreter has finished with them.
</p>
<p>
Note: Operator overloads are basically done in the same way, by adding functions such as '__add' & '__call' to the class' metatable. The current implementation is a bit rough as it will add any member function beginning with '__' into the metatable too, assuming its an operator overload.
</p>
<H3><a name="Lua_nn38"></a>26.7.3 Memory management</H3>
<p>
Lua is very helpful with the memory management. The 'swig_lua_userdata' is fully managed by the interpreter itself. This means that neither the C code nor the Lua code can damage it. Once a piece of userdata has no references to it, it is not instantly collected, but will be collected when Lua deems is necessary. (You can force collection by calling the Lua function <tt>collectgarbage()</tt>). Once the userdata is about to be free'ed, the interpreter will check the userdata for a metatable and for a function '__gc'. If this exists this is called. For all complete types (ie normal wrapped classes & structs) this should exist. The '__gc' function will check the 'swig_lua_userdata' to check for the 'own' field and if this is true (which is will be for all owned data) it will then call the destructor on the pointer.
</p>
<p>
It is currently not recommended to edit this field or add some user code, to change the behaviour. Though for those who wish to try, here is where to look.
</p>
<p>
It is also currently not possible to change the ownership flag on the data (unlike most other scripting languages, Lua does not permit access to the data from within the interpreter).
</p>
</body>
</html>
|
