1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4 <title>Extending SWIG to support new languages</title>
5 <link rel="stylesheet" type="text/css" href="style.css">
8 <body bgcolor="#ffffff">
9 <H1><a name="Extending"></a>35 Extending SWIG to support new languages</H1>
11 <div class="sectiontoc">
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>
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>
27 <li><a href="#Extending_nn14">Primitive Data Structures</a>
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>
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>
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>
47 <li><a href="#Extending_nn30">Parameters</a>
48 <li><a href="#Extending_nn31">Writing a Language Module</a>
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 <li><a href="#Extending_prerequisites">Prerequisites for adding a new language module to the SWIG distribution</a>
63 <li><a href="#Extending_coding_style_guidelines">Coding style guidelines</a>
65 <li><a href="#Extending_nn44">Typemaps</a>
67 <li><a href="#Extending_nn45">Proxy classes</a>
69 <li><a href="#Extending_nn46">Guide to parse tree nodes</a>
76 <H2><a name="Extending_nn2"></a>35.1 Introduction</H2>
80 This chapter describes SWIG's internal organization and the process by which
81 new target languages can be developed. First, a brief word of warning---SWIG
82 is continually evolving.
83 The information in this chapter is mostly up to
84 date, but changes are ongoing. Expect a few inconsistencies.
88 Also, this chapter is not meant to be a hand-holding tutorial. As a starting point,
89 you should probably look at one of SWIG's existing modules.
92 <H2><a name="Extending_nn3"></a>35.2 Prerequisites</H2>
96 In order to extend SWIG, it is useful to have the following background:
100 <li>An understanding of the C API for the target language.
101 <li>A good grasp of the C++ type system.
102 <li>An understanding of typemaps and some of SWIG's advanced features.
103 <li>Some familiarity with writing C++ (language modules are currently written in C++).
107 Since SWIG is essentially a specialized C++ compiler, it may be useful
108 to have some prior experience with compiler design (perhaps even a
109 compilers course) to better understand certain parts of the system. A
110 number of books will also be useful. For example, "The C Programming
111 Language" by Kernighan and Ritchie (a.k.a, "K&R") and the C++ standard,
112 "ISO/IEC 14882 Programming Languages - C++" will be of great use.
116 Also, it is useful to keep in mind that SWIG primarily operates as an
117 extension of the C++ <em>type</em> system. At first glance, this might not be
118 obvious, but almost all SWIG directives as well as the low-level generation of
119 wrapper code are driven by C++ datatypes.
122 <H2><a name="Extending_nn4"></a>35.3 The Big Picture</H2>
126 SWIG is a special purpose compiler that parses C++ declarations to
127 generate wrapper code. To make this conversion possible, SWIG makes
128 three fundamental extensions to the C++ language:
132 <li><b>Typemaps</b>. Typemaps are used to define the
133 conversion/marshalling behavior of specific C++ datatypes. All type conversion in SWIG is
134 based on typemaps. Furthermore, the association of typemaps to datatypes utilizes an advanced pattern matching
135 mechanism that is fully integrated with the C++ type system.
138 <li><b>Declaration Annotation</b>. To customize wrapper code
139 generation, most declarations can be annotated with special features.
140 For example, you can make a variable read-only, you can ignore a
141 declaration, you can rename a member function, you can add exception
142 handling, and so forth. Virtually all of these customizations are built on top of a low-level
143 declaration annotator that can attach arbitrary attributes to any declaration.
144 Code generation modules can look for these attributes to guide the wrapping process.
147 <li><b>Class extension</b>. SWIG allows classes and structures to be extended with new
148 methods and attributes (the <tt>%extend</tt> directive). This has the effect of altering
149 the API in the target language and can be used to generate OO interfaces to C libraries.
153 It is important to emphasize that virtually all SWIG features reduce to one of these three
154 fundamental concepts. The type system and pattern matching rules also play a critical
155 role in making the system work. For example, both typemaps and declaration annotation are
156 based on pattern matching and interact heavily with the underlying type system.
159 <H2><a name="Extending_nn5"></a>35.4 Execution Model</H2>
163 When you run SWIG on an interface, processing is handled in stages by a series of system components:
167 <li>An integrated C preprocessor reads a collection of configuration
168 files and the specified interface file into memory. The preprocessor
169 performs the usual functions including macro expansion and file
170 inclusion. However, the preprocessor also performs some transformations of the
171 interface. For instance, <tt>#define</tt> statements are sometimes transformed into
172 <tt>%constant</tt> declarations. In addition, information related to file/line number
173 tracking is inserted.
176 <li>A C/C++ parser reads the preprocessed input and generates a full
177 parse tree of all of the SWIG directives and C declarations found.
178 The parser is responsible for many aspects of the system including
179 renaming, declaration annotation, and template expansion. However, the parser
180 does not produce any output nor does it interact with the target
181 language module as it runs. SWIG is not a one-pass compiler.
184 <li>A type-checking pass is made. This adjusts all of the C++ typenames to properly
185 handle namespaces, typedefs, nested classes, and other issues related to type scoping.
188 <li>A semantic pass is made on the parse tree to collect information
189 related to properties of the C++ interface. For example, this pass
190 would determine whether or not a class allows a default constructor.
193 <li>A code generation pass is made using a specific target language
194 module. This phase is responsible for generating the actual wrapper
195 code. All of SWIG's user-defined modules are invoked during this
196 latter stage of compilation.
201 The next few sections briefly describe some of these stages.
204 <H3><a name="Extending_nn6"></a>35.4.1 Preprocessing</H3>
208 The preprocessor plays a critical role in the SWIG implementation. This is because a lot
209 of SWIG's processing and internal configuration is managed not by code written in C, but
210 by configuration files in the SWIG library. In fact, when you
211 run SWIG, parsing starts with a small interface file like this (note: this explains
212 the cryptic error messages that new users sometimes get when SWIG is misconfigured or installed
218 %include "swig.swg" // Global SWIG configuration
219 %include "<em>langconfig.swg</em>" // Language specific configuration
220 %include "yourinterface.i" // Your interface file
225 The <tt>swig.swg</tt> file contains global configuration information. In addition, this file
226 defines many of SWIG's standard directives as macros. For instance, part of
227 of <tt>swig.swg</tt> looks like this:
233 /* Code insertion directives such as %wrapper %{ ... %} */
235 #define %begin %insert("begin")
236 #define %runtime %insert("runtime")
237 #define %header %insert("header")
238 #define %wrapper %insert("wrapper")
239 #define %init %insert("init")
241 /* Access control directives */
243 #define %immutable %feature("immutable","1")
244 #define %mutable %feature("immutable")
246 /* Directives for callback functions */
248 #define %callback(x) %feature("callback") `x`;
249 #define %nocallback %feature("callback");
251 /* %ignore directive */
253 #define %ignore %rename($ignore)
254 #define %ignorewarn(x) %rename("$ignore:" x)
260 The fact that most of the standard SWIG directives are macros is
261 intended to simplify the implementation of the internals. For instance,
262 rather than having to support dozens of special directives, it is
263 easier to have a few basic primitives such as <tt>%feature</tt> or
268 The <em><tt>langconfig.swg</tt></em> file is supplied by the target
269 language. This file contains language-specific configuration
270 information. More often than not, this file provides run-time wrapper
271 support code (e.g., the type-checker) as well as a collection of
272 typemaps that define the default wrapping behavior. Note: the name of this
273 file depends on the target language and is usually something like <tt>python.swg</tt>
274 or <tt>perl5.swg</tt>.
278 As a debugging aide, the text that SWIG feeds to its C++ parser can be
279 obtained by running <tt>swig -E interface.i</tt>. This output
280 probably isn't too useful in general, but it will show how macros have
281 been expanded as well as everything else that goes into the low-level
282 construction of the wrapper code.
285 <H3><a name="Extending_nn7"></a>35.4.2 Parsing</H3>
289 The current C++ parser handles a subset of C++. Most incompatibilities with C are due to
290 subtle aspects of how SWIG parses declarations. Specifically, SWIG expects all C/C++ declarations to follow this general form:
293 <div class="diagram">
295 <em>storage</em> <em>type</em> <em>declarator</em> <em>initializer</em>;
300 <tt><em>storage</em></tt> is a keyword such as <tt>extern</tt>,
301 <tt>static</tt>, <tt>typedef</tt>, or <tt>virtual</tt>. <tt><em>type</em></tt> is a primitive
302 datatype such as <tt>int</tt> or <tt>void</tt>. <tt><em>type</em></tt> may be optionally
303 qualified with a qualifier such as <tt>const</tt> or <tt>volatile</tt>. <tt><em>declarator</em></tt>
304 is a name with additional type-construction modifiers attached to it (pointers, arrays, references,
305 functions, etc.). Examples of declarators include <tt>*x</tt>, <tt>**x</tt>, <tt>x[20]</tt>, and
306 <tt>(*x)(int,double)</tt>. The <tt><em>initializer</em></tt> may be a value assigned using <tt>=</tt> or
307 body of code enclosed in braces <tt>{ ... }</tt>.
311 This declaration format covers most common C++ declarations. However, the C++ standard
312 is somewhat more flexible in the placement of the parts. For example, it is technically legal, although
313 uncommon to write something like <tt>int typedef const a</tt> in your program. SWIG simply
314 doesn't bother to deal with this case.
318 The other significant difference between C++ and SWIG is in the
319 treatment of typenames. In C++, if you have a declaration like this,
324 int blah(Foo *x, Bar *y);
329 it won't parse correctly unless <tt>Foo</tt> and <tt>Bar</tt> have
330 been previously defined as types either using a <tt>class</tt>
331 definition or a <tt>typedef</tt>. The reasons for this are subtle,
332 but this treatment of typenames is normally integrated at the level of the C
333 tokenizer---when a typename appears, a different token is returned to the parser
334 instead of an identifier.
338 SWIG does not operate in this manner--any legal identifier can be used
339 as a type name. The reason for this is primarily motivated by the use
340 of SWIG with partially defined data. Specifically,
341 SWIG is supposed to be easy to use on interfaces with missing type information.
345 Because of the different treatment of typenames, the most serious
346 limitation of the SWIG parser is that it can't process type declarations where
347 an extra (and unnecessary) grouping operator is used. For example:
352 int (x); /* A variable x */
353 int (y)(int); /* A function y */
358 The placing of extra parentheses in type declarations like this is
359 already recognized by the C++ community as a potential source of
360 strange programming errors. For example, Scott Meyers "Effective STL"
361 discusses this problem in a section on avoiding C++'s "most vexing
366 The parser is also unable to handle declarations with no return type or bare argument names.
367 For example, in an old C program, you might see things like this:
379 In this case, the return type as well as the types of the arguments
380 are taken by the C compiler to be an <tt>int</tt>. However, SWIG
381 interprets the above code as an abstract declarator for a function
382 returning a <tt>foo</tt> and taking types <tt>a</tt> and <tt>b</tt> as
386 <H3><a name="Extending_nn8"></a>35.4.3 Parse Trees</H3>
390 The SWIG parser produces a complete parse tree of the input file before any wrapper code
391 is actually generated. Each item in the tree is known as a "Node". Each node is identified
392 by a symbolic tag. Furthermore, a node may have an arbitrary number of children.
393 The parse tree structure and tag names of an interface can be displayed using <tt>swig -debug-tags</tt>.
399 $ <b>swig -c++ -python -debug-tags example.i</b>
401 . top . include (example.i:1)
402 . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/swig.swg:71)
403 . top . include . typemap . typemapitem (/r0/beazley/Projects/lib/swig1.3/swig.swg:71)
404 . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/swig.swg:83)
405 . top . include . typemap . typemapitem (/r0/beazley/Projects/lib/swig1.3/swig.swg:83)
406 . top . include (example.i:4)
407 . top . include . insert (/r0/beazley/Projects/lib/swig1.3/python/python.swg:7)
408 . top . include . insert (/r0/beazley/Projects/lib/swig1.3/python/python.swg:8)
409 . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/python/python.swg:19)
411 . top . include (example.i:6)
412 . top . include . module (example.i:2)
413 . top . include . insert (example.i:6)
414 . top . include . include (example.i:9)
415 . top . include . include . class (example.h:3)
416 . top . include . include . class . access (example.h:4)
417 . top . include . include . class . constructor (example.h:7)
418 . top . include . include . class . destructor (example.h:10)
419 . top . include . include . class . cdecl (example.h:11)
420 . top . include . include . class . cdecl (example.h:11)
421 . top . include . include . class . cdecl (example.h:12)
422 . top . include . include . class . cdecl (example.h:13)
423 . top . include . include . class . cdecl (example.h:14)
424 . top . include . include . class . cdecl (example.h:15)
425 . top . include . include . class (example.h:18)
426 . top . include . include . class . access (example.h:19)
427 . top . include . include . class . cdecl (example.h:20)
428 . top . include . include . class . access (example.h:21)
429 . top . include . include . class . constructor (example.h:22)
430 . top . include . include . class . cdecl (example.h:23)
431 . top . include . include . class . cdecl (example.h:24)
432 . top . include . include . class (example.h:27)
433 . top . include . include . class . access (example.h:28)
434 . top . include . include . class . cdecl (example.h:29)
435 . top . include . include . class . access (example.h:30)
436 . top . include . include . class . constructor (example.h:31)
437 . top . include . include . class . cdecl (example.h:32)
438 . top . include . include . class . cdecl (example.h:33)
443 Even for the most simple interface, the parse tree structure is larger than you might expect. For example, in the
444 above output, a substantial number of nodes are actually generated by the <tt>python.swg</tt> configuration file
445 which defines typemaps and other directives. The contents of the user-supplied input file don't appear until the end
450 The contents of each parse tree node consist of a collection of attribute/value
451 pairs. Internally, the nodes are simply represented by hash tables. A display of
452 the entire parse-tree structure can be obtained using <tt>swig -debug-top <n></tt>, where <tt>n</tt> is
453 the stage being processed.
454 There are a number of other parse tree display options, for example, <tt>swig -debug-module <n></tt> will
455 avoid displaying system parse information and only display the parse tree pertaining to the user's module at
456 stage <tt>n</tt> of processing.
461 $ swig -c++ -python -debug-module 4 example.i
462 +++ include ----------------------------------------
465 +++ module ----------------------------------------
468 +++ insert ----------------------------------------
469 | code - "\n#include \"example.h\"\n"
471 +++ include ----------------------------------------
474 +++ class ----------------------------------------
479 | symtab - 0x40194140
480 | sym:symtab - 0x40191078
482 +++ access ----------------------------------------
485 +++ constructor ----------------------------------------
489 | code - "{\n nshapes++;\n }"
490 | sym:symtab - 0x40194140
492 +++ destructor ----------------------------------------
493 | sym:name - "~Shape"
495 | storage - "virtual"
496 | code - "{\n nshapes--;\n }"
497 | sym:symtab - 0x40194140
499 +++ cdecl ----------------------------------------
504 | sym:symtab - 0x40194140
506 +++ cdecl ----------------------------------------
511 | sym:symtab - 0x40194140
513 +++ cdecl ----------------------------------------
516 | decl - "f(double,double)."
517 | parms - double ,double
519 | sym:symtab - 0x40194140
521 +++ cdecl ----------------------------------------
526 | storage - "virtual"
529 | sym:symtab - 0x40194140
531 +++ cdecl ----------------------------------------
532 | sym:name - "perimeter"
536 | storage - "virtual"
539 | sym:symtab - 0x40194140
541 +++ cdecl ----------------------------------------
542 | sym:name - "nshapes"
547 | sym:symtab - 0x40194140
549 +++ class ----------------------------------------
550 | sym:name - "Circle"
554 | symtab - 0x40194538
555 | sym:symtab - 0x40191078
557 +++ access ----------------------------------------
560 +++ cdecl ----------------------------------------
565 +++ access ----------------------------------------
568 +++ constructor ----------------------------------------
569 | sym:name - "Circle"
572 | decl - "f(double)."
574 | sym:symtab - 0x40194538
576 +++ cdecl ----------------------------------------
581 | storage - "virtual"
583 | sym:symtab - 0x40194538
585 +++ cdecl ----------------------------------------
586 | sym:name - "perimeter"
590 | storage - "virtual"
592 | sym:symtab - 0x40194538
594 +++ class ----------------------------------------
595 | sym:name - "Square"
599 | symtab - 0x40194788
600 | sym:symtab - 0x40191078
602 +++ access ----------------------------------------
605 +++ cdecl ----------------------------------------
610 +++ access ----------------------------------------
613 +++ constructor ----------------------------------------
614 | sym:name - "Square"
617 | decl - "f(double)."
619 | sym:symtab - 0x40194788
621 +++ cdecl ----------------------------------------
626 | storage - "virtual"
628 | sym:symtab - 0x40194788
630 +++ cdecl ----------------------------------------
631 | sym:name - "perimeter"
635 | storage - "virtual"
637 | sym:symtab - 0x40194788
641 <H3><a name="Extending_nn9"></a>35.4.4 Attribute namespaces</H3>
645 Attributes of parse tree nodes are often prepended with a namespace qualifier.
646 For example, the attributes
647 <tt>sym:name</tt> and <tt>sym:symtab</tt> are attributes related to
648 symbol table management and are prefixed with <tt>sym:</tt>. As a
649 general rule, only those attributes which are directly related to the raw declaration
650 appear without a prefix (type, name, declarator, etc.).
654 Target language modules may add additional attributes to nodes to assist the generation
655 of wrapper code. The convention for doing this is to place these attributes in a namespace
656 that matches the name of the target language. For example, <tt>python:foo</tt> or
660 <H3><a name="Extending_nn10"></a>35.4.5 Symbol Tables</H3>
664 During parsing, all symbols are managed in the space of the target
665 language. The <tt>sym:name</tt> attribute of each node contains the symbol name
666 selected by the parser. Normally, <tt>sym:name</tt> and <tt>name</tt>
667 are the same. However, the <tt>%rename</tt> directive can be used to
668 change the value of <tt>sym:name</tt>. You can see the effect of
669 <tt>%rename</tt> by trying it on a simple interface and dumping the
670 parse tree. For example:
675 %rename(foo_i) foo(int);
676 %rename(foo_d) foo(double);
685 There are various <tt>debug-</tt> options that can be useful for debugging and analysing the parse tree.
686 For example, the <tt>debug-top <n></tt> or <tt>debug-module <n></tt> options will
687 dump the entire/top of the parse tree or the module subtree at one of the four <tt>n</tt> stages of processing.
688 The parse tree can be viewed after the final stage of processing by running SWIG:
693 $ swig -debug-top 4 example.i
695 +++ cdecl ----------------------------------------
701 | sym:symtab - 0x40165078
703 +++ cdecl ----------------------------------------
706 | decl - "f(double)."
709 | sym:symtab - 0x40165078
711 +++ cdecl ----------------------------------------
717 | sym:symtab - 0x40165078
722 All symbol-related conflicts and complaints about overloading are based on <tt>sym:name</tt> values.
723 For instance, the following example uses <tt>%rename</tt> in reverse to generate a name clash.
728 %rename(foo) foo_i(int);
729 %rename(foo) foo_d(double;
738 When you run SWIG on this you now get:
744 example.i:6. Overloaded declaration ignored. foo_d(double )
745 example.i:5. Previous declaration is foo_i(int )
746 example.i:7. Overloaded declaration ignored. foo(Bar *)
747 example.i:5. Previous declaration is foo_i(int )
751 <H3><a name="Extending_nn11"></a>35.4.6 The %feature directive</H3>
755 A number of SWIG directives such as <tt>%exception</tt> are implemented using the
756 low-level <tt>%feature</tt> directive. For example:
761 %feature("except") getitem(int) {
772 Object *getitem(int index) throws(badindex);
779 The behavior of <tt>%feature</tt> is very easy to describe--it simply
780 attaches a new attribute to any parse tree node that matches the
781 given prototype. When a feature is added, it shows up as an attribute in the <tt>feature:</tt> namespace.
782 You can see this when running with the <tt>-debug-top 4</tt> option. For example:
787 +++ cdecl ----------------------------------------
788 | sym:name - "getitem"
793 | feature:except - "{\n try {\n $action\n } catc..."
794 | sym:symtab - 0x40168ac8
800 Feature names are completely arbitrary and a target language module can be
801 programmed to respond to any feature name that it wants to recognize. The
802 data stored in a feature attribute is usually just a raw unparsed string.
803 For example, the exception code above is simply
804 stored without any modifications.
807 <H3><a name="Extending_nn12"></a>35.4.7 Code Generation</H3>
811 Language modules work by defining handler functions that know how to respond to
812 different types of parse-tree nodes. These handlers simply look at the
813 attributes of each node in order to produce low-level code.
817 In reality, the generation of code is somewhat more subtle than simply
818 invoking handler functions. This is because parse-tree nodes might be
819 transformed. For example, suppose you are wrapping a class like this:
826 virtual int *bar(int x);
832 When the parser constructs a node for the member <tt>bar</tt>, it creates a raw "cdecl" node with the following
836 <div class="diagram">
849 To produce wrapper code, this "cdecl" node undergoes a number of transformations. First, the node is recognized as a function declaration. This adjusts some of the type information--specifically, the declarator is joined with the base datatype to produce this:
852 <div class="diagram">
856 type : p.int <-- Notice change in return type
865 Next, the context of the node indicates that the node is really a
866 member function. This produces a transformation to a low-level
867 accessor function like this:
870 <div class="diagram">
876 parms : Foo *self, int x <-- Added parameter
878 wrap:action : result = (arg1)->bar(arg2) <-- Action code added
879 sym:name : Foo_bar <-- Symbol name changed
884 In this transformation, notice how an additional parameter was added
885 to the parameter list and how the symbol name of the node has suddenly
886 changed into an accessor using the naming scheme described in the
887 "SWIG Basics" chapter. A small fragment of "action" code has also
888 been generated--notice how the <tt>wrap:action</tt> attribute defines
889 the access to the underlying method. The data in this transformed
890 node is then used to generate a wrapper.
894 Language modules work by registering handler functions for dealing with
895 various types of nodes at different stages of transformation. This is done by
896 inheriting from a special <tt>Language</tt> class and defining a collection
897 of virtual methods. For example, the Python module defines a class as
903 class PYTHON : public Language {
906 virtual void main(int, char *argv[]);
907 virtual int top(Node *);
908 virtual int functionWrapper(Node *);
909 virtual int constantWrapper(Node *);
910 virtual int variableWrapper(Node *);
911 virtual int nativeWrapper(Node *);
912 virtual int membervariableHandler(Node *);
913 virtual int memberconstantHandler(Node *);
914 virtual int memberfunctionHandler(Node *);
915 virtual int constructorHandler(Node *);
916 virtual int destructorHandler(Node *);
917 virtual int classHandler(Node *);
918 virtual int classforwardDeclaration(Node *);
919 virtual int insertDirective(Node *);
920 virtual int importDirective(Node *);
926 The role of these functions is described shortly.
929 <H3><a name="Extending_nn13"></a>35.4.8 SWIG and XML</H3>
933 Much of SWIG's current parser design was originally motivated by
934 interest in using XML to represent SWIG parse trees. Although XML is
935 not currently used in any direct manner, the parse tree structure, use
936 of node tags, attributes, and attribute namespaces are all influenced
937 by aspects of XML parsing. Therefore, in trying to understand SWIG's
938 internal data structures, it may be useful to keep XML in the back of
939 your mind as a model.
942 <H2><a name="Extending_nn14"></a>35.5 Primitive Data Structures</H2>
946 Most of SWIG is constructed using three basic data structures:
947 strings, hashes, and lists. These data structures are dynamic in same way as
948 similar structures found in many scripting languages. For instance,
949 you can have containers (lists and hash tables) of mixed types and
950 certain operations are polymorphic.
954 This section briefly describes the basic structures so that later
955 sections of this chapter make more sense.
959 When describing the low-level API, the following type name conventions are
964 <li><tt>String</tt>. A string object.
965 <li><tt>Hash</tt>. A hash object.
966 <li><tt>List</tt>. A list object.
967 <li><tt>String_or_char</tt>. A string object or a <tt>char *</tt>.
968 <li><tt>Object_or_char</tt>. An object or a <tt>char *</tt>.
969 <li><tt>Object</tt>. Any object (string, hash, list, etc.)
973 In most cases, other typenames in the source are aliases for one of these
974 primitive types. Specifically:
979 typedef String SwigType;
981 typedef Hash ParmList;
984 typedef Hash Typetab;
988 <H3><a name="Extending_nn15"></a>35.5.1 Strings</H3>
992 <b><tt>String *NewString(const String_or_char *val)</tt></b>
996 Creates a new string with initial value <tt>val</tt>. <tt>val</tt> may
997 be a <tt>char *</tt> or another <tt>String</tt> object. If you want
998 to create an empty string, use "" for val.
1002 <b><tt>String *NewStringf(const char *fmt, ...)</tt></b>
1005 <div class="indent">
1006 Creates a new string whose initial value is set according to a C <tt>printf</tt> style
1007 format string in <tt>fmt</tt>. Additional arguments follow depending
1012 <b><tt>String *Copy(String *s)</tt></b>
1015 <div class="indent">
1016 Make a copy of the string <tt>s</tt>.
1020 <b><tt>void Delete(String *s)</tt></b>
1023 <div class="indent">
1028 <b><tt>int Len(const String_or_char *s)</tt></b>
1031 <div class="indent">
1032 Returns the length of the string.
1036 <b><tt>char *Char(const String_or_char *s)</tt></b>
1039 <div class="indent">
1040 Returns a pointer to the first character in a string.
1044 <b><tt>void Append(String *s, const String_or_char *t)</tt></b>
1047 <div class="indent">
1048 Appends <tt>t</tt> to the end of string <tt>s</tt>.
1052 <b><tt>void Insert(String *s, int pos, const String_or_char *t)</tt></b>
1055 <div class="indent">
1056 Inserts <tt>t</tt> into <tt>s</tt> at position <tt>pos</tt>. The contents
1057 of <tt>s</tt> are shifted accordingly. The special value <tt>DOH_END</tt>
1058 can be used for <tt>pos</tt> to indicate insertion at the end of the string (appending).
1062 <b><tt>int Strcmp(const String_or_char *s, const String_or_char *t)</tt></b>
1065 <div class="indent">
1066 Compare strings <tt>s</tt> and <tt>t</tt>. Same as the C <tt>strcmp()</tt>
1071 <b><tt>int Strncmp(const String_or_char *s, const String_or_char *t, int len)</tt></b>
1074 <div class="indent">
1075 Compare the first <tt>len</tt> characters of strings <tt>s</tt> and <tt>t</tt>. Same as the C <tt>strncmp()</tt>
1080 <b><tt>char *Strstr(const String_or_char *s, const String_or_char *pat)</tt></b>
1083 <div class="indent">
1084 Returns a pointer to the first occurrence of <tt>pat</tt> in <tt>s</tt>.
1085 Same as the C <tt>strstr()</tt> function.
1089 <b><tt>char *Strchr(const String_or_char *s, char ch)</tt></b>
1092 <div class="indent">
1093 Returns a pointer to the first occurrence of character <tt>ch</tt> in <tt>s</tt>.
1094 Same as the C <tt>strchr()</tt> function.
1098 <b><tt>void Chop(String *s)</tt></b>
1101 <div class="indent">
1102 Chops trailing whitespace off the end of <tt>s</tt>.
1106 <b><tt>int Replace(String *s, const String_or_char *pat, const String_or_char *rep, int flags)</tt></b>
1109 <div class="indent">
1111 Replaces the pattern <tt>pat</tt> with <tt>rep</tt> in string <tt>s</tt>.
1112 <tt>flags</tt> is a combination of the following flags:</p>
1116 DOH_REPLACE_ANY - Replace all occurrences
1117 DOH_REPLACE_ID - Valid C identifiers only
1118 DOH_REPLACE_NOQUOTE - Don't replace in quoted strings
1119 DOH_REPLACE_FIRST - Replace first occurrence only.
1124 Returns the number of replacements made (if any).
1129 <H3><a name="Extending_nn16"></a>35.5.2 Hashes</H3>
1133 <b><tt>Hash *NewHash()</tt></b>
1136 <div class="indent">
1137 Creates a new empty hash table.
1141 <b><tt>Hash *Copy(Hash *h)</tt></b>
1144 <div class="indent">
1145 Make a shallow copy of the hash <tt>h</tt>.
1149 <b><tt>void Delete(Hash *h)</tt></b>
1152 <div class="indent">
1157 <b><tt>int Len(Hash *h)</tt></b>
1160 <div class="indent">
1161 Returns the number of items in <tt>h</tt>.
1165 <b><tt>Object *Getattr(Hash *h, const String_or_char *key)</tt></b>
1168 <div class="indent">
1169 Gets an object from <tt>h</tt>. <tt>key</tt> may be a string or
1170 a simple <tt>char *</tt> string. Returns NULL if not found.
1174 <b><tt>int Setattr(Hash *h, const String_or_char *key, const Object_or_char *val)</tt></b>
1177 <div class="indent">
1178 Stores <tt>val</tt> in <tt>h</tt>. <tt>key</tt> may be a string or
1179 a simple <tt>char *</tt>. If <tt>val</tt> is not a standard
1180 object (String, Hash, or List) it is assumed to be a <tt>char *</tt> in which
1181 case it is used to construct a <tt>String</tt> that is stored in the hash.
1182 If <tt>val</tt> is NULL, the object is deleted. Increases the reference count
1183 of <tt>val</tt>. Returns 1 if this operation replaced an existing hash entry,
1188 <b><tt>int Delattr(Hash *h, const String_or_char *key)</tt></b>
1191 <div class="indent">
1192 Deletes the hash item referenced by <tt>key</tt>. Decreases the
1193 reference count on the corresponding object (if any). Returns 1
1194 if an object was removed, 0 otherwise.
1198 <b><tt>List *Keys(Hash *h)</tt></b>
1201 <div class="indent">
1202 Returns the list of hash table keys.
1206 <H3><a name="Extending_nn17"></a>35.5.3 Lists</H3>
1210 <b><tt>List *NewList()</tt></b>
1213 <div class="indent">
1214 Creates a new empty list.
1218 <b><tt>List *Copy(List *x)</tt></b>
1221 <div class="indent">
1222 Make a shallow copy of the List <tt>x</tt>.
1226 <b><tt>void Delete(List *x)</tt></b>
1229 <div class="indent">
1234 <b><tt>int Len(List *x)</tt></b>
1237 <div class="indent">
1238 Returns the number of items in <tt>x</tt>.
1242 <b><tt>Object *Getitem(List *x, int n)</tt></b>
1245 <div class="indent">
1246 Returns an object from <tt>x</tt> with index <tt>n</tt>. If <tt>n</tt> is
1247 beyond the end of the list, the last item is returned. If <tt>n</tt> is
1248 negative, the first item is returned.
1252 <b><tt>int *Setitem(List *x, int n, const Object_or_char *val)</tt></b>
1255 <div class="indent">
1256 Stores <tt>val</tt> in <tt>x</tt>.
1257 If <tt>val</tt> is not a standard
1258 object (String, Hash, or List) it is assumed to be a <tt>char *</tt> in which
1259 case it is used to construct a <tt>String</tt> that is stored in the list.
1260 <tt>n</tt> must be in range. Otherwise, an assertion will be raised.
1264 <b><tt>int *Delitem(List *x, int n)</tt></b>
1267 <div class="indent">
1268 Deletes item <tt>n</tt> from the list, shifting items down if necessary.
1269 To delete the last item in the list, use the special value <tt>DOH_END</tt>
1274 <b><tt>void Append(List *x, const Object_or_char *t)</tt></b>
1277 <div class="indent">
1278 Appends <tt>t</tt> to the end of <tt>x</tt>. If <tt>t</tt> is not
1279 a standard object, it is assumed to be a <tt>char *</tt> and is
1280 used to create a String object.
1284 <b><tt>void Insert(String *s, int pos, const Object_or_char *t)</tt></b>
1287 <div class="indent">
1288 Inserts <tt>t</tt> into <tt>s</tt> at position <tt>pos</tt>. The contents
1289 of <tt>s</tt> are shifted accordingly. The special value <tt>DOH_END</tt>
1290 can be used for <tt>pos</tt> to indicate insertion at the end of the list (appending).
1291 If <tt>t</tt> is not a standard object, it is assumed to be a <tt>char *</tt>
1292 and is used to create a String object.
1295 <H3><a name="Extending_nn18"></a>35.5.4 Common operations</H3>
1298 The following operations are applicable to all datatypes.
1301 <b><tt>Object *Copy(Object *x)</tt></b>
1304 <div class="indent">
1305 Make a copy of the object <tt>x</tt>.
1309 <b><tt>void Delete(Object *x)</tt></b>
1312 <div class="indent">
1317 <b><tt>void Setfile(Object *x, String_or_char *f)</tt></b>
1320 <div class="indent">
1321 Sets the filename associated with <tt>x</tt>. Used to track
1322 objects and report errors.
1326 <b><tt>String *Getfile(Object *x)</tt></b>
1329 <div class="indent">
1330 Gets the filename associated with <tt>x</tt>.
1334 <b><tt>void Setline(Object *x, int n)</tt></b>
1337 <div class="indent">
1338 Sets the line number associated with <tt>x</tt>. Used to track
1339 objects and report errors.
1343 <b><tt>int Getline(Object *x)</tt></b>
1346 <div class="indent">
1347 Gets the line number associated with <tt>x</tt>.
1350 <H3><a name="Extending_nn19"></a>35.5.5 Iterating over Lists and Hashes</H3>
1353 To iterate over the elements of a list or a hash table, the following functions are used:
1356 <b><tt>Iterator First(Object *x)</tt></b>
1359 <div class="indent">
1360 Returns an iterator object that points to the first item in a list or hash table. The
1361 <tt>item</tt> attribute of the Iterator object is a pointer to the item. For hash tables, the <tt>key</tt> attribute
1362 of the Iterator object additionally points to the corresponding Hash table key. The <tt>item</tt> and <tt>key</tt> attributes
1363 are NULL if the object contains no items or if there are no more items.
1367 <b><tt>Iterator Next(Iterator i)</tt></b>
1370 <div class="indent">
1371 <p>Returns an iterator that points to the next item in a list or hash table.
1373 Here are two examples of iteration:</p>
1377 List *l = (some list);
1380 for (i = First(l); i.item; i = Next(i)) {
1381 Printf(stdout,"%s\n", i.item);
1384 Hash *h = (some hash);
1387 for (j = First(j); j.item; j= Next(j)) {
1388 Printf(stdout,"%s : %s\n", j.key, j.item);
1395 <H3><a name="Extending_nn20"></a>35.5.6 I/O</H3>
1398 Special I/O functions are used for all internal I/O. These operations
1399 work on C <tt>FILE *</tt> objects, String objects, and special <tt>File</tt> objects
1400 (which are merely a wrapper around <tt>FILE *</tt>).
1403 <b><tt>int Printf(String_or_FILE *f, const char *fmt, ...)</tt></b>
1406 <div class="indent">
1407 Formatted I/O. Same as the C <tt>fprintf()</tt> function except that output
1408 can also be directed to a string object. Note: the <tt>%s</tt> format
1409 specifier works with both strings and <tt>char *</tt>. All other format
1410 operators have the same meaning.
1414 <b><tt>int Printv(String_or_FILE *f, String_or_char *arg1,..., NULL)</tt></b>
1417 <div class="indent">
1418 Prints a variable number of strings arguments to the output. The last
1419 argument to this function must be NULL. The other arguments can either
1420 be <tt>char *</tt> or string objects.
1424 <b><tt>int Putc(int ch, String_or_FILE *f)</tt></b>
1427 <div class="indent">
1428 Same as the C <tt>fputc()</tt> function.
1432 <b><tt>int Write(String_or_FILE *f, void *buf, int len)</tt></b>
1435 <div class="indent">
1436 Same as the C <tt>write()</tt> function.
1440 <b><tt>int Read(String_or_FILE *f, void *buf, int maxlen)</tt></b>
1443 <div class="indent">
1444 Same as the C <tt>read()</tt> function.
1448 <b><tt>int Getc(String_or_FILE *f)</tt></b>
1451 <div class="indent">
1452 Same as the C <tt>fgetc()</tt> function.
1456 <b><tt>int Ungetc(int ch, String_or_FILE *f)</tt></b>
1459 <div class="indent">
1460 Same as the C <tt>ungetc()</tt> function.
1464 <b><tt>int Seek(String_or_FILE *f, int offset, int whence)</tt></b>
1467 <div class="indent">
1468 Same as the C <tt>seek()</tt> function. <tt>offset</tt> is the number
1469 of bytes. <tt>whence</tt> is one of <tt>SEEK_SET</tt>,<tt>SEEK_CUR</tt>,
1470 or <tt>SEEK_END</tt>..
1474 <b><tt>long Tell(String_or_FILE *f)</tt></b>
1477 <div class="indent">
1478 Same as the C <tt>tell()</tt> function.
1482 <b><tt>File *NewFile(const char *filename, const char *mode, List *newfiles)</tt></b>
1485 <div class="indent">
1486 Create a File object using the <tt>fopen()</tt> library call. This
1487 file differs from <tt>FILE *</tt> in that it can be placed in the standard
1488 SWIG containers (lists, hashes, etc.). The <tt>filename</tt> is added to the
1489 <tt>newfiles</tt> list if <tt>newfiles</tt> is non-zero and the file was created successfully.
1493 <b><tt>File *NewFileFromFile(FILE *f)</tt></b>
1496 <div class="indent">
1497 Create a File object wrapper around an existing <tt>FILE *</tt> object.
1501 <b><tt>int Close(String_or_FILE *f)</tt></b>
1504 <div class="indent">
1505 <p>Closes a file. Has no effect on strings.</p>
1508 The use of the above I/O functions and strings play a critical role in SWIG. It is
1509 common to see small code fragments of code generated using code like this:
1514 /* Print into a string */
1515 String *s = NewString("");
1516 Printf(s,"Hello\n");
1517 for (i = 0; i < 10; i++) {
1518 Printf(s,"%d\n", i);
1521 /* Print string into a file */
1522 Printf(f, "%s\n", s);
1527 Similarly, the preprocessor and parser all operate on string-files.
1532 <H2><a name="Extending_nn21"></a>35.6 Navigating and manipulating parse trees</H2>
1535 Parse trees are built as collections of hash tables. Each node is a hash table in which
1536 arbitrary attributes can be stored. Certain attributes in the hash table provide links to
1537 other parse tree nodes. The following macros can be used to move around the parse tree.
1540 <b><tt>String *nodeType(Node *n)</tt></b>
1543 <div class="indent">
1544 Returns the node type tag as a string. The returned string indicates the type of parse
1549 <b><tt>Node *nextSibling(Node *n)</tt></b>
1552 <div class="indent">
1553 Returns the next node in the parse tree. For example, the next C declaration.
1557 <b><tt>Node *previousSibling(Node *n)</tt></b>
1560 <div class="indent">
1561 Returns the previous node in the parse tree. For example, the previous C declaration.
1565 <b><tt>Node *firstChild(Node *n)</tt></b>
1568 <div class="indent">
1569 Returns the first child node. For example, if <tt>n</tt> was a C++ class node, this would
1570 return the node for the first class member.
1574 <b><tt>Node *lastChild(Node *n)</tt></b>
1577 <div class="indent">
1578 Returns the last child node. You might use this if you wanted to append a new
1579 node to the of a class.
1583 <b><tt>Node *parentNode(Node *n)</tt></b>
1586 <div class="indent">
1587 Returns the parent of node <tt>n</tt>. Use this to move up the pass tree.
1591 The following macros can be used to change all of the above attributes.
1592 Normally, these functions are only used by the parser. Changing them without
1593 knowing what you are doing is likely to be dangerous.
1597 <b><tt>void set_nodeType(Node *n, const String_or_char)</tt></b>
1600 <div class="indent">
1601 Change the node type.
1606 <b><tt>void set_nextSibling(Node *n, Node *s)</tt></b>
1609 <div class="indent">
1610 Set the next sibling.
1614 <b><tt>void set_previousSibling(Node *n, Node *s)</tt></b>
1617 <div class="indent">
1618 Set the previous sibling.
1622 <b><tt>void set_firstChild(Node *n, Node *c)</tt></b>
1625 <div class="indent">
1626 Set the first child node.
1630 <b><tt>void set_lastChild(Node *n, Node *c)</tt></b>
1633 <div class="indent">
1634 Set the last child node.
1638 <b><tt>void set_parentNode(Node *n, Node *p)</tt></b>
1641 <div class="indent">
1642 Set the parent node.
1646 The following utility functions are used to alter the parse tree (at your own risk)
1650 <b><tt>void appendChild(Node *parent, Node *child)</tt></b>
1653 <div class="indent">
1654 Append a child to <tt>parent</tt>. The appended node becomes the last child.
1658 <b><tt>void deleteNode(Node *node)</tt></b>
1661 <div class="indent">
1662 Deletes a node from the parse tree. Deletion reconnects siblings and properly updates
1663 the parent so that sibling nodes are unaffected.
1666 <H2><a name="Extending_nn22"></a>35.7 Working with attributes</H2>
1670 Since parse tree nodes are just hash tables, attributes are accessed using the <tt>Getattr()</tt>,
1671 <tt>Setattr()</tt>, and <tt>Delattr()</tt> operations. For example:
1676 int functionHandler(Node *n) {
1677 String *name = Getattr(n,"name");
1678 String *symname = Getattr(n,"sym:name");
1679 SwigType *type = Getattr(n,"type");
1686 New attributes can be freely attached to a node as needed. However, when new attributes
1687 are attached during code generation, they should be prepended with a namespace prefix.
1694 Setattr(n,"python:docstring", doc); /* Store docstring */
1700 A quick way to check the value of an attribute is to use the <tt>checkAttribute()</tt> function like this:
1705 if (checkAttribute(n,"storage","virtual")) {
1713 Changing the values of existing attributes is allowed and is sometimes done to implement
1714 node transformations. However, if a function/method modifies a node, it is required to restore
1715 modified attributes to their original values. To simplify the task of saving/restoring attributes,
1716 the following functions are used:
1720 <b><tt>int Swig_save(const char *ns, Node *n, const char *name1, const char *name2, ..., NIL)</tt></b>
1723 <div class="indent">
1724 Saves a copy of attributes <tt>name1</tt>, <tt>name2</tt>, etc. from node <tt>n</tt>.
1725 Copies of the attributes are actually resaved in the node in a different namespace which is
1726 set by the <tt>ns</tt> argument. For example, if you call <tt>Swig_save("foo",n,"type",NIL)</tt>,
1727 then the "type" attribute will be copied and saved as "foo:type". The namespace name itself is stored in
1728 the "view" attribute of the node. If necessary, this can be examined to find out where previous
1729 values of attributes might have been saved.
1733 <b><tt>int Swig_restore(Node *n)</tt></b>
1736 <div class="indent">
1739 Restores the attributes saved by the previous call to <tt>Swig_save()</tt>. Those
1740 attributes that were supplied to <tt>Swig_save()</tt> will be restored to their
1745 The <tt>Swig_save()</tt> and <tt>Swig_restore()</tt> functions must always be used as a pair.
1746 That is, every call to <tt>Swig_save()</tt> must have a matching call to <tt>Swig_restore()</tt>.
1747 Calls can be nested if necessary. Here is an example that shows how the functions might be used:
1752 int variableHandler(Node *n) {
1753 Swig_save("variableHandler",n,"type","sym:name",NIL);
1754 String *symname = Getattr(n,"sym:name");
1755 SwigType *type = Getattr(n,"type");
1757 Append(symname,"_global"); // Change symbol name
1758 SwigType_add_pointer(type); // Add pointer
1762 Swig_restore(n); // Restore original values
1771 <b><tt>int Swig_require(const char *ns, Node *n, const char *name1, const char *name2, ..., NIL)</tt></b>
1774 <div class="indent">
1775 This is an enhanced version of <tt>Swig_save()</tt> that adds error checking. If an attribute
1776 name is not present in <tt>n</tt>, a failed assertion results and SWIG terminates with a fatal
1777 error. Optionally, if an attribute name is specified as "*<em>name</em>", a copy of the
1778 attribute is saved as with <tt>Swig_save()</tt>. If an attribute is specified as "?<em>name</em>",
1779 the attribute is optional. <tt>Swig_restore()</tt> must always be called after using this
1783 <H2><a name="Extending_nn23"></a>35.8 Type system</H2>
1787 SWIG implements the complete C++ type system including typedef, inheritance,
1788 pointers, references, and pointers to members. A detailed discussion of
1789 type theory is impossible here. However, let's cover the highlights.
1792 <H3><a name="Extending_nn24"></a>35.8.1 String encoding of types</H3>
1796 All types in SWIG consist of a base datatype and a collection of type
1797 operators that are applied to the base. A base datatype is almost
1798 always some kind of primitive type such as <tt>int</tt> or <tt>double</tt>.
1799 The operators consist of things like pointers, references, arrays, and so forth.
1800 Internally, types are represented as strings that are constructed in a very
1801 precise manner. Here are some examples:
1804 <div class="diagram">
1806 C datatype SWIG encoding (strings)
1807 ----------------------------- --------------------------
1810 const int * "p.q(const).int"
1811 int (*x)(int,double) "p.f(int,double).int"
1812 int [20][30] "a(20).a(30).int"
1813 int (F::*)(int) "m(F).f(int).int"
1814 vector<int> * "p.vector<(int)>"
1819 Reading the SWIG encoding is often easier than figuring out the C code---just
1820 read it from left to right. For a type of "p.f(int,double).int" is
1821 a "pointer to a function(int,double) that returns int".
1825 The following operator encodings are used in type strings:
1828 <div class="diagram">
1831 ------------------- -------------------------------
1833 a(n). Array of dimension n
1835 m(class). Member pointer to class
1837 q(qlist). Qualifiers
1842 In addition, type names may be parameterized by templates. This is
1843 represented by enclosing the template parameters in <tt><(
1844 ... )></tt>. Variable length arguments are represented by the
1845 special base type of <tt>v(...)</tt>.
1849 If you want to experiment with type encodings, the raw type strings can
1850 be inserted into an interface file using backticks `` wherever a type
1851 is expected. For instance, here is
1852 an extremely perverted example:
1855 <div class="diagram">
1857 `p.a(10).p.f(int,p.f(int).int)` foo(int, int (*x)(int));
1862 This corresponds to the immediately obvious C declaration:
1865 <div class="diagram">
1867 (*(*foo(int,int (*)(int)))[10])(int,int (*)(int));
1872 Aside from the potential use of this declaration on a C programming quiz,
1873 it motivates the use of the special SWIG encoding of types. The SWIG
1874 encoding is much easier to work with because types can be easily examined,
1875 modified, and constructed using simple string operations (comparison,
1876 substrings, concatenation, etc.). For example, in the parser, a declaration
1887 is processed in a few pieces. In this case, you have the base type
1888 "<tt>int</tt>" and the declarator of type "<tt>a(30).p.</tt>". To
1889 make the final type, the two parts are just joined together using
1890 string concatenation.
1893 <H3><a name="Extending_nn25"></a>35.8.2 Type construction</H3>
1897 The following functions are used to construct types. You should use
1898 these functions instead of trying to build the type strings yourself.
1902 <b><tt>void SwigType_add_pointer(SwigType *ty)</tt></b>
1905 <div class="indent">
1906 Adds a pointer to <tt>ty</tt>.
1910 <b><tt>void SwigType_del_pointer(SwigType *ty)</tt></b>
1913 <div class="indent">
1914 Removes a single pointer from <tt>ty</tt>.
1918 <b><tt>void SwigType_add_reference(SwigType *ty)</tt></b>
1921 <div class="indent">
1922 Adds a reference to <tt>ty</tt>.
1926 <b><tt>void SwigType_add_array(SwigType *ty, const String_or_char *size)</tt></b>
1929 <div class="indent">
1930 Adds an array with dimension <tt>dim</tt> to <tt>ty</tt>.
1934 <b><tt>void SwigType_del_array(SwigType *ty)</tt></b>
1937 <div class="indent">
1938 Removes a single array dimension from <tt>ty</tt>.
1942 <b><tt>int SwigType_array_ndim(SwigType *ty)</tt></b>
1945 <div class="indent">
1946 Returns number of array dimensions of <tt>ty</tt>.
1950 <b><tt>String* SwigType_array_getdim(SwigType *ty,int n)</tt></b>
1953 <div class="indent">
1954 Returns <tt>n</tt>th array dimension of <tt>ty</tt>.
1958 <b><tt>void SwigType_array_setdim(SwigType *ty, int n, const String_or_char *rep)</tt></b>
1961 <div class="indent">
1962 Sets <tt>n</tt>th array dimensions of <tt>ty</tt> to <tt>rep</tt>.
1966 <b><tt>void SwigType_add_qualifier(SwigType *ty, const String_or_char *q)</tt></b>
1969 <div class="indent">
1970 Adds a type qualifier <tt>q</tt> to <tt>ty</tt>. <tt>q</tt> is typically
1971 <tt>"const"</tt> or <tt>"volatile"</tt>.
1975 <b><tt>void SwigType_add_memberpointer(SwigType *ty, const String_or_char *cls)</tt></b>
1978 <div class="indent">
1979 Adds a pointer to a member of class <tt>cls</tt> to <tt>ty</tt>.
1983 <b><tt>void SwigType_add_function(SwigType *ty, ParmList *p)</tt></b>
1986 <div class="indent">
1987 Adds a function to <tt>ty</tt>. <tt>p</tt> is a linked-list of parameter
1988 nodes as generated by the parser. See the section on parameter lists
1989 for details about the representation.
1993 <b><tt>void SwigType_add_template(SwigType *ty, ParmList *p)</tt></b>
1996 <div class="indent">
1997 Adds a template to <tt>ty</tt>. <tt>p</tt> is a linked-list of parameter
1998 nodes as generated by the parser. See the section on parameter lists
1999 for details about the representation.
2003 <b><tt>SwigType *SwigType_pop(SwigType *ty)</tt></b>
2006 <div class="indent">
2007 Removes the last type constructor from <tt>ty</tt> and returns it.
2008 <tt>ty</tt> is modified.
2012 <b><tt>void SwigType_push(SwigType *ty, SwigType *op)</tt></b>
2015 <div class="indent">
2016 Pushes the type operators in <tt>op</tt> onto type <tt>ty</tt>. The
2017 opposite of <tt>SwigType_pop()</tt>.
2021 <b><tt>SwigType *SwigType_pop_arrays(SwigType *ty)</tt></b>
2024 <div class="indent">
2025 Removes all leading array operators from <tt>ty</tt> and returns them.
2026 <tt>ty</tt> is modified. For example, if <tt>ty</tt> is <tt>"a(20).a(10).p.int"</tt>,
2027 then this function would return <tt>"a(20).a(10)."</tt> and modify <tt>ty</tt>
2028 so that it has the value <tt>"p.int"</tt>.
2032 <b><tt>SwigType *SwigType_pop_function(SwigType *ty)</tt></b>
2035 <div class="indent">
2036 Removes a function operator from <tt>ty</tt> including any qualification.
2037 <tt>ty</tt> is modified. For example, if <tt>ty</tt> is <tt>"f(int).int"</tt>,
2038 then this function would return <tt>"f(int)."</tt> and modify <tt>ty</tt>
2039 so that it has the value <tt>"int"</tt>.
2043 <b><tt>SwigType *SwigType_base(SwigType *ty)</tt></b>
2046 <div class="indent">
2047 Returns the base type of a type. For example, if <tt>ty</tt> is
2048 <tt>"p.a(20).int"</tt>, this function would return <tt>"int"</tt>.
2049 <tt>ty</tt> is unmodified.
2053 <b><tt>SwigType *SwigType_prefix(SwigType *ty)</tt></b>
2056 <div class="indent">
2057 Returns the prefix of a type. For example, if <tt>ty</tt> is
2058 <tt>"p.a(20).int"</tt>, this function would return <tt>"p.a(20)."</tt>.
2059 <tt>ty</tt> is unmodified.
2062 <H3><a name="Extending_nn26"></a>35.8.3 Type tests</H3>
2066 The following functions can be used to test properties of a datatype.
2070 <b><tt>int SwigType_ispointer(SwigType *ty)</tt></b>
2073 <div class="indent">
2074 Checks if <tt>ty</tt> is a standard pointer.
2078 <b><tt>int SwigType_ismemberpointer(SwigType *ty)</tt></b>
2081 <div class="indent">
2082 Checks if <tt>ty</tt> is a member pointer.
2086 <b><tt>int SwigType_isreference(SwigType *ty)</tt></b>
2089 <div class="indent">
2090 Checks if <tt>ty</tt> is a C++ reference.
2094 <b><tt>int SwigType_isarray(SwigType *ty)</tt></b>
2097 <div class="indent">
2098 Checks if <tt>ty</tt> is an array.
2102 <b><tt>int SwigType_isfunction(SwigType *ty)</tt></b>
2105 <div class="indent">
2106 Checks if <tt>ty</tt> is a function.
2110 <b><tt>int SwigType_isqualifier(SwigType *ty)</tt></b>
2113 <div class="indent">
2114 Checks if <tt>ty</tt> is a qualifier.
2118 <b><tt>int SwigType_issimple(SwigType *ty)</tt></b>
2121 <div class="indent">
2122 Checks if <tt>ty</tt> is a simple type. No operators applied.
2126 <b><tt>int SwigType_isconst(SwigType *ty)</tt></b>
2129 <div class="indent">
2130 Checks if <tt>ty</tt> is a const type.
2134 <b><tt>int SwigType_isvarargs(SwigType *ty)</tt></b>
2137 <div class="indent">
2138 Checks if <tt>ty</tt> is a varargs type.
2142 <b><tt>int SwigType_istemplate(SwigType *ty)</tt></b>
2145 <div class="indent">
2146 Checks if <tt>ty</tt> is a templatized type.
2149 <H3><a name="Extending_nn27"></a>35.8.4 Typedef and inheritance</H3>
2153 The behavior of <tt>typedef</tt> declaration is to introduce a type alias.
2154 For instance, <tt>typedef int Integer</tt> makes the identifier
2155 <tt>Integer</tt> an alias for <tt>int</tt>. The treatment of typedef in
2156 SWIG is somewhat complicated due to the pattern matching rules that get applied
2157 in typemaps and the fact that SWIG prefers to generate wrapper code
2158 that closely matches the input to simplify debugging (a user will see the
2159 typedef names used in their program instead of the low-level primitive C
2164 To handle <tt>typedef</tt>, SWIG builds a collection of trees containing typedef relations. For example,
2169 typedef int Integer;
2170 typedef Integer *IntegerPtr;
2177 produces two trees like this:
2180 <div class="diagram">
2186 Integer Size Number IntegerPtr
2191 To resolve a single typedef relationship, the following function is used:
2195 <b><tt>SwigType *SwigType_typedef_resolve(SwigType *ty)</tt></b>
2198 <div class="indent">
2199 Checks if <tt>ty</tt> can be reduced to a new type via typedef. If so,
2200 returns the new type. If not, returns NULL.
2204 Typedefs are only resolved in simple typenames that appear in a type.
2205 For example, the type base name and in function parameters. When
2206 resolving types, the process starts in the leaf nodes and moves up
2207 the tree towards the root. Here are a few examples that show how it works:
2210 <div class="diagram">
2212 Original type After typedef_resolve()
2213 ------------------------ -----------------------
2216 p.IntegerPtr p.p.Integer
2222 For complicated types, the process can be quite involved. Here is the
2223 reduction of a function pointer:
2226 <div class="diagram">
2228 p.f(Integer, p.IntegerPtr, Size).Integer : Start
2229 p.f(Integer, p.IntegerPtr, Size).int
2230 p.f(int, p.IntegerPtr, Size).int
2231 p.f(int, p.p.Integer, Size).int
2232 p.f(int, p.p.int, Size).int
2233 p.f(int, p.p.int, int).int : End
2238 Two types are equivalent if their full type reductions are the same.
2239 The following function will fully reduce a datatype:
2243 <b><tt>SwigType *SwigType_typedef_resolve_all(SwigType *ty)</tt></b>
2246 <div class="indent">
2247 Fully reduces <tt>ty</tt> according to typedef rules. Resulting datatype
2248 will consist only of primitive typenames.
2251 <H3><a name="Extending_nn28"></a>35.8.5 Lvalues</H3>
2255 When generating wrapper code, it is necessary to emit datatypes that can
2256 be used on the left-hand side of an assignment operator (an lvalue). However,
2257 not all C datatypes can be used in this way---especially arrays and
2258 const-qualified types. To generate a type that can be used as an lvalue,
2259 use the following function:
2263 <b><tt>SwigType *SwigType_ltype(SwigType *ty)</tt></b>
2266 <div class="indent">
2267 Converts type <tt>ty</tt> to a type that can be used as an lvalue in
2268 assignment. The resulting type is stripped of qualifiers and arrays are
2269 converted to a pointers.
2273 The creation of lvalues is fully aware of typedef and other aspects
2274 of the type system. Therefore, the creation of an lvalue may result in
2275 unexpected results. Here are a few examples:
2280 typedef double Matrix4[4][4];
2281 Matrix4 x; // type = 'Matrix4', ltype='p.a(4).double'
2283 typedef const char * Literal;
2284 Literal y; // type = 'Literal', ltype='p.char'
2288 <H3><a name="Extending_nn29"></a>35.8.6 Output functions</H3>
2292 The following functions produce strings that are suitable for output.
2296 <b><tt>String *SwigType_str(SwigType *ty, const String_or_char *id = 0)</tt></b>
2299 <div class="indent">
2300 Generates a C string for a datatype. <tt>id</tt> is an optional declarator.
2301 For example, if <tt>ty</tt> is "p.f(int).int" and <tt>id</tt> is "foo", then
2302 this function produces "<tt>int (*foo)(int)</tt>". This function is
2303 used to convert string-encoded types back into a form that is valid C syntax.
2307 <b><tt>String *SwigType_lstr(SwigType *ty, const String_or_char *id = 0)</tt></b>
2310 <div class="indent">
2311 This is the same as <tt>SwigType_str()</tt> except that the result
2312 is generated from the type's lvalue (as generated from SwigType_ltype).
2316 <b><tt>String *SwigType_lcaststr(SwigType *ty, const String_or_char *id = 0)</tt></b>
2319 <div class="indent">
2320 Generates a casting operation that converts from type <tt>ty</tt> to its
2321 lvalue. <tt>id</tt> is an optional name to include in the cast. For example,
2322 if <tt>ty</tt> is "<tt>q(const).p.char</tt>" and <tt>id</tt> is "<tt>foo</tt>",
2323 this function produces the string "<tt>(char *) foo</tt>".
2327 <b><tt>String *SwigType_rcaststr(SwigType *ty, const String_or_char *id = 0)</tt></b>
2330 <div class="indent">
2331 Generates a casting operation that converts from a type's lvalue to a
2332 type equivalent to <tt>ty</tt>. <tt>id</tt> is an optional name to
2333 include in the cast. For example, if <tt>ty</tt> is
2334 "<tt>q(const).p.char</tt>" and <tt>id</tt> is "<tt>foo</tt>", this
2335 function produces the string "<tt>(const char *) foo</tt>".
2339 <b><tt>String *SwigType_manglestr(SwigType *ty)</tt></b>
2342 <div class="indent">
2343 Generates a mangled string encoding of type <tt>ty</tt>. The
2344 mangled string only contains characters that are part of a valid
2345 C identifier. The resulting string is used in various parts of
2346 SWIG, but is most commonly associated with type-descriptor objects
2347 that appear in wrappers (e.g., <tt>SWIGTYPE_p_double</tt>).
2350 <H2><a name="Extending_nn30"></a>35.9 Parameters</H2>
2354 Several type-related functions involve parameter lists. These include
2355 functions and templates. Parameter list are represented as a list of
2356 nodes with the following attributes:
2359 <div class="diagram">
2361 "type" - Parameter type (required)
2362 "name" - Parameter name (optional)
2363 "value" - Initializer (optional)
2368 Typically parameters are denoted in the source by using a typename of
2369 <tt>Parm *</tt> or <tt>ParmList *</tt>. To walk a parameter list, simply use
2373 <div class="diagram">
2377 for (p = parms; p; p = nextSibling(p)) {
2378 SwigType *type = Getattr(p,"type");
2379 String *name = Getattr(p,"name");
2380 String *value = Getattr(p,"value");
2387 Note: this code is exactly the same as what you would use to walk parse tree nodes.
2391 An empty list of parameters is denoted by a NULL pointer.
2395 Since parameter lists are fairly common, the following utility functions are provided
2400 <b><tt>Parm *CopyParm(Parm *p);</tt></b>
2403 <div class="indent">
2404 Copies a single parameter.
2408 <b><tt>ParmList *CopyParmList(ParmList *p);</tt></b>
2411 <div class="indent">
2412 Copies an entire list of parameters.
2416 <b><tt>int ParmList_len(ParmList *p);</tt></b>
2419 <div class="indent">
2420 Returns the number of parameters in a parameter list.
2424 <b><tt>String *ParmList_str(ParmList *p);</tt></b>
2427 <div class="indent">
2428 Converts a parameter list into a C string. For example,
2429 produces a string like "<tt>(int *p, int n, double x);</tt>".
2433 <b><tt>String *ParmList_protostr(ParmList *p);</tt></b>
2436 <div class="indent">
2437 The same as <tt>ParmList_str()</tt> except that parameter names are not
2438 included. Used to emit prototypes.
2442 <b><tt>int ParmList_numrequired(ParmList *p);</tt></b>
2445 <div class="indent">
2446 Returns the number of required (non-optional) arguments in <tt>p</tt>.
2449 <H2><a name="Extending_nn31"></a>35.10 Writing a Language Module</H2>
2453 One of the easiest routes to supporting a new language module is to copy an already
2454 supported language module implementation and modify it.
2455 Be sure to choose a language that is similar in nature to the new language.
2456 All language modules follow a similar structure and
2457 this section briefly outlines the steps needed to create a bare-bones
2458 language module from scratch.
2459 Since the code is relatively easy to read, this section
2460 describes the creation of a minimal Python module. You should be able to extrapolate
2461 this to other languages.
2464 <H3><a name="Extending_nn32"></a>35.10.1 Execution model</H3>
2468 Code generation modules are defined by inheriting from the <tt>Language</tt> class,
2469 currently defined in the <tt>Source/Modules</tt> directory of SWIG. Starting from
2470 the parsing of command line options, all aspects of code generation are controlled by
2471 different methods of the <tt>Language</tt> that must be defined by your module.
2474 <H3><a name="Extending_nn33"></a>35.10.2 Starting out</H3>
2478 To define a new language module, first create a minimal implementation using
2479 this example as a guide:
2484 #include "swigmod.h"
2486 class PYTHON : public Language {
2489 virtual void main(int argc, char *argv[]) {
2490 printf("I'm the Python module.\n");
2493 virtual int top(Node *n) {
2494 printf("Generating code.\n");
2500 extern "C" Language *
2502 return new PYTHON();
2508 The "swigmod.h" header file contains, among other things, the declaration
2509 of the <tt>Language</tt> base class and so you should include it at the top
2510 of your language module's source file. Similarly, the "swigconfig.h" header
2511 file contains some other useful definitions that you may need. Note that you
2512 should <em>not</em> include any header files that are installed with the
2513 target language. That is to say, the implementation of the SWIG Python module
2514 shouldn't have any dependencies on the Python header files. The wrapper code
2515 generated by SWIG will almost always depend on some language-specific C/C++
2516 header files, but SWIG itself does not.
2520 Give your language class a reasonable name, usually the same as the target language.
2521 By convention, these class names are all uppercase (e.g. "PYTHON" for the Python
2522 language module) but this is not a requirement. This class will ultimately consist
2523 of a number of overrides of the virtual functions declared in the <tt>Language</tt>
2524 base class, in addition to any language-specific member functions and data you
2525 need. For now, just use the dummy implementations shown above.
2529 The language module ends with a factory function, <tt>swig_python()</tt>, that simply
2530 returns a new instance of the language class. As shown, it should be declared with the
2531 <tt>extern "C"</tt> storage qualifier so that it can be called from C code. It should
2532 also return a pointer to the base class (<tt>Language</tt>) so that only the interface
2533 (and not the implementation) of your language module is exposed to the rest of SWIG.
2537 Save the code for your language module in a file named "<tt>python.cxx</tt>" and.
2538 place this file in the <tt>Source/Modules</tt> directory of the SWIG distribution.
2539 To ensure that your module is compiled into SWIG along with the other language modules,
2540 modify the file <tt>Source/Modules/Makefile.am</tt> to include the additional source
2541 files. In addition, modify the file <tt>Source/Modules/swigmain.cxx</tt>
2542 with an additional command line option that activates the module. Read the source---it's straightforward.
2546 Next, at the top level of the SWIG distribution, re-run the <tt>autogen.sh</tt> script
2547 to regenerate the various build files:
2552 $ <b>./autogen.sh</b>
2557 Next re-run <tt>configure</tt> to regenerate all of the Makefiles:
2562 $ <b>./configure</b>
2567 Finally, rebuild SWIG with your module added:
2577 Once it finishes compiling, try running SWIG with the command-line option
2578 that activates your module. For example, <tt>swig -python foo.i</tt>. The
2579 messages from your new module should appear.
2582 <H3><a name="Extending_nn34"></a>35.10.3 Command line options</H3>
2586 When SWIG starts, the command line options are passed to your language module. This occurs
2587 before any other processing occurs (preprocessing, parsing, etc.). To capture the
2588 command line options, simply use code similar to this:
2593 void Language::main(int argc, char *argv[]) {
2594 for (int i = 1; i < argc; i++) {
2596 if(strcmp(argv[i],"-interface") == 0) {
2598 interface = NewString(argv[i+1]);
2605 } else if (strcmp(argv[i],"-globals") == 0) {
2607 global_name = NewString(argv[i+1]);
2614 } else if ( (strcmp(argv[i],"-proxy") == 0)) {
2617 } else if (strcmp(argv[i],"-keyword") == 0) {
2620 } else if (strcmp(argv[i],"-help") == 0) {
2621 fputs(usage,stderr);
2631 The exact set of options depends on what you want to do in your module. Generally,
2632 you would use the options to change code generation modes or to print diagnostic information.
2636 If a module recognizes an option, it should always call <tt>Swig_mark_arg()</tt>
2637 to mark the option as valid. If you forget to do this, SWIG will terminate with an
2638 unrecognized command line option error.
2641 <H3><a name="Extending_nn35"></a>35.10.4 Configuration and preprocessing</H3>
2645 In addition to looking at command line options, the <tt>main()</tt> method is responsible
2646 for some initial configuration of the SWIG library and preprocessor. To do this,
2647 insert some code like this:
2652 void main(int argc, char *argv[]) {
2653 ... command line options ...
2655 /* Set language-specific subdirectory in SWIG library */
2656 SWIG_library_directory("python");
2658 /* Set language-specific preprocessing symbol */
2659 Preprocessor_define("SWIGPYTHON 1", 0);
2661 /* Set language-specific configuration file */
2662 SWIG_config_file("python.swg");
2664 /* Set typemap language (historical) */
2665 SWIG_typemap_lang("python");
2671 The above code does several things--it registers the name of the
2672 language module with the core, it supplies some preprocessor macro definitions
2673 for use in input files (so that they can determine the target language), and
2674 it registers a start-up file. In this case, the file <tt>python.swg</tt> will
2675 be parsed before any part of the user-supplied input file.
2679 Before proceeding any further, create a directory for your module in the SWIG
2680 library (The <tt>Lib</tt> directory). Now, create a configuration file in the
2681 directory. For example, <tt>python.swg</tt>.
2685 Just to review, your language module should now consist of two files--
2686 an implementation file <tt>python.cxx</tt> and a configuration file
2687 <tt>python.swg</tt>.
2690 <H3><a name="Extending_nn36"></a>35.10.5 Entry point to code generation</H3>
2694 SWIG is a multi-pass compiler. Once the <tt>main()</tt> method has
2695 been invoked, the language module does not execute again until
2696 preprocessing, parsing, and a variety of semantic analysis passes have
2697 been performed. When the core is ready to start generating wrappers,
2698 it invokes the <tt>top()</tt> method of your language class. The
2699 argument to <tt>top</tt> is a single parse tree node that corresponds to
2700 the top of the entire parse tree.
2704 To get the code generation process started, the <tt>top()</tt> procedure needs
2705 to do several things:
2709 <li>Initialize the wrapper code output.
2710 <li>Set the module name.
2711 <li>Emit common initialization code.
2712 <li>Emit code for all of the child nodes.
2713 <li>Finalize the wrapper module and cleanup.
2717 An outline of <tt>top()</tt> might be as follows:
2722 int Python::top(Node *n) {
2724 /* Get the module name */
2725 String *module = Getattr(n,"name");
2727 /* Get the output file name */
2728 String *outfile = Getattr(n,"outfile");
2730 /* Initialize I/O (see next section) */
2733 /* Output module initialization code */
2736 /* Emit code for children */
2748 <H3><a name="Extending_nn37"></a>35.10.6 Module I/O and wrapper skeleton</H3>
2751 <!-- please report bugs in this section to mgossage -->
2755 Within SWIG wrappers, there are four main sections. These are (in order)
2759 <li>runtime: This section has most of the common SWIG runtime code
2760 <li>header: This section holds declarations and inclusions from the .i file
2761 <li>wrapper: This section holds all the wrappering code
2762 <li>init: This section holds the module initalisation function
2763 (the entry point for the interpreter)
2766 Different parts of the SWIG code will fill different sections,
2767 then upon completion of the wrappering all the sections will be saved
2768 to the wrapper file.
2771 To perform this will require several additions to the code in various places,
2777 class PYTHON : public Language {
2779 /* General DOH objects used for holding the strings */
2791 int Python::top(Node *n) {
2795 /* Initialize I/O */
2796 f_begin = NewFile(outfile, "w", SWIG_output_files());
2798 FileErrorDisplay(outfile);
2799 SWIG_exit(EXIT_FAILURE);
2801 f_runtime = NewString("");
2802 f_init = NewString("");
2803 f_header = NewString("");
2804 f_wrappers = NewString("");
2806 /* Register file targets with the SWIG file handler */
2807 Swig_register_filebyname("begin", f_begin);
2808 Swig_register_filebyname("header", f_header);
2809 Swig_register_filebyname("wrapper", f_wrappers);
2810 Swig_register_filebyname("runtime", f_runtime);
2811 Swig_register_filebyname("init", f_init);
2813 /* Output module initialization code */
2814 Swig_banner(f_begin);
2817 /* Emit code for children */
2821 /* Write all to the file */
2822 Dump(f_runtime, f_begin);
2823 Dump(f_header, f_begin);
2824 Dump(f_wrappers, f_begin);
2825 Wrapper_pretty_print(f_init, f_begin);
2841 Using this to process a file will generate a wrapper file, however the
2842 wrapper will only consist of the common SWIG code as well as any inline
2843 code which was written in the .i file. It does not contain any wrappers for
2844 any of the functions or classes.
2848 The code to generate the wrappers are the various member functions, which
2849 currently have not been touched. We will look at <tt>functionWrapper()</tt> as this
2850 is the most commonly used function. In fact many of the other wrapper routines
2851 will call this to do their work.
2854 A simple modification to write some basic details to the wrapper looks like this:
2859 int Python::functionWrapper(Node *n) {
2860 /* Get some useful attributes of this function */
2861 String *name = Getattr(n,"sym:name");
2862 SwigType *type = Getattr(n,"type");
2863 ParmList *parms = Getattr(n,"parms");
2864 String *parmstr= ParmList_str_defaultargs(parms); // to string
2865 String *func = SwigType_str(type, NewStringf("%s(%s)", name, parmstr));
2866 String *action = Getattr(n,"wrap:action");
2868 Printf(f_wrappers,"functionWrapper : %s\n", func);
2869 Printf(f_wrappers," action : %s\n", action);
2876 This will now produce some useful information within your wrapper file.
2881 functionWrapper : void delete_Shape(Shape *self)
2882 action : delete arg1;
2884 functionWrapper : void Shape_x_set(Shape *self,double x)
2885 action : if (arg1) (arg1)->x = arg2;
2887 functionWrapper : double Shape_x_get(Shape *self)
2888 action : result = (double) ((arg1)->x);
2890 functionWrapper : void Shape_y_set(Shape *self,double y)
2891 action : if (arg1) (arg1)->y = arg2;
2896 <H3><a name="Extending_nn38"></a>35.10.7 Low-level code generators</H3>
2899 <!-- please report bugs in this section to mgossage -->
2902 As ingenious as SWIG is, and despite all its capabilities and the power of
2903 its parser, the Low-level code generation takes a lot of work to write
2904 properly. Mainly because every language insists on its own manner of
2905 interfacing to C/C++. To write the code generators you will need a good
2906 understanding of how to manually write an interface to your chosen
2907 language, so make sure you have your documentation handy.
2910 At this point it is also probably a good idea to take a very simple file
2911 (just one function), and try letting SWIG generate wrappers for many
2912 different languages. Take a look at all of the wrappers generated, and decide
2913 which one looks closest to the language you are trying to wrap.
2914 This may help you to decide which code to look at.
2917 In general most language wrappers look a little like this:
2921 /* wrapper for TYPE3 some_function(TYPE1,TYPE2); */
2922 RETURN_TYPE _wrap_some_function(ARGS){
2927 if(ARG1 is not of TYPE1) goto fail;
2928 arg1=(convert ARG1);
2929 if(ARG2 is not of TYPE2) goto fail;
2930 arg2=(convert ARG2);
2932 result=some_function(arg1,arg2);
2934 convert 'result' to whatever the language wants;
2948 Yes, it is rather vague and not very clear. But each language works differently
2949 so this will have to do for now.
2952 Tackling this problem will be done in two stages:
2955 <li>The skeleton: the function wrapper, and call, but without the conversion
2956 <li>The conversion: converting the arguments to-from what the language wants
2959 The first step will be done in the code, the second will be done in typemaps.
2962 Our first step will be to write the code for <tt>functionWrapper()</tt>. What is
2963 shown below is <b>NOT</b> the solution, merely a step in the right direction.
2964 There are a lot of issues to address.
2967 <li>Variable length and default parameters
2968 <li>Typechecking and number of argument checks
2969 <li>Overloaded functions
2970 <li>Inout and Output only arguments
2974 virtual int functionWrapper(Node *n) {
2975 /* get useful atributes */
2976 String *name = Getattr(n,"sym:name");
2977 SwigType *type = Getattr(n,"type");
2978 ParmList *parms = Getattr(n,"parms");
2981 /* create the wrapper object */
2982 Wrapper *wrapper = NewWrapper();
2984 /* create the functions wrappered name */
2985 String *wname = Swig_name_wrapper(iname);
2987 /* deal with overloading */
2990 /* write the wrapper function definition */
2991 Printv(wrapper->def,"RETURN_TYPE ", wname, "(ARGS) {",NIL);
2993 /* if any additional local variable needed, add them now */
2996 /* write the list of locals/arguments required */
2997 emit_args(type, parms, wrapper);
2999 /* check arguments */
3002 /* write typemaps(in) */
3005 /* write constriants */
3008 /* Emit the function call */
3009 emit_action(n,wrapper);
3011 /* return value if necessary */
3014 /* write typemaps(out) */
3017 /* add cleanup code */
3020 /* Close the function(ok) */
3021 Printv(wrapper->code, "return ALL_OK;\n", NIL);
3023 /* add the failure cleanup code */
3026 /* Close the function(error) */
3027 Printv(wrapper->code, "return ERROR;\n", "}\n", NIL);
3029 /* final substititions if applicable */
3032 /* Dump the function out */
3033 Wrapper_print(wrapper,f_wrappers);
3037 DelWrapper(wrapper);
3045 Executing this code will produce wrappers which have our basic skeleton
3046 but without the typemaps, there is still work to do.
3050 <H3><a name="Extending_nn39"></a>35.10.8 Configuration files</H3>
3053 <!-- please report bugs in this section to ttn -->
3056 At the time of this writing, SWIG supports nearly a dozen languages,
3057 which means that for continued sanity in maintaining the configuration
3058 files, the language modules need to follow some conventions. These are
3059 outlined here along with the admission that, yes it is ok to violate
3060 these conventions in minor ways, as long as you know where to apply the
3061 proper kludge to keep the overall system regular and running.
3062 Engineering is the art of compromise, see...
3066 Much of the maintenance regularity depends on choosing a suitable
3067 nickname for your language module (and then using it in a controlled
3068 way). Nicknames should be all lower case letters with an optional
3069 numeric suffix (no underscores, no dashes, no spaces). Some examples
3070 are: <TT>foo</TT>, <TT>bar</TT>, <TT>qux99</TT>.
3074 The numeric suffix variant, as in the last example, is somewhat tricky
3075 to work with because sometimes people expect to refer to the language
3076 without this number but sometimes that number is extremely relevant
3077 (especially when it corresponds to language implementation versions with
3078 incompatible interfaces). New language modules that unavoidably require
3079 a numeric suffix in their nickname should include that number in all
3080 uses, or be prepared to kludge.
3084 The nickname is used in four places:
3087 <TABLE summary="nickname table">
3088 <TR><TD><B>usage</B></TD><TD><B>transform</B></TD></TR>
3089 <TR><TD>"skip" tag</TD><TD>(none)</TD></TR>
3090 <TR><TD>Examples/ subdir name</TD><TD>(none)</TD></TR>
3091 <TR><TD>Examples/GIFPlot/ subdir name</TD>
3092 <TD>capitalize (upcase first letter)</TD></TR>
3093 <TR><TD>Examples/test-suite/ subdir name</TD><TD>(none)</TD></TR>
3094 <!-- add more uses here (remember to adjust header) -->
3098 As you can see, most usages are direct.
3103 <dt> <b>configure.in</b>
3104 <dd> This file is processed by
3107 <A HREF="http://www.gnu.org/software/autoconf/">autoconf</A>
3108 to generate the <TT>configure</TT> script. This is where you
3109 need to add shell script fragments and autoconf macros to detect the
3110 presence of whatever development support your language module requires,
3111 typically directories where headers and libraries can be found, and/or
3112 utility programs useful for integrating the generated wrapper code.
3116 Use the <TT>AC_ARG_WITH</TT>, <TT>AC_MSG_CHECKING</TT>, <TT>AC_SUBST</TT>
3117 macros and so forth (see other languages for examples). Avoid using the
3118 <TT>[</TT> and <TT>]</TT> character in shell script fragments. The
3119 variable names passed to <TT>AC_SUBST</TT> should begin with the nickname,
3124 At the end of the new section is the place to put the aforementioned
3125 nickname kludges (should they be needed). See Perl5 for
3126 examples of what to do. [If this is still unclear after you've read
3127 the code, ping me and I'll expand on this further. --ttn]
3130 <dt> <b>Makefile.in</b>
3134 Some of the variables AC_SUBSTituted are essential to the
3135 support of your language module. Fashion these into a shell script
3136 "test" clause and assign that to a skip tag using "-z" and "-o":
3139 <div class="code"><tt>
3140 skip-qux99 = [ -z "@QUX99INCLUDE@" -o -z "@QUX99LIBS" ]
3144 This means if those vars should ever be empty, qux99 support should
3145 be considered absent and so it would be a good idea to skip actions that
3150 Here is where you may also define an alias (but then you'll need to
3151 kludge --- don't do this):
3154 <div class="code"><tt>
3155 skip-qux = $(skip-qux99)
3159 Lastly, you need to modify each of <TT>check-aliveness</TT>,
3160 <TT>check-examples</TT>, <TT>check-test-suite</TT>,
3161 <TT>check-gifplot</TT> (all targets) and <TT>lib-languages</TT> (var).
3162 Use the nickname for these, not the alias.
3163 Note that you can do this even before you have any tests or examples
3164 set up; the Makefile rules do some sanity checking and skip around
3165 these kinds of problems.
3168 <dt> <b>Examples/Makefile.in</b>
3169 <dd> Nothing special here; see comments at top the of this file
3170 and look to the existing languages for examples.
3172 <dt> <b>Examples/qux99/check.list</b>
3173 <dd> Do <TT>cp ../python/check.list .</TT> and modify to taste.
3174 One subdir per line.
3176 <dt> <b>Examples/GIFPlot/Qux99/check.list</b>
3177 <dd> Do <TT>cp ../Python/check.list .</TT> and modify to taste.
3178 One subdir per line.
3180 <dt> <b>Lib/qux99/extra-install.list</b>
3181 <dd> If you add your language to the top-level Makefile.in var
3182 <TT>lib-languages</TT>, then <TT>make install</TT> will install
3183 all <TT>*.i</TT> and <TT>*.swg</TT> files from the language-specific
3184 subdirectory of <TT>Lib</TT>. Use (optional) file
3185 <TT>extra-install.list</TT> in that directory to name
3186 additional files to install (see ruby for example).
3188 <dt> <b>Source/Modules/Makefile.am</b>
3189 <dd> Add appropriate files to this Automake file. That's it!
3192 When you have modified these files, please make sure that the new language module is completely
3193 ignored if it is not installed and detected on a box, that is, <tt>make check-examples</tt> and <tt>make check-test-suite</tt>
3194 politely displays the ignoring language message.
3200 <H3><a name="Extending_nn40"></a>35.10.9 Runtime support</H3>
3204 Discuss the kinds of functions typically needed for SWIG runtime support (e.g.
3205 <tt>SWIG_ConvertPtr()</tt> and <tt>SWIG_NewPointerObj()</tt>) and the names of
3206 the SWIG files that implement those functions.
3209 <H3><a name="Extending_nn41"></a>35.10.10 Standard library files</H3>
3213 The standard library files that most languages supply keeps growing as SWIG matures.
3214 The following are the minimum that are usually supported:
3218 <li> typemaps.i </li>
3219 <li> std_string.i </li>
3220 <li> std_vector.i </li>
3225 Please copy these and modify for any new language.
3228 <H3><a name="Extending_nn42"></a>35.10.11 Examples and test cases</H3>
3232 Each of the language modules provides one or more examples. These examples
3233 are used to demonstrate different features of the language module to SWIG
3234 end-users, but you'll find that they're useful during development and testing
3235 of your language module as well. You can use examples from the existing SWIG
3236 language modules for inspiration.
3240 Each example is self-contained and consists of (at least) a <tt>Makefile</tt>,
3241 a SWIG interface file for the example module, and a 'runme' script that demonstrates
3242 the functionality for that module. All of these files are stored in the same
3243 subdirectory under the <tt>Examples/[lang]</tt> directory.
3244 There are two classic examples which should be the first to convert to a new
3245 language module. These are the "simple" C example and the "class" C++ example.
3246 These can be found, for example for Python, in
3247 <tt>Examples/python/simple</tt> and <tt>Examples/python/class</tt>.
3251 By default, all of the examples are built and run when the user types
3252 <tt>make check</tt>. To ensure that your examples are automatically run
3253 during this process, see the section on <a href="#n37a">configuration
3257 <H3><a name="Extending_nn43"></a>35.10.12 Documentation</H3>
3261 Don't forget to write end-user documentation for your language module. Currently,
3262 each language module has a dedicated chapter
3263 You shouldn't rehash things that are already covered in sufficient
3264 detail in the <a href="SWIG.html#SWIG">SWIG Basics</a> and <a href="SWIGPlus.html#SWIGPlus">SWIG
3265 and C++</a> chapters. There is no fixed format for <em>what</em>, exactly, you should
3266 document about your language module, but you'll obviously want to cover issues that
3267 are unique to your language.
3271 Some topics that you'll want to be sure to address include:
3275 <li> Command line options unique to your language module.
3276 <li> Non-obvious mappings between C/C++ and target language concepts.
3277 For example, if your target language provides a single floating
3278 point type, it should be no big surprise to find that C/C++
3279 <tt>float</tt> and <tt>double</tt> types are mapped to it. On the other
3280 hand, if your target language doesn't provide support for "classes"
3281 or something similar, you'd want to discuss how C++ classes are handled.
3282 <li> How to compile the SWIG-generated wrapper code into shared libraries
3283 that can actually be used. For some languages, there are well-defined
3284 procedures for doing this, but for others it's an ad hoc process.
3285 Provide as much detail as appropriate, and links to other resources
3289 <H3><a name="Extending_prerequisites"></a>35.10.13 Prerequisites for adding a new language module to the SWIG distribution</H3>
3293 If you wish for a new language module to be distributed with SWIG,
3294 which we encourage for all popular languages, there are a few requirements.
3295 While we appreciate that getting all aspects of a new language working
3296 won't happen at the outset, there are a set of minimum requirements before
3297 a module can be committed into the SVN repository for distribution with future
3298 versions of SWIG. The following are really a summary of this whole section with
3299 details being outlined earlier on.
3304 Demonstrate basic C code working by porting the "simple" example including
3305 a runtime test, see for example <tt>Examples/python/simple</tt>.
3308 Demonstrate basic C++ code working by porting the "class" example including
3309 a runtime test, see for example <tt>Examples/python/class</tt>.
3312 Modify <tt>configure.in</tt>, <tt>Makefile.in</tt> and <tt>Examples/Makefile.in</tt> to run
3313 these examples. Please make sure that if the new language is not
3314 installed properly on a box, <tt>make -k check</tt> should still work by
3315 skipping the tests and examples for the new language module.
3318 Get the test-suite running for the new language (<tt>make check-[lang]-test-suite</tt>).
3319 While the test-suite tests many corner cases,
3320 we'd expect the majority of it to work by compiling the generated code
3321 correctly as most of the corner cases are covered in the SWIG core. Get
3322 at least one C and one C++ runtime test running in the test-suite.
3325 Provide a chapter in the html documentation on the basics of using
3326 the language module.
3329 Ensure your source code is formatted according to the <a href="#Extending_coding_style_guidelines">coding style guidelines</a>.
3332 Finally, email the SWIG developers with a patch and a demonstration of
3333 commitment to maintaining the language module,
3334 certainly in the short term and ideally long term.
3339 Once accepted into SVN, development efforts should concentrate on
3340 getting the entire test-suite to work with plenty of runtime tests.
3341 Runtime tests should be for existing testcases and new test cases
3342 should be added should there be an area not already covered by
3346 <H3><a name="Extending_coding_style_guidelines"></a>35.10.14 Coding style guidelines</H3>
3350 The coding guidelines for the C/C++ source code are pretty much K&R C style.
3351 The style can be inferred from the existing code base and is
3352 largely dictated by the <tt>indent</tt> code beautifier tool set to K&R style.
3353 The code can formatted using the make targets in the Source directory.
3354 Below is an example of how to format the emit.cxx file:
3360 $ make beautify-file INDENTFILE=Modules/emit.cxx
3365 Of particular note is indentation is set to 2 spaces and a tab is used instead of 8 spaces.
3366 The generated C/C++ code should also follow this style as close as possible. However, tabs
3367 should be avoided as unlike the SWIG developers, users will never have consistent tab settings.
3370 <H2><a name="Extending_nn44"></a>35.11 Typemaps</H2>
3373 <H3><a name="Extending_nn45"></a>35.11.1 Proxy classes</H3>
3376 <H2><a name="Extending_nn46"></a>35.12 Guide to parse tree nodes</H2>
3380 This section describes the different parse tree nodes and their attributes.
3388 Describes general C declarations including variables, functions, and typedefs.
3389 A declaration is parsed as "storage T D" where storage is a storage class, T is a base type,
3390 and D is a declarator.
3393 <div class="diagram">
3395 "name" - Declarator name
3396 "type" - Base type T
3397 "decl" - Declarator type (abstract)
3398 "storage" - Storage class (static, extern, typedef, etc.)
3399 "parms" - Function parameters (if a function)
3400 "code" - Function body code (if supplied)
3401 "value" - Default value (if supplied)
3411 C++ constructor declaration.
3414 <div class="diagram">
3416 "name" - Name of constructor
3417 "parms" - Parameters
3418 "decl" - Declarator (function with parameters)
3419 "code" - Function body code (if any)
3420 "feature:new" - Set to indicate return of new object.
3430 C++ destructor declaration.
3433 <div class="diagram">
3435 "name" - Name of destructor
3436 "code" - Function body code (if any)
3437 "storage" - Storage class (set if virtual)
3438 "value" - Default value (set if pure virtual).
3451 <div class="diagram">
3453 "kind" - public, protected, private
3463 Constant created by %constant or #define.
3466 <div class="diagram">
3468 "name" - Name of constant.
3471 "storage" - Set to %constant
3472 "feature:immutable" - Set to indicate read-only
3481 C++ class definition or C structure definition.
3484 <div class="diagram">
3486 "name" - Name of the class.
3487 "kind" - Class kind ("struct", "union", "class")
3488 "symtab" - Enclosing symbol table.
3489 "tdname" - Typedef name. Use for typedef struct { ... } A.
3490 "abstract" - Set if class has pure virtual methods.
3491 "baselist" - List of base class names.
3492 "storage" - Storage class (if any)
3493 "unnamed" - Set if class is unnamed.
3506 <div class="diagram">
3508 "name" - Name of the enum (if supplied).
3509 "storage" - Storage class (if any)
3510 "tdname" - Typedef name (typedef enum { ... } name).
3511 "unnamed" - Set if enum is unnamed.
3524 <div class="diagram">
3526 "name" - Name of the enum value.
3527 "type" - Type (integer or char)
3528 "value" - Enum value (if given)
3529 "feature:immutable" - Set to indicate read-only
3541 <div class="diagram">
3543 "name" - Name of the namespace.
3544 "symtab" - Symbol table for enclosed scope.
3545 "unnamed" - Set if unnamed namespace
3546 "alias" - Alias name. Set for namespace A = B;
3556 C++ using directive.
3559 <div class="diagram">
3561 "name" - Name of the object being referred to.
3562 "uname" - Qualified name actually given to using.
3563 "node" - Node being referenced.
3564 "namespace" - Namespace name being reference (using namespace name)
3574 A forward C++ class declaration.
3577 <div class="diagram">
3579 "name" - Name of the class.
3580 "kind" - Class kind ("union", "struct", "class")
3590 Code insertion directive. For example, %{ ... %} or
3594 <div class="diagram">
3596 "code" - Inserted code
3597 "section" - Section name ("header", "wrapper", etc.)
3606 Top of the parse tree.
3609 <div class="diagram">
3611 "module" - Module name
3623 <div class="diagram">
3625 "name" - Module name
3626 "symtab" - Symbol table of enclosed scope.
3635 %apply pattern { patternlist }.
3638 <div class="diagram">
3640 "pattern" - Source pattern.
3641 "symtab" - Symbol table of enclosed scope.
3653 <div class="diagram">
3655 "firstChild" - Patterns to clear
3667 <div class="diagram">
3670 "firstChild" - Children
3682 <div class="diagram">
3685 "firstChild" - Children
3698 <div class="diagram">
3700 "name" - Name of the module
3713 <div class="diagram">
3715 "method" - Typemap method name.
3716 "code" - Typemap code.
3717 "kwargs" - Keyword arguments (if any)
3718 "firstChild" - Typemap patterns
3727 %typemap directive with copy.
3730 <div class="diagram">
3732 "method" - Typemap method name.
3733 "pattern" - Typemap source pattern.
3734 "firstChild" - Typemap patterns
3744 %typemap pattern. Used with %apply, %clear, %typemap.
3747 <div class="diagram">
3749 "pattern" - Typemap pattern (a parameter list)
3750 "parms" - Typemap parameters.
3762 <div class="diagram">
3764 "parms" - List of parameter types.
3765 "convcode" - Code which replaces the default casting / conversion code
3775 extern "X" { ... } declaration.
3778 <div class="diagram">
3780 "name" - Name "C", "Fortran", etc.
projects / external / swig.git / blob