PageRenderTime 50ms CodeModel.GetById 19ms app.highlight 20ms RepoModel.GetById 2ms app.codeStats 0ms

/trunk/Doc/Manual/Extending.html

#
HTML | 2179 lines | 1785 code | 392 blank | 2 comment | 0 complexity | 835424fbad01723b7c2524b7fd5b1ad7 MD5 | raw file

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

   1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2<html>
   3<head>
   4<title>Extending SWIG to support new languages</title>
   5<link rel="stylesheet" type="text/css" href="style.css">
   6</head>
   7
   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 *previousSibli…

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