PageRenderTime 59ms CodeModel.GetById 12ms app.highlight 34ms RepoModel.GetById 1ms app.codeStats 0ms

/trunk/Doc/Manual/Extending.html

#
HTML | 2179 lines | 1785 code | 392 blank | 2 comment | 0 complexity | 835424fbad01723b7c2524b7fd5b1ad7 MD5 | raw file
   1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2<html>
   3<head>
   4<title>Extending SWIG to support new languages</title>
   5<link rel="stylesheet" type="text/css" href="style.css">
   6</head>
   7
   8<body bgcolor="#ffffff">
   9<H1><a name="Extending"></a>38 Extending SWIG to support new languages</H1>
  10<!-- INDEX -->
  11<div class="sectiontoc">
  12<ul>
  13<li><a href="#Extending_nn2">Introduction</a>
  14<li><a href="#Extending_nn3">Prerequisites</a>
  15<li><a href="#Extending_nn4">The Big Picture</a>
  16<li><a href="#Extending_nn5">Execution Model</a>
  17<ul>
  18<li><a href="#Extending_nn6">Preprocessing</a>
  19<li><a href="#Extending_nn7">Parsing</a>
  20<li><a href="#Extending_nn8">Parse Trees</a>
  21<li><a href="#Extending_nn9">Attribute namespaces</a>
  22<li><a href="#Extending_nn10">Symbol Tables</a>
  23<li><a href="#Extending_nn11">The %feature directive</a>
  24<li><a href="#Extending_nn12">Code Generation</a>
  25<li><a href="#Extending_nn13">SWIG and XML</a>
  26</ul>
  27<li><a href="#Extending_nn14">Primitive Data Structures</a>
  28<ul>
  29<li><a href="#Extending_nn15">Strings</a>
  30<li><a href="#Extending_nn16">Hashes</a>
  31<li><a href="#Extending_nn17">Lists</a>
  32<li><a href="#Extending_nn18">Common operations</a>
  33<li><a href="#Extending_nn19">Iterating over Lists and Hashes</a>
  34<li><a href="#Extending_nn20">I/O</a>
  35</ul>
  36<li><a href="#Extending_nn21">Navigating and manipulating parse trees</a>
  37<li><a href="#Extending_nn22">Working with attributes</a>
  38<li><a href="#Extending_nn23">Type system</a>
  39<ul>
  40<li><a href="#Extending_nn24">String encoding of types</a>
  41<li><a href="#Extending_nn25">Type construction</a>
  42<li><a href="#Extending_nn26">Type tests</a>
  43<li><a href="#Extending_nn27">Typedef and inheritance</a>
  44<li><a href="#Extending_nn28">Lvalues</a>
  45<li><a href="#Extending_nn29">Output functions</a>
  46</ul>
  47<li><a href="#Extending_nn30">Parameters</a>
  48<li><a href="#Extending_nn31">Writing a Language Module</a>
  49<ul>
  50<li><a href="#Extending_nn32">Execution model</a>
  51<li><a href="#Extending_starting_out">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_configuration_files">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">User examples</a>
  61<li><a href="#Extending_test_suite">Test driven development and the test-suite</a>
  62<ul>
  63<li><a href="#Extending_running_test_suite">Running the test-suite</a>
  64</ul>
  65<li><a href="#Extending_nn43">Documentation</a>
  66<li><a href="#Extending_prerequisites">Prerequisites for adding a new language module to the SWIG distribution</a>
  67<li><a href="#Extending_coding_style_guidelines">Coding style guidelines</a>
  68</ul>
  69<li><a href="#Extending_debugging_options">Debugging Options</a>
  70<li><a href="#Extending_nn46">Guide to parse tree nodes</a>
  71<li><a href="#Extending_further_info">Further Development Information</a>
  72</ul>
  73</div>
  74<!-- INDEX -->
  75
  76
  77
  78<H2><a name="Extending_nn2"></a>38.1 Introduction</H2>
  79
  80
  81<p>
  82This chapter describes SWIG's internal organization and the process by which
  83new target languages can be developed.    First, a brief word of warning---SWIG
  84is continually evolving.
  85The information in this chapter is mostly up to
  86date, but changes are ongoing.   Expect a few inconsistencies.
  87</p>
  88
  89<p>
  90Also, this chapter is not meant to be a hand-holding tutorial.  As a starting point,
  91you should probably look at one of SWIG's existing modules.
  92</p>
  93
  94<H2><a name="Extending_nn3"></a>38.2 Prerequisites</H2>
  95
  96
  97<p>
  98In order to extend SWIG, it is useful to have the following background:
  99</p>
 100
 101<ul>
 102<li>An understanding of the C API for the target language.
 103<li>A good grasp of the C++ type system.
 104<li>An understanding of typemaps and some of SWIG's advanced features.
 105<li>Some familiarity with writing C++ (language modules are currently written in C++).
 106</ul>
 107
 108<p>
 109Since SWIG is essentially a specialized C++ compiler, it may be useful
 110to have some prior experience with compiler design (perhaps even a
 111compilers course) to better understand certain parts of the system.  A
 112number of books will also be useful.  For example, "The C Programming
 113Language" by Kernighan and Ritchie (a.k.a, "K&amp;R") and the C++ standard,
 114"ISO/IEC 14882 Programming Languages - C++" will be of great use.
 115</p>
 116
 117<p>
 118Also, it is useful to keep in mind that SWIG primarily operates as an
 119extension of the C++ <em>type</em> system.  At first glance, this might not be
 120obvious, but almost all SWIG directives as well as the low-level generation of
 121wrapper code are driven by C++ datatypes.
 122</p>
 123
 124<H2><a name="Extending_nn4"></a>38.3 The Big Picture</H2>
 125
 126
 127<p>
 128SWIG is a special purpose compiler that parses C++ declarations to
 129generate wrapper code.  To make this conversion possible, SWIG makes
 130three fundamental extensions to the C++ language:
 131</p>
 132
 133<ul>
 134<li><b>Typemaps</b>. Typemaps are used to define the
 135conversion/marshalling behavior of specific C++ datatypes.  All type conversion in SWIG is
 136based on typemaps.  Furthermore, the association of typemaps to datatypes utilizes an advanced pattern matching
 137mechanism that is fully integrated with the C++ type system.
 138</li>
 139
 140<li><b>Declaration Annotation</b>. To customize wrapper code
 141generation, most declarations can be annotated with special features.
 142For example, you can make a variable read-only, you can ignore a
 143declaration, you can rename a member function, you can add exception
 144handling, and so forth.  Virtually all of these customizations are built on top of a low-level
 145declaration annotator that can attach arbitrary attributes to any declaration.
 146Code generation modules can look for these attributes to guide the wrapping process.
 147</li>
 148
 149<li><b>Class extension</b>. SWIG allows classes and structures to be extended with new
 150methods and attributes (the <tt>%extend</tt> directive).   This has the effect of altering
 151the API in the target language and can be used to generate OO interfaces to C libraries.
 152</ul>
 153
 154<p>
 155It is important to emphasize that virtually all SWIG features reduce to one of these three
 156fundamental concepts.  The type system and pattern matching rules also play a critical
 157role in making the system work.  For example, both typemaps and declaration annotation are
 158based on pattern matching and interact heavily with the underlying type system.
 159</p>
 160
 161<H2><a name="Extending_nn5"></a>38.4 Execution Model</H2>
 162
 163
 164<p>
 165When you run SWIG on an interface, processing is handled in stages by a series of system components:
 166</p>
 167
 168<ul>
 169<li>An integrated C preprocessor reads a collection of configuration
 170files and the specified interface file into memory.  The preprocessor
 171performs the usual functions including macro expansion and file
 172inclusion.   However, the preprocessor also performs some transformations of the
 173interface.  For instance, <tt>#define</tt> statements are sometimes transformed into
 174<tt>%constant</tt> declarations.  In addition, information related to file/line number
 175tracking is inserted.
 176</li>
 177
 178<li>A C/C++ parser reads the preprocessed input and generates a full
 179parse tree of all of the SWIG directives and C declarations found.
 180The parser is responsible for many aspects of the system including
 181renaming, declaration annotation, and template expansion.  However, the parser
 182does not produce any output nor does it interact with the target
 183language module as it runs.  SWIG is not a one-pass compiler.
 184</li>
 185
 186<li>A type-checking pass is made. This adjusts all of the C++ typenames to properly
 187handle namespaces, typedefs, nested classes, and other issues related to type scoping.
 188</li>
 189
 190<li>A semantic pass is made on the parse tree to collect information
 191related to properties of the C++ interface.  For example, this pass
 192would determine whether or not a class allows a default constructor.
 193</li>
 194
 195<li>A code generation pass is made using a specific target language
 196module.  This phase is responsible for generating the actual wrapper
 197code.  All of SWIG's user-defined modules are invoked during this
 198latter stage of compilation.
 199</li>
 200</ul>
 201
 202<p>
 203The next few sections briefly describe some of these stages.
 204</p>
 205
 206<H3><a name="Extending_nn6"></a>38.4.1 Preprocessing</H3>
 207
 208
 209<p>
 210The preprocessor plays a critical role in the SWIG implementation.  This is because a lot
 211of SWIG's processing and internal configuration is managed not by code written in C, but
 212by configuration files in the SWIG library.  In fact, when you
 213run SWIG, parsing starts with a small interface file like this (note: this explains
 214the cryptic error messages that new users sometimes get when SWIG is misconfigured or installed
 215incorrectly):
 216</p>
 217
 218<div class="code">
 219<pre>
 220%include "swig.swg"             // Global SWIG configuration
 221%include "<em>langconfig.swg</em>"       // Language specific configuration
 222%include "yourinterface.i"      // Your interface file
 223</pre>
 224</div>
 225
 226<p>
 227The <tt>swig.swg</tt> file contains global configuration information.  In addition, this file
 228defines many of SWIG's standard directives as macros.  For instance, part of
 229of <tt>swig.swg</tt> looks like this:
 230</p>
 231
 232<div class="code">
 233<pre>
 234...
 235/* Code insertion directives such as %wrapper %{ ... %} */
 236
 237#define %begin       %insert("begin")
 238#define %runtime     %insert("runtime")
 239#define %header      %insert("header")
 240#define %wrapper     %insert("wrapper")
 241#define %init        %insert("init")
 242
 243/* Access control directives */
 244
 245#define %immutable   %feature("immutable","1")
 246#define %mutable     %feature("immutable")
 247
 248/* Directives for callback functions */
 249
 250#define %callback(x) %feature("callback") `x`;
 251#define %nocallback  %feature("callback");
 252
 253/* %ignore directive */
 254
 255#define %ignore         %rename($ignore)
 256#define %ignorewarn(x)  %rename("$ignore:" x)
 257...
 258</pre>
 259</div>
 260
 261<p>
 262The fact that most of the standard SWIG directives are macros is
 263intended to simplify the implementation of the internals.  For instance,
 264rather than having to support dozens of special directives, it is
 265easier to have a few basic primitives such as <tt>%feature</tt> or
 266<tt>%insert</tt>.
 267</p>
 268
 269<p>
 270The <em><tt>langconfig.swg</tt></em> file is supplied by the target
 271language. This file contains language-specific configuration
 272information.  More often than not, this file provides run-time wrapper
 273support code (e.g., the type-checker) as well as a collection of
 274typemaps that define the default wrapping behavior.  Note: the name of this
 275file depends on the target language and is usually something like <tt>python.swg</tt>
 276or <tt>perl5.swg</tt>.
 277</p>
 278
 279<p>
 280As a debugging aide, the text that SWIG feeds to its C++ parser can be
 281obtained by running <tt>swig -E interface.i</tt>.  This output
 282probably isn't too useful in general, but it will show how macros have
 283been expanded as well as everything else that goes into the low-level
 284construction of the wrapper code.
 285</p>
 286
 287<H3><a name="Extending_nn7"></a>38.4.2 Parsing</H3>
 288
 289
 290<p>
 291The current C++ parser handles a subset of C++.  Most incompatibilities with C are due to
 292subtle aspects of how SWIG parses declarations.  Specifically, SWIG expects all C/C++ declarations to follow this general form:
 293</p>
 294
 295<div class="diagram">
 296<pre>
 297<em>storage</em> <em>type</em> <em>declarator</em> <em>initializer</em>;
 298</pre>
 299</div>
 300
 301<p>
 302<tt><em>storage</em></tt> is a keyword such as <tt>extern</tt>,
 303<tt>static</tt>, <tt>typedef</tt>, or <tt>virtual</tt>.  <tt><em>type</em></tt> is a primitive
 304datatype such as <tt>int</tt> or <tt>void</tt>.   <tt><em>type</em></tt> may be optionally
 305qualified with a qualifier such as <tt>const</tt> or <tt>volatile</tt>. <tt><em>declarator</em></tt>
 306is a name with additional type-construction modifiers attached to it (pointers, arrays, references,
 307functions, etc.).  Examples of declarators include <tt>*x</tt>, <tt>**x</tt>, <tt>x[20]</tt>, and
 308<tt>(*x)(int,double)</tt>.   The <tt><em>initializer</em></tt> may be a value assigned using <tt>=</tt> or
 309body of code enclosed in braces <tt>{ ... }</tt>.
 310</p>
 311
 312<p>
 313This declaration format covers most common C++ declarations. However, the C++ standard
 314is somewhat more flexible in the placement of the parts.  For example, it is technically legal, although
 315uncommon to write something like <tt>int typedef const a</tt> in your program.   SWIG simply
 316doesn't bother to deal with this case.
 317</p>
 318
 319<p>
 320The other significant difference between C++ and SWIG is in the
 321treatment of typenames.  In C++, if you have a declaration like this,
 322</p>
 323
 324<div class="code">
 325<pre>
 326int blah(Foo *x, Bar *y);
 327</pre>
 328</div>
 329
 330<p>
 331it won't parse correctly unless <tt>Foo</tt> and <tt>Bar</tt> have
 332been previously defined as types either using a <tt>class</tt>
 333definition or a <tt>typedef</tt>.  The reasons for this are subtle,
 334but this treatment of typenames is normally integrated at the level of the C
 335tokenizer---when a typename appears, a different token is returned to the parser
 336instead of an identifier.
 337</p>
 338
 339<p>
 340SWIG does not operate in this manner--any legal identifier can be used
 341as a type name.  The reason for this is primarily motivated by the use
 342of SWIG with partially defined data.  Specifically,
 343SWIG is supposed to be easy to use on interfaces with missing type information.
 344</p>
 345
 346<p>
 347Because of the different treatment of typenames, the most serious
 348limitation of the SWIG parser is that it can't process type declarations where
 349an extra (and unnecessary) grouping operator is used.  For example:
 350</p>
 351
 352<div class="code">
 353<pre>
 354int (x);         /* A variable x */
 355int (y)(int);    /* A function y */
 356</pre>
 357</div>
 358
 359<p>
 360The placing of extra parentheses in type declarations like this is
 361already recognized by the C++ community as a potential source of
 362strange programming errors. For example, Scott Meyers "Effective STL"
 363discusses this problem in a section on avoiding C++'s "most vexing
 364parse."
 365</p>
 366
 367<p>
 368The parser is also unable to handle declarations with no return type or bare argument names.
 369For example, in an old C program, you might see things like this:
 370</p>
 371
 372<div class="code">
 373<pre>
 374foo(a,b) {
 375...
 376}
 377</pre>
 378</div>
 379
 380<p>
 381In this case, the return type as well as the types of the arguments
 382are taken by the C compiler to be an <tt>int</tt>.  However, SWIG
 383interprets the above code as an abstract declarator for a function
 384returning a <tt>foo</tt> and taking types <tt>a</tt> and <tt>b</tt> as
 385arguments).
 386</p>
 387
 388<H3><a name="Extending_nn8"></a>38.4.3 Parse Trees</H3>
 389
 390
 391<p>
 392The SWIG parser produces a complete parse tree of the input file before any wrapper code
 393is actually generated.  Each item in the tree is known as a "Node".   Each node is identified
 394by a symbolic tag.   Furthermore, a node may have an arbitrary number of children.
 395The parse tree structure and tag names of an interface can be displayed using <tt>swig -debug-tags</tt>.
 396For example:
 397</p>
 398
 399<div class="shell">
 400<pre>
 401$ <b>swig -c++ -python -debug-tags example.i</b>
 402 . top (example.i:1)
 403 . top . include (example.i:1)
 404 . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/swig.swg:71)
 405 . top . include . typemap . typemapitem (/r0/beazley/Projects/lib/swig1.3/swig.swg:71)
 406 . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/swig.swg:83)
 407 . top . include . typemap . typemapitem (/r0/beazley/Projects/lib/swig1.3/swig.swg:83)
 408 . top . include (example.i:4)
 409 . top . include . insert (/r0/beazley/Projects/lib/swig1.3/python/python.swg:7)
 410 . top . include . insert (/r0/beazley/Projects/lib/swig1.3/python/python.swg:8)
 411 . top . include . typemap (/r0/beazley/Projects/lib/swig1.3/python/python.swg:19)
 412...
 413 . top . include (example.i:6)
 414 . top . include . module (example.i:2)
 415 . top . include . insert (example.i:6)
 416 . top . include . include (example.i:9)
 417 . top . include . include . class (example.h:3)
 418 . top . include . include . class . access (example.h:4)
 419 . top . include . include . class . constructor (example.h:7)
 420 . top . include . include . class . destructor (example.h:10)
 421 . top . include . include . class . cdecl (example.h:11)
 422 . top . include . include . class . cdecl (example.h:11)
 423 . top . include . include . class . cdecl (example.h:12)
 424 . top . include . include . class . cdecl (example.h:13)
 425 . top . include . include . class . cdecl (example.h:14)
 426 . top . include . include . class . cdecl (example.h:15)
 427 . top . include . include . class (example.h:18)
 428 . top . include . include . class . access (example.h:19)
 429 . top . include . include . class . cdecl (example.h:20)
 430 . top . include . include . class . access (example.h:21)
 431 . top . include . include . class . constructor (example.h:22)
 432 . top . include . include . class . cdecl (example.h:23)
 433 . top . include . include . class . cdecl (example.h:24)
 434 . top . include . include . class (example.h:27)
 435 . top . include . include . class . access (example.h:28)
 436 . top . include . include . class . cdecl (example.h:29)
 437 . top . include . include . class . access (example.h:30)
 438 . top . include . include . class . constructor (example.h:31)
 439 . top . include . include . class . cdecl (example.h:32)
 440 . top . include . include . class . cdecl (example.h:33)
 441</pre>
 442</div>
 443
 444<p>
 445Even for the most simple interface, the parse tree structure is larger than you might expect.  For example, in the
 446above output, a substantial number of nodes are actually generated by the <tt>python.swg</tt> configuration file
 447which defines typemaps and other directives.   The contents of the user-supplied input file don't appear until the end
 448of the output.
 449</p>
 450
 451<p>
 452The contents of each parse tree node consist of a collection of attribute/value
 453pairs.  Internally, the nodes are simply represented by hash tables.  A display of
 454the entire parse-tree structure can be obtained using <tt>swig -debug-top &lt;n&gt;</tt>, where <tt>n</tt> is
 455the stage being processed. 
 456There are a number of other parse tree display options, for example, <tt>swig -debug-module &lt;n&gt;</tt> will
 457avoid displaying system parse information and only display the parse tree pertaining to the user's module at
 458stage <tt>n</tt> of processing.
 459</p>
 460
 461<div class="shell">
 462<pre>
 463$ swig -c++ -python -debug-module 4 example.i
 464      +++ include ----------------------------------------
 465      | name         - "example.i"
 466
 467            +++ module ----------------------------------------
 468            | name         - "example"
 469            |
 470            +++ insert ----------------------------------------
 471            | code         - "\n#include \"example.h\"\n"
 472            |
 473            +++ include ----------------------------------------
 474            | name         - "example.h"
 475
 476                  +++ class ----------------------------------------
 477                  | abstract     - "1"
 478                  | sym:name     - "Shape"
 479                  | name         - "Shape"
 480                  | kind         - "class"
 481                  | symtab       - 0x40194140
 482                  | sym:symtab   - 0x40191078
 483
 484                        +++ access ----------------------------------------
 485                        | kind         - "public"
 486                        |
 487                        +++ constructor ----------------------------------------
 488                        | sym:name     - "Shape"
 489                        | name         - "Shape"
 490                        | decl         - "f()."
 491                        | code         - "{\n    nshapes++;\n  }"
 492                        | sym:symtab   - 0x40194140
 493                        |
 494                        +++ destructor ----------------------------------------
 495                        | sym:name     - "~Shape"
 496                        | name         - "~Shape"
 497                        | storage      - "virtual"
 498                        | code         - "{\n    nshapes--;\n  }"
 499                        | sym:symtab   - 0x40194140
 500                        |
 501                        +++ cdecl ----------------------------------------
 502                        | sym:name     - "x"
 503                        | name         - "x"
 504                        | decl         - ""
 505                        | type         - "double"
 506                        | sym:symtab   - 0x40194140
 507                        |
 508                        +++ cdecl ----------------------------------------
 509                        | sym:name     - "y"
 510                        | name         - "y"
 511                        | decl         - ""
 512                        | type         - "double"
 513                        | sym:symtab   - 0x40194140
 514                        |
 515                        +++ cdecl ----------------------------------------
 516                        | sym:name     - "move"
 517                        | name         - "move"
 518                        | decl         - "f(double,double)."
 519                        | parms        - double ,double
 520                        | type         - "void"
 521                        | sym:symtab   - 0x40194140
 522                        |
 523                        +++ cdecl ----------------------------------------
 524                        | sym:name     - "area"
 525                        | name         - "area"
 526                        | decl         - "f(void)."
 527                        | parms        - void
 528                        | storage      - "virtual"
 529                        | value        - "0"
 530                        | type         - "double"
 531                        | sym:symtab   - 0x40194140
 532                        |
 533                        +++ cdecl ----------------------------------------
 534                        | sym:name     - "perimeter"
 535                        | name         - "perimeter"
 536                        | decl         - "f(void)."
 537                        | parms        - void
 538                        | storage      - "virtual"
 539                        | value        - "0"
 540                        | type         - "double"
 541                        | sym:symtab   - 0x40194140
 542                        |
 543                        +++ cdecl ----------------------------------------
 544                        | sym:name     - "nshapes"
 545                        | name         - "nshapes"
 546                        | decl         - ""
 547                        | storage      - "static"
 548                        | type         - "int"
 549                        | sym:symtab   - 0x40194140
 550                        |
 551                  +++ class ----------------------------------------
 552                  | sym:name     - "Circle"
 553                  | name         - "Circle"
 554                  | kind         - "class"
 555                  | bases        - 0x40194510
 556                  | symtab       - 0x40194538
 557                  | sym:symtab   - 0x40191078
 558
 559                        +++ access ----------------------------------------
 560                        | kind         - "private"
 561                        |
 562                        +++ cdecl ----------------------------------------
 563                        | name         - "radius"
 564                        | decl         - ""
 565                        | type         - "double"
 566                        |
 567                        +++ access ----------------------------------------
 568                        | kind         - "public"
 569                        |
 570                        +++ constructor ----------------------------------------
 571                        | sym:name     - "Circle"
 572                        | name         - "Circle"
 573                        | parms        - double
 574                        | decl         - "f(double)."
 575                        | code         - "{ }"
 576                        | sym:symtab   - 0x40194538
 577                        |
 578                        +++ cdecl ----------------------------------------
 579                        | sym:name     - "area"
 580                        | name         - "area"
 581                        | decl         - "f(void)."
 582                        | parms        - void
 583                        | storage      - "virtual"
 584                        | type         - "double"
 585                        | sym:symtab   - 0x40194538
 586                        |
 587                        +++ cdecl ----------------------------------------
 588                        | sym:name     - "perimeter"
 589                        | name         - "perimeter"
 590                        | decl         - "f(void)."
 591                        | parms        - void
 592                        | storage      - "virtual"
 593                        | type         - "double"
 594                        | sym:symtab   - 0x40194538
 595                        |
 596                  +++ class ----------------------------------------
 597                  | sym:name     - "Square"
 598                  | name         - "Square"
 599                  | kind         - "class"
 600                  | bases        - 0x40194760
 601                  | symtab       - 0x40194788
 602                  | sym:symtab   - 0x40191078
 603
 604                        +++ access ----------------------------------------
 605                        | kind         - "private"
 606                        |
 607                        +++ cdecl ----------------------------------------
 608                        | name         - "width"
 609                        | decl         - ""
 610                        | type         - "double"
 611                        |
 612                        +++ access ----------------------------------------
 613                        | kind         - "public"
 614                        |
 615                        +++ constructor ----------------------------------------
 616                        | sym:name     - "Square"
 617                        | name         - "Square"
 618                        | parms        - double
 619                        | decl         - "f(double)."
 620                        | code         - "{ }"
 621                        | sym:symtab   - 0x40194788
 622                        |
 623                        +++ cdecl ----------------------------------------
 624                        | sym:name     - "area"
 625                        | name         - "area"
 626                        | decl         - "f(void)."
 627                        | parms        - void
 628                        | storage      - "virtual"
 629                        | type         - "double"
 630                        | sym:symtab   - 0x40194788
 631                        |
 632                        +++ cdecl ----------------------------------------
 633                        | sym:name     - "perimeter"
 634                        | name         - "perimeter"
 635                        | decl         - "f(void)."
 636                        | parms        - void
 637                        | storage      - "virtual"
 638                        | type         - "double"
 639                        | sym:symtab   - 0x40194788
 640</pre>
 641</div>
 642
 643<H3><a name="Extending_nn9"></a>38.4.4 Attribute namespaces</H3>
 644
 645
 646<p>
 647Attributes of parse tree nodes are often prepended with a namespace qualifier.
 648For example, the attributes
 649<tt>sym:name</tt> and <tt>sym:symtab</tt> are attributes related to
 650symbol table management and are prefixed with <tt>sym:</tt>.  As a
 651general rule, only those attributes which are directly related to the raw declaration
 652appear without a prefix (type, name, declarator, etc.).
 653</p>
 654
 655<p>
 656Target language modules may add additional attributes to nodes to assist the generation
 657of wrapper code.  The convention for doing this is to place these attributes in a namespace
 658that matches the name of the target language.  For example, <tt>python:foo</tt> or
 659<tt>perl:foo</tt>.
 660</p>
 661
 662<H3><a name="Extending_nn10"></a>38.4.5 Symbol Tables</H3>
 663
 664
 665<p>
 666During parsing, all symbols are managed in the space of the target
 667language.  The <tt>sym:name</tt> attribute of each node contains the symbol name
 668selected by the parser.  Normally, <tt>sym:name</tt> and <tt>name</tt>
 669are the same.  However, the <tt>%rename</tt> directive can be used to
 670change the value of <tt>sym:name</tt>.  You can see the effect of
 671<tt>%rename</tt> by trying it on a simple interface and dumping the
 672parse tree.  For example:
 673</p>
 674
 675<div class="code">
 676<pre>
 677%rename(foo_i) foo(int);
 678%rename(foo_d) foo(double);
 679
 680void foo(int);
 681void foo(double);
 682void foo(Bar *b);
 683</pre>
 684</div>
 685
 686<p>
 687There are various <tt>debug-</tt> options that can be useful for debugging and analysing the parse tree.
 688For example, the <tt>debug-top &lt;n&gt;</tt> or <tt>debug-module &lt;n&gt;</tt> options will
 689dump the entire/top of the parse tree or the module subtree at one of the four <tt>n</tt> stages of processing.
 690The parse tree can be viewed after the final stage of processing by running SWIG:
 691</p>
 692
 693<div class="shell">
 694<pre>
 695$ swig -debug-top 4 example.i
 696...
 697            +++ cdecl ----------------------------------------
 698            | sym:name     - "foo_i"
 699            | name         - "foo"
 700            | decl         - "f(int)."
 701            | parms        - int
 702            | type         - "void"
 703            | sym:symtab   - 0x40165078
 704            |
 705            +++ cdecl ----------------------------------------
 706            | sym:name     - "foo_d"
 707            | name         - "foo"
 708            | decl         - "f(double)."
 709            | parms        - double
 710            | type         - "void"
 711            | sym:symtab   - 0x40165078
 712            |
 713            +++ cdecl ----------------------------------------
 714            | sym:name     - "foo"
 715            | name         - "foo"
 716            | decl         - "f(p.Bar)."
 717            | parms        - Bar *
 718            | type         - "void"
 719            | sym:symtab   - 0x40165078
 720</pre>
 721</div>
 722
 723<p>
 724All symbol-related conflicts and complaints about overloading are based on <tt>sym:name</tt> values.
 725For instance, the following example uses <tt>%rename</tt> in reverse to generate a name clash.
 726</p>
 727
 728<div class="code">
 729<pre>
 730%rename(foo) foo_i(int);
 731%rename(foo) foo_d(double;
 732
 733void foo_i(int);
 734void foo_d(double);
 735void foo(Bar *b);
 736</pre>
 737</div>
 738
 739<p>
 740When you run SWIG on this you now get:
 741</p>
 742
 743<div class="shell">
 744<pre>
 745$ ./swig example.i
 746example.i:6. Overloaded declaration ignored.  foo_d(double )
 747example.i:5. Previous declaration is foo_i(int )
 748example.i:7. Overloaded declaration ignored.  foo(Bar *)
 749example.i:5. Previous declaration is foo_i(int )
 750</pre>
 751</div>
 752
 753<H3><a name="Extending_nn11"></a>38.4.6 The %feature directive</H3>
 754
 755
 756<p>
 757A number of SWIG directives such as <tt>%exception</tt> are implemented using the
 758low-level <tt>%feature</tt> directive.  For example:
 759</p>
 760
 761<div class="code">
 762<pre>
 763%feature("except") getitem(int) {
 764  try {
 765     $action
 766  } catch (badindex) {
 767     ...
 768  }
 769}
 770
 771...
 772class Foo {
 773public:
 774    Object *getitem(int index) throws(badindex);
 775    ...
 776};
 777</pre>
 778</div>
 779
 780<p>
 781The behavior of <tt>%feature</tt> is very easy to describe--it simply
 782attaches a new attribute to any parse tree node that matches the
 783given prototype.   When a feature is added, it shows up as an attribute in the <tt>feature:</tt> namespace.
 784You can see this when running with the <tt>-debug-top 4</tt> option.   For example:
 785</p>
 786
 787<div class="shell">
 788<pre>
 789 +++ cdecl ----------------------------------------
 790 | sym:name     - "getitem"
 791 | name         - "getitem"
 792 | decl         - "f(int).p."
 793 | parms        - int
 794 | type         - "Object"
 795 | feature:except - "{\n    try {\n       $action\n    } catc..."
 796 | sym:symtab   - 0x40168ac8
 797 |
 798</pre>
 799</div>
 800
 801<p>
 802Feature names are completely arbitrary and a target language module can be
 803programmed to respond to any feature name that it wants to recognize.  The 
 804data stored in a feature attribute is usually just a raw unparsed string.   
 805For example, the exception code above is simply
 806stored without any modifications.
 807</p>
 808
 809<H3><a name="Extending_nn12"></a>38.4.7 Code Generation</H3>
 810
 811
 812<p>
 813Language modules work by defining handler functions that know how to respond to
 814different types of parse-tree nodes.  These handlers simply look at the
 815attributes of each node in order to produce low-level code.
 816</p>
 817
 818<p>
 819In reality, the generation of code is somewhat more subtle than simply
 820invoking handler functions.  This is because parse-tree nodes might be
 821transformed. For example, suppose you are wrapping a class like this:
 822</p>
 823
 824<div class="code">
 825<pre>
 826class Foo {
 827public:
 828    virtual int *bar(int x);
 829};
 830</pre>
 831</div>
 832
 833<p>
 834When the parser constructs a node for the member <tt>bar</tt>, it creates a raw "cdecl" node with the following
 835attributes:
 836</p>
 837
 838<div class="diagram">
 839<pre>
 840nodeType    : cdecl
 841name        : bar
 842type        : int
 843decl        : f(int).p
 844parms       : int x
 845storage     : virtual
 846sym:name    : bar
 847</pre>
 848</div>
 849
 850<p>
 851To 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</p>
 853
 854<div class="diagram">
 855<pre>
 856nodeType    : cdecl
 857name        : bar
 858type        : p.int        &lt;-- Notice change in return type
 859decl        : f(int).p
 860parms       : int x
 861storage     : virtual
 862sym:name    : bar
 863</pre>
 864</div>
 865
 866<p>
 867Next, the context of the node indicates that the node is really a
 868member function.  This produces a transformation to a low-level
 869accessor function like this:
 870</p>
 871
 872<div class="diagram">
 873<pre>
 874nodeType    : cdecl
 875name        : bar
 876type        : int.p
 877decl        : f(int).p
 878parms       : Foo *self, int x            &lt;-- Added parameter
 879storage     : virtual
 880wrap:action : result = (arg1)-&gt;bar(arg2)  &lt;-- Action code added
 881sym:name    : Foo_bar                     &lt;-- Symbol name changed
 882</pre>
 883</div>
 884
 885<p>
 886In this transformation, notice how an additional parameter was added
 887to the parameter list and how the symbol name of the node has suddenly
 888changed into an accessor using the naming scheme described in the
 889"SWIG Basics" chapter.  A small fragment of "action" code has also
 890been generated--notice how the <tt>wrap:action</tt> attribute defines
 891the access to the underlying method.  The data in this transformed
 892node is then used to generate a wrapper.
 893</p>
 894
 895<p>
 896Language modules work by registering handler functions for dealing with
 897various types of nodes at different stages of transformation.   This is done by
 898inheriting from a special <tt>Language</tt> class and defining a collection
 899of virtual methods.   For example, the Python module defines a class as
 900follows:
 901</p>
 902
 903<div class="code">
 904<pre>
 905class PYTHON : public Language {
 906protected:
 907public :
 908  virtual void main(int, char *argv[]);
 909  virtual int  top(Node *);
 910  virtual int  functionWrapper(Node *);
 911  virtual int  constantWrapper(Node *);
 912  virtual int  variableWrapper(Node *);
 913  virtual int  nativeWrapper(Node *);
 914  virtual int  membervariableHandler(Node *);
 915  virtual int  memberconstantHandler(Node *);
 916  virtual int  memberfunctionHandler(Node *);
 917  virtual int  constructorHandler(Node *);
 918  virtual int  destructorHandler(Node *);
 919  virtual int  classHandler(Node *);
 920  virtual int  classforwardDeclaration(Node *);
 921  virtual int  insertDirective(Node *);
 922  virtual int  importDirective(Node *);
 923};
 924</pre>
 925</div>
 926
 927<p>
 928The role of these functions is described shortly.
 929</p>
 930
 931<H3><a name="Extending_nn13"></a>38.4.8 SWIG and XML</H3>
 932
 933
 934<p>
 935Much of SWIG's current parser design was originally motivated by
 936interest in using XML to represent SWIG parse trees.  Although XML is
 937not currently used in any direct manner, the parse tree structure, use
 938of node tags, attributes, and attribute namespaces are all influenced
 939by aspects of XML parsing.  Therefore, in trying to understand SWIG's
 940internal data structures, it may be useful to keep XML in the back of
 941your mind as a model.
 942</p>
 943
 944<H2><a name="Extending_nn14"></a>38.5 Primitive Data Structures</H2>
 945
 946
 947<p>
 948Most of SWIG is constructed using three basic data structures:
 949strings, hashes, and lists.  These data structures are dynamic in same way as
 950similar structures found in many scripting languages.  For instance,
 951you can have containers (lists and hash tables) of mixed types and
 952certain operations are polymorphic.
 953</p>
 954
 955<p>
 956This section briefly describes the basic structures so that later
 957sections of this chapter make more sense.
 958</p>
 959
 960<p>
 961When describing the low-level API, the following type name conventions are
 962used:
 963</p>
 964
 965<ul>
 966<li><tt>String</tt>.  A string object.
 967<li><tt>Hash</tt>. A hash object.
 968<li><tt>List</tt>. A list object.
 969<li><tt>String_or_char</tt>. A string object or a <tt>char *</tt>.
 970<li><tt>Object_or_char</tt>. An object or a <tt>char *</tt>.
 971<li><tt>Object</tt>.  Any object (string, hash, list, etc.)
 972</ul>
 973
 974<p>
 975In most cases, other typenames in the source are aliases for one of these
 976primitive types.   Specifically:
 977</p>
 978
 979<div class="code">
 980<pre>
 981typedef String SwigType;
 982typedef Hash   Parm;
 983typedef Hash   ParmList;
 984typedef Hash   Node;
 985typedef Hash   Symtab;
 986typedef Hash   Typetab;
 987</pre>
 988</div>
 989
 990<H3><a name="Extending_nn15"></a>38.5.1 Strings</H3>
 991
 992
 993<p>
 994<b><tt>String *NewString(const String_or_char *val)</tt></b>
 995</p>
 996
 997<div class="indent">
 998Creates a new string with initial value <tt>val</tt>. <tt>val</tt> may
 999be a <tt>char *</tt> or another <tt>String</tt> object.   If you want
1000to create an empty string, use "" for val.
1001</div>
1002
1003<p>
1004<b><tt>String *NewStringf(const char *fmt, ...)</tt></b>
1005</p>
1006
1007<div class="indent">
1008Creates a new string whose initial value is set according to a C <tt>printf</tt> style
1009format string in <tt>fmt</tt>.   Additional arguments follow depending
1010on <tt>fmt</tt>.
1011</div>
1012
1013<p>
1014<b><tt>String *Copy(String *s)</tt></b>
1015</p>
1016
1017<div class="indent">
1018Make a copy of the string <tt>s</tt>.
1019</div>
1020
1021<p>
1022<b><tt>void Delete(String *s)</tt></b>
1023</p>
1024
1025<div class="indent">
1026Deletes <tt>s</tt>.
1027</div>
1028
1029<p>
1030<b><tt>int Len(const String_or_char *s)</tt></b>
1031</p>
1032
1033<div class="indent">
1034Returns the length of the string.
1035</div>
1036
1037<p>
1038<b><tt>char *Char(const String_or_char *s)</tt></b>
1039</p>
1040
1041<div class="indent">
1042Returns a pointer to the first character in a string.
1043</div>
1044
1045<p>
1046<b><tt>void Append(String *s, const String_or_char *t)</tt></b>
1047</p>
1048
1049<div class="indent">
1050Appends <tt>t</tt> to the end of string <tt>s</tt>.
1051</div>
1052
1053<p>
1054<b><tt>void Insert(String *s, int pos, const String_or_char *t)</tt></b>
1055</p>
1056
1057<div class="indent">
1058Inserts <tt>t</tt> into <tt>s</tt> at position <tt>pos</tt>.  The contents
1059of <tt>s</tt> are shifted accordingly.    The special value <tt>DOH_END</tt>
1060can be used for <tt>pos</tt> to indicate insertion at the end of the string (appending).
1061</div>
1062
1063<p>
1064<b><tt>int Strcmp(const String_or_char *s, const String_or_char *t)</tt></b>
1065</p>
1066
1067<div class="indent">
1068Compare strings <tt>s</tt> and <tt>t</tt>.   Same as the C <tt>strcmp()</tt>
1069function.
1070</div>
1071
1072<p>
1073<b><tt>int Strncmp(const String_or_char *s, const String_or_char *t, int len)</tt></b>
1074</p>
1075
1076<div class="indent">
1077Compare the first <tt>len</tt> characters of strings <tt>s</tt> and <tt>t</tt>.   Same as the C <tt>strncmp()</tt>
1078function.
1079</div>
1080
1081<p>
1082<b><tt>char *Strstr(const String_or_char *s, const String_or_char *pat)</tt></b>
1083</p>
1084
1085<div class="indent">
1086Returns a pointer to the first occurrence of <tt>pat</tt> in <tt>s</tt>.
1087Same as the C <tt>strstr()</tt> function.
1088</div>
1089
1090<p>
1091<b><tt>char *Strchr(const String_or_char *s, char ch)</tt></b>
1092</p>
1093
1094<div class="indent">
1095Returns a pointer to the first occurrence of character <tt>ch</tt> in <tt>s</tt>.
1096Same as the C <tt>strchr()</tt> function.
1097</div>
1098
1099<p>
1100<b><tt>void Chop(String *s)</tt></b>
1101</p>
1102
1103<div class="indent">
1104Chops trailing whitespace off the end of <tt>s</tt>.
1105</div>
1106
1107<p>
1108<b><tt>int Replace(String *s, const String_or_char *pat, const String_or_char *rep, int flags)</tt></b>
1109</p>
1110
1111<div class="indent">
1112<p>
1113Replaces the pattern <tt>pat</tt> with <tt>rep</tt> in string <tt>s</tt>.
1114<tt>flags</tt> is a combination of the following flags:</p>
1115
1116<div class="code">
1117<pre>
1118DOH_REPLACE_ANY       - Replace all occurrences
1119DOH_REPLACE_ID        - Valid C identifiers only
1120DOH_REPLACE_NOQUOTE   - Don't replace in quoted strings
1121DOH_REPLACE_FIRST     - Replace first occurrence only.
1122</pre>
1123</div>
1124
1125<p>
1126Returns the number of replacements made (if any).
1127</p>
1128
1129</div>
1130
1131<H3><a name="Extending_nn16"></a>38.5.2 Hashes</H3>
1132
1133
1134<p>
1135<b><tt>Hash *NewHash()</tt></b>
1136</p>
1137
1138<div class="indent">
1139Creates a new empty hash table.
1140</div>
1141
1142<p>
1143<b><tt>Hash *Copy(Hash *h)</tt></b>
1144</p>
1145
1146<div class="indent">
1147Make a shallow copy of the hash <tt>h</tt>.
1148</div>
1149
1150<p>
1151<b><tt>void Delete(Hash *h)</tt></b>
1152</p>
1153
1154<div class="indent">
1155Deletes <tt>h</tt>.
1156</div>
1157
1158<p>
1159<b><tt>int Len(Hash *h)</tt></b>
1160</p>
1161
1162<div class="indent">
1163Returns the number of items in <tt>h</tt>.
1164</div>
1165
1166<p>
1167<b><tt>Object *Getattr(Hash *h, const String_or_char *key)</tt></b>
1168</p>
1169
1170<div class="indent">
1171Gets an object from <tt>h</tt>.  <tt>key</tt> may be a string or
1172a simple <tt>char *</tt> string.   Returns NULL if not found.
1173</div>
1174
1175<p>
1176<b><tt>int Setattr(Hash *h, const String_or_char *key, const Object_or_char *val)</tt></b>
1177</p>
1178
1179<div class="indent">
1180Stores <tt>val</tt> in <tt>h</tt>. <tt>key</tt> may be a string or
1181a simple <tt>char *</tt>. If <tt>val</tt> is not a standard
1182object (String, Hash, or List) it is assumed to be a <tt>char *</tt> in which
1183case it is used to construct a <tt>String</tt> that is stored in the hash.
1184If <tt>val</tt> is NULL, the object is deleted. Increases the reference count
1185of <tt>val</tt>.   Returns 1 if this operation replaced an existing hash entry,
11860 otherwise.
1187</div>
1188
1189<p>
1190<b><tt>int Delattr(Hash *h, const String_or_char *key)</tt></b>
1191</p>
1192
1193<div class="indent">
1194Deletes the hash item referenced by <tt>key</tt>.  Decreases the
1195reference count on the corresponding object (if any).  Returns 1
1196if an object was removed, 0 otherwise.
1197</div>
1198
1199<p>
1200<b><tt>List *Keys(Hash *h)</tt></b>
1201</p>
1202
1203<div class="indent">
1204Returns the list of hash table keys.
1205</div>
1206
1207
1208<H3><a name="Extending_nn17"></a>38.5.3 Lists</H3>
1209
1210
1211<p>
1212<b><tt>List *NewList()</tt></b>
1213</p>
1214
1215<div class="indent">
1216Creates a new empty list.
1217</div>
1218
1219<p>
1220<b><tt>List *Copy(List *x)</tt></b>
1221</p>
1222
1223<div class="indent">
1224Make a shallow copy of the List <tt>x</tt>.
1225</div>
1226
1227<p>
1228<b><tt>void Delete(List *x)</tt></b>
1229</p>
1230
1231<div class="indent">
1232Deletes <tt>x</tt>.
1233</div>
1234
1235<p>
1236<b><tt>int Len(List *x)</tt></b>
1237</p>
1238
1239<div class="indent">
1240Returns the number of items in <tt>x</tt>.
1241</div>
1242
1243<p>
1244<b><tt>Object *Getitem(List *x, int n)</tt></b>
1245</p>
1246
1247<div class="indent">
1248Returns an object from <tt>x</tt> with index <tt>n</tt>.  If <tt>n</tt> is
1249beyond the end of the list, the last item is returned. If <tt>n</tt> is
1250negative, the first item is returned.
1251</div>
1252
1253<p>
1254<b><tt>int *Setitem(List *x, int n, const Object_or_char *val)</tt></b>
1255</p>
1256
1257<div class="indent">
1258Stores <tt>val</tt> in <tt>x</tt>.
1259If <tt>val</tt> is not a standard
1260object (String, Hash, or List) it is assumed to be a <tt>char *</tt> in which
1261case it is used to construct a <tt>String</tt> that is stored in the list.
1262<tt>n</tt> must be in range.  Otherwise, an assertion will be raised.
1263</div>
1264
1265<p>
1266<b><tt>int *Delitem(List *x, int n)</tt></b>
1267</p>
1268
1269<div class="indent">
1270Deletes item <tt>n</tt> from the list, shifting items down if necessary.
1271To delete the last item in the list, use the special value <tt>DOH_END</tt>
1272for <tt>n</tt>.
1273</div>
1274
1275<p>
1276<b><tt>void Append(List *x, const Object_or_char *t)</tt></b>
1277</p>
1278
1279<div class="indent">
1280Appends <tt>t</tt> to the end of <tt>x</tt>.  If <tt>t</tt> is not
1281a standard object, it is assumed to be a <tt>char *</tt> and is
1282used to create a String object.
1283</div>
1284
1285<p>
1286<b><tt>void Insert(String *s, int pos, const Object_or_char *t)</tt></b>
1287</p>
1288
1289<div class="indent">
1290Inserts <tt>t</tt> into <tt>s</tt> at position <tt>pos</tt>.  The contents
1291of <tt>s</tt> are shifted accordingly.    The special value <tt>DOH_END</tt>
1292can be used for <tt>pos</tt> to indicate insertion at the end of the list (appending).
1293If <tt>t</tt> is not a standard object, it is assumed to be a <tt>char *</tt>
1294and is used to create a String object.
1295</div>
1296
1297<H3><a name="Extending_nn18"></a>38.5.4 Common operations</H3>
1298
1299
1300The following operations are applicable to all datatypes.
1301
1302<p>
1303<b><tt>Object *Copy(Object *x)</tt></b>
1304</p>
1305
1306<div class="indent">
1307Make a copy of the object <tt>x</tt>.
1308</div>
1309
1310<p>
1311<b><tt>void Delete(Object *x)</tt></b>
1312</p>
1313
1314<div class="indent">
1315Deletes <tt>x</tt>.
1316</div>
1317
1318<p>
1319<b><tt>void Setfile(Object *x, String_or_char *f)</tt></b>
1320</p>
1321
1322<div class="indent">
1323Sets the filename associated with <tt>x</tt>.  Used to track
1324objects and report errors.
1325</div>
1326
1327<p>
1328<b><tt>String *Getfile(Object *x)</tt></b>
1329</p>
1330
1331<div class="indent">
1332Gets the filename associated with <tt>x</tt>.
1333</div>
1334
1335<p>
1336<b><tt>void Setline(Object *x, int n)</tt></b>
1337</p>
1338
1339<div class="indent">
1340Sets the line number associated with <tt>x</tt>.  Used to track
1341objects and report errors.
1342</div>
1343
1344<p>
1345<b><tt>int Getline(Object *x)</tt></b>
1346</p>
1347
1348<div class="indent">
1349Gets the line number associated with <tt>x</tt>.
1350</div>
1351
1352<H3><a name="Extending_nn19"></a>38.5.5 Iterating over Lists and Hashes</H3>
1353
1354
1355To iterate over the elements of a list or a hash table, the following functions are used:
1356
1357<p>
1358<b><tt>Iterator First(Object *x)</tt></b>
1359</p>
1360
1361<div class="indent">
1362Returns an iterator object that points to the first item in a list or hash table.  The
1363<tt>item</tt> attribute of the Iterator object is a pointer to the item.  For hash tables, the <tt>key</tt> attribute
1364of the Iterator object additionally points to the corresponding Hash table key.  The <tt>item</tt> and <tt>key</tt> attributes
1365are NULL if the object contains no items or if there are no more items.
1366</div>
1367
1368<p>
1369<b><tt>Iterator Next(Iterator i)</tt></b>
1370</p>
1371
1372<div class="indent">
1373<p>Returns an iterator that points to the next item in a list or hash table.
1374
1375Here are two examples of iteration:</p>
1376
1377<div class="code">
1378<pre>
1379List *l = (some list);
1380Iterator i;
1381
1382for (i = First(l); i.item; i = Next(i)) {
1383    Printf(stdout,"%s\n", i.item);
1384}
1385
1386Hash *h = (some hash);
1387Iterator j;
1388
1389for (j = First(j); j.item; j= Next(j)) {
1390    Printf(stdout,"%s : %s\n", j.key, j.item);
1391}
1392</pre>
1393</div>
1394
1395</div>
1396
1397<H3><a name="Extending_nn20"></a>38.5.6 I/O</H3>
1398
1399
1400Special I/O functions are used for all internal I/O.  These operations
1401work on C <tt>FILE *</tt> objects, String objects, and special <tt>File</tt> objects
1402(which are merely a wrapper around <tt>FILE *</tt>).
1403
1404<p>
1405<b><tt>int Printf(String_or_FILE *f, const char *fmt, ...)</tt></b>
1406</p>
1407
1408<div class="indent">
1409Formatted I/O.   Same as the C <tt>fprintf()</tt> function except that output
1410can also be directed to a string object.  Note:  the <tt>%s</tt> format
1411specifier works with both strings and <tt>char *</tt>.  All other format
1412operators have the same meaning.
1413</div>
1414
1415<p>
1416<b><tt>int Printv(String_or_FILE *f, String_or_char *arg1,..., NULL)</tt></b>
1417</p>
1418
1419<div class="indent">
1420Prints a variable number of strings arguments to the output.  The last
1421argument to this function must be NULL.   The other arguments can either
1422be <tt>char *</tt> or string objects.
1423</div>
1424
1425<p>
1426<b><tt>int Putc(int ch, String_or_FILE *f)</tt></b>
1427</p>
1428
1429<div class="indent">
1430Same as the C <tt>fputc()</tt> function.
1431</div>
1432
1433<p>
1434<b><tt>int Write(String_or_FILE *f, void *buf, int len)</tt></b>
1435</p>
1436
1437<div class="indent">
1438Same as the C <tt>write()</tt> function.
1439</div>
1440
1441<p>
1442<b><tt>int Read(String_or_FILE *f, void *buf, int maxlen)</tt></b>
1443</p>
1444
1445<div class="indent">
1446Same as the C <tt>read()</tt> function.
1447</div>
1448
1449<p>
1450<b><tt>int Getc(String_or_FILE *f)</tt></b>
1451</p>
1452
1453<div class="indent">
1454Same as the C <tt>fgetc()</tt> function.
1455</div>
1456
1457<p>
1458<b><tt>int Ungetc(int ch, String_or_FILE *f)</tt></b>
1459</p>
1460
1461<div class="indent">
1462Same as the C <tt>ungetc()</tt> function.
1463</div>
1464
1465<p>
1466<b><tt>int Seek(String_or_FILE *f, int offset, int whence)</tt></b>
1467</p>
1468
1469<div class="indent">
1470Same as the C <tt>seek()</tt> function.  <tt>offset</tt> is the number
1471of bytes.  <tt>whence</tt> is one of <tt>SEEK_SET</tt>,<tt>SEEK_CUR</tt>,
1472or <tt>SEEK_END</tt>..
1473</div>
1474
1475<p>
1476<b><tt>long Tell(String_or_FILE *f)</tt></b>
1477</p>
1478
1479<div class="indent">
1480Same as the C <tt>tell()</tt> function.
1481</div>
1482
1483<p>
1484<b><tt>File *NewFile(const char *filename, const char *mode, List *newfiles)</tt></b>
1485</p>
1486
1487<div class="indent">
1488Create a File object using the <tt>fopen()</tt> library call.  This
1489file differs from <tt>FILE *</tt> in that it can be placed in the standard
1490SWIG containers (lists, hashes, etc.). The <tt>filename</tt> is added to the 
1491<tt>newfiles</tt> list if <tt>newfiles</tt> is non-zero and the file was created successfully.
1492</div>
1493
1494<p>
1495<b><tt>File *NewFileFromFile(FILE *f)</tt></b>
1496</p>
1497
1498<div class="indent">
1499Create a File object wrapper around an existing <tt>FILE *</tt> object.
1500</div>
1501
1502<p>
1503<b><tt>int Close(String_or_FILE *f)</tt></b>
1504</p>
1505
1506<div class="indent">
1507<p>Closes a file.  Has no effect on strings.</p>
1508
1509<p>
1510The use of the above I/O functions and strings play a critical role in SWIG.   It is
1511common to see small code fragments of code generated using code like this:
1512</p>
1513
1514<div class="code">
1515<pre>
1516/* Print into a string */
1517String *s = NewString("");
1518Printf(s,"Hello\n");
1519for (i = 0; i &lt; 10; i++) {
1520    Printf(s,"%d\n", i);
1521}
1522...
1523/* Print string into a file */
1524Printf(f, "%s\n", s);
1525</pre>
1526</div>
1527
1528<p>
1529Similarly, the preprocessor and parser all operate on string-files.
1530</p>
1531
1532</div>
1533
1534<H2><a name="Extending_nn21"></a>38.6 Navigating and manipulating parse trees</H2>
1535
1536
1537Parse trees are built as collections of hash tables.   Each node is a hash table in which
1538arbitrary attributes can be stored.  Certain attributes in the hash table provide links to
1539other parse tree nodes.   The following macros can be used to move around the parse tree.
1540
1541<p>
1542<b><tt>String *nodeType(Node *n)</tt></b>
1543</p>
1544
1545<div class="indent">
1546Returns the node type tag as a string.  The returned string indicates the type of parse
1547tree node.
1548</div>
1549
1550<p>
1551<b><tt>Node *nextSibling(Node *n)</tt></b>
1552</p>
1553
1554<div class="indent">
1555Returns the next node in the parse tree.  For example, the next C declaration.
1556</div>
1557
1558<p>
1559<b><tt>Node *previousSibling(Node *n)</tt></b>
1560</p>
1561
1562<div class="indent">
1563Returns the previous node in the parse tree.  For example, the previous C declaration.
1564</div>
1565
1566<p>
1567<b><tt>Node *firstChild(Node *n)</tt></b>
1568</p>
1569
1570<div class="indent">
1571Returns the first child node.  For example, if <tt>n</tt> was a C++ class node, this would
1572return the node for the first class member.
1573</div>
1574
1575<p>
1576<b><tt>Node *lastChild(Node *n)</tt></b>
1577</p>
1578
1579<div class="indent">
1580Returns the last child node.   You might use this if you wanted to append a new
1581node to the of a class.
1582</div>
1583
1584<p>
1585<b><tt>Node *parentNode(Node *n)</tt></b>
1586</p>
1587
1588<div class="indent">
1589Returns the parent of node <tt>n</tt>.  Use this to move up the pass tree.
1590</div>
1591
1592<p>
1593The following macros can be used to change all of the above attributes.
1594Normally, these functions are only used by the parser.  Changing them without
1595knowing what you are doing is likely to be dangerous.
1596</p>
1597
1598<p>
1599<b><tt>void set_nodeType(Node *n, const String_or_char)</tt></b>
1600</p>
1601
1602<div class="indent">
1603Change the node type.
1604tree node.
1605</div>
1606
1607<p>
1608<b><tt>void set_nextSibling(Node *n, Node *s)</tt></b>
1609</p>
1610
1611<div class="indent">
1612Set the next sibling.
1613</div>
1614
1615<p>
1616<b><tt>void set_previousSibling(Node *n, Node *s)</tt></b>
1617</p>
1618
1619<div class="indent">
1620Set the previous sibling.
1621</div>
1622
1623<p>
1624<b><tt>void set_firstChild(Node *n, Node *c)</tt></b>
1625</p>
1626
1627<div class="indent">
1628Set the first child node.
1629</div>
1630
1631<p>
1632<b><tt>void set_lastChild(Node *n, Node *c)</tt></b>
1633</p>
1634
1635<div class="indent">
1636Set the last child node.
1637</div>
1638
1639<p>
1640<b><tt>void set_parentNode(Node *n, Node *p)</tt></b>
1641</p>
1642
1643<div class="indent">
1644Set the parent node.
1645</div>
1646
1647<p>
1648The following utility functions are used to alter the parse tree (at your own risk)
1649</p>
1650
1651<p>
1652<b><tt>void appendChild(Node *parent, Node *child)</tt></b>
1653</p>
1654
1655<div class="indent">
1656Append a child to <tt>parent</tt>.  The appended node becomes the last child.
1657</div>
1658
1659<p>
1660<b><tt>void deleteNode(Node *node)</tt></b>
1661</p>
1662
1663<div class="indent">
1664Deletes a node from the parse tree.  Deletion reconnects siblings and properly updates
1665the parent so that sibling nodes are unaffected.
1666</div>
1667
1668<H2><a name="Extending_nn22"></a>38.7 Working with attributes</H2>
1669
1670
1671<p>
1672Since parse tree nodes are just hash tables, attributes are accessed using the <tt>Getattr()</tt>,
1673<tt>Setattr()</tt>, and <tt>Delattr()</tt> operations.  For example:
1674</p>
1675
1676<div class="code">
1677<pre>
1678int functionHandler(Node *n) {
1679    String *name    = Getattr(n,"name");
1680    String *symname = Getattr(n,"sym:name");
1681    SwigType *type  = Getattr(n,"type");
1682    ...
1683}
1684</pre>
1685</div>
1686
1687<p>
1688New attributes can be freely attached to a node as needed.   However, when new attributes
1689are attached during code generation, they should be prepended with a namespace prefix.
1690For example:
1691</p>
1692
1693<div class="code">
1694<pre>
1695...
1696Setattr(n,"python:docstring", doc);     /* Store docstring */
1697...
1698</pre>
1699</div>
1700
1701<p>
1702A quick way to check the value of an attribute is to use the <tt>checkAttribute()</tt> function like this:
1703</p>
1704
1705<div class="code">
1706<pre>
1707if (checkAttribute(n,"storage","virtual")) {
1708   /* n is virtual */
1709   ...
1710}
1711</pre>
1712</div>
1713
1714<p>
1715Changing the values of existing attributes is allowed and is sometimes done to implement
1716node transformations.   However, if a function/method modifies a node, it is required to restore
1717modified attributes to their original values.  To simplify the task of saving/restoring attributes,
1718the following functions are used:
1719</p>
1720
1721<p>
1722<b><tt>int Swig_save(const char *ns, Node *n, const char *name1, const char *name2, ..., NIL)</tt></b>
1723</p>
1724
1725<div class="indent">
1726Saves a copy of attributes <tt>name1</tt>, <tt>name2</tt>, etc. from node <tt>n</tt>.
1727Copies of the attributes are actually resaved in the node in a different namespace which is
1728set by the <tt>ns</tt> argument.   For example, if you call <tt>Swig_save("foo",n,"type",NIL)</tt>,
1729then the "type" attribute will be copied and saved as "foo:type".  The namespace name itself is stored in
1730the "view" attribute of the node.  If necessary, this can be examined to find out where previous
1731values of attributes might have been saved.
1732</div>
1733
1734<p>
1735<b><tt>int Swig_restore(Node *n)</tt></b>
1736</p>
1737
1738<div class="indent">
1739
1740<p>
1741Restores the attributes saved by the previous call to <tt>Swig_save()</tt>.  Those
1742attributes that were supplied to <tt>Swig_save()</tt> will be restored to their
1743original values.
1744</p>
1745
1746<p>
1747The <tt>Swig_save()</tt> and <tt>Swig_restore()</tt> functions must always be used as a pair.
1748That is, every call to <tt>Swig_save()</tt> must have a matching call to <tt>Swig_restore()</tt>.
1749Calls can be nested if necessary.  Here is an example that shows how the functions might be used:
1750</p>
1751
1752<div class="code">
1753<pre>
1754int variableHandler(Node *n) {
1755    Swig_save("variableHandler",n,"type","sym:name",NIL);
1756    String *symname = Getattr(n,"sym:name");
1757    SwigType *type  = Getattr(n,"type");
1758    ...
1759    Append(symname,"_global");         // Change symbol name
1760    SwigType_add_pointer(type);        // Add pointer
1761    ...
1762    generate wrappers
1763    ...
1764    Swig_restore(n);                  // Restore original values
1765    return SWIG_OK;
1766}
1767</pre>
1768</div>
1769
1770</div>
1771
1772<p>
1773<b><tt>int Swig_require(const char *ns, Node *n, const char *name1, const char *name2, ..., NIL)</tt></b>
1774</p>
1775
1776<div class="indent">
1777This is an enhanced version of <tt>Swig_save()</tt> that adds error checking.  If an attribute
1778name is not present in <tt>n</tt>, a failed assertion results and SWIG terminates with a fatal
1779error.  Optionally, if an attribute name is specified as "*<em>name</em>", a copy of the
1780attribute is saved as with <tt>Swig_save()</tt>.  If an attribute is specified as "?<em>name</em>",
1781the attribute is optional.   <tt>Swig_restore()</tt> must always be called after using this
1782function.
1783</div>
1784
1785<H2><a name="Extending_nn23"></a>38.8 Type system</H2>
1786
1787
1788<p>
1789SWIG implements the complete C++ type system including typedef, inheritance,
1790pointers, references, and pointers to members.   A detailed discussion of
1791type theory is impossible here.   However, let's cover the highlights.
1792</p>
1793
1794<H3><a name="Extending_nn24"></a>38.8.1 String encoding of types</H3>
1795
1796
1797<p>
1798All types in SWIG consist of a base datatype and a collection of type
1799operators that are applied to the base.   A base datatype is almost
1800always some kind of primitive type such as <tt>int</tt> or <tt>double</tt>.
1801The operators consist of things like pointers, references, arrays, and so forth.
1802Internally, types are represented as strings that are constructed in a very
1803precise manner.  Here are some examples:
1804</p>
1805
1806<div class="diagram">
1807<pre>
1808C datatype                     SWIG encoding (strings)
1809-----------------------------  --------------------------
1810int                            "int"
1811int *                          "p.int"
1812const int *                    "p.q(const).int"
1813int (*x)(int,double)           "p.f(int,double).int"
1814int [20][30]                   "a(20).a(30).int"
1815int (F::*)(int)                "m(F).f(int).int"
1816vector&lt;int&gt; *                  "p.vector&lt;(int)&gt;"
1817</pre>
1818</div>
1819
1820<p>
1821Reading the SWIG encoding is often easier than figuring out the C code---just
1822read it from left to right.  For a type of "p.f(int,double).int" is
1823a "pointer to a function(int,double) that returns int".
1824</p>
1825
1826<p>
1827The following operator encodings are used in type strings:
1828</p>
1829
1830<div class="diagram">
1831<pre>
1832Operator              Meaning
1833-------------------   -------------------------------
1834p.                    Pointer to
1835a(n).                 Array of dimension n
1836r.                    C++ reference
1837m(class).             Member pointer to class
1838f(args).              Function.
1839q(qlist).             Qualifiers
1840</pre>
1841</div>
1842
1843<p>
1844In addition, type names may be parameterized by templates.  This is
1845represented by enclosing the template parameters in <tt>&lt;(
1846... )&gt;</tt>.  Variable length arguments are represented by the
1847special base type of <tt>v(...)</tt>.
1848</p>
1849
1850<p>
1851If you want to experiment with type encodings, the raw type strings can
1852be inserted into an interface file using backticks `` wherever a type
1853is expected.  For instance, here is
1854an extremely perverted example:
1855</p>
1856
1857<div class="diagram">
1858<pre>
1859`p.a(10).p.f(int,p.f(int).int)` foo(int, int (*x)(int));
1860</pre>
1861</div>
1862
1863<p>
1864This corresponds to the immediately obvious C declaration:
1865</p>
1866
1867<div class="diagram">
1868<pre>
1869(*(*foo(int,int (*)(int)))[10])(int,int (*)(int));
1870</pre>
1871</div>
1872
1873<p>
1874Aside from the potential use of this declaration on a C programming quiz,
1875it motivates the use of the special SWIG encoding of types.   The SWIG
1876encoding is much easier to work with because types can be easily examined,
1877modified, and constructed using simple string operations (comparison,
1878substrings, concatenation, etc.).   For example, in the parser, a declaration
1879like this
1880</p>
1881
1882<div class="code">
1883<pre>
1884int *a[30];
1885</pre>
1886</div>
1887
1888<p>
1889is processed in a few pieces.  In this case, you have the base type
1890"<tt>int</tt>" and the declarator of type "<tt>a(30).p.</tt>".  To
1891make the final type, the two parts are just joined together using
1892string concatenation.
1893</p>
1894
1895<H3><a name="Extending_nn25"></a>38.8.2 Type construction</H3>
1896
1897
1898<p>
1899The following functions are used to construct types.  You should use
1900these functions instead of trying to build the type strings yourself.
1901</p>
1902
1903<p>
1904<b><tt>void SwigType_add_pointer(SwigType *ty)</tt></b>
1905</p>
1906
1907<div class="indent">
1908Adds a pointer to <tt>ty</tt>.
1909</div>
1910
1911<p>
1912<b><tt>void SwigType_del_pointer(SwigType *ty)</tt></b>
1913</p>
1914
1915<div class="indent">
1916Removes a single pointer from <tt>ty</tt>.
1917</div>
1918
1919<p>
1920<b><tt>void SwigType_add_reference(SwigType *ty)</tt></b>
1921</p>
1922
1923<div class="indent">
1924Adds a reference to <tt>ty</tt>.
1925</div>
1926
1927<p>
1928<b><tt>void SwigType_add_array(SwigType *ty, const String_or_char *size)</tt></b>
1929</p>
1930
1931<div class="indent">
1932Adds an array with dimension <tt>dim</tt> to <tt>ty</tt>.
1933</div>
1934
1935<p>
1936<b><tt>void SwigType_del_array(SwigType *ty)</tt></b>
1937</p>
1938
1939<div class="indent">
1940Removes a single array dimension from <tt>ty</tt>.
1941</div>
1942
1943<p>
1944<b><tt>int SwigType_array_ndim(SwigType *ty)</tt></b>
1945</p>
1946
1947<div class="indent">
1948Returns number of array dimensions of <tt>ty</tt>.
1949</div>
1950
1951<p>
1952<b><tt>String* SwigType_array_getdim(SwigType *ty,int n)</tt></b>
1953</p>
1954
1955<div class="indent">
1956Returns <tt>n</tt>th array dimension of <tt>ty</tt>.
1957</div>
1958
1959<p>
1960<b><tt>void SwigType_array_setdim(SwigType *ty, int n, const String_or_char *rep)</tt></b>
1961</p>
1962
1963<div class="indent">
1964Sets <tt>n</tt>th array dimensions of <tt>ty</tt> to <tt>rep</tt>.
1965</div>
1966
1967<p>
1968<b><tt>void SwigType_add_qualifier(SwigType *ty, const String_or_char *q)</tt></b>
1969</p>
1970
1971<div class="indent">
1972Adds a type qualifier <tt>q</tt> to <tt>ty</tt>.  <tt>q</tt> is typically
1973<tt>"const"</tt> or <tt>"volatile"</tt>.
1974</div>
1975
1976<p>
1977<b><tt>void SwigType_add_memberpointer(SwigType *ty, const String_or_char *cls)</tt></b>
1978</p>
1979
1980<div class="indent">
1981Adds a pointer to a member of class <tt>cls</tt> to <tt>ty</tt>.
1982</div>
1983
1984<p>
1985<b><tt>void SwigType_add_function(SwigType *ty, ParmList *p)</tt></b>
1986</p>
1987
1988<div class="indent">
1989Adds a function to <tt>ty</tt>.  <tt>p</tt> is a linked-list of parameter
1990nodes as generated by the parser. See the section on parameter lists
1991for details about the representation.
1992</div>
1993
1994<p>
1995<b><tt>void SwigType_add_template(SwigType *ty, ParmList *p)</tt></b>
1996</p>
1997
1998<div class="indent">
1999Adds a template to <tt>ty</tt>.  <tt>p</tt> is a linked-list of parameter
2000nodes as generated by the parser. See the section on parameter lists
2001for details about the representation.
2002</div>
2003
2004<p>
2005<b><tt>SwigType *SwigType_pop(SwigType *ty)</tt></b>
2006</p>
2007
2008<div class="indent">
2009Removes the last type constructor from <tt>ty</tt> and returns it.
2010<tt>ty</tt> is modified.
2011</div>
2012
2013<p>
2014<b><tt>void SwigType_push(SwigType *ty, SwigType *op)</tt></b>
2015</p>
2016
2017<div class="indent">
2018Pushes the type operators in <tt>op</tt> onto type <tt>ty</tt>.  The
2019opposite of <tt>SwigType_pop()</tt>.
2020</div>
2021
2022<p>
2023<b><tt>SwigType *SwigType_pop_arrays(SwigType *ty)</tt></b>
2024</p>
2025
2026<div class="indent">
2027Removes all leading array operators from <tt>ty</tt> and returns them.
2028<tt>ty</tt> is modified.   For example, if <tt>ty</tt> is <tt>"a(20).a(10).p.int"</tt>,
2029then this function would return <tt>"a(20).a(10)."</tt> and modify <tt>ty</tt>
2030so that it has the value <tt>"p.int"</tt>.
2031</div>
2032
2033<p>
2034<b><tt>SwigType *SwigType_pop_function(SwigType *ty)</tt></b>
2035</p>
2036
2037<div class="indent">
2038Removes a function operator from <tt>ty</tt> including any qualification.
2039<tt>ty</tt> is modified.   For example, if <tt>ty</tt> is <tt>"f(int).int"</tt>,
2040then this function would return <tt>"f(int)."</tt> and modify <tt>ty</tt>
2041so that it has the value <tt>"int"</tt>.
2042</div>
2043
2044<p>
2045<b><tt>SwigType *SwigType_base(SwigType *ty)</tt></b>
2046</p>
2047
2048<div class="indent">
2049Returns the base type of a type.  For example, if <tt>ty</tt> is
2050<tt>"p.a(20).int"</tt>, this function would return <tt>"int"</tt>.
2051<tt>ty</tt> is unmodified.
2052</div>
2053
2054<p>
2055<b><tt>SwigType *SwigType_prefix(SwigType *ty)</tt></b>
2056</p>
2057
2058<div class="indent">
2059Returns the prefix of a type. For example, if <tt>ty</tt> is
2060<tt>"p.a(20).int"</tt>, this function would return <tt>"p.a(20)."</tt>.
2061<tt>ty</tt> is unmodified.
2062</div>
2063
2064<H3><a name="Extending_nn26"></a>38.8.3 Type tests</H3>
2065
2066
2067<p>
2068The following functions can be used to test properties of a datatype.
2069</p>
2070
2071<p>
2072<b><tt>int SwigType_ispointer(SwigType *ty)</tt></b>
2073</p>
2074
2075<div class="indent">
2076Checks if <tt>ty</tt> is a standard pointer.
2077</div>
2078
2079<p>
2080<b><tt>int SwigType_ismemberpointer(SwigType *ty)</tt></b>
2081</p>
2082
2083<div class="indent">
2084Checks if <tt>ty</tt> is a member pointer.
2085</div>
2086
2087<p>
2088<b><tt>int SwigType_isreference(SwigType *ty)</tt></b>
2089</p>
2090
2091<div class="indent">
2092Checks if <tt>ty</tt> is a C++ reference.
2093</div>
2094
2095<p>
2096<b><tt>int SwigType_isarray(SwigType *ty)</tt></b>
2097</p>
2098
2099<div class="indent">
2100Checks if <tt>ty</tt> is an array.
2101</div>
2102
2103<p>
2104<b><tt>int SwigType_isfunction(SwigType *ty)</tt></b>
2105</p>
2106
2107<div class="indent">
2108Checks if <tt>ty</tt> is a function.
2109</div>
2110
2111<p>
2112<b><tt>int SwigType_isqualifier(SwigType *ty)</tt></b>
2113</p>
2114
2115<div class="indent">
2116Checks if <tt>ty</tt> is a qualifier.
2117</div>
2118
2119<p>
2120<b><tt>int SwigType_issimple(SwigType *ty)</tt></b>
2121</p>
2122
2123<div class="indent">
2124Checks if <tt>ty</tt> is a simple type.  No operators applied.
2125</div>
2126
2127<p>
2128<b><tt>int SwigType_isconst(SwigType *ty)</tt></b>
2129</p>
2130
2131<div class="indent">
2132Checks if <tt>ty</tt> is a const type.
2133</div>
2134
2135<p>
2136<b><tt>int SwigType_isvarargs(SwigType *ty)</tt></b>
2137</p>
2138
2139<div class="indent">
2140Checks if <tt>ty</tt> is a varargs type.
2141</div>
2142
2143<p>
2144<b><tt>int SwigType_istemplate(SwigType *ty)</tt></b>
2145</p>
2146
2147<div class="indent">
2148Checks if <tt>ty</tt> is a templatized type.
2149</div>
2150
2151<H3><a name="Extending_nn27"></a>38.8.4 Typedef and inheritance</H3>
2152
2153
2154<p>
2155The behavior of <tt>typedef</tt> declaration is to introduce a type alias.
2156For instance, <tt>typedef int Integer</tt> makes the identifier
2157<tt>Integer</tt> an alias for <tt>int</tt>.  The treatment of typedef in
2158SWIG is somewhat complicated due to the pattern matching rules that get applied
2159in typemaps and the fact that SWIG prefers to generate wrapper code
2160that closely matches the input to simplify debugging (a user will see the
2161typedef names used in their program instead of the low-level primitive C
2162datatypes).
2163</p>
2164
2165<p>
2166To handle <tt>typedef</tt>, SWIG builds a collection of trees containing typedef relations. For example,
2167</p>
2168
2169<div class="code">
2170<pre>
2171typedef int Integer;
2172typedef Integer *IntegerPtr;
2173typedef int Number;
2174typedef int Size;
2175</pre>
2176</div>
2177
2178<p>
2179produces two