From 4b468ea8a3e4e92e08b69b9dd218e111f44b41e9 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Sun, 23 Jul 2000 11:52:37 +0000 Subject: [PATCH] Move TOC up. Add cross-links like a madman. Quench insomnia. git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@594 626c5289-ae23-0410-ae9c-e8d60b6d4f22 --- Doc/internals.html | 114 +++++++++++++++++++++++++++++++++++---------- 1 file changed, 90 insertions(+), 24 deletions(-) diff --git a/Doc/internals.html b/Doc/internals.html index dfa8ed83f..292a5dc03 100644 --- a/Doc/internals.html +++ b/Doc/internals.html @@ -23,7 +23,50 @@ beazley@cs.uchicago.edu

(Note : This is a work in progress.) +

Table of Contents

+ + +

1. Introduction

+ This document details SWIG internals: architecture and sometimes implementation. The first few sections concentrate on data structures, @@ -35,7 +78,9 @@ The audience is assumed to be SWIG developers (who should also read the SWIG Engineering Manual before starting to code). -

Directory Guide

+ +

1.1 Directory Guide

+ @@ -141,7 +186,9 @@ are used in building the swig executable.
Doc
-

Overall Program Flow

+ +

1.2 Overall Program Flow

+ Here is the general control flow and where under subdir Source to look for code: @@ -185,22 +232,6 @@ which uses the callbacks registered by SWIG_main() above. -

Table of Contents

- -

2. DOH

 @@ -211,7 +242,9 @@ unofficially stands for "Dave's Object Hack", but it's also a good expletive to use when things don't work (as in "SWIG core dumped---DOH!"). +

2.1 Motivation and Background

+ The development of DOH is influenced heavily by the problems encountered during earlier attempts to create a C++ based version of @@ -245,7 +278,9 @@ extremely flexible and highly extensible. Also, in terms of coding, many of the newly DOH-based subsystems are less than half the size (in lines of code) of the earlier C++ implementation. +

2.2 Basic Types

+ The following built-in types are currently provided by DOH: @@ -290,7 +325,9 @@ It should be stressed that all of these names are merely symbolic aliases to the type DOH * and that no compile-time type checking is performed (of course, a runtime error may occur if you screw up). +

2.3 Creating, Copying, and Destroying Objects

+ The following functions can be used to create new DOH objects @@ -379,7 +416,9 @@ DohIncref(a); +

2.4 A Word About Mutability and Copying

+ All DOH objects are mutable regardless of their current reference count. For example, if you create a string and then create a 1000 @@ -389,7 +428,9 @@ make any kind of local change, you should first make a copy using the Copy() function. Caveat: when copying lists and hash tables, elements are copied by reference. +

2.5 Strings

+ The DOH String type is perhaps the most flexible object. First, it supports a variety of string-oriented operations. Second, it supports many of the same operations as lists. Finally, strings provide file I/O @@ -397,23 +438,33 @@ operations that allow them to be used interchangably with DOH file objects. [ TODO ] +

2.6 Lists

+ [ TODO ] +

2.7 Hash tables

+ [ TODO ] +

2.8 Files

+ [ TODO ] +

2.9 Void objects

+ [ TODO ] +

2.10 Utility functions

+ [ TODO ] @@ -806,16 +857,23 @@ for specifying local variable declarations and argument conversions.

10. Guile Support

+Revised: Thien-Thi Nguyen (July 23, 2000) + +

This section details guile-specific support in SWIG. -

Meaning of "Module"

+ +

10.1 Meaning of "Module"

+

There are three different concepts of "module" involved, defined separately for SWIG, Guile, and Libtool. To avoid horrible confusion, we explicitly prefix the context, e.g., "guile-module". -

Linkage

+ +

10.2 Linkage

+

Guile support is complicated by a lack of user community cohesiveness, @@ -868,14 +926,18 @@ There are no other linkage types planned, but that could change... To add a new type, add the name to the enum in guile.h and add the case to GUILE::emit_linkage(). -

Underscore Folding

+ +

10.3 Underscore Folding

+

Underscores are converted to dashes in identifiers. Guile support may grow an option to inhibit this folding in the future, but no one has complained so far. -

Typemaps

+ +

10.4 Typemaps

+

It used to be that the mappings for "native" types were included in @@ -891,7 +953,9 @@ processing the user's foo.i. At this time, we must say: in foo.i. This may change in the future. -

Smobs

+ +

10.5 Smobs

+

For pointer types, SWIG uses Guile smobs. This feature used to be @@ -942,7 +1006,9 @@ the type table and accessing the list of compatible types. If the Scheme object passed was not a SWIG smob representing a compatible pointer, a wrong-type-arg exception is raised. -

Exception Handling

+ +

10.6 Exception Handling

+

SWIG code calls scm_error on exception, using the following