Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <title>Extending SWIG</title> | |
5 | <link rel="stylesheet" type="text/css" href="style.css"> | |
6 | </head> | |
7 | ||
8 | <body bgcolor="#ffffff"> | |
9 | <H1><a name="Extending"></a>30 Extending SWIG</H1> | |
10 | <!-- INDEX --> | |
11 | <div class="sectiontoc"> | |
12 | <ul> | |
13 | <li><a href="#Extending_nn2">Introduction</a> | |
14 | <li><a href="#Extending_nn3">Prerequisites</a> | |
15 | <li><a href="#Extending_nn4">The Big Picture</a> | |
16 | <li><a href="#Extending_nn5">Execution Model</a> | |
17 | <ul> | |
18 | <li><a href="#Extending_nn6">Preprocessing</a> | |
19 | <li><a href="#Extending_nn7">Parsing</a> | |
20 | <li><a href="#Extending_nn8">Parse Trees</a> | |
21 | <li><a href="#Extending_nn9">Attribute namespaces</a> | |
22 | <li><a href="#Extending_nn10">Symbol Tables</a> | |
23 | <li><a href="#Extending_nn11">The %feature directive</a> | |
24 | <li><a href="#Extending_nn12">Code Generation</a> | |
25 | <li><a href="#Extending_nn13">SWIG and XML</a> | |
26 | </ul> | |
27 | <li><a href="#Extending_nn14">Primitive Data Structures</a> | |
28 | <ul> | |
29 | <li><a href="#Extending_nn15">Strings</a> | |
30 | <li><a href="#Extending_nn16">Hashes</a> | |
31 | <li><a href="#Extending_nn17">Lists</a> | |
32 | <li><a href="#Extending_nn18">Common operations</a> | |
33 | <li><a href="#Extending_nn19">Iterating over Lists and Hashes</a> | |
34 | <li><a href="#Extending_nn20">I/O</a> | |
35 | </ul> | |
36 | <li><a href="#Extending_nn21">Navigating and manipulating parse trees</a> | |
37 | <li><a href="#Extending_nn22">Working with attributes</a> | |
38 | <li><a href="#Extending_nn23">Type system</a> | |
39 | <ul> | |
40 | <li><a href="#Extending_nn24">String encoding of types</a> | |
41 | <li><a href="#Extending_nn25">Type construction</a> | |
42 | <li><a href="#Extending_nn26">Type tests</a> | |
43 | <li><a href="#Extending_nn27">Typedef and inheritance</a> | |
44 | <li><a href="#Extending_nn28">Lvalues</a> | |
45 | <li><a href="#Extending_nn29">Output functions</a> | |
46 | </ul> | |
47 | <li><a href="#Extending_nn30">Parameters</a> | |
48 | <li><a href="#Extending_nn31">Writing a Language Module</a> | |
49 | <ul> | |
50 | <li><a href="#Extending_nn32">Execution model</a> | |
51 | <li><a href="#Extending_nn33">Starting out</a> | |
52 | <li><a href="#Extending_nn34">Command line options</a> | |
53 | <li><a href="#Extending_nn35">Configuration and preprocessing</a> | |
54 | <li><a href="#Extending_nn36">Entry point to code generation</a> | |
55 | <li><a href="#Extending_nn37">Module I/O and wrapper skeleton</a> | |
56 | <li><a href="#Extending_nn38">Low-level code generators</a> | |
57 | <li><a href="#Extending_nn39">Configuration files</a> | |
58 | <li><a href="#Extending_nn40">Runtime support</a> | |
59 | <li><a href="#Extending_nn41">Standard library files</a> | |
60 | <li><a href="#Extending_nn42">Examples and test cases</a> | |
61 | <li><a href="#Extending_nn43">Documentation</a> | |
62 | </ul> | |
63 | <li><a href="#Extending_nn44">Typemaps</a> | |
64 | <ul> | |
65 | <li><a href="#Extending_nn45">Proxy classes</a> | |
66 | </ul> | |
67 | <li><a href="#Extending_nn46">Guide to parse tree nodes</a> | |
68 | </ul> | |
69 | </div> | |
70 | <!-- INDEX --> | |
71 | ||
72 | ||
73 | ||
74 | <p> | |
75 | <b>Caution: This chapter is being rewritten! (11/25/01)</b> | |
76 | </p> | |
77 | ||
78 | <H2><a name="Extending_nn2"></a>30.1 Introduction</H2> | |
79 | ||
80 | ||
81 | <p> | |
82 | This chapter describes SWIG's internal organization and the process by which | |
83 | new target languages can be developed. First, a brief word of warning---SWIG | |
84 | has been undergoing a massive redevelopment effort that has focused extensively | |
85 | on its internal organization. The information in this chapter is mostly up to | |
86 | date, but changes are ongoing. Expect a few inconsistencies. | |
87 | </p> | |
88 | ||
89 | <p> | |
90 | Also, this chapter is not meant to be a hand-holding tutorial. As a starting point, | |
91 | you should probably look at one of SWIG's existing modules. | |
92 | </p> | |
93 | ||
94 | <H2><a name="Extending_nn3"></a>30.2 Prerequisites</H2> | |
95 | ||
96 | ||
97 | <p> | |
98 | In order to extend SWIG, it is useful to have the following background: | |
99 | </p> | |
100 | ||
101 | <ul> | |
102 | <li>An understanding of the C API for the target language. | |
103 | <li>A good grasp of the C++ type system. | |
104 | <li>An understanding of typemaps and some of SWIG's advanced features. | |
105 | <li>Some familiarity with writing C++ (language modules are currently written in C++). | |
106 | </ul> | |
107 | ||
108 | <p> | |
109 | Since SWIG is essentially a specialized C++ compiler, it may be useful | |
110 | to have some prior experience with compiler design (perhaps even a | |
111 | compilers course) to better understand certain parts of the system. A | |
112 | number of books will also be useful. For example, "The C Programming | |
113 | Language" by Kernighan and Ritchie (a.k.a, "K&R") and the "C++ | |
114 | Annotated Reference Manual" by Stroustrup (a.k.a, the "ARM") will be of great use. | |
115 | </p> | |
116 | ||
117 | <p> | |
118 | Also, it is useful to keep in mind that SWIG primarily operates as an | |
119 | extension of the C++ <em>type</em> system. At first glance, this might not be | |
120 | obvious, but almost all SWIG directives as well as the low-level generation of | |
121 | wrapper code are driven by C++ datatypes. | |
122 | </p> | |
123 | ||
124 | <H2><a name="Extending_nn4"></a>30.3 The Big Picture</H2> | |
125 | ||
126 | ||
127 | <p> | |
128 | SWIG is a special purpose compiler that parses C++ declarations to | |
129 | generate wrapper code. To make this conversion possible, SWIG makes | |
130 | three fundamental extensions to the C++ language: | |
131 | </p> | |
132 | ||
133 | <ul> | |
134 | <li><b>Typemaps</b>. Typemaps are used to define the | |
135 | conversion/marshalling behavior of specific C++ datatypes. All type conversion in SWIG is | |
136 | based on typemaps. Furthermore, the association of typemaps to datatypes utilizes an advanced pattern matching | |
137 | mechanism that is fully integrated with the C++ type system. | |
138 | </li> | |
139 | ||
140 | <li><b>Declaration Annotation</b>. To customize wrapper code | |
141 | generation, most declarations can be annotated with special features. | |
142 | For example, you can make a variable read-only, you can ignore a | |
143 | declaration, you can rename a member function, you can add exception | |
144 | handling, and so forth. Virtually all of these customizations are built on top of a low-level | |
145 | declaration annotator that can attach arbitrary attributes to any declaration. | |
146 | Code generation modules can look for these attributes to guide the wrapping process. | |
147 | </li> | |
148 | ||
149 | <li><b>Class extension</b>. SWIG allows classes and structures to be extended with new | |
150 | methods and attributes (the <tt>%extend</tt> directive). This has the effect of altering | |
151 | the API in the target language and can be used to generate OO interfaces to C libraries. | |
152 | </ul> | |
153 | ||
154 | <p> | |
155 | It is important to emphasize that virtually all SWIG features reduce to one of these three | |
156 | fundamental concepts. The type system and pattern matching rules also play a critical | |
157 | role in making the system work. For example, both typemaps and declaration annotation are | |
158 | based on pattern matching and interact heavily with the underlying type system. | |
159 | </p> | |
160 | ||
161 | <H2><a name="Extending_nn5"></a>30.4 Execution Model</H2> | |
162 | ||
163 | ||
164 | <p> | |
165 | When you run SWIG on an interface, processing is handled in stages by a series of system components: | |
166 | </p> | |
167 | ||
168 | <ul> | |
169 | <li>An integrated C preprocessor reads a collection of configuration | |
170 | files and the specified interface file into memory. The preprocessor | |
171 | performs the usual functions including macro expansion and file | |
172 | inclusion. However, the preprocessor also performs some transformations of the | |
173 | interface. For instance, <tt>#define</tt> statements are sometimes transformed into | |
174 | <tt>%constant</tt> declarations. In addition, information related to file/line number | |
175 | tracking is inserted. | |
176 | </li> | |
177 | ||
178 | <li>A C/C++ parser reads the preprocessed input and generates a full | |
179 | parse tree of all of the SWIG directives and C declarations found. | |
180 | The parser is responsible for many aspects of the system including | |
181 | renaming, declaration annotation, and template expansion. However, the parser | |
182 | does not produce any output nor does it interact with the target | |
183 | language module as it runs. SWIG is not a one-pass compiler. | |
184 | </li> | |
185 | ||
186 | <li>A type-checking pass is made. This adjusts all of the C++ typenames to properly | |
187 | handle namespaces, typedefs, nested classes, and other issues related to type scoping. | |
188 | </li> | |
189 | ||
190 | <li>A semantic pass is made on the parse tree to collect information | |
191 | related to properties of the C++ interface. For example, this pass | |
192 | would determine whether or not a class allows a default constructor. | |
193 | </li> | |
194 | ||
195 | <li>A code generation pass is made using a specific target language | |
196 | module. This phase is responsible for generating the actual wrapper | |
197 | code. All of SWIG's user-defined modules are invoked during this | |
198 | stage of compilation. | |
199 | </li> | |
200 | </ul> | |
201 | ||
202 | <p> | |
203 | The next few sections briefly describe some of these stages. | |
204 | </p> | |
205 | ||
206 | <H3><a name="Extending_nn6"></a>30.4.1 Preprocessing</H3> | |
207 | ||
208 | ||
209 | <p> | |
210 | The preprocessor plays a critical role in the SWIG implementation. This is because a lot | |
211 | of SWIG's processing and internal configuration is managed not by code written in C, but | |
212 | by configuration files in the SWIG library. In fact, when you | |
213 | run SWIG, parsing starts with a small interface file like this (note: this explains | |
214 | the cryptic error messages that new users sometimes get when SWIG is misconfigured or installed | |
215 | incorrectly): | |
216 | </p> | |
217 | ||
218 | <div class="code"> | |
219 | <pre> | |
220 | %include "swig.swg" // Global SWIG configuration | |
221 | %include "<em>langconfig.swg</em>" // Language specific configuration | |
222 | %include "yourinterface.i" // Your interface file | |
223 | </pre> | |
224 | </div> | |
225 | ||
226 | <p> | |
227 | The <tt>swig.swg</tt> file contains global configuration information. In addition, this file | |
228 | defines many of SWIG's standard directives as macros. For instance, part of | |
229 | of <tt>swig.swg</tt> looks like this: | |
230 | </p> | |
231 | ||
232 | <div class="code"> | |
233 | <pre> | |
234 | ... | |
235 | /* Code insertion directives such as %wrapper %{ ... %} */ | |
236 | ||
237 | #define %init %insert("init") | |
238 | #define %wrapper %insert("wrapper") | |
239 | #define %header %insert("header") | |
240 | #define %runtime %insert("runtime") | |
241 | ||
242 | /* Access control directives */ | |
243 | ||
244 | #define %immutable %feature("immutable","1") | |
245 | #define %mutable %feature("immutable") | |
246 | ||
247 | /* Directives for callback functions */ | |
248 | ||
249 | #define %callback(x) %feature("callback") `x`; | |
250 | #define %nocallback %feature("callback"); | |
251 | ||
252 | /* %ignore directive */ | |
253 | ||
254 | #define %ignore %rename($ignore) | |
255 | #define %ignorewarn(x) %rename("$ignore:" x) | |
256 | ... | |
257 | </pre> | |
258 | </div> | |
259 | ||
260 | <p> | |
261 | The fact that most of the standard SWIG directives are macros is | |
262 | intended to simplify the implementation of the internals. For instance, | |
263 | rather than having to support dozens of special directives, it is | |
264 | easier to have a few basic primitives such as <tt>%feature</tt> or | |
265 | <tt>%insert</tt>. | |
266 | </p> | |
267 | ||
268 | <p> | |
269 | The <em><tt>langconfig.swg</tt></em> file is supplied by the target | |
270 | language. This file contains language-specific configuration | |
271 | information. More often than not, this file provides run-time wrapper | |
272 | support code (e.g., the type-checker) as well as a collection of | |
273 | typemaps that define the default wrapping behavior. Note: the name of this | |
274 | file depends on the target language and is usually something like <tt>python.swg</tt> | |
275 | or <tt>perl5.swg</tt>. | |
276 | </p> | |
277 | ||
278 | <p> | |
279 | As a debugging aide, the text that SWIG feeds to its C++ parser can be | |
280 | obtained by running <tt>swig -E interface.i</tt>. This output | |
281 | probably isn't too useful in general, but it will show how macros have | |
282 | been expanded as well as everything else that goes into the low-level | |
283 | construction of the wrapper code. | |
284 | </p> | |
285 | ||
286 | <H3><a name="Extending_nn7"></a>30.4.2 Parsing</H3> | |
287 | ||
288 | ||
289 | <p> | |
290 | The current C++ parser handles a subset of C++. Most incompatibilities with C are due to | |
291 | subtle aspects of how SWIG parses declarations. Specifically, SWIG expects all C/C++ declarations to follow this general form: | |
292 | </p> | |
293 | ||
294 | <div class="diagram"> | |
295 | <pre> | |
296 | <em>storage</em> <em>type</em> <em>declarator</em> <em>initializer</em>; | |
297 | </pre> | |
298 | </div> | |
299 | ||
300 | <p> | |
301 | <tt><em>storage</em></tt> is a keyword such as <tt>extern</tt>, | |
302 | <tt>static</tt>, <tt>typedef</tt>, or <tt>virtual</tt>. <tt><em>type</em></tt> is a primitive | |
303 | datatype such as <tt>int</tt> or <tt>void</tt>. <tt><em>type</em></tt> may be optionally | |
304 | qualified with a qualifier such as <tt>const</tt> or <tt>volatile</tt>. <tt><em>declarator</em></tt> | |
305 | is a name with additional type-construction modifiers attached to it (pointers, arrays, references, | |
306 | functions, etc.). Examples of declarators include <tt>*x</tt>, <tt>**x</tt>, <tt>x[20]</tt>, and | |
307 | <tt>(*x)(int,double)</tt>. The <tt><em>initializer</em></tt> may be a value assigned using <tt>=</tt> or | |
308 | body of code enclosed in braces <tt>{ ... }</tt>. | |
309 | </p> | |
310 | ||
311 | <p> | |
312 | This declaration format covers most common C++ declarations. However, the C++ standard | |
313 | is somewhat more flexible in the placement of the parts. For example, it is technically legal, although | |
314 | uncommon to write something like <tt>int typedef const a</tt> in your program. SWIG simply | |
315 | doesn't bother to deal with this case. | |
316 | </p> | |
317 | ||
318 | <p> | |
319 | The other significant difference between C++ and SWIG is in the | |
320 | treatment of typenames. In C++, if you have a declaration like this, | |
321 | </p> | |
322 | ||
323 | <div class="code"> | |
324 | <pre> | |
325 | int blah(Foo *x, Bar *y); | |
326 | </pre> | |
327 | </div> | |
328 | ||
329 | <p> | |
330 | it won't parse correctly unless <tt>Foo</tt> and <tt>Bar</tt> have | |
331 | been previously defined as types either using a <tt>class</tt> | |
332 | definition or a <tt>typedef</tt>. The reasons for this are subtle, | |
333 | but this treatment of typenames is normally integrated at the level of the C | |
334 | tokenizer---when a typename appears, a different token is returned to the parser | |
335 | instead of an identifier. | |
336 | </p> | |
337 | ||
338 | <p> | |
339 | SWIG does not operate in this manner--any legal identifier can be used | |
340 | as a type name. The reason for this is primarily motivated by the use | |
341 | of SWIG with partially defined data. Specifically, | |
342 | SWIG is supposed to be easy to use on interfaces with missing type information. | |
343 | </p> | |
344 | ||
345 | <p> | |
346 | Because of the different treatment of typenames, the most serious | |
347 | limitation of the SWIG parser is that it can't process type declarations where | |
348 | an extra (and unnecessary) grouping operator is used. For example: | |
349 | </p> | |
350 | ||
351 | <div class="code"> | |
352 | <pre> | |
353 | int (x); /* A variable x */ | |
354 | int (y)(int); /* A function y */ | |
355 | </pre> | |
356 | </div> | |
357 | ||
358 | <p> | |
359 | The placing of extra parentheses in type declarations like this is | |
360 | already recognized by the C++ community as a potential source of | |
361 | strange programming errors. For example, Scott Meyers "Effective STL" | |
362 | discusses this problem in a section on avoiding C++'s "most vexing | |
363 | parse." | |
364 | </p> | |
365 | ||
366 | <p> | |
367 | The parser is also unable to handle declarations with no return type or bare argument names. | |
368 | For example, in an old C program, you might see things like this: | |
369 | </p> | |
370 | ||
371 | <div class="code"> | |
372 | <pre> | |
373 | foo(a,b) { | |
374 | ... | |
375 | } | |
376 | </pre> | |
377 | </div> | |
378 | ||
379 | <p> | |
380 | In this case, the return type as well as the types of the arguments | |
381 | are taken by the C compiler to be an <tt>int</tt>. However, SWIG | |
382 | interprets the above code as an abstract declarator for a function | |
383 | returning a <tt>foo</tt> and taking types <tt>a</tt> and <tt>b</tt> as | |
384 | arguments). | |
385 | </p> | |
386 | ||
387 | <H3><a name="Extending_nn8"></a>30.4.3 Parse Trees</H3> | |
388 | ||
389 | ||
390 | <p> | |
391 | The SWIG parser produces a complete parse tree of the input file before any wrapper code | |
392 | is actually generated. Each item in the tree is known as a "Node". Each node is identified | |
393 | by a symbolic tag. Furthermore, a node may have an arbitrary number of children. | |
394 | The parse tree structure and tag names of an interface can be displayed using <tt>swig -dump_tags</tt>. | |
395 | For example: | |
396 | </p> | |
397 | ||
398 | <div class="shell"> | |
399 | <pre> | |
400 | $ <b>swig -c++ -python -dump_tags example.i</b> | |
401 | . top (example.i:1) | |
402 | . top . include (example.i:1) | |
403 | . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/swig.swg:71) | |
404 | . top . include . typemap . typemapitem (/r0/beazley/Projects/lib/swig1.3/swig.swg:71) | |
405 | . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/swig.swg:83) | |
406 | . top . include . typemap . typemapitem (/r0/beazley/Projects/lib/swig1.3/swig.swg:83) | |
407 | . top . include (example.i:4) | |
408 | . top . include . insert (/r0/beazley/Projects/lib/swig1.3/python/python.swg:7) | |
409 | . top . include . insert (/r0/beazley/Projects/lib/swig1.3/python/python.swg:8) | |
410 | . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/python/python.swg:19) | |
411 | ... | |
412 | . top . include (example.i:6) | |
413 | . top . include . module (example.i:2) | |
414 | . top . include . insert (example.i:6) | |
415 | . top . include . include (example.i:9) | |
416 | . top . include . include . class (example.h:3) | |
417 | . top . include . include . class . access (example.h:4) | |
418 | . top . include . include . class . constructor (example.h:7) | |
419 | . top . include . include . class . destructor (example.h:10) | |
420 | . top . include . include . class . cdecl (example.h:11) | |
421 | . top . include . include . class . cdecl (example.h:11) | |
422 | . top . include . include . class . cdecl (example.h:12) | |
423 | . top . include . include . class . cdecl (example.h:13) | |
424 | . top . include . include . class . cdecl (example.h:14) | |
425 | . top . include . include . class . cdecl (example.h:15) | |
426 | . top . include . include . class (example.h:18) | |
427 | . top . include . include . class . access (example.h:19) | |
428 | . top . include . include . class . cdecl (example.h:20) | |
429 | . top . include . include . class . access (example.h:21) | |
430 | . top . include . include . class . constructor (example.h:22) | |
431 | . top . include . include . class . cdecl (example.h:23) | |
432 | . top . include . include . class . cdecl (example.h:24) | |
433 | . top . include . include . class (example.h:27) | |
434 | . top . include . include . class . access (example.h:28) | |
435 | . top . include . include . class . cdecl (example.h:29) | |
436 | . top . include . include . class . access (example.h:30) | |
437 | . top . include . include . class . constructor (example.h:31) | |
438 | . top . include . include . class . cdecl (example.h:32) | |
439 | . top . include . include . class . cdecl (example.h:33) | |
440 | </pre> | |
441 | </div> | |
442 | ||
443 | <p> | |
444 | Even for the most simple interface, the parse tree structure is larger than you might expect. For example, in the | |
445 | above output, a substantial number of nodes are actually generated by the <tt>python.swg</tt> configuration file | |
446 | which defines typemaps and other directives. The contents of the user-supplied input file don't appear until the end | |
447 | of the output. | |
448 | </p> | |
449 | ||
450 | <p> | |
451 | The contents of each parse tree node consist of a collection of attribute/value | |
452 | pairs. Internally, the nodes are simply represented by hash tables. A display of | |
453 | the parse-tree structure can be obtained using <tt>swig -dump_tree</tt>. For example: | |
454 | </p> | |
455 | ||
456 | <div class="shell"> | |
457 | <pre> | |
458 | $ swig -c++ -python -dump_tree example.i | |
459 | ... | |
460 | +++ include ---------------------------------------- | |
461 | | name - "example.i" | |
462 | ||
463 | +++ module ---------------------------------------- | |
464 | | name - "example" | |
465 | | | |
466 | +++ insert ---------------------------------------- | |
467 | | code - "\n#include \"example.h\"\n" | |
468 | | | |
469 | +++ include ---------------------------------------- | |
470 | | name - "example.h" | |
471 | ||
472 | +++ class ---------------------------------------- | |
473 | | abstract - "1" | |
474 | | sym:name - "Shape" | |
475 | | name - "Shape" | |
476 | | kind - "class" | |
477 | | symtab - 0x40194140 | |
478 | | sym:symtab - 0x40191078 | |
479 | ||
480 | +++ access ---------------------------------------- | |
481 | | kind - "public" | |
482 | | | |
483 | +++ constructor ---------------------------------------- | |
484 | | sym:name - "Shape" | |
485 | | name - "Shape" | |
486 | | decl - "f()." | |
487 | | code - "{\n nshapes++;\n }" | |
488 | | sym:symtab - 0x40194140 | |
489 | | | |
490 | +++ destructor ---------------------------------------- | |
491 | | sym:name - "~Shape" | |
492 | | name - "~Shape" | |
493 | | storage - "virtual" | |
494 | | code - "{\n nshapes--;\n }" | |
495 | | sym:symtab - 0x40194140 | |
496 | | | |
497 | +++ cdecl ---------------------------------------- | |
498 | | sym:name - "x" | |
499 | | name - "x" | |
500 | | decl - "" | |
501 | | type - "double" | |
502 | | sym:symtab - 0x40194140 | |
503 | | | |
504 | +++ cdecl ---------------------------------------- | |
505 | | sym:name - "y" | |
506 | | name - "y" | |
507 | | decl - "" | |
508 | | type - "double" | |
509 | | sym:symtab - 0x40194140 | |
510 | | | |
511 | +++ cdecl ---------------------------------------- | |
512 | | sym:name - "move" | |
513 | | name - "move" | |
514 | | decl - "f(double,double)." | |
515 | | parms - double ,double | |
516 | | type - "void" | |
517 | | sym:symtab - 0x40194140 | |
518 | | | |
519 | +++ cdecl ---------------------------------------- | |
520 | | sym:name - "area" | |
521 | | name - "area" | |
522 | | decl - "f(void)." | |
523 | | parms - void | |
524 | | storage - "virtual" | |
525 | | value - "0" | |
526 | | type - "double" | |
527 | | sym:symtab - 0x40194140 | |
528 | | | |
529 | +++ cdecl ---------------------------------------- | |
530 | | sym:name - "perimeter" | |
531 | | name - "perimeter" | |
532 | | decl - "f(void)." | |
533 | | parms - void | |
534 | | storage - "virtual" | |
535 | | value - "0" | |
536 | | type - "double" | |
537 | | sym:symtab - 0x40194140 | |
538 | | | |
539 | +++ cdecl ---------------------------------------- | |
540 | | sym:name - "nshapes" | |
541 | | name - "nshapes" | |
542 | | decl - "" | |
543 | | storage - "static" | |
544 | | type - "int" | |
545 | | sym:symtab - 0x40194140 | |
546 | | | |
547 | +++ class ---------------------------------------- | |
548 | | sym:name - "Circle" | |
549 | | name - "Circle" | |
550 | | kind - "class" | |
551 | | bases - 0x40194510 | |
552 | | symtab - 0x40194538 | |
553 | | sym:symtab - 0x40191078 | |
554 | ||
555 | +++ access ---------------------------------------- | |
556 | | kind - "private" | |
557 | | | |
558 | +++ cdecl ---------------------------------------- | |
559 | | name - "radius" | |
560 | | decl - "" | |
561 | | type - "double" | |
562 | | | |
563 | +++ access ---------------------------------------- | |
564 | | kind - "public" | |
565 | | | |
566 | +++ constructor ---------------------------------------- | |
567 | | sym:name - "Circle" | |
568 | | name - "Circle" | |
569 | | parms - double | |
570 | | decl - "f(double)." | |
571 | | code - "{ }" | |
572 | | sym:symtab - 0x40194538 | |
573 | | | |
574 | +++ cdecl ---------------------------------------- | |
575 | | sym:name - "area" | |
576 | | name - "area" | |
577 | | decl - "f(void)." | |
578 | | parms - void | |
579 | | storage - "virtual" | |
580 | | type - "double" | |
581 | | sym:symtab - 0x40194538 | |
582 | | | |
583 | +++ cdecl ---------------------------------------- | |
584 | | sym:name - "perimeter" | |
585 | | name - "perimeter" | |
586 | | decl - "f(void)." | |
587 | | parms - void | |
588 | | storage - "virtual" | |
589 | | type - "double" | |
590 | | sym:symtab - 0x40194538 | |
591 | | | |
592 | +++ class ---------------------------------------- | |
593 | | sym:name - "Square" | |
594 | | name - "Square" | |
595 | | kind - "class" | |
596 | | bases - 0x40194760 | |
597 | | symtab - 0x40194788 | |
598 | | sym:symtab - 0x40191078 | |
599 | ||
600 | +++ access ---------------------------------------- | |
601 | | kind - "private" | |
602 | | | |
603 | +++ cdecl ---------------------------------------- | |
604 | | name - "width" | |
605 | | decl - "" | |
606 | | type - "double" | |
607 | | | |
608 | +++ access ---------------------------------------- | |
609 | | kind - "public" | |
610 | | | |
611 | +++ constructor ---------------------------------------- | |
612 | | sym:name - "Square" | |
613 | | name - "Square" | |
614 | | parms - double | |
615 | | decl - "f(double)." | |
616 | | code - "{ }" | |
617 | | sym:symtab - 0x40194788 | |
618 | | | |
619 | +++ cdecl ---------------------------------------- | |
620 | | sym:name - "area" | |
621 | | name - "area" | |
622 | | decl - "f(void)." | |
623 | | parms - void | |
624 | | storage - "virtual" | |
625 | | type - "double" | |
626 | | sym:symtab - 0x40194788 | |
627 | | | |
628 | +++ cdecl ---------------------------------------- | |
629 | | sym:name - "perimeter" | |
630 | | name - "perimeter" | |
631 | | decl - "f(void)." | |
632 | | parms - void | |
633 | | storage - "virtual" | |
634 | | type - "double" | |
635 | | sym:symtab - 0x40194788 | |
636 | </pre> | |
637 | </div> | |
638 | ||
639 | <H3><a name="Extending_nn9"></a>30.4.4 Attribute namespaces</H3> | |
640 | ||
641 | ||
642 | <p> | |
643 | Attributes of parse tree nodes are often prepended with a namespace qualifier. | |
644 | For example, the attributes | |
645 | <tt>sym:name</tt> and <tt>sym:symtab</tt> are attributes related to | |
646 | symbol table management and are prefixed with <tt>sym:</tt>. As a | |
647 | general rule, only those attributes which are directly related to the raw declaration | |
648 | appear without a prefix (type, name, declarator, etc.). | |
649 | </p> | |
650 | ||
651 | <p> | |
652 | Target language modules may add additional attributes to nodes to assist the generation | |
653 | of wrapper code. The convention for doing this is to place these attributes in a namespace | |
654 | that matches the name of the target language. For example, <tt>python:foo</tt> or | |
655 | <tt>perl:foo</tt>. | |
656 | </p> | |
657 | ||
658 | <H3><a name="Extending_nn10"></a>30.4.5 Symbol Tables</H3> | |
659 | ||
660 | ||
661 | <p> | |
662 | During parsing, all symbols are managed in the space of the target | |
663 | language. The <tt>sym:name</tt> attribute of each node contains the symbol name | |
664 | selected by the parser. Normally, <tt>sym:name</tt> and <tt>name</tt> | |
665 | are the same. However, the <tt>%rename</tt> directive can be used to | |
666 | change the value of <tt>sym:name</tt>. You can see the effect of | |
667 | <tt>%rename</tt> by trying it on a simple interface and dumping the | |
668 | parse tree. For example: | |
669 | </p> | |
670 | ||
671 | <div class="code"> | |
672 | <pre> | |
673 | %rename(foo_i) foo(int); | |
674 | %rename(foo_d) foo(double); | |
675 | ||
676 | void foo(int); | |
677 | void foo(double); | |
678 | void foo(Bar *b); | |
679 | </pre> | |
680 | </div> | |
681 | ||
682 | <p> | |
683 | Now, running SWIG: | |
684 | </p> | |
685 | ||
686 | <div class="shell"> | |
687 | <pre> | |
688 | $ swig -dump_tree example.i | |
689 | ... | |
690 | +++ cdecl ---------------------------------------- | |
691 | | sym:name - "foo_i" | |
692 | | name - "foo" | |
693 | | decl - "f(int)." | |
694 | | parms - int | |
695 | | type - "void" | |
696 | | sym:symtab - 0x40165078 | |
697 | | | |
698 | +++ cdecl ---------------------------------------- | |
699 | | sym:name - "foo_d" | |
700 | | name - "foo" | |
701 | | decl - "f(double)." | |
702 | | parms - double | |
703 | | type - "void" | |
704 | | sym:symtab - 0x40165078 | |
705 | | | |
706 | +++ cdecl ---------------------------------------- | |
707 | | sym:name - "foo" | |
708 | | name - "foo" | |
709 | | decl - "f(p.Bar)." | |
710 | | parms - Bar * | |
711 | | type - "void" | |
712 | | sym:symtab - 0x40165078 | |
713 | </pre> | |
714 | </div> | |
715 | ||
716 | <p> | |
717 | All symbol-related conflicts and complaints about overloading are based on <tt>sym:name</tt> values. | |
718 | For instance, the following example uses <tt>%rename</tt> in reverse to generate a name clash. | |
719 | </p> | |
720 | ||
721 | <div class="code"> | |
722 | <pre> | |
723 | %rename(foo) foo_i(int); | |
724 | %rename(foo) foo_d(double; | |
725 | ||
726 | void foo_i(int); | |
727 | void foo_d(double); | |
728 | void foo(Bar *b); | |
729 | </pre> | |
730 | </div> | |
731 | ||
732 | <p> | |
733 | When you run SWIG on this you now get: | |
734 | </p> | |
735 | ||
736 | <div class="shell"> | |
737 | <pre> | |
738 | $ ./swig example.i | |
739 | example.i:6. Overloaded declaration ignored. foo_d(double ) | |
740 | example.i:5. Previous declaration is foo_i(int ) | |
741 | example.i:7. Overloaded declaration ignored. foo(Bar *) | |
742 | example.i:5. Previous declaration is foo_i(int ) | |
743 | </pre> | |
744 | </div> | |
745 | ||
746 | <H3><a name="Extending_nn11"></a>30.4.6 The %feature directive</H3> | |
747 | ||
748 | ||
749 | <p> | |
750 | A number of SWIG directives such as <tt>%exception</tt> are implemented using the | |
751 | low-level <tt>%feature</tt> directive. For example: | |
752 | </p> | |
753 | ||
754 | <div class="code"> | |
755 | <pre> | |
756 | %feature("except") getitem(int) { | |
757 | try { | |
758 | $action | |
759 | } catch (badindex) { | |
760 | ... | |
761 | } | |
762 | } | |
763 | ||
764 | ... | |
765 | class Foo { | |
766 | public: | |
767 | Object *getitem(int index) throws(badindex); | |
768 | ... | |
769 | }; | |
770 | </pre> | |
771 | </div> | |
772 | ||
773 | <p> | |
774 | The behavior of <tt>%feature</tt> is very easy to describe--it simply | |
775 | attaches a new attribute to any parse tree node that matches the | |
776 | given prototype. When a feature is added, it shows up as an attribute in the <tt>feature:</tt> namespace. | |
777 | You can see this when running with the <tt>-dump_tree</tt> option. For example: | |
778 | </p> | |
779 | ||
780 | <div class="shell"> | |
781 | <pre> | |
782 | +++ cdecl ---------------------------------------- | |
783 | | sym:name - "getitem" | |
784 | | name - "getitem" | |
785 | | decl - "f(int).p." | |
786 | | parms - int | |
787 | | type - "Object" | |
788 | | feature:except - "{\n try {\n $action\n } catc..." | |
789 | | sym:symtab - 0x40168ac8 | |
790 | | | |
791 | </pre> | |
792 | </div> | |
793 | ||
794 | <p> | |
795 | Feature names are completely arbitrary and a target language module can be | |
796 | programmed to respond to any feature name that it wants to recognized. The | |
797 | data stored in a feature attribute is usually just a raw unparsed string. | |
798 | For example, the exception code above is simply | |
799 | stored without any modifications. | |
800 | </p> | |
801 | ||
802 | <H3><a name="Extending_nn12"></a>30.4.7 Code Generation</H3> | |
803 | ||
804 | ||
805 | <p> | |
806 | Language modules work by defining handler functions that know how to respond to | |
807 | different types of parse-tree nodes. These handlers simply look at the | |
808 | attributes of each node in order to produce low-level code. | |
809 | </p> | |
810 | ||
811 | <p> | |
812 | In reality, the generation of code is somewhat more subtle than simply | |
813 | invoking handler functions. This is because parse-tree nodes might be | |
814 | transformed. For example, suppose you are wrapping a class like this: | |
815 | </p> | |
816 | ||
817 | <div class="code"> | |
818 | <pre> | |
819 | class Foo { | |
820 | public: | |
821 | virtual int *bar(int x); | |
822 | }; | |
823 | </pre> | |
824 | </div> | |
825 | ||
826 | <p> | |
827 | When the parser constructs a node for the member <tt>bar</tt>, it creates a raw "cdecl" node with the following | |
828 | attributes: | |
829 | </p> | |
830 | ||
831 | <div class="diagram"> | |
832 | <pre> | |
833 | nodeType : cdecl | |
834 | name : bar | |
835 | type : int | |
836 | decl : f(int).p | |
837 | parms : int x | |
838 | storage : virtual | |
839 | sym:name : bar | |
840 | </pre> | |
841 | </div> | |
842 | ||
843 | <p> | |
844 | 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: | |
845 | </p> | |
846 | ||
847 | <div class="diagram"> | |
848 | <pre> | |
849 | nodeType : cdecl | |
850 | name : bar | |
851 | type : p.int <-- Notice change in return type | |
852 | decl : f(int).p | |
853 | parms : int x | |
854 | storage : virtual | |
855 | sym:name : bar | |
856 | </pre> | |
857 | </div> | |
858 | ||
859 | <p> | |
860 | Next, the context of the node indicates that the node is really a | |
861 | member function. This produces a transformation to a low-level | |
862 | accessor function like this: | |
863 | </p> | |
864 | ||
865 | <div class="diagram"> | |
866 | <pre> | |
867 | nodeType : cdecl | |
868 | name : bar | |
869 | type : int.p | |
870 | decl : f(int).p | |
871 | parms : Foo *self, int x <-- Added parameter | |
872 | storage : virtual | |
873 | wrap:action : result = (arg1)->bar(arg2) <-- Action code added | |
874 | sym:name : Foo_bar <-- Symbol name changed | |
875 | </pre> | |
876 | </div> | |
877 | ||
878 | <p> | |
879 | In this transformation, notice how an additional parameter was added | |
880 | to the parameter list and how the symbol name of the node has suddenly | |
881 | changed into an accessor using the naming scheme described in the | |
882 | "SWIG Basics" chapter. A small fragment of "action" code has also | |
883 | been generated--notice how the <tt>wrap:action</tt> attribute defines | |
884 | the access to the underlying method. The data in this transformed | |
885 | node is then used to generate a wrapper. | |
886 | </p> | |
887 | ||
888 | <p> | |
889 | Language modules work by registering handler functions for dealing with | |
890 | various types of nodes at different stages of transformation. This is done by | |
891 | inheriting from a special <tt>Language</tt> class and defining a collection | |
892 | of virtual methods. For example, the Python module defines a class as | |
893 | follows: | |
894 | </p> | |
895 | ||
896 | <div class="code"> | |
897 | <pre> | |
898 | class PYTHON : public Language { | |
899 | protected: | |
900 | public : | |
901 | virtual void main(int, char *argv[]); | |
902 | virtual int top(Node *); | |
903 | virtual int functionWrapper(Node *); | |
904 | virtual int constantWrapper(Node *); | |
905 | virtual int variableWrapper(Node *); | |
906 | virtual int nativeWrapper(Node *); | |
907 | virtual int membervariableHandler(Node *); | |
908 | virtual int memberconstantHandler(Node *); | |
909 | virtual int memberfunctionHandler(Node *); | |
910 | virtual int constructorHandler(Node *); | |
911 | virtual int destructorHandler(Node *); | |
912 | virtual int classHandler(Node *); | |
913 | virtual int classforwardDeclaration(Node *); | |
914 | virtual int insertDirective(Node *); | |
915 | virtual int importDirective(Node *); | |
916 | }; | |
917 | </pre> | |
918 | </div> | |
919 | ||
920 | <p> | |
921 | The role of these functions is described shortly. | |
922 | </p> | |
923 | ||
924 | <H3><a name="Extending_nn13"></a>30.4.8 SWIG and XML</H3> | |
925 | ||
926 | ||
927 | <p> | |
928 | Much of SWIG's current parser design was originally motivated by | |
929 | interest in using XML to represent SWIG parse trees. Although XML is | |
930 | not currently used in any direct manner, the parse tree structure, use | |
931 | of node tags, attributes, and attribute namespaces are all influenced | |
932 | by aspects of XML parsing. Therefore, in trying to understand SWIG's | |
933 | internal data structures, it may be useful keep XML in the back of | |
934 | your mind as a model. | |
935 | </p> | |
936 | ||
937 | <H2><a name="Extending_nn14"></a>30.5 Primitive Data Structures</H2> | |
938 | ||
939 | ||
940 | <p> | |
941 | Most of SWIG is constructed using three basic data structures: | |
942 | strings, hashes, and lists. These data structures are dynamic in same way as | |
943 | similar structures found in many scripting languages. For instance, | |
944 | you can have containers (lists and hash tables) of mixed types and | |
945 | certain operations are polymorphic. | |
946 | </p> | |
947 | ||
948 | <p> | |
949 | This section briefly describes the basic structures so that later | |
950 | sections of this chapter make more sense. | |
951 | </p> | |
952 | ||
953 | <p> | |
954 | When describing the low-level API, the following type name conventions are | |
955 | used: | |
956 | </p> | |
957 | ||
958 | <ul> | |
959 | <li><tt>String</tt>. A string object. | |
960 | <li><tt>Hash</tt>. A hash object. | |
961 | <li><tt>List</tt>. A list object. | |
962 | <li><tt>String_or_char</tt>. A string object or a <tt>char *</tt>. | |
963 | <li><tt>Object_or_char</tt>. An object or a <tt>char *</tt>. | |
964 | <li><tt>Object</tt>. Any object (string, hash, list, etc.) | |
965 | </ul> | |
966 | ||
967 | <p> | |
968 | In most cases, other typenames in the source are aliases for one of these | |
969 | primitive types. Specifically: | |
970 | </p> | |
971 | ||
972 | <div class="code"> | |
973 | <pre> | |
974 | typedef String SwigType; | |
975 | typedef Hash Parm; | |
976 | typedef Hash ParmList; | |
977 | typedef Hash Node; | |
978 | typedef Hash Symtab; | |
979 | typedef Hash Typetab; | |
980 | </pre> | |
981 | </div> | |
982 | ||
983 | <H3><a name="Extending_nn15"></a>30.5.1 Strings</H3> | |
984 | ||
985 | ||
986 | <p> | |
987 | <b><tt>String *NewString(const String_or_char *val)</tt></b> | |
988 | </p> | |
989 | ||
990 | <div class="indent"> | |
991 | Creates a new string with initial value <tt>val</tt>. <tt>val</tt> may | |
992 | be a <tt>char *</tt> or another <tt>String</tt> object. If you want | |
993 | to create an empty string, use "" for val. | |
994 | </div> | |
995 | ||
996 | <p> | |
997 | <b><tt>String *NewStringf(const char *fmt, ...)</tt></b> | |
998 | </p> | |
999 | ||
1000 | <div class="indent"> | |
1001 | Creates a new string whose initial value is set according to a C <tt>printf</tt> style | |
1002 | format string in <tt>fmt</tt>. Additional arguments follow depending | |
1003 | on <tt>fmt</tt>. | |
1004 | </div> | |
1005 | ||
1006 | <p> | |
1007 | <b><tt>String *Copy(String *s)</tt></b> | |
1008 | </p> | |
1009 | ||
1010 | <div class="indent"> | |
1011 | Make a copy of the string <tt>s</tt>. | |
1012 | </div> | |
1013 | ||
1014 | <p> | |
1015 | <b><tt>void Delete(String *s)</tt></b> | |
1016 | </p> | |
1017 | ||
1018 | <div class="indent"> | |
1019 | Deletes <tt>s</tt>. | |
1020 | </div> | |
1021 | ||
1022 | <p> | |
1023 | <b><tt>int Len(String_or_char *s)</tt></b> | |
1024 | </p> | |
1025 | ||
1026 | <div class="indent"> | |
1027 | Returns the length of the string. | |
1028 | </div> | |
1029 | ||
1030 | <p> | |
1031 | <b><tt>char *Char(String_or_char *s)</tt></b> | |
1032 | </p> | |
1033 | ||
1034 | <div class="indent"> | |
1035 | Returns a pointer to the first character in a string. | |
1036 | </div> | |
1037 | ||
1038 | <p> | |
1039 | <b><tt>void Append(String *s, String_or_char *t)</tt></b> | |
1040 | </p> | |
1041 | ||
1042 | <div class="indent"> | |
1043 | Appends <tt>t</tt> to the end of string <tt>s</tt>. | |
1044 | </div> | |
1045 | ||
1046 | <p> | |
1047 | <b><tt>void Insert(String *s, int pos, String_or_char *t)</tt></b> | |
1048 | </p> | |
1049 | ||
1050 | <div class="indent"> | |
1051 | Inserts <tt>t</tt> into <tt>s</tt> at position <tt>pos</tt>. The contents | |
1052 | of <tt>s</tt> are shifted accordingly. The special value <tt>DOH_END</tt> | |
1053 | can be used for <tt>pos</tt> to indicate insertion at the end of the string (appending). | |
1054 | </div> | |
1055 | ||
1056 | <p> | |
1057 | <b><tt>int Strcmp(const String_or_char *s, const String_or_char *t)</tt></b> | |
1058 | </p> | |
1059 | ||
1060 | <div class="indent"> | |
1061 | Compare strings <tt>s</tt> and <tt>t</tt>. Same as the C <tt>strcmp()</tt> | |
1062 | function. | |
1063 | </div> | |
1064 | ||
1065 | <p> | |
1066 | <b><tt>int Strncmp(const String_or_char *s, const String_or_char *t, int len)</tt></b> | |
1067 | </p> | |
1068 | ||
1069 | <div class="indent"> | |
1070 | Compare the first <tt>len</tt> characters of strings <tt>s</tt> and <tt>t</tt>. Same as the C <tt>strncmp()</tt> | |
1071 | function. | |
1072 | </div> | |
1073 | ||
1074 | <p> | |
1075 | <b><tt>char *Strstr(const String_or_char *s, const String_or_char *pat)</tt></b> | |
1076 | </p> | |
1077 | ||
1078 | <div class="indent"> | |
1079 | Returns a pointer to the first occurrence of <tt>pat</tt> in <tt>s</tt>. | |
1080 | Same as the C <tt>strstr()</tt> function. | |
1081 | </div> | |
1082 | ||
1083 | <p> | |
1084 | <b><tt>char *Strchr(const String_or_char *s, char ch)</tt></b> | |
1085 | </p> | |
1086 | ||
1087 | <div class="indent"> | |
1088 | Returns a pointer to the first occurrence of character <tt>ch</tt> in <tt>s</tt>. | |
1089 | Same as the C <tt>strchr()</tt> function. | |
1090 | </div> | |
1091 | ||
1092 | <p> | |
1093 | <b><tt>void Chop(String *s)</tt></b> | |
1094 | </p> | |
1095 | ||
1096 | <div class="indent"> | |
1097 | Chops trailing whitespace off the end of <tt>s</tt>. | |
1098 | </div> | |
1099 | ||
1100 | <p> | |
1101 | <b><tt>int Replace(String *s, const String_or_char *pat, const String_or_char *rep, int flags)</tt></b> | |
1102 | </p> | |
1103 | ||
1104 | <div class="indent"> | |
1105 | <p> | |
1106 | Replaces the pattern <tt>pat</tt> with <tt>rep</tt> in string <tt>s</tt>. | |
1107 | <tt>flags</tt> is a combination of the following flags:</p> | |
1108 | ||
1109 | <div class="code"> | |
1110 | <pre> | |
1111 | DOH_REPLACE_ANY - Replace all occurrences | |
1112 | DOH_REPLACE_ID - Valid C identifiers only | |
1113 | DOH_REPLACE_NOQUOTE - Don't replace in quoted strings | |
1114 | DOH_REPLACE_FIRST - Replace first occurrence only. | |
1115 | </pre> | |
1116 | </div> | |
1117 | ||
1118 | <p> | |
1119 | Returns the number of replacements made (if any). | |
1120 | </p> | |
1121 | ||
1122 | </div> | |
1123 | ||
1124 | <H3><a name="Extending_nn16"></a>30.5.2 Hashes</H3> | |
1125 | ||
1126 | ||
1127 | <p> | |
1128 | <b><tt>Hash *NewHash()</tt></b> | |
1129 | </p> | |
1130 | ||
1131 | <div class="indent"> | |
1132 | Creates a new empty hash table. | |
1133 | </div> | |
1134 | ||
1135 | <p> | |
1136 | <b><tt>Hash *Copy(Hash *h)</tt></b> | |
1137 | </p> | |
1138 | ||
1139 | <div class="indent"> | |
1140 | Make a shallow copy of the hash <tt>h</tt>. | |
1141 | </div> | |
1142 | ||
1143 | <p> | |
1144 | <b><tt>void Delete(Hash *h)</tt></b> | |
1145 | </p> | |
1146 | ||
1147 | <div class="indent"> | |
1148 | Deletes <tt>h</tt>. | |
1149 | </div> | |
1150 | ||
1151 | <p> | |
1152 | <b><tt>int Len(Hash *h)</tt></b> | |
1153 | </p> | |
1154 | ||
1155 | <div class="indent"> | |
1156 | Returns the number of items in <tt>h</tt>. | |
1157 | </div> | |
1158 | ||
1159 | <p> | |
1160 | <b><tt>Object *Getattr(Hash *h, String_or_char *key)</tt></b> | |
1161 | </p> | |
1162 | ||
1163 | <div class="indent"> | |
1164 | Gets an object from <tt>h</tt>. <tt>key</tt> may be a string or | |
1165 | a simple <tt>char *</tt> string. Returns NULL if not found. | |
1166 | </div> | |
1167 | ||
1168 | <p> | |
1169 | <b><tt>int Setattr(Hash *h, String_or_char *key, Object_or_char *val)</tt></b> | |
1170 | </p> | |
1171 | ||
1172 | <div class="indent"> | |
1173 | Stores <tt>val</tt> in <tt>h</tt>. <tt>key</tt> may be a string or | |
1174 | a simple <tt>char *</tt>. If <tt>val</tt> is not a standard | |
1175 | object (String, Hash, or List) it is assumed to be a <tt>char *</tt> in which | |
1176 | case it is used to construct a <tt>String</tt> that is stored in the hash. | |
1177 | If <tt>val</tt> is NULL, the object is deleted. Increases the reference count | |
1178 | of <tt>val</tt>. Returns 1 if this operation replaced an existing hash entry, | |
1179 | 0 otherwise. | |
1180 | </div> | |
1181 | ||
1182 | <p> | |
1183 | <b><tt>int Delattr(Hash *h, String_or_char *key)</tt></b> | |
1184 | </p> | |
1185 | ||
1186 | <div class="indent"> | |
1187 | Deletes the hash item referenced by <tt>key</tt>. Decreases the | |
1188 | reference count on the corresponding object (if any). Returns 1 | |
1189 | if an object was removed, 0 otherwise. | |
1190 | </div> | |
1191 | ||
1192 | <p> | |
1193 | <b><tt>List *Keys(Hash *h)</tt></b> | |
1194 | </p> | |
1195 | ||
1196 | <div class="indent"> | |
1197 | Returns the list of hash table keys. | |
1198 | </div> | |
1199 | ||
1200 | ||
1201 | <H3><a name="Extending_nn17"></a>30.5.3 Lists</H3> | |
1202 | ||
1203 | ||
1204 | <p> | |
1205 | <b><tt>List *NewList()</tt></b> | |
1206 | </p> | |
1207 | ||
1208 | <div class="indent"> | |
1209 | Creates a new empty list. | |
1210 | </div> | |
1211 | ||
1212 | <p> | |
1213 | <b><tt>List *Copy(List *x)</tt></b> | |
1214 | </p> | |
1215 | ||
1216 | <div class="indent"> | |
1217 | Make a shallow copy of the List <tt>x</tt>. | |
1218 | </div> | |
1219 | ||
1220 | <p> | |
1221 | <b><tt>void Delete(List *x)</tt></b> | |
1222 | </p> | |
1223 | ||
1224 | <div class="indent"> | |
1225 | Deletes <tt>x</tt>. | |
1226 | </div> | |
1227 | ||
1228 | <p> | |
1229 | <b><tt>int Len(List *x)</tt></b> | |
1230 | </p> | |
1231 | ||
1232 | <div class="indent"> | |
1233 | Returns the number of items in <tt>x</tt>. | |
1234 | </div> | |
1235 | ||
1236 | <p> | |
1237 | <b><tt>Object *Getitem(List *x, int n)</tt></b> | |
1238 | </p> | |
1239 | ||
1240 | <div class="indent"> | |
1241 | Returns an object from <tt>x</tt> with index <tt>n</tt>. If <tt>n</tt> is | |
1242 | beyond the end of the list, the last item is returned. If <tt>n</tt> is | |
1243 | negative, the first item is returned. | |
1244 | </div> | |
1245 | ||
1246 | <p> | |
1247 | <b><tt>int *Setitem(List *x, int n, Object_or_char *val)</tt></b> | |
1248 | </p> | |
1249 | ||
1250 | <div class="indent"> | |
1251 | Stores <tt>val</tt> in <tt>x</tt>. | |
1252 | If <tt>val</tt> is not a standard | |
1253 | object (String, Hash, or List) it is assumed to be a <tt>char *</tt> in which | |
1254 | case it is used to construct a <tt>String</tt> that is stored in the list. | |
1255 | <tt>n</tt> must be in range. Otherwise, an assertion will be raised. | |
1256 | </div> | |
1257 | ||
1258 | <p> | |
1259 | <b><tt>int *Delitem(List *x, int n)</tt></b> | |
1260 | </p> | |
1261 | ||
1262 | <div class="indent"> | |
1263 | Deletes item <tt>n</tt> from the list, shifting items down if necessary. | |
1264 | To delete the last item in the list, use the special value <tt>DOH_END</tt> | |
1265 | for <tt>n</tt>. | |
1266 | </div> | |
1267 | ||
1268 | <p> | |
1269 | <b><tt>void Append(List *x, Object_or_char *t)</tt></b> | |
1270 | </p> | |
1271 | ||
1272 | <div class="indent"> | |
1273 | Appends <tt>t</tt> to the end of <tt>x</tt>. If <tt>t</tt> is not | |
1274 | a standard object, it is assumed to be a <tt>char *</tt> and is | |
1275 | used to create a String object. | |
1276 | </div> | |
1277 | ||
1278 | <p> | |
1279 | <b><tt>void Insert(String *s, int pos, Object_or_char *t)</tt></b> | |
1280 | </p> | |
1281 | ||
1282 | <div class="indent"> | |
1283 | Inserts <tt>t</tt> into <tt>s</tt> at position <tt>pos</tt>. The contents | |
1284 | of <tt>s</tt> are shifted accordingly. The special value <tt>DOH_END</tt> | |
1285 | can be used for <tt>pos</tt> to indicate insertion at the end of the list (appending). | |
1286 | If <tt>t</tt> is not a standard object, it is assumed to be a <tt>char *</tt> | |
1287 | and is used to create a String object. | |
1288 | </div> | |
1289 | ||
1290 | <H3><a name="Extending_nn18"></a>30.5.4 Common operations</H3> | |
1291 | ||
1292 | ||
1293 | The following operations are applicable to all datatypes. | |
1294 | ||
1295 | <p> | |
1296 | <b><tt>Object *Copy(Object *x)</tt></b> | |
1297 | </p> | |
1298 | ||
1299 | <div class="indent"> | |
1300 | Make a copy of the object <tt>x</tt>. | |
1301 | </div> | |
1302 | ||
1303 | <p> | |
1304 | <b><tt>void Delete(Object *x)</tt></b> | |
1305 | </p> | |
1306 | ||
1307 | <div class="indent"> | |
1308 | Deletes <tt>x</tt>. | |
1309 | </div> | |
1310 | ||
1311 | <p> | |
1312 | <b><tt>void Setfile(Object *x, String_or_char *f)</tt></b> | |
1313 | </p> | |
1314 | ||
1315 | <div class="indent"> | |
1316 | Sets the filename associated with <tt>x</tt>. Used to track | |
1317 | objects and report errors. | |
1318 | </div> | |
1319 | ||
1320 | <p> | |
1321 | <b><tt>String *Getfile(Object *x)</tt></b> | |
1322 | </p> | |
1323 | ||
1324 | <div class="indent"> | |
1325 | Gets the filename associated with <tt>x</tt>. | |
1326 | </div> | |
1327 | ||
1328 | <p> | |
1329 | <b><tt>void Setline(Object *x, int n)</tt></b> | |
1330 | </p> | |
1331 | ||
1332 | <div class="indent"> | |
1333 | Sets the line number associated with <tt>x</tt>. Used to track | |
1334 | objects and report errors. | |
1335 | </div> | |
1336 | ||
1337 | <p> | |
1338 | <b><tt>int Getline(Object *x)</tt></b> | |
1339 | </p> | |
1340 | ||
1341 | <div class="indent"> | |
1342 | Gets the line number associated with <tt>x</tt>. | |
1343 | </div> | |
1344 | ||
1345 | <H3><a name="Extending_nn19"></a>30.5.5 Iterating over Lists and Hashes</H3> | |
1346 | ||
1347 | ||
1348 | To iterate over the elements of a list or a hash table, the following functions are used: | |
1349 | ||
1350 | <p> | |
1351 | <b><tt>Iterator First(Object *x)</tt></b> | |
1352 | </p> | |
1353 | ||
1354 | <div class="indent"> | |
1355 | Returns an iterator object that points to the first item in a list or hash table. The | |
1356 | <tt>item</tt> attribute of the Iterator object is a pointer to the item. For hash tables, the <tt>key</tt> attribute | |
1357 | of the Iterator object additionally points to the corresponding Hash table key. The <tt>item</tt> and <tt>key</tt> attributes | |
1358 | are NULL if the object contains no items or if there are no more items. | |
1359 | </div> | |
1360 | ||
1361 | <p> | |
1362 | <b><tt>Iterator Next(Iterator i)</tt></b> | |
1363 | </p> | |
1364 | ||
1365 | <div class="indent"> | |
1366 | <p>Returns an iterator that points to the next item in a list or hash table. | |
1367 | ||
1368 | Here are two examples of iteration:</p> | |
1369 | ||
1370 | <div class="code"> | |
1371 | <pre> | |
1372 | List *l = (some list); | |
1373 | Iterator i; | |
1374 | ||
1375 | for (i = First(l); i.item; i = Next(i)) { | |
1376 | Printf(stdout,"%s\n", i.item); | |
1377 | } | |
1378 | ||
1379 | Hash *h = (some hash); | |
1380 | Iterator j; | |
1381 | ||
1382 | for (j = First(j); j.item; j= Next(j)) { | |
1383 | Printf(stdout,"%s : %s\n", j.key, j.item); | |
1384 | } | |
1385 | </pre> | |
1386 | </div> | |
1387 | ||
1388 | </div> | |
1389 | ||
1390 | <H3><a name="Extending_nn20"></a>30.5.6 I/O</H3> | |
1391 | ||
1392 | ||
1393 | Special I/O functions are used for all internal I/O. These operations | |
1394 | work on C <tt>FILE *</tt> objects, String objects, and special <tt>File</tt> objects | |
1395 | (which are merely a wrapper around <tt>FILE *</tt>). | |
1396 | ||
1397 | <p> | |
1398 | <b><tt>int Printf(String_or_FILE *f, const char *fmt, ...)</tt></b> | |
1399 | </p> | |
1400 | ||
1401 | <div class="indent"> | |
1402 | Formatted I/O. Same as the C <tt>fprintf()</tt> function except that output | |
1403 | can also be directed to a string object. Note: the <tt>%s</tt> format | |
1404 | specifier works with both strings and <tt>char *</tt>. All other format | |
1405 | operators have the same meaning. | |
1406 | </div> | |
1407 | ||
1408 | <p> | |
1409 | <b><tt>int Printv(String_or_FILE *f, String_or_char *arg1,..., NULL)</tt></b> | |
1410 | </p> | |
1411 | ||
1412 | <div class="indent"> | |
1413 | Prints a variable number of strings arguments to the output. The last | |
1414 | argument to this function must be NULL. The other arguments can either | |
1415 | be <tt>char *</tt> or string objects. | |
1416 | </div> | |
1417 | ||
1418 | <p> | |
1419 | <b><tt>int Putc(int ch, String_or_FILE *f)</tt></b> | |
1420 | </p> | |
1421 | ||
1422 | <div class="indent"> | |
1423 | Same as the C <tt>fputc()</tt> function. | |
1424 | </div> | |
1425 | ||
1426 | <p> | |
1427 | <b><tt>int Write(String_or_FILE *f, void *buf, int len)</tt></b> | |
1428 | </p> | |
1429 | ||
1430 | <div class="indent"> | |
1431 | Same as the C <tt>write()</tt> function. | |
1432 | </div> | |
1433 | ||
1434 | <p> | |
1435 | <b><tt>int Read(String_or_FILE *f, void *buf, int maxlen)</tt></b> | |
1436 | </p> | |
1437 | ||
1438 | <div class="indent"> | |
1439 | Same as the C <tt>read()</tt> function. | |
1440 | </div> | |
1441 | ||
1442 | <p> | |
1443 | <b><tt>int Getc(String_or_FILE *f)</tt></b> | |
1444 | </p> | |
1445 | ||
1446 | <div class="indent"> | |
1447 | Same as the C <tt>fgetc()</tt> function. | |
1448 | </div> | |
1449 | ||
1450 | <p> | |
1451 | <b><tt>int Ungetc(int ch, String_or_FILE *f)</tt></b> | |
1452 | </p> | |
1453 | ||
1454 | <div class="indent"> | |
1455 | Same as the C <tt>ungetc()</tt> function. | |
1456 | </div> | |
1457 | ||
1458 | <p> | |
1459 | <b><tt>int Seek(String_or_FILE *f, int offset, int whence)</tt></b> | |
1460 | </p> | |
1461 | ||
1462 | <div class="indent"> | |
1463 | Same as the C <tt>seek()</tt> function. <tt>offset</tt> is the number | |
1464 | of bytes. <tt>whence</tt> is one of <tt>SEEK_SET</tt>,<tt>SEEK_CUR</tt>, | |
1465 | or <tt>SEEK_END</tt>.. | |
1466 | </div> | |
1467 | ||
1468 | <p> | |
1469 | <b><tt>long Tell(String_or_FILE *f)</tt></b> | |
1470 | </p> | |
1471 | ||
1472 | <div class="indent"> | |
1473 | Same as the C <tt>tell()</tt> function. | |
1474 | </div> | |
1475 | ||
1476 | <p> | |
1477 | <b><tt>File *NewFile(const char *filename, const char *mode)</tt></b> | |
1478 | </p> | |
1479 | ||
1480 | <div class="indent"> | |
1481 | Create a File object using the <tt>fopen()</tt> library call. This | |
1482 | file differs from <tt>FILE *</tt> in that it can be placed in the standard | |
1483 | SWIG containers (lists, hashes, etc.). | |
1484 | </div> | |
1485 | ||
1486 | <p> | |
1487 | <b><tt>File *NewFileFromFile(FILE *f)</tt></b> | |
1488 | </p> | |
1489 | ||
1490 | <div class="indent"> | |
1491 | Create a File object wrapper around an existing <tt>FILE *</tt> object. | |
1492 | </div> | |
1493 | ||
1494 | <p> | |
1495 | <b><tt>int Close(String_or_FILE *f)</tt></b> | |
1496 | </p> | |
1497 | ||
1498 | <div class="indent"> | |
1499 | <p>Closes a file. Has no effect on strings.</p> | |
1500 | ||
1501 | <p> | |
1502 | The use of the above I/O functions and strings play a critical role in SWIG. It is | |
1503 | common to see small code fragments of code generated using code like this: | |
1504 | </p> | |
1505 | ||
1506 | <div class="code"> | |
1507 | <pre> | |
1508 | /* Print into a string */ | |
1509 | String *s = NewString(""); | |
1510 | Printf(s,"Hello\n"); | |
1511 | for (i = 0; i < 10; i++) { | |
1512 | Printf(s,"%d\n", i); | |
1513 | } | |
1514 | ... | |
1515 | /* Print string into a file */ | |
1516 | Printf(f, "%s\n", s); | |
1517 | </pre> | |
1518 | </div> | |
1519 | ||
1520 | <p> | |
1521 | Similarly, the preprocessor and parser all operate on string-files. | |
1522 | </p> | |
1523 | ||
1524 | </div> | |
1525 | ||
1526 | <H2><a name="Extending_nn21"></a>30.6 Navigating and manipulating parse trees</H2> | |
1527 | ||
1528 | ||
1529 | Parse trees are built as collections of hash tables. Each node is a hash table in which | |
1530 | arbitrary attributes can be stored. Certain attributes in the hash table provide links to | |
1531 | other parse tree nodes. The following macros can be used to move around the parse tree. | |
1532 | ||
1533 | <p> | |
1534 | <b><tt>String *nodeType(Node *n)</tt></b> | |
1535 | </p> | |
1536 | ||
1537 | <div class="indent"> | |
1538 | Returns the node type tag as a string. The returned string indicates the type of parse | |
1539 | tree node. | |
1540 | </div> | |
1541 | ||
1542 | <p> | |
1543 | <b><tt>Node *nextSibling(Node *n)</tt></b> | |
1544 | </p> | |
1545 | ||
1546 | <div class="indent"> | |
1547 | Returns the next node in the parse tree. For example, the next C declaration. | |
1548 | </div> | |
1549 | ||
1550 | <p> | |
1551 | <b><tt>Node *previousSibling(Node *n)</tt></b> | |
1552 | </p> | |
1553 | ||
1554 | <div class="indent"> | |
1555 | Returns the previous node in the parse tree. For example, the previous C declaration. | |
1556 | </div> | |
1557 | ||
1558 | <p> | |
1559 | <b><tt>Node *firstChild(Node *n)</tt></b> | |
1560 | </p> | |
1561 | ||
1562 | <div class="indent"> | |
1563 | Returns the first child node. For example, if <tt>n</tt> was a C++ class node, this would | |
1564 | return the node for the first class member. | |
1565 | </div> | |
1566 | ||
1567 | <p> | |
1568 | <b><tt>Node *lastChild(Node *n)</tt></b> | |
1569 | </p> | |
1570 | ||
1571 | <div class="indent"> | |
1572 | Returns the last child node. You might use this if you wanted to append a new | |
1573 | node to the of a class. | |
1574 | </div> | |
1575 | ||
1576 | <p> | |
1577 | <b><tt>Node *parentNode(Node *n)</tt></b> | |
1578 | </p> | |
1579 | ||
1580 | <div class="indent"> | |
1581 | Returns the parent of node <tt>n</tt>. Use this to move up the pass tree. | |
1582 | </div> | |
1583 | ||
1584 | <p> | |
1585 | The following macros can be used to change all of the above attributes. | |
1586 | Normally, these functions are only used by the parser. Changing them without | |
1587 | knowing what you are doing is likely to be dangerous. | |
1588 | </p> | |
1589 | ||
1590 | <p> | |
1591 | <b><tt>void set_nodeType(Node *n, const String_or_char)</tt></b> | |
1592 | </p> | |
1593 | ||
1594 | <div class="indent"> | |
1595 | Change the node type. | |
1596 | tree node. | |
1597 | </div> | |
1598 | ||
1599 | <p> | |
1600 | <b><tt>void set_nextSibling(Node *n, Node *s)</tt></b> | |
1601 | </p> | |
1602 | ||
1603 | <div class="indent"> | |
1604 | Set the next sibling. | |
1605 | </div> | |
1606 | ||
1607 | <p> | |
1608 | <b><tt>void set_previousSibling(Node *n, Node *s)</tt></b> | |
1609 | </p> | |
1610 | ||
1611 | <div class="indent"> | |
1612 | Set the previous sibling. | |
1613 | </div> | |
1614 | ||
1615 | <p> | |
1616 | <b><tt>void set_firstChild(Node *n, Node *c)</tt></b> | |
1617 | </p> | |
1618 | ||
1619 | <div class="indent"> | |
1620 | Set the first child node. | |
1621 | </div> | |
1622 | ||
1623 | <p> | |
1624 | <b><tt>void set_lastChild(Node *n, Node *c)</tt></b> | |
1625 | </p> | |
1626 | ||
1627 | <div class="indent"> | |
1628 | Set the last child node. | |
1629 | </div> | |
1630 | ||
1631 | <p> | |
1632 | <b><tt>void set_parentNode(Node *n, Node *p)</tt></b> | |
1633 | </p> | |
1634 | ||
1635 | <div class="indent"> | |
1636 | Set the parent node. | |
1637 | </div> | |
1638 | ||
1639 | <p> | |
1640 | The following utility functions are used to alter the parse tree (at your own risk) | |
1641 | </p> | |
1642 | ||
1643 | <p> | |
1644 | <b><tt>void appendChild(Node *parent, Node *child)</tt></b> | |
1645 | </p> | |
1646 | ||
1647 | <div class="indent"> | |
1648 | Append a child to <tt>parent</tt>. The appended node becomes the last child. | |
1649 | </div> | |
1650 | ||
1651 | <p> | |
1652 | <b><tt>void deleteNode(Node *node)</tt></b> | |
1653 | </p> | |
1654 | ||
1655 | <div class="indent"> | |
1656 | Deletes a node from the parse tree. Deletion reconnects siblings and properly updates | |
1657 | the parent so that sibling nodes are unaffected. | |
1658 | </div> | |
1659 | ||
1660 | <H2><a name="Extending_nn22"></a>30.7 Working with attributes</H2> | |
1661 | ||
1662 | ||
1663 | <p> | |
1664 | Since parse tree nodes are just hash tables, attributes are accessed using the <tt>Getattr()</tt>, | |
1665 | <tt>Setattr()</tt>, and <tt>Delattr()</tt> operations. For example: | |
1666 | </p> | |
1667 | ||
1668 | <div class="code"> | |
1669 | <pre> | |
1670 | int functionHandler(Node *n) { | |
1671 | String *name = Getattr(n,"name"); | |
1672 | String *symname = Getattr(n,"sym:name"); | |
1673 | SwigType *type = Getattr(n,"type"); | |
1674 | ... | |
1675 | } | |
1676 | </pre> | |
1677 | </div> | |
1678 | ||
1679 | <p> | |
1680 | New attributes can be freely attached to a node as needed. However, when new attributes | |
1681 | are attached during code generation, they should be prepended with a namespace prefix. | |
1682 | For example: | |
1683 | </p> | |
1684 | ||
1685 | <div class="code"> | |
1686 | <pre> | |
1687 | ... | |
1688 | Setattr(n,"python:docstring", doc); /* Store docstring */ | |
1689 | ... | |
1690 | </pre> | |
1691 | </div> | |
1692 | ||
1693 | <p> | |
1694 | A quick way to check the value of an attribute is to use the <tt>checkAttribute()</tt> function like this: | |
1695 | </p> | |
1696 | ||
1697 | <div class="code"> | |
1698 | <pre> | |
1699 | if (checkAttribute(n,"storage","virtual")) { | |
1700 | /* n is virtual */ | |
1701 | ... | |
1702 | } | |
1703 | </pre> | |
1704 | </div> | |
1705 | ||
1706 | <p> | |
1707 | Changing the values of existing attributes is allowed and is sometimes done to implement | |
1708 | node transformations. However, if a function/method modifies a node, it is required to restore | |
1709 | modified attributes to their original values. To simplify the task of saving/restoring attributes, | |
1710 | the following functions are used: | |
1711 | </p> | |
1712 | ||
1713 | <p> | |
1714 | <b><tt>int Swig_save(const char *ns, Node *n, const char *name1, const char *name2, ..., NIL)</tt></b> | |
1715 | </p> | |
1716 | ||
1717 | <div class="indent"> | |
1718 | Saves a copy of attributes <tt>name1</tt>, <tt>name2</tt>, etc. from node <tt>n</tt>. | |
1719 | Copies of the attributes are actually resaved in the node in a different namespace which is | |
1720 | set by the <tt>ns</tt> argument. For example, if you call <tt>Swig_save("foo",n,"type",NIL)</tt>, | |
1721 | then the "type" attribute will be copied and saved as "foo:type". The namespace name itself is stored in | |
1722 | the "view" attribute of the node. If necessary, this can be examined to find out where previous | |
1723 | values of attributes might have been saved. | |
1724 | </div> | |
1725 | ||
1726 | <p> | |
1727 | <b><tt>int Swig_restore(Node *n)</tt></b> | |
1728 | </p> | |
1729 | ||
1730 | <div class="indent"> | |
1731 | ||
1732 | <p> | |
1733 | Restores the attributes saved by the previous call to <tt>Swig_save()</tt>. Those | |
1734 | attributes that were supplied to <tt>Swig_save()</tt> will be restored to their | |
1735 | original values. | |
1736 | </p> | |
1737 | ||
1738 | <p> | |
1739 | The <tt>Swig_save()</tt> and <tt>Swig_restore()</tt> functions must always be used as a pair. | |
1740 | That is, every call to <tt>Swig_save()</tt> must have a matching call to <tt>Swig_restore()</tt>. | |
1741 | Calls can be nested if necessary. Here is an example that shows how the functions might be used: | |
1742 | </p> | |
1743 | ||
1744 | <div class="code"> | |
1745 | <pre> | |
1746 | int variableHandler(Node *n) { | |
1747 | Swig_save("variableHandler",n,"type","sym:name",NIL); | |
1748 | String *symname = Getattr(n,"sym:name"); | |
1749 | SwigType *type = Getattr(n,"type"); | |
1750 | ... | |
1751 | Append(symname,"_global"); // Change symbol name | |
1752 | SwigType_add_pointer(type); // Add pointer | |
1753 | ... | |
1754 | generate wrappers | |
1755 | ... | |
1756 | Swig_restore(n); // Restore original values | |
1757 | return SWIG_OK; | |
1758 | } | |
1759 | </pre> | |
1760 | </div> | |
1761 | ||
1762 | </div> | |
1763 | ||
1764 | <p> | |
1765 | <b><tt>int Swig_require(const char *ns, Node *n, const char *name1, const char *name2, ..., NIL)</tt></b> | |
1766 | </p> | |
1767 | ||
1768 | <div class="indent"> | |
1769 | This is an enhanced version of <tt>Swig_save()</tt> that adds error checking. If an attribute | |
1770 | name is not present in <tt>n</tt>, a failed assertion results and SWIG terminates with a fatal | |
1771 | error. Optionally, if an attribute name is specified as "*<em>name</em>", a copy of the | |
1772 | attribute is saved as with <tt>Swig_save()</tt>. If an attribute is specified as "?<em>name</em>", | |
1773 | the attribute is optional. <tt>Swig_restore()</tt> must always be called after using this | |
1774 | function. | |
1775 | </div> | |
1776 | ||
1777 | <H2><a name="Extending_nn23"></a>30.8 Type system</H2> | |
1778 | ||
1779 | ||
1780 | <p> | |
1781 | SWIG implements the complete C++ type system including typedef, inheritance, | |
1782 | pointers, references, and pointers to members. A detailed discussion of | |
1783 | type theory is impossible here. However, let's cover the highlights. | |
1784 | </p> | |
1785 | ||
1786 | <H3><a name="Extending_nn24"></a>30.8.1 String encoding of types</H3> | |
1787 | ||
1788 | ||
1789 | <p> | |
1790 | All types in SWIG consist of a base datatype and a collection of type | |
1791 | operators that are applied to the base. A base datatype is almost | |
1792 | always some kind of primitive type such as <tt>int</tt> or <tt>double</tt>. | |
1793 | The operators consist of things like pointers, references, arrays, and so forth. | |
1794 | Internally, types are represented as strings that are constructed in a very | |
1795 | precise manner. Here are some examples: | |
1796 | </p> | |
1797 | ||
1798 | <div class="diagram"> | |
1799 | <pre> | |
1800 | C datatype SWIG encoding (strings) | |
1801 | ----------------------------- -------------------------- | |
1802 | int "int" | |
1803 | int * "p.int" | |
1804 | const int * "p.q(const).int" | |
1805 | int (*x)(int,double) "p.f(int,double).int" | |
1806 | int [20][30] "a(20).a(30).int" | |
1807 | int (F::*)(int) "m(F).f(int).int" | |
1808 | vector<int> * "p.vector<(int)>" | |
1809 | </pre> | |
1810 | </div> | |
1811 | ||
1812 | <p> | |
1813 | Reading the SWIG encoding is often easier than figuring out the C code---just | |
1814 | read it from left to right. For a type of "p.f(int,double).int" is | |
1815 | a "pointer to a function(int,double) that returns int". | |
1816 | </p> | |
1817 | ||
1818 | <p> | |
1819 | The following operator encodings are used in type strings: | |
1820 | </p> | |
1821 | ||
1822 | <div class="diagram"> | |
1823 | <pre> | |
1824 | Operator Meaning | |
1825 | ------------------- ------------------------------- | |
1826 | p. Pointer to | |
1827 | a(n). Array of dimension n | |
1828 | r. C++ reference | |
1829 | m(class). Member pointer to class | |
1830 | f(args). Function. | |
1831 | q(qlist). Qualifiers | |
1832 | </pre> | |
1833 | </div> | |
1834 | ||
1835 | <p> | |
1836 | In addition, type names may be parameterized by templates. This is | |
1837 | represented by enclosing the template parameters in <tt><( | |
1838 | ... )></tt>. Variable length arguments are represented by the | |
1839 | special base type of <tt>v(...)</tt>. | |
1840 | </p> | |
1841 | ||
1842 | <p> | |
1843 | If you want to experiment with type encodings, the raw type strings can | |
1844 | be inserted into an interface file using backticks `` wherever a type | |
1845 | is expected. For instance, here is | |
1846 | an extremely perverted example: | |
1847 | </p> | |
1848 | ||
1849 | <div class="diagram"> | |
1850 | <pre> | |
1851 | `p.a(10).p.f(int,p.f(int).int)` foo(int, int (*x)(int)); | |
1852 | </pre> | |
1853 | </div> | |
1854 | ||
1855 | <p> | |
1856 | This corresponds to the immediately obvious C declaration: | |
1857 | </p> | |
1858 | ||
1859 | <div class="diagram"> | |
1860 | <pre> | |
1861 | (*(*foo(int,int (*)(int)))[10])(int,int (*)(int)); | |
1862 | </pre> | |
1863 | </div> | |
1864 | ||
1865 | <p> | |
1866 | Aside from the potential use of this declaration on a C programming quiz, | |
1867 | it motivates the use of the special SWIG encoding of types. The SWIG | |
1868 | encoding is much easier to work with because types can be easily examined, | |
1869 | modified, and constructed using simple string operations (comparison, | |
1870 | substrings, concatenation, etc.). For example, in the parser, a declaration | |
1871 | like this | |
1872 | </p> | |
1873 | ||
1874 | <div class="code"> | |
1875 | <pre> | |
1876 | int *a[30]; | |
1877 | </pre> | |
1878 | </div> | |
1879 | ||
1880 | <p> | |
1881 | is processed in a few pieces. In this case, you have the base type | |
1882 | "<tt>int</tt>" and the declarator of type "<tt>a(30).p.</tt>". To | |
1883 | make the final type, the two parts are just joined together using | |
1884 | string concatenation. | |
1885 | </p> | |
1886 | ||
1887 | <H3><a name="Extending_nn25"></a>30.8.2 Type construction</H3> | |
1888 | ||
1889 | ||
1890 | <p> | |
1891 | The following functions are used to construct types. You should use | |
1892 | these functions instead of trying to build the type strings yourself. | |
1893 | </p> | |
1894 | ||
1895 | <p> | |
1896 | <b><tt>void SwigType_add_pointer(SwigType *ty)</tt></b> | |
1897 | </p> | |
1898 | ||
1899 | <div class="indent"> | |
1900 | Adds a pointer to <tt>ty</tt>. | |
1901 | </div> | |
1902 | ||
1903 | <p> | |
1904 | <b><tt>void SwigType_del_pointer(SwigType *ty)</tt></b> | |
1905 | </p> | |
1906 | ||
1907 | <div class="indent"> | |
1908 | Removes a single pointer from <tt>ty</tt>. | |
1909 | </div> | |
1910 | ||
1911 | <p> | |
1912 | <b><tt>void SwigType_add_reference(SwigType *ty)</tt></b> | |
1913 | </p> | |
1914 | ||
1915 | <div class="indent"> | |
1916 | Adds a reference to <tt>ty</tt>. | |
1917 | </div> | |
1918 | ||
1919 | <p> | |
1920 | <b><tt>void SwigType_add_array(SwigType *ty, String_or_char *dim)</tt></b> | |
1921 | </p> | |
1922 | ||
1923 | <div class="indent"> | |
1924 | Adds an array with dimension <tt>dim</tt> to <tt>ty</tt>. | |
1925 | </div> | |
1926 | ||
1927 | <p> | |
1928 | <b><tt>void SwigType_del_array(SwigType *ty)</tt></b> | |
1929 | </p> | |
1930 | ||
1931 | <div class="indent"> | |
1932 | Removes a single array dimension from <tt>ty</tt>. | |
1933 | </div> | |
1934 | ||
1935 | <p> | |
1936 | <b><tt>int SwigType_array_ndim(SwigType *ty)</tt></b> | |
1937 | </p> | |
1938 | ||
1939 | <div class="indent"> | |
1940 | Returns number of array dimensions of <tt>ty</tt>. | |
1941 | </div> | |
1942 | ||
1943 | <p> | |
1944 | <b><tt>String* SwigType_array_getdim(SwigType *ty,int n)</tt></b> | |
1945 | </p> | |
1946 | ||
1947 | <div class="indent"> | |
1948 | Returns <tt>n</tt>th array dimension of <tt>ty</tt>. | |
1949 | </div> | |
1950 | ||
1951 | <p> | |
1952 | <b><tt>void SwigType_array_setdim(SwigType *ty, int n, const String_or_char *rep)</tt></b> | |
1953 | </p> | |
1954 | ||
1955 | <div class="indent"> | |
1956 | Sets <tt>n</tt>th array dimensions of <tt>ty</tt> to <tt>rep</tt>. | |
1957 | </div> | |
1958 | ||
1959 | <p> | |
1960 | <b><tt>void SwigType_add_qualifier(SwigType *ty, String_or_char *q)</tt></b> | |
1961 | </p> | |
1962 | ||
1963 | <div class="indent"> | |
1964 | Adds a type qualifier <tt>q</tt> to <tt>ty</tt>. <tt>q</tt> is typically | |
1965 | <tt>"const"</tt> or <tt>"volatile"</tt>. | |
1966 | </div> | |
1967 | ||
1968 | <p> | |
1969 | <b><tt>void SwigType_add_memberpointer(SwigType *ty, String_or_char *cls)</tt></b> | |
1970 | </p> | |
1971 | ||
1972 | <div class="indent"> | |
1973 | Adds a pointer to a member of class <tt>cls</tt> to <tt>ty</tt>. | |
1974 | </div> | |
1975 | ||
1976 | <p> | |
1977 | <b><tt>void SwigType_add_function(SwigType *ty, ParmList *p)</tt></b> | |
1978 | </p> | |
1979 | ||
1980 | <div class="indent"> | |
1981 | Adds a function to <tt>ty</tt>. <tt>p</tt> is a linked-list of parameter | |
1982 | nodes as generated by the parser. See the section on parameter lists | |
1983 | for details about the representation. | |
1984 | </div> | |
1985 | ||
1986 | <p> | |
1987 | <b><tt>void SwigType_add_template(SwigType *ty, ParmList *p)</tt></b> | |
1988 | </p> | |
1989 | ||
1990 | <div class="indent"> | |
1991 | Adds a template to <tt>ty</tt>. <tt>p</tt> is a linked-list of parameter | |
1992 | nodes as generated by the parser. See the section on parameter lists | |
1993 | for details about the representation. | |
1994 | </div> | |
1995 | ||
1996 | <p> | |
1997 | <b><tt>SwigType *SwigType_pop(SwigType *ty)</tt></b> | |
1998 | </p> | |
1999 | ||
2000 | <div class="indent"> | |
2001 | Removes the last type constructor from <tt>ty</tt> and returns it. | |
2002 | <tt>ty</tt> is modified. | |
2003 | </div> | |
2004 | ||
2005 | <p> | |
2006 | <b><tt>void SwigType_push(SwigType *ty, SwigType *op)</tt></b> | |
2007 | </p> | |
2008 | ||
2009 | <div class="indent"> | |
2010 | Pushes the type operators in <tt>op</tt> onto type <tt>ty</tt>. The | |
2011 | opposite of <tt>SwigType_pop()</tt>. | |
2012 | </div> | |
2013 | ||
2014 | <p> | |
2015 | <b><tt>SwigType *SwigType_pop_arrays(SwigType *ty)</tt></b> | |
2016 | </p> | |
2017 | ||
2018 | <div class="indent"> | |
2019 | Removes all leading array operators from <tt>ty</tt> and returns them. | |
2020 | <tt>ty</tt> is modified. For example, if <tt>ty</tt> is <tt>"a(20).a(10).p.int"</tt>, | |
2021 | then this function would return <tt>"a(20).a(10)."</tt> and modify <tt>ty</tt> | |
2022 | so that it has the value <tt>"p.int"</tt>. | |
2023 | </div> | |
2024 | ||
2025 | <p> | |
2026 | <b><tt>SwigType *SwigType_pop_function(SwigType *ty)</tt></b> | |
2027 | </p> | |
2028 | ||
2029 | <div class="indent"> | |
2030 | Removes a function operator from <tt>ty</tt> including any qualification. | |
2031 | <tt>ty</tt> is modified. For example, if <tt>ty</tt> is <tt>"f(int).int"</tt>, | |
2032 | then this function would return <tt>"f(int)."</tt> and modify <tt>ty</tt> | |
2033 | so that it has the value <tt>"int"</tt>. | |
2034 | </div> | |
2035 | ||
2036 | <p> | |
2037 | <b><tt>SwigType *SwigType_base(SwigType *ty)</tt></b> | |
2038 | </p> | |
2039 | ||
2040 | <div class="indent"> | |
2041 | Returns the base type of a type. For example, if <tt>ty</tt> is | |
2042 | <tt>"p.a(20).int"</tt>, this function would return <tt>"int"</tt>. | |
2043 | <tt>ty</tt> is unmodified. | |
2044 | </div> | |
2045 | ||
2046 | <p> | |
2047 | <b><tt>SwigType *SwigType_prefix(SwigType *ty)</tt></b> | |
2048 | </p> | |
2049 | ||
2050 | <div class="indent"> | |
2051 | Returns the prefix of a type. For example, if <tt>ty</tt> is | |
2052 | <tt>"p.a(20).int"</tt>, this function would return <tt>"p.a(20)."</tt>. | |
2053 | <tt>ty</tt> is unmodified. | |
2054 | </div> | |
2055 | ||
2056 | <H3><a name="Extending_nn26"></a>30.8.3 Type tests</H3> | |
2057 | ||
2058 | ||
2059 | <p> | |
2060 | The following functions can be used to test properties of a datatype. | |
2061 | </p> | |
2062 | ||
2063 | <p> | |
2064 | <b><tt>int SwigType_ispointer(SwigType *ty)</tt></b> | |
2065 | </p> | |
2066 | ||
2067 | <div class="indent"> | |
2068 | Checks if <tt>ty</tt> is a standard pointer. | |
2069 | </div> | |
2070 | ||
2071 | <p> | |
2072 | <b><tt>int SwigType_ismemberpointer(SwigType *ty)</tt></b> | |
2073 | </p> | |
2074 | ||
2075 | <div class="indent"> | |
2076 | Checks if <tt>ty</tt> is a member pointer. | |
2077 | </div> | |
2078 | ||
2079 | <p> | |
2080 | <b><tt>int SwigType_isreference(SwigType *ty)</tt></b> | |
2081 | </p> | |
2082 | ||
2083 | <div class="indent"> | |
2084 | Checks if <tt>ty</tt> is a C++ reference. | |
2085 | </div> | |
2086 | ||
2087 | <p> | |
2088 | <b><tt>int SwigType_isarray(SwigType *ty)</tt></b> | |
2089 | </p> | |
2090 | ||
2091 | <div class="indent"> | |
2092 | Checks if <tt>ty</tt> is an array. | |
2093 | </div> | |
2094 | ||
2095 | <p> | |
2096 | <b><tt>int SwigType_isfunction(SwigType *ty)</tt></b> | |
2097 | </p> | |
2098 | ||
2099 | <div class="indent"> | |
2100 | Checks if <tt>ty</tt> is a function. | |
2101 | </div> | |
2102 | ||
2103 | <p> | |
2104 | <b><tt>int SwigType_isqualifier(SwigType *ty)</tt></b> | |
2105 | </p> | |
2106 | ||
2107 | <div class="indent"> | |
2108 | Checks if <tt>ty</tt> is a qualifier. | |
2109 | </div> | |
2110 | ||
2111 | <p> | |
2112 | <b><tt>int SwigType_issimple(SwigType *ty)</tt></b> | |
2113 | </p> | |
2114 | ||
2115 | <div class="indent"> | |
2116 | Checks if <tt>ty</tt> is a simple type. No operators applied. | |
2117 | </div> | |
2118 | ||
2119 | <p> | |
2120 | <b><tt>int SwigType_isconst(SwigType *ty)</tt></b> | |
2121 | </p> | |
2122 | ||
2123 | <div class="indent"> | |
2124 | Checks if <tt>ty</tt> is a const type. | |
2125 | </div> | |
2126 | ||
2127 | <p> | |
2128 | <b><tt>int SwigType_isvarargs(SwigType *ty)</tt></b> | |
2129 | </p> | |
2130 | ||
2131 | <div class="indent"> | |
2132 | Checks if <tt>ty</tt> is a varargs type. | |
2133 | </div> | |
2134 | ||
2135 | <p> | |
2136 | <b><tt>int SwigType_istemplate(SwigType *ty)</tt></b> | |
2137 | </p> | |
2138 | ||
2139 | <div class="indent"> | |
2140 | Checks if <tt>ty</tt> is a templatized type. | |
2141 | </div> | |
2142 | ||
2143 | <H3><a name="Extending_nn27"></a>30.8.4 Typedef and inheritance</H3> | |
2144 | ||
2145 | ||
2146 | <p> | |
2147 | The behavior of <tt>typedef</tt> declaration is to introduce a type alias. | |
2148 | For instance, <tt>typedef int Integer</tt> makes the identifier | |
2149 | <tt>Integer</tt> an alias for <tt>int</tt>. The treatment of typedef in | |
2150 | SWIG is somewhat complicated due to the pattern matching rules that get applied | |
2151 | in typemaps and the fact that SWIG prefers to generate wrapper code | |
2152 | that closely matches the input to simplify debugging (a user will see the | |
2153 | typedef names used in their program instead of the low-level primitive C | |
2154 | datatypes). | |
2155 | </p> | |
2156 | ||
2157 | <p> | |
2158 | To handle <tt>typedef</tt>, SWIG builds a collection of trees containing typedef relations. For example, | |
2159 | </p> | |
2160 | ||
2161 | <div class="code"> | |
2162 | <pre> | |
2163 | typedef int Integer; | |
2164 | typedef Integer *IntegerPtr; | |
2165 | typedef int Number; | |
2166 | typedef int Size; | |
2167 | </pre> | |
2168 | </div> | |
2169 | ||
2170 | <p> | |
2171 | produces two trees like this: | |
2172 | </p> | |
2173 | ||
2174 | <div class="diagram"> | |
2175 | <pre> | |
2176 | int p.Integer | |
2177 | ^ ^ ^ ^ | |
2178 | / | \ | | |
2179 | / | \ | | |
2180 | Integer Size Number IntegerPtr | |
2181 | </pre> | |
2182 | </div> | |
2183 | ||
2184 | <p> | |
2185 | To resolve a single typedef relationship, the following function is used: | |
2186 | </p> | |
2187 | ||
2188 | <p> | |
2189 | <b><tt>SwigType *SwigType_typedef_resolve(SwigType *ty)</tt></b> | |
2190 | </p> | |
2191 | ||
2192 | <div class="indent"> | |
2193 | Checks if <tt>ty</tt> can be reduced to a new type via typedef. If so, | |
2194 | returns the new type. If not, returns NULL. | |
2195 | </div> | |
2196 | ||
2197 | <p> | |
2198 | Typedefs are only resolved in simple typenames that appear in a type. | |
2199 | For example, the type base name and in function parameters. When | |
2200 | resolving types, the process starts in the leaf nodes and moves up | |
2201 | the tree towards the root. Here are a few examples that show how it works: | |
2202 | </p> | |
2203 | ||
2204 | <div class="diagram"> | |
2205 | <pre> | |
2206 | Original type After typedef_resolve() | |
2207 | ------------------------ ----------------------- | |
2208 | Integer int | |
2209 | a(30).Integer int | |
2210 | p.IntegerPtr p.p.Integer | |
2211 | p.p.Integer p.p.int | |
2212 | </pre> | |
2213 | </div> | |
2214 | ||
2215 | <p> | |
2216 | For complicated types, the process can be quite involved. Here is the | |
2217 | reduction of a function pointer: | |
2218 | </p> | |
2219 | ||
2220 | <div class="diagram"> | |
2221 | <pre> | |
2222 | p.f(Integer, p.IntegerPtr, Size).Integer : Start | |
2223 | p.f(Integer, p.IntegerPtr, Size).int | |
2224 | p.f(int, p.IntegerPtr, Size).int | |
2225 | p.f(int, p.p.Integer, Size).int | |
2226 | p.f(int, p.p.int, Size).int | |
2227 | p.f(int, p.p.int, int).int : End | |
2228 | </pre> | |
2229 | </div> | |
2230 | ||
2231 | <p> | |
2232 | Two types are equivalent if their full type reductions are the same. | |
2233 | The following function will fully reduce a datatype: | |
2234 | </p> | |
2235 | ||
2236 | <p> | |
2237 | <b><tt>SwigType *SwigType_typedef_resolve_all(SwigType *ty)</tt></b> | |
2238 | </p> | |
2239 | ||
2240 | <div class="indent"> | |
2241 | Fully reduces <tt>ty</tt> according to typedef rules. Resulting datatype | |
2242 | will consist only of primitive typenames. | |
2243 | </div> | |
2244 | ||
2245 | <H3><a name="Extending_nn28"></a>30.8.5 Lvalues</H3> | |
2246 | ||
2247 | ||
2248 | <p> | |
2249 | When generating wrapper code, it is necessary to emit datatypes that can | |
2250 | be used on the left-hand side of an assignment operator (an lvalue). However, | |
2251 | not all C datatypes can be used in this way---especially arrays and | |
2252 | const-qualified types. To generate a type that can be used as an lvalue, | |
2253 | use the following function: | |
2254 | </p> | |
2255 | ||
2256 | <p> | |
2257 | <b><tt>SwigType *SwigType_ltype(SwigType *ty)</tt></b> | |
2258 | </p> | |
2259 | ||
2260 | <div class="indent"> | |
2261 | Converts type <tt>ty</tt> to a type that can be used as an lvalue in | |
2262 | assignment. The resulting type is stripped of qualifiers and arrays are | |
2263 | converted to a pointers. | |
2264 | </div> | |
2265 | ||
2266 | <p> | |
2267 | The creation of lvalues is fully aware of typedef and other aspects | |
2268 | of the type system. Therefore, the creation of an lvalue may result in | |
2269 | unexpected results. Here are a few examples: | |
2270 | </p> | |
2271 | ||
2272 | <div class="code"> | |
2273 | <pre> | |
2274 | typedef double Matrix4[4][4]; | |
2275 | Matrix4 x; // type = 'Matrix4', ltype='p.a(4).double' | |
2276 | ||
2277 | typedef const char * Literal; | |
2278 | Literal y; // type = 'Literal', ltype='p.char' | |
2279 | </pre> | |
2280 | </div> | |
2281 | ||
2282 | <H3><a name="Extending_nn29"></a>30.8.6 Output functions</H3> | |
2283 | ||
2284 | ||
2285 | <p> | |
2286 | The following functions produce strings that are suitable for output. | |
2287 | </p> | |
2288 | ||
2289 | <p> | |
2290 | <b><tt>String *SwigType_str(SwigType *ty, String_or_char *id = 0)</tt></b> | |
2291 | </p> | |
2292 | ||
2293 | <div class="indent"> | |
2294 | Generates a C string for a datatype. <tt>id</tt> is an optional declarator. | |
2295 | For example, if <tt>ty</tt> is "p.f(int).int" and <tt>id</tt> is "foo", then | |
2296 | this function produces "<tt>int (*foo)(int)</tt>". This function is | |
2297 | used to convert string-encoded types back into a form that is valid C syntax. | |
2298 | </div> | |
2299 | ||
2300 | <p> | |
2301 | <b><tt>String *SwigType_lstr(SwigType *ty, String_or_char *id = 0)</tt></b> | |
2302 | </p> | |
2303 | ||
2304 | <div class="indent"> | |
2305 | This is the same as <tt>SwigType_str()</tt> except that the result | |
2306 | is generated from the type's lvalue (as generated from SwigType_ltype). | |
2307 | </div> | |
2308 | ||
2309 | <p> | |
2310 | <b><tt>String *SwigType_lcaststr(SwigType *ty, String_or_char *id = 0)</tt></b> | |
2311 | </p> | |
2312 | ||
2313 | <div class="indent"> | |
2314 | Generates a casting operation that converts from type <tt>ty</tt> to its | |
2315 | lvalue. <tt>id</tt> is an optional name to include in the cast. For example, | |
2316 | if <tt>ty</tt> is "<tt>q(const).p.char</tt>" and <tt>id</tt> is "<tt>foo</tt>", | |
2317 | this function produces the string "<tt>(char *) foo</tt>". | |
2318 | </div> | |
2319 | ||
2320 | <p> | |
2321 | <b><tt>String *SwigType_rcaststr(SwigType *ty, String_or_char *id = 0)</tt></b> | |
2322 | </p> | |
2323 | ||
2324 | <div class="indent"> | |
2325 | Generates a casting operation that converts from a type's lvalue to a | |
2326 | type equivalent to <tt>ty</tt>. <tt>id</tt> is an optional name to | |
2327 | include in the cast. For example, if <tt>ty</tt> is | |
2328 | "<tt>q(const).p.char</tt>" and <tt>id</tt> is "<tt>foo</tt>", this | |
2329 | function produces the string "<tt>(const char *) foo</tt>". | |
2330 | </div> | |
2331 | ||
2332 | <p> | |
2333 | <b><tt>String *SwigType_manglestr(SwigType *ty)</tt></b> | |
2334 | </p> | |
2335 | ||
2336 | <div class="indent"> | |
2337 | Generates a mangled string encoding of type <tt>ty</tt>. The | |
2338 | mangled string only contains characters that are part of a valid | |
2339 | C identifier. The resulting string is used in various parts of | |
2340 | SWIG, but is most commonly associated with type-descriptor objects | |
2341 | that appear in wrappers (e.g., <tt>SWIGTYPE_p_double</tt>). | |
2342 | </div> | |
2343 | ||
2344 | <H2><a name="Extending_nn30"></a>30.9 Parameters</H2> | |
2345 | ||
2346 | ||
2347 | <p> | |
2348 | Several type-related functions involve parameter lists. These include | |
2349 | functions and templates. Parameter list are represented as a list of | |
2350 | nodes with the following attributes: | |
2351 | </p> | |
2352 | ||
2353 | <div class="diagram"> | |
2354 | <pre> | |
2355 | "type" - Parameter type (required) | |
2356 | "name" - Parameter name (optional) | |
2357 | "value" - Initializer (optional) | |
2358 | </pre> | |
2359 | </div> | |
2360 | ||
2361 | <p> | |
2362 | Typically parameters are denoted in the source by using a typename of | |
2363 | <tt>Parm *</tt> or <tt>ParmList *</tt>. To walk a parameter list, simply use | |
2364 | code like this: | |
2365 | </p> | |
2366 | ||
2367 | <div class="diagram"> | |
2368 | <pre> | |
2369 | Parm *parms; | |
2370 | Parm *p; | |
2371 | for (p = parms; p; p = nextSibling(p)) { | |
2372 | SwigType *type = Getattr(p,"type"); | |
2373 | String *name = Getattr(p,"name"); | |
2374 | String *value = Getattr(p,"value"); | |
2375 | ... | |
2376 | } | |
2377 | </pre> | |
2378 | </div> | |
2379 | ||
2380 | <p> | |
2381 | Note: this code is exactly the same as what you would use to walk parse tree nodes. | |
2382 | </p> | |
2383 | ||
2384 | <p> | |
2385 | An empty list of parameters is denoted by a NULL pointer. | |
2386 | </p> | |
2387 | ||
2388 | <p> | |
2389 | Since parameter lists are fairly common, the following utility functions are provided | |
2390 | to manipulate them: | |
2391 | </p> | |
2392 | ||
2393 | <p> | |
2394 | <b><tt>Parm *CopyParm(Parm *p);</tt></b> | |
2395 | </p> | |
2396 | ||
2397 | <div class="indent"> | |
2398 | Copies a single parameter. | |
2399 | </div> | |
2400 | ||
2401 | <p> | |
2402 | <b><tt>ParmList *CopyParmList(ParmList *p);</tt></b> | |
2403 | </p> | |
2404 | ||
2405 | <div class="indent"> | |
2406 | Copies an entire list of parameters. | |
2407 | </div> | |
2408 | ||
2409 | <p> | |
2410 | <b><tt>int ParmList_len(ParmList *p);</tt></b> | |
2411 | </p> | |
2412 | ||
2413 | <div class="indent"> | |
2414 | Returns the number of parameters in a parameter list. | |
2415 | </div> | |
2416 | ||
2417 | <p> | |
2418 | <b><tt>String *ParmList_str(ParmList *p);</tt></b> | |
2419 | </p> | |
2420 | ||
2421 | <div class="indent"> | |
2422 | Converts a parameter list into a C string. For example, | |
2423 | produces a string like "<tt>(int *p, int n, double x);</tt>". | |
2424 | </div> | |
2425 | ||
2426 | <p> | |
2427 | <b><tt>String *ParmList_protostr(ParmList *p);</tt></b> | |
2428 | </p> | |
2429 | ||
2430 | <div class="indent"> | |
2431 | The same as <tt>ParmList_str()</tt> except that parameter names are not | |
2432 | included. Used to emit prototypes. | |
2433 | </div> | |
2434 | ||
2435 | <p> | |
2436 | <b><tt>int ParmList_numrequired(ParmList *p);</tt></b> | |
2437 | </p> | |
2438 | ||
2439 | <div class="indent"> | |
2440 | Returns the number of required (non-optional) arguments in <tt>p</tt>. | |
2441 | </div> | |
2442 | ||
2443 | <H2><a name="Extending_nn31"></a>30.10 Writing a Language Module</H2> | |
2444 | ||
2445 | ||
2446 | <p> | |
2447 | This section briefly outlines the steps needed to create a bare-bones | |
2448 | language module. For more advanced techniques, you should look at the implementation | |
2449 | of existing modules. Since the code is relatively easy to read, this section | |
2450 | describes the creation of a minimal Python module. You should be able to extrapolate | |
2451 | this to other languages. | |
2452 | </p> | |
2453 | ||
2454 | <H3><a name="Extending_nn32"></a>30.10.1 Execution model</H3> | |
2455 | ||
2456 | ||
2457 | <p> | |
2458 | Code generation modules are defined by inheriting from the <tt>Language</tt> class, | |
2459 | currently defined in the <tt>Source/Modules1.1</tt> directory of SWIG. Starting from | |
2460 | the parsing of command line options, all aspects of code generation are controlled by | |
2461 | different methods of the <tt>Language</tt> that must be defined by your module. | |
2462 | </p> | |
2463 | ||
2464 | <H3><a name="Extending_nn33"></a>30.10.2 Starting out</H3> | |
2465 | ||
2466 | ||
2467 | <p> | |
2468 | To define a new language module, first create a minimal implementation using | |
2469 | this example as a guide: | |
2470 | </p> | |
2471 | ||
2472 | <div class="code"> | |
2473 | <pre> | |
2474 | #include "swigmod.h" | |
2475 | ||
2476 | #ifndef MACSWIG | |
2477 | #include "swigconfig.h" | |
2478 | #endif | |
2479 | ||
2480 | class PYTHON : public Language { | |
2481 | public: | |
2482 | ||
2483 | virtual void main(int argc, char *argv[]) { | |
2484 | printf("I'm the Python module.\n"); | |
2485 | } | |
2486 | ||
2487 | virtual int top(Node *n) { | |
2488 | printf("Generating code.\n"); | |
2489 | return SWIG_OK; | |
2490 | } | |
2491 | ||
2492 | }; | |
2493 | ||
2494 | extern "C" Language * | |
2495 | swig_python(void) { | |
2496 | return new PYTHON(); | |
2497 | } | |
2498 | </pre> | |
2499 | </div> | |
2500 | ||
2501 | <p> | |
2502 | The "swigmod.h" header file contains, among other things, the declaration | |
2503 | of the <tt>Language</tt> base class and so you should include it at the top | |
2504 | of your language module's source file. Similarly, the "swigconfig.h" header | |
2505 | file contains some other useful definitions that you may need. Note that you | |
2506 | should <em>not</em> include any header files that are installed with the | |
2507 | target language. That is to say, the implementation of the SWIG Python module | |
2508 | shouldn't have any dependencies on the Python header files. The wrapper code | |
2509 | generated by SWIG will almost always depend on some language-specific C/C++ | |
2510 | header files, but SWIG itself does not. | |
2511 | </p> | |
2512 | ||
2513 | <p> | |
2514 | Give your language class a reasonable name, usually the same as the target language. | |
2515 | By convention, these class names are all uppercase (e.g. "PYTHON" for the Python | |
2516 | language module) but this is not a requirement. This class will ultimately consist | |
2517 | of a number of overrides of the virtual functions declared in the <tt>Language</tt> | |
2518 | base class, in addition to any language-specific member functions and data you | |
2519 | need. For now, just use the dummy implementations shown above. | |
2520 | </p> | |
2521 | ||
2522 | <p> | |
2523 | The language module ends with a factory function, <tt>swig_python()</tt>, that simply | |
2524 | returns a new instance of the language class. As shown, it should be declared with the | |
2525 | <tt>extern "C"</tt> storage qualifier so that it can be called from C code. It should | |
2526 | also return a pointer to the base class (<tt>Language</tt>) so that only the interface | |
2527 | (and not the implementation) of your language module is exposed to the rest of SWIG. | |
2528 | </p> | |
2529 | ||
2530 | <p> | |
2531 | Save the code for your language module in a file named "<tt>python.cxx</tt>" and. | |
2532 | place this file in the <tt>Source/Modules1.1</tt> directory of the SWIG distribution. | |
2533 | To ensure that your module is compiled into SWIG along with the other language modules, | |
2534 | modify the file <tt>Source/Modules1.1/Makefile.in</tt> to include the additional source | |
2535 | files. Look for the lines that define the <tt>SRCS</tt> and <tt>OBJS</tt> variables and | |
2536 | add entries for your language. In addition, modify the file <tt>Source/Modules1.1/swigmain.cxx</tt> | |
2537 | with an additional command line option that activates the module. Read the source---it's straightforward. | |
2538 | </p> | |
2539 | ||
2540 | <p> | |
2541 | Next, at the top level of the SWIG distribution, re-run the <tt>autogen.sh</tt> script | |
2542 | to regenerate the various build files: | |
2543 | </p> | |
2544 | ||
2545 | <div class="shell"> | |
2546 | <pre> | |
2547 | $ <b>sh autogen.sh</b> | |
2548 | </pre> | |
2549 | </div> | |
2550 | ||
2551 | <p> | |
2552 | Next re-run <tt>configure</tt> to regenerate all of the Makefiles: | |
2553 | </p> | |
2554 | ||
2555 | <div class="shell"> | |
2556 | <pre> | |
2557 | $ <b>./configure</b> | |
2558 | </pre> | |
2559 | </div> | |
2560 | ||
2561 | <p> | |
2562 | Finally, rebuild SWIG with your module added: | |
2563 | </p> | |
2564 | ||
2565 | <div class="shell"> | |
2566 | <pre> | |
2567 | $ <b>make</b> | |
2568 | </pre> | |
2569 | </div> | |
2570 | ||
2571 | <p> | |
2572 | Once it finishes compiling, try running SWIG with the command-line option | |
2573 | that activates your module. For example, <tt>swig -python foo.i</tt>. The | |
2574 | messages from your new module should appear. | |
2575 | </p> | |
2576 | ||
2577 | <H3><a name="Extending_nn34"></a>30.10.3 Command line options</H3> | |
2578 | ||
2579 | ||
2580 | <p> | |
2581 | When SWIG starts, the command line options are passed to your language module. This occurs | |
2582 | before any other processing occurs (preprocessing, parsing, etc.). To capture the | |
2583 | command line options, simply use code similar to this: | |
2584 | </p> | |
2585 | ||
2586 | <div class="code"> | |
2587 | <pre> | |
2588 | void Language::main(int argc, char *argv[]) { | |
2589 | for (int i = 1; i < argc; i++) { | |
2590 | if (argv[i]) { | |
2591 | if(strcmp(argv[i],"-interface") == 0) { | |
2592 | if (argv[i+1]) { | |
2593 | interface = NewString(argv[i+1]); | |
2594 | Swig_mark_arg(i); | |
2595 | Swig_mark_arg(i+1); | |
2596 | i++; | |
2597 | } else { | |
2598 | Swig_arg_error(); | |
2599 | } | |
2600 | } else if (strcmp(argv[i],"-globals") == 0) { | |
2601 | if (argv[i+1]) { | |
2602 | global_name = NewString(argv[i+1]); | |
2603 | Swig_mark_arg(i); | |
2604 | Swig_mark_arg(i+1); | |
2605 | i++; | |
2606 | } else { | |
2607 | Swig_arg_error(); | |
2608 | } | |
2609 | } else if ( (strcmp(argv[i],"-proxy") == 0)) { | |
2610 | proxy_flag = 1; | |
2611 | Swig_mark_arg(i); | |
2612 | } else if (strcmp(argv[i],"-keyword") == 0) { | |
2613 | use_kw = 1; | |
2614 | Swig_mark_arg(i); | |
2615 | } else if (strcmp(argv[i],"-help") == 0) { | |
2616 | fputs(usage,stderr); | |
2617 | } | |
2618 | ... | |
2619 | } | |
2620 | } | |
2621 | } | |
2622 | </pre> | |
2623 | </div> | |
2624 | ||
2625 | <p> | |
2626 | The exact set of options depends on what you want to do in your module. Generally, | |
2627 | you would use the options to change code generation modes or to print diagnostic information. | |
2628 | </p> | |
2629 | ||
2630 | <p> | |
2631 | If a module recognizes an option, it should always call <tt>Swig_mark_arg()</tt> | |
2632 | to mark the option as valid. If you forget to do this, SWIG will terminate with an | |
2633 | unrecognized command line option error. | |
2634 | </p> | |
2635 | ||
2636 | <H3><a name="Extending_nn35"></a>30.10.4 Configuration and preprocessing</H3> | |
2637 | ||
2638 | ||
2639 | <p> | |
2640 | In addition to looking at command line options, the <tt>main()</tt> method is responsible | |
2641 | for some initial configuration of the SWIG library and preprocessor. To do this, | |
2642 | insert some code like this: | |
2643 | </p> | |
2644 | ||
2645 | <div class="code"> | |
2646 | <pre> | |
2647 | void main(int argc, char *argv[]) { | |
2648 | ... command line options ... | |
2649 | ||
2650 | /* Set language-specific subdirectory in SWIG library */ | |
2651 | SWIG_library_directory("python"); | |
2652 | ||
2653 | /* Set language-specific preprocessing symbol */ | |
2654 | Preprocessor_define("SWIGPYTHON 1", 0); | |
2655 | ||
2656 | /* Set language-specific configuration file */ | |
2657 | SWIG_config_file("python.swg"); | |
2658 | ||
2659 | /* Set typemap language (historical) */ | |
2660 | SWIG_typemap_lang("python"); | |
2661 | } | |
2662 | </pre> | |
2663 | </div> | |
2664 | ||
2665 | <p> | |
2666 | The above code does several things--it registers the name of the | |
2667 | language module with the core, it supplies some preprocessor macro definitions | |
2668 | for use in input files (so that they can determine the target language), and | |
2669 | it registers a start-up file. In this case, the file <tt>python.swg</tt> will | |
2670 | be parsed before any part of the user-supplied input file. | |
2671 | </p> | |
2672 | ||
2673 | <p> | |
2674 | Before proceeding any further, create a directory for your module in the SWIG | |
2675 | library (The <tt>Lib</tt> directory). Now, create a configuration file in the | |
2676 | directory. For example, <tt>python.swg</tt>. | |
2677 | </p> | |
2678 | ||
2679 | <p> | |
2680 | Just to review, your language module should now consist of two files-- | |
2681 | an implementation file <tt>python.cxx</tt> and a configuration file | |
2682 | <tt>python.swg</tt>. | |
2683 | </p> | |
2684 | ||
2685 | <H3><a name="Extending_nn36"></a>30.10.5 Entry point to code generation</H3> | |
2686 | ||
2687 | ||
2688 | <p> | |
2689 | SWIG is a multi-pass compiler. Once the <tt>main()</tt> method has | |
2690 | been invoked, the language module does not execute again until | |
2691 | preprocessing, parsing, and a variety of semantic analysis passes have | |
2692 | been performed. When the core is ready to start generating wrappers, | |
2693 | it invokes the <tt>top()</tt> method of your language class. The | |
2694 | argument to <tt>top</tt> is a single parse tree node that corresponds to | |
2695 | the top of the entire parse tree. | |
2696 | </p> | |
2697 | ||
2698 | <p> | |
2699 | To get the code generation process started, the <tt>top()</tt> procedure needs | |
2700 | to do several things: | |
2701 | </p> | |
2702 | ||
2703 | <ul> | |
2704 | <li>Initialize the wrapper code output. | |
2705 | <li>Set the module name. | |
2706 | <li>Emit common initialization code. | |
2707 | <li>Emit code for all of the child nodes. | |
2708 | <li>Finalize the wrapper module and cleanup. | |
2709 | </ul> | |
2710 | ||
2711 | <p> | |
2712 | An outline of <tt>top()</tt> might be as follows: | |
2713 | </p> | |
2714 | ||
2715 | <div class="code"> | |
2716 | <pre> | |
2717 | int Python::top(Node *n) { | |
2718 | ||
2719 | /* Get the module name */ | |
2720 | String *module = Getattr(n,"name"); | |
2721 | ||
2722 | /* Get the output file name */ | |
2723 | String *outfile = Getattr(n,"outfile"); | |
2724 | ||
2725 | /* Initialize I/O (see next section) */ | |
2726 | ... | |
2727 | ||
2728 | /* Output module initialization code */ | |
2729 | ... | |
2730 | ||
2731 | /* Emit code for children */ | |
2732 | Language::top(n); | |
2733 | ||
2734 | ... | |
2735 | /* Cleanup files */ | |
2736 | ... | |
2737 | ||
2738 | return SWIG_OK; | |
2739 | } | |
2740 | </pre> | |
2741 | </div> | |
2742 | ||
2743 | <H3><a name="Extending_nn37"></a>30.10.6 Module I/O and wrapper skeleton</H3> | |
2744 | ||
2745 | ||
2746 | <H3><a name="Extending_nn38"></a>30.10.7 Low-level code generators</H3> | |
2747 | ||
2748 | ||
2749 | <H3><a name="Extending_nn39"></a>30.10.8 Configuration files</H3> | |
2750 | ||
2751 | ||
2752 | <!-- please report bugs in this section to ttn --> | |
2753 | ||
2754 | <p> | |
2755 | At the time of this writing, SWIG supports nearly a dozen languages, | |
2756 | which means that for continued sanity in maintaining the configuration | |
2757 | files, the language modules need to follow some conventions. These are | |
2758 | outlined here along with the admission that, yes it is ok to violate | |
2759 | these conventions in minor ways, as long as you know where to apply the | |
2760 | proper kludge to keep the overall system regular and running. | |
2761 | Engineering is the art of compromise, see... | |
2762 | </p> | |
2763 | ||
2764 | <p> | |
2765 | Much of the maintenance regularity depends on choosing a suitable | |
2766 | nickname for your language module (and then using it in a controlled | |
2767 | way). Nicknames should be all lower case letters with an optional | |
2768 | numeric suffix (no underscores, no dashes, no spaces). Some examples | |
2769 | are: <TT>foo</TT>, <TT>bar</TT>, <TT>qux99</TT>. | |
2770 | </p> | |
2771 | ||
2772 | <p> | |
2773 | The numeric suffix variant, as in the last example, is somewhat tricky | |
2774 | to work with because sometimes people expect to refer to the language | |
2775 | without this number but sometimes that number is extremely relevant | |
2776 | (especially when it corresponds to language implementation versions with | |
2777 | incompatible interfaces). New language modules that unavoidably require | |
2778 | a numeric suffix in their nickname should include that number in all | |
2779 | uses, or be prepared to kludge. | |
2780 | </p> | |
2781 | ||
2782 | <p> | |
2783 | The nickname is used in four places: | |
2784 | </p> | |
2785 | ||
2786 | <TABLE summary="nickname table"> | |
2787 | <TR><TD><B>usage</B></TD><TD><B>transform</B></TD></TR> | |
2788 | <TR><TD>"skip" tag</TD><TD>(none)</TD></TR> | |
2789 | <TR><TD>Examples/ subdir name</TD><TD>(none)</TD></TR> | |
2790 | <TR><TD>Examples/GIFPlot/ subdir name</TD> | |
2791 | <TD>capitalize (upcase first letter)</TD></TR> | |
2792 | <TR><TD>Examples/test-suite/ subdir name</TD><TD>(none)</TD></TR> | |
2793 | <!-- add more uses here (remember to adjust header) --> | |
2794 | </TABLE> | |
2795 | ||
2796 | <p> | |
2797 | As you can see, most usages are direct. | |
2798 | </p> | |
2799 | ||
2800 | <dl> | |
2801 | ||
2802 | <dt> <b>configure.in</b> | |
2803 | <dd> This file is processed by | |
2804 | ||
2805 | <p> | |
2806 | <A HREF="http://www.gnu.org/software/autoconf/">autoconf</A> | |
2807 | to generate the <TT>configure</TT> script. This is where you | |
2808 | need to add shell script fragments and autoconf macros to detect the | |
2809 | presence of whatever development support your language module requires, | |
2810 | typically directories where headers and libraries can be found, and/or | |
2811 | utility programs useful for integrating the generated wrapper code. | |
2812 | </p> | |
2813 | ||
2814 | <p> | |
2815 | Use the <TT>AC_ARG_WITH</TT>, <TT>AC_MSG_CHECKING</TT>, <TT>AC_SUBST</TT> | |
2816 | macros and so forth (see other languages for examples). Avoid using the | |
2817 | <TT>[</TT> and <TT>]</TT> character in shell script fragments. The | |
2818 | variable names passed to <TT>AC_SUBST</TT> should begin with the nickname, | |
2819 | entirely upcased. | |
2820 | </p> | |
2821 | ||
2822 | <p> | |
2823 | At the end of the new section is the place to put the aforementioned | |
2824 | nickname kludges (should they be needed). See Perl5 and Php4 for | |
2825 | examples of what to do. [If this is still unclear after you've read | |
2826 | the code, ping me and I'll expand on this further. --ttn] | |
2827 | </p> | |
2828 | ||
2829 | <dt> <b>Makefile.in</b> | |
2830 | <dd> | |
2831 | ||
2832 | <p> | |
2833 | Some of the variables AC_SUBSTitutued are essential to the | |
2834 | support of your language module. Fashion these into a shell script | |
2835 | "test" clause and assign that to a skip tag using "-z" and "-o": | |
2836 | </p> | |
2837 | ||
2838 | <div class="code"><tt> | |
2839 | skip-qux99 = [ -z "@QUX99INCLUDE@" -o -z "@QUX99LIBS" ] | |
2840 | </tt></div> | |
2841 | ||
2842 | <p> | |
2843 | This means if those vars should ever be empty, qux99 support should | |
2844 | be considered absent and so it would be a good idea to skip actions that | |
2845 | might rely on it. | |
2846 | </p> | |
2847 | ||
2848 | <p> | |
2849 | Here is where you may also define an alias (but then you'll need to | |
2850 | kludge --- don't do this): | |
2851 | </p> | |
2852 | ||
2853 | <div class="code"><tt> | |
2854 | skip-qux = $(skip-qux99) | |
2855 | </tt></div> | |
2856 | ||
2857 | <p> | |
2858 | Lastly, you need to modify each of <TT>check-aliveness</TT>, | |
2859 | <TT>check-examples</TT>, <TT>check-test-suite</TT>, | |
2860 | <TT>check-gifplot</TT> (all targets) and <TT>lib-languages</TT> (var). | |
2861 | Use the nickname for these, not the alias. | |
2862 | Note that you can do this even before you have any tests or examples | |
2863 | set up; the Makefile rules do some sanity checking and skip around | |
2864 | these kinds of problems. | |
2865 | </p> | |
2866 | ||
2867 | <dt> <b>Examples/Makefile.in</b> | |
2868 | <dd> Nothing special here; see comments at top the of this file | |
2869 | and look to the existing languages for examples. | |
2870 | ||
2871 | <dt> <b>Examples/qux99/check.list</b> | |
2872 | <dd> Do <TT>cp ../python/check.list .</TT> and modify to taste. | |
2873 | One subdir per line. | |
2874 | ||
2875 | <dt> <b>Examples/GIFPlot/Qux99/check.list</b> | |
2876 | <dd> Do <TT>cp ../Python/check.list .</TT> and modify to taste. | |
2877 | One subdir per line. | |
2878 | ||
2879 | <dt> <b>Lib/qux99/extra-install.list</b> | |
2880 | <dd> If you add your language to the top-level Makefile.in var | |
2881 | <TT>lib-languages</TT>, then <TT>make install</TT> will install | |
2882 | all <TT>*.i</TT> and <TT>*.swg</TT> files from the language-specific | |
2883 | subdirectory of <TT>Lib</TT>. Use (optional) file | |
2884 | <TT>extra-install.list</TT> in that directory to name | |
2885 | additional files to install (see ruby for example). | |
2886 | ||
2887 | <dt> <b>Runtime/Makefile.in</b> | |
2888 | <dd> Add another <TT>make</TT> invocation to <TT>all</TT>, and | |
2889 | a section for your language module. | |
2890 | ||
2891 | <dt> <b>Source/Modules1.1/Makefile.in</b> | |
2892 | <dd> Add appropriate entries for vars <TT>OBJS</TT> and <TT>SRCS</TT>. | |
2893 | That's it! | |
2894 | ||
2895 | </dl> | |
2896 | ||
2897 | <p> | |
2898 | At some point it would be a good idea to use | |
2899 | <A HREF="http://www.gnu.org/software/automake/">automake</A> | |
2900 | to handle some of these configuration tasks, but that point is now | |
2901 | long past. If you are interested in working on that, feel free to | |
2902 | raise the issue in the context of a next-generation clean-slate SWIG. | |
2903 | ||
2904 | <H3><a name="Extending_nn40"></a>30.10.9 Runtime support</H3> | |
2905 | ||
2906 | ||
2907 | <p> | |
2908 | Discuss the kinds of functions typically needed for SWIG runtime support (e.g. | |
2909 | <tt>SWIG_ConvertPtr()</tt> and <tt>SWIG_NewPointerObj()</tt>) and the names of | |
2910 | the SWIG files that implement those functions. | |
2911 | </p> | |
2912 | ||
2913 | <H3><a name="Extending_nn41"></a>30.10.10 Standard library files</H3> | |
2914 | ||
2915 | ||
2916 | <p> | |
2917 | Discuss the standard library files that most language modules provide, e.g. | |
2918 | </p> | |
2919 | ||
2920 | <ul> | |
2921 | <li> typemaps.i </li> | |
2922 | <li> std_string.i </li> | |
2923 | <li> std_vector.i </li> | |
2924 | <li> stl.i </li> | |
2925 | </ul> | |
2926 | ||
2927 | <H3><a name="Extending_nn42"></a>30.10.11 Examples and test cases</H3> | |
2928 | ||
2929 | ||
2930 | <p> | |
2931 | Each of the language modules provides one or more examples. These examples | |
2932 | are used to demonstrate different features of the language module to SWIG | |
2933 | end-users, but you'll find that they're useful during development and testing | |
2934 | of your language module as well. You can use examples from the existing SWIG | |
2935 | language modules for inspiration. | |
2936 | </p> | |
2937 | ||
2938 | <p> | |
2939 | Each example is self-contained and consists of (at least) a <tt>Makefile</tt>, | |
2940 | a SWIG interface file for the example module, and a script that demonstrates | |
2941 | the functionality for that module. All of these files are stored in the same | |
2942 | subdirectory, and that directory should be nested under <tt>Examples/python</tt>. | |
2943 | For example, the files for the Python "simple" example are found in | |
2944 | <tt>Examples/python/simple</tt>. | |
2945 | </p> | |
2946 | ||
2947 | <p> | |
2948 | By default, all of the examples are built and run when the user types | |
2949 | <tt>make check</tt>. To ensure that your examples are automatically run | |
2950 | during this process, see the section on <a href="#n37a">configuration | |
2951 | files</a>. | |
2952 | </p> | |
2953 | ||
2954 | <H3><a name="Extending_nn43"></a>30.10.12 Documentation</H3> | |
2955 | ||
2956 | ||
2957 | <p> | |
2958 | Don't forget to write end-user documentation for your language module. Currently, | |
2959 | each language module has a dedicated chapter (although this structure may change | |
2960 | in the future). You shouldn't rehash things that are already covered in sufficient | |
2961 | detail in the <a href="SWIG.html#SWIG">SWIG Basics</a> and <a href="SWIGPlus.html#SWIGPlus">SWIG | |
2962 | and C++</a> chapters. There is no fixed format for <em>what</em>, exactly, you should | |
2963 | document about your language module, but you'll obviously want to cover issues that | |
2964 | are unique to your language. | |
2965 | </p> | |
2966 | ||
2967 | <p> | |
2968 | Some topics that you'll want to be sure to address include: | |
2969 | </p> | |
2970 | ||
2971 | <ul> | |
2972 | <li> Command line options unique to your language module. | |
2973 | <li> Non-obvious mappings between C/C++ and scripting language concepts. | |
2974 | For example, if your scripting language provides a single floating | |
2975 | point type, it should be no big surprise to find that C/C++ | |
2976 | <tt>float</tt> and <tt>double</tt> types are mapped to it. On the other | |
2977 | hand, if your scripting language doesn't provide support for "classes" | |
2978 | or something similar, you'd want to discuss how C++ classes are handled. | |
2979 | <li> How to compile the SWIG-generated wrapper code into shared libraries | |
2980 | that can actually be used. For some languages, there are well-defined | |
2981 | procedures for doing this, but for others it's an ad hoc process. | |
2982 | Provide as much detail as appropriate, and links to other resources | |
2983 | if available. | |
2984 | </ul> | |
2985 | ||
2986 | <H2><a name="Extending_nn44"></a>30.11 Typemaps</H2> | |
2987 | ||
2988 | ||
2989 | <H3><a name="Extending_nn45"></a>30.11.1 Proxy classes</H3> | |
2990 | ||
2991 | ||
2992 | <H2><a name="Extending_nn46"></a>30.12 Guide to parse tree nodes</H2> | |
2993 | ||
2994 | ||
2995 | <p> | |
2996 | This section describes the different parse tree nodes and their attributes. | |
2997 | </p> | |
2998 | ||
2999 | <p> | |
3000 | <b>cdecl</b> | |
3001 | </p> | |
3002 | ||
3003 | <p> | |
3004 | Describes general C declarations including variables, functions, and typedefs. | |
3005 | A declaration is parsed as "storage T D" where storage is a storage class, T is a base type, | |
3006 | and D is a declarator. | |
3007 | </p> | |
3008 | ||
3009 | <div class="diagram"> | |
3010 | <pre> | |
3011 | "name" - Declarator name | |
3012 | "type" - Base type T | |
3013 | "decl" - Declarator type (abstract) | |
3014 | "storage" - Storage class (static, extern, typedef, etc.) | |
3015 | "parms" - Function parameters (if a function) | |
3016 | "code" - Function body code (if supplied) | |
3017 | "value" - Default value (if supplied) | |
3018 | </pre> | |
3019 | ||
3020 | </div> | |
3021 | ||
3022 | <p> | |
3023 | <b>constructor</b> | |
3024 | </p> | |
3025 | ||
3026 | <p> | |
3027 | C++ constructor declaration. | |
3028 | </p> | |
3029 | ||
3030 | <div class="diagram"> | |
3031 | <pre> | |
3032 | "name" - Name of constructor | |
3033 | "parms" - Parameters | |
3034 | "decl" - Declarator (function with parameters) | |
3035 | "code" - Function body code (if any) | |
3036 | "feature:new" - Set to indicate return of new object. | |
3037 | </pre> | |
3038 | </div> | |
3039 | ||
3040 | ||
3041 | <p> | |
3042 | <b>destructor</b> | |
3043 | </p> | |
3044 | ||
3045 | <p> | |
3046 | C++ destructor declaration. | |
3047 | </p> | |
3048 | ||
3049 | <div class="diagram"> | |
3050 | <pre> | |
3051 | "name" - Name of destructor | |
3052 | "code" - Function body code (if any) | |
3053 | "storage" - Storage class (set if virtual) | |
3054 | "value" - Default value (set if pure virtual). | |
3055 | </pre> | |
3056 | </div> | |
3057 | ||
3058 | ||
3059 | <p> | |
3060 | <b>access</b> | |
3061 | </p> | |
3062 | ||
3063 | <p> | |
3064 | C++ access change. | |
3065 | </p> | |
3066 | ||
3067 | <div class="diagram"> | |
3068 | <pre> | |
3069 | "kind" - public, protected, private | |
3070 | </pre> | |
3071 | </div> | |
3072 | ||
3073 | ||
3074 | <p> | |
3075 | <b>constant</b> | |
3076 | </p> | |
3077 | ||
3078 | <p> | |
3079 | Constant created by %constant or #define. | |
3080 | </p> | |
3081 | ||
3082 | <div class="diagram"> | |
3083 | <pre> | |
3084 | "name" - Name of constant. | |
3085 | "type" - Base type. | |
3086 | "value" - Value. | |
3087 | "storage" - Set to %constant | |
3088 | "feature:immutable" - Set to indicate read-only | |
3089 | </pre> | |
3090 | </div> | |
3091 | ||
3092 | <p> | |
3093 | <b>class</b> | |
3094 | </p> | |
3095 | ||
3096 | <p> | |
3097 | C++ class definition or C structure definition. | |
3098 | </p> | |
3099 | ||
3100 | <div class="diagram"> | |
3101 | <pre> | |
3102 | "name" - Name of the class. | |
3103 | "kind" - Class kind ("struct", "union", "class") | |
3104 | "symtab" - Enclosing symbol table. | |
3105 | "tdname" - Typedef name. Use for typedef struct { ... } A. | |
3106 | "abstract" - Set if class has pure virtual methods. | |
3107 | "baselist" - List of base class names. | |
3108 | "storage" - Storage class (if any) | |
3109 | "unnamed" - Set if class is unnamed. | |
3110 | </pre> | |
3111 | </div> | |
3112 | ||
3113 | ||
3114 | <p> | |
3115 | <b>enum</b> | |
3116 | </p> | |
3117 | ||
3118 | <p> | |
3119 | Enumeration. | |
3120 | </p> | |
3121 | ||
3122 | <div class="diagram"> | |
3123 | <pre> | |
3124 | "name" - Name of the enum (if supplied). | |
3125 | "storage" - Storage class (if any) | |
3126 | "tdname" - Typedef name (typedef enum { ... } name). | |
3127 | "unnamed" - Set if enum is unnamed. | |
3128 | </pre> | |
3129 | </div> | |
3130 | ||
3131 | ||
3132 | <p> | |
3133 | <b>enumitem</b> | |
3134 | </p> | |
3135 | ||
3136 | <p> | |
3137 | Enumeration value. | |
3138 | </p> | |
3139 | ||
3140 | <div class="diagram"> | |
3141 | <pre> | |
3142 | "name" - Name of the enum value. | |
3143 | "type" - Type (integer or char) | |
3144 | "value" - Enum value (if given) | |
3145 | "feature:immutable" - Set to indicate read-only | |
3146 | </pre> | |
3147 | </div> | |
3148 | ||
3149 | <p> | |
3150 | <b>namespace</b> | |
3151 | </p> | |
3152 | ||
3153 | <p> | |
3154 | C++ namespace. | |
3155 | </p> | |
3156 | ||
3157 | <div class="diagram"> | |
3158 | <pre> | |
3159 | "name" - Name of the namespace. | |
3160 | "symtab" - Symbol table for enclosed scope. | |
3161 | "unnamed" - Set if unnamed namespace | |
3162 | "alias" - Alias name. Set for namespace A = B; | |
3163 | </pre> | |
3164 | </div> | |
3165 | ||
3166 | ||
3167 | <p> | |
3168 | <b>using</b> | |
3169 | </p> | |
3170 | ||
3171 | <p> | |
3172 | C++ using directive. | |
3173 | </p> | |
3174 | ||
3175 | <div class="diagram"> | |
3176 | <pre> | |
3177 | "name" - Name of the object being referred to. | |
3178 | "uname" - Qualified name actually given to using. | |
3179 | "node" - Node being referenced. | |
3180 | "namespace" - Namespace name being reference (using namespace name) | |
3181 | </pre> | |
3182 | </div> | |
3183 | ||
3184 | ||
3185 | <p> | |
3186 | <b>classforward</b> | |
3187 | </p> | |
3188 | ||
3189 | <p> | |
3190 | A forward C++ class declaration. | |
3191 | </p> | |
3192 | ||
3193 | <div class="diagram"> | |
3194 | <pre> | |
3195 | "name" - Name of the class. | |
3196 | "kind" - Class kind ("union", "struct", "class") | |
3197 | </pre> | |
3198 | </div> | |
3199 | ||
3200 | ||
3201 | <p> | |
3202 | <b>insert</b> | |
3203 | </p> | |
3204 | ||
3205 | <p> | |
3206 | Code insertion directive. For example, %{ ... %} or | |
3207 | %insert(section). | |
3208 | </p> | |
3209 | ||
3210 | <div class="diagram"> | |
3211 | <pre> | |
3212 | "code" - Inserted code | |
3213 | "section" - Section name ("header", "wrapper", etc.) | |
3214 | </pre> | |
3215 | </div> | |
3216 | ||
3217 | <p> | |
3218 | <b>top</b> | |
3219 | </p> | |
3220 | ||
3221 | <p> | |
3222 | Top of the parse tree. | |
3223 | </p> | |
3224 | ||
3225 | <div class="diagram"> | |
3226 | <pre> | |
3227 | "module" - Module name | |
3228 | </pre> | |
3229 | </div> | |
3230 | ||
3231 | <p> | |
3232 | <b>extend</b> | |
3233 | </p> | |
3234 | ||
3235 | <p> | |
3236 | %extend directive. | |
3237 | </p> | |
3238 | ||
3239 | <div class="diagram"> | |
3240 | <pre> | |
3241 | "name" - Module name | |
3242 | "symtab" - Symbol table of enclosed scope. | |
3243 | </pre> | |
3244 | </div> | |
3245 | ||
3246 | <p> | |
3247 | <b>apply</b> | |
3248 | </p> | |
3249 | ||
3250 | <p> | |
3251 | %apply pattern { patternlist }. | |
3252 | </p> | |
3253 | ||
3254 | <div class="diagram"> | |
3255 | <pre> | |
3256 | "pattern" - Source pattern. | |
3257 | "symtab" - Symbol table of enclosed scope. | |
3258 | </pre> | |
3259 | </div> | |
3260 | ||
3261 | <p> | |
3262 | <b>clear</b> | |
3263 | </p> | |
3264 | ||
3265 | <p> | |
3266 | %clear patternlist; | |
3267 | </p> | |
3268 | ||
3269 | <div class="diagram"> | |
3270 | <pre> | |
3271 | "firstChild" - Patterns to clear | |
3272 | </pre> | |
3273 | </div> | |
3274 | ||
3275 | <p> | |
3276 | <b>include</b> | |
3277 | </p> | |
3278 | ||
3279 | <p> | |
3280 | %include directive. | |
3281 | </p> | |
3282 | ||
3283 | <div class="diagram"> | |
3284 | <pre> | |
3285 | "name" - Filename | |
3286 | "firstChild" - Children | |
3287 | </pre> | |
3288 | </div> | |
3289 | ||
3290 | <p> | |
3291 | <b>import</b> | |
3292 | </p> | |
3293 | ||
3294 | <p> | |
3295 | %import directive. | |
3296 | </p> | |
3297 | ||
3298 | <div class="diagram"> | |
3299 | <pre> | |
3300 | "name" - Filename | |
3301 | "firstChild" - Children | |
3302 | </pre> | |
3303 | </div> | |
3304 | ||
3305 | ||
3306 | <p> | |
3307 | <b>module</b> | |
3308 | </p> | |
3309 | ||
3310 | <p> | |
3311 | %module directive. | |
3312 | </p> | |
3313 | ||
3314 | <div class="diagram"> | |
3315 | <pre> | |
3316 | "name" - Name of the module | |
3317 | </pre> | |
3318 | </div> | |
3319 | ||
3320 | ||
3321 | <p> | |
3322 | <b>typemap</b> | |
3323 | </p> | |
3324 | ||
3325 | <p> | |
3326 | %typemap directive. | |
3327 | </p> | |
3328 | ||
3329 | <div class="diagram"> | |
3330 | <pre> | |
3331 | "method" - Typemap method name. | |
3332 | "code" - Typemap code. | |
3333 | "kwargs" - Keyword arguments (if any) | |
3334 | "firstChild" - Typemap patterns | |
3335 | </pre> | |
3336 | </div> | |
3337 | ||
3338 | <p> | |
3339 | <b>typemapcopy</b> | |
3340 | </p> | |
3341 | ||
3342 | <p> | |
3343 | %typemap directive with copy. | |
3344 | </p> | |
3345 | ||
3346 | <div class="diagram"> | |
3347 | <pre> | |
3348 | "method" - Typemap method name. | |
3349 | "pattern" - Typemap source pattern. | |
3350 | "firstChild" - Typemap patterns | |
3351 | </pre> | |
3352 | </div> | |
3353 | ||
3354 | ||
3355 | <p> | |
3356 | <b>typemapitem</b> | |
3357 | </p> | |
3358 | ||
3359 | <p> | |
3360 | %typemap pattern. Used with %apply, %clear, %typemap. | |
3361 | </p> | |
3362 | ||
3363 | <div class="diagram"> | |
3364 | <pre> | |
3365 | "pattern" - Typemap pattern (a parameter list) | |
3366 | "parms" - Typemap parameters. | |
3367 | </pre> | |
3368 | </div> | |
3369 | ||
3370 | <p> | |
3371 | <b>types</b> | |
3372 | </p> | |
3373 | ||
3374 | <p> | |
3375 | %types directive. | |
3376 | </p> | |
3377 | ||
3378 | <div class="diagram"> | |
3379 | <pre> | |
3380 | "parms" - List of parameter types. | |
3381 | </pre> | |
3382 | </div> | |
3383 | ||
3384 | ||
3385 | <p> | |
3386 | <b>extern</b> | |
3387 | </p> | |
3388 | ||
3389 | <p> | |
3390 | extern "X" { ... } declaration. | |
3391 | </p> | |
3392 | ||
3393 | <div class="diagram"> | |
3394 | <pre> | |
3395 | "name" - Name "C", "Fortran", etc. | |
3396 | </pre> | |
3397 | </div> | |
3398 | ||
3399 | ||
3400 | ||
3401 | ||
3402 | </body> | |
3403 | </html> |