PageRenderTime 77ms CodeModel.GetById 24ms 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

Large files files are truncated, but you can click here to view the full file

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  2. <html>
  3. <head>
  4. <title>Extending SWIG to support new languages</title>
  5. <link rel="stylesheet" type="text/css" href="style.css">
  6. </head>
  7. <body bgcolor="#ffffff">
  8. <H1><a name="Extending"></a>35 Extending SWIG to support new languages</H1>
  9. <!-- INDEX -->
  10. <div class="sectiontoc">
  11. <ul>
  12. <li><a href="#Extending_nn2">Introduction</a>
  13. <li><a href="#Extending_nn3">Prerequisites</a>
  14. <li><a href="#Extending_nn4">The Big Picture</a>
  15. <li><a href="#Extending_nn5">Execution Model</a>
  16. <ul>
  17. <li><a href="#Extending_nn6">Preprocessing</a>
  18. <li><a href="#Extending_nn7">Parsing</a>
  19. <li><a href="#Extending_nn8">Parse Trees</a>
  20. <li><a href="#Extending_nn9">Attribute namespaces</a>
  21. <li><a href="#Extending_nn10">Symbol Tables</a>
  22. <li><a href="#Extending_nn11">The %feature directive</a>
  23. <li><a href="#Extending_nn12">Code Generation</a>
  24. <li><a href="#Extending_nn13">SWIG and XML</a>
  25. </ul>
  26. <li><a href="#Extending_nn14">Primitive Data Structures</a>
  27. <ul>
  28. <li><a href="#Extending_nn15">Strings</a>
  29. <li><a href="#Extending_nn16">Hashes</a>
  30. <li><a href="#Extending_nn17">Lists</a>
  31. <li><a href="#Extending_nn18">Common operations</a>
  32. <li><a href="#Extending_nn19">Iterating over Lists and Hashes</a>
  33. <li><a href="#Extending_nn20">I/O</a>
  34. </ul>
  35. <li><a href="#Extending_nn21">Navigating and manipulating parse trees</a>
  36. <li><a href="#Extending_nn22">Working with attributes</a>
  37. <li><a href="#Extending_nn23">Type system</a>
  38. <ul>
  39. <li><a href="#Extending_nn24">String encoding of types</a>
  40. <li><a href="#Extending_nn25">Type construction</a>
  41. <li><a href="#Extending_nn26">Type tests</a>
  42. <li><a href="#Extending_nn27">Typedef and inheritance</a>
  43. <li><a href="#Extending_nn28">Lvalues</a>
  44. <li><a href="#Extending_nn29">Output functions</a>
  45. </ul>
  46. <li><a href="#Extending_nn30">Parameters</a>
  47. <li><a href="#Extending_nn31">Writing a Language Module</a>
  48. <ul>
  49. <li><a href="#Extending_nn32">Execution model</a>
  50. <li><a href="#Extending_starting_out">Starting out</a>
  51. <li><a href="#Extending_nn34">Command line options</a>
  52. <li><a href="#Extending_nn35">Configuration and preprocessing</a>
  53. <li><a href="#Extending_nn36">Entry point to code generation</a>
  54. <li><a href="#Extending_nn37">Module I/O and wrapper skeleton</a>
  55. <li><a href="#Extending_nn38">Low-level code generators</a>
  56. <li><a href="#Extending_nn39">Configuration files</a>
  57. <li><a href="#Extending_nn40">Runtime support</a>
  58. <li><a href="#Extending_nn41">Standard library files</a>
  59. <li><a href="#Extending_nn42">User examples</a>
  60. <li><a href="#Extending_test_suite">Test driven development and the test-suite</a>
  61. <ul>
  62. <li><a href="#Extending_running_test_suite">Running the test-suite</a>
  63. </ul>
  64. <li><a href="#Extending_nn43">Documentation</a>
  65. <li><a href="#Extending_prerequisites">Prerequisites for adding a new language module to the SWIG distribution</a>
  66. <li><a href="#Extending_coding_style_guidelines">Coding style guidelines</a>
  67. </ul>
  68. <li><a href="#Extending_debugging_options">Debugging Options</a>
  69. <li><a href="#Extending_nn46">Guide to parse tree nodes</a>
  70. <li><a href="#Extending_further_info">Further Development Information</a>
  71. </ul>
  72. </div>
  73. <!-- INDEX -->
  74. <H2><a name="Extending_nn2"></a>35.1 Introduction</H2>
  75. <p>
  76. This chapter describes SWIG's internal organization and the process by which
  77. new target languages can be developed. First, a brief word of warning---SWIG
  78. is continually evolving.
  79. The information in this chapter is mostly up to
  80. date, but changes are ongoing. Expect a few inconsistencies.
  81. </p>
  82. <p>
  83. Also, this chapter is not meant to be a hand-holding tutorial. As a starting point,
  84. you should probably look at one of SWIG's existing modules.
  85. </p>
  86. <H2><a name="Extending_nn3"></a>35.2 Prerequisites</H2>
  87. <p>
  88. In order to extend SWIG, it is useful to have the following background:
  89. </p>
  90. <ul>
  91. <li>An understanding of the C API for the target language.
  92. <li>A good grasp of the C++ type system.
  93. <li>An understanding of typemaps and some of SWIG's advanced features.
  94. <li>Some familiarity with writing C++ (language modules are currently written in C++).
  95. </ul>
  96. <p>
  97. Since SWIG is essentially a specialized C++ compiler, it may be useful
  98. to have some prior experience with compiler design (perhaps even a
  99. compilers course) to better understand certain parts of the system. A
  100. number of books will also be useful. For example, "The C Programming
  101. Language" by Kernighan and Ritchie (a.k.a, "K&amp;R") and the C++ standard,
  102. "ISO/IEC 14882 Programming Languages - C++" will be of great use.
  103. </p>
  104. <p>
  105. Also, it is useful to keep in mind that SWIG primarily operates as an
  106. extension of the C++ <em>type</em> system. At first glance, this might not be
  107. obvious, but almost all SWIG directives as well as the low-level generation of
  108. wrapper code are driven by C++ datatypes.
  109. </p>
  110. <H2><a name="Extending_nn4"></a>35.3 The Big Picture</H2>
  111. <p>
  112. SWIG is a special purpose compiler that parses C++ declarations to
  113. generate wrapper code. To make this conversion possible, SWIG makes
  114. three fundamental extensions to the C++ language:
  115. </p>
  116. <ul>
  117. <li><b>Typemaps</b>. Typemaps are used to define the
  118. conversion/marshalling behavior of specific C++ datatypes. All type conversion in SWIG is
  119. based on typemaps. Furthermore, the association of typemaps to datatypes utilizes an advanced pattern matching
  120. mechanism that is fully integrated with the C++ type system.
  121. </li>
  122. <li><b>Declaration Annotation</b>. To customize wrapper code
  123. generation, most declarations can be annotated with special features.
  124. For example, you can make a variable read-only, you can ignore a
  125. declaration, you can rename a member function, you can add exception
  126. handling, and so forth. Virtually all of these customizations are built on top of a low-level
  127. declaration annotator that can attach arbitrary attributes to any declaration.
  128. Code generation modules can look for these attributes to guide the wrapping process.
  129. </li>
  130. <li><b>Class extension</b>. SWIG allows classes and structures to be extended with new
  131. methods and attributes (the <tt>%extend</tt> directive). This has the effect of altering
  132. the API in the target language and can be used to generate OO interfaces to C libraries.
  133. </ul>
  134. <p>
  135. It is important to emphasize that virtually all SWIG features reduce to one of these three
  136. fundamental concepts. The type system and pattern matching rules also play a critical
  137. role in making the system work. For example, both typemaps and declaration annotation are
  138. based on pattern matching and interact heavily with the underlying type system.
  139. </p>
  140. <H2><a name="Extending_nn5"></a>35.4 Execution Model</H2>
  141. <p>
  142. When you run SWIG on an interface, processing is handled in stages by a series of system components:
  143. </p>
  144. <ul>
  145. <li>An integrated C preprocessor reads a collection of configuration
  146. files and the specified interface file into memory. The preprocessor
  147. performs the usual functions including macro expansion and file
  148. inclusion. However, the preprocessor also performs some transformations of the
  149. interface. For instance, <tt>#define</tt> statements are sometimes transformed into
  150. <tt>%constant</tt> declarations. In addition, information related to file/line number
  151. tracking is inserted.
  152. </li>
  153. <li>A C/C++ parser reads the preprocessed input and generates a full
  154. parse tree of all of the SWIG directives and C declarations found.
  155. The parser is responsible for many aspects of the system including
  156. renaming, declaration annotation, and template expansion. However, the parser
  157. does not produce any output nor does it interact with the target
  158. language module as it runs. SWIG is not a one-pass compiler.
  159. </li>
  160. <li>A type-checking pass is made. This adjusts all of the C++ typenames to properly
  161. handle namespaces, typedefs, nested classes, and other issues related to type scoping.
  162. </li>
  163. <li>A semantic pass is made on the parse tree to collect information
  164. related to properties of the C++ interface. For example, this pass
  165. would determine whether or not a class allows a default constructor.
  166. </li>
  167. <li>A code generation pass is made using a specific target language
  168. module. This phase is responsible for generating the actual wrapper
  169. code. All of SWIG's user-defined modules are invoked during this
  170. latter stage of compilation.
  171. </li>
  172. </ul>
  173. <p>
  174. The next few sections briefly describe some of these stages.
  175. </p>
  176. <H3><a name="Extending_nn6"></a>35.4.1 Preprocessing</H3>
  177. <p>
  178. The preprocessor plays a critical role in the SWIG implementation. This is because a lot
  179. of SWIG's processing and internal configuration is managed not by code written in C, but
  180. by configuration files in the SWIG library. In fact, when you
  181. run SWIG, parsing starts with a small interface file like this (note: this explains
  182. the cryptic error messages that new users sometimes get when SWIG is misconfigured or installed
  183. incorrectly):
  184. </p>
  185. <div class="code">
  186. <pre>
  187. %include "swig.swg" // Global SWIG configuration
  188. %include "<em>langconfig.swg</em>" // Language specific configuration
  189. %include "yourinterface.i" // Your interface file
  190. </pre>
  191. </div>
  192. <p>
  193. The <tt>swig.swg</tt> file contains global configuration information. In addition, this file
  194. defines many of SWIG's standard directives as macros. For instance, part of
  195. of <tt>swig.swg</tt> looks like this:
  196. </p>
  197. <div class="code">
  198. <pre>
  199. ...
  200. /* Code insertion directives such as %wrapper %{ ... %} */
  201. #define %begin %insert("begin")
  202. #define %runtime %insert("runtime")
  203. #define %header %insert("header")
  204. #define %wrapper %insert("wrapper")
  205. #define %init %insert("init")
  206. /* Access control directives */
  207. #define %immutable %feature("immutable","1")
  208. #define %mutable %feature("immutable")
  209. /* Directives for callback functions */
  210. #define %callback(x) %feature("callback") `x`;
  211. #define %nocallback %feature("callback");
  212. /* %ignore directive */
  213. #define %ignore %rename($ignore)
  214. #define %ignorewarn(x) %rename("$ignore:" x)
  215. ...
  216. </pre>
  217. </div>
  218. <p>
  219. The fact that most of the standard SWIG directives are macros is
  220. intended to simplify the implementation of the internals. For instance,
  221. rather than having to support dozens of special directives, it is
  222. easier to have a few basic primitives such as <tt>%feature</tt> or
  223. <tt>%insert</tt>.
  224. </p>
  225. <p>
  226. The <em><tt>langconfig.swg</tt></em> file is supplied by the target
  227. language. This file contains language-specific configuration
  228. information. More often than not, this file provides run-time wrapper
  229. support code (e.g., the type-checker) as well as a collection of
  230. typemaps that define the default wrapping behavior. Note: the name of this
  231. file depends on the target language and is usually something like <tt>python.swg</tt>
  232. or <tt>perl5.swg</tt>.
  233. </p>
  234. <p>
  235. As a debugging aide, the text that SWIG feeds to its C++ parser can be
  236. obtained by running <tt>swig -E interface.i</tt>. This output
  237. probably isn't too useful in general, but it will show how macros have
  238. been expanded as well as everything else that goes into the low-level
  239. construction of the wrapper code.
  240. </p>
  241. <H3><a name="Extending_nn7"></a>35.4.2 Parsing</H3>
  242. <p>
  243. The current C++ parser handles a subset of C++. Most incompatibilities with C are due to
  244. subtle aspects of how SWIG parses declarations. Specifically, SWIG expects all C/C++ declarations to follow this general form:
  245. </p>
  246. <div class="diagram">
  247. <pre>
  248. <em>storage</em> <em>type</em> <em>declarator</em> <em>initializer</em>;
  249. </pre>
  250. </div>
  251. <p>
  252. <tt><em>storage</em></tt> is a keyword such as <tt>extern</tt>,
  253. <tt>static</tt>, <tt>typedef</tt>, or <tt>virtual</tt>. <tt><em>type</em></tt> is a primitive
  254. datatype such as <tt>int</tt> or <tt>void</tt>. <tt><em>type</em></tt> may be optionally
  255. qualified with a qualifier such as <tt>const</tt> or <tt>volatile</tt>. <tt><em>declarator</em></tt>
  256. is a name with additional type-construction modifiers attached to it (pointers, arrays, references,
  257. functions, etc.). Examples of declarators include <tt>*x</tt>, <tt>**x</tt>, <tt>x[20]</tt>, and
  258. <tt>(*x)(int,double)</tt>. The <tt><em>initializer</em></tt> may be a value assigned using <tt>=</tt> or
  259. body of code enclosed in braces <tt>{ ... }</tt>.
  260. </p>
  261. <p>
  262. This declaration format covers most common C++ declarations. However, the C++ standard
  263. is somewhat more flexible in the placement of the parts. For example, it is technically legal, although
  264. uncommon to write something like <tt>int typedef const a</tt> in your program. SWIG simply
  265. doesn't bother to deal with this case.
  266. </p>
  267. <p>
  268. The other significant difference between C++ and SWIG is in the
  269. treatment of typenames. In C++, if you have a declaration like this,
  270. </p>
  271. <div class="code">
  272. <pre>
  273. int blah(Foo *x, Bar *y);
  274. </pre>
  275. </div>
  276. <p>
  277. it won't parse correctly unless <tt>Foo</tt> and <tt>Bar</tt> have
  278. been previously defined as types either using a <tt>class</tt>
  279. definition or a <tt>typedef</tt>. The reasons for this are subtle,
  280. but this treatment of typenames is normally integrated at the level of the C
  281. tokenizer---when a typename appears, a different token is returned to the parser
  282. instead of an identifier.
  283. </p>
  284. <p>
  285. SWIG does not operate in this manner--any legal identifier can be used
  286. as a type name. The reason for this is primarily motivated by the use
  287. of SWIG with partially defined data. Specifically,
  288. SWIG is supposed to be easy to use on interfaces with missing type information.
  289. </p>
  290. <p>
  291. Because of the different treatment of typenames, the most serious
  292. limitation of the SWIG parser is that it can't process type declarations where
  293. an extra (and unnecessary) grouping operator is used. For example:
  294. </p>
  295. <div class="code">
  296. <pre>
  297. int (x); /* A variable x */
  298. int (y)(int); /* A function y */
  299. </pre>
  300. </div>
  301. <p>
  302. The placing of extra parentheses in type declarations like this is
  303. already recognized by the C++ community as a potential source of
  304. strange programming errors. For example, Scott Meyers "Effective STL"
  305. discusses this problem in a section on avoiding C++'s "most vexing
  306. parse."
  307. </p>
  308. <p>
  309. The parser is also unable to handle declarations with no return type or bare argument names.
  310. For example, in an old C program, you might see things like this:
  311. </p>
  312. <div class="code">
  313. <pre>
  314. foo(a,b) {
  315. ...
  316. }
  317. </pre>
  318. </div>
  319. <p>
  320. In this case, the return type as well as the types of the arguments
  321. are taken by the C compiler to be an <tt>int</tt>. However, SWIG
  322. interprets the above code as an abstract declarator for a function
  323. returning a <tt>foo</tt> and taking types <tt>a</tt> and <tt>b</tt> as
  324. arguments).
  325. </p>
  326. <H3><a name="Extending_nn8"></a>35.4.3 Parse Trees</H3>
  327. <p>
  328. The SWIG parser produces a complete parse tree of the input file before any wrapper code
  329. is actually generated. Each item in the tree is known as a "Node". Each node is identified
  330. by a symbolic tag. Furthermore, a node may have an arbitrary number of children.
  331. The parse tree structure and tag names of an interface can be displayed using <tt>swig -debug-tags</tt>.
  332. For example:
  333. </p>
  334. <div class="shell">
  335. <pre>
  336. $ <b>swig -c++ -python -debug-tags example.i</b>
  337. . top (example.i:1)
  338. . top . include (example.i:1)
  339. . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/swig.swg:71)
  340. . top . include . typemap . typemapitem (/r0/beazley/Projects/lib/swig1.3/swig.swg:71)
  341. . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/swig.swg:83)
  342. . top . include . typemap . typemapitem (/r0/beazley/Projects/lib/swig1.3/swig.swg:83)
  343. . top . include (example.i:4)
  344. . top . include . insert (/r0/beazley/Projects/lib/swig1.3/python/python.swg:7)
  345. . top . include . insert (/r0/beazley/Projects/lib/swig1.3/python/python.swg:8)
  346. . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/python/python.swg:19)
  347. ...
  348. . top . include (example.i:6)
  349. . top . include . module (example.i:2)
  350. . top . include . insert (example.i:6)
  351. . top . include . include (example.i:9)
  352. . top . include . include . class (example.h:3)
  353. . top . include . include . class . access (example.h:4)
  354. . top . include . include . class . constructor (example.h:7)
  355. . top . include . include . class . destructor (example.h:10)
  356. . top . include . include . class . cdecl (example.h:11)
  357. . top . include . include . class . cdecl (example.h:11)
  358. . top . include . include . class . cdecl (example.h:12)
  359. . top . include . include . class . cdecl (example.h:13)
  360. . top . include . include . class . cdecl (example.h:14)
  361. . top . include . include . class . cdecl (example.h:15)
  362. . top . include . include . class (example.h:18)
  363. . top . include . include . class . access (example.h:19)
  364. . top . include . include . class . cdecl (example.h:20)
  365. . top . include . include . class . access (example.h:21)
  366. . top . include . include . class . constructor (example.h:22)
  367. . top . include . include . class . cdecl (example.h:23)
  368. . top . include . include . class . cdecl (example.h:24)
  369. . top . include . include . class (example.h:27)
  370. . top . include . include . class . access (example.h:28)
  371. . top . include . include . class . cdecl (example.h:29)
  372. . top . include . include . class . access (example.h:30)
  373. . top . include . include . class . constructor (example.h:31)
  374. . top . include . include . class . cdecl (example.h:32)
  375. . top . include . include . class . cdecl (example.h:33)
  376. </pre>
  377. </div>
  378. <p>
  379. Even for the most simple interface, the parse tree structure is larger than you might expect. For example, in the
  380. above output, a substantial number of nodes are actually generated by the <tt>python.swg</tt> configuration file
  381. which defines typemaps and other directives. The contents of the user-supplied input file don't appear until the end
  382. of the output.
  383. </p>
  384. <p>
  385. The contents of each parse tree node consist of a collection of attribute/value
  386. pairs. Internally, the nodes are simply represented by hash tables. A display of
  387. the entire parse-tree structure can be obtained using <tt>swig -debug-top &lt;n&gt;</tt>, where <tt>n</tt> is
  388. the stage being processed.
  389. There are a number of other parse tree display options, for example, <tt>swig -debug-module &lt;n&gt;</tt> will
  390. avoid displaying system parse information and only display the parse tree pertaining to the user's module at
  391. stage <tt>n</tt> of processing.
  392. </p>
  393. <div class="shell">
  394. <pre>
  395. $ swig -c++ -python -debug-module 4 example.i
  396. +++ include ----------------------------------------
  397. | name - "example.i"
  398. +++ module ----------------------------------------
  399. | name - "example"
  400. |
  401. +++ insert ----------------------------------------
  402. | code - "\n#include \"example.h\"\n"
  403. |
  404. +++ include ----------------------------------------
  405. | name - "example.h"
  406. +++ class ----------------------------------------
  407. | abstract - "1"
  408. | sym:name - "Shape"
  409. | name - "Shape"
  410. | kind - "class"
  411. | symtab - 0x40194140
  412. | sym:symtab - 0x40191078
  413. +++ access ----------------------------------------
  414. | kind - "public"
  415. |
  416. +++ constructor ----------------------------------------
  417. | sym:name - "Shape"
  418. | name - "Shape"
  419. | decl - "f()."
  420. | code - "{\n nshapes++;\n }"
  421. | sym:symtab - 0x40194140
  422. |
  423. +++ destructor ----------------------------------------
  424. | sym:name - "~Shape"
  425. | name - "~Shape"
  426. | storage - "virtual"
  427. | code - "{\n nshapes--;\n }"
  428. | sym:symtab - 0x40194140
  429. |
  430. +++ cdecl ----------------------------------------
  431. | sym:name - "x"
  432. | name - "x"
  433. | decl - ""
  434. | type - "double"
  435. | sym:symtab - 0x40194140
  436. |
  437. +++ cdecl ----------------------------------------
  438. | sym:name - "y"
  439. | name - "y"
  440. | decl - ""
  441. | type - "double"
  442. | sym:symtab - 0x40194140
  443. |
  444. +++ cdecl ----------------------------------------
  445. | sym:name - "move"
  446. | name - "move"
  447. | decl - "f(double,double)."
  448. | parms - double ,double
  449. | type - "void"
  450. | sym:symtab - 0x40194140
  451. |
  452. +++ cdecl ----------------------------------------
  453. | sym:name - "area"
  454. | name - "area"
  455. | decl - "f(void)."
  456. | parms - void
  457. | storage - "virtual"
  458. | value - "0"
  459. | type - "double"
  460. | sym:symtab - 0x40194140
  461. |
  462. +++ cdecl ----------------------------------------
  463. | sym:name - "perimeter"
  464. | name - "perimeter"
  465. | decl - "f(void)."
  466. | parms - void
  467. | storage - "virtual"
  468. | value - "0"
  469. | type - "double"
  470. | sym:symtab - 0x40194140
  471. |
  472. +++ cdecl ----------------------------------------
  473. | sym:name - "nshapes"
  474. | name - "nshapes"
  475. | decl - ""
  476. | storage - "static"
  477. | type - "int"
  478. | sym:symtab - 0x40194140
  479. |
  480. +++ class ----------------------------------------
  481. | sym:name - "Circle"
  482. | name - "Circle"
  483. | kind - "class"
  484. | bases - 0x40194510
  485. | symtab - 0x40194538
  486. | sym:symtab - 0x40191078
  487. +++ access ----------------------------------------
  488. | kind - "private"
  489. |
  490. +++ cdecl ----------------------------------------
  491. | name - "radius"
  492. | decl - ""
  493. | type - "double"
  494. |
  495. +++ access ----------------------------------------
  496. | kind - "public"
  497. |
  498. +++ constructor ----------------------------------------
  499. | sym:name - "Circle"
  500. | name - "Circle"
  501. | parms - double
  502. | decl - "f(double)."
  503. | code - "{ }"
  504. | sym:symtab - 0x40194538
  505. |
  506. +++ cdecl ----------------------------------------
  507. | sym:name - "area"
  508. | name - "area"
  509. | decl - "f(void)."
  510. | parms - void
  511. | storage - "virtual"
  512. | type - "double"
  513. | sym:symtab - 0x40194538
  514. |
  515. +++ cdecl ----------------------------------------
  516. | sym:name - "perimeter"
  517. | name - "perimeter"
  518. | decl - "f(void)."
  519. | parms - void
  520. | storage - "virtual"
  521. | type - "double"
  522. | sym:symtab - 0x40194538
  523. |
  524. +++ class ----------------------------------------
  525. | sym:name - "Square"
  526. | name - "Square"
  527. | kind - "class"
  528. | bases - 0x40194760
  529. | symtab - 0x40194788
  530. | sym:symtab - 0x40191078
  531. +++ access ----------------------------------------
  532. | kind - "private"
  533. |
  534. +++ cdecl ----------------------------------------
  535. | name - "width"
  536. | decl - ""
  537. | type - "double"
  538. |
  539. +++ access ----------------------------------------
  540. | kind - "public"
  541. |
  542. +++ constructor ----------------------------------------
  543. | sym:name - "Square"
  544. | name - "Square"
  545. | parms - double
  546. | decl - "f(double)."
  547. | code - "{ }"
  548. | sym:symtab - 0x40194788
  549. |
  550. +++ cdecl ----------------------------------------
  551. | sym:name - "area"
  552. | name - "area"
  553. | decl - "f(void)."
  554. | parms - void
  555. | storage - "virtual"
  556. | type - "double"
  557. | sym:symtab - 0x40194788
  558. |
  559. +++ cdecl ----------------------------------------
  560. | sym:name - "perimeter"
  561. | name - "perimeter"
  562. | decl - "f(void)."
  563. | parms - void
  564. | storage - "virtual"
  565. | type - "double"
  566. | sym:symtab - 0x40194788
  567. </pre>
  568. </div>
  569. <H3><a name="Extending_nn9"></a>35.4.4 Attribute namespaces</H3>
  570. <p>
  571. Attributes of parse tree nodes are often prepended with a namespace qualifier.
  572. For example, the attributes
  573. <tt>sym:name</tt> and <tt>sym:symtab</tt> are attributes related to
  574. symbol table management and are prefixed with <tt>sym:</tt>. As a
  575. general rule, only those attributes which are directly related to the raw declaration
  576. appear without a prefix (type, name, declarator, etc.).
  577. </p>
  578. <p>
  579. Target language modules may add additional attributes to nodes to assist the generation
  580. of wrapper code. The convention for doing this is to place these attributes in a namespace
  581. that matches the name of the target language. For example, <tt>python:foo</tt> or
  582. <tt>perl:foo</tt>.
  583. </p>
  584. <H3><a name="Extending_nn10"></a>35.4.5 Symbol Tables</H3>
  585. <p>
  586. During parsing, all symbols are managed in the space of the target
  587. language. The <tt>sym:name</tt> attribute of each node contains the symbol name
  588. selected by the parser. Normally, <tt>sym:name</tt> and <tt>name</tt>
  589. are the same. However, the <tt>%rename</tt> directive can be used to
  590. change the value of <tt>sym:name</tt>. You can see the effect of
  591. <tt>%rename</tt> by trying it on a simple interface and dumping the
  592. parse tree. For example:
  593. </p>
  594. <div class="code">
  595. <pre>
  596. %rename(foo_i) foo(int);
  597. %rename(foo_d) foo(double);
  598. void foo(int);
  599. void foo(double);
  600. void foo(Bar *b);
  601. </pre>
  602. </div>
  603. <p>
  604. There are various <tt>debug-</tt> options that can be useful for debugging and analysing the parse tree.
  605. For example, the <tt>debug-top &lt;n&gt;</tt> or <tt>debug-module &lt;n&gt;</tt> options will
  606. dump the entire/top of the parse tree or the module subtree at one of the four <tt>n</tt> stages of processing.
  607. The parse tree can be viewed after the final stage of processing by running SWIG:
  608. </p>
  609. <div class="shell">
  610. <pre>
  611. $ swig -debug-top 4 example.i
  612. ...
  613. +++ cdecl ----------------------------------------
  614. | sym:name - "foo_i"
  615. | name - "foo"
  616. | decl - "f(int)."
  617. | parms - int
  618. | type - "void"
  619. | sym:symtab - 0x40165078
  620. |
  621. +++ cdecl ----------------------------------------
  622. | sym:name - "foo_d"
  623. | name - "foo"
  624. | decl - "f(double)."
  625. | parms - double
  626. | type - "void"
  627. | sym:symtab - 0x40165078
  628. |
  629. +++ cdecl ----------------------------------------
  630. | sym:name - "foo"
  631. | name - "foo"
  632. | decl - "f(p.Bar)."
  633. | parms - Bar *
  634. | type - "void"
  635. | sym:symtab - 0x40165078
  636. </pre>
  637. </div>
  638. <p>
  639. All symbol-related conflicts and complaints about overloading are based on <tt>sym:name</tt> values.
  640. For instance, the following example uses <tt>%rename</tt> in reverse to generate a name clash.
  641. </p>
  642. <div class="code">
  643. <pre>
  644. %rename(foo) foo_i(int);
  645. %rename(foo) foo_d(double;
  646. void foo_i(int);
  647. void foo_d(double);
  648. void foo(Bar *b);
  649. </pre>
  650. </div>
  651. <p>
  652. When you run SWIG on this you now get:
  653. </p>
  654. <div class="shell">
  655. <pre>
  656. $ ./swig example.i
  657. example.i:6. Overloaded declaration ignored. foo_d(double )
  658. example.i:5. Previous declaration is foo_i(int )
  659. example.i:7. Overloaded declaration ignored. foo(Bar *)
  660. example.i:5. Previous declaration is foo_i(int )
  661. </pre>
  662. </div>
  663. <H3><a name="Extending_nn11"></a>35.4.6 The %feature directive</H3>
  664. <p>
  665. A number of SWIG directives such as <tt>%exception</tt> are implemented using the
  666. low-level <tt>%feature</tt> directive. For example:
  667. </p>
  668. <div class="code">
  669. <pre>
  670. %feature("except") getitem(int) {
  671. try {
  672. $action
  673. } catch (badindex) {
  674. ...
  675. }
  676. }
  677. ...
  678. class Foo {
  679. public:
  680. Object *getitem(int index) throws(badindex);
  681. ...
  682. };
  683. </pre>
  684. </div>
  685. <p>
  686. The behavior of <tt>%feature</tt> is very easy to describe--it simply
  687. attaches a new attribute to any parse tree node that matches the
  688. given prototype. When a feature is added, it shows up as an attribute in the <tt>feature:</tt> namespace.
  689. You can see this when running with the <tt>-debug-top 4</tt> option. For example:
  690. </p>
  691. <div class="shell">
  692. <pre>
  693. +++ cdecl ----------------------------------------
  694. | sym:name - "getitem"
  695. | name - "getitem"
  696. | decl - "f(int).p."
  697. | parms - int
  698. | type - "Object"
  699. | feature:except - "{\n try {\n $action\n } catc..."
  700. | sym:symtab - 0x40168ac8
  701. |
  702. </pre>
  703. </div>
  704. <p>
  705. Feature names are completely arbitrary and a target language module can be
  706. programmed to respond to any feature name that it wants to recognize. The
  707. data stored in a feature attribute is usually just a raw unparsed string.
  708. For example, the exception code above is simply
  709. stored without any modifications.
  710. </p>
  711. <H3><a name="Extending_nn12"></a>35.4.7 Code Generation</H3>
  712. <p>
  713. Language modules work by defining handler functions that know how to respond to
  714. different types of parse-tree nodes. These handlers simply look at the
  715. attributes of each node in order to produce low-level code.
  716. </p>
  717. <p>
  718. In reality, the generation of code is somewhat more subtle than simply
  719. invoking handler functions. This is because parse-tree nodes might be
  720. transformed. For example, suppose you are wrapping a class like this:
  721. </p>
  722. <div class="code">
  723. <pre>
  724. class Foo {
  725. public:
  726. virtual int *bar(int x);
  727. };
  728. </pre>
  729. </div>
  730. <p>
  731. When the parser constructs a node for the member <tt>bar</tt>, it creates a raw "cdecl" node with the following
  732. attributes:
  733. </p>
  734. <div class="diagram">
  735. <pre>
  736. nodeType : cdecl
  737. name : bar
  738. type : int
  739. decl : f(int).p
  740. parms : int x
  741. storage : virtual
  742. sym:name : bar
  743. </pre>
  744. </div>
  745. <p>
  746. 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:
  747. </p>
  748. <div class="diagram">
  749. <pre>
  750. nodeType : cdecl
  751. name : bar
  752. type : p.int &lt;-- Notice change in return type
  753. decl : f(int).p
  754. parms : int x
  755. storage : virtual
  756. sym:name : bar
  757. </pre>
  758. </div>
  759. <p>
  760. Next, the context of the node indicates that the node is really a
  761. member function. This produces a transformation to a low-level
  762. accessor function like this:
  763. </p>
  764. <div class="diagram">
  765. <pre>
  766. nodeType : cdecl
  767. name : bar
  768. type : int.p
  769. decl : f(int).p
  770. parms : Foo *self, int x &lt;-- Added parameter
  771. storage : virtual
  772. wrap:action : result = (arg1)-&gt;bar(arg2) &lt;-- Action code added
  773. sym:name : Foo_bar &lt;-- Symbol name changed
  774. </pre>
  775. </div>
  776. <p>
  777. In this transformation, notice how an additional parameter was added
  778. to the parameter list and how the symbol name of the node has suddenly
  779. changed into an accessor using the naming scheme described in the
  780. "SWIG Basics" chapter. A small fragment of "action" code has also
  781. been generated--notice how the <tt>wrap:action</tt> attribute defines
  782. the access to the underlying method. The data in this transformed
  783. node is then used to generate a wrapper.
  784. </p>
  785. <p>
  786. Language modules work by registering handler functions for dealing with
  787. various types of nodes at different stages of transformation. This is done by
  788. inheriting from a special <tt>Language</tt> class and defining a collection
  789. of virtual methods. For example, the Python module defines a class as
  790. follows:
  791. </p>
  792. <div class="code">
  793. <pre>
  794. class PYTHON : public Language {
  795. protected:
  796. public :
  797. virtual void main(int, char *argv[]);
  798. virtual int top(Node *);
  799. virtual int functionWrapper(Node *);
  800. virtual int constantWrapper(Node *);
  801. virtual int variableWrapper(Node *);
  802. virtual int nativeWrapper(Node *);
  803. virtual int membervariableHandler(Node *);
  804. virtual int memberconstantHandler(Node *);
  805. virtual int memberfunctionHandler(Node *);
  806. virtual int constructorHandler(Node *);
  807. virtual int destructorHandler(Node *);
  808. virtual int classHandler(Node *);
  809. virtual int classforwardDeclaration(Node *);
  810. virtual int insertDirective(Node *);
  811. virtual int importDirective(Node *);
  812. };
  813. </pre>
  814. </div>
  815. <p>
  816. The role of these functions is described shortly.
  817. </p>
  818. <H3><a name="Extending_nn13"></a>35.4.8 SWIG and XML</H3>
  819. <p>
  820. Much of SWIG's current parser design was originally motivated by
  821. interest in using XML to represent SWIG parse trees. Although XML is
  822. not currently used in any direct manner, the parse tree structure, use
  823. of node tags, attributes, and attribute namespaces are all influenced
  824. by aspects of XML parsing. Therefore, in trying to understand SWIG's
  825. internal data structures, it may be useful to keep XML in the back of
  826. your mind as a model.
  827. </p>
  828. <H2><a name="Extending_nn14"></a>35.5 Primitive Data Structures</H2>
  829. <p>
  830. Most of SWIG is constructed using three basic data structures:
  831. strings, hashes, and lists. These data structures are dynamic in same way as
  832. similar structures found in many scripting languages. For instance,
  833. you can have containers (lists and hash tables) of mixed types and
  834. certain operations are polymorphic.
  835. </p>
  836. <p>
  837. This section briefly describes the basic structures so that later
  838. sections of this chapter make more sense.
  839. </p>
  840. <p>
  841. When describing the low-level API, the following type name conventions are
  842. used:
  843. </p>
  844. <ul>
  845. <li><tt>String</tt>. A string object.
  846. <li><tt>Hash</tt>. A hash object.
  847. <li><tt>List</tt>. A list object.
  848. <li><tt>String_or_char</tt>. A string object or a <tt>char *</tt>.
  849. <li><tt>Object_or_char</tt>. An object or a <tt>char *</tt>.
  850. <li><tt>Object</tt>. Any object (string, hash, list, etc.)
  851. </ul>
  852. <p>
  853. In most cases, other typenames in the source are aliases for one of these
  854. primitive types. Specifically:
  855. </p>
  856. <div class="code">
  857. <pre>
  858. typedef String SwigType;
  859. typedef Hash Parm;
  860. typedef Hash ParmList;
  861. typedef Hash Node;
  862. typedef Hash Symtab;
  863. typedef Hash Typetab;
  864. </pre>
  865. </div>
  866. <H3><a name="Extending_nn15"></a>35.5.1 Strings</H3>
  867. <p>
  868. <b><tt>String *NewString(const String_or_char *val)</tt></b>
  869. </p>
  870. <div class="indent">
  871. Creates a new string with initial value <tt>val</tt>. <tt>val</tt> may
  872. be a <tt>char *</tt> or another <tt>String</tt> object. If you want
  873. to create an empty string, use "" for val.
  874. </div>
  875. <p>
  876. <b><tt>String *NewStringf(const char *fmt, ...)</tt></b>
  877. </p>
  878. <div class="indent">
  879. Creates a new string whose initial value is set according to a C <tt>printf</tt> style
  880. format string in <tt>fmt</tt>. Additional arguments follow depending
  881. on <tt>fmt</tt>.
  882. </div>
  883. <p>
  884. <b><tt>String *Copy(String *s)</tt></b>
  885. </p>
  886. <div class="indent">
  887. Make a copy of the string <tt>s</tt>.
  888. </div>
  889. <p>
  890. <b><tt>void Delete(String *s)</tt></b>
  891. </p>
  892. <div class="indent">
  893. Deletes <tt>s</tt>.
  894. </div>
  895. <p>
  896. <b><tt>int Len(const String_or_char *s)</tt></b>
  897. </p>
  898. <div class="indent">
  899. Returns the length of the string.
  900. </div>
  901. <p>
  902. <b><tt>char *Char(const String_or_char *s)</tt></b>
  903. </p>
  904. <div class="indent">
  905. Returns a pointer to the first character in a string.
  906. </div>
  907. <p>
  908. <b><tt>void Append(String *s, const String_or_char *t)</tt></b>
  909. </p>
  910. <div class="indent">
  911. Appends <tt>t</tt> to the end of string <tt>s</tt>.
  912. </div>
  913. <p>
  914. <b><tt>void Insert(String *s, int pos, const String_or_char *t)</tt></b>
  915. </p>
  916. <div class="indent">
  917. Inserts <tt>t</tt> into <tt>s</tt> at position <tt>pos</tt>. The contents
  918. of <tt>s</tt> are shifted accordingly. The special value <tt>DOH_END</tt>
  919. can be used for <tt>pos</tt> to indicate insertion at the end of the string (appending).
  920. </div>
  921. <p>
  922. <b><tt>int Strcmp(const String_or_char *s, const String_or_char *t)</tt></b>
  923. </p>
  924. <div class="indent">
  925. Compare strings <tt>s</tt> and <tt>t</tt>. Same as the C <tt>strcmp()</tt>
  926. function.
  927. </div>
  928. <p>
  929. <b><tt>int Strncmp(const String_or_char *s, const String_or_char *t, int len)</tt></b>
  930. </p>
  931. <div class="indent">
  932. Compare the first <tt>len</tt> characters of strings <tt>s</tt> and <tt>t</tt>. Same as the C <tt>strncmp()</tt>
  933. function.
  934. </div>
  935. <p>
  936. <b><tt>char *Strstr(const String_or_char *s, const String_or_char *pat)</tt></b>
  937. </p>
  938. <div class="indent">
  939. Returns a pointer to the first occurrence of <tt>pat</tt> in <tt>s</tt>.
  940. Same as the C <tt>strstr()</tt> function.
  941. </div>
  942. <p>
  943. <b><tt>char *Strchr(const String_or_char *s, char ch)</tt></b>
  944. </p>
  945. <div class="indent">
  946. Returns a pointer to the first occurrence of character <tt>ch</tt> in <tt>s</tt>.
  947. Same as the C <tt>strchr()</tt> function.
  948. </div>
  949. <p>
  950. <b><tt>void Chop(String *s)</tt></b>
  951. </p>
  952. <div class="indent">
  953. Chops trailing whitespace off the end of <tt>s</tt>.
  954. </div>
  955. <p>
  956. <b><tt>int Replace(String *s, const String_or_char *pat, const String_or_char *rep, int flags)</tt></b>
  957. </p>
  958. <div class="indent">
  959. <p>
  960. Replaces the pattern <tt>pat</tt> with <tt>rep</tt> in string <tt>s</tt>.
  961. <tt>flags</tt> is a combination of the following flags:</p>
  962. <div class="code">
  963. <pre>
  964. DOH_REPLACE_ANY - Replace all occurrences
  965. DOH_REPLACE_ID - Valid C identifiers only
  966. DOH_REPLACE_NOQUOTE - Don't replace in quoted strings
  967. DOH_REPLACE_FIRST - Replace first occurrence only.
  968. </pre>
  969. </div>
  970. <p>
  971. Returns the number of replacements made (if any).
  972. </p>
  973. </div>
  974. <H3><a name="Extending_nn16"></a>35.5.2 Hashes</H3>
  975. <p>
  976. <b><tt>Hash *NewHash()</tt></b>
  977. </p>
  978. <div class="indent">
  979. Creates a new empty hash table.
  980. </div>
  981. <p>
  982. <b><tt>Hash *Copy(Hash *h)</tt></b>
  983. </p>
  984. <div class="indent">
  985. Make a shallow copy of the hash <tt>h</tt>.
  986. </div>
  987. <p>
  988. <b><tt>void Delete(Hash *h)</tt></b>
  989. </p>
  990. <div class="indent">
  991. Deletes <tt>h</tt>.
  992. </div>
  993. <p>
  994. <b><tt>int Len(Hash *h)</tt></b>
  995. </p>
  996. <div class="indent">
  997. Returns the number of items in <tt>h</tt>.
  998. </div>
  999. <p>
  1000. <b><tt>Object *Getattr(Hash *h, const String_or_char *key)</tt></b>
  1001. </p>
  1002. <div class="indent">
  1003. Gets an object from <tt>h</tt>. <tt>key</tt> may be a string or
  1004. a simple <tt>char *</tt> string. Returns NULL if not found.
  1005. </div>
  1006. <p>
  1007. <b><tt>int Setattr(Hash *h, const String_or_char *key, const Object_or_char *val)</tt></b>
  1008. </p>
  1009. <div class="indent">
  1010. Stores <tt>val</tt> in <tt>h</tt>. <tt>key</tt> may be a string or
  1011. a simple <tt>char *</tt>. If <tt>val</tt> is not a standard
  1012. object (String, Hash, or List) it is assumed to be a <tt>char *</tt> in which
  1013. case it is used to construct a <tt>String</tt> that is stored in the hash.
  1014. If <tt>val</tt> is NULL, the object is deleted. Increases the reference count
  1015. of <tt>val</tt>. Returns 1 if this operation replaced an existing hash entry,
  1016. 0 otherwise.
  1017. </div>
  1018. <p>
  1019. <b><tt>int Delattr(Hash *h, const String_or_char *key)</tt></b>
  1020. </p>
  1021. <div class="indent">
  1022. Deletes the hash item referenced by <tt>key</tt>. Decreases the
  1023. reference count on the corresponding object (if any). Returns 1
  1024. if an object was removed, 0 otherwise.
  1025. </div>
  1026. <p>
  1027. <b><tt>List *Keys(Hash *h)</tt></b>
  1028. </p>
  1029. <div class="indent">
  1030. Returns the list of hash table keys.
  1031. </div>
  1032. <H3><a name="Extending_nn17"></a>35.5.3 Lists</H3>
  1033. <p>
  1034. <b><tt>List *NewList()</tt></b>
  1035. </p>
  1036. <div class="indent">
  1037. Creates a new empty list.
  1038. </div>
  1039. <p>
  1040. <b><tt>List *Copy(List *x)</tt></b>
  1041. </p>
  1042. <div class="indent">
  1043. Make a shallow copy of the List <tt>x</tt>.
  1044. </div>
  1045. <p>
  1046. <b><tt>void Delete(List *x)</tt></b>
  1047. </p>
  1048. <div class="indent">
  1049. Deletes <tt>x</tt>.
  1050. </div>
  1051. <p>
  1052. <b><tt>int Len(List *x)</tt></b>
  1053. </p>
  1054. <div class="indent">
  1055. Returns the number of items in <tt>x</tt>.
  1056. </div>
  1057. <p>
  1058. <b><tt>Object *Getitem(List *x, int n)</tt></b>
  1059. </p>
  1060. <div class="indent">
  1061. Returns an object from <tt>x</tt> with index <tt>n</tt>. If <tt>n</tt> is
  1062. beyond the end of the list, the last item is returned. If <tt>n</tt> is
  1063. negative, the first item is returned.
  1064. </div>
  1065. <p>
  1066. <b><tt>int *Setitem(List *x, int n, const Object_or_char *val)</tt></b>
  1067. </p>
  1068. <div class="indent">
  1069. Stores <tt>val</tt> in <tt>x</tt>.
  1070. If <tt>val</tt> is not a standard
  1071. object (String, Hash, or List) it is assumed to be a <tt>char *</tt> in which
  1072. case it is used to construct a <tt>String</tt> that is stored in the list.
  1073. <tt>n</tt> must be in range. Otherwise, an assertion will be raised.
  1074. </div>
  1075. <p>
  1076. <b><tt>int *Delitem(List *x, int n)</tt></b>
  1077. </p>
  1078. <div class="indent">
  1079. Deletes item <tt>n</tt> from the list, shifting items down if necessary.
  1080. To delete the last item in the list, use the special value <tt>DOH_END</tt>
  1081. for <tt>n</tt>.
  1082. </div>
  1083. <p>
  1084. <b><tt>void Append(List *x, const Object_or_char *t)</tt></b>
  1085. </p>
  1086. <div class="indent">
  1087. Appends <tt>t</tt> to the end of <tt>x</tt>. If <tt>t</tt> is not
  1088. a standard object, it is assumed to be a <tt>char *</tt> and is
  1089. used to create a String object.
  1090. </div>
  1091. <p>
  1092. <b><tt>void Insert(String *s, int pos, const Object_or_char *t)</tt></b>
  1093. </p>
  1094. <div class="indent">
  1095. Inserts <tt>t</tt> into <tt>s</tt> at position <tt>pos</tt>. The contents
  1096. of <tt>s</tt> are shifted accordingly. The special value <tt>DOH_END</tt>
  1097. can be used for <tt>pos</tt> to indicate insertion at the end of the list (appending).
  1098. If <tt>t</tt> is not a standard object, it is assumed to be a <tt>char *</tt>
  1099. and is used to create a String object.
  1100. </div>
  1101. <H3><a name="Extending_nn18"></a>35.5.4 Common operations</H3>
  1102. The following operations are applicable to all datatypes.
  1103. <p>
  1104. <b><tt>Object *Copy(Object *x)</tt></b>
  1105. </p>
  1106. <div class="indent">
  1107. Make a copy of the object <tt>x</tt>.
  1108. </div>
  1109. <p>
  1110. <b><tt>void Delete(Object *x)</tt></b>
  1111. </p>
  1112. <div class="indent">
  1113. Deletes <tt>x</tt>.
  1114. </div>
  1115. <p>
  1116. <b><tt>void Setfile(Object *x, String_or_char *f)</tt></b>
  1117. </p>
  1118. <div class="indent">
  1119. Sets the filename associated with <tt>x</tt>. Used to track
  1120. objects and report errors.
  1121. </div>
  1122. <p>
  1123. <b><tt>String *Getfile(Object *x)</tt></b>
  1124. </p>
  1125. <div class="indent">
  1126. Gets the filename associated with <tt>x</tt>.
  1127. </div>
  1128. <p>
  1129. <b><tt>void Setline(Object *x, int n)</tt></b>
  1130. </p>
  1131. <div class="indent">
  1132. Sets the line number associated with <tt>x</tt>. Used to track
  1133. objects and report errors.
  1134. </div>
  1135. <p>
  1136. <b><tt>int Getline(Object *x)</tt></b>
  1137. </p>
  1138. <div class="indent">
  1139. Gets the line number associated with <tt>x</tt>.
  1140. </div>
  1141. <H3><a name="Extending_nn19"></a>35.5.5 Iterating over Lists and Hashes</H3>
  1142. To iterate over the elements of a list or a hash table, the following functions are used:
  1143. <p>
  1144. <b><tt>Iterator First(Object *x)</tt></b>
  1145. </p>
  1146. <div class="indent">
  1147. Returns an iterator object that points to the first item in a list or hash table. The
  1148. <tt>item</tt> attribute of the Iterator object is a pointer to the item. For hash tables, the <tt>key</tt> attribute
  1149. of the Iterator object additionally points to the corresponding Hash table key. The <tt>item</tt> and <tt>key</tt> attributes
  1150. are NULL if the object contains no items or if there are no more items.
  1151. </div>
  1152. <p>
  1153. <b><tt>Iterator Next(Iterator i)</tt></b>
  1154. </p>
  1155. <div class="indent">
  1156. <p>Returns an iterator that points to the next item in a list or hash table.
  1157. Here are two examples of iteration:</p>
  1158. <div class="code">
  1159. <pre>
  1160. List *l = (some list);
  1161. Iterator i;
  1162. for (i = First(l); i.item; i = Next(i)) {
  1163. Printf(stdout,"%s\n", i.item);
  1164. }
  1165. Hash *h = (some hash);
  1166. Iterator j;
  1167. for (j = First(j); j.item; j= Next(j)) {
  1168. Printf(stdout,"%s : %s\n", j.key, j.item);
  1169. }
  1170. </pre>
  1171. </div>
  1172. </div>
  1173. <H3><a name="Extending_nn20"></a>35.5.6 I/O</H3>
  1174. Special I/O functions are used for all internal I/O. These operations
  1175. work on C <tt>FILE *</tt> objects, String objects, and special <tt>File</tt> objects
  1176. (which are merely a wrapper around <tt>FILE *</tt>).
  1177. <p>
  1178. <b><tt>int Printf(String_or_FILE *f, const char *fmt, ...)</tt></b>
  1179. </p>
  1180. <div class="indent">
  1181. Formatted I/O. Same as the C <tt>fprintf()</tt> function except that output
  1182. can also be directed to a string object. Note: the <tt>%s</tt> format
  1183. specifier works with both strings and <tt>char *</tt>. All other format
  1184. operators have the same meaning.
  1185. </div>
  1186. <p>
  1187. <b><tt>int Printv(String_or_FILE *f, String_or_char *arg1,..., NULL)</tt></b>
  1188. </p>
  1189. <div class="indent">
  1190. Prints a variable number of strings arguments to the output. The last
  1191. argument to this function must be NULL. The other arguments can either
  1192. be <tt>char *</tt> or string objects.
  1193. </div>
  1194. <p>
  1195. <b><tt>int Putc(int ch, String_or_FILE *f)</tt></b>
  1196. </p>
  1197. <div class="indent">
  1198. Same as the C <tt>fputc()</tt> function.
  1199. </div>
  1200. <p>
  1201. <b><tt>int Write(String_or_FILE *f, void *buf, int len)</tt></b>
  1202. </p>
  1203. <div class="indent">
  1204. Same as the C <tt>write()</tt> function.
  1205. </div>
  1206. <p>
  1207. <b><tt>int Read(String_or_FILE *f, void *buf, int maxlen)</tt></b>
  1208. </p>
  1209. <div class="indent">
  1210. Same as the C <tt>read()</tt> function.
  1211. </div>
  1212. <p>
  1213. <b><tt>int Getc(String_or_FILE *f)</tt></b>
  1214. </p>
  1215. <div class="indent">
  1216. Same as the C <tt>fgetc()</tt> function.
  1217. </div>
  1218. <p>
  1219. <b><tt>int Ungetc(int ch, String_or_FILE *f)</tt></b>
  1220. </p>
  1221. <div class="indent">
  1222. Same as the C <tt>ungetc()</tt> function.
  1223. </div>
  1224. <p>
  1225. <b><tt>int Seek(String_or_FILE *f, int offset, int whence)</tt></b>
  1226. </p>
  1227. <div class="indent">
  1228. Same as the C <tt>seek()</tt> function. <tt>offset</tt> is the number
  1229. of bytes. <tt>whence</tt> is one of <tt>SEEK_SET</tt>,<tt>SEEK_CUR</tt>,
  1230. or <tt>SEEK_END</tt>..
  1231. </div>
  1232. <p>
  1233. <b><tt>long Tell(String_or_FILE *f)</tt></b>
  1234. </p>
  1235. <div class="indent">
  1236. Same as the C <tt>tell()</tt> function.
  1237. </div>
  1238. <p>
  1239. <b><tt>File *NewFile(const char *filename, const char *mode, List *newfiles)</tt></b>
  1240. </p>
  1241. <div class="indent">
  1242. Create a File object using the <tt>fopen()</tt> library call. This
  1243. file differs from <tt>FILE *</tt> in that it can be placed in the standard
  1244. SWIG containers (lists, hashes, etc.). The <tt>filename</tt> is added to the
  1245. <tt>newfiles</tt> list if <tt>newfiles</tt> is non-zero and the file was created successfully.
  1246. </div>
  1247. <p>
  1248. <b><tt>File *NewFileFromFile(FILE *f)</tt></b>
  1249. </p>
  1250. <div class="indent">
  1251. Create a File object wrapper around an existing <tt>FILE *</tt> object.
  1252. </div>
  1253. <p>
  1254. <b><tt>int Close(String_or_FILE *f)</tt></b>
  1255. </p>
  1256. <div class="indent">
  1257. <p>Closes a file. Has no effect on strings.</p>
  1258. <p>
  1259. The use of the above I/O functions and strings play a critical role in SWIG. It is
  1260. common to see small code fragments of code generated using code like this:
  1261. </p>
  1262. <div class="code">
  1263. <pre>
  1264. /* Print into a string */
  1265. String *s = NewString("");
  1266. Printf(s,"Hello\n");
  1267. for (i = 0; i &lt; 10; i++) {
  1268. Printf(s,"%d\n", i);
  1269. }
  1270. ...
  1271. /* Print string into a file */
  1272. Printf(f, "%s\n", s);
  1273. </pre>
  1274. </div>
  1275. <p>
  1276. Similarly, the preprocessor and parser all operate on string-files.
  1277. </p>
  1278. </div>
  1279. <H2><a name="Extending_nn21"></a>35.6 Navigating and manipulating parse trees</H2>
  1280. Parse trees are built as collections of hash tables. Each node is a hash table in which
  1281. arbitrary attributes can be stored. Certain attributes in the hash table provide links to
  1282. other parse tree nodes. The following macros can be used to move around the parse tree.
  1283. <p>
  1284. <b><tt>String *nodeType(Node *n)</tt></b>
  1285. </p>
  1286. <div class="indent">
  1287. Returns the node type tag as a string. The returned string indicates the type of parse
  1288. tree node.
  1289. </div>
  1290. <p>
  1291. <b><tt>Node *nextSibling(Node *n)</tt></b>
  1292. </p>
  1293. <div class="indent">
  1294. Returns the next node in the parse tree. For example, the next C declaration.
  1295. </div>
  1296. <p>
  1297. <b><tt>Node *previousSibling(Node *n)</tt

Large files files are truncated, but you can click here to view the full file