/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&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 <n></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 <n></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 <n></tt> or <tt>debug-module <n></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 <-- 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 <-- Added parameter 879storage : virtual 880wrap:action : result = (arg1)->bar(arg2) <-- Action code added 881sym:name : Foo_bar <-- 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 < 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