jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update after running html tools in makefile

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@6139 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
William S Fulton 2004-08-24 22:21:18 +00:00
commit 229d40e0ee
11 changed files with 339 additions and 331 deletions
Download patch file Download diff file Expand all files Collapse all files

92
SWIG/Doc/Manual/Extending.html
View file

@ -5,7 +5,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Extending"></a>28 Extending SWIG</H1>
<H1><a name="Extending"></a>29 Extending SWIG</H1>
<!-- INDEX -->
<ul>
<li><a href="#Extending_nn2">Introduction</a>
@ -70,7 +70,7 @@
<b>Caution: This chapter is being rewritten! (11/25/01)</b>
<H2><a name="Extending_nn2"></a>28.1 Introduction</H2>
<H2><a name="Extending_nn2"></a>29.1 Introduction</H2>
<p>
@ -86,7 +86,7 @@ Also, this chapter is not meant to be a hand-holding tutorial. As a starting po
you should probably look at one of SWIG's existing modules.
</p>
<H2><a name="Extending_nn3"></a>28.2 Prerequisites</H2>
<H2><a name="Extending_nn3"></a>29.2 Prerequisites</H2>
<p>
@ -116,7 +116,7 @@ obvious, but almost all SWIG directives as well as the low-level generation of
wrapper code are driven by C++ datatypes.
</p>
<H2><a name="Extending_nn4"></a>28.3 The Big Picture</H2>
<H2><a name="Extending_nn4"></a>29.3 The Big Picture</H2>
SWIG is a special purpose compiler that parses C++ declarations to
@ -151,7 +151,7 @@ role in making the system work. For example, both typemaps and declaration anno
based on pattern matching and interact heavily with the underlying type system.
</p>
<H2><a name="Extending_nn5"></a>28.4 Execution Model</H2>
<H2><a name="Extending_nn5"></a>29.4 Execution Model</H2>
When you run SWIG on an interface, processing is handled in stages by a series of system components:
@ -194,7 +194,7 @@ stage of compilation.
The next few sections briefly describe some of these stages.
</p>
<H3><a name="Extending_nn6"></a>28.4.1 Preprocessing</H3>
<H3><a name="Extending_nn6"></a>29.4.1 Preprocessing</H3>
The preprocessor plays a critical role in the SWIG implementation. This is because a lot
@ -270,7 +270,7 @@ been expanded as well as everything else that goes into the low-level
construction of the wrapper code.
</p>
<H3><a name="Extending_nn7"></a>28.4.2 Parsing</H3>
<H3><a name="Extending_nn7"></a>29.4.2 Parsing</H3>
<p>
@ -368,7 +368,7 @@ interprets the above code as an abstract declarator for a function
returning a <tt>foo</tt> and taking types <tt>a</tt> and <tt>b</tt> as
arguments).
<H3><a name="Extending_nn8"></a>28.4.3 Parse Trees</H3>
<H3><a name="Extending_nn8"></a>29.4.3 Parse Trees</H3>
The SWIG parser produces a complete parse tree of the input file before any wrapper code
@ -618,7 +618,7 @@ $ swig -c++ -python -dump_tree example.i
</pre>
</blockquote>
<H3><a name="Extending_nn9"></a>28.4.4 Attribute namespaces</H3>
<H3><a name="Extending_nn9"></a>29.4.4 Attribute namespaces</H3>
<p>
@ -637,7 +637,7 @@ that matches the name of the target language. For example, <tt>python:foo</tt>
<tt>perl:foo</tt>.
</p>
<H3><a name="Extending_nn10"></a>28.4.5 Symbol Tables</H3>
<H3><a name="Extending_nn10"></a>29.4.5 Symbol Tables</H3>
During parsing, all symbols are managed in the space of the target
@ -717,7 +717,7 @@ example.i:5. Previous declaration is foo_i(int )
</pre>
</blockquote>
<H3><a name="Extending_nn11"></a>28.4.6 The %feature directive</H3>
<H3><a name="Extending_nn11"></a>29.4.6 The %feature directive</H3>
A number of SWIG directives such as <tt>%exception</tt> are implemented using the
@ -767,7 +767,7 @@ data stored in a feature attribute is usually just a raw unparsed string.
For example, the exception code above is simply
stored without any modifications.
<H3><a name="Extending_nn12"></a>28.4.7 Code Generation</H3>
<H3><a name="Extending_nn12"></a>29.4.7 Code Generation</H3>
<p>
@ -883,7 +883,7 @@ public :
The role of these functions is described shortly.
<H3><a name="Extending_nn13"></a>28.4.8 SWIG and XML</H3>
<H3><a name="Extending_nn13"></a>29.4.8 SWIG and XML</H3>
Much of SWIG's current parser design was originally motivated by
@ -894,7 +894,7 @@ by aspects of XML parsing. Therefore, in trying to understand SWIG's
internal data structures, it may be useful keep XML in the back of
your mind as a model.
<H2><a name="Extending_nn14"></a>28.5 Primitive Data Structures</H2>
<H2><a name="Extending_nn14"></a>29.5 Primitive Data Structures</H2>
<p>
@ -938,7 +938,7 @@ typedef Hash Typetab;
</pre>
</blockquote>
<H3><a name="Extending_nn15"></a>28.5.1 Strings</H3>
<H3><a name="Extending_nn15"></a>29.5.1 Strings</H3>
<p>
@ -1077,7 +1077,7 @@ Returns the number of replacements made (if any).
</blockquote>
<H3><a name="Extending_nn16"></a>28.5.2 Hashes</H3>
<H3><a name="Extending_nn16"></a>29.5.2 Hashes</H3>
<p>
@ -1154,7 +1154,7 @@ Returns the list of hash table keys.
</blockquote>
<H3><a name="Extending_nn17"></a>28.5.3 Lists</H3>
<H3><a name="Extending_nn17"></a>29.5.3 Lists</H3>
<p>
@ -1243,7 +1243,7 @@ If <tt>t</tt> is not a standard object, it is assumed to be a <tt>char *</tt>
and is used to create a String object.
</blockquote>
<H3><a name="Extending_nn18"></a>28.5.4 Common operations</H3>
<H3><a name="Extending_nn18"></a>29.5.4 Common operations</H3>
The following operations are applicable to all datatypes.
@ -1298,7 +1298,7 @@ objects and report errors.
Gets the line number associated with <tt>x</tt>.
</blockquote>
<H3><a name="Extending_nn19"></a>28.5.5 Iterating over Lists and Hashes</H3>
<H3><a name="Extending_nn19"></a>29.5.5 Iterating over Lists and Hashes</H3>
To iterate over the elements of a list or a hash table, the following functions are used:
@ -1342,7 +1342,7 @@ for (j = First(j); j.item; j= Next(j)) {
</pre>
</blockquote>
<H3><a name="Extending_nn20"></a>28.5.6 I/O</H3>
<H3><a name="Extending_nn20"></a>29.5.6 I/O</H3>
Special I/O functions are used for all internal I/O. These operations
@ -1473,7 +1473,7 @@ Printf(f, "%s\n", s);
Similarly, the preprocessor and parser all operate on string-files.
<H2><a name="Extending_nn21"></a>28.6 Navigating and manipulating parse trees</H2>
<H2><a name="Extending_nn21"></a>29.6 Navigating and manipulating parse trees</H2>
Parse trees are built as collections of hash tables. Each node is a hash table in which
@ -1603,7 +1603,7 @@ Deletes a node from the parse tree. Deletion reconnects siblings and properly u
the parent so that sibling nodes are unaffected.
</blockquote>
<H2><a name="Extending_nn22"></a>28.7 Working with attributes</H2>
<H2><a name="Extending_nn22"></a>29.7 Working with attributes</H2>
Since parse tree nodes are just hash tables, attributes are accessed using the <tt>Getattr()</tt>,
@ -1710,14 +1710,14 @@ the attribute is optional. <tt>Swig_restore()</tt> must always be called after
function.
</blockquote>
<H2><a name="Extending_nn23"></a>28.8 Type system</H2>
<H2><a name="Extending_nn23"></a>29.8 Type system</H2>
SWIG implements the complete C++ type system including typedef, inheritance,
pointers, references, and pointers to members. A detailed discussion of
type theory is impossible here. However, let's cover the highlights.
<H3><a name="Extending_nn24"></a>28.8.1 String encoding of types</H3>
<H3><a name="Extending_nn24"></a>29.8.1 String encoding of types</H3>
<p>
@ -1810,7 +1810,7 @@ is processed in a few pieces. In this case, you have the base type
make the final type, the two parts are just joined together using
string concatenation.
<H3><a name="Extending_nn25"></a>28.8.2 Type construction</H3>
<H3><a name="Extending_nn25"></a>29.8.2 Type construction</H3>
The following functions are used to construct types. You should use
@ -1945,7 +1945,7 @@ Returns the prefix of a type. For example, if <tt>ty</tt> is
<tt>ty</tt> is unmodified.
</blockquote>
<H3><a name="Extending_nn26"></a>28.8.3 Type tests</H3>
<H3><a name="Extending_nn26"></a>29.8.3 Type tests</H3>
The following functions can be used to test properties of a datatype.
@ -2030,7 +2030,7 @@ Checks if <tt>ty</tt> is a varargs type.
Checks if <tt>ty</tt> is a templatized type.
</blockquote>
<H3><a name="Extending_nn27"></a>28.8.4 Typedef and inheritance</H3>
<H3><a name="Extending_nn27"></a>29.8.4 Typedef and inheritance</H3>
The behavior of <tt>typedef</tt> declaration is to introduce a type alias.
@ -2122,7 +2122,7 @@ Fully reduces <tt>ty</tt> according to typedef rules. Resulting datatype
will consist only of primitive typenames.
</blockquote>
<H3><a name="Extending_nn28"></a>28.8.5 Lvalues</H3>
<H3><a name="Extending_nn28"></a>29.8.5 Lvalues</H3>
When generating wrapper code, it is necessary to emit datatypes that can
@ -2155,7 +2155,7 @@ Literal y; // type = 'Literal', ltype='p.char'
</pre>
</blockquote>
<H3><a name="Extending_nn29"></a>28.8.6 Output functions</H3>
<H3><a name="Extending_nn29"></a>29.8.6 Output functions</H3>
The following functions produce strings that are suitable for output.
@ -2215,7 +2215,7 @@ SWIG, but is most commonly associated with type-descriptor objects
that appear in wrappers (e.g., <tt>SWIGTYPE_p_double</tt>).
</blockquote>
<H2><a name="Extending_nn30"></a>28.9 Parameters</H2>
<H2><a name="Extending_nn30"></a>29.9 Parameters</H2>
Several type-related functions involve parameter lists. These include
@ -2310,7 +2310,7 @@ included. Used to emit prototypes.
Returns the number of required (non-optional) arguments in <tt>p</tt>.
</blockquote>
<H2><a name="Extending_nn31"></a>28.10 Writing a Language Module</H2>
<H2><a name="Extending_nn31"></a>29.10 Writing a Language Module</H2>
This section briefly outlines the steps needed to create a bare-bones
@ -2319,7 +2319,7 @@ of existing modules. Since the code is relatively easy to read, this section
describes the creation of a minimal Python module. You should be able to extrapolate
this to other languages.
<H3><a name="Extending_nn32"></a>28.10.1 Execution model</H3>
<H3><a name="Extending_nn32"></a>29.10.1 Execution model</H3>
Code generation modules are defined by inheriting from the <tt>Language</tt> class,
@ -2327,7 +2327,7 @@ currently defined in the <tt>Source/Modules1.1</tt> directory of SWIG. Starting
the parsing of command line options, all aspects of code generation are controlled by
different methods of the <tt>Language</tt> that must be defined by your module.
<H3><a name="Extending_nn33"></a>28.10.2 Starting out</H3>
<H3><a name="Extending_nn33"></a>29.10.2 Starting out</H3>
To define a new language module, first create a minimal implementation using
@ -2430,7 +2430,7 @@ Once it finishes compiling, try running SWIG with the command-line option
that activates your module. For example, <tt>swig -python foo.i</tt>. The
messages from your new module should appear.
<H3><a name="Extending_nn34"></a>28.10.3 Command line options</H3>
<H3><a name="Extending_nn34"></a>29.10.3 Command line options</H3>
When SWIG starts, the command line options are passed to your language module. This occurs
@ -2487,7 +2487,7 @@ to mark the option as valid. If you forget to do this, SWIG will terminate wit
unrecognized command line option error.
</p>
<H3><a name="Extending_nn35"></a>28.10.4 Configuration and preprocessing</H3>
<H3><a name="Extending_nn35"></a>29.10.4 Configuration and preprocessing</H3>
<p>
@ -2536,7 +2536,7 @@ an implementation file <tt>python.cxx</tt> and a configuration file
<tt>python.swg</tt>.
</p>
<H3><a name="Extending_nn36"></a>28.10.5 Entry point to code generation</H3>
<H3><a name="Extending_nn36"></a>29.10.5 Entry point to code generation</H3>
<p>
@ -2594,13 +2594,13 @@ int Python::top(Node *n) {
</pre>
</blockquote>
<H3><a name="Extending_nn37"></a>28.10.6 Module I/O and wrapper skeleton</H3>
<H3><a name="Extending_nn37"></a>29.10.6 Module I/O and wrapper skeleton</H3>
<H3><a name="Extending_nn38"></a>28.10.7 Low-level code generators</H3>
<H3><a name="Extending_nn38"></a>29.10.7 Low-level code generators</H3>
<H3><a name="Extending_nn39"></a>28.10.8 Configuration files</H3>
<H3><a name="Extending_nn39"></a>29.10.8 Configuration files</H3>
<!-- please report bugs in this section to ttn -->
@ -2748,7 +2748,7 @@ to handle some of these configuration tasks, but that point is now
long past. If you are interested in working on that, feel free to
raise the issue in the context of a next-generation clean-slate SWIG.
<H3><a name="Extending_nn40"></a>28.10.9 Runtime support</H3>
<H3><a name="Extending_nn40"></a>29.10.9 Runtime support</H3>
<p>
@ -2757,7 +2757,7 @@ Discuss the kinds of functions typically needed for SWIG runtime support (e.g.
the SWIG files that implement those functions.
</p>
<H3><a name="Extending_nn41"></a>28.10.10 Standard library files</H3>
<H3><a name="Extending_nn41"></a>29.10.10 Standard library files</H3>
<p>
@ -2771,7 +2771,7 @@ Discuss the standard library files that most language modules provide, e.g.
<li> stl.i </li>
</ul>
<H3><a name="Extending_nn42"></a>28.10.11 Examples and test cases</H3>
<H3><a name="Extending_nn42"></a>29.10.11 Examples and test cases</H3>
<p>
@ -2798,7 +2798,7 @@ during this process, see the section on <a href="#n37a">configuration
files</a>.
</p>
<H3><a name="Extending_nn43"></a>28.10.12 Documentation</H3>
<H3><a name="Extending_nn43"></a>29.10.12 Documentation</H3>
<p>
@ -2830,13 +2830,13 @@ Some topics that you'll want to be sure to address include:
if available.
</ul>
<H2><a name="Extending_nn44"></a>28.11 Typemaps</H2>
<H2><a name="Extending_nn44"></a>29.11 Typemaps</H2>
<H3><a name="Extending_nn45"></a>28.11.1 Proxy classes</H3>
<H3><a name="Extending_nn45"></a>29.11.1 Proxy classes</H3>
<H2><a name="Extending_nn46"></a>28.12 Guide to parse tree nodes</H2>
<H2><a name="Extending_nn46"></a>29.12 Guide to parse tree nodes</H2>
<p>