PageRenderTime 66ms CodeModel.GetById 13ms RepoModel.GetById 0ms app.codeStats 1ms

/Doc/Manual/Extending.html

https://github.com/sunaku/swig-ruby-ffi
HTML | 4034 lines | 3273 code | 755 blank | 6 comment | 0 complexity | 2ef4bba18c35dc72606eabd75981c999 MD5 | raw file
Possible License(s): 0BSD, GPL-2.0, LGPL-2.1 
    

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
    2. 

  2. <html>
    3. 

  3. <head>
    4. 

  4. <title>Extending SWIG to support new languages</title>
    5. 

  5. <link rel="stylesheet" type="text/css" href="style.css">
    6. 

  6. </head>
    7. 

  7. 

  8. <body bgcolor="#ffffff">
    9. 

  9. <H1><a name="Extending"></a>35 Extending SWIG to support new languages</H1>
    10. 

  10. <!-- INDEX -->
    11. 

  11. <div class="sectiontoc">
    12. 

  12. <ul>
    13. 

  13. <li><a href="#Extending_nn2">Introduction</a>
    14. 

  14. <li><a href="#Extending_nn3">Prerequisites</a>
    15. 

  15. <li><a href="#Extending_nn4">The Big Picture</a>
    16. 

  16. <li><a href="#Extending_nn5">Execution Model</a>
    17. 

  17. <ul>
    18. 

  18. <li><a href="#Extending_nn6">Preprocessing</a>
    19. 

  19. <li><a href="#Extending_nn7">Parsing</a>
    20. 

  20. <li><a href="#Extending_nn8">Parse Trees</a>
    21. 

  21. <li><a href="#Extending_nn9">Attribute namespaces</a>
    22. 

  22. <li><a href="#Extending_nn10">Symbol Tables</a>
    23. 

  23. <li><a href="#Extending_nn11">The %feature directive</a>
    24. 

  24. <li><a href="#Extending_nn12">Code Generation</a>
    25. 

  25. <li><a href="#Extending_nn13">SWIG and XML</a>
    26. 

  26. </ul>
    27. 

  27. <li><a href="#Extending_nn14">Primitive Data Structures</a>
    28. 

  28. <ul>
    29. 

  29. <li><a href="#Extending_nn15">Strings</a>
    30. 

  30. <li><a href="#Extending_nn16">Hashes</a>
    31. 

  31. <li><a href="#Extending_nn17">Lists</a>
    32. 

  32. <li><a href="#Extending_nn18">Common operations</a>
    33. 

  33. <li><a href="#Extending_nn19">Iterating over Lists and Hashes</a>
    34. 

  34. <li><a href="#Extending_nn20">I/O</a>
    35. 

  35. </ul>
    36. 

  36. <li><a href="#Extending_nn21">Navigating and manipulating parse trees</a>
    37. 

  37. <li><a href="#Extending_nn22">Working with attributes</a>
    38. 

  38. <li><a href="#Extending_nn23">Type system</a>
    39. 

  39. <ul>
    40. 

  40. <li><a href="#Extending_nn24">String encoding of types</a>
    41. 

  41. <li><a href="#Extending_nn25">Type construction</a>
    42. 

  42. <li><a href="#Extending_nn26">Type tests</a>
    43. 

  43. <li><a href="#Extending_nn27">Typedef and inheritance</a>
    44. 

  44. <li><a href="#Extending_nn28">Lvalues</a>
    45. 

  45. <li><a href="#Extending_nn29">Output functions</a>
    46. 

  46. </ul>
    47. 

  47. <li><a href="#Extending_nn30">Parameters</a>
    48. 

  48. <li><a href="#Extending_nn31">Writing a Language Module</a>
    49. 

  49. <ul>
    50. 

  50. <li><a href="#Extending_nn32">Execution model</a>
    51. 

  51. <li><a href="#Extending_starting_out">Starting out</a>
    52. 

  52. <li><a href="#Extending_nn34">Command line options</a>
    53. 

  53. <li><a href="#Extending_nn35">Configuration and preprocessing</a>
    54. 

  54. <li><a href="#Extending_nn36">Entry point to code generation</a>
    55. 

  55. <li><a href="#Extending_nn37">Module I/O and wrapper skeleton</a>
    56. 

  56. <li><a href="#Extending_nn38">Low-level code generators</a>
    57. 

  57. <li><a href="#Extending_nn39">Configuration files</a>
    58. 

  58. <li><a href="#Extending_nn40">Runtime support</a>
    59. 

  59. <li><a href="#Extending_nn41">Standard library files</a>
    60. 

  60. <li><a href="#Extending_nn42">User examples</a>
    61. 

  61. <li><a href="#Extending_test_suite">Test driven development and the test-suite</a>
    62. 

  62. <ul>
    63. 

  63. <li><a href="#Extending_running_test_suite">Running the test-suite</a>
    64. 

  64. </ul>
    65. 

  65. <li><a href="#Extending_nn43">Documentation</a>
    66. 

  66. <li><a href="#Extending_prerequisites">Prerequisites for adding a new language module to the SWIG distribution</a>
    67. 

  67. <li><a href="#Extending_coding_style_guidelines">Coding style guidelines</a>
    68. 

  68. </ul>
    69. 

  69. <li><a href="#Extending_debugging_options">Debugging Options</a>
    70. 

  70. <li><a href="#Extending_nn46">Guide to parse tree nodes</a>
    71. 

  71. <li><a href="#Extending_further_info">Further Development Information</a>
    72. 

  72. </ul>
    73. 

  73. </div>
    74. 

  74. <!-- INDEX -->
    75. 

  75. 

  76. 

  77. 

  78. <H2><a name="Extending_nn2"></a>35.1 Introduction</H2>
    79. 

  79. 

  80. 

  81. <p>
    82. 

  82. This chapter describes SWIG's internal organization and the process by which
    83. 

  83. new target languages can be developed.    First, a brief word of warning---SWIG
    84. 

  84. is continually evolving.
    85. 

  85. The information in this chapter is mostly up to
    86. 

  86. date, but changes are ongoing.   Expect a few inconsistencies.
    87. 

  87. </p>
    88. 

  88. 

  89. <p>
    90. 

  90. Also, this chapter is not meant to be a hand-holding tutorial.  As a starting point,
    91. 

  91. you should probably look at one of SWIG's existing modules.
    92. 

  92. </p>
    93. 

  93. 

  94. <H2><a name="Extending_nn3"></a>35.2 Prerequisites</H2>
    95. 

  95. 

  96. 

  97. <p>
    98. 

  98. In order to extend SWIG, it is useful to have the following background:
    99. 

  99. </p>
    100. 

  100. 

  101. <ul>
    102. 

  102. <li>An understanding of the C API for the target language.
    103. 

  103. <li>A good grasp of the C++ type system.
    104. 

  104. <li>An understanding of typemaps and some of SWIG's advanced features.
    105. 

  105. <li>Some familiarity with writing C++ (language modules are currently written in C++).
    106. 

  106. </ul>
    107. 

  107. 

  108. <p>
    109. 

  109. Since SWIG is essentially a specialized C++ compiler, it may be useful
    110. 

  110. to have some prior experience with compiler design (perhaps even a
    111. 

  111. compilers course) to better understand certain parts of the system.  A
    112. 

  112. number of books will also be useful.  For example, "The C Programming
    113. 

  113. Language" by Kernighan and Ritchie (a.k.a, "K&amp;R") and the C++ standard,
    114. 

  114. "ISO/IEC 14882 Programming Languages - C++" will be of great use.
    115. 

  115. </p>
    116. 

  116. 

  117. <p>
    118. 

  118. Also, it is useful to keep in mind that SWIG primarily operates as an
    119. 

  119. extension of the C++ <em>type</em> system.  At first glance, this might not be
    120. 

  120. obvious, but almost all SWIG directives as well as the low-level generation of
    121. 

  121. wrapper code are driven by C++ datatypes.
    122. 

  122. </p>
    123. 

  123. 

  124. <H2><a name="Extending_nn4"></a>35.3 The Big Picture</H2>
    125. 

  125. 

  126. 

  127. <p>
    128. 

  128. SWIG is a special purpose compiler that parses C++ declarations to
    129. 

  129. generate wrapper code.  To make this conversion possible, SWIG makes
    130. 

  130. three fundamental extensions to the C++ language:
    131. 

  131. </p>
    132. 

  132. 

  133. <ul>
    134. 

  134. <li><b>Typemaps</b>. Typemaps are used to define the
    135. 

  135. conversion/marshalling behavior of specific C++ datatypes.  All type conversion in SWIG is
    136. 

  136. based on typemaps.  Furthermore, the association of typemaps to datatypes utilizes an advanced pattern matching
    137. 

  137. mechanism that is fully integrated with the C++ type system.
    138. 

  138. </li>
    139. 

  139. 

  140. <li><b>Declaration Annotation</b>. To customize wrapper code
    141. 

  141. generation, most declarations can be annotated with special features.
    142. 

  142. For example, you can make a variable read-only, you can ignore a
    143. 

  143. declaration, you can rename a member function, you can add exception
    144. 

  144. handling, and so forth.  Virtually all of these customizations are built on top of a low-level
    145. 

  145. declaration annotator that can attach arbitrary attributes to any declaration.
    146. 

  146. Code generation modules can look for these attributes to guide the wrapping process.
    147. 

  147. </li>
    148. 

  148. 

  149. <li><b>Class extension</b>. SWIG allows classes and structures to be extended with new
    150. 

  150. methods and attributes (the <tt>%extend</tt> directive).   This has the effect of altering
    151. 

  151. the API in the target language and can be used to generate OO interfaces to C libraries.
    152. 

  152. </ul>
    153. 

  153. 

  154. <p>
    155. 

  155. It is important to emphasize that virtually all SWIG features reduce to one of these three
    156. 

  156. fundamental concepts.  The type system and pattern matching rules also play a critical
    157. 

  157. role in making the system work.  For example, both typemaps and declaration annotation are
    158. 

  158. based on pattern matching and interact heavily with the underlying type system.
    159. 

  159. </p>
    160. 

  160. 

  161. <H2><a name="Extending_nn5"></a>35.4 Execution Model</H2>
    162. 

  162. 

  163. 

  164. <p>
    165. 

  165. When you run SWIG on an interface, processing is handled in stages by a series of system components:
    166. 

  166. </p>
    167. 

  167. 

  168. <ul>
    169. 

  169. <li>An integrated C preprocessor reads a collection of configuration
    170. 

  170. files and the specified interface file into memory.  The preprocessor
    171. 

  171. performs the usual functions including macro expansion and file
    172. 

  172. inclusion.   However, the preprocessor also performs some transformations of the
    173. 

  173. interface.  For instance, <tt>#define</tt> statements are sometimes transformed into
    174. 

  174. <tt>%constant</tt> declarations.  In addition, information related to file/line number
    175. 

  175. tracking is inserted.
    176. 

  176. </li>
    177. 

  177. 

  178. <li>A C/C++ parser reads the preprocessed input and generates a full
    179. 

  179. parse tree of all of the SWIG directives and C declarations found.
    180. 

  180. The parser is responsible for many aspects of the system including
    181. 

  181. renaming, declaration annotation, and template expansion.  However, the parser
    182. 

  182. does not produce any output nor does it interact with the target
    183. 

  183. language module as it runs.  SWIG is not a one-pass compiler.
    184. 

  184. </li>
    185. 

  185. 

  186. <li>A type-checking pass is made. This adjusts all of the C++ typenames to properly
    187. 

  187. handle namespaces, typedefs, nested classes, and other issues related to type scoping.
    188. 

  188. </li>
    189. 

  189. 

  190. <li>A semantic pass is made on the parse tree to collect information
    191. 

  191. related to properties of the C++ interface.  For example, this pass
    192. 

  192. would determine whether or not a class allows a default constructor.
    193. 

  193. </li>
    194. 

  194. 

  195. <li>A code generation pass is made using a specific target language
    196. 

  196. module.  This phase is responsible for generating the actual wrapper
    197. 

  197. code.  All of SWIG's user-defined modules are invoked during this
    198. 

  198. latter stage of compilation.
    199. 

  199. </li>
    200. 

  200. </ul>
    201. 

  201. 

  202. <p>
    203. 

  203. The next few sections briefly describe some of these stages.
    204. 

  204. </p>
    205. 

  205. 

  206. <H3><a name="Extending_nn6"></a>35.4.1 Preprocessing</H3>
    207. 

  207. 

  208. 

  209. <p>
    210. 

  210. The preprocessor plays a critical role in the SWIG implementation.  This is because a lot
    211. 

  211. of SWIG's processing and internal configuration is managed not by code written in C, but
    212. 

  212. by configuration files in the SWIG library.  In fact, when you
    213. 

  213. run SWIG, parsing starts with a small interface file like this (note: this explains
    214. 

  214. the cryptic error messages that new users sometimes get when SWIG is misconfigured or installed
    215. 

  215. incorrectly):
    216. 

  216. </p>
    217. 

  217. 

  218. <div class="code">
    219. 

  219. <pre>
    220. 

  220. %include "swig.swg"             // Global SWIG configuration
    221. 

  221. %include "<em>langconfig.swg</em>"       // Language specific configuration
    222. 

  222. %include "yourinterface.i"      // Your interface file
    223. 

  223. </pre>
    224. 

  224. </div>
    225. 

  225. 

  226. <p>
    227. 

  227. The <tt>swig.swg</tt> file contains global configuration information.  In addition, this file
    228. 

  228. defines many of SWIG's standard directives as macros.  For instance, part of
    229. 

  229. of <tt>swig.swg</tt> looks like this:
    230. 

  230. </p>
    231. 

  231. 

  232. <div class="code">
    233. 

  233. <pre>
    234. 

  234. ...
    235. 

  235. /* Code insertion directives such as %wrapper %{ ... %} */
    236. 

  236. 

  237. #define %begin       %insert("begin")
    238. 

  238. #define %runtime     %insert("runtime")
    239. 

  239. #define %header      %insert("header")
    240. 

  240. #define %wrapper     %insert("wrapper")
    241. 

  241. #define %init        %insert("init")
    242. 

  242. 

  243. /* Access control directives */
    244. 

  244. 

  245. #define %immutable   %feature("immutable","1")
    246. 

  246. #define %mutable     %feature("immutable")
    247. 

  247. 

  248. /* Directives for callback functions */
    249. 

  249. 

  250. #define %callback(x) %feature("callback") `x`;
    251. 

  251. #define %nocallback  %feature("callback");
    252. 

  252. 

  253. /* %ignore directive */
    254. 

  254. 

  255. #define %ignore         %rename($ignore)
    256. 

  256. #define %ignorewarn(x)  %rename("$ignore:" x)
    257. 

  257. ...
    258. 

  258. </pre>
    259. 

  259. </div>
    260. 

  260. 

  261. <p>
    262. 

  262. The fact that most of the standard SWIG directives are macros is
    263. 

  263. intended to simplify the implementation of the internals.  For instance,
    264. 

  264. rather than having to support dozens of special directives, it is
    265. 

  265. easier to have a few basic primitives such as <tt>%feature</tt> or
    266. 

  266. <tt>%insert</tt>.
    267. 

  267. </p>
    268. 

  268. 

  269. <p>
    270. 

  270. The <em><tt>langconfig.swg</tt></em> file is supplied by the target
    271. 

  271. language. This file contains language-specific configuration
    272. 

  272. information.  More often than not, this file provides run-time wrapper
    273. 

  273. support code (e.g., the type-checker) as well as a collection of
    274. 

  274. typemaps that define the default wrapping behavior.  Note: the name of this
    275. 

  275. file depends on the target language and is usually something like <tt>python.swg</tt>
    276. 

  276. or <tt>perl5.swg</tt>.
    277. 

  277. </p>
    278. 

  278. 

  279. <p>
    280. 

  280. As a debugging aide, the text that SWIG feeds to its C++ parser can be
    281. 

  281. obtained by running <tt>swig -E interface.i</tt>.  This output
    282. 

  282. probably isn't too useful in general, but it will show how macros have
    283. 

  283. been expanded as well as everything else that goes into the low-level
    284. 

  284. construction of the wrapper code.
    285. 

  285. </p>
    286. 

  286. 

  287. <H3><a name="Extending_nn7"></a>35.4.2 Parsing</H3>
    288. 

  288. 

  289. 

  290. <p>
    291. 

  291. The current C++ parser handles a subset of C++.  Most incompatibilities with C are due to
    292. 

  292. subtle aspects of how SWIG parses declarations.  Specifically, SWIG expects all C/C++ declarations to follow this general form:
    293. 

  293. </p>
    294. 

  294. 

  295. <div class="diagram">
    296. 

  296. <pre>
    297. 

  297. <em>storage</em> <em>type</em> <em>declarator</em> <em>initializer</em>;
    298. 

  298. </pre>
    299. 

  299. </div>
    300. 

  300. 

  301. <p>
    302. 

  302. <tt><em>storage</em></tt> is a keyword such as <tt>extern</tt>,
    303. 

  303. <tt>static</tt>, <tt>typedef</tt>, or <tt>virtual</tt>.  <tt><em>type</em></tt> is a primitive
    304. 

  304. datatype such as <tt>int</tt> or <tt>void</tt>.   <tt><em>type</em></tt> may be optionally
    305. 

  305. qualified with a qualifier such as <tt>const</tt> or <tt>volatile</tt>. <tt><em>declarator</em></tt>
    306. 

  306. is a name with additional type-construction modifiers attached to it (pointers, arrays, references,
    307. 

  307. functions, etc.).  Examples of declarators include <tt>*x</tt>, <tt>**x</tt>, <tt>x[20]</tt>, and
    308. 

  308. <tt>(*x)(int,double)</tt>.   The <tt><em>initializer</em></tt> may be a value assigned using <tt>=</tt> or
    309. 

  309. body of code enclosed in braces <tt>{ ... }</tt>.
    310. 

  310. </p>
    311. 

  311. 

  312. <p>
    313. 

  313. This declaration format covers most common C++ declarations. However, the C++ standard
    314. 

  314. is somewhat more flexible in the placement of the parts.  For example, it is technically legal, although
    315. 

  315. uncommon to write something like <tt>int typedef const a</tt> in your program.   SWIG simply
    316. 

  316. doesn't bother to deal with this case.
    317. 

  317. </p>
    318. 

  318. 

  319. <p>
    320. 

  320. The other significant difference between C++ and SWIG is in the
    321. 

  321. treatment of typenames.  In C++, if you have a declaration like this,
    322. 

  322. </p>
    323. 

  323. 

  324. <div class="code">
    325. 

  325. <pre>
    326. 

  326. int blah(Foo *x, Bar *y);
    327. 

  327. </pre>
    328. 

  328. </div>
    329. 

  329. 

  330. <p>
    331. 

  331. it won't parse correctly unless <tt>Foo</tt> and <tt>Bar</tt> have
    332. 

  332. been previously defined as types either using a <tt>class</tt>
    333. 

  333. definition or a <tt>typedef</tt>.  The reasons for this are subtle,
    334. 

  334. but this treatment of typenames is normally integrated at the level of the C
    335. 

  335. tokenizer---when a typename appears, a different token is returned to the parser
    336. 

  336. instead of an identifier.
    337. 

  337. </p>
    338. 

  338. 

  339. <p>
    340. 

  340. SWIG does not operate in this manner--any legal identifier can be used
    341. 

  341. as a type name.  The reason for this is primarily motivated by the use
    342. 

  342. of SWIG with partially defined data.  Specifically,
    343. 

  343. SWIG is supposed to be easy to use on interfaces with missing type information.
    344. 

  344. </p>
    345. 

  345. 

  346. <p>
    347. 

  347. Because of the different treatment of typenames, the most serious
    348. 

  348. limitation of the SWIG parser is that it can't process type declarations where
    349. 

  349. an extra (and unnecessary) grouping operator is used.  For example:
    350. 

  350. </p>
    351. 

  351. 

  352. <div class="code">
    353. 

  353. <pre>
    354. 

  354. int (x);         /* A variable x */
    355. 

  355. int (y)(int);    /* A function y */
    356. 

  356. </pre>
    357. 

  357. </div>
    358. 

  358. 

  359. <p>
    360. 

  360. The placing of extra parentheses in type declarations like this is
    361. 

  361. already recognized by the C++ community as a potential source of
    362. 

  362. strange programming errors. For example, Scott Meyers "Effective STL"
    363. 

  363. discusses this problem in a section on avoiding C++'s "most vexing
    364. 

  364. parse."
    365. 

  365. </p>
    366. 

  366. 

  367. <p>
    368. 

  368. The parser is also unable to handle declarations with no return type or bare argument names.
    369. 

  369. For example, in an old C program, you might see things like this:
    370. 

  370. </p>
    371. 

  371. 

  372. <div class="code">
    373. 

  373. <pre>
    374. 

  374. foo(a,b) {
    375. 

  375. ...
    376. 

  376. }
    377. 

  377. </pre>
    378. 

  378. </div>
    379. 

  379. 

  380. <p>
    381. 

  381. In this case, the return type as well as the types of the arguments
    382. 

  382. are taken by the C compiler to be an <tt>int</tt>.  However, SWIG
    383. 

  383. interprets the above code as an abstract declarator for a function
    384. 

  384. returning a <tt>foo</tt> and taking types <tt>a</tt> and <tt>b</tt> as
    385. 

  385. arguments).
    386. 

  386. </p>
    387. 

  387. 

  388. <H3><a name="Extending_nn8"></a>35.4.3 Parse Trees</H3>
    389. 

  389. 

  390. 

  391. <p>
    392. 

  392. The SWIG parser produces a complete parse tree of the input file before any wrapper code
    393. 

  393. is actually generated.  Each item in the tree is known as a "Node".   Each node is identified
    394. 

  394. by a symbolic tag.   Furthermore, a node may have an arbitrary number of children.
    395. 

  395. The parse tree structure and tag names of an interface can be displayed using <tt>swig -debug-tags</tt>.
    396. 

  396. For example:
    397. 

  397. </p>
    398. 

  398. 

  399. <div class="shell">
    400. 

  400. <pre>
    401. 

  401. $ <b>swig -c++ -python -debug-tags example.i</b>
    402. 

  402.  . top (example.i:1)
    403. 

  403.  . top . include (example.i:1)
    404. 

  404.  . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/swig.swg:71)
    405. 

  405.  . top . include . typemap . typemapitem (/r0/beazley/Projects/lib/swig1.3/swig.swg:71)
    406. 

  406.  . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/swig.swg:83)
    407. 

  407.  . top . include . typemap . typemapitem (/r0/beazley/Projects/lib/swig1.3/swig.swg:83)
    408. 

  408.  . top . include (example.i:4)
    409. 

  409.  . top . include . insert (/r0/beazley/Projects/lib/swig1.3/python/python.swg:7)
    410. 

  410.  . top . include . insert (/r0/beazley/Projects/lib/swig1.3/python/python.swg:8)
    411. 

  411.  . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/python/python.swg:19)
    412. 

  412. ...
    413. 

  413.  . top . include (example.i:6)
    414. 

  414.  . top . include . module (example.i:2)
    415. 

  415.  . top . include . insert (example.i:6)
    416. 

  416.  . top . include . include (example.i:9)
    417. 

  417.  . top . include . include . class (example.h:3)
    418. 

  418.  . top . include . include . class . access (example.h:4)
    419. 

  419.  . top . include . include . class . constructor (example.h:7)
    420. 

  420.  . top . include . include . class . destructor (example.h:10)
    421. 

  421.  . top . include . include . class . cdecl (example.h:11)
    422. 

  422.  . top . include . include . class . cdecl (example.h:11)
    423. 

  423.  . top . include . include . class . cdecl (example.h:12)
    424. 

  424.  . top . include . include . class . cdecl (example.h:13)
    425. 

  425.  . top . include . include . class . cdecl (example.h:14)
    426. 

  426.  . top . include . include . class . cdecl (example.h:15)
    427. 

  427.  . top . include . include . class (example.h:18)
    428. 

  428.  . top . include . include . class . access (example.h:19)
    429. 

  429.  . top . include . include . class . cdecl (example.h:20)
    430. 

  430.  . top . include . include . class . access (example.h:21)
    431. 

  431.  . top . include . include . class . constructor (example.h:22)
    432. 

  432.  . top . include . include . class . cdecl (example.h:23)
    433. 

  433.  . top . include . include . class . cdecl (example.h:24)
    434. 

  434.  . top . include . include . class (example.h:27)
    435. 

  435.  . top . include . include . class . access (example.h:28)
    436. 

  436.  . top . include . include . class . cdecl (example.h:29)
    437. 

  437.  . top . include . include . class . access (example.h:30)
    438. 

  438.  . top . include . include . class . constructor (example.h:31)
    439. 

  439.  . top . include . include . class . cdecl (example.h:32)
    440. 

  440.  . top . include . include . class . cdecl (example.h:33)
    441. 

  441. </pre>
    442. 

  442. </div>
    443. 

  443. 

  444. <p>
    445. 

  445. Even for the most simple interface, the parse tree structure is larger than you might expect.  For example, in the
    446. 

  446. above output, a substantial number of nodes are actually generated by the <tt>python.swg</tt> configuration file
    447. 

  447. which defines typemaps and other directives.   The contents of the user-supplied input file don't appear until the end
    448. 

  448. of the output.
    449. 

  449. </p>
    450. 

  450. 

  451. <p>
    452. 

  452. The contents of each parse tree node consist of a collection of attribute/value
    453. 

  453. pairs.  Internally, the nodes are simply represented by hash tables.  A display of
    454. 

  454. the entire parse-tree structure can be obtained using <tt>swig -debug-top &lt;n&gt;</tt>, where <tt>n</tt> is
    455. 

  455. the stage being processed. 
    456. 

  456. There are a number of other parse tree display options, for example, <tt>swig -debug-module &lt;n&gt;</tt> will
    457. 

  457. avoid displaying system parse information and only display the parse tree pertaining to the user's module at
    458. 

  458. stage <tt>n</tt> of processing.
    459. 

  459. </p>
    460. 

  460. 

  461. <div class="shell">
    462. 

  462. <pre>
    463. 

  463. $ swig -c++ -python -debug-module 4 example.i
    464. 

  464.       +++ include ----------------------------------------
    465. 

  465.       | name         - "example.i"
    466. 

  466. 

  467.             +++ module ----------------------------------------
    468. 

  468.             | name         - "example"
    469. 

  469.             |
    470. 

  470.             +++ insert ----------------------------------------
    471. 

  471.             | code         - "\n#include \"example.h\"\n"
    472. 

  472.             |
    473. 

  473.             +++ include ----------------------------------------
    474. 

  474.             | name         - "example.h"
    475. 

  475. 

  476.                   +++ class ----------------------------------------
    477. 

  477.                   | abstract     - "1"
    478. 

  478.                   | sym:name     - "Shape"
    479. 

  479.                   | name         - "Shape"
    480. 

  480.                   | kind         - "class"
    481. 

  481.                   | symtab       - 0x40194140
    482. 

  482.                   | sym:symtab   - 0x40191078
    483. 

  483. 

  484.                         +++ access ----------------------------------------
    485. 

  485.                         | kind         - "public"
    486. 

  486.                         |
    487. 

  487.                         +++ constructor ----------------------------------------
    488. 

  488.                         | sym:name     - "Shape"
    489. 

  489.                         | name         - "Shape"
    490. 

  490.                         | decl         - "f()."
    491. 

  491.                         | code         - "{\n    nshapes++;\n  }"
    492. 

  492.                         | sym:symtab   - 0x40194140
    493. 

  493.                         |
    494. 

  494.                         +++ destructor ----------------------------------------
    495. 

  495.                         | sym:name     - "~Shape"
    496. 

  496.                         | name         - "~Shape"
    497. 

  497.                         | storage      - "virtual"
    498. 

  498.                         | code         - "{\n    nshapes--;\n  }"
    499. 

  499.                         | sym:symtab   - 0x40194140
    500. 

  500.                         |
    501. 

  501.                         +++ cdecl ----------------------------------------
    502. 

  502.                         | sym:name     - "x"
    503. 

  503.                         | name         - "x"
    504. 

  504.                         | decl         - ""
    505. 

  505.                         | type         - "double"
    506. 

  506.                         | sym:symtab   - 0x40194140
    507. 

  507.                         |
    508. 

  508.                         +++ cdecl ----------------------------------------
    509. 

  509.                         | sym:name     - "y"
    510. 

  510.                         | name         - "y"
    511. 

  511.                         | decl         - ""
    512. 

  512.                         | type         - "double"
    513. 

  513.                         | sym:symtab   - 0x40194140
    514. 

  514.                         |
    515. 

  515.                         +++ cdecl ----------------------------------------
    516. 

  516.                         | sym:name     - "move"
    517. 

  517.                         | name         - "move"
    518. 

  518.                         | decl         - "f(double,double)."
    519. 

  519.                         | parms        - double ,double
    520. 

  520.                         | type         - "void"
    521. 

  521.                         | sym:symtab   - 0x40194140
    522. 

  522.                         |
    523. 

  523.                         +++ cdecl ----------------------------------------
    524. 

  524.                         | sym:name     - "area"
    525. 

  525.                         | name         - "area"
    526. 

  526.                         | decl         - "f(void)."
    527. 

  527.                         | parms        - void
    528. 

  528.                         | storage      - "virtual"
    529. 

  529.                         | value        - "0"
    530. 

  530.                         | type         - "double"
    531. 

  531.                         | sym:symtab   - 0x40194140
    532. 

  532.                         |
    533. 

  533.                         +++ cdecl ----------------------------------------
    534. 

  534.                         | sym:name     - "perimeter"
    535. 

  535.                         | name         - "perimeter"
    536. 

  536.                         | decl         - "f(void)."
    537. 

  537.                         | parms        - void
    538. 

  538.                         | storage      - "virtual"
    539. 

  539.                         | value        - "0"
    540. 

  540.                         | type         - "double"
    541. 

  541.                         | sym:symtab   - 0x40194140
    542. 

  542.                         |
    543. 

  543.                         +++ cdecl ----------------------------------------
    544. 

  544.                         | sym:name     - "nshapes"
    545. 

  545.                         | name         - "nshapes"
    546. 

  546.                         | decl         - ""
    547. 

  547.                         | storage      - "static"
    548. 

  548.                         | type         - "int"
    549. 

  549.                         | sym:symtab   - 0x40194140
    550. 

  550.                         |
    551. 

  551.                   +++ class ----------------------------------------
    552. 

  552.                   | sym:name     - "Circle"
    553. 

  553.                   | name         - "Circle"
    554. 

  554.                   | kind         - "class"
    555. 

  555.                   | bases        - 0x40194510
    556. 

  556.                   | symtab       - 0x40194538
    557. 

  557.                   | sym:symtab   - 0x40191078
    558. 

  558. 

  559.                         +++ access ----------------------------------------
    560. 

  560.                         | kind         - "private"
    561. 

  561.                         |
    562. 

  562.                         +++ cdecl ----------------------------------------
    563. 

  563.                         | name         - "radius"
    564. 

  564.                         | decl         - ""
    565. 

  565.                         | type         - "double"
    566. 

  566.                         |
    567. 

  567.                         +++ access ----------------------------------------
    568. 

  568.                         | kind         - "public"
    569. 

  569.                         |
    570. 

  570.                         +++ constructor ----------------------------------------
    571. 

  571.                         | sym:name     - "Circle"
    572. 

  572.                         | name         - "Circle"
    573. 

  573.                         | parms        - double
    574. 

  574.                         | decl         - "f(double)."
    575. 

  575.                         | code         - "{ }"
    576. 

  576.                         | sym:symtab   - 0x40194538
    577. 

  577.                         |
    578. 

  578.                         +++ cdecl ----------------------------------------
    579. 

  579.                         | sym:name     - "area"
    580. 

  580.                         | name         - "area"
    581. 

  581.                         | decl         - "f(void)."
    582. 

  582.                         | parms        - void
    583. 

  583.                         | storage      - "virtual"
    584. 

  584.                         | type         - "double"
    585. 

  585.                         | sym:symtab   - 0x40194538
    586. 

  586.                         |
    587. 

  587.                         +++ cdecl ----------------------------------------
    588. 

  588.                         | sym:name     - "perimeter"
    589. 

  589.                         | name         - "perimeter"
    590. 

  590.                         | decl         - "f(void)."
    591. 

  591.                         | parms        - void
    592. 

  592.                         | storage      - "virtual"
    593. 

  593.                         | type         - "double"
    594. 

  594.                         | sym:symtab   - 0x40194538
    595. 

  595.                         |
    596. 

  596.                   +++ class ----------------------------------------
    597. 

  597.                   | sym:name     - "Square"
    598. 

  598.                   | name         - "Square"
    599. 

  599.                   | kind         - "class"
    600. 

  600.                   | bases        - 0x40194760
    601. 

  601.                   | symtab       - 0x40194788
    602. 

  602.                   | sym:symtab   - 0x40191078
    603. 

  603. 

  604.                         +++ access ----------------------------------------
    605. 

  605.                         | kind         - "private"
    606. 

  606.                         |
    607. 

  607.                         +++ cdecl ----------------------------------------
    608. 

  608.                         | name         - "width"
    609. 

  609.                         | decl         - ""
    610. 

  610.                         | type         - "double"
    611. 

  611.                         |
    612. 

  612.                         +++ access ----------------------------------------
    613. 

  613.                         | kind         - "public"
    614. 

  614.                         |
    615. 

  615.                         +++ constructor ----------------------------------------
    616. 

  616.                         | sym:name     - "Square"
    617. 

  617.                         | name         - "Square"
    618. 

  618.                         | parms        - double
    619. 

  619.                         | decl         - "f(double)."
    620. 

  620.                         | code         - "{ }"
    621. 

  621.                         | sym:symtab   - 0x40194788
    622. 

  622.                         |
    623. 

  623.                         +++ cdecl ----------------------------------------
    624. 

  624.                         | sym:name     - "area"
    625. 

  625.                         | name         - "area"
    626. 

  626.                         | decl         - "f(void)."
    627. 

  627.                         | parms        - void
    628. 

  628.                         | storage      - "virtual"
    629. 

  629.                         | type         - "double"
    630. 

  630.                         | sym:symtab   - 0x40194788
    631. 

  631.                         |
    632. 

  632.                         +++ cdecl ----------------------------------------
    633. 

  633.                         | sym:name     - "perimeter"
    634. 

  634.                         | name         - "perimeter"
    635. 

  635.                         | decl         - "f(void)."
    636. 

  636.                         | parms        - void
    637. 

  637.                         | storage      - "virtual"
    638. 

  638.                         | type         - "double"
    639. 

  639.                         | sym:symtab   - 0x40194788
    640. 

  640. </pre>
    641. 

  641. </div>
    642. 

  642. 

  643. <H3><a name="Extending_nn9"></a>35.4.4 Attribute namespaces</H3>
    644. 

  644. 

  645. 

  646. <p>
    647. 

  647. Attributes of parse tree nodes are often prepended with a namespace qualifier.
    648. 

  648. For example, the attributes
    649. 

  649. <tt>sym:name</tt> and <tt>sym:symtab</tt> are attributes related to
    650. 

  650. symbol table management and are prefixed with <tt>sym:</tt>.  As a
    651. 

  651. general rule, only those attributes which are directly related to the raw declaration
    652. 

  652. appear without a prefix (type, name, declarator, etc.).
    653. 

  653. </p>
    654. 

  654. 

  655. <p>
    656. 

  656. Target language modules may add additional attributes to nodes to assist the generation
    657. 

  657. of wrapper code.  The convention for doing this is to place these attributes in a namespace
    658. 

  658. that matches the name of the target language.  For example, <tt>python:foo</tt> or
    659. 

  659. <tt>perl:foo</tt>.
    660. 

  660. </p>
    661. 

  661. 

  662. <H3><a name="Extending_nn10"></a>35.4.5 Symbol Tables</H3>
    663. 

  663. 

  664. 

  665. <p>
    666. 

  666. During parsing, all symbols are managed in the space of the target
    667. 

  667. language.  The <tt>sym:name</tt> attribute of each node contains the symbol name
    668. 

  668. selected by the parser.  Normally, <tt>sym:name</tt> and <tt>name</tt>
    669. 

  669. are the same.  However, the <tt>%rename</tt> directive can be used to
    670. 

  670. change the value of <tt>sym:name</tt>.  You can see the effect of
    671. 

  671. <tt>%rename</tt> by trying it on a simple interface and dumping the
    672. 

  672. parse tree.  For example:
    673. 

  673. </p>
    674. 

  674. 

  675. <div class="code">
    676. 

  676. <pre>
    677. 

  677. %rename(foo_i) foo(int);
    678. 

  678. %rename(foo_d) foo(double);
    679. 

  679. 

  680. void foo(int);
    681. 

  681. void foo(double);
    682. 

  682. void foo(Bar *b);
    683. 

  683. </pre>
    684. 

  684. </div>
    685. 

  685. 

  686. <p>
    687. 

  687. There are various <tt>debug-</tt> options that can be useful for debugging and analysing the parse tree.
    688. 

  688. For example, the <tt>debug-top &lt;n&gt;</tt> or <tt>debug-module &lt;n&gt;</tt> options will
    689. 

  689. dump the entire/top of the parse tree or the module subtree at one of the four <tt>n</tt> stages of processing.
    690. 

  690. The parse tree can be viewed after the final stage of processing by running SWIG:
    691. 

  691. </p>
    692. 

  692. 

  693. <div class="shell">
    694. 

  694. <pre>
    695. 

  695. $ swig -debug-top 4 example.i
    696. 

  696. ...
    697. 

  697.             +++ cdecl ----------------------------------------
    698. 

  698.             | sym:name     - "foo_i"
    699. 

  699.             | name         - "foo"
    700. 

  700.             | decl         - "f(int)."
    701. 

  701.             | parms        - int
    702. 

  702.             | type         - "void"
    703. 

  703.             | sym:symtab   - 0x40165078
    704. 

  704.             |
    705. 

  705.             +++ cdecl ----------------------------------------
    706. 

  706.             | sym:name     - "foo_d"
    707. 

  707.             | name         - "foo"
    708. 

  708.             | decl         - "f(double)."
    709. 

  709.             | parms        - double
    710. 

  710.             | type         - "void"
    711. 

  711.             | sym:symtab   - 0x40165078
    712. 

  712.             |
    713. 

  713.             +++ cdecl ----------------------------------------
    714. 

  714.             | sym:name     - "foo"
    715. 

  715.             | name         - "foo"
    716. 

  716.             | decl         - "f(p.Bar)."
    717. 

  717.             | parms        - Bar *
    718. 

  718.             | type         - "void"
    719. 

  719.             | sym:symtab   - 0x40165078
    720. 

  720. </pre>
    721. 

  721. </div>
    722. 

  722. 

  723. <p>
    724. 

  724. All symbol-related conflicts and complaints about overloading are based on <tt>sym:name</tt> values.
    725. 

  725. For instance, the following example uses <tt>%rename</tt> in reverse to generate a name clash.
    726. 

  726. </p>
    727. 

  727. 

  728. <div class="code">
    729. 

  729. <pre>
    730. 

  730. %rename(foo) foo_i(int);
    731. 

  731. %rename(foo) foo_d(double;
    732. 

  732. 

  733. void foo_i(int);
    734. 

  734. void foo_d(double);
    735. 

  735. void foo(Bar *b);
    736. 

  736. </pre>
    737. 

  737. </div>
    738. 

  738. 

  739. <p>
    740. 

  740. When you run SWIG on this you now get:
    741. 

  741. </p>
    742. 

  742. 

  743. <div class="shell">
    744. 

  744. <pre>
    745. 

  745. $ ./swig example.i
    746. 

  746. example.i:6. Overloaded declaration ignored.  foo_d(double )
    747. 

  747. example.i:5. Previous declaration is foo_i(int )
    748. 

  748. example.i:7. Overloaded declaration ignored.  foo(Bar *)
    749. 

  749. example.i:5. Previous declaration is foo_i(int )
    750. 

  750. </pre>
    751. 

  751. </div>
    752. 

  752. 

  753. <H3><a name="Extending_nn11"></a>35.4.6 The %feature directive</H3>
    754. 

  754. 

  755. 

  756. <p>
    757. 

  757. A number of SWIG directives such as <tt>%exception</tt> are implemented using the
    758. 

  758. low-level <tt>%feature</tt> directive.  For example:
    759. 

  759. </p>
    760. 

  760. 

  761. <div class="code">
    762. 

  762. <pre>
    763. 

  763. %feature("except") getitem(int) {
    764. 

  764.   try {
    765. 

  765.      $action
    766. 

  766.   } catch (badindex) {
    767. 

  767.      ...
    768. 

  768.   }
    769. 

  769. }
    770. 

  770. 

  771. ...
    772. 

  772. class Foo {
    773. 

  773. public:
    774. 

  774.     Object *getitem(int index) throws(badindex);
    775. 

  775.     ...
    776. 

  776. };
    777. 

  777. </pre>
    778. 

  778. </div>
    779. 

  779. 

  780. <p>
    781. 

  781. The behavior of <tt>%feature</tt> is very easy to describe--it simply
    782. 

  782. attaches a new attribute to any parse tree node that matches the
    783. 

  783. given prototype.   When a feature is added, it shows up as an attribute in the <tt>feature:</tt> namespace.
    784. 

  784. You can see this when running with the <tt>-debug-top 4</tt> option.   For example:
    785. 

  785. </p>
    786. 

  786. 

  787. <div class="shell">
    788. 

  788. <pre>
    789. 

  789.  +++ cdecl ----------------------------------------
    790. 

  790.  | sym:name     - "getitem"
    791. 

  791.  | name         - "getitem"
    792. 

  792.  | decl         - "f(int).p."
    793. 

  793.  | parms        - int
    794. 

  794.  | type         - "Object"
    795. 

  795.  | feature:except - "{\n    try {\n       $action\n    } catc..."
    796. 

  796.  | sym:symtab   - 0x40168ac8
    797. 

  797.  |
    798. 

  798. </pre>
    799. 

  799. </div>
    800. 

  800. 

  801. <p>
    802. 

  802. Feature names are completely arbitrary and a target language module can be
    803. 

  803. programmed to respond to any feature name that it wants to recognize.  The 
    804. 

  804. data stored in a feature attribute is usually just a raw unparsed string.   
    805. 

  805. For example, the exception code above is simply
    806. 

  806. stored without any modifications.
    807. 

  807. </p>
    808. 

  808. 

  809. <H3><a name="Extending_nn12"></a>35.4.7 Code Generation</H3>
    810. 

  810. 

  811. 

  812. <p>
    813. 

  813. Language modules work by defining handler functions that know how to respond to
    814. 

  814. different types of parse-tree nodes.  These handlers simply look at the
    815. 

  815. attributes of each node in order to produce low-level code.
    816. 

  816. </p>
    817. 

  817. 

  818. <p>
    819. 

  819. In reality, the generation of code is somewhat more subtle than simply
    820. 

  820. invoking handler functions.  This is because parse-tree nodes might be
    821. 

  821. transformed. For example, suppose you are wrapping a class like this:
    822. 

  822. </p>
    823. 

  823. 

  824. <div class="code">
    825. 

  825. <pre>
    826. 

  826. class Foo {
    827. 

  827. public:
    828. 

  828.     virtual int *bar(int x);
    829. 

  829. };
    830. 

  830. </pre>
    831. 

  831. </div>
    832. 

  832. 

  833. <p>
    834. 

  834. When the parser constructs a node for the member <tt>bar</tt>, it creates a raw "cdecl" node with the following
    835. 

  835. attributes:
    836. 

  836. </p>
    837. 

  837. 

  838. <div class="diagram">
    839. 

  839. <pre>
    840. 

  840. nodeType    : cdecl
    841. 

  841. name        : bar
    842. 

  842. type        : int
    843. 

  843. decl        : f(int).p
    844. 

  844. parms       : int x
    845. 

  845. storage     : virtual
    846. 

  846. sym:name    : bar
    847. 

  847. </pre>
    848. 

  848. </div>
    849. 

  849. 

  850. <p>
    851. 

  851. To produce wrapper code, this "cdecl" node undergoes a number of transformations.  First, the node is recognized as a function declaration.   This adjusts some of the type information--specifically, the declarator is joined with the base datatype to produce this:
    852. 

  852. </p>
    853. 

  853. 

  854. <div class="diagram">
    855. 

  855. <pre>
    856. 

  856. nodeType    : cdecl
    857. 

  857. name        : bar
    858. 

  858. type        : p.int        &lt;-- Notice change in return type
    859. 

  859. decl        : f(int).p
    860. 

  860. parms       : int x
    861. 

  861. storage     : virtual
    862. 

  862. sym:name    : bar
    863. 

  863. </pre>
    864. 

  864. </div>
    865. 

  865. 

  866. <p>
    867. 

  867. Next, the context of the node indicates that the node is really a
    868. 

  868. member function.  This produces a transformation to a low-level
    869. 

  869. accessor function like this:
    870. 

  870. </p>
    871. 

  871. 

  872. <div class="diagram">
    873. 

  873. <pre>
    874. 

  874. nodeType    : cdecl
    875. 

  875. name        : bar
    876. 

  876. type        : int.p
    877. 

  877. decl        : f(int).p
    878. 

  878. parms       : Foo *self, int x            &lt;-- Added parameter
    879. 

  879. storage     : virtual
    880. 

  880. wrap:action : result = (arg1)-&gt;bar(arg2)  &lt;-- Action code added
    881. 

  881. sym:name    : Foo_bar                     &lt;-- Symbol name changed
    882. 

  882. </pre>
    883. 

  883. </div>
    884. 

  884. 

  885. <p>
    886. 

  886. In this transformation, notice how an additional parameter was added
    887. 

  887. to the parameter list and how the symbol name of the node has suddenly
    888. 

  888. changed into an accessor using the naming scheme described in the
    889. 

  889. "SWIG Basics" chapter.  A small fragment of "action" code has also
    890. 

  890. been generated--notice how the <tt>wrap:action</tt> attribute defines
    891. 

  891. the access to the underlying method.  The data in this transformed
    892. 

  892. node is then used to generate a wrapper.
    893. 

  893. </p>
    894. 

  894. 

  895. <p>
    896. 

  896. Language modules work by registering handler functions for dealing with
    897. 

  897. various types of nodes at different stages of transformation.   This is done by
    898. 

  898. inheriting from a special <tt>Language</tt> class and defining a collection
    899. 

  899. of virtual methods.   For example, the Python module defines a class as
    900. 

  900. follows:
    901. 

  901. </p>
    902. 

  902. 

  903. <div class="code">
    904. 

  904. <pre>
    905. 

  905. class PYTHON : public Language {
    906. 

  906. protected:
    907. 

  907. public :
    908. 

  908.   virtual void main(int, char *argv[]);
    909. 

  909.   virtual int  top(Node *);
    910. 

  910.   virtual int  functionWrapper(Node *);
    911. 

  911.   virtual int  constantWrapper(Node *);
    912. 

  912.   virtual int  variableWrapper(Node *);
    913. 

  913.   virtual int  nativeWrapper(Node *);
    914. 

  914.   virtual int  membervariableHandler(Node *);
    915. 

  915.   virtual int  memberconstantHandler(Node *);
    916. 

  916.   virtual int  memberfunctionHandler(Node *);
    917. 

  917.   virtual int  constructorHandler(Node *);
    918. 

  918.   virtual int  destructorHandler(Node *);
    919. 

  919.   virtual int  classHandler(Node *);
    920. 

  920.   virtual int  classforwardDeclaration(Node *);
    921. 

  921.   virtual int  insertDirective(Node *);
    922. 

  922.   virtual int  importDirective(Node *);
    923. 

  923. };
    924. 

  924. </pre>
    925. 

  925. </div>
    926. 

  926. 

  927. <p>
    928. 

  928. The role of these functions is described shortly.
    929. 

  929. </p>
    930. 

  930. 

  931. <H3><a name="Extending_nn13"></a>35.4.8 SWIG and XML</H3>
    932. 

  932. 

  933. 

  934. <p>
    935. 

  935. Much of SWIG's current parser design was originally motivated by
    936. 

  936. interest in using XML to represent SWIG parse trees.  Although XML is
    937. 

  937. not currently used in any direct manner, the parse tree structure, use
    938. 

  938. of node tags, attributes, and attribute namespaces are all influenced
    939. 

  939. by aspects of XML parsing.  Therefore, in trying to understand SWIG's
    940. 

  940. internal data structures, it may be useful to keep XML in the back of
    941. 

  941. your mind as a model.
    942. 

  942. </p>
    943. 

  943. 

  944. <H2><a name="Extending_nn14"></a>35.5 Primitive Data Structures</H2>
    945. 

  945. 

  946. 

  947. <p>
    948. 

  948. Most of SWIG is constructed using three basic data structures:
    949. 

  949. strings, hashes, and lists.  These data structures are dynamic in same way as
    950. 

  950. similar structures found in many scripting languages.  For instance,
    951. 

  951. you can have containers (lists and hash tables) of mixed types and
    952. 

  952. certain operations are polymorphic.
    953. 

  953. </p>
    954. 

  954. 

  955. <p>
    956. 

  956. This section briefly describes the basic structures so that later
    957. 

  957. sections of this chapter make more sense.
    958. 

  958. </p>
    959. 

  959. 

  960. <p>
    961. 

  961. When describing the low-level API, the following type name conventions are
    962. 

  962. used:
    963. 

  963. </p>
    964. 

  964. 

  965. <ul>
    966. 

  966. <li><tt>String</tt>.  A string object.
    967. 

  967. <li><tt>Hash</tt>. A hash object.
    968. 

  968. <li><tt>List</tt>. A list object.
    969. 

  969. <li><tt>String_or_char</tt>. A string object or a <tt>char *</tt>.
    970. 

  970. <li><tt>Object_or_char</tt>. An object or a <tt>char *</tt>.
    971. 

  971. <li><tt>Object</tt>.  Any object (string, hash, list, etc.)
    972. 

  972. </ul>
    973. 

  973. 

  974. <p>
    975. 

  975. In most cases, other typenames in the source are aliases for one of these
    976. 

  976. primitive types.   Specifically:
    977. 

  977. </p>
    978. 

  978. 

  979. <div class="code">
    980. 

  980. <pre>
    981. 

  981. typedef String SwigType;
    982. 

  982. typedef Hash   Parm;
    983. 

  983. typedef Hash   ParmList;
    984. 

  984. typedef Hash   Node;
    985. 

  985. typedef Hash   Symtab;
    986. 

  986. typedef Hash   Typetab;
    987. 

  987. </pre>
    988. 

  988. </div>
    989. 

  989. 

  990. <H3><a name="Extending_nn15"></a>35.5.1 Strings</H3>
    991. 

  991. 

  992. 

  993. <p>
    994. 

  994. <b><tt>String *NewString(const String_or_char *val)</tt></b>
    995. 

  995. </p>
    996. 

  996. 

  997. <div class="indent">
    998. 

  998. Creates a new string with initial value <tt>val</tt>. <tt>val</tt> may
    999. 

  999. be a <tt>char *</tt> or another <tt>String</tt> object.   If you want
    1000. 

  1000. to create an empty string, use "" for val.
    1001. 

  1001. </div>
    1002. 

  1002. 

  1003. <p>
    1004. 

  1004. <b><tt>String *NewStringf(const char *fmt, ...)</tt></b>
    1005. 

  1005. </p>
    1006. 

  1006. 

  1007. <div class="indent">
    1008. 

  1008. Creates a new string whose initial value is set according to a C <tt>printf</tt> style
    1009. 

  1009. format string in <tt>fmt</tt>.   Additional arguments follow depending
    1010. 

  1010. on <tt>fmt</tt>.
    1011. 

  1011. </div>
    1012. 

  1012. 

  1013. <p>
    1014. 

  1014. <b><tt>String *Copy(String *s)</tt></b>
    1015. 

  1015. </p>
    1016. 

  1016. 

  1017. <div class="indent">
    1018. 

  1018. Make a copy of the string <tt>s</tt>.
    1019. 

  1019. </div>
    1020. 

  1020. 

  1021. <p>
    1022. 

  1022. <b><tt>void Delete(String *s)</tt></b>
    1023. 

  1023. </p>
    1024. 

  1024. 

  1025. <div class="indent">
    1026. 

  1026. Deletes <tt>s</tt>.
    1027. 

  1027. </div>
    1028. 

  1028. 

  1029. <p>
    1030. 

  1030. <b><tt>int Len(const String_or_char *s)</tt></b>
    1031. 

  1031. </p>
    1032. 

  1032. 

  1033. <div class="indent">
    1034. 

  1034. Returns the length of the string.
    1035. 

  1035. </div>
    1036. 

  1036. 

  1037. <p>
    1038. 

  1038. <b><tt>char *Char(const String_or_char *s)</tt></b>
    1039. 

  1039. </p>
    1040. 

  1040. 

  1041. <div class="indent">
    1042. 

  1042. Returns a pointer to the first character in a string.
    1043. 

  1043. </div>
    1044. 

  1044. 

  1045. <p>
    1046. 

  1046. <b><tt>void Append(String *s, const String_or_char *t)</tt></b>
    1047. 

  1047. </p>
    1048. 

  1048. 

  1049. <div class="indent">
    1050. 

  1050. Appends <tt>t</tt> to the end of string <tt>s</tt>.
    1051. 

  1051. </div>
    1052. 

  1052. 

  1053. <p>
    1054. 

  1054. <b><tt>void Insert(String *s, int pos, const String_or_char *t)</tt></b>
    1055. 

  1055. </p>
    1056. 

  1056. 

  1057. <div class="indent">
    1058. 

  1058. Inserts <tt>t</tt> into <tt>s</tt> at position <tt>pos</tt>.  The contents
    1059. 

  1059. of <tt>s</tt> are shifted accordingly.    The special value <tt>DOH_END</tt>
    1060. 

  1060. can be used for <tt>pos</tt> to indicate insertion at the end of the string (appending).
    1061. 

  1061. </div>
    1062. 

  1062. 

  1063. <p>
    1064. 

  1064. <b><tt>int Strcmp(const String_or_char *s, const String_or_char *t)</tt></b>
    1065. 

  1065. </p>
    1066. 

  1066. 

  1067. <div class="indent">
    1068. 

  1068. Compare strings <tt>s</tt> and <tt>t</tt>.   Same as the C <tt>strcmp()</tt>
    1069. 

  1069. function.
    1070. 

  1070. </div>
    1071. 

  1071. 

  1072. <p>
    1073. 

  1073. <b><tt>int Strncmp(const String_or_char *s, const String_or_char *t, int len)</tt></b>
    1074. 

  1074. </p>
    1075. 

  1075. 

  1076. <div class="indent">
    1077. 

  1077. Compare the first <tt>len</tt> characters of strings <tt>s</tt> and <tt>t</tt>.   Same as the C <tt>strncmp()</tt>
    1078. 

  1078. function.
    1079. 

  1079. </div>
    1080. 

  1080. 

  1081. <p>
    1082. 

  1082. <b><tt>char *Strstr(const String_or_char *s, const String_or_char *pat)</tt></b>
    1083. 

  1083. </p>
    1084. 

  1084. 

  1085. <div class="indent">
    1086. 

  1086. Returns a pointer to the first occurrence of <tt>pat</tt> in <tt>s</tt>.
    1087. 

  1087. Same as the C <tt>strstr()</tt> function.
    1088. 

  1088. </div>
    1089. 

  1089. 

  1090. <p>
    1091. 

  1091. <b><tt>char *Strchr(const String_or_char *s, char ch)</tt></b>
    1092. 

  1092. </p>
    1093. 

  1093. 

  1094. <div class="indent">
    1095. 

  1095. Returns a pointer to the first occurrence of character <tt>ch</tt> in <tt>s</tt>.
    1096. 

  1096. Same as the C <tt>strchr()</tt> function.
    1097. 

  1097. </div>
    1098. 

  1098. 

  1099. <p>
    1100. 

  1100. <b><tt>void Chop(String *s)</tt></b>
    1101. 

  1101. </p>
    1102. 

  1102. 

  1103. <div class="indent">
    1104. 

  1104. Chops trailing whitespace off the end of <tt>s</tt>.
    1105. 

  1105. </div>
    1106. 

  1106. 

  1107. <p>
    1108. 

  1108. <b><tt>int Replace(String *s, const String_or_char *pat, const String_or_char *rep, int flags)</tt></b>
    1109. 

  1109. </p>
    1110. 

  1110. 

  1111. <div class="indent">
    1112. 

  1112. <p>
    1113. 

  1113. Replaces the pattern <tt>pat</tt> with <tt>rep</tt> in string <tt>s</tt>.
    1114. 

  1114. <tt>flags</tt> is a combination of the following flags:</p>
    1115. 

  1115. 

  1116. <div class="code">
    1117. 

  1117. <pre>
    1118. 

  1118. DOH_REPLACE_ANY       - Replace all occurrences
    1119. 

  1119. DOH_REPLACE_ID        - Valid C identifiers only
    1120. 

  1120. DOH_REPLACE_NOQUOTE   - Don't replace in quoted strings
    1121. 

  1121. DOH_REPLACE_FIRST     - Replace first occurrence only.
    1122. 

  1122. </pre>
    1123. 

  1123. </div>
    1124. 

  1124. 

  1125. <p>
    1126. 

  1126. Returns the number of replacements made (if any).
    1127. 

  1127. </p>
    1128. 

  1128. 

  1129. </div>
    1130. 

  1130. 

  1131. <H3><a name="Extending_nn16"></a>35.5.2 Hashes</H3>
    1132. 

  1132. 

  1133. 

  1134. <p>
    1135. 

  1135. <b><tt>Hash *NewHash()</tt></b>
    1136. 

  1136. </p>
    1137. 

  1137. 

  1138. <div class="indent">
    1139. 

  1139. Creates a new empty hash table.
    1140. 

  1140. </div>
    1141. 

  1141. 

  1142. <p>
    1143. 

  1143. <b><tt>Hash *Copy(Hash *h)</tt></b>
    1144. 

  1144. </p>
    1145. 

  1145. 

  1146. <div class="indent">
    1147. 

  1147. Make a shallow copy of the hash <tt>h</tt>.
    1148. 

  1148. </div>
    1149. 

  1149. 

  1150. <p>
    1151. 

  1151. <b><tt>void Delete(Hash *h)</tt></b>
    1152. 

  1152. </p>
    1153. 

  1153. 

  1154. <div class="indent">
    1155. 

  1155. Deletes <tt>h</tt>.
    1156. 

  1156. </div>
    1157. 

  1157. 

  1158. <p>
    1159. 

  1159. <b><tt>int Len(Hash *h)</tt></b>
    1160. 

  1160. </p>
    1161. 

  1161. 

  1162. <div class="indent">
    1163. 

  1163. Returns the number of items in <tt>h</tt>.
    1164. 

  1164. </div>
    1165. 

  1165. 

  1166. <p>
    1167. 

  1167. <b><tt>Object *Getattr(Hash *h, const String_or_char *key)</tt></b>
    1168. 

  1168. </p>
    1169. 

  1169. 

  1170. <div class="indent">
    1171. 

  1171. Gets an object from <tt>h</tt>.  <tt>key</tt> may be a string or
    1172. 

  1172. a simple <tt>char *</tt> string.   Returns NULL if not found.
    1173. 

  1173. </div>
    1174. 

  1174. 

  1175. <p>
    1176. 

  1176. <b><tt>int Setattr(Hash *h, const String_or_char *key, const Object_or_char *val)</tt></b>
    1177. 

  1177. </p>
    1178. 

  1178. 

  1179. <div class="indent">
    1180. 

  1180. Stores <tt>val</tt> in <tt>h</tt>. <tt>key</tt> may be a string or
    1181. 

  1181. a simple <tt>char *</tt>. If <tt>val</tt> is not a standard
    1182. 

  1182. object (String, Hash, or List) it is assumed to be a <tt>char *</tt> in which
    1183. 

  1183. case it is used to construct a <tt>String</tt> that is stored in the hash.
    1184. 

  1184. If <tt>val</tt> is NULL, the object is deleted. Increases the reference count
    1185. 

  1185. of <tt>val</tt>.   Returns 1 if this operation replaced an existing hash entry,
    1186. 

  1186. 0 otherwise.
    1187. 

  1187. </div>
    1188. 

  1188. 

  1189. <p>
    1190. 

  1190. <b><tt>int Delattr(Hash *h, const String_or_char *key)</tt></b>
    1191. 

  1191. </p>
    1192. 

  1192. 

  1193. <div class="indent">
    1194. 

  1194. Deletes the hash item referenced by <tt>key</tt>.  Decreases the
    1195. 

  1195. reference count on the corresponding object (if any).  Returns 1
    1196. 

  1196. if an object was removed, 0 otherwise.
    1197. 

  1197. </div>
    1198. 

  1198. 

  1199. <p>
    1200. 

  1200. <b><tt>List *Keys(Hash *h)</tt></b>
    1201. 

  1201. </p>
    1202. 

  1202. 

  1203. <div class="indent">
    1204. 

  1204. Returns the list of hash table keys.
    1205. 

  1205. </div>
    1206. 

  1206. 

  1207. 

  1208. <H3><a name="Extending_nn17"></a>35.5.3 Lists</H3>
    1209. 

  1209. 

  1210. 

  1211. <p>
    1212. 

  1212. <b><tt>List *NewList()</tt></b>
    1213. 

  1213. </p>
    1214. 

  1214. 

  1215. <div class="indent">
    1216. 

  1216. Creates a new empty list.
    1217. 

  1217. </div>
    1218. 

  1218. 

  1219. <p>
    1220. 

  1220. <b><tt>List *Copy(List *x)</tt></b>
    1221. 

  1221. </p>
    1222. 

  1222. 

  1223. <div class="indent">
    1224. 

  1224. Make a shallow copy of the List <tt>x</tt>.
    1225. 

  1225. </div>
    1226. 

  1226. 

  1227. <p>
    1228. 

  1228. <b><tt>void Delete(List *x)</tt></b>
    1229. 

  1229. </p>
    1230. 

  1230. 

  1231. <div class="indent">
    1232. 

  1232. Deletes <tt>x</tt>.
    1233. 

  1233. </div>
    1234. 

  1234. 

  1235. <p>
    1236. 

  1236. <b><tt>int Len(List *x)</tt></b>
    1237. 

  1237. </p>
    1238. 

  1238. 

  1239. <div class="indent">
    1240. 

  1240. Returns the number of items in <tt>x</tt>.
    1241. 

  1241. </div>
    1242. 

  1242. 

  1243. <p>
    1244. 

  1244. <b><tt>Object *Getitem(List *x, int n)</tt></b>
    1245. 

  1245. </p>
    1246. 

  1246. 

  1247. <div class="indent">
    1248. 

  1248. Returns an object from <tt>x</tt> with index <tt>n</tt>.  If <tt>n</tt> is
    1249. 

  1249. beyond the end of the list, the last item is returned. If <tt>n</tt> is
    1250. 

  1250. negative, the first item is returned.
    1251. 

  1251. </div>
    1252. 

  1252. 

  1253. <p>
    1254. 

  1254. <b><tt>int *Setitem(List *x, int n, const Object_or_char *val)</tt></b>
    1255. 

  1255. </p>
    1256. 

  1256. 

  1257. <div class="indent">
    1258. 

  1258. Stores <tt>val</tt> in <tt>x</tt>.
    1259. 

  1259. If <tt>val</tt> is not a standard
    1260. 

  1260. object (String, Hash, or List) it is assumed to be a <tt>char *</tt> in which
    1261. 

  1261. case it is used to construct a <tt>String</tt> that is stored in the list.
    1262. 

  1262. <tt>n</tt> must be in range.  Otherwise, an assertion will be raised.
    1263. 

  1263. </div>
    1264. 

  1264. 

  1265. <p>
    1266. 

  1266. <b><tt>int *Delitem(List *x, int n)</tt></b>
    1267. 

  1267. </p>
    1268. 

  1268. 

  1269. <div class="indent">
    1270. 

  1270. Deletes item <tt>n</tt> from the list, shifting items down if necessary.
    1271. 

  1271. To delete the last item in the list, use the special value <tt>DOH_END</tt>
    1272. 

  1272. for <tt>n</tt>.
    1273. 

  1273. </div>
    1274. 

  1274. 

  1275. <p>
    1276. 

  1276. <b><tt>void Append(List *x, const Object_or_char *t)</tt></b>
    1277. 

  1277. </p>
    1278. 

  1278. 

  1279. <div class="indent">
    1280. 

  1280. Appends <tt>t</tt> to the end of <tt>x</tt>.  If <tt>t</tt> is not
    1281. 

  1281. a standard object, it is assumed to be a <tt>char *</tt> and is
    1282. 

  1282. used to create a String object.
    1283. 

  1283. </div>
    1284. 

  1284. 

  1285. <p>
    1286. 

  1286. <b><tt>void Insert(String *s, int pos, const Object_or_char *t)</tt></b>
    1287. 

  1287. </p>
    1288. 

  1288. 

  1289. <div class="indent">
    1290. 

  1290. Inserts <tt>t</tt> into <tt>s</tt> at position <tt>pos</tt>.  The contents
    1291. 

  1291. of <tt>s</tt> are shifted accordingly.    The special value <tt>DOH_END</tt>
    1292. 

  1292. can be used for <tt>pos</tt> to indicate insertion at the end of the list (appending).
    1293. 

  1293. If <tt>t</tt> is not a standard object, it is assumed to be a <tt>char *</tt>
    1294. 

  1294. and is used to create a String object.
    1295. 

  1295. </div>
    1296. 

  1296. 

  1297. <H3><a name="Extending_nn18"></a>35.5.4 Common operations</H3>
    1298. 

  1298. 

  1299. 

  1300. The following operations are applicable to all datatypes.
    1301. 

  1301. 

  1302. <p>
    1303. 

  1303. <b><tt>Object *Copy(Object *x)</tt></b>
    1304. 

  1304. </p>
    1305. 

  1305. 

  1306. <div class="indent">
    1307. 

  1307. Make a copy of the object <tt>x</tt>.
    1308. 

  1308. </div>
    1309. 

  1309. 

  1310. <p>
    1311. 

  1311. <b><tt>void Delete(Object *x)</tt></b>
    1312. 

  1312. </p>
    1313. 

  1313. 

  1314. <div class="indent">
    1315. 

  1315. Deletes <tt>x</tt>.
    1316. 

  1316. </div>
    1317. 

  1317. 

  1318. <p>
    1319. 

  1319. <b><tt>void Setfile(Object *x, String_or_char *f)</tt></b>
    1320. 

  1320. </p>
    1321. 

  1321. 

  1322. <div class="indent">
    1323. 

  1323. Sets the filename associated with <tt>x</tt>.  Used to track
    1324. 

  1324. objects and report errors.
    1325. 

  1325. </div>
    1326. 

  1326. 

  1327. <p>
    1328. 

  1328. <b><tt>String *Getfile(Object *x)</tt></b>
    1329. 

  1329. </p>
    1330. 

  1330. 

  1331. <div class="indent">
    1332. 

  1332. Gets the filename associated with <tt>x</tt>.
    1333. 

  1333. </div>
    1334. 

  1334. 

  1335. <p>
    1336. 

  1336. <b><tt>void Setline(Object *x, int n)</tt></b>
    1337. 

  1337. </p>
    1338. 

  1338. 

  1339. <div class="indent">
    1340. 

  1340. Sets the line number associated with <tt>x</tt>.  Used to track
    1341. 

  1341. objects and report errors.
    1342. 

  1342. </div>
    1343. 

  1343. 

  1344. <p>
    1345. 

  1345. <b><tt>int Getline(Object *x)</tt></b>
    1346. 

  1346. </p>
    1347. 

  1347. 

  1348. <div class="indent">
    1349. 

  1349. Gets the line number associated with <tt>x</tt>.
    1350. 

  1350. </div>
    1351. 

  1351. 

  1352. <H3><a name="Extending_nn19"></a>35.5.5 Iterating over Lists and Hashes</H3>
    1353. 

  1353. 

  1354. 

  1355. To iterate over the elements of a list or a hash table, the following functions are used:
    1356. 

  1356. 

  1357. <p>
    1358. 

  1358. <b><tt>Iterator First(Object *x)</tt></b>
    1359. 

  1359. </p>
    1360. 

  1360. 

  1361. <div class="indent">
    1362. 

  1362. Returns an iterator object that points to the first item in a list or hash table.  The
    1363. 

  1363. <tt>item</tt> attribute of the Iterator object is a pointer to the item.  For hash tables, the <tt>key</tt> attribute
    1364. 

  1364. of the Iterator object additionally points to the corresponding Hash table key.  The <tt>item</tt> and <tt>key</tt> attributes
    1365. 

  1365. are NULL if the object contains no items or if there are no more items.
    1366. 

  1366. </div>
    1367. 

  1367. 

  1368. <p>
    1369. 

  1369. <b><tt>Iterator Next(Iterator i)</tt></b>
    1370. 

  1370. </p>
    1371. 

  1371. 

  1372. <div class="indent">
    1373. 

  1373. <p>Returns an iterator that points to the next item in a list or hash table.
    1374. 

  1374. 

  1375. Here are two examples of iteration:</p>
    1376. 

  1376. 

  1377. <div class="code">
    1378. 

  1378. <pre>
    1379. 

  1379. List *l = (some list);
    1380. 

  1380. Iterator i;
    1381. 

  1381. 

  1382. for (i = First(l); i.item; i = Next(i)) {
    1383. 

  1383.     Printf(stdout,"%s\n", i.item);
    1384. 

  1384. }
    1385. 

  1385. 

  1386. Hash *h = (some hash);
    1387. 

  1387. Iterator j;
    1388. 

  1388. 

  1389. for (j = First(j); j.item; j= Next(j)) {
    1390. 

  1390.     Printf(stdout,"%s : %s\n", j.key, j.item);
    1391. 

  1391. }
    1392. 

  1392. </pre>
    1393. 

  1393. </div>
    1394. 

  1394. 

  1395. </div>
    1396. 

  1396. 

  1397. <H3><a name="Extending_nn20"></a>35.5.6 I/O</H3>
    1398. 

  1398. 

  1399. 

  1400. Special I/O functions are used for all internal I/O.  These operations
    1401. 

  1401. work on C <tt>FILE *</tt> objects, String objects, and special <tt>File</tt> objects
    1402. 

  1402. (which are merely a wrapper around <tt>FILE *</tt>).
    1403. 

  1403. 

  1404. <p>
    1405. 

  1405. <b><tt>int Printf(String_or_FILE *f, const char *fmt, ...)</tt></b>
    1406. 

  1406. </p>
    1407. 

  1407. 

  1408. <div class="indent">
    1409. 

  1409. Formatted I/O.   Same as the C <tt>fprintf()</tt> function except that output
    1410. 

  1410. can also be directed to a string object.  Note:  the <tt>%s</tt> format
    1411. 

  1411. specifier works with both strings and <tt>char *</tt>.  All other format
    1412. 

  1412. operators have the same meaning.
    1413. 

  1413. </div>
    1414. 

  1414. 

  1415. <p>
    1416. 

  1416. <b><tt>int Printv(String_or_FILE *f, String_or_char *arg1,..., NULL)</tt></b>
    1417. 

  1417. </p>
    1418. 

  1418. 

  1419. <div class="indent">
    1420. 

  1420. Prints a variable number of strings arguments to the output.  The last
    1421. 

  1421. argument to this function must be NULL.   The other arguments can either
    1422. 

  1422. be <tt>char *</tt> or string objects.
    1423. 

  1423. </div>
    1424. 

  1424. 

  1425. <p>
    1426. 

  1426. <b><tt>int Putc(int ch, String_or_FILE *f)</tt></b>
    1427. 

  1427. </p>
    1428. 

  1428. 

  1429. <div class="indent">
    1430. 

  1430. Same as the C <tt>fputc()</tt> function.
    1431. 

  1431. </div>
    1432. 

  1432. 

  1433. <p>
    1434. 

  1434. <b><tt>int Write(String_or_FILE *f, void *buf, int len)</tt></b>
    1435. 

  1435. </p>
    1436. 

  1436. 

  1437. <div class="indent">
    1438. 

  1438. Same as the C <tt>write()</tt> function.
    1439. 

  1439. </div>
    1440. 

  1440. 

  1441. <p>
    1442. 

  1442. <b><tt>int Read(String_or_FILE *f, void *buf, int maxlen)</tt></b>
    1443. 

  1443. </p>
    1444. 

  1444. 

  1445. <div class="indent">
    1446. 

  1446. Same as the C <tt>read()</tt> function.
    1447. 

  1447. </div>
    1448. 

  1448. 

  1449. <p>
    1450. 

  1450. <b><tt>int Getc(String_or_FILE *f)</tt></b>
    1451. 

  1451. </p>
    1452. 

  1452. 

  1453. <div class="indent">
    1454. 

  1454. Same as the C <tt>fgetc()</tt> function.
    1455. 

  1455. </div>
    1456. 

  1456. 

  1457. <p>
    1458. 

  1458. <b><tt>int Ungetc(int ch, String_or_FILE *f)</tt></b>
    1459. 

  1459. </p>
    1460. 

  1460. 

  1461. <div class="indent">
    1462. 

  1462. Same as the C <tt>ungetc()</tt> function.
    1463. 

  1463. </div>
    1464. 

  1464. 

  1465. <p>
    1466. 

  1466. <b><tt>int Seek(String_or_FILE *f, int offset, int whence)</tt></b>
    1467. 

  1467. </p>
    1468. 

  1468. 

  1469. <div class="indent">
    1470. 

  1470. Same as the C <tt>seek()</tt> function.  <tt>offset</tt> is the number
    1471. 

  1471. of bytes.  <tt>whence</tt> is one of <tt>SEEK_SET</tt>,<tt>SEEK_CUR</tt>,
    1472. 

  1472. or <tt>SEEK_END</tt>..
    1473. 

  1473. </div>
    1474. 

  1474. 

  1475. <p>
    1476. 

  1476. <b><tt>long Tell(String_or_FILE *f)</tt></b>
    1477. 

  1477. </p>
    1478. 

  1478. 

  1479. <div class="indent">
    1480. 

  1480. Same as the C <tt>tell()</tt> function.
    1481. 

  1481. </div>
    1482. 

  1482. 

  1483. <p>
    1484. 

  1484. <b><tt>File *NewFile(const char *filename, const char *mode, List *newfiles)</tt></b>
    1485. 

  1485. </p>
    1486. 

  1486. 

  1487. <div class="indent">
    1488. 

  1488. Create a File object using the <tt>fopen()</tt> library call.  This
    1489. 

  1489. file differs from <tt>FILE *</tt> in that it can be placed in the standard
    1490. 

  1490. SWIG containers (lists, hashes, etc.). The <tt>filename</tt> is added to the 
    1491. 

  1491. <tt>newfiles</tt> list if <tt>newfiles</tt> is non-zero and the file was created successfully.
    1492. 

  1492. </div>
    1493. 

  1493. 

  1494. <p>
    1495. 

  1495. <b><tt>File *NewFileFromFile(FILE *f)</tt></b>
    1496. 

  1496. </p>
    1497. 

  1497. 

  1498. <div class="indent">
    1499. 

  1499. Create a File object wrapper around an existing <tt>FILE *</tt> object.
    1500. 

  1500. </div>
    1501. 

  1501. 

  1502. <p>
    1503. 

  1503. <b><tt>int Close(String_or_FILE *f)</tt></b>
    1504. 

  1504. </p>
    1505. 

  1505. 

  1506. <div class="indent">
    1507. 

  1507. <p>Closes a file.  Has no effect on strings.</p>
    1508. 

  1508. 

  1509. <p>
    1510. 

  1510. The use of the above I/O functions and strings play a critical role in SWIG.   It is
    1511. 

  1511. common to see small code fragments of code generated using code like this:
    1512. 

  1512. </p>
    1513. 

  1513. 

  1514. <div class="code">
    1515. 

  1515. <pre>
    1516. 

  1516. /* Print into a string */
    1517. 

  1517. String *s = NewString("");
    1518. 

  1518. Printf(s,"Hello\n");
    1519. 

  1519. for (i = 0; i &lt; 10; i++) {
    1520. 

  1520.     Printf(s,"%d\n", i);
    1521. 

  1521. }
    1522. 

  1522. ...
    1523. 

  1523. /* Print string into a file */
    1524. 

  1524. Printf(f, "%s\n", s);
    1525. 

  1525. </pre>
    1526. 

  1526. </div>
    1527. 

  1527. 

  1528. <p>
    1529. 

  1529. Similarly, the preprocessor and parser all operate on string-files.
    1530. 

  1530. </p>
    1531. 

  1531. 

  1532. </div>
    1533. 

  1533. 

  1534. <H2><a name="Extending_nn21"></a>35.6 Navigating and manipulating parse trees</H2>
    1535. 

  1535. 

  1536. 

  1537. Parse trees are built as collections of hash tables.   Each node is a hash table in which
    1538. 

  1538. arbitrary attributes can be stored.  Certain attributes in the hash table provide links to
    1539. 

  1539. other parse tree nodes.   The following macros can be used to move around the parse tree.
    1540. 

  1540. 

  1541. <p>
    1542. 

  1542. <b><tt>String *nodeType(Node *n)</tt></b>
    1543. 

  1543. </p>
    1544. 

  1544. 

  1545. <div class="indent">
    1546. 

  1546. Returns the node type tag as a string.  The returned string indicates the type of parse
    1547. 

  1547. tree node.
    1548. 

  1548. </div>
    1549. 

  1549. 

  1550. <p>
    1551. 

  1551. <b><tt>Node *nextSibling(Node *n)</tt></b>
    1552. 

  1552. </p>
    1553. 

  1553. 

  1554. <div class="indent">
    1555. 

  1555. Returns the next node in the parse tree.  For example, the next C declaration.
    1556. 

  1556. </div>
    1557. 

  1557. 

  1558. <p>
    1559. 

  1559. <b><tt>Node *previousSibling(Node *n)</tt></b>
    1560. 

  1560. </p>
    1561. 

  1561. 

  1562. <div class="indent">
    1563. 

  1563. Returns the previous node in the parse tree.  For example, the previous C declaration.
    1564. 

  1564. </div>
    1565. 

  1565. 

  1566. <p>
    1567. 

  1567. <b><tt>Node *firstChild(Node *n)</tt></b>
    1568. 

  1568. </p>
    1569. 

  1569. 

  1570. <div class="indent">
    1571. 

  1571. Returns the first child node.  For example, if <tt>n</tt> was a C++ class node, this would
    1572. 

  1572. return the node for the first class member.
    1573. 

  1573. </div>
    1574. 

  1574. 

  1575. <p>
    1576. 

  1576. <b><tt>Node *lastChild(Node *n)</tt></b>
    1577. 

  1577. </p>
    1578. 

  1578. 

  1579. <div class="indent">
    1580. 

  1580. Returns the last child node.   You might use this if you wanted to append a new
    1581. 

  1581. node to the of a class.
    1582. 

  1582. </div>
    1583. 

  1583. 

  1584. <p>
    1585. 

  1585. <b><tt>Node *parentNode(Node *n)</tt></b>
    1586. 

  1586. </p>
    1587. 

  1587. 

  1588. <div class="indent">
    1589. 

  1589. Returns the parent of node <tt>n</tt>.  Use this to move up the pass tree.
    1590. 

  1590. </div>
    1591. 

  1591. 

  1592. <p>
    1593. 

  1593. The following macros can be used to change all of the above attributes.
    1594. 

  1594. Normally, these functions are only used by the parser.  Changing them without
    1595. 

  1595. knowing what you are doing is likely to be dangerous.
    1596. 

  1596. </p>
    1597. 

  1597. 

  1598. <p>
    1599. 

  1599. <b><tt>void set_nodeType(Node *n, const String_or_char)</tt></b>
    1600. 

  1600. </p>
    1601. 

  1601. 

  1602. <div class="indent">
    1603. 

  1603. Change the node type.
    1604. 

  1604. tree node.
    1605. 

  1605. </div>
    1606. 

  1606. 

  1607. <p>
    1608. 

  1608. <b><tt>void set_nextSibling(Node *n, Node *s)</tt></b>
    1609. 

  1609. </p>
    1610. 

  1610. 

  1611. <div class="indent">
    1612. 

  1612. Set the next sibling.
    1613. 

  1613. </div>
    1614. 

  1614. 

  1615. <p>
    1616. 

  1616. <b><tt>void set_previousSibling(Node *n, Node *s)</tt></b>
    1617. 

  1617. </p>
    1618. 

  1618. 

  1619. <div class="indent">
    1620. 

  1620. Set the previous sibling.
    1621. 

  1621. </div>
    1622. 

  1622. 

  1623. <p>
    1624. 

  1624. <b><tt>void set_firstChild(Node *n, Node *c)</tt></b>
    1625. 

  1625. </p>
    1626. 

  1626. 

  1627. <div class="indent">
    1628. 

  1628. Set the first child node.
    1629. 

  1629. </div>
    1630. 

  1630. 

  1631. <p>
    1632. 

  1632. <b><tt>void set_lastChild(Node *n, Node *c)</tt></b>
    1633. 

  1633. </p>
    1634. 

  1634. 

  1635. <div class="indent">
    1636. 

  1636. Set the last child node.
    1637. 

  1637. </div>
    1638. 

  1638. 

  1639. <p>
    1640. 

  1640. <b><tt>void set_parentNode(Node *n, Node *p)</tt></b>
    1641. 

  1641. </p>
    1642. 

  1642. 

  1643. <div class="indent">
    1644. 

  1644. Set the parent node.
    1645. 

  1645. </div>
    1646. 

  1646. 

  1647. <p>
    1648. 

  1648. The following utility functions are used to alter the parse tree (at your own risk)
    1649. 

  1649. </p>
    1650. 

  1650. 

  1651. <p>
    1652. 

  1652. <b><tt>void appendChild(Node *parent, Node *child)</tt></b>
    1653. 

  1653. </p>
    1654. 

  1654. 

  1655. <div class="indent">
    1656. 

  1656. Append a child to <tt>parent</tt>.  The appended node becomes the last child.
    1657. 

  1657. </div>
    1658. 

  1658. 

  1659. <p>
    1660. 

  1660. <b><tt>void deleteNode(Node *node)</tt></b>
    1661. 

  1661. </p>
    1662. 

  1662. 

  1663. <div class="indent">
    1664. 

  1664. Deletes a node from the parse tree.  Deletion reconnects siblings and properly updates
    1665. 

  1665. the parent so that sibling nodes are unaffected.
    1666. 

  1666. </div>
    1667. 

  1667. 

  1668. <H2><a name="Extending_nn22"></a>35.7 Working with attributes</H2>
    1669. 

  1669. 

  1670. 

  1671. <p>
    1672. 

  1672. Since parse tree nodes are just hash tables, attributes are accessed using the <tt>Getattr()</tt>,
    1673. 

  1673. <tt>Setattr()</tt>, and <tt>Delattr()</tt> operations.  For example:
    1674. 

  1674. </p>
    1675. 

  1675. 

  1676. <div class="code">
    1677. 

  1677. <pre>
    1678. 

  1678. int functionHandler(Node *n) {
    1679. 

  1679.     String *name    = Getattr(n,"name");
    1680. 

  1680.     String *symname = Getattr(n,"sym:name");
    1681. 

  1681.     SwigType *type  = Getattr(n,"type");
    1682. 

  1682.     ...
    1683. 

  1683. }
    1684. 

  1684. </pre>
    1685. 

  1685. </div>
    1686. 

  1686. 

  1687. <p>
    1688. 

  1688. New attributes can be freely attached to a node as needed.   However, when new attributes
    1689. 

  1689. are attached during code generation, they should be prepended with a namespace prefix.
    1690. 

  1690. For example:
    1691. 

  1691. </p>
    1692. 

  1692. 

  1693. <div class="code">
    1694. 

  1694. <pre>
    1695. 

  1695. ...
    1696. 

  1696. Setattr(n,"python:docstring", doc);     /* Store docstring */
    1697. 

  1697. ...
    1698. 

  1698. </pre>
    1699. 

  1699. </div>
    1700. 

  1700. 

  1701. <p>
    1702. 

  1702. A quick way to check the value of an attribute is to use the <tt>checkAttribute()</tt> function like this:
    1703. 

  1703. </p>
    1704. 

  1704. 

  1705. <div class="code">
    1706. 

  1706. <pre>
    1707. 

  1707. if (checkAttribute(n,"storage","virtual")) {
    1708. 

  1708.    /* n is virtual */
    1709. 

  1709.    ...
    1710. 

  1710. }
    1711. 

  1711. </pre>
    1712. 

  1712. </div>
    1713. 

  1713. 

  1714. <p>
    1715. 

  1715. Changing the values of existing attributes is allowed and is sometimes done to implement
    1716. 

  1716. node transformations.   However, if a function/method modifies a node, it is required to restore
    1717. 

  1717. modified attributes to their original values.  To simplify the task of saving/restoring attributes,
    1718. 

  1718. the following functions are used:
    1719. 

  1719. </p>
    1720. 

  1720. 

  1721. <p>
    1722. 

  1722. <b><tt>int Swig_save(const char *ns, Node *n, const char *name1, const char *name2, ..., NIL)</tt></b>
    1723. 

  1723. </p>
    1724. 

  1724. 

  1725. <div class="indent">
    1726. 

  1726. Saves a copy of attributes <tt>name1</tt>, <tt>name2</tt>, etc. from node <tt>n</tt>.
    1727. 

  1727. Copies of the attributes are actually resaved in the node in a different namespace which is
    1728. 

  1728. set by the <tt>ns</tt> argument.   For example, if you call <tt>Swig_save("foo",n,"type",NIL)</tt>,
    1729. 

  1729. then the "type" attribute will be copied and saved as "foo:type".  The namespace name itself is stored in
    1730. 

  1730. the "view" attribute of the node.  If necessary, this can be examined to find out where previous
    1731. 

  1731. values of attributes might have been saved.
    1732. 

  1732. </div>
    1733. 

  1733. 

  1734. <p>
    1735. 

  1735. <b><tt>int Swig_restore(Node *n)</tt></b>
    1736. 

  1736. </p>
    1737. 

  1737. 

  1738. <div class="indent">
    1739. 

  1739. 

  1740. <p>
    1741. 

  1741. Restores the attributes saved by the previous call to <tt>Swig_save()</tt>.  Those
    1742. 

  1742. attributes that were supplied to <tt>Swig_save()</tt> will be restored to their
    1743. 

  1743. original values.
    1744. 

  1744. </p>
    1745. 

  1745. 

  1746. <p>
    1747. 

  1747. The <tt>Swig_save()</tt> and <tt>Swig_restore()</tt> functions must always be used as a pair.
    1748. 

  1748. That is, every call to <tt>Swig_save()</tt> must have a matching call to <tt>Swig_restore()</tt>.
    1749. 

  1749. Calls can be nested if necessary.  Here is an example that shows how the functions might be used:
    1750. 

  1750. </p>
    1751. 

  1751. 

  1752. <div class="code">
    1753. 

  1753. <pre>
    1754. 

  1754. int variableHandler(Node *n) {
    1755. 

  1755.     Swig_save("variableHandler",n,"type","sym:name",NIL);
    1756. 

  1756.     String *symname = Getattr(n,"sym:name");
    1757. 

  1757.     SwigType *type  = Getattr(n,"type");
    1758. 

  1758.     ...
    1759. 

  1759.     Append(symname,"_global");         // Change symbol name
    1760. 

  1760.     SwigType_add_pointer(type);        // Add pointer
    1761. 

  1761.     ...
    1762. 

  1762.     generate wrappers
    1763. 

  1763.     ...
    1764. 

  1764.     Swig_restore(n);                  // Restore original values
    1765. 

  1765.     return SWIG_OK;
    1766. 

  1766. }
    1767. 

  1767. </pre>
    1768. 

  1768. </div>
    1769. 

  1769. 

  1770. </div>
    1771. 

  1771. 

  1772. <p>
    1773. 

  1773. <b><tt>int Swig_require(const char *ns, Node *n, const char *name1, const char *name2, ..., NIL)</tt></b>
    1774. 

  1774. </p>
    1775. 

  1775. 

  1776. <div class="indent">
    1777. 

  1777. This is an enhanced version of <tt>Swig_save()</tt> that adds error checking.  If an attribute
    1778. 

  1778. name is not present in <tt>n</tt>, a failed assertion results and SWIG terminates with a fatal
    1779. 

  1779. error.  Optionally, if an attribute name is specified as "*<em>name</em>", a copy of the
    1780. 

  1780. attribute is saved as with <tt>Swig_save()</tt>.  If an attribute is specified as "?<em>name</em>",
    1781. 

  1781. the attribute is optional.   <tt>Swig_restore()</tt> must always be called after using this
    1782. 

  1782. function.
    1783. 

  1783. </div>
    1784. 

  1784. 

  1785. <H2><a name="Extending_nn23"></a>35.8 Type system</H2>
    1786. 

  1786. 

  1787. 

  1788. <p>
    1789. 

  1789. SWIG implements the complete C++ type system including typedef, inheritance,
    1790. 

  1790. pointers, references, and pointers to members.   A detailed discussion of
    1791. 

  1791. type theory is impossible here.   However, let's cover the highlights.
    1792. 

  1792. </p>
    1793. 

  1793. 

  1794. <H3><a name="Extending_nn24"></a>35.8.1 String encoding of types</H3>
    1795. 

  1795. 

  1796. 

  1797. <p>
    1798. 

  1798. All types in SWIG consist of a base datatype and a collection of type
    1799. 

  1799. operators that are applied to the base.   A base datatype is almost
    1800. 

  1800. always some kind of primitive type such as <tt>int</tt> or <tt>double</tt>.
    1801. 

  1801. The operators consist of things like pointers, references, arrays, and so forth.
    1802. 

  1802. Internally, types are represented as strings that are constructed in a very
    1803. 

  1803. precise manner.  Here are some examples:
    1804. 

  1804. </p>
    1805. 

  1805. 

  1806. <div class="diagram">
    1807. 

  1807. <pre>
    1808. 

  1808. C datatype                     SWIG encoding (strings)
    1809. 

  1809. -----------------------------  --------------------------
    1810. 

  1810. int                            "int"
    1811. 

  1811. int *                          "p.int"
    1812. 

  1812. const int *                    "p.q(const).int"
    1813. 

  1813. int (*x)(int,double)           "p.f(int,double).int"
    1814. 

  1814. int [20][30]                   "a(20).a(30).int"
    1815. 

  1815. int (F::*)(int)                "m(F).f(int).int"
    1816. 

  1816. vector&lt;int&gt; *                  "p.vector&lt;(int)&gt;"
    1817. 

  1817. </pre>
    1818. 

  1818. </div>
    1819. 

  1819. 

  1820. <p>
    1821. 

  1821. Reading the SWIG encoding is often easier than figuring out the C code---just
    1822. 

  1822. read it from left to right.  For a type of "p.f(int,double).int" is
    1823. 

  1823. a "pointer to a function(int,double) that returns int".
    1824. 

  1824. </p>
    1825. 

  1825. 

  1826. <p>
    1827. 

  1827. The following operator encodings are used in type strings:
    1828. 

  1828. </p>
    1829. 

  1829. 

  1830. <div class="diagram">
    1831. 

  1831. <pre>
    1832. 

  1832. Operator              Meaning
    1833. 

  1833. -------------------   -------------------------------
    1834. 

  1834. p.                    Pointer to
    1835. 

  1835. a(n).                 Array of dimension n
    1836. 

  1836. r.                    C++ reference
    1837. 

  1837. m(class).             Member pointer to class
    1838. 

  1838. f(args).              Function.
    1839. 

  1839. q(qlist).             Qualifiers
    1840. 

  1840. </pre>
    1841. 

  1841. </div>
    1842. 

  1842. 

  1843. <p>
    1844. 

  1844. In addition, type names may be parameterized by templates.  This is
    1845. 

  1845. represented by enclosing the template parameters in <tt>&lt;(
    1846. 

  1846. ... )&gt;</tt>.  Variable length arguments are represented by the
    1847. 

  1847. special base type of <tt>v(...)</tt>.
    1848. 

  1848. </p>
    1849. 

  1849. 

  1850. <p>
    1851. 

  1851. If you want to experiment with type encodings, the raw type strings can
    1852. 

  1852. be inserted into an interface file using backticks `` wherever a type
    1853. 

  1853. is expected.  For instance, here is
    1854. 

  1854. an extremely perverted example:
    1855. 

  1855. </p>
    1856. 

  1856. 

  1857. <div class="diagram">
    1858. 

  1858. <pre>
    1859. 

  1859. `p.a(10).p.f(int,p.f(int).int)` foo(int, int (*x)(int));
    1860. 

  1860. </pre>
    1861. 

  1861. </div>
    1862. 

  1862. 

  1863. <p>
    1864. 

  1864. This corresponds to the immediately obvious C declaration:
    1865. 

  1865. </p>
    1866. 

  1866. 

  1867. <div class="diagram">
    1868. 

  1868. <pre>
    1869. 

  1869. (*(*foo(int,int (*)(int)))[10])(int,int (*)(int));
    1870. 

  1870. </pre>
    1871. 

  1871. </div>
    1872. 

  1872. 

  1873. <p>
    1874. 

  1874. Aside from the potential use of this declaration on a C programming quiz,
    1875. 

  1875. it motivates the use of the special SWIG encoding of types.   The SWIG
    1876. 

  1876. encoding is much easier to work with because types can be easily examined,
    1877. 

  1877. modified, and constructed using simple string operations (comparison,
    1878. 

  1878. substrings, concatenation, etc.).   For example, in the parser, a declaration
    1879. 

  1879. like this
    1880. 

  1880. </p>
    1881. 

  1881. 

  1882. <div class="code">
    1883. 

  1883. <pre>
    1884. 

  1884. int *a[30];
    1885. 

  1885. </pre>
    1886. 

  1886. </div>
    1887. 

  1887. 

  1888. <p>
    1889. 

  1889. is processed in a few pieces.  In this case, you have the base type
    1890. 

  1890. "<tt>int</tt>" and the declarator of type "<tt>a(30).p.</tt>".  To
    1891. 

  1891. make the final type, the two parts are just joined together using
    1892. 

  1892. string concatenation.
    1893. 

  1893. </p>
    1894. 

  1894. 

  1895. <H3><a name="Extending_nn25"></a>35.8.2 Type construction</H3>
    1896. 

  1896. 

  1897. 

  1898. <p>
    1899. 

  1899. The following functions are used to construct types.  You should use
    1900. 

  1900. these functions instead of trying to build the type strings yourself.
    1901. 

  1901. </p>
    1902. 

  1902. 

  1903. <p>
    1904. 

  1904. <b><tt>void SwigType_add_pointer(SwigType *ty)</tt></b>
    1905. 

  1905. </p>
    1906. 

  1906. 

  1907. <div class="indent">
    1908. 

  1908. Adds a pointer to <tt>ty</tt>.
    1909. 

  1909. </div>
    1910. 

  1910. 

  1911. <p>
    1912. 

  1912. <b><tt>void SwigType_del_pointer(SwigType *ty)</tt></b>
    1913. 

  1913. </p>
    1914. 

  1914. 

  1915. <div class="indent">
    1916. 

  1916. Removes a single pointer from <tt>ty</tt>.
    1917. 

  1917. </div>
    1918. 

  1918. 

  1919. <p>
    1920. 

  1920. <b><tt>void SwigType_add_reference(SwigType *ty)</tt></b>
    1921. 

  1921. </p>
    1922. 

  1922. 

  1923. <div class="indent">
    1924. 

  1924. Adds a reference to <tt>ty</tt>.
    1925. 

  1925. </div>
    1926. 

  1926. 

  1927. <p>
    1928. 

  1928. <b><tt>void SwigType_add_array(SwigType *ty, const String_or_char *size)</tt></b>
    1929. 

  1929. </p>
    1930. 

  1930. 

  1931. <div class="indent">
    1932. 

  1932. Adds an array with dimension <tt>dim</tt> to <tt>ty</tt>.
    1933. 

  1933. </div>
    1934. 

  1934. 

  1935. <p>
    1936. 

  1936. <b><tt>void SwigType_del_array(SwigType *ty)</tt></b>
    1937. 

  1937. </p>
    1938. 

  1938. 

  1939. <div class="indent">
    1940. 

  1940. Removes a single array dimension from <tt>ty</tt>.
    1941. 

  1941. </div>
    1942. 

  1942. 

  1943. <p>
    1944. 

  1944. <b><tt>int SwigType_array_ndim(SwigType *ty)</tt></b>
    1945. 

  1945. </p>
    1946. 

  1946. 

  1947. <div class="indent">
    1948. 

  1948. Returns number of array dimensions of <tt>ty</tt>.
    1949. 

  1949. </div>
    1950. 

  1950. 

  1951. <p>
    1952. 

  1952. <b><tt>String* SwigType_array_getdim(SwigType *ty,int n)</tt></b>
    1953. 

  1953. </p>
    1954. 

  1954. 

  1955. <div class="indent">
    1956. 

  1956. Returns <tt>n</tt>th array dimension of <tt>ty</tt>.
    1957. 

  1957. </div>
    1958. 

  1958. 

  1959. <p>
    1960. 

  1960. <b><tt>void SwigType_array_setdim(SwigType *ty, int n, const String_or_char *rep)</tt></b>
    1961. 

  1961. </p>
    1962. 

  1962. 

  1963. <div class="indent">
    1964. 

  1964. Sets <tt>n</tt>th array dimensions of <tt>ty</tt> to <tt>rep</tt>.
    1965. 

  1965. </div>
    1966. 

  1966. 

  1967. <p>
    1968. 

  1968. <b><tt>void SwigType_add_qualifier(SwigType *ty, const String_or_char *q)</tt></b>
    1969. 

  1969. </p>
    1970. 

  1970. 

  1971. <div class="indent">
    1972. 

  1972. Adds a type qualifier <tt>q</tt> to <tt>ty</tt>.  <tt>q</tt> is typically
    1973. 

  1973. <tt>"const"</tt> or <tt>"volatile"</tt>.
    1974. 

  1974. </div>
    1975. 

  1975. 

  1976. <p>
    1977. 

  1977. <b><tt>void SwigType_add_memberpointer(SwigType *ty, const String_or_char *cls)</tt></b>
    1978. 

  1978. </p>
    1979. 

  1979. 

  1980. <div class="indent">
    1981. 

  1981. Adds a pointer to a member of class <tt>cls</tt> to <tt>ty</tt>.
    1982. 

  1982. </div>
    1983. 

  1983. 

  1984. <p>
    1985. 

  1985. <b><tt>void SwigType_add_function(SwigType *ty, ParmList *p)</tt></b>
    1986. 

  1986. </p>
    1987. 

  1987. 

  1988. <div class="indent">
    1989. 

  1989. Adds a function to <tt>ty</tt>.  <tt>p</tt> is a linked-list of parameter
    1990. 

  1990. nodes as generated by the parser. See the section on parameter lists
    1991. 

  1991. for details about the representation.
    1992. 

  1992. </div>
    1993. 

  1993. 

  1994. <p>
    1995. 

  1995. <b><tt>void SwigType_add_template(SwigType *ty, ParmList *p)</tt></b>
    1996. 

  1996. </p>
    1997. 

  1997. 

  1998. <div class="indent">
    1999. 

  1999. Adds a template to <tt>ty</tt>.  <tt>p</tt> is a linked-list of parameter
    2000. 

  2000. nodes as generated by the parser. See the section on parameter lists
    2001. 

  2001. for details about the representation.
    2002. 

  2002. </div>
    2003. 

  2003. 

  2004. <p>
    2005. 

  2005. <b><tt>SwigType *SwigType_pop(SwigType *ty)</tt></b>
    2006. 

  2006. </p>
    2007. 

  2007. 

  2008. <div class="indent">
    2009. 

  2009. Removes the last type constructor from <tt>ty</tt> and returns it.
    2010. 

  2010. <tt>ty</tt> is modified.
    2011. 

  2011. </div>
    2012. 

  2012. 

  2013. <p>
    2014. 

  2014. <b><tt>void SwigType_push(SwigType *ty, SwigType *op)</tt></b>
    2015. 

  2015. </p>
    2016. 

  2016. 

  2017. <div class="indent">
    2018. 

  2018. Pushes the type operators in <tt>op</tt> onto type <tt>ty</tt>.  The
    2019. 

  2019. opposite of <tt>SwigType_pop()</tt>.
    2020. 

  2020. </div>
    2021. 

  2021. 

  2022. <p>
    2023. 

  2023. <b><tt>SwigType *SwigType_pop_arrays(SwigType *ty)</tt></b>
    2024. 

  2024. </p>
    2025. 

  2025. 

  2026. <div class="indent">
    2027. 

  2027. Removes all leading array operators from <tt>ty</tt> and returns them.
    2028. 

  2028. <tt>ty</tt> is modified.   For example, if <tt>ty</tt> is <tt>"a(20).a(10).p.int"</tt>,
    2029. 

  2029. then this function would return <tt>"a(20).a(10)."</tt> and modify <tt>ty</tt>
    2030. 

  2030. so that it has the value <tt>"p.int"</tt>.
    2031. 

  2031. </div>
    2032. 

  2032. 

  2033. <p>
    2034. 

  2034. <b><tt>SwigType *SwigType_pop_function(SwigType *ty)</tt></b>
    2035. 

  2035. </p>
    2036. 

  2036. 

  2037. <div class="indent">
    2038. 

  2038. Removes a function operator from <tt>ty</tt> including any qualification.
    2039. 

  2039. <tt>ty</tt> is modified.   For example, if <tt>ty</tt> is <tt>"f(int).int"</tt>,
    2040. 

  2040. then this function would return <tt>"f(int)."</tt> and modify <tt>ty</tt>
    2041. 

  2041. so that it has the value <tt>"int"</tt>.
    2042. 

  2042. </div>
    2043. 

  2043. 

  2044. <p>
    2045. 

  2045. <b><tt>SwigType *SwigType_base(SwigType *ty)</tt></b>
    2046. 

  2046. </p>
    2047. 

  2047. 

  2048. <div class="indent">
    2049. 

  2049. Returns the base type of a type.  For example, if <tt>ty</tt> is
    2050. 

  2050. <tt>"p.a(20).int"</tt>, this function would return <tt>"int"</tt>.
    2051. 

  2051. <tt>ty</tt> is unmodified.
    2052. 

  2052. </div>
    2053. 

  2053. 

  2054. <p>
    2055. 

  2055. <b><tt>SwigType *SwigType_prefix(SwigType *ty)</tt></b>
    2056. 

  2056. </p>
    2057. 

  2057. 

  2058. <div class="indent">
    2059. 

  2059. Returns the prefix of a type. For example, if <tt>ty</tt> is
    2060. 

  2060. <tt>"p.a(20).int"</tt>, this function would return <tt>"p.a(20)."</tt>.
    2061. 

  2061. <tt>ty</tt> is unmodified.
    2062. 

  2062. </div>
    2063. 

  2063. 

  2064. <H3><a name="Extending_nn26"></a>35.8.3 Type tests</H3>
    2065. 

  2065. 

  2066. 

  2067. <p>
    2068. 

  2068. The following functions can be used to test properties of a datatype.
    2069. 

  2069. </p>
    2070. 

  2070. 

  2071. <p>
    2072. 

  2072. <b><tt>int SwigType_ispointer(SwigType *ty)</tt></b>
    2073. 

  2073. </p>
    2074. 

  2074. 

  2075. <div class="indent">
    2076. 

  2076. Checks if <tt>ty</tt> is a standard pointer.
    2077. 

  2077. </div>
    2078. 

  2078. 

  2079. <p>
    2080. 

  2080. <b><tt>int SwigType_ismemberpointer(SwigType *ty)</tt></b>
    2081. 

  2081. </p>
    2082. 

  2082. 

  2083. <div class="indent">
    2084. 

  2084. Checks if <tt>ty</tt> is a member pointer.
    2085. 

  2085. </div>
    2086. 

  2086. 

  2087. <p>
    2088. 

  2088. <b><tt>int SwigType_isreference(SwigType *ty)</tt></b>
    2089. 

  2089. </p>
    2090. 

  2090. 

  2091. <div class="indent">
    2092. 

  2092. Checks if <tt>ty</tt> is a C++ reference.
    2093. 

  2093. </div>
    2094. 

  2094. 

  2095. <p>
    2096. 

  2096. <b><tt>int SwigType_isarray(SwigType *ty)</tt></b>
    2097. 

  2097. </p>
    2098. 

  2098. 

  2099. <div class="indent">
    2100. 

  2100. Checks if <tt>ty</tt> is an array.
    2101. 

  2101. </div>
    2102. 

  2102. 

  2103. <p>
    2104. 

  2104. <b><tt>int SwigType_isfunction(SwigType *ty)</tt></b>
    2105. 

  2105. </p>
    2106. 

  2106. 

  2107. <div class="indent">
    2108. 

  2108. Checks if <tt>ty</tt> is a function.
    2109. 

  2109. </div>
    2110. 

  2110. 

  2111. <p>
    2112. 

  2112. <b><tt>int SwigType_isqualifier(SwigType *ty)</tt></b>
    2113. 

  2113. </p>
    2114. 

  2114. 

  2115. <div class="indent">
    2116. 

  2116. Checks if <tt>ty</tt> is a qualifier.
    2117. 

  2117. </div>
    2118. 

  2118. 

  2119. <p>
    2120. 

  2120. <b><tt>int SwigType_issimple(SwigType *ty)</tt></b>
    2121. 

  2121. </p>
    2122. 

  2122. 

  2123. <div class="indent">
    2124. 

  2124. Checks if <tt>ty</tt> is a simple type.  No operators applied.
    2125. 

  2125. </div>
    2126. 

  2126. 

  2127. <p>
    2128. 

  2128. <b><tt>int SwigType_isconst(SwigType *ty)</tt></b>
    2129. 

  2129. </p>
    2130. 

  2130. 

  2131. <div class="indent">
    2132. 

  2132. Checks if <tt>ty</tt> is a const type.
    2133. 

  2133. </div>
    2134. 

  2134. 

  2135. <p>
    2136. 

  2136. <b><tt>int SwigType_isvarargs(SwigType *ty)</tt></b>
    2137. 

  2137. </p>
    2138. 

  2138. 

  2139. <div class="indent">
    2140. 

  2140. Checks if <tt>ty</tt> is a varargs type.
    2141. 

  2141. </div>
    2142. 

  2142. 

  2143. <p>
    2144. 

  2144. <b><tt>int SwigType_istemplate(SwigType *ty)</tt></b>
    2145. 

  2145. </p>
    2146. 

  2146. 

  2147. <div class="indent">
    2148. 

  2148. Checks if <tt>ty</tt> is a templatized type.
    2149. 

  2149. </div>
    2150. 

  2150. 

  2151. <H3><a name="Extending_nn27"></a>35.8.4 Typedef and inheritance</H3>
    2152. 

  2152. 

  2153. 

  2154. <p>
    2155. 

  2155. The behavior of <tt>typedef</tt> declaration is to introduce a type alias.
    2156. 

  2156. For instance, <tt>typedef int Integer</tt> makes the identifier
    2157. 

  2157. <tt>Integer</tt> an alias for <tt>int</tt>.  The treatment of typedef in
    2158. 

  2158. SWIG is somewhat complicated due to the pattern matching rules that get applied
    2159. 

  2159. in typemaps and the fact that SWIG prefers to generate wrapper code
    2160. 

  2160. that closely matches the input to simplify debugging (a user will see the
    2161. 

  2161. typedef names used in their program instead of the low-level primitive C
    2162. 

  2162. datatypes).
    2163. 

  2163. </p>
    2164. 

  2164. 

  2165. <p>
    2166. 

  2166. To handle <tt>typedef</tt>, SWIG builds a collection of trees containing typedef relations. For example,
    2167. 

  2167. </p>
    2168. 

  2168. 

  2169. <div class="code">
    2170. 

  2170. <pre>
    2171. 

  2171. typedef int Integer;
    2172. 

  2172. typedef Integer *IntegerPtr;
    2173. 

  2173. typedef int Number;
    2174. 

  2174. typedef int Size;
    2175. 

  2175. </pre>
    2176. 

  2176. </div>
    2177. 

  2177. 

  2178. <p>
    2179. 

  2179. produces two trees like this:
    2180. 

  2180. </p>
    2181. 

  2181. 

  2182. <div class="diagram">
    2183. 

  2183. <pre>
    2184. 

  2184.                  int               p.Integer
    2185. 

  2185.                ^  ^  ^                 ^
    2186. 

  2186.               /   |   \                |
    2187. 

  2187.              /    |    \               |
    2188. 

  2188.         Integer  Size   Number    IntegerPtr
    2189. 

  2189. </pre>
    2190. 

  2190. </div>
    2191. 

  2191. 

  2192. <p>
    2193. 

  2193. To resolve a single typedef relationship, the following function is used:
    2194. 

  2194. </p>
    2195. 

  2195. 

  2196. <p>
    2197. 

  2197. <b><tt>SwigType *SwigType_typedef_resolve(SwigType *ty)</tt></b>
    2198. 

  2198. </p>
    2199. 

  2199. 

  2200. <div class="indent">
    2201. 

  2201. Checks if <tt>ty</tt> can be reduced to a new type via typedef.  If so,
    2202. 

  2202. returns the new type.  If not, returns NULL.
    2203. 

  2203. </div>
    2204. 

  2204. 

  2205. <p>
    2206. 

  2206. Typedefs are only resolved in simple typenames that appear in a type.
    2207. 

  2207. For example, the type base name and in function parameters.   When
    2208. 

  2208. resolving types, the process starts in the leaf nodes and moves up
    2209. 

  2209. the tree towards the root.   Here are a few examples that show how it works:
    2210. 

  2210. </p>
    2211. 

  2211. 

  2212. <div class="diagram">
    2213. 

  2213. <pre>
    2214. 

  2214. Original type            After typedef_resolve()
    2215. 

  2215. ------------------------ -----------------------
    2216. 

  2216. Integer                  int
    2217. 

  2217. a(30).Integer            int
    2218. 

  2218. p.IntegerPtr             p.p.Integer
    2219. 

  2219. p.p.Integer              p.p.int
    2220. 

  2220. </pre>
    2221. 

  2221. </div>
    2222. 

  2222. 

  2223. <p>
    2224. 

  2224. For complicated types, the process can be quite involved.  Here is the
    2225. 

  2225. reduction of a function pointer:
    2226. 

  2226. </p>
    2227. 

  2227. 

  2228. <div class="diagram">
    2229. 

  2229. <pre>
    2230. 

  2230. p.f(Integer, p.IntegerPtr, Size).Integer          : Start
    2231. 

  2231. p.f(Integer, p.IntegerPtr, Size).int
    2232. 

  2232. p.f(int, p.IntegerPtr, Size).int
    2233. 

  2233. p.f(int, p.p.Integer, Size).int
    2234. 

  2234. p.f(int, p.p.int, Size).int
    2235. 

  2235. p.f(int, p.p.int, int).int                        : End
    2236. 

  2236. </pre>
    2237. 

  2237. </div>
    2238. 

  2238. 

  2239. <p>
    2240. 

  2240. Two types are equivalent if their full type reductions are the same.
    2241. 

  2241. The following function will fully reduce a datatype:
    2242. 

  2242. </p>
    2243. 

  2243. 

  2244. <p>
    2245. 

  2245. <b><tt>SwigType *SwigType_typedef_resolve_all(SwigType *ty)</tt></b>
    2246. 

  2246. </p>
    2247. 

  2247. 

  2248. <div class="indent">
    2249. 

  2249. Fully reduces <tt>ty</tt> according to typedef rules.  Resulting datatype
    2250. 

  2250. will consist only of primitive typenames.
    2251. 

  2251. </div>
    2252. 

  2252. 

  2253. <H3><a name="Extending_nn28"></a>35.8.5 Lvalues</H3>
    2254. 

  2254. 

  2255. 

  2256. <p>
    2257. 

  2257. When generating wrapper code, it is necessary to emit datatypes that can
    2258. 

  2258. be used on the left-hand side of an assignment operator (an lvalue). However,
    2259. 

  2259. not all C datatypes can be used in this way---especially arrays and
    2260. 

  2260. const-qualified types.  To generate a type that can be used as an lvalue,
    2261. 

  2261. use the following function:
    2262. 

  2262. </p>
    2263. 

  2263. 

  2264. <p>
    2265. 

  2265. <b><tt>SwigType *SwigType_ltype(SwigType *ty)</tt></b>
    2266. 

  2266. </p>
    2267. 

  2267. 

  2268. <div class="indent">
    2269. 

  2269. Converts type <tt>ty</tt> to a type that can be used as an lvalue in
    2270. 

  2270. assignment.  The resulting type is stripped of qualifiers and arrays are
    2271. 

  2271. converted to a pointers.
    2272. 

  2272. </div>
    2273. 

  2273. 

  2274. <p>
    2275. 

  2275. The creation of lvalues is fully aware of typedef and other aspects
    2276. 

  2276. of the type system.  Therefore, the creation of an lvalue may result in
    2277. 

  2277. unexpected results.  Here are a few examples:
    2278. 

  2278. </p>
    2279. 

  2279. 

  2280. <div class="code">
    2281. 

  2281. <pre>
    2282. 

  2282. typedef double Matrix4[4][4];
    2283. 

  2283. Matrix4 x;    // type = 'Matrix4', ltype='p.a(4).double'
    2284. 

  2284. 

  2285. typedef const char * Literal;
    2286. 

  2286. Literal y;    // type = 'Literal', ltype='p.char'
    2287. 

  2287. </pre>
    2288. 

  2288. </div>
    2289. 

  2289. 

  2290. <H3><a name="Extending_nn29"></a>35.8.6 Output functions</H3>
    2291. 

  2291. 

  2292. 

  2293. <p>
    2294. 

  2294. The following functions produce strings that are suitable for output.
    2295. 

  2295. </p>
    2296. 

  2296. 

  2297. <p>
    2298. 

  2298. <b><tt>String *SwigType_str(SwigType *ty, const String_or_char *id = 0)</tt></b>
    2299. 

  2299. </p>
    2300. 

  2300. 

  2301. <div class="indent">
    2302. 

  2302. Generates a C string for a datatype.  <tt>id</tt> is an optional declarator.
    2303. 

  2303. For example, if <tt>ty</tt> is "p.f(int).int" and <tt>id</tt> is "foo", then
    2304. 

  2304. this function produces "<tt>int (*foo)(int)</tt>".   This function is
    2305. 

  2305. used to convert string-encoded types back into a form that is valid C syntax.
    2306. 

  2306. </div>
    2307. 

  2307. 

  2308. <p>
    2309. 

  2309. <b><tt>String *SwigType_lstr(SwigType *ty, const String_or_char *id = 0)</tt></b>
    2310. 

  2310. </p>
    2311. 

  2311. 

  2312. <div class="indent">
    2313. 

  2313. This is the same as <tt>SwigType_str()</tt> except that the result
    2314. 

  2314. is generated from the type's lvalue (as generated from SwigType_ltype).
    2315. 

  2315. </div>
    2316. 

  2316. 

  2317. <p>
    2318. 

  2318. <b><tt>String *SwigType_lcaststr(SwigType *ty, const String_or_char *id = 0)</tt></b>
    2319. 

  2319. </p>
    2320. 

  2320. 

  2321. <div class="indent">
    2322. 

  2322. Generates a casting operation that converts from type <tt>ty</tt> to its
    2323. 

  2323. lvalue.  <tt>id</tt> is an optional name to include in the cast.  For example,
    2324. 

  2324. if <tt>ty</tt> is "<tt>q(const).p.char</tt>" and <tt>id</tt> is "<tt>foo</tt>",
    2325. 

  2325. this function produces the string "<tt>(char *) foo</tt>".
    2326. 

  2326. </div>
    2327. 

  2327. 

  2328. <p>
    2329. 

  2329. <b><tt>String *SwigType_rcaststr(SwigType *ty, const String_or_char *id = 0)</tt></b>
    2330. 

  2330. </p>
    2331. 

  2331. 

  2332. <div class="indent">
    2333. 

  2333. Generates a casting operation that converts from a type's lvalue to a
    2334. 

  2334. type equivalent to <tt>ty</tt>. <tt>id</tt> is an optional name to
    2335. 

  2335. include in the cast.  For example, if <tt>ty</tt> is
    2336. 

  2336. "<tt>q(const).p.char</tt>" and <tt>id</tt> is "<tt>foo</tt>", this
    2337. 

  2337. function produces the string "<tt>(const char *) foo</tt>".
    2338. 

  2338. </div>
    2339. 

  2339. 

  2340. <p>
    2341. 

  2341. <b><tt>String *SwigType_manglestr(SwigType *ty)</tt></b>
    2342. 

  2342. </p>
    2343. 

  2343. 

  2344. <div class="indent">
    2345. 

  2345. Generates a mangled string encoding of type <tt>ty</tt>.   The
    2346. 

  2346. mangled string only contains characters that are part of a valid
    2347. 

  2347. C identifier.   The resulting string is used in various parts of
    2348. 

  2348. SWIG, but is most commonly associated with type-descriptor objects
    2349. 

  2349. that appear in wrappers (e.g., <tt>SWIGTYPE_p_double</tt>).
    2350. 

  2350. </div>
    2351. 

  2351. 

  2352. <H2><a name="Extending_nn30"></a>35.9 Parameters</H2>
    2353. 

  2353. 

  2354. 

  2355. <p>
    2356. 

  2356. Several type-related functions involve parameter lists.  These include
    2357. 

  2357. functions and templates.  Parameter list are represented as a list of
    2358. 

  2358. nodes with the following attributes:
    2359. 

  2359. </p>
    2360. 

  2360. 

  2361. <div class="diagram">
    2362. 

  2362. <pre>
    2363. 

  2363. "type"        -  Parameter type  (required)
    2364. 

  2364. "name"        -  Parameter name  (optional)
    2365. 

  2365. "value"       -  Initializer     (optional)
    2366. 

  2366. </pre>
    2367. 

  2367. </div>
    2368. 

  2368. 

  2369. <p>
    2370. 

  2370. Typically parameters are denoted in the source by using a typename of
    2371. 

  2371. <tt>Parm *</tt> or <tt>ParmList *</tt>.  To walk a parameter list, simply use
    2372. 

  2372. code like this:
    2373. 

  2373. </p>
    2374. 

  2374. 

  2375. <div class="diagram">
    2376. 

  2376. <pre>
    2377. 

  2377. Parm *parms;
    2378. 

  2378. Parm *p;
    2379. 

  2379. for (p = parms; p; p = nextSibling(p)) {
    2380. 

  2380.     SwigType *type  = Getattr(p,"type");
    2381. 

  2381.     String   *name  = Getattr(p,"name");
    2382. 

  2382.     String   *value = Getattr(p,"value");
    2383. 

  2383.     ...
    2384. 

  2384. }
    2385. 

  2385. </pre>
    2386. 

  2386. </div>
    2387. 

  2387. 

  2388. <p>
    2389. 

  2389. Note: this code is exactly the same as what you would use to walk parse tree nodes.
    2390. 

  2390. </p>
    2391. 

  2391. 

  2392. <p>
    2393. 

  2393. An empty list of parameters is denoted by a NULL pointer.
    2394. 

  2394. </p>
    2395. 

  2395. 

  2396. <p>
    2397. 

  2397. Since parameter lists are fairly common, the following utility functions are provided
    2398. 

  2398. to manipulate them:
    2399. 

  2399. </p>
    2400. 

  2400. 

  2401. <p>
    2402. 

  2402. <b><tt>Parm  *CopyParm(Parm *p);</tt></b>
    2403. 

  2403. </p>
    2404. 

  2404. 

  2405. <div class="indent">
    2406. 

  2406. Copies a single parameter.
    2407. 

  2407. </div>
    2408. 

  2408. 

  2409. <p>
    2410. 

  2410. <b><tt>ParmList  *CopyParmList(ParmList *p);</tt></b>
    2411. 

  2411. </p>
    2412. 

  2412. 

  2413. <div class="indent">
    2414. 

  2414. Copies an entire list of parameters.
    2415. 

  2415. </div>
    2416. 

  2416. 

  2417. <p>
    2418. 

  2418. <b><tt>int ParmList_len(ParmList *p);</tt></b>
    2419. 

  2419. </p>
    2420. 

  2420. 

  2421. <div class="indent">
    2422. 

  2422. Returns the number of parameters in a parameter list.
    2423. 

  2423. </div>
    2424. 

  2424. 

  2425. <p>
    2426. 

  2426. <b><tt>String *ParmList_str(ParmList *p);</tt></b>
    2427. 

  2427. </p>
    2428. 

  2428. 

  2429. <div class="indent">
    2430. 

  2430. Converts a parameter list into a C string.  For example,
    2431. 

  2431. produces a string like "<tt>(int *p, int n, double x);</tt>".
    2432. 

  2432. </div>
    2433. 

  2433. 

  2434. <p>
    2435. 

  2435. <b><tt>String *ParmList_protostr(ParmList *p);</tt></b>
    2436. 

  2436. </p>
    2437. 

  2437. 

  2438. <div class="indent">
    2439. 

  2439. The same as <tt>ParmList_str()</tt> except that parameter names are not
    2440. 

  2440. included.  Used to emit prototypes.
    2441. 

  2441. </div>
    2442. 

  2442. 

  2443. <p>
    2444. 

  2444. <b><tt>int ParmList_numrequired(ParmList *p);</tt></b>
    2445. 

  2445. </p>
    2446. 

  2446. 

  2447. <div class="indent">
    2448. 

  2448. Returns the number of required (non-optional) arguments in <tt>p</tt>.
    2449. 

  2449. </div>
    2450. 

  2450. 

  2451. <H2><a name="Extending_nn31"></a>35.10 Writing a Language Module</H2>
    2452. 

  2452. 

  2453. 

  2454. <p>
    2455. 

  2455. One of the easiest routes to supporting a new language module is to copy an already
    2456. 

  2456. supported language module implementation and modify it.
    2457. 

  2457. Be sure to choose a language that is similar in nature to the new language.
    2458. 

  2458. All language modules follow a similar structure and 
    2459. 

  2459. this section briefly outlines the steps needed to create a bare-bones
    2460. 

  2460. language module from scratch.
    2461. 

  2461. Since the code is relatively easy to read, this section
    2462. 

  2462. describes the creation of a minimal Python module.   You should be able to extrapolate
    2463. 

  2463. this to other languages.
    2464. 

  2464. </p>
    2465. 

  2465. 

  2466. <H3><a name="Extending_nn32"></a>35.10.1 Execution model</H3>
    2467. 

  2467. 

  2468. 

  2469. <p>
    2470. 

  2470. Code generation modules are defined by inheriting from the <tt>Language</tt> class,
    2471. 

  2471. currently defined in the <tt>Source/Modules</tt> directory of SWIG.  Starting from
    2472. 

  2472. the parsing of command line options, all aspects of code generation are controlled by
    2473. 

  2473. different methods of the <tt>Language</tt> that must be defined by your module.
    2474. 

  2474. </p>
    2475. 

  2475. 

  2476. <H3><a name="Extending_starting_out"></a>35.10.2 Starting out</H3>
    2477. 

  2477. 

  2478. 

  2479. <p>
    2480. 

  2480. To define a new language module, first create a minimal implementation using
    2481. 

  2481. this example as a guide:
    2482. 

  2482. </p>
    2483. 

  2483. 

  2484. <div class="code">
    2485. 

  2485. <pre>
    2486. 

  2486. #include "swigmod.h"
    2487. 

  2487. 

  2488. class PYTHON : public Language {
    2489. 

  2489. public:
    2490. 

  2490. 

  2491.   virtual void main(int argc, char *argv[]) {
    2492. 

  2492.     printf("I'm the Python module.\n");
    2493. 

  2493.   }
    2494. 

  2494. 

  2495.   virtual int top(Node *n) {
    2496. 

  2496.     printf("Generating code.\n");
    2497. 

  2497.     return SWIG_OK;
    2498. 

  2498.   }
    2499. 

  2499. 

  2500. };
    2501. 

  2501. 

  2502. extern "C" Language *
    2503. 

  2503. swig_python(void) {
    2504. 

  2504.   return new PYTHON();
    2505. 

  2505. }
    2506. 

  2506. </pre>
    2507. 

  2507. </div>
    2508. 

  2508. 

  2509. <p>
    2510. 

  2510. The "swigmod.h" header file contains, among other things, the declaration
    2511. 

  2511. of the <tt>Language</tt> base class and so you should include it at the top
    2512. 

  2512. of your language module's source file. Similarly, the "swigconfig.h" header
    2513. 

  2513. file contains some other useful definitions that you may need. Note that you
    2514. 

  2514. should <em>not</em> include any header files that are installed with the
    2515. 

  2515. target language. That is to say, the implementation of the SWIG Python module
    2516. 

  2516. shouldn't have any dependencies on the Python header files. The wrapper code
    2517. 

  2517. generated by SWIG will almost always depend on some language-specific C/C++
    2518. 

  2518. header files, but SWIG itself does not.
    2519. 

  2519. </p>
    2520. 

  2520. 

  2521. <p>
    2522. 

  2522. Give your language class a reasonable name, usually the same as the target language.
    2523. 

  2523. By convention, these class names are all uppercase (e.g. "PYTHON" for the Python
    2524. 

  2524. language module) but this is not a requirement. This class will ultimately consist
    2525. 

  2525. of a number of overrides of the virtual functions declared in the <tt>Language</tt>
    2526. 

  2526. base class, in addition to any language-specific member functions and data you
    2527. 

  2527. need. For now, just use the dummy implementations shown above.
    2528. 

  2528. </p>
    2529. 

  2529. 

  2530. <p>
    2531. 

  2531. The language module ends with a factory function, <tt>swig_python()</tt>, that simply
    2532. 

  2532. returns a new instance of the language class. As shown, it should be declared with the
    2533. 

  2533. <tt>extern "C"</tt> storage qualifier so that it can be called from C code. It should
    2534. 

  2534. also return a pointer to the base class (<tt>Language</tt>) so that only the interface
    2535. 

  2535. (and not the implementation) of your language module is exposed to the rest of SWIG.
    2536. 

  2536. </p>
    2537. 

  2537. 

  2538. <p>
    2539. 

  2539. Save the code for your language module in a file named "<tt>python.cxx</tt>" and.
    2540. 

  2540. place this file in the <tt>Source/Modules</tt> directory of the SWIG distribution.
    2541. 

  2541. To ensure that your module is compiled into SWIG along with the other language modules,
    2542. 

  2542. modify the file <tt>Source/Modules/Makefile.am</tt> to include the additional source
    2543. 

  2543. files.  In addition, modify the file <tt>Source/Modules/swigmain.cxx</tt>
    2544. 

  2544. with an additional command line option that activates the module. Read the source---it's straightforward.
    2545. 

  2545. </p>
    2546. 

  2546. 

  2547. <p>
    2548. 

  2548. Next, at the top level of the SWIG distribution, re-run the <tt>autogen.sh</tt> script
    2549. 

  2549. to regenerate the various build files:
    2550. 

  2550. </p>
    2551. 

  2551. 

  2552. <div class="shell">
    2553. 

  2553. <pre>
    2554. 

  2554. $ <b>./autogen.sh</b>
    2555. 

  2555. </pre>
    2556. 

  2556. </div>
    2557. 

  2557. 

  2558. <p>
    2559. 

  2559. Next re-run <tt>configure</tt> to regenerate all of the Makefiles:
    2560. 

  2560. </p>
    2561. 

  2561. 

  2562. <div class="shell">
    2563. 

  2563. <pre>
    2564. 

  2564. $ <b>./configure</b>
    2565. 

  2565. </pre>
    2566. 

  2566. </div>
    2567. 

  2567. 

  2568. <p>
    2569. 

  2569. Finally, rebuild SWIG with your module added:
    2570. 

  2570. </p>
    2571. 

  2571. 

  2572. <div class="shell">
    2573. 

  2573. <pre>
    2574. 

  2574. $ <b>make</b>
    2575. 

  2575. </pre>
    2576. 

  2576. </div>
    2577. 

  2577. 

  2578. <p>
    2579. 

  2579. Once it finishes compiling, try running SWIG with the command-line option
    2580. 

  2580. that activates your module. For example, <tt>swig -python foo.i</tt>. The
    2581. 

  2581. messages from your new module should appear.
    2582. 

  2582. </p>
    2583. 

  2583. 

  2584. <H3><a name="Extending_nn34"></a>35.10.3 Command line options</H3>
    2585. 

  2585. 

  2586. 

  2587. <p>
    2588. 

  2588. When SWIG starts, the command line options are passed to your language module.  This occurs
    2589. 

  2589. before any other processing occurs (preprocessing, parsing, etc.).   To capture the
    2590. 

  2590. command line options, simply use code similar to this:
    2591. 

  2591. </p>
    2592. 

  2592. 

  2593. <div class="code">
    2594. 

  2594. <pre>
    2595. 

  2595. void Language::main(int argc, char *argv[]) {
    2596. 

  2596.   for (int i = 1; i &lt; argc; i++) {
    2597. 

  2597.       if (argv[i]) {
    2598. 

  2598.           if(strcmp(argv[i],"-interface") == 0) {
    2599. 

  2599.             if (argv[i+1]) {
    2600. 

  2600.               interface = NewString(argv[i+1]);
    2601. 

  2601.               Swig_mark_arg(i);
    2602. 

  2602.               Swig_mark_arg(i+1);
    2603. 

  2603.               i++;
    2604. 

  2604.             } else {
    2605. 

  2605.               Swig_arg_error();
    2606. 

  2606.             }
    2607. 

  2607.           } else if (strcmp(argv[i],"-globals") == 0) {
    2608. 

  2608.             if (argv[i+1]) {
    2609. 

  2609.               global_name = NewString(argv[i+1]);
    2610. 

  2610.               Swig_mark_arg(i);
    2611. 

  2611.               Swig_mark_arg(i+1);
    2612. 

  2612.               i++;
    2613. 

  2613.             } else {
    2614. 

  2614.               Swig_arg_error();
    2615. 

  2615.             }
    2616. 

  2616.           } else if ( (strcmp(argv[i],"-proxy") == 0)) {
    2617. 

  2617.             proxy_flag = 1;
    2618. 

  2618.             Swig_mark_arg(i);
    2619. 

  2619.           } else if (strcmp(argv[i],"-keyword") == 0) {
    2620. 

  2620.             use_kw = 1;
    2621. 

  2621.             Swig_mark_arg(i);
    2622. 

  2622.           } else if (strcmp(argv[i],"-help") == 0) {
    2623. 

  2623.             fputs(usage,stderr);
    2624. 

  2624.           }
    2625. 

  2625.           ...
    2626. 

  2626.       }
    2627. 

  2627.   }
    2628. 

  2628. }
    2629. 

  2629. </pre>
    2630. 

  2630. </div>
    2631. 

  2631. 

  2632. <p>
    2633. 

  2633. The exact set of options depends on what you want to do in your module.   Generally,
    2634. 

  2634. you would use the options to change code generation modes or to print diagnostic information.
    2635. 

  2635. </p>
    2636. 

  2636. 

  2637. <p>
    2638. 

  2638. If a module recognizes an option, it should always call <tt>Swig_mark_arg()</tt>
    2639. 

  2639. to mark the option as valid.   If you forget to do this, SWIG will terminate with an
    2640. 

  2640. unrecognized command line option error.
    2641. 

  2641. </p>
    2642. 

  2642. 

  2643. <H3><a name="Extending_nn35"></a>35.10.4 Configuration and preprocessing</H3>
    2644. 

  2644. 

  2645. 

  2646. <p>
    2647. 

  2647. In addition to looking at command line options, the <tt>main()</tt> method is responsible
    2648. 

  2648. for some initial configuration of the SWIG library and preprocessor.   To do this,
    2649. 

  2649. insert some code like this:
    2650. 

  2650. </p>
    2651. 

  2651. 

  2652. <div class="code">
    2653. 

  2653. <pre>
    2654. 

  2654. void main(int argc, char *argv[]) {
    2655. 

  2655.    ... command line options ...
    2656. 

  2656. 

  2657.    /* Set language-specific subdirectory in SWIG library */
    2658. 

  2658.    SWIG_library_directory("python");
    2659. 

  2659. 

  2660.    /* Set language-specific preprocessing symbol */
    2661. 

  2661.    Preprocessor_define("SWIGPYTHON 1", 0);
    2662. 

  2662. 

  2663.    /* Set language-specific configuration file */
    2664. 

  2664.    SWIG_config_file("python.swg");
    2665. 

  2665. 

  2666.    /* Set typemap language (historical) */
    2667. 

  2667.    SWIG_typemap_lang("python");
    2668. 

  2668. }
    2669. 

  2669. </pre>
    2670. 

  2670. </div>
    2671. 

  2671. 

  2672. <p>
    2673. 

  2673. The above code does several things--it registers the name of the
    2674. 

  2674. language module with the core, it supplies some preprocessor macro definitions
    2675. 

  2675. for use in input files (so that they can determine the target language), and
    2676. 

  2676. it registers a start-up file.   In this case, the file <tt>python.swg</tt> will
    2677. 

  2677. be parsed before any part of the user-supplied input file.
    2678. 

  2678. </p>
    2679. 

  2679. 

  2680. <p>
    2681. 

  2681. Before proceeding any further, create a directory for your module in the SWIG
    2682. 

  2682. library (The <tt>Lib</tt> directory).   Now, create a configuration file in the
    2683. 

  2683. directory.  For example, <tt>python.swg</tt>.
    2684. 

  2684. </p>
    2685. 

  2685. 

  2686. <p>
    2687. 

  2687. Just to review, your language module should now consist of two files--
    2688. 

  2688. an implementation file <tt>python.cxx</tt> and a configuration file
    2689. 

  2689. <tt>python.swg</tt>.
    2690. 

  2690. </p>
    2691. 

  2691. 

  2692. <H3><a name="Extending_nn36"></a>35.10.5 Entry point to code generation</H3>
    2693. 

  2693. 

  2694. 

  2695. <p>
    2696. 

  2696. SWIG is a multi-pass compiler.  Once the <tt>main()</tt> method has
    2697. 

  2697. been invoked, the language module does not execute again until
    2698. 

  2698. preprocessing, parsing, and a variety of semantic analysis passes have
    2699. 

  2699. been performed.  When the core is ready to start generating wrappers,
    2700. 

  2700. it invokes the <tt>top()</tt> method of your language class.  The
    2701. 

  2701. argument to <tt>top</tt> is a single parse tree node that corresponds to
    2702. 

  2702. the top of the entire parse tree.
    2703. 

  2703. </p>
    2704. 

  2704. 

  2705. <p>
    2706. 

  2706. To get the code generation process started, the <tt>top()</tt> procedure needs
    2707. 

  2707. to do several things:
    2708. 

  2708. </p>
    2709. 

  2709. 

  2710. <ul>
    2711. 

  2711. <li>Initialize the wrapper code output.
    2712. 

  2712. <li>Set the module name.
    2713. 

  2713. <li>Emit common initialization code.
    2714. 

  2714. <li>Emit code for all of the child nodes.
    2715. 

  2715. <li>Finalize the wrapper module and cleanup.
    2716. 

  2716. </ul>
    2717. 

  2717. 

  2718. <p>
    2719. 

  2719. An outline of <tt>top()</tt> might be as follows:
    2720. 

  2720. </p>
    2721. 

  2721. 

  2722. <div class="code">
    2723. 

  2723. <pre>
    2724. 

  2724. int Python::top(Node *n) {
    2725. 

  2725. 

  2726.    /* Get the module name */
    2727. 

  2727.    String *module = Getattr(n,"name");
    2728. 

  2728. 

  2729.    /* Get the output file name */
    2730. 

  2730.    String *outfile = Getattr(n,"outfile");
    2731. 

  2731. 

  2732.    /* Initialize I/O (see next section) */
    2733. 

  2733.    ...
    2734. 

  2734. 

  2735.    /* Output module initialization code */
    2736. 

  2736.    ...
    2737. 

  2737. 

  2738.    /* Emit code for children */
    2739. 

  2739.    Language::top(n);
    2740. 

  2740. 

  2741.    ...
    2742. 

  2742.    /* Cleanup files */
    2743. 

  2743.    ...
    2744. 

  2744. 

  2745.    return SWIG_OK;
    2746. 

  2746. }
    2747. 

  2747. </pre>
    2748. 

  2748. </div>
    2749. 

  2749. 

  2750. <H3><a name="Extending_nn37"></a>35.10.6 Module I/O and wrapper skeleton</H3>
    2751. 

  2751. 

  2752. 

  2753. <!-- please report bugs in this section to mgossage -->
    2754. 

  2754. 

  2755. 

  2756. <p>
    2757. 

  2757. Within SWIG wrappers, there are four main sections. These are (in order)
    2758. 

  2758. </p>
    2759. 

  2759. 

  2760. <ul>
    2761. 

  2761. <li>runtime: This section has most of the common SWIG runtime code
    2762. 

  2762. <li>header: This section holds declarations and inclusions from the .i file
    2763. 

  2763. <li>wrapper: This section holds all the wrappering code
    2764. 

  2764. <li>init: This section holds the module initalisation function
    2765. 

  2765. (the entry point for the interpreter)
    2766. 

  2766. </ul>
    2767. 

  2767. <p>
    2768. 

  2768. Different parts of the SWIG code will fill different sections,
    2769. 

  2769. then upon completion of the wrappering all the sections will be saved
    2770. 

  2770. to the wrapper file.
    2771. 

  2771. </p>
    2772. 

  2772. <p>
    2773. 

  2773. To perform this will require several additions to the code in various places,
    2774. 

  2774. such as:
    2775. 

  2775. </p>
    2776. 

  2776. 

  2777. <div class="code">
    2778. 

  2778. <pre>
    2779. 

  2779. class PYTHON : public Language {
    2780. 

  2780. protected:
    2781. 

  2781.    /* General DOH objects used for holding the strings */
    2782. 

  2782.    File *f_begin;
    2783. 

  2783.    File *f_runtime;
    2784. 

  2784.    File *f_header;
    2785. 

  2785.    File *f_wrappers;
    2786. 

  2786.    File *f_init;
    2787. 

  2787. 

  2788. public:
    2789. 

  2789.    ...
    2790. 

  2790. 

  2791. };
    2792. 

  2792. 

  2793. int Python::top(Node *n) {
    2794. 

  2794. 

  2795.    ...
    2796. 

  2796. 

  2797.    /* Initialize I/O */
    2798. 

  2798.    f_begin = NewFile(outfile, "w", SWIG_output_files());
    2799. 

  2799.    if (!f_begin) {
    2800. 

  2800.       FileErrorDisplay(outfile);
    2801. 

  2801.       SWIG_exit(EXIT_FAILURE);
    2802. 

  2802.    }
    2803. 

  2803.    f_runtime = NewString("");
    2804. 

  2804.    f_init = NewString("");
    2805. 

  2805.    f_header = NewString("");
    2806. 

  2806.    f_wrappers = NewString("");
    2807. 

  2807. 

  2808.    /* Register file targets with the SWIG file handler */
    2809. 

  2809.    Swig_register_filebyname("begin", f_begin);
    2810. 

  2810.    Swig_register_filebyname("header", f_header);
    2811. 

  2811.    Swig_register_filebyname("wrapper", f_wrappers);
    2812. 

  2812.    Swig_register_filebyname("runtime", f_runtime);
    2813. 

  2813.    Swig_register_filebyname("init", f_init);
    2814. 

  2814. 

  2815.    /* Output module initialization code */
    2816. 

  2816.    Swig_banner(f_begin);
    2817. 

  2817.    ...
    2818. 

  2818. 

  2819.    /* Emit code for children */
    2820. 

  2820.    Language::top(n);
    2821. 

  2821. 

  2822.    ...
    2823. 

  2823.    /* Write all to the file */
    2824. 

  2824.    Dump(f_runtime, f_begin);
    2825. 

  2825.    Dump(f_header, f_begin);
    2826. 

  2826.    Dump(f_wrappers, f_begin);
    2827. 

  2827.    Wrapper_pretty_print(f_init, f_begin);
    2828. 

  2828. 

  2829.    /* Cleanup files */
    2830. 

  2830.    Delete(f_runtime);
    2831. 

  2831.    Delete(f_header);
    2832. 

  2832.    Delete(f_wrappers);
    2833. 

  2833.    Delete(f_init);
    2834. 

  2834.    Close(f_begin);
    2835. 

  2835.    Delete(f_begin);
    2836. 

  2836. 

  2837.    return SWIG_OK;
    2838. 

  2838. }
    2839. 

  2839. </pre>
    2840. 

  2840. </div>
    2841. 

  2841. 

  2842. <p>
    2843. 

  2843. Using this to process a file will generate a wrapper file, however the
    2844. 

  2844. wrapper will only consist of the common SWIG code as well as any inline
    2845. 

  2845. code which was written in the .i file. It does not contain any wrappers for
    2846. 

  2846. any of the functions or classes.
    2847. 

  2847. </p>
    2848. 

  2848. 

  2849. <p>
    2850. 

  2850. The code to generate the wrappers are the various member functions, which
    2851. 

  2851. currently have not been touched. We will look at <tt>functionWrapper()</tt> as this
    2852. 

  2852. is the most commonly used function. In fact many of the other wrapper routines
    2853. 

  2853. will call this to do their work.
    2854. 

  2854. </p>
    2855. 

  2855. <p>
    2856. 

  2856. A simple modification to write some basic details to the wrapper looks like this:
    2857. 

  2857. </p>
    2858. 

  2858. 

  2859. <div class="code">
    2860. 

  2860. <pre>
    2861. 

  2861. int Python::functionWrapper(Node *n) {
    2862. 

  2862.   /* Get some useful attributes of this function */
    2863. 

  2863.   String   *name   = Getattr(n,"sym:name");
    2864. 

  2864.   SwigType *type   = Getattr(n,"type");
    2865. 

  2865.   ParmList *parms  = Getattr(n,"parms");
    2866. 

  2866.   String   *parmstr= ParmList_str_defaultargs(parms); // to string
    2867. 

  2867.   String   *func   = SwigType_str(type, NewStringf("%s(%s)", name, parmstr));
    2868. 

  2868.   String   *action = Getattr(n,"wrap:action");
    2869. 

  2869. 

  2870.   Printf(f_wrappers,"functionWrapper   : %s\n", func);
    2871. 

  2871.   Printf(f_wrappers,"           action : %s\n", action);
    2872. 

  2872.   return SWIG_OK;
    2873. 

  2873. }
    2874. 

  2874. </pre>
    2875. 

  2875. </div>
    2876. 

  2876. 

  2877. <p>
    2878. 

  2878. This will now produce some useful information within your wrapper file.
    2879. 

  2879. </p>
    2880. 

  2880. 

  2881. <div class="shell">
    2882. 

  2882. <pre>
    2883. 

  2883. functionWrapper   : void delete_Shape(Shape *self)
    2884. 

  2884.            action : delete arg1;
    2885. 

  2885. 

  2886. functionWrapper   : void Shape_x_set(Shape *self,double x)
    2887. 

  2887.            action : if (arg1) (arg1)-&gt;x = arg2;
    2888. 

  2888. 

  2889. functionWrapper   : double Shape_x_get(Shape *self)
    2890. 

  2890.            action : result = (double) ((arg1)-&gt;x);
    2891. 

  2891. 

  2892. functionWrapper   : void Shape_y_set(Shape *self,double y)
    2893. 

  2893.            action : if (arg1) (arg1)-&gt;y = arg2;
    2894. 

  2894. ...
    2895. 

  2895. </pre>
    2896. 

  2896. </div>
    2897. 

  2897. 

  2898. <H3><a name="Extending_nn38"></a>35.10.7 Low-level code generators</H3>
    2899. 

  2899. 

  2900. 

  2901. <!-- please report bugs in this section to mgossage -->
    2902. 

  2902. 

  2903. <p>
    2904. 

  2904. As ingenious as SWIG is, and despite all its capabilities and the power of
    2905. 

  2905. its parser, the Low-level code generation takes a lot of work to write
    2906. 

  2906. properly. Mainly because every language insists on its own manner of
    2907. 

  2907. interfacing to C/C++. To write the code generators you will need a good
    2908. 

  2908. understanding of how to manually write an interface to your chosen
    2909. 

  2909. language, so make sure you have your documentation handy.
    2910. 

  2910. </p>
    2911. 

  2911. <p>
    2912. 

  2912. At this point it is also probably a good idea to take a very simple file
    2913. 

  2913. (just one function), and try letting SWIG generate wrappers for many
    2914. 

  2914. different languages. Take a look at all of the wrappers generated, and decide
    2915. 

  2915. which one looks closest to the language you are trying to wrap.
    2916. 

  2916. This may help you to decide which code to look at.
    2917. 

  2917. </p>
    2918. 

  2918. <p>
    2919. 

  2919. In general most language wrappers look a little like this:
    2920. 

  2920. </p>
    2921. 

  2921. <div class="code">
    2922. 

  2922. <pre>
    2923. 

  2923. /* wrapper for TYPE3 some_function(TYPE1,TYPE2); */
    2924. 

  2924. RETURN_TYPE _wrap_some_function(ARGS){
    2925. 

  2925.   TYPE1 arg1;
    2926. 

  2926.   TYPE2 arg2;
    2927. 

  2927.   TYPE3 result;
    2928. 

  2928. 

  2929.   if(ARG1 is not of TYPE1) goto fail;
    2930. 

  2930.   arg1=(convert ARG1);
    2931. 

  2931.   if(ARG2 is not of TYPE2) goto fail;
    2932. 

  2932.   arg2=(convert ARG2);
    2933. 

  2933. 

  2934.   result=some_function(arg1,arg2);
    2935. 

  2935. 

  2936.   convert 'result' to whatever the language wants;
    2937. 

  2937. 

  2938.   do any tidy up;
    2939. 

  2939. 

  2940.   return ALL_OK;
    2941. 

  2941. 

  2942.   fail:
    2943. 

  2943.   do any tidy up;
    2944. 

  2944.   return ERROR;
    2945. 

  2945. }
    2946. 

  2946. </pre>
    2947. 

  2947. </div>
    2948. 

  2948. 

  2949. <p>
    2950. 

  2950. Yes, it is rather vague and not very clear. But each language works differently
    2951. 

  2951. so this will have to do for now.
    2952. 

  2952. </p>
    2953. 

  2953. <p>
    2954. 

  2954. Tackling this problem will be done in two stages:
    2955. 

  2955. </p>
    2956. 

  2956. <ul>
    2957. 

  2957. <li>The skeleton: the function wrapper, and call, but without the conversion
    2958. 

  2958. <li>The conversion: converting the arguments to-from what the language wants
    2959. 

  2959. </ul>
    2960. 

  2960. <p>
    2961. 

  2961. The first step will be done in the code, the second will be done in typemaps.
    2962. 

  2962. </p>
    2963. 

  2963. <p>
    2964. 

  2964. Our first step will be to write the code for <tt>functionWrapper()</tt>. What is
    2965. 

  2965. shown below is <b>NOT</b> the solution, merely a step in the right direction.
    2966. 

  2966. There are a lot of issues to address.
    2967. 

  2967. </p>
    2968. 

  2968. <ul>
    2969. 

  2969. <li>Variable length and default parameters
    2970. 

  2970. <li>Typechecking and number of argument checks
    2971. 

  2971. <li>Overloaded functions
    2972. 

  2972. <li>Inout and Output only arguments
    2973. 

  2973. </ul>
    2974. 

  2974. <div class="code">
    2975. 

  2975. <pre>
    2976. 

  2976. virtual int functionWrapper(Node *n) {
    2977. 

  2977.   /* get useful atributes */
    2978. 

  2978.   String   *name   = Getattr(n,"sym:name");
    2979. 

  2979.   SwigType *type   = Getattr(n,"type");
    2980. 

  2980.   ParmList *parms  = Getattr(n,"parms");
    2981. 

  2981.   ...
    2982. 

  2982. 

  2983.   /* create the wrapper object */
    2984. 

  2984.   Wrapper *wrapper = NewWrapper();
    2985. 

  2985. 

  2986.   /* create the functions wrappered name */
    2987. 

  2987.   String *wname = Swig_name_wrapper(iname);
    2988. 

  2988. 

  2989.   /* deal with overloading */
    2990. 

  2990.   ....
    2991. 

  2991. 

  2992.   /* write the wrapper function definition */
    2993. 

  2993.   Printv(wrapper-&gt;def,"RETURN_TYPE ", wname, "(ARGS) {",NIL);
    2994. 

  2994. 

  2995.   /* if any additional local variable needed, add them now */
    2996. 

  2996.   ...
    2997. 

  2997. 

  2998.   /* write the list of locals/arguments required */
    2999. 

  2999.   emit_args(type, parms, wrapper);
    3000. 

  3000. 

  3001.   /* check arguments */
    3002. 

  3002.   ...
    3003. 

  3003. 

  3004.   /* write typemaps(in) */
    3005. 

  3005.   ....
    3006. 

  3006. 

  3007.   /* write constriants */
    3008. 

  3008.   ....
    3009. 

  3009. 

  3010.   /* Emit the function call */
    3011. 

  3011.   emit_action(n,wrapper);
    3012. 

  3012. 

  3013.   /* return value if necessary  */
    3014. 

  3014.   ....
    3015. 

  3015. 

  3016.   /* write typemaps(out) */
    3017. 

  3017.   ....
    3018. 

  3018. 

  3019.   /* add cleanup code */
    3020. 

  3020.   ....
    3021. 

  3021. 

  3022.   /* Close the function(ok) */
    3023. 

  3023.   Printv(wrapper-&gt;code, "return ALL_OK;\n", NIL);
    3024. 

  3024. 

  3025.   /* add the failure cleanup code */
    3026. 

  3026.   ...
    3027. 

  3027. 

  3028.   /* Close the function(error) */
    3029. 

  3029.   Printv(wrapper-&gt;code, "return ERROR;\n", "}\n", NIL);
    3030. 

  3030. 

  3031.   /* final substititions if applicable */
    3032. 

  3032.   ...
    3033. 

  3033. 

  3034.   /* Dump the function out */
    3035. 

  3035.   Wrapper_print(wrapper,f_wrappers);
    3036. 

  3036. 

  3037.   /* tidy up */
    3038. 

  3038.   Delete(wname);
    3039. 

  3039.   DelWrapper(wrapper);
    3040. 

  3040. 

  3041.   return SWIG_OK;
    3042. 

  3042. }
    3043. 

  3043. </pre>
    3044. 

  3044. </div>
    3045. 

  3045. 

  3046. <p>
    3047. 

  3047. Executing this code will produce wrappers which have our basic skeleton
    3048. 

  3048. but without the typemaps, there is still work to do.
    3049. 

  3049. </p>
    3050. 

  3050. 

  3051. 

  3052. <H3><a name="Extending_nn39"></a>35.10.8 Configuration files</H3>
    3053. 

  3053. 

  3054. 

  3055. <!-- please report bugs in this section to ttn -->
    3056. 

  3056. 

  3057. <p>
    3058. 

  3058. At the time of this writing, SWIG supports nearly twenty languages,
    3059. 

  3059. which means that for continued sanity in maintaining the configuration
    3060. 

  3060. files, the language modules need to follow some conventions.  These are
    3061. 

  3061. outlined here along with the admission that, yes it is ok to violate
    3062. 

  3062. these conventions in minor ways, as long as you know where to apply the
    3063. 

  3063. proper kludge to keep the overall system regular and running.
    3064. 

  3064. Engineering is the art of compromise, see...
    3065. 

  3065. </p>
    3066. 

  3066. 

  3067. <p>
    3068. 

  3068. Much of the maintenance regularity depends on choosing a suitable
    3069. 

  3069. nickname for your language module (and then using it in a controlled
    3070. 

  3070. way).  Nicknames should be all lower case letters with an optional
    3071. 

  3071. numeric suffix (no underscores, no dashes, no spaces).  Some examples
    3072. 

  3072. are: <TT>foo</TT>, <TT>bar</TT>, <TT>qux99</TT>.
    3073. 

  3073. </p>
    3074. 

  3074. 

  3075. <p>
    3076. 

  3076. The numeric suffix variant, as in the last example, is somewhat tricky
    3077. 

  3077. to work with because sometimes people expect to refer to the language
    3078. 

  3078. without this number but sometimes that number is extremely relevant
    3079. 

  3079. (especially when it corresponds to language implementation versions with
    3080. 

  3080. incompatible interfaces).  New language modules that unavoidably require
    3081. 

  3081. a numeric suffix in their nickname should include that number in all
    3082. 

  3082. uses, or be prepared to kludge.
    3083. 

  3083. </p>
    3084. 

  3084. 

  3085. <p>
    3086. 

  3086. The nickname is used in four places:
    3087. 

  3087. </p>
    3088. 

  3088. 

  3089. <TABLE summary="nickname table">
    3090. 

  3090. <TR><TD><B>usage</B></TD><TD><B>transform</B></TD></TR>
    3091. 

  3091. <TR><TD>"skip" tag</TD><TD>(none)</TD></TR>
    3092. 

  3092. <TR><TD>Examples/ subdir name</TD><TD>(none)</TD></TR>
    3093. 

  3093. <TR><TD>Examples/GIFPlot/ subdir name</TD>
    3094. 

  3094.     <TD>capitalize (upcase first letter)</TD></TR>
    3095. 

  3095. <TR><TD>Examples/test-suite/ subdir name</TD><TD>(none)</TD></TR>
    3096. 

  3096. <!-- add more uses here (remember to adjust header) -->
    3097. 

  3097. </TABLE>
    3098. 

  3098. 

  3099. <p>
    3100. 

  3100. As you can see, most usages are direct.
    3101. 

  3101. </p>
    3102. 

  3102. 

  3103. <dl>
    3104. 

  3104. 

  3105. <dt> <b>configure.in</b>
    3106. 

  3106. <dd> This file is processed by
    3107. 

  3107. 

  3108. <p>
    3109. 

  3109. <A HREF="http://www.gnu.org/software/autoconf/">autoconf</A>
    3110. 

  3110. to generate the <TT>configure</TT> script.  This is where you
    3111. 

  3111. need to add shell script fragments and autoconf macros to detect the
    3112. 

  3112. presence of whatever development support your language module requires,
    3113. 

  3113. typically directories where headers and libraries can be found, and/or
    3114. 

  3114. utility programs useful for integrating the generated wrapper code.
    3115. 

  3115. </p>
    3116. 

  3116. 

  3117. <p>
    3118. 

  3118. Use the <TT>AC_ARG_WITH</TT>, <TT>AC_MSG_CHECKING</TT>, <TT>AC_SUBST</TT>
    3119. 

  3119. macros and so forth (see other languages for examples).  Avoid using the
    3120. 

  3120. <TT>[</TT> and <TT>]</TT> character in shell script fragments.  The
    3121. 

  3121. variable names passed to <TT>AC_SUBST</TT> should begin with the nickname,
    3122. 

  3122. entirely upcased.
    3123. 

  3123. </p>
    3124. 

  3124. 

  3125. <p>
    3126. 

  3126. At the end of the new section is the place to put the aforementioned
    3127. 

  3127. nickname kludges (should they be needed).  See Perl5 for
    3128. 

  3128. examples of what to do.  [If this is still unclear after you've read
    3129. 

  3129. the code, ping me and I'll expand on this further.  --ttn]
    3130. 

  3130. </p>
    3131. 

  3131. 

  3132. <dt> <b>Makefile.in</b>
    3133. 

  3133. <dd>
    3134. 

  3134. 

  3135. <p>
    3136. 

  3136. Some of the variables AC_SUBSTituted are essential to the
    3137. 

  3137. support of your language module.  Fashion these into a shell script
    3138. 

  3138. "test" clause and assign that to a skip tag using "-z" and "-o":
    3139. 

  3139. </p>
    3140. 

  3140. 

  3141. <div class="code"><tt>
    3142. 

  3142. skip-qux99 = [ -z "@QUX99INCLUDE@" -o -z "@QUX99LIBS" ]
    3143. 

  3143. </tt></div>
    3144. 

  3144. 

  3145. <p>
    3146. 

  3146. This means if those vars should ever be empty, qux99 support should
    3147. 

  3147. be considered absent and so it would be a good idea to skip actions that
    3148. 

  3148. might rely on it.
    3149. 

  3149. </p>
    3150. 

  3150. 

  3151. <p>
    3152. 

  3152. Here is where you may also define an alias (but then you'll need to
    3153. 

  3153. kludge --- don't do this):
    3154. 

  3154. </p>
    3155. 

  3155. 

  3156. <div class="code"><tt>
    3157. 

  3157. skip-qux = $(skip-qux99)
    3158. 

  3158. </tt></div>
    3159. 

  3159. 

  3160. <p>
    3161. 

  3161. Lastly, you need to modify each of <TT>check-aliveness</TT>,
    3162. 

  3162. <TT>check-examples</TT>, <TT>check-test-suite</TT>,
    3163. 

  3163. <TT>check-gifplot</TT> (all targets) and <TT>lib-languages</TT> (var).
    3164. 

  3164. Use the nickname for these, not the alias.
    3165. 

  3165. Note that you can do this even before you have any tests or examples
    3166. 

  3166. set up; the Makefile rules do some sanity checking and skip around
    3167. 

  3167. these kinds of problems.
    3168. 

  3168. </p>
    3169. 

  3169. 

  3170. <dt> <b>Examples/Makefile.in</b>
    3171. 

  3171. <dd> Nothing special here; see comments at top the of this file
    3172. 

  3172. and look to the existing languages for examples.
    3173. 

  3173. 

  3174. <dt> <b>Examples/qux99/check.list</b>
    3175. 

  3175. <dd> Do <TT>cp ../python/check.list .</TT> and modify to taste.
    3176. 

  3176. One subdir per line.
    3177. 

  3177. 

  3178. <dt> <b>Examples/GIFPlot/Qux99/check.list</b>
    3179. 

  3179. <dd> Do <TT>cp ../Python/check.list .</TT> and modify to taste.
    3180. 

  3180. One subdir per line.
    3181. 

  3181. 

  3182. <dt> <b>Lib/qux99/extra-install.list</b>
    3183. 

  3183. <dd> If you add your language to the top-level Makefile.in var
    3184. 

  3184. <TT>lib-languages</TT>, then <TT>make install</TT> will install
    3185. 

  3185. all <TT>*.i</TT> and <TT>*.swg</TT> files from the language-specific
    3186. 

  3186. subdirectory of <TT>Lib</TT>.  Use (optional) file
    3187. 

  3187. <TT>extra-install.list</TT> in that directory to name
    3188. 

  3188. additional files to install (see ruby for example).
    3189. 

  3189. 

  3190. <dt> <b>Source/Modules/Makefile.am</b>
    3191. 

  3191. <dd> Add appropriate files to this Automake file. That's it!
    3192. 

    3193. 

  3193. <p>
    3194. 

  3194. When you have modified these files, please make sure that the new language module is completely
    3195. 

  3195. ignored if it is not installed and detected on a box, that is, <tt>make check-examples</tt> and <tt>make check-test-suite</tt>
    3196. 

  3196. politely displays the ignoring language message.
    3197. 

  3197. </p>
    3198. 

  3198. 

  3199. </dl>
    3200. 

  3200. 

  3201. 

  3202. <H3><a name="Extending_nn40"></a>35.10.9 Runtime support</H3>
    3203. 

  3203. 

  3204. 

  3205. <p>
    3206. 

  3206. Discuss the kinds of functions typically needed for SWIG runtime support (e.g.
    3207. 

  3207. <tt>SWIG_ConvertPtr()</tt> and <tt>SWIG_NewPointerObj()</tt>) and the names of
    3208. 

  3208. the SWIG files that implement those functions.
    3209. 

  3209. </p>
    3210. 

  3210. 

  3211. <H3><a name="Extending_nn41"></a>35.10.10 Standard library files</H3>
    3212. 

  3212. 

  3213. 

  3214. <p>
    3215. 

  3215. The standard library files that most languages supply keeps growing as SWIG matures.
    3216. 

  3216. The following are the minimum that are usually supported:
    3217. 

  3217. </p>
    3218. 

  3218. 

  3219. <ul>
    3220. 

  3220. <li> typemaps.i </li>
    3221. 

  3221. <li> std_string.i </li>
    3222. 

  3222. <li> std_vector.i </li>
    3223. 

  3223. <li> stl.i </li>
    3224. 

  3224. </ul>
    3225. 

  3225. 

  3226. <p>
    3227. 

  3227. Please copy these and modify for any new language.
    3228. 

  3228. </p>
    3229. 

  3229. 

  3230. <H3><a name="Extending_nn42"></a>35.10.11 User examples</H3>
    3231. 

  3231. 

  3232. 

  3233. <p>
    3234. 

  3234. Each of the language modules provides one or more examples. These examples
    3235. 

  3235. are used to demonstrate different features of the language module to SWIG
    3236. 

  3236. end-users, but you'll find that they're useful during development and testing
    3237. 

  3237. of your language module as well. You can use examples from the existing SWIG
    3238. 

  3238. language modules for inspiration.
    3239. 

  3239. </p>
    3240. 

  3240. 

  3241. <p>
    3242. 

  3242. Each example is self-contained and consists of (at least) a <tt>Makefile</tt>,
    3243. 

  3243. a SWIG interface file for the example module, and a 'runme' script that demonstrates
    3244. 

  3244. the functionality for that module. All of these files are stored in the same
    3245. 

  3245. subdirectory under the <tt>Examples/[lang]</tt> directory.
    3246. 

  3246. There are two classic examples which should be the first to convert to a new
    3247. 

  3247. language module. These are the "simple" C example and the "class" C++ example.
    3248. 

  3248. These can be found, for example for Python, in
    3249. 

  3249. <tt>Examples/python/simple</tt> and <tt>Examples/python/class</tt>.
    3250. 

  3250. </p>
    3251. 

  3251. 

  3252. <p>
    3253. 

  3253. By default, all of the examples are built and run when the user types
    3254. 

  3254. <tt>make check</tt>. To ensure that your examples are automatically run
    3255. 

  3255. during this process, see the section on <a href="#n37a">configuration
    3256. 

  3256. files</a>.
    3257. 

  3257. </p>
    3258. 

  3258. 

  3259. <H3><a name="Extending_test_suite"></a>35.10.12 Test driven development and the test-suite</H3>
    3260. 

  3260. 

  3261. 

  3262. <p>
    3263. 

  3263. A test driven development approach is central to the improvement and development of SWIG.
    3264. 

  3264. Most modifications to SWIG are accompanied by additional regression tests and checking all 
    3265. 

  3265. tests to ensure that no regressions have been introduced.
    3266. 

  3266. </p>
    3267. 

  3267. 

  3268. <p>
    3269. 

  3269. The regression testing is carried out by the SWIG <i>test-suite</i>.
    3270. 

  3270. The test-suite consists of numerous testcase interface files in the <tt>Examples/test-suite</tt> directory
    3271. 

  3271. as well as target language specific runtime tests in the <tt>Examples/test-suite/[lang]</tt> directory. 
    3272. 

  3272. When a testcase is run, it will execute the following steps for each testcase:
    3273. 

  3273. </p>
    3274. 

  3274. 

  3275. <ol>
    3276. 

  3276. <li>Execute SWIG passing it the testcase interface file.</li>
    3277. 

  3277. <li>Compile the resulting generated C/C++ code with either the C or C++ compiler into object files.</li>
    3278. 

  3278. <li>Link the object files into a dynamic library (dll/shared object).</li>
    3279. 

  3279. <li>Compile any generated and any runtime test target language code with the target language compiler, if the target language supports compilation. This step thus does not apply to the interpreted languages.</li>
    3280. 

  3280. <li>Execute a runtime test if one exists.</li>
    3281. 

  3281. </ol>
    3282. 

  3282. 

  3283. <p>
    3284. 

  3284. For example, the <i>ret_by_value</i> testcase consists of two components.
    3285. 

  3285. The first component is the <tt>Examples/test-suite/ret_by_value.i</tt> interface file.
    3286. 

  3286. The name of the SWIG module <b>must</b> always be the name of the testcase, so the <tt>ret_by_value.i</tt> interface file thus begins with: 
    3287. 

  3287. </p>
    3288. 

  3288. 

  3289. <div class="code">
    3290. 

  3290. <pre>
    3291. 

  3291. %module ret_by_value
    3292. 

  3292. </pre>
    3293. 

  3293. </div>
    3294. 

  3294. 

  3295. <p>
    3296. 

  3296. The testcase code will then follow the module declaration,
    3297. 

  3297. usually within a <tt>%inline %{ ... %}</tt> section for the majority of the tests.
    3298. 

  3298. </p>
    3299. 

  3299. 

  3300. <p>
    3301. 

  3301. The second component is the optional runtime tests.
    3302. 

  3302. Any runtime tests are named using the following convention: <tt>[testcase]_runme.[ext]</tt>, 
    3303. 

  3303. where <tt>[testcase]</tt> is the testcase name and <tt>[ext]</tt> is the normal extension for the target language file.
    3304. 

  3304. In this case, the Java and Python target languages implement a runtime test, so their files are respectively, 
    3305. 

  3305. <tt>Examples/test-suite/java/ret_by_value_runme.java</tt> and 
    3306. 

  3306. <tt>Examples/test-suite/python/ret_by_value_runme.py</tt>.
    3307. 

  3307. </p>
    3308. 

  3308. 

  3309. <p>
    3310. 

  3310. The goal of the test-suite is to test as much as possible in a <b>silent</b> manner.
    3311. 

  3311. This way any SWIG or compiler errors or warnings are easily visible.
    3312. 

  3312. Should there be any warnings, changes must be made to either fix them (preferably) or suppress them.
    3313. 

  3313. Compilation or runtime errors result in a testcase failure and will be immediately visible.
    3314. 

  3314. It is therefore essential that the runtime tests are written in a manner that displays nothing to stdout/stderr on success 
    3315. 

  3315. but error/exception out with an error message on stderr on failure.
    3316. 

  3316. </p>
    3317. 

  3317. 

  3318. <H4><a name="Extending_running_test_suite"></a>35.10.12.1 Running the test-suite</H4>
    3319. 

  3319. 

  3320. 

  3321. <p>
    3322. 

  3322. In order for the test-suite to work for a particular target language, the language must be correctly detected
    3323. 

  3323. and configured during the configure stage so that the correct Makefiles are generated.
    3324. 

  3324. Most development occurs on Linux, so usually it is a matter of installing the development packages for the target language
    3325. 

  3325. and simply configuring as outlined <a href="#Extending_starting_out">earlier</a>.
    3326. 

  3326. </p>
    3327. 

  3327. 

  3328. <p>
    3329. 

  3329. If when running the test-suite commands that follow, you get a message that the test was skipped, it indicates that the
    3330. 

  3330. configure stage is missing information in order to compile and run everything for that language.
    3331. 

  3331. </p>
    3332. 

  3332. 

  3333. <p>
    3334. 

  3334. The test-suite can be run in a number of ways.
    3335. 

  3335. The first group of commands are for running multiple testcases in one run and should be executed in the top level directory.
    3336. 

  3336. To run the entire test-suite (can take a long time):
    3337. 

  3337. </p>
    3338. 

  3338. 

  3339. <div class="shell"><pre>
    3340. 

  3340. make -k check-test-suite
    3341. 

  3341. </pre></div>
    3342. 

  3342. 

  3343. <p>
    3344. 

  3344. To run the test-suite just for target language [lang], replace [lang] with one of csharp, java, perl5, python, ruby, tcl etc:
    3345. 

  3345. </p>
    3346. 

  3346. 

  3347. <div class="shell"><pre>
    3348. 

  3348. make check-[lang]-test-suite
    3349. 

  3349. </pre></div>
    3350. 

  3350. 

  3351. <p>
    3352. 

  3352. Note that if a runtime test is available, a message "(with run test)" is displayed when run. For example:
    3353. 

  3353. </p>
    3354. 

  3354. 

  3355. <div class="shell"><pre>
    3356. 

  3356. $ make check-python-test-suite
    3357. 

  3357. checking python test-suite
    3358. 

  3358. checking testcase argcargvtest (with run test) under python
    3359. 

  3359. checking testcase python_autodoc under python
    3360. 

  3360. checking testcase python_append (with run test) under python
    3361. 

  3361. checking testcase callback (with run test) under python
    3362. 

  3362. </pre></div>
    3363. 

  3363. 

  3364. <p>
    3365. 

  3365. The files generated on a previous run can be deleted using the clean targets, either the whole test-suite or for a particular language:
    3366. 

  3366. </p>
    3367. 

  3367. 

  3368. <div class="shell"><pre>
    3369. 

  3369. make clean-test-suite
    3370. 

  3370. make clean-[lang]-test-suite
    3371. 

  3371. </pre></div>
    3372. 

  3372. 

  3373. <p>
    3374. 

  3374. The test-suite can be run in a <i>partialcheck</i> mode where just SWIG is executed, that is, the compile, 
    3375. 

  3375. link and running of the testcases is not performed.
    3376. 

  3376. Note that the partialcheck does not require the target language to be correctly configured and detected and unlike the other test-suite make targets, is never skipped. Once again, either all the languages can be executed or just a chosen language:
    3377. 

  3377. </p>
    3378. 

  3378. 

  3379. <div class="shell"><pre>
    3380. 

  3380. make partialcheck-test-suite
    3381. 

  3381. make partialcheck-[lang]-test-suite
    3382. 

  3382. </pre></div>
    3383. 

  3383. 

  3384. <p>
    3385. 

  3385. If your computer has more than one CPU, you are strongly advised to use parallel make to speed up the execution speed. 
    3386. 

  3386. This can be done with any of the make targets that execute more than one testcase.
    3387. 

  3387. For example, a dual core processor can efficiently use 2 parallel jobs:
    3388. 

  3388. </p>
    3389. 

  3389. 

  3390. <div class="shell"><pre>
    3391. 

  3391. make -j2 check-test-suite
    3392. 

  3392. make -j2 check-python-test-suite
    3393. 

  3393. make -j2 partialcheck-java-test-suite
    3394. 

  3394. </pre></div>
    3395. 

  3395. 

  3396. <p>
    3397. 

  3397. The second group of commands are for running individual testcases and should be executed in the appropriate
    3398. 

  3398. target language directory, <tt>Examples/test-suite/[lang]</tt>.
    3399. 

  3399. Testcases can contain either C or C++ code and when one is written, a decision must be made as to which of these input
    3400. 

  3400. languages is to be used.
    3401. 

  3401. Replace <tt>[testcase]</tt> in the commands below with the name of the testcase.
    3402. 

  3402. </p>
    3403. 

  3403. 

  3404. <p>
    3405. 

  3405. For a C language testcase, add the testcase under the C_TEST_CASES list in <tt>Examples/test-suite/common.mk</tt> and 
    3406. 

  3406. execute individually as:
    3407. 

  3407. </p>
    3408. 

  3408. <div class="shell"><pre>
    3409. 

  3409. make -s [testcase].ctest
    3410. 

  3410. </pre></div>
    3411. 

  3411. 

  3412. <p>
    3413. 

  3413. For a C++ language testcase, add the testcase under the CPP_TEST_CASES list in <tt>Examples/test-suite/common.mk</tt> and 
    3414. 

  3414. execute individually as:
    3415. 

  3415. </p>
    3416. 

  3416. <div class="shell"><pre>
    3417. 

  3417. make -s [testcase].cpptest
    3418. 

  3418. </pre></div>
    3419. 

  3419. 

  3420. <p>
    3421. 

  3421. A third category of tests are C++ language testcases testing multiple modules (the %import directive).
    3422. 

  3422. These require more than one shared library (dll/shared object) to be built and so are separated out from the normal C++ testcases.
    3423. 

  3423. Add the testcase under the MULTI_CPP_TEST_CASES list in <tt>Examples/test-suite/common.mk</tt> and 
    3424. 

  3424. execute individually as:
    3425. 

  3425. </p>
    3426. 

  3426. <div class="shell"><pre>
    3427. 

  3427. make -s [testcase].multicpptest
    3428. 

  3428. </pre></div>
    3429. 

  3429. 

  3430. <p>
    3431. 

  3431. To delete the generated files, execute:
    3432. 

  3432. </p>
    3433. 

  3433. <div class="shell"><pre>
    3434. 

  3434. make -s [testcase].clean
    3435. 

  3435. </pre></div>
    3436. 

  3436. 

  3437. <p>
    3438. 

  3438. If you would like to see the exact commands being executed, drop the -s option:
    3439. 

  3439. </p>
    3440. 

  3440. <div class="shell"><pre>
    3441. 

  3441. make [testcase].ctest
    3442. 

  3442. make [testcase].cpptest
    3443. 

  3443. make [testcase].multicpptest
    3444. 

  3444. </pre></div>
    3445. 

  3445. 

  3446. <p>
    3447. 

  3447. Some real examples of each:
    3448. 

  3448. </p>
    3449. 

  3449. <div class="shell"><pre>
    3450. 

  3450. make -s ret_by_value.clean
    3451. 

  3451. make -s ret_by_value.ctest
    3452. 

  3452. make -s bools.cpptest
    3453. 

  3453. make -s imports.multicpptest
    3454. 

  3454. </pre></div>
    3455. 

  3455. 

  3456. <p>
    3457. 

  3457. Advanced usage of the test-suite facilitates running tools on some of the five stages.
    3458. 

  3458. The make variables <tt>SWIGTOOL</tt> and <tt>RUNTOOL</tt> are used to specify a tool to respectively, invoke SWIG 
    3459. 

  3459. and the execution of the runtime test.
    3460. 

  3460. You are advised to view the <tt>Examples/test-suite/common.mk</tt> file for details but for a short summary,
    3461. 

  3461. the classic usage is to use <a href="http://valgrind.org/">Valgrind</a> for memory checking.
    3462. 

  3462. For example, checking for memory leaks when running the runtime test in the target language interpreter:
    3463. 

  3463. </p>
    3464. 

  3464. 

  3465. <div class="shell"><pre>
    3466. 

  3466. make ret_by_value.ctest RUNTOOL="valgrind --leak-check=full"
    3467. 

  3467. </pre></div>
    3468. 

  3468. 

  3469. <p>
    3470. 

  3470. This will probably make more sense if you look at the output of the above as it will show the exact commands being executed.
    3471. 

  3471. SWIG can be analyzed for bad memory accesses using:
    3472. 

  3472. </p>
    3473. 

  3473. 

  3474. <div class="shell"><pre>
    3475. 

  3475. make ret_by_value.ctest SWIGTOOL="valgrind --tool=memcheck --trace-children=yes"
    3476. 

  3476. </pre></div>
    3477. 

  3477. 

  3478. <H3><a name="Extending_nn43"></a>35.10.13 Documentation</H3>
    3479. 

  3479. 

  3480. 

  3481. <p>
    3482. 

  3482. Don't forget to write end-user documentation for your language module. Currently,
    3483. 

  3483. each language module has a dedicated chapter 
    3484. 

  3484. You shouldn't rehash things that are already covered in sufficient
    3485. 

  3485. detail in the <a href="SWIG.html#SWIG">SWIG Basics</a> and <a href="SWIGPlus.html#SWIGPlus">SWIG
    3486. 

  3486. and C++</a> chapters. There is no fixed format for <em>what</em>, exactly, you should
    3487. 

  3487. document about your language module, but you'll obviously want to cover issues that
    3488. 

  3488. are unique to your language.
    3489. 

  3489. </p>
    3490. 

  3490. 

  3491. <p>
    3492. 

  3492. Some topics that you'll want to be sure to address include:
    3493. 

  3493. </p>
    3494. 

  3494. 

  3495. <ul>
    3496. 

  3496. <li> Command line options unique to your language module.
    3497. 

  3497. <li> Non-obvious mappings between C/C++ and target language concepts.
    3498. 

  3498.      For example, if your target language provides a single floating
    3499. 

  3499.      point type, it should be no big surprise to find that C/C++
    3500. 

  3500.      <tt>float</tt> and <tt>double</tt> types are mapped to it. On the other
    3501. 

  3501.      hand, if your target language doesn't provide support for "classes"
    3502. 

  3502.      or something similar, you'd want to discuss how C++ classes are handled.
    3503. 

  3503. <li> How to compile the SWIG-generated wrapper code into shared libraries
    3504. 

  3504.      that can actually be used. For some languages, there are well-defined
    3505. 

  3505.      procedures for doing this, but for others it's an ad hoc process.
    3506. 

  3506.      Provide as much detail as appropriate, and links to other resources
    3507. 

  3507.      if available.
    3508. 

  3508. </ul>
    3509. 

  3509. 

  3510. <H3><a name="Extending_prerequisites"></a>35.10.14 Prerequisites for adding a new language module to the SWIG distribution</H3>
    3511. 

  3511. 

  3512. 

  3513. <p>
    3514. 

  3514. If you wish for a new language module to be distributed with SWIG,
    3515. 

  3515. which we encourage for all popular languages, there are a few requirements.
    3516. 

  3516. While we appreciate that getting all aspects of a new language working
    3517. 

  3517. won't happen at the outset, there are a set of minimum requirements before
    3518. 

  3518. a module can be committed into the SVN repository for distribution with future
    3519. 

  3519. versions of SWIG. The following are really a summary of this whole section with
    3520. 

  3520. details being outlined earlier on.
    3521. 

  3521. </p>
    3522. 

  3522. 

  3523. <ol>
    3524. 

  3524.   <li>
    3525. 

  3525.   Demonstrate basic C code working by porting the "simple" example including
    3526. 

  3526.   a runtime test, see for example <tt>Examples/python/simple</tt>.
    3527. 

  3527.   </li>
    3528. 

  3528.   <li>
    3529. 

  3529.   Demonstrate basic C++ code working by porting the "class" example including
    3530. 

  3530.   a runtime test, see for example <tt>Examples/python/class</tt>.
    3531. 

  3531.   </li>
    3532. 

  3532.   <li>
    3533. 

  3533.   Modify <tt>configure.in</tt>, <tt>Makefile.in</tt> and <tt>Examples/Makefile.in</tt> to run
    3534. 

  3534.   these examples. Please make sure that if the new language is not
    3535. 

  3535.   installed properly on a box, <tt>make -k check</tt> should still work by
    3536. 

  3536.   skipping the tests and examples for the new language module.
    3537. 

  3537.   </li>
    3538. 

  3538.   <li>
    3539. 

  3539.   Get the test-suite running for the new language (<tt>make check-[lang]-test-suite</tt>).
    3540. 

  3540.   While the test-suite tests many corner cases,
    3541. 

  3541.   we'd expect the majority of it to work by compiling the generated code
    3542. 

  3542.   correctly as most of the corner cases are covered in the SWIG core. Get
    3543. 

  3543.   at least one C and one C++ runtime test running in the test-suite.
    3544. 

  3544.   </li>
    3545. 

  3545.   <li>
    3546. 

  3546.   Provide a chapter in the html documentation on the basics of using
    3547. 

  3547.   the language module.
    3548. 

  3548.   </li>
    3549. 

  3549.   <li>
    3550. 

  3550.   Ensure your source code is formatted according to the <a href="#Extending_coding_style_guidelines">coding style guidelines</a>.
    3551. 

  3551.   </li>
    3552. 

  3552.   <li>
    3553. 

  3553.   Finally, email the SWIG developers with a patch and a demonstration of
    3554. 

  3554.   commitment to maintaining the language module,
    3555. 

  3555.   certainly in the short term and ideally long term.
    3556. 

  3556.   </li>
    3557. 

  3557. </ol>
    3558. 

  3558. 

  3559. <p>
    3560. 

  3560. Once accepted into SVN, development efforts should concentrate on
    3561. 

  3561. getting the entire test-suite to work with plenty of runtime tests.
    3562. 

  3562. Runtime tests should be for existing testcases and new test cases 
    3563. 

  3563. should be added should there be an area not already covered by 
    3564. 

  3564. the existing tests.
    3565. 

  3565. </p>
    3566. 

  3566. 

  3567. <H3><a name="Extending_coding_style_guidelines"></a>35.10.15 Coding style guidelines</H3>
    3568. 

  3568. 

  3569. 

  3570. <p>
    3571. 

  3571. The coding guidelines for the C/C++ source code are pretty much K&amp;R C style.
    3572. 

  3572. The style can be inferred from the existing code base and is
    3573. 

  3573. largely dictated by the <tt>indent</tt> code beautifier tool set to K&amp;R style.
    3574. 

  3574. The code can formatted using the make targets in the Source directory.
    3575. 

  3575. Below is an example of how to format the emit.cxx file:
    3576. 

  3576. </p>
    3577. 

  3577. 

  3578. <blockquote>
    3579. 

  3579. <pre>
    3580. 

  3580. $ cd Source
    3581. 

  3581. $ make beautify-file INDENTFILE=Modules/emit.cxx
    3582. 

  3582. </pre>
    3583. 

  3583. </blockquote>
    3584. 

  3584. 

  3585. <p>
    3586. 

  3586. Of particular note is indentation is set to 2 spaces and a tab is used instead of 8 spaces.
    3587. 

  3587. The generated C/C++ code should also follow this style as close as possible. However, tabs
    3588. 

  3588. should be avoided as unlike the SWIG developers, users will never have consistent tab settings.
    3589. 

  3589. </p>
    3590. 

  3590. 

  3591. <H2><a name="Extending_debugging_options"></a>35.11 Debugging Options</H2>
    3592. 

  3592. 

  3593. 

  3594. <p>
    3595. 

  3595. There are various command line options which can aid debugging a SWIG interface as well as debugging the development of a language module. These are as follows:
    3596. 

  3596. </p>
    3597. 

  3597. 

  3598. <div class="shell"><pre>
    3599. 

  3599. -debug-classes    - Display information about the classes found in the interface
    3600. 

  3600. -debug-module &lt;n&gt; - Display module parse tree at stages 1-4, &lt;n&gt; is a csv list of stages
    3601. 

  3601. -debug-symtabs    - Display symbol tables information
    3602. 

  3602. -debug-symbols    - Display target language symbols in the symbol tables
    3603. 

  3603. -debug-csymbols   - Display C symbols in the symbol tables
    3604. 

  3604. -debug-tags       - Display information about the tags found in the interface
    3605. 

  3605. -debug-template   - Display information for debugging templates
    3606. 

  3606. -debug-top &lt;n&gt;    - Display entire parse tree at stages 1-4, &lt;n&gt; is a csv list of stages
    3607. 

  3607. -debug-typedef    - Display information about the types and typedefs in the interface
    3608. 

  3608. -debug-typemap    - Display information for debugging typemaps
    3609. 

  3609. </pre></div>
    3610. 

  3610. 

  3611. <p>
    3612. 

  3612. The complete list of command line options for SWIG are available by running <tt>swig -help</tt>.
    3613. 

  3613. </p>
    3614. 

  3614. 

  3615. <H2><a name="Extending_nn46"></a>35.12 Guide to parse tree nodes</H2>
    3616. 

  3616. 

  3617. 

  3618. <p>
    3619. 

  3619. This section describes the different parse tree nodes and their attributes.
    3620. 

  3620. </p>
    3621. 

  3621. 

  3622. <p>
    3623. 

  3623. <b>cdecl</b>
    3624. 

  3624. </p>
    3625. 

  3625. 

  3626. <p>
    3627. 

  3627. Describes general C declarations including variables, functions, and typedefs.
    3628. 

  3628. A declaration is parsed as "storage T D" where storage is a storage class, T is a base type,
    3629. 

  3629. and D is a declarator.
    3630. 

  3630. </p>
    3631. 

  3631. 

  3632. <div class="diagram">
    3633. 

  3633. <pre>
    3634. 

  3634. "name"          - Declarator name
    3635. 

  3635. "type"          - Base type T
    3636. 

  3636. "decl"          - Declarator type (abstract)
    3637. 

  3637. "storage"       - Storage class (static, extern, typedef, etc.)
    3638. 

  3638. "parms"         - Function parameters (if a function)
    3639. 

  3639. "code"          - Function body code (if supplied)
    3640. 

  3640. "value"         - Default value (if supplied)
    3641. 

  3641. </pre>
    3642. 

  3642. 

  3643. </div>
    3644. 

  3644. 

  3645. <p>
    3646. 

  3646. <b>constructor</b>
    3647. 

  3647. </p>
    3648. 

  3648. 

  3649. <p>
    3650. 

  3650. C++ constructor declaration.
    3651. 

  3651. </p>
    3652. 

  3652. 

  3653. <div class="diagram">
    3654. 

  3654. <pre>
    3655. 

  3655. "name"          - Name of constructor
    3656. 

  3656. "parms"         - Parameters
    3657. 

  3657. "decl"          - Declarator (function with parameters)
    3658. 

  3658. "code"          - Function body code (if any)
    3659. 

  3659. "feature:new"   - Set to indicate return of new object.
    3660. 

  3660. </pre>
    3661. 

  3661. </div>
    3662. 

  3662. 

  3663. 

  3664. <p>
    3665. 

  3665. <b>destructor</b>
    3666. 

  3666. </p>
    3667. 

  3667. 

  3668. <p>
    3669. 

  3669. C++ destructor declaration.
    3670. 

  3670. </p>
    3671. 

  3671. 

  3672. <div class="diagram">
    3673. 

  3673. <pre>
    3674. 

  3674. "name"          - Name of destructor
    3675. 

  3675. "code"          - Function body code (if any)
    3676. 

  3676. "storage"       - Storage class (set if virtual)
    3677. 

  3677. "value"         - Default value (set if pure virtual).
    3678. 

  3678. </pre>
    3679. 

  3679. </div>
    3680. 

  3680. 

  3681. 

  3682. <p>
    3683. 

  3683. <b>access</b>
    3684. 

  3684. </p>
    3685. 

  3685. 

  3686. <p>
    3687. 

  3687. C++ access change.
    3688. 

  3688. </p>
    3689. 

  3689. 

  3690. <div class="diagram">
    3691. 

  3691. <pre>
    3692. 

  3692. "kind"          - public, protected, private
    3693. 

  3693. </pre>
    3694. 

  3694. </div>
    3695. 

  3695. 

  3696. 

  3697. <p>
    3698. 

  3698. <b>constant</b>
    3699. 

  3699. </p>
    3700. 

  3700. 

  3701. <p>
    3702. 

  3702. Constant created by %constant or #define.
    3703. 

  3703. </p>
    3704. 

  3704. 

  3705. <div class="diagram">
    3706. 

  3706. <pre>
    3707. 

  3707. "name"          - Name of constant.
    3708. 

  3708. "type"          - Base type.
    3709. 

  3709. "value"         - Value.
    3710. 

  3710. "storage"       - Set to %constant
    3711. 

  3711. "feature:immutable" - Set to indicate read-only
    3712. 

  3712. </pre>
    3713. 

  3713. </div>
    3714. 

  3714. 

  3715. <p>
    3716. 

  3716. <b>class</b>
    3717. 

  3717. </p>
    3718. 

  3718. 

  3719. <p>
    3720. 

  3720. C++ class definition or C structure definition.
    3721. 

  3721. </p>
    3722. 

  3722. 

  3723. <div class="diagram">
    3724. 

  3724. <pre>
    3725. 

  3725. "name"          - Name of the class.
    3726. 

  3726. "kind"          - Class kind ("struct", "union", "class")
    3727. 

  3727. "symtab"        - Enclosing symbol table.
    3728. 

  3728. "tdname"        - Typedef name. Use for typedef struct { ... } A.
    3729. 

  3729. "abstract"      - Set if class has pure virtual methods.
    3730. 

  3730. "baselist"      - List of base class names.
    3731. 

  3731. "storage"       - Storage class (if any)
    3732. 

  3732. "unnamed"       - Set if class is unnamed.
    3733. 

  3733. </pre>
    3734. 

  3734. </div>
    3735. 

  3735. 

  3736. 

  3737. <p>
    3738. 

  3738. <b>enum</b>
    3739. 

  3739. </p>
    3740. 

  3740. 

  3741. <p>
    3742. 

  3742. Enumeration.
    3743. 

  3743. </p>
    3744. 

  3744. 

  3745. <div class="diagram">
    3746. 

  3746. <pre>
    3747. 

  3747. "name"          - Name of the enum (if supplied).
    3748. 

  3748. "storage"       - Storage class (if any)
    3749. 

  3749. "tdname"        - Typedef name (typedef enum { ... } name).
    3750. 

  3750. "unnamed"       - Set if enum is unnamed.
    3751. 

  3751. </pre>
    3752. 

  3752. </div>
    3753. 

  3753. 

  3754. 

  3755. <p>
    3756. 

  3756. <b>enumitem</b>
    3757. 

  3757. </p>
    3758. 

  3758. 

  3759. <p>
    3760. 

  3760. Enumeration value.
    3761. 

  3761. </p>
    3762. 

  3762. 

  3763. <div class="diagram">
    3764. 

  3764. <pre>
    3765. 

  3765. "name"          - Name of the enum value.
    3766. 

  3766. "type"          - Type (integer or char)
    3767. 

  3767. "value"         - Enum value (if given)
    3768. 

  3768. "feature:immutable" - Set to indicate read-only
    3769. 

  3769. </pre>
    3770. 

  3770. </div>
    3771. 

  3771. 

  3772. <p>
    3773. 

  3773. <b>namespace</b>
    3774. 

  3774. </p>
    3775. 

  3775. 

  3776. <p>
    3777. 

  3777. C++ namespace.
    3778. 

  3778. </p>
    3779. 

  3779. 

  3780. <div class="diagram">
    3781. 

  3781. <pre>
    3782. 

  3782. "name"          - Name of the namespace.
    3783. 

  3783. "symtab"        - Symbol table for enclosed scope.
    3784. 

  3784. "unnamed"       - Set if unnamed namespace
    3785. 

  3785. "alias"         - Alias name. Set for namespace A = B;
    3786. 

  3786. </pre>
    3787. 

  3787. </div>
    3788. 

  3788. 

  3789. 

  3790. <p>
    3791. 

  3791. <b>using</b>
    3792. 

  3792. </p>
    3793. 

  3793. 

  3794. <p>
    3795. 

  3795. C++ using directive.
    3796. 

  3796. </p>
    3797. 

  3797. 

  3798. <div class="diagram">
    3799. 

  3799. <pre>
    3800. 

  3800. "name"          - Name of the object being referred to.
    3801. 

  3801. "uname"         - Qualified name actually given to using.
    3802. 

  3802. "node"          - Node being referenced.
    3803. 

  3803. "namespace"     - Namespace name being reference (using namespace name)
    3804. 

  3804. </pre>
    3805. 

  3805. </div>
    3806. 

  3806. 

  3807. 

  3808. <p>
    3809. 

  3809. <b>classforward</b>
    3810. 

  3810. </p>
    3811. 

  3811. 

  3812. <p>
    3813. 

  3813. A forward C++ class declaration.
    3814. 

  3814. </p>
    3815. 

  3815. 

  3816. <div class="diagram">
    3817. 

  3817. <pre>
    3818. 

  3818. "name"          - Name of the class.
    3819. 

  3819. "kind"          - Class kind ("union", "struct", "class")
    3820. 

  3820. </pre>
    3821. 

  3821. </div>
    3822. 

  3822. 

  3823. 

  3824. <p>
    3825. 

  3825. <b>insert</b>
    3826. 

  3826. </p>
    3827. 

  3827. 

  3828. <p>
    3829. 

  3829. Code insertion directive.  For example, %{ ... %} or
    3830. 

  3830. %insert(section).
    3831. 

  3831. </p>
    3832. 

  3832. 

  3833. <div class="diagram">
    3834. 

  3834. <pre>
    3835. 

  3835. "code"          - Inserted code
    3836. 

  3836. "section"       - Section name ("header", "wrapper", etc.)
    3837. 

  3837. </pre>
    3838. 

  3838. </div>
    3839. 

  3839. 

  3840. <p>
    3841. 

  3841. <b>top</b>
    3842. 

  3842. </p>
    3843. 

  3843. 

  3844. <p>
    3845. 

  3845. Top of the parse tree.
    3846. 

  3846. </p>
    3847. 

  3847. 

  3848. <div class="diagram">
    3849. 

  3849. <pre>
    3850. 

  3850. "module"        - Module name
    3851. 

  3851. </pre>
    3852. 

  3852. </div>
    3853. 

  3853. 

  3854. <p>
    3855. 

  3855. <b>extend</b>
    3856. 

  3856. </p>
    3857. 

  3857. 

  3858. <p>
    3859. 

  3859. %extend directive.
    3860. 

  3860. </p>
    3861. 

  3861. 

  3862. <div class="diagram">
    3863. 

  3863. <pre>
    3864. 

  3864. "name"          - Module name
    3865. 

  3865. "symtab"        - Symbol table of enclosed scope.
    3866. 

  3866. </pre>
    3867. 

  3867. </div>
    3868. 

  3868. 

  3869. <p>
    3870. 

  3870. <b>apply</b>
    3871. 

  3871. </p>
    3872. 

  3872. 

  3873. <p>
    3874. 

  3874. %apply pattern { patternlist }.
    3875. 

  3875. </p>
    3876. 

  3876. 

  3877. <div class="diagram">
    3878. 

  3878. <pre>
    3879. 

  3879. "pattern"       - Source pattern.
    3880. 

  3880. "symtab"        - Symbol table of enclosed scope.
    3881. 

  3881. </pre>
    3882. 

  3882. </div>
    3883. 

  3883. 

  3884. <p>
    3885. 

  3885. <b>clear</b>
    3886. 

  3886. </p>
    3887. 

  3887. 

  3888. <p>
    3889. 

  3889. %clear patternlist;
    3890. 

  3890. </p>
    3891. 

  3891. 

  3892. <div class="diagram">
    3893. 

  3893. <pre>
    3894. 

  3894. "firstChild"    - Patterns to clear
    3895. 

  3895. </pre>
    3896. 

  3896. </div>
    3897. 

  3897. 

  3898. <p>
    3899. 

  3899. <b>include</b>
    3900. 

  3900. </p>
    3901. 

  3901. 

  3902. <p>
    3903. 

  3903. %include directive.
    3904. 

  3904. </p>
    3905. 

  3905. 

  3906. <div class="diagram">
    3907. 

  3907. <pre>
    3908. 

  3908. "name"         - Filename
    3909. 

  3909. "firstChild"   - Children
    3910. 

  3910. </pre>
    3911. 

  3911. </div>
    3912. 

  3912. 

  3913. <p>
    3914. 

  3914. <b>import</b>
    3915. 

  3915. </p>
    3916. 

  3916. 

  3917. <p>
    3918. 

  3918. %import directive.
    3919. 

  3919. </p>
    3920. 

  3920. 

  3921. <div class="diagram">
    3922. 

  3922. <pre>
    3923. 

  3923. "name"         - Filename
    3924. 

  3924. "firstChild"   - Children
    3925. 

  3925. </pre>
    3926. 

  3926. </div>
    3927. 

  3927. 

  3928. 

  3929. <p>
    3930. 

  3930. <b>module</b>
    3931. 

  3931. </p>
    3932. 

  3932. 

  3933. <p>
    3934. 

  3934. %module directive.
    3935. 

  3935. </p>
    3936. 

  3936. 

  3937. <div class="diagram">
    3938. 

  3938. <pre>
    3939. 

  3939. "name"         - Name of the module
    3940. 

  3940. </pre>
    3941. 

  3941. </div>
    3942. 

  3942. 

  3943. 

  3944. <p>
    3945. 

  3945. <b>typemap</b>
    3946. 

  3946. </p>
    3947. 

  3947. 

  3948. <p>
    3949. 

  3949. %typemap directive.
    3950. 

  3950. </p>
    3951. 

  3951. 

  3952. <div class="diagram">
    3953. 

  3953. <pre>
    3954. 

  3954. "method"       - Typemap method name.
    3955. 

  3955. "code"         - Typemap code.
    3956. 

  3956. "kwargs"       - Keyword arguments (if any)
    3957. 

  3957. "firstChild"   - Typemap patterns
    3958. 

  3958. </pre>
    3959. 

  3959. </div>
    3960. 

  3960. 

  3961. <p>
    3962. 

  3962. <b>typemapcopy</b>
    3963. 

  3963. </p>
    3964. 

  3964. 

  3965. <p>
    3966. 

  3966. %typemap directive with copy.
    3967. 

  3967. </p>
    3968. 

  3968. 

  3969. <div class="diagram">
    3970. 

  3970. <pre>
    3971. 

  3971. "method"       - Typemap method name.
    3972. 

  3972. "pattern"      - Typemap source pattern.
    3973. 

  3973. "firstChild"   - Typemap patterns
    3974. 

  3974. </pre>
    3975. 

  3975. </div>
    3976. 

  3976. 

  3977. 

  3978. <p>
    3979. 

  3979. <b>typemapitem</b>
    3980. 

  3980. </p>
    3981. 

  3981. 

  3982. <p>
    3983. 

  3983. %typemap pattern. Used with %apply, %clear, %typemap.
    3984. 

  3984. </p>
    3985. 

  3985. 

  3986. <div class="diagram">
    3987. 

  3987. <pre>
    3988. 

  3988. "pattern"      - Typemap pattern (a parameter list)
    3989. 

  3989. "parms"        - Typemap parameters.
    3990. 

  3990. </pre>
    3991. 

  3991. </div>
    3992. 

  3992. 

  3993. <p>
    3994. 

  3994. <b>types</b>
    3995. 

  3995. </p>
    3996. 

  3996. 

  3997. <p>
    3998. 

  3998. %types directive.
    3999. 

  3999. </p>
    4000. 

  4000. 

  4001. <div class="diagram">
    4002. 

  4002. <pre>
    4003. 

  4003. "parms"        - List of parameter types.
    4004. 

  4004. "convcode"     - Code which replaces the default casting / conversion code
    4005. 

  4005. </pre>
    4006. 

  4006. </div>
    4007. 

  4007. 

  4008. 

  4009. <p>
    4010. 

  4010. <b>extern</b>
    4011. 

  4011. </p>
    4012. 

  4012. 

  4013. <p>
    4014. 

  4014. extern "X" { ... } declaration.
    4015. 

  4015. </p>
    4016. 

  4016. 

  4017. <div class="diagram">
    4018. 

  4018. <pre>
    4019. 

  4019. "name"       - Name "C", "Fortran", etc.
    4020. 

  4020. </pre>
    4021. 

  4021. </div>
    4022. 

  4022. 

  4023. <H2><a name="Extending_further_info"></a>35.13 Further Development Information</H2>
    4024. 

  4024. 

  4025. 

  4026. <p>
    4027. 

  4027. There is further documentation available on the internals of SWIG, API documentation and debugging information.
    4028. 

  4028. This is shipped with SWIG in the <tt>Doc/Devel</tt> directory.
    4029. 

  4029. </P>
    4030. 

  4030. 

  4031. 

  4032. 

  4033. </body>
    4034. 

  4034. </html>
    4035. 

  4035.