bgirgis/cpp-thirdparty
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Bassem Girgis
2018-12-20 17:34:07 -06:00
parent 7a2d899662
commit 81b4b9e273
34743 changed files with 5940233 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
winx64/bin/swig-3.0.12/Doc/Devel/cmdopt.html Normal file
View File

@@ -0,0 +1,79 @@
<html>
<head>
<title>SWIG Command Line Handling</title>
</head>
<body>
<center>
<h1>SWIG Command Line Handling</h1>
<p>
David M. Beazley <br>
dave-swig@dabeaz.com<br>
December, 2006<br>
</b>
</center>
<h2>Introduction</h2>
This document describes the functions related to the handling of
command line options passed to SWIG. These functions are defined in
the header file <tt>Source/Swig/swigopt.h</tt>. This API is
considered to be stable.
<h2>Initialization</h2>
Upon SWIG startup, the following function is called:
<p>
<b><tt>void Swig_init_args(int argc, char **argv_)</tt></b>
<blockquote>
Registers command line options with the SWIG core. This creates an internal array that is used by other
functions to mark whether or not a particular command line option was used. This is ultimately used to issue error messages about unused or unknown command line options. This function is currently invoked in the SWIG main() function that is found in <tt>Source/Modules/swigmain.cxx</tt>.
</blockquote>
<h2>Argument Marking</h2>
As command line options are processed by language modules, the following functions are used
to mark the arguments as used:
<p>
<b><tt>void Swig_mark_arg(int n)</tt></b>
<blockquote>
Mark argument number <tt>n</tt> as used.
</blockquote>
<p>
<b><tt>int Swig_check_marked(int n)</tt></b>
<blockquote>
Check to see if argument <tt>n</tt> has been marked. Returns 0 or 1.
</blockquote>
<h2>Argument Checking</h2>
The following function is used to check all of the command line options after parsing. It looks at the marked list
and issues an error message if any unconsumed arguments are found.
<p>
<b><tt>void Swig_check_options()</tt></b>
<blockquote>
Checks all command line options to see if they have all been processed. If not, an error message is generated and
execution terminates with a call to <tt>exit()</tt>. This function is currently invoked in <tt>Source/Modules/main.cxx</tt> just before SWIG starts any processing of input files.
</blockquote>
<h2>Utility Function</h2>
<p>
<b><tt>void Swig_arg_error())</tt></b>
<blockquote>
A generic function that issues an error message about being unable to parse command line options. SWIG is terminated by a call to <tt>exit()</tt>.
</body>
</html>

404
winx64/bin/swig-3.0.12/Doc/Devel/engineering.html Normal file
View File

@@ -0,0 +1,404 @@
<html>
<head>
<title>SWIG Engineering Manual</title>
</head>
<body bgcolor="#ffffff">
<center>
<h1>SWIG Engineering Manual</h1>
<b>David Beazley <br>
</b>
</center>
<p>
(Note : This is a work in progress.)
<h2>Table of Contents</h2>
<ul>
<li><a name="i1" href="#1">1. Introduction</a>
<li><a name="i2" href="#2">2. Programming Languages and Libraries</a>
<li><a name="i3" href="#3">3. The Source Directory and Module Names</a>
<li><a name="i4" href="#4">4. Include Files</a>
<li><a name="i5" href="#5">5. File Structure</a>
<li><a name="i6" href="#6">6. Bottom-Up Design</a>
<li><a name="i7" href="#7">7. Functions</a>
<li><a name="i8" href="#8">8. Naming Conventions</a>
<li><a name="i9" href="#9">9. Visibility</a>
<li><a name="i10" href="#10">10. Miscellaneous Coding Guidelines</a>
<li><a name="i11" href="#11">11. Git Tagging Conventions</a>
</ul>
<a name="1" href="#i1">
<h2>1. Introduction</h2>
</a>
The purpose of this document is to describe various coding conventions
and organizational aspects for SWIG developers. The idea for this
document is largely borrowed from John Ousterhout's Tcl/Tk Engineering
Manual. It is not my intent to overly managerial about matters--rather I'm
hoping to make life a little less chaotic for everyone.
<p>
First a little background: SWIG was started in 1995 as a one-person
project and continued in this mode of operation until about 1998.
Most of this development was driven by ideas submitted by early SWIG
users as opposed to being motivated by a grand design. As a result,
the code ended up being a pretty horrible C++ coding disaster. A
mostly working disaster perhaps, but a disaster nonetheless.
<p>
With that said, the primary goal of future SWIG development is to
reengineer the original system, fix most of its inherent design flaws,
and to produce what I hope will become a highly extensible and modular
interface compiler framework. To this do this, there are a few
critical areas of work. First, I want to restructure SWIG as a
collection of loosely coupled modules written in either ANSI C or an
scripting language. Second, I want the system to be minimalistic in
its use of data structures and interconnections. The primary reason
for this is that the fewer data structures there are, the less users
will have to remember. This will also make the system more accessible
to non-experts. Finally, I want to reevaluate the whole idea of a
SWIG module is and expand the definition to include just about
anything from parsers, preprocessors, optimizers, interface editors,
and code generators.
<p>
The rest of this document outlines a few general rules of how code
should be developed within the SWIG project. These rules are
primarily drawn from my own experience developing software and
observing the practices of other successful projects.
<a name="2" href="#i2">
<h2>2. Programming Languages and Libraries </h2>
</a>
All SWIG modules must be written in either ANSI C or one of the
scripting languages for which SWIG can generate an interface (e.g.,
Perl, Python, or Tcl). C++ is currently being used to write
SWIG modules, but it is only being utilized to avoid working with
a lot of pointers to functions. <b>Advanced C++ features like namespaces, templates,
and overloading should not be used.</b>.
<p>
Module writers should make every attempt to use only those functions
described in the POSIX.1 standard. This includes most of the
functions contained the Kernighan and Ritchie C programming book. Use
of operating system dependent functionality such as socket libraries
should always be included inside a conditional compilation block so
that it can be omitted on problematic platforms. If you are unsure
about a library call, check the man page or contact Dave.
<a name="3" href="#i3">
<h2>3. The Source Directory and Module Names</h2>
</a>
All SWIG modules are contained within the "Source" directory. Within
this directory, each module is placed into its own subdirectory. The
name of this subdirectory should exactly match the name of the module.
For example, if you are creating a module called "Tcl", all of your
files should be placed in a directory "Tcl".
<p>
When choosing a module name, please pick a name that is not
currently in use. As a general convention, the first letter of a
module name is capitalized such as "Perl". Alternatives such as
"perl" or "PERL" should be avoided. In certain instances, the first
two letters may be capitalized as in "CParse." The exact usage of
this is somewhat inconsistent and isn't terribly important--just make
sure the first letter is capitalized. Also, module names should not
start with numbers, include underscores or any other special
non-alphanumeric characters.
<a name="5" href="#i5">
<h2>5. File Structure </h2>
</a>
Each file in a module should be given a filename that is all lowercase letters
such as "parser.c", not "Parser.c" or "PARSER.c". Please note that filenames
are case-insensitive on Windows so this convention will prevent you from inadvertently
creating two files that differ in case-only.
<p>
Each file should include a short abstract and license information
like this:
<blockquote>
<pre>
/* -----------------------------------------------------------------------------
* This file is part of SWIG, which is licensed as a whole under version 3
* (or any later version) of the GNU General Public License. Some additional
* terms also apply to certain portions of SWIG. The full details of the SWIG
* license and copyrights can be found in the LICENSE and COPYRIGHT files
* included with the SWIG source code as distributed by the SWIG developers
* and at http://www.swig.org/legal.html.
*
* xxx.c
*
* This file defines ...
* ----------------------------------------------------------------------------- */
#include "swig.h"
/* Declarations */
typedef struct {
int x, y;
} Foo;
...
/* Private Declarations (used only in this file) */
static int avariable;
...
/* Functions */
...
</pre>
</blockquote>
<p>
As a general rule, files start to get unmanageable once they exceed
about 2000 lines. Files larger than this should be broken up into
multiple files. Similarly, you should avoid the temptation to create
many small files as this increases compilation time and makes the
directory structure too complicated.
<a name="6" href="#i6">
<h2>6. Bottom-Up Design </h2>
</a>
Within each source file, the preferred organization is to use what is
known as "bottom-up" design. Under this scheme, lower-level functions
appear first and the highest level function appears last. The easy
way to remember is that the "main" function of your module should
always appear last in the source file. For example:
<blockquote>
<pre>
/* Simple bottom-up program */
#include &lt;stdio.h&gt;
int foo(int x, int y) {
/* Implement foo */
...
}
int bar() {
...
foo(i,j);
...
}
...
int main(int argc, char **argv) {
...
bar();
...
}
</pre>
</blockquote>
This choice of design is somewhat arbitrary however it has a number of
benefits particular to C. In particular, a bottom-up design generally
eliminates the need to include forward references--resulting in
cleaner code and fewer compilation errors.
<a name="7" href="#i7">
<h2>7. Functions</h2>
</a>
All functions should have a function header that gives the function name
and a short description like this:
<blockquote>
<pre>
/* -------------------------------------------------------------------------
* Swig_add_directory()
*
* Adds a directory to the SWIG search path.
* ------------------------------------------------------------------------- */
void
Swig_add_directory(DOH *dirname) {
...
}
</pre>
</blockquote>
In the function declaration, the return type and any specifiers
(extern or static) should appear on a separate line followed by the
function name and arguments as shown above. The left curly brace
should appear on the same line as the function name.
<p>
Function declarations should <b>NOT</b> use the pre-ANSI function
declaration syntax. The ANSI standard has been around long enough for
this to be a non-issue.
<a name="8" href="#i8">
<h2>8. Naming Conventions</h2>
</a>
The following conventions are used to name various objects throughout SWIG.
<h4>Functions</h4>
Functions should consist of the module name and the function name separated by an underscore like this:
<blockquote>
<pre>
Preprocessor_define()
Swig_add_directory()
</pre>
</blockquote>
In general, the module name should match the name of the module
subdirectory and the function name should be in all lowercase with
words separated by underscores.
<h4>Structures and Types</h4>
If your module defines new structures, the structure name should include the name of the
module and the name of the structure appended together like this:
<blockquote>
<pre>
typedef struct SwigScanner {
...
} SwigScanner;
typedef struct LParseType {
...
} LParseType;
</pre>
</blockquote>
In this case, both the name of the module and the type should be capitalized. Also, whenever
possible, you should use the "typedef struct Name { ... } Name" form when defining new
data structures.
<h4>Global Variables</h4>
Global variables should be avoided if at all possible. However, if you must use a global
variable, please prepend the module name and use the same naming scheme as for functions.
<h4>Constants</h4>
Constants should be created using #define and should be in all caps like this:
<blockquote>
<pre>
#define SWIG_TOKEN_LPAREN 1
</pre>
</blockquote>
Separate words in a constant should be separated by underscores as with functions.
<h4>Structure members</h4>
Structure members should be in all lower-case and follow the same word-separation convention
as for function names. However, the module name does not have to be included.
For example:
<blockquote>
<pre>
typedef struct SwigScanner {
DOH *text; /* Current token value */
DOH *scanobjs; /* Objects being scanned */
DOH *str; /* Current object being scanned */
char *idstart; /* Optional identifier start characters */
int next_token; /* Next token to be returned */
int start_line; /* Starting line of certain declarations */
int yylen; /* Length of text pushed into text */
DOH *file; /* Current file name */
} SwigScanner;
</pre>
</blockquote>
<h4>Static Functions and Variables </h4>
Static declarations are free to use any naming convention that is appropriate. However, most
existing parts of SWIG use lower-case names and follow the same convention as described for functions.
<a name="9" href="#i9">
<h2>9. Visibility</h2>
</a>
Modules should keep the following rules in mind when exposing their internals:
<ul>
<li>Only publicly accessible functions should be included in the module header file.
<li>All non-static declarations must be prepended with some form of the module name
to avoid potential linker namespace conflicts with other modules.
<li>Modules should not expose global variables or use global variables in their
public interface.
<li>Similarly, modules should discourage the direct manipulation of data contained
within data structures in favor of using function calls instead. For example,
instead of providing a user with a structure like this:
<blockquote>
<pre>
typedef struct Foo {
int line;
} Foo;
</pre>
</blockquote>
It is better to hide the implementation of Foo and provide an
function-call interface like this:
<blockquote>
<pre>
typedef struct Foo Foo;
extern int Foo_getline(Foo *f);
extern void Foo_setline(Foo *f, int line);
</pre>
</blockquote>
Although this results in worse performance, there are many practical
reasons for doing this. The most important reason is that it allows
you to change the internal representation of Foo without breaking all
of the other modules or having to recompile the entire universe after
making your changes.
</ul>
<a name="10" href="#i10">
<h2>10. Miscellaneous Coding Guidelines</h2>
</a>
These are largely covered in the main documentation in the Extending.html file.
<a name="11" href="#i11">
<h2>11. Git Tagging Conventions</h2>
</a>
Use <tt>git tag</tt> to declare some set of file revisions as related in some
symbolic way. This eases reference, retrieval and manipulation of these files
later. At the moment (2001/01/16 14:02:53), the conventions are very simple;
let's hope they stay that way!
<p>
There are two types of tags, internal (aka personal) and external.
Internal tags are used by SWIG developers primarily, whereas external
tags are used when communicating with people w/ anonymous git access.
<ul>
<li> Internal tags should start with the developer name and a hyphen.
<li> External tags should start with "rel-".
</ul>
That's all there is to it. Some example tags:
<ul>
<li> ttn-pre-xml-patch
<li> ttn-post-xml-patch
<li> ttn-going-on-vacation-so-dutifully-tagging-now
<li> rel-1.3.40
<li> rel-2.0.9
</ul>
<hr>
Copyright (C) 1999-2004 SWIG Development Team.
</body>
</html>

181
winx64/bin/swig-3.0.12/Doc/Devel/file.html Normal file
View File

@@ -0,0 +1,181 @@
<html>
<head>
<title>SWIG File Handling</title>
</head>
<body>
<center>
<h1>SWIG File Handling</h1>
<p>
David M. Beazley <br>
dave-swig@dabeaz.com<br>
December, 2006<br>
</b>
</center>
<h2>Introduction</h2>
This document describes the functions related to file and filename handling in the SWIG core. These functions are
defined in the header file <tt>Source/Swig/swigfile.h</tt>. This API is considered to be stable.
<h2>File Search Path</h2>
These functions manipulate the search path for locating files.
<p>
<b><tt>List *Swig_add_directory(const String_or_char *dirname)</tt></b>
<blockquote>
Adds a new directory to the system search path. The directory is appended to
the end of the search path. Returns a list containing the current
system search path.
</blockquote>
<p>
<b><tt>void Swig_push_directory(const String_or_char *dirname)</tt></b>
<blockquote>
Pushes a temporary directory onto the search path. This directory is searched before
directories added with <tt>Swig_add_directory()</tt> except when including a system
file explicitly (either using #include &lt;file&gt; or calling <tt>Swig_include_sys()</tt>).
This function is normally used by the preprocessor to add temporary directories when
processing #include statements.
</blockquote>
<p>
<b><tt>void Swig_pop_directory()</tt></b>
<blockquote>
Pops off the last pushed directory with <tt>Swig_push_directory()</tt>
</blockquote>
<p>
<b><tt>int Swig_get_push_dir()</tt></b>
<blockquote>
Returns a flag that indicates whether directory pushing is enabled or not.
</blockquote>
<p>
<b><tt>void Swig_set_push_dir(int dopush)</tt></b>
<blockquote>
Enables or disables directory pushing. By default, it is turned on. However, the <tt>-I-</tt> command line
option to SWIG disables it.
</blockquote>
<p>
<b><tt>List *Swig_search_path()</tt></b>
<blockquote>
Returns the current search path.
</blockquote>
<h2>File access functions</h2>
<p>
<b><tt>FILE *Swig_open(const String_or_char *name)</tt></b>
<blockquote>
Opens a file, using the applicable search paths, and returns an open <tt>FILE *</tt> object if found. Returns NULL if the file is not found.
</blockquote>
<p>
<b><tt>String *Swig_read_file(FILE *f)</tt></b>
<blockquote>
Reads all of the data from an open file into a string which is returned.
</blockquote>
<p>
<b><tt>String *Swig_include(const String_or_char *name)</tt></b>
<blockquote>
Searches for an include file <tt>name</tt> and returns its contents as
a string if found. Returns NULL if not found. All of the applicable
search paths are searched when trying to locate the file.
</blockquote>
<p>
<b><tt>String *Swig_include_sys(const String_or_char *name)</tt></b>
<blockquote>
Searches for an include file <tt>name</tt> and returns its contents as
a string if found. Returns NULL if not found. All of the applicable
search paths are searched when trying to locate the file, but
preference is given to system paths first. This mimics the behavior
of <tt>#include &lt;file&gt;</tt> in the preprocessor.
</blockquote>
<p>
<b><tt>int Swig_insert_file(const String_or_char *name, File *outfile)</tt></b>
<blockquote>
Searches for a file <tt>name</tt> and dumps its contents to <tt>outfile</tt> if found.
Returns 0 on success, -1 if the file couldn't be found.
</blockquote>
<h2>Query functions</h2>
<p>
<b><tt>String *Swig_last_file()</tt></b>
<blockquote>
Returns the full pathname of the file last opened or included.
</blockquote>
<h2>Named files</h2>
<p>
<b><tt>void *Swig_register_filebyname(const String_or_char *filename, File *outfile)</tt></b>
<blockquote>
Registers a file object <tt>outfile</tt> with a specific name <tt>filename</tt>. This function is
used to implement the SWIG %insert directive and to manage different sections of the output
file such as "runtime","header","wrapper","init", etc. Different language modules may add their own
sections for generating Python code, Perl code, etc.
</blockquote>
<p>
<b><tt>File *Swig_filebyname(const String_or_char *filename)</tt></b>
<blockquote>
This looks up a file object previously registered using <tt>Swig_register_filebyname()</tt>. This
is used to implement the %insert directive.
</blockquote>
<h2>Filename utilities</h2>
<p>
<b><tt>char *Swig_file_suffix(const String_or_char *filename)</tt></b>
<blockquote>
Returns the suffix of a filename. For instance, if the filename is "foo.txt", it returns ".txt".
</blockquote>
<p>
<b><tt>char *Swig_file_basename(const String_or_char *filename)</tt></b>
<blockquote>
Returns the filename without the suffix attached to it. For instance, if the filename is "foo.txt", it returns
"foo". The result is stored in a static variable. If you need to save it, make your own copy.
</blockquote>
<p>
<b><tt>char *Swig_file_filename(const String_or_char *filename)</tt></b>
<blockquote>
Returns the filename without any leading directories. For instance, if the filename is "/bar/spam/foo.txt", it
returns "foo.txt". This function is aware of local naming conventions on the machine (e.g., forward versus back slashes on Unix and Windows). The result is stored in a static variable. If you need to save the value, make a copy.
</blockquote>
<p>
<b><tt>char *Swig_file_dirname(const String_or_char *filename)</tt></b>
<blockquote>
Returns the directory name (if any). For instance, if the filename is "/bar/spam/foo.txt", it
returns "/bar/spam/". This function is aware of local naming conventions on the machine (e.g., forward versus back slashes on Unix and Windows). The result is stored in a static variable. If you need to save the value, make a copy.
</blockquote>
<p>
<b><tt>SWIG_FILE_DELIMITER</tt></b>
<blockquote>
This macro contains the file delimiter string for the local machine. On Unix it is "/", on Windows it is "\\".
</blockquote>
</body>
</html>

31
winx64/bin/swig-3.0.12/Doc/Devel/index.html Normal file
View File

@@ -0,0 +1,31 @@
<html>
<head>
<title>SWIG Documentation</title>
</head>
<body>
This directory contains SWIG documentation:
<ul>
<li><a href="engineering.html">Engineering Manual</a>
<li><a href="internals.html">Internals Manual</a>
<li><a href="migrate.txt">SWIG1.3 Migration Guide</a>
</ul>
The following documentation describe the internal APIs used by SWIG. These may be useful to module developers.
<ul>
<li><a href="file.html">File handling functions</a>
<li><a href="cmdopt.html">Command line arguments</a>
<li><a href="tree.html">Parse tree navigation and manipulation</a>
<li><a href="parm.html">Parameter and Parameter list handling functions</a>
<li><a href="scanner.html">Generic C/C++ Scanner interface</a>
<li><a href="wrapobj.html">Wrapper objects</a>.
<li><a href="runtime.txt">SWIG Runtime</a>.
</ul>
<hr>
Copyright (C) 1999-2007 SWIG Development Team.
</body>
</html>

1215
winx64/bin/swig-3.0.12/Doc/Devel/internals.html Normal file
View File

File diff suppressed because it is too large Load Diff

140
winx64/bin/swig-3.0.12/Doc/Devel/migrate.txt Normal file
View File

@@ -0,0 +1,140 @@
SWIG1.3 Migration Guide
(The not entirely complete guide to updating language modules to work with SWIG1.3).
Dave Beazley
August 15, 2000
1. Introduction
---------------
Virtually all of SWIG's internal data structures have now been
rewritten. Take everything you thought you knew about SWIG1.1 and
throw it out.
2. DataTypes
------------
The old 'DataType' data structure is gone. Therefore, direct
manipulation of 'is_pointer', 'implicit_ptr', and 'arraystr'
attributes no longer applies. Sorry.
Datatypes are now represented by the type 'SwigType' which has no
public attributes. Actually, if you look at it closely, 'SwigType' is
really just an alias for 'void' and if you look at it even closer than
that you will realize that it's nothing more than a string!
The string encoding of types is described in more detail in the file
Source/Swig/stype.c and is not so important here. What is important is
the functions used to produce various types of output:
SwigType_str(type,name = 0);
This produces an exact C representation of the datatype with all
qualifiers, arrays, references, and so forth. name is an optional
name that is given if you wanted to associate the type with a
parameter name or something.
SwigType_lstr(type,name = 0);
This function takes a type and produces a C string containing
a type suitable for assignment (appearing as an lvalue in an
expression). To do this, certain things such as 'const',
arrays, and references are stripped away or converted into
pointers.
SwigType_ltype(type);
Returns a SwigType object corresponding to the type created
by SwigType_lstr().
SwigType_lcaststr(type,name);
Produces a string casting a value 'name' from the real datatype
to the assignable type created by SwigType_lstr().
SwigType_rcaststr(type,name)
Produces a string that casts a value 'name' from the type
created by SwigType_lstr() to the real datatype.
SwigType_manglestr(type)
Produces the 'mangled' version of a datatype.
Getting the 'type' code. Most language modules still operate by
looking at special integer type codes. This interface is a little
ragged and will probably go away at some point. However, for now the
following function can be used to get the type code:
int SwigType_type(type)
The codes are the same as the before, except that there are a few
special codes:
T_STRING - The 'char *' type and variations.
T_POINTER - Any pointer type (not char * though)
T_REFERENCE - Any C++ reference
T_ARRAY - Any array
T_FUNCTION - A function (this is usually an error).
Because of the special codes, it is no longer necessary to have code like this:
if ((t->is_pointer == 1) and (t->type == T_CHAR)) {
... get a string ...
}
Instead, just use the type code above like this:
switch(SwigType_type(type)) {
case T_STRING:
... get a string ...
break;
case T_POINTER:
... get a pointer ...
break;
}
There are about 2-dozen type manipulation functions that could also be useful.
See Source/Swig/swig.h and Source/Swig/stype.c.
3. Parameter Lists
------------------
The ParmList data structure is gone. In reality, parameter lists are nothing more than
a linked list of parameters. The proper way to iterate over this list and get
parameter values is as follows:
ParmList *l;
Parm *p;
for (p = l; p; p = Getnext(p)) {
SwigType *pt = Gettype(p); /* Get parameter type */
String *pn = Getname(p); /* Get parameter name */
String *value = Getvalue(p); /* Get parameter value */
...
do whatever
...
}
4. Typemaps
-----------
Typemaps more or less work. However, the interface has changed slightly. Instead of
typemap_lookup("in","python",type,pname,"$source","$target",wrapper);
the function is
Swig_typemap_lookup("in",type,pname,"$source","$target",wrapper);
There are a variety of other changes to typemaps (see CHANGES).
5. Use of new types
-------------------
When possible, language modules should try to use the built in String,
List, and Hash objects instead of C arrays or 'char *'. This will probably require a
detailed pass through the code with an eye towards cleanup.
6. Miscellaneous
----------------
Language modules no longer need to concern themselves with formatting the
wrapper code they produce (provided you are using the special Wrapper object).
The function Wrapper_print() passes everything through a pretty-printer that
automatically performs indentation and tries to clean things up. This especially
works well when there are lots of typemaps.

102
winx64/bin/swig-3.0.12/Doc/Devel/parm.html Normal file
View File

@@ -0,0 +1,102 @@
<html>
<head>
<title>SWIG Parameter Handling</title>
</head>
<body>
<center>
<h1>SWIG Parameter Handling</h1>
<p>
David M. Beazley <br>
dave-swig@dabeaz.com<br>
January 9, 2007<br>
</b>
</center>
<h2>Introduction</h2>
This document describes the functions related to management of function parameters and parameter lists in the SWIG core. These functions are declared in <tt>Source/Swig/swigparm.h</tt>. This API is considered to be stable.
<h2>Parameters</h2>
The following utility functions are used to create and copy individual parameters. In their most basic form, a parameter merely contains a type, a name, and an optional default value.
<p>
<b><tt>Parm *NewParm(SwigType *type, const String_or_char *name)</tt></b>
<blockquote>
Creates a new parameter object with type <tt>type</tt> and name <tt>name</tt>. The type is stored in the attribute "type" and the name is stored in the attribute "name".
</blockquote>
<p>
<b><tt>Parm *CopyParm(Parm *p)</tt></b>
<blockquote>
Copies a parameter object. All string attributes are copied in the
process of making the copy. However, no complex attributes (lists,
hashes, etc.) are copied.
</blockquote>
<h2>Parameter Lists</h2>
<p>
<b><tt>ParmList *CopyParmList(ParmList *p)</tt></b>
<blockquote>
Creates a copy of a parameter list. A parameter list is merely a linked list of parameters created by NewParm().
</blockquote>
<p>
<b><tt>ParmList *CopyParmListMax(ParmList *p, int count)</tt></b>
<blockquote>
Copies at most <tt>count</tt> parameters from the parameter list <tt>p</tt>.
</blockquote>
<p>
<b><tt>int ParmList_len(ParmList *p)</tt></b>
<blockquote>
Returns the total number of parameters in a parameter list.
</blockquote>
<p>
<b><tt>int ParmList_numrequired(ParmList *p)</tt></b>
<blockquote>
Returns the number of required parameters in a parameter list. This pertains to invoking a function/method in C/C++.
</blockquote>
<p>
<b><tt>int ParmList_has_defaultargs(ParmList *p)</tt></b>
<blockquote>
Returns 1 if the parameter list has any default arguments. Otherwise returns 0.
</blockquote>
<h2>Code Generation Functions</h2>
<p>
<b><tt>String *ParmList_str(ParmList *p)</tt></b>
<blockquote>
Creates a C prototype string of the parameters, but without any default values.
</blockquote>
<p>
<b><tt>String *ParmList_str_defaultargs(ParmList *p)</tt></b>
<blockquote>
Creates a C prototype string of the parameters and includes the default values (if any).
</blockquote>
<p>
<b><tt>String *ParmList_protostr(ParmList *p)</tt></b>
<blockquote>
Creates a C prototype string of the parameters.
</blockquote>
</body>
</html>

169
winx64/bin/swig-3.0.12/Doc/Devel/runtime.txt Normal file
View File

@@ -0,0 +1,169 @@
This file describes the necessary functions and interfaces a language module
needs to implement to take advantage of the run time type system. I assume you
have read the run-time section of the Typemaps chapter in the SWIG
documentation.
Last updated: February 23, 2005
The file we are concerned with here should be named langrun.swg. A good example
of a simple file is the Lib/mzscheme/mzrun.swg file. First, a few requirements
and notes:
1) Every function in this file should be declared static.
2) It should be inserted into the runtime section of the _wrap file from your
config file. The Lib/swigrun.swg file should be included before this file.
That is, you need to have
%runtime "swigrun.swg"
%runtime "langrun.swg"
3) You must also include the swiginit.swg file in the init section of the
wrapper. That is, you should have
%insert(init) "swiginit.swg"
4) From module.cxx, you need to call the SwigType_emit_type_table function, as
well as register types with SwigType_remember or SwigType_remember_clientdata
5) By convention, all functions in this file are of the form
SWIG_Language_Whatever, and #defines are used to rename SWIG API functions to
these function names
6) You need to call void SWIG_InitializeModule(void *clientdata) from your init
function.
7) You need to implement the runtimeCode() and defaultExternalRuntimeFilename()
functions inside module.cxx. runtimeCode should return all the language
specific runtime code as a string, and defaultExternalRuntimeFilename should
return a string for the default name of the external runtime header. This is
usually "swigpyrun.h", where "py" is replaced by the language name. These
two functions are used by the -external-runtime argument.
-------------------------------------------------------------------------------
Required Functions
-------------------------------------------------------------------------------
swig_module_info *SWIG_GetModule(void *clientdata);
void SWIG_SetModule(void *clientdata, swig_module_info *mod);
The SetModule function should store the mod argument into some globally
accessible variable in the target language. The action of these two functions
is to provide a way for multiple modules to share information. The SetModule
function should create a new global var named something like
"swig_runtime_data_type_pointer" SWIG_RUNTIME_VERSION SWIG_TYPE_TABLE_NAME
SWIG_RUNTIME_VERSION is currently defined as "2", and SWIG_TYPE_TABLE_NAME is
defined by the -DSWIG_TYPE_TABLE=mytable option when compiling the wrapper.
Alternatively, if the language supports modules, a module named
"swig_runtime_data" SWIG_RUNTIME_VERSION can be created, and a global variable
named "type_table" SWIG_TYPE_TABLE_NAME can be created inside it. The most
common approach is to store the mod pointer in some global variable in the
target language, but if the language provides an alternative place to store data
(like the chicken module), then that is good too.
The way the code is set up, SetModule should only be called when GetModule
returns NULL, and if SetModule is called a second time, the behavior is
undefined. Just make sure it doesn't crash in the random chance occurrence that
SetModule is called twice.
There are two options here.
1) The preferred approach is for GetModule and SetModule to not require a
clientdata pointer. If you can at all avoid it, please do so. Here, you would
write swig_module_info *SWIG_Language_GetModule();
void SWIG_Language_SetModule(swig_module_info *mod);
and then add
#define SWIG_GetModule(clientdata) SWIG_Language_GetModule()
#define SWIG_SetModule(cd, ptr) SWIG_Language_SetModule(ptr)
You would then call
SWIG_InitializeModule(0)
2) If GetModule and SetModule need to take a custom pointer (most notably an
environment pointer, see tcl or mzscheme), then you should write
swig_module_info *SWIG_Language_GetModule(void *clientdata)
void SWIG_Language_SetModule(void *clientdata, swig_module_info *mod);
and also define
#define SWIG_GetModule(cd) SWIG_Language_GetModule(cd)
#define SWIG_SetModule(cd, ptr) SWIG_Language_SetModule(cd, ptr)
#define SWIG_MODULE_CLIENTDATA_TYPE Whatever
SWIG_MODULE_CLIENTDATA_TYPE should be defined to whatever the type of
clientdata is.
You would then call SWIG_InitializeModule(clientdata), and clientdata would get
passed to GetModule and SetModule. clientdata will not be stored and will only
be referenced during the InitializeModule call. After InitializeModule returns,
clientdata does not need to be valid any more.
This method is not preferred, because it makes external access to the type
system more complicated. See the Modules chapter of the documentation, and read
the "External access to the run-time" section. Then take a look at
Lib/runtime.swg. Anybody that calls SWIG_TypeQuery needs to pass along the
clientdata pointer, and that is the reason for defining
SWIG_MODULE_CLIENTDATA_TYPE.
-------------------------------------------------------------------------------
Standard Functions
-------------------------------------------------------------------------------
These functions are not required and their API is not formalized, but almost all
language modules implement them for consistency across languages. Throughout
this discussion, I will use LangType to represent the underlying language type
(C_word in chicken, Scheme_Object * in mzscheme, PyObject * in python, etc)
LangObj SWIG_NewPointerObj(void *ptr, swig_type_info *type, int flags);
Create and return a new pointer object that has both ptr and type. For almost
all language modules, flags is used for ownership. If flags==1, then the
created pointer should be registered to be garbage collected.
int SWIG_ConvertPtr(LangType obj, void **result, swig_type_info *type, int flags);
Convert a language wrapped pointer into a void *. The pointer is returned in
result, and the function should return 0 on success, non-zero on error.
A sample ConvertPtr is given here:
swig_cast_info *cast;
if (<obj is a wrapped pointer type>) {
cast = SWIG_TypeCheck(<obj type name>, type);
cast = SWIG_TypeCheckStruct(<obj type structure>, type);
if (cast) {
*result = SWIG_TypeCast(cast, <obj pointer>);
return 0;
}
}
return 1;
Either TypeCheck or TypeCheckStruct can be called, depending on how the pointer
is wrapped in langtype. If obj stores the void pointer and the type name, then
the TypeCheck function should be used, while if obj stores the void pointer and
a pointer to the swig_type_info structure, then the TypeCheckStruct function
should be called. The TypeCheckStruct is slightly faster, since it does a
pointer comparison instead of a strcmp.
The flag argument to ConvertPtr is used in some languages for disowning a
pointer. If the wrapped C function is taking ownership of the pointer (that
means, the wrapped C function is responsible for deleting the object), then that
pointer should be removed from the garbage collector. We do that in the
ConvertPtr function. The pointer is still valid in the target language, but
when the target language type is garbage collected, it will not call the
associated destructor. Languages have a special typemap called DISOWN that can be
applied which passes this argument. All the languages have the flags argument
for consistency, and the flags argument can be ignored or used for some other
purpose.
void *SWIG_MustGetPtr(LangType obj, swig_type_info *type, int flags,
int argnum, const char *func_name) {
void *result;
if (SWIG_ConvertPtr(s, &result, type, flags)) {
generate runtime type error ("Error in func_name, expected a" +
type->str ? type->str : "void *" +
"at argument number" + argnum);
}
return result;
}
This function is optional, and the number and type of parameters can be
different, but is useful for typemap purposes:
%typemap(in) SWIGTYPE *, SWIGTYPE &, SWIGTYPE [] {
$1 = ($1_ltype)SWIG_MustGetPtr($input, $descriptor, 0, $argnum, FUNC_NAME);
}

283
winx64/bin/swig-3.0.12/Doc/Devel/scanner.html Normal file
View File

@@ -0,0 +1,283 @@
<html>
<head>
<title>SWIG C Scanner</title>
</head>
<body>
<center>
<h1>SWIG C/C++ Scanning</h1>
<p>
David M. Beazley <br>
dave-swig@dabeaz.com<br>
January 11, 2007<br>
</b>
</center>
<h2>Introduction</h2>
This document describes functions that can be used to tokenize C/C++
input text. These functions are relatively low-level and are meant to
be used in the implementation of scanners that can be plugged into yacc or used for
other purposes. For instance, the preprocessor uses these functions to evaluate and test
constant expressions.
<p>
All of these functions are declared in <tt>Source/Swig/swigscan.h</tt>. This API is considered to be stable.
<h2>Creation and Deletion of Scanners</h2>
The following functions are used to create and destroy a scanner object. More than one scanner object can be created and used
as necessary.
<p>
<b><tt>Scanner *NewScanner()</tt></b>
<blockquote>
Creates a new scanner object. The scanner contains initially contains no text. To feed text to the scanner use <tt>Scanner_push()</tt>.
</blockquote>
<p>
<b><tt>Scanner *DelScanner()</tt></b>
<blockquote>
Deletes a scanner object.
</blockquote>
<h2>Scanner Functions</h2>
<p>
<b><tt>void Scanner_clear(Scanner *s)</tt></b>
<blockquote>
Clears all text from the scanner. This can be used to reset a scanner to its initial state, ready to receive new input text.
</blockquote>
<p>
<b><tt>void Scanner_push(Scanner *s, String *text)</tt></b>
<blockquote>
Pushes an input string into the scanner. Subsequent tokens will be
returned from the new string. If the scanner is already processing a
string, the pushed string takes precedence--in effect, interrupting
the scanning of the previous string. This behavior is used to
implement certain SWIG features such as the <tt>%inline</tt>
directive. Once the pushed string has been completely scanned, the
scanner will return to scanning the previous string (if any). The
scanning of text relies upon the DOH file interface to strings
(<tt>Getc()</tt>, <tt>Ungetc()</tt>, etc.). Prior to calling this
function, the input string should be set so that its file pointer is
in the location where you want scanning to begin. You may have to
use <tt>Seek()</tt> to set the file pointer back to the beginning of a
string prior to using this function.
</blockquote>
<p>
<b><tt>void Scanner_pushtoken(Scanner *s, int tokvalue, String_or_char *val)</tt></b>
<blockquote>
Pushes a token into the scanner. This exact token will be returned by the next call to <tt>Scanner_token()</tt>.
<tt>tokvalue</tt> is the integer token value to return and <tt>val</tt> is the token text to return. This
function is only used to handle very special parsing cases. For instance, if you need the scanner to
return a fictitious token into order to enter a special parsing case.
</blockquote>
<p>
<b><tt>int Scanner_token(Scanner *s)</tt></b>
<blockquote>
Returns the next token. An integer token code is returned (see table below) on success. If no more input text is
available 0 is returned. If a scanning error occurred, -1 is returned. In this case, error information can be
obtained using <tt>Scanner_errinfo()</tt>.
</blockquote>
<p>
<b><tt>String *Scanner_text(Scanner *s)</tt></b>
<blockquote>
Returns the scanned text corresponding to the last token returned by <tt>Scanner_token()</tt>. The returned string
is only valid until the next call to <tt>Scanner_token()</tt>. If you need to save it, make a copy.
</blockquote>
<p>
<b><tt>void Scanner_skip_line(Scanner *s)</tt></b>
<blockquote>
Skips to the end of the current line. The text skipped can be obtained using <tt>Scanner_text()</tt> afterwards.
</blockquote>
<p>
<b><tt>void Scanner_skip_balanced(Scanner *s, int startchar, int endchar)</tt></b>
<blockquote>
Skips to the end of a block of text denoted by starting and ending characters. For example, <tt>{</tt> and <tt>}</tt>. The
function is smart about how it skips text. String literals and comments are ignored. The function also is aware of nesting. The
skipped text can be obtained using <tt>Scanner_text()</tt> afterwards. Returns 0 on success, -1 if no matching <tt>endchar</tt> could be found.
</blockquote>
<p>
<b><tt>void Scanner_set_location(Scanner *s, int startchar, int endchar)</tt></b>
<blockquote>
Changes the current filename and line number of the scanner.
</blockquote>
<p>
<b><tt>String *Scanner_file(Scanner *s)</tt></b>
<blockquote>
Gets the current filename associated with text in the scanner.
</blockquote>
<p>
<b><tt>int Scanner_line(Scanner *s)</tt></b>
<blockquote>
Gets the current line number associated with text in the scanner.
</blockquote>
<p>
<b><tt>int Scanner_start_line(Scanner *s)</tt></b>
<blockquote>
Gets the starting line number of the last token returned by the scanner.
</blockquote>
<p>
<b><tt>void Scanner_idstart(Scanner *s, char *idchar)</tt></b>
<blockquote>
Sets additional characters (other than the C default) that may be used to start C identifiers. <tt>idchar</tt> is a string
containing the characters (e.g., "%@"). The purpose of this function is to up special keywords such as "%module" or "@directive" as
simple identifiers.
</blockquote>
<p>
<b><tt>String *Scanner_errmsg(Scanner *s)</tt></b>
<blockquote>
Returns the error message associated with the last scanner error (if any). This will only return a meaningful result
if <tt>Scanner_token()</tt> returned -1.
</blockquote>
<p>
<b><tt>int Scanner_errline(Scanner *s)</tt></b>
<blockquote>
Returns the line number associated with the last scanner error (if any). This will only return a meaningful result
if <tt>Scanner_token()</tt> returned -1. The line number usually corresponds to the starting line number of a particular
token (e.g., for unterminated strings, comments, etc.).
</blockquote>
<p>
<b><tt>int Scanner_isoperator(int tokval)</tt></b>
<blockquote>
A convenience function that returns 0 or 1 depending on whether <tt>tokval</tt> is a valid C/C++ operator (i.e., a candidate for
operator overloading).
</blockquote>
<p>
<b><tt>void Scanner_freeze_line(int val)</tt></b>
<blockquote>
Freezes the current line number depending upon whether or not <tt>val</tt> is 1 or 0. When the line number is frozen, newline characters will not result in
updates to the line number. This is sometimes useful in tracking line numbers through complicated macro expansions.
</blockquote>
<h2>Token Codes</h2>
The following table shows token codes returned by the scanner. These are integer codes returned by
the <tt>Scanner_token()</tt> function.
<blockquote>
<pre>
Token code C Token
------------------------- -------------
SWIG_TOKEN_LPAREN (
SWIG_TOKEN_RPAREN )
SWIG_TOKEN_SEMI ;
SWIG_TOKEN_COMMA ,
SWIG_TOKEN_STAR *
SWIG_TOKEN_TIMES *
SWIG_TOKEN_LBRACE {
SWIG_TOKEN_RBRACE }
SWIG_TOKEN_EQUAL =
SWIG_TOKEN_EQUALTO ==
SWIG_TOKEN_NOTEQUAL !=
SWIG_TOKEN_PLUS +
SWIG_TOKEN_MINUS -
SWIG_TOKEN_AND &amp;
SWIG_TOKEN_LAND &amp;&amp;
SWIG_TOKEN_OR |
SWIG_TOKEN_LOR ||
SWIG_TOKEN_XOR ^
SWIG_TOKEN_LESSTHAN &lt;
SWIG_TOKEN_GREATERTHAN &gt;
SWIG_TOKEN_LTEQUAL &lt;=
SWIG_TOKEN_GTEQUAL &gt;=
SWIG_TOKEN_NOT ~
SWIG_TOKEN_LNOT !
SWIG_TOKEN_LBRACKET [
SWIG_TOKEN_RBRACKET ]
SWIG_TOKEN_SLASH /
SWIG_TOKEN_DIVIDE /
SWIG_TOKEN_BACKSLASH \
SWIG_TOKEN_POUND #
SWIG_TOKEN_PERCENT %
SWIG_TOKEN_MODULO %
SWIG_TOKEN_COLON :
SWIG_TOKEN_DCOLON ::
SWIG_TOKEN_DCOLONSTAR ::*
SWIG_TOKEN_LSHIFT &lt;&lt;
SWIG_TOKEN_RSHIFT &gt;&gt;
SWIG_TOKEN_QUESTION ?
SWIG_TOKEN_PLUSPLUS ++
SWIG_TOKEN_MINUSMINUS --
SWIG_TOKEN_PLUSEQUAL +=
SWIG_TOKEN_MINUSEQUAL -=
SWIG_TOKEN_TIMESEQUAL *=
SWIG_TOKEN_DIVEQUAL /=
SWIG_TOKEN_ANDEQUAL &amp;=
SWIG_TOKEN_OREQUAL |=
SWIG_TOKEN_XOREQUAL ^=
SWIG_TOKEN_LSEQUAL &lt;&lt;=
SWIG_TOKEN_RSEQUAL &gt;&gt;=
SWIG_TOKEN_MODEQUAL %=
SWIG_TOKEN_ARROW -&gt;
SWIG_TOKEN_ARROWSTAR -&gt;*
SWIG_TOKEN_PERIOD .
SWIG_TOKEN_AT @
SWIG_TOKEN_DOLLAR $
SWIG_TOKEN_ENDLINE Literal newline
SWIG_TOKEN_ID identifier
SWIG_TOKEN_FLOAT Floating point with F suffix (e.g., 3.1415F)
SWIG_TOKEN_DOUBLE Floating point (e.g., 3.1415 )
SWIG_TOKEN_INT Integer (e.g., 314)
SWIG_TOKEN_UINT Unsigned integer (e.g., 314U)
SWIG_TOKEN_LONG Long integer (e.g., 314L)
SWIG_TOKEN_ULONG Unsigned long integer (e.g., 314UL)
SWIG_TOKEN_LONGLONG Long long integer (e.g., 314LL )
SWIG_TOKEN_ULONGLONG Unsigned long long integer (e.g., 314ULL)
SWIG_TOKEN_CHAR Character literal in single quotes ('c')
SWIG_TOKEN_STRING String literal in double quotes ("str")
SWIG_TOKEN_RSTRING Reverse quote string (`str`)
SWIG_TOKEN_CODEBLOCK SWIG code literal block %{ ... %}
SWIG_TOKEN_COMMENT C or C++ comment (// or /* ... */)
SWIG_TOKEN_ILLEGAL Illegal character
</pre>
</blockquote>
<b>Notes</b>
<ul>
<li>When more than one token code exist for the same token text, those codes are identical (e.g., <tt>SWIG_TOKEN_STAR</tt> and <tt>SWIG_TOKEN_TIMES</tt>).
<p>
<li>
String literals are returned in their exact representation in which escape codes (if any) have been interpreted.
<p>
<li>
All C identifiers and keywords are simply returned as <tt>SWIG_TOKEN_ID</tt>. To check for specific keywords, you will need to
add extra checking on the returned text.
<p>
<li>C and C++ comments include the comment starting and ending text (e.g., "//", "/*").
<p>
<li>The maximum token integer value is found in the constant <tt>SWIG_MAXTOKENS</tt>. This can be used if you wanted to create
an array or table for the purposes of remapping tokens to a different set of codes. For instance, if you are
using these functions to write a yacc-compatible lexer.
</ul>
</body>
</html>

284
winx64/bin/swig-3.0.12/Doc/Devel/tree.html Normal file
View File

@@ -0,0 +1,284 @@
<html>
<head>
<title>SWIG Parse Tree Handling</title>
</head>
<body>
<center>
<h1>SWIG Parse Tree Handling</h1>
</center>
<h2>Introduction</h2>
This document describes the functions related to the handling of
parse trees in SWIG. The structure of SWIG parse trees has been influenced heavily by ideas
from XML-DOM trees. In fact, the functions in the API and attribute names are nearly identical.
The header file <tt>Source/swig/swigtree.h</tt> contains the functions and macros described in
this document. This API is
considered to be stable.
<h2>Parse tree navigation</h2>
The following macros are used to navigate the parse tree.
<p>
<b><tt>nodeType(n)</tt></b>
<blockquote>
Returns the type of a node as a String object. The type is stored in the "nodeType" attribute of <tt>n</tt>.
</blockquote>
<p>
<b><tt>parentNode(n)</tt></b>
<blockquote>
Returns the parent of a node. This is found in the "parentNode" attribute of <tt>n</tt>.
</blockquote>
<p>
<b><tt>previousSibling(n)</tt></b>
<blockquote>
Returns the previous sibling of a node (if any). This is found in the "previousSibling" attribute of <tt>n</tt>.
</blockquote>
<p>
<b><tt>nextSibling(n)</tt></b>
<blockquote>
Returns the next sibling of a node (if any). This is found in the "nextSibling" attribute of <tt>n</tt>.
</blockquote>
<p>
<b><tt>firstChild(n)</tt></b>
<blockquote>
Returns the first child of a node (if any). This is found in the "firstChild" attribute of <tt>n</tt>.
</blockquote>
<p>
<b><tt>lastChild(n)</tt></b>
<blockquote>
Returns the last child of a node (if any). This is found in the "lastChild" attribute of <tt>n</tt>.
</blockquote>
<h2>Parse Tree Construction</h2>
The following macros are used to construct parse trees.
<p>
<b><tt>set_nodeType(n, val)</tt></b>
<blockquote>
Sets the nodeType attribute of n. val is a string containing the type.
</blockquote>
<p>
<b><tt>set_parentNode(n, parent)</tt></b>
<blockquote>
Sets the parent of node n.
</blockquote>
<p>
<b><tt>set_previousSibling(n, prev)</tt></b>
<blockquote>
Sets the previous sibling of node n.
</blockquote>
<p>
<b><tt>set_nextSibling(n, next)</tt></b>
<blockquote>
Sets the next sibling of node n.
</blockquote>
<p>
<b><tt>set_firstChild(n, chd)</tt></b>
<blockquote>
Sets the first child of node n.
</blockquote>
<p>
<b><tt>set_lastChild(n, chd)</tt></b>
<blockquote>
Sets the last child of node n.
</blockquote>
<h2>Tree Management Functions</h2>
The following functions are used to help with the management and construction of parse trees.
<p>
<b><tt>void appendChild(Node *node, Node *child)</tt></b>
<blockquote>
Adds a new child to <tt>node</tt>. This function takes care of adjusting the "firstChild" and "lastChild" attributes of <tt>node</tt> to appropriate values. After calling this function, the "lastChild" attribute will point to <tt>child</tt>.
</blockquote>
<p>
<b><tt>void prependChild(Node *node, Node *child)</tt></b>
<blockquote>
Prepends a new child to <tt>node</tt>. The new child is added so that it becomes the first child of <tt>node</tt>.
</blockquote>
<p>
<b><tt>void removeNode(Node *node)</tt></b>
<blockquote>
Removes a node from the parse tree. The removal process detaches a node from its parent by removing it from the parent's child list. Upon return, <tt>node</tt> will have no parent and no siblings. This function does NOT delete <tt>node</tt> or modify children of <tt>node</tt>. If desired, <tt>node</tt> could be reattached to a different part of the parse tree.
</blockquote>
<p>
<b><tt>Node *copyNode(Node *node)</tt></b>
<blockquote>
Copies a node, but only copies those attributes that are simple strings. Thus, the new node will not contain any references to other nodes, lists, hashes, or other complex data structures. This function may be useful if you want to copy the data contents of a node in the process of creating a new parse tree node.
</blockquote>
<h2>Attribute Checking</h2>
The following utility is provided since this is an extremely common operation.
<p>
<b><tt>int checkAttribute(Node *n, const String_or_char *name, const String_or_char *value)</tt></b>
<blockquote>
This function checks to see whether node <tt>n</tt> has a given
attribute name and that the attribute has a given value. Returns 0 or
1.
</blockquote>
<h2>Node Transformation</h2>
In the course of processing, SWIG often applies a transform to a node.
This transformation process made modify many of the attributes--even
changing the type of a node. The following functions are used to help
manage this transformation process. In addition to provide sanity
checks, they save the old contents of the node so that they can be
restored later.
<p>
<b><tt>void Swig_save(const char *namespace, Node *n, ...)</tt></b>
<blockquote>
This function takes a node and a list of attribute names and saves their contents in a specified namespace. For example,
the call
<pre>
Swig_save("temp",n,"type","parms","name",NIL)
</pre>
takes the attributes "type","parms", and "name" and saves their
contents under the attribute names "temp:type","temp:parms","temp:name". In addition, this function sets
an attribute "view" to hold the name of the current namespace. In this example, the "view" attribute would be set
to "temp". The attribute names specified are all optional. If one or more of the attributes don't exist,
this function merely records that those attributes did not exist in the original node.
</blockquote>
<p>
<b><tt>void Swig_require(const char *namespace, Node *n, ...)</tt></b>
<blockquote>
This function is similar to <tt>Swig_save()</tt> except that adds additional attribute checking. There are different interpretations
of the attribute names. A name of "attr" merely requests that the function check for the presence of an attribute. If the attribute is missing, SWIG will exit with a failed assertion. An attribute name of "?attr" specifies that the attribute "attr" is optional and
that its old value must be saved (if any). An attribute name of "*attr" specifies that the attribute is required and that
its value must be saved. The saving of attributes is performed in the same manner as with <tt>Swig_save()</tt>. Here is an example:
<pre>
Swig_require("temp",n,"type","*name","?parms",NIL);
</pre>
</blockquote>
<p>
<b><tt>void Swig_restore(Node *n)</tt></b>
<blockquote>
This function restores a node to the state it was in prior to the last <tt>Swig_save()</tt> or <tt>Swig_require()</tt> call. This is used to undo node transformations.
</blockquote>
<h2>Debugging Functions</h2>
<p>
The following functions can be used to help debug any SWIG DOH object.
</p>
<b><tt>void Swig_print(DOH *object, int count = -1)</tt></b>
<blockquote>
Prints to stdout a string representation of any DOH type.
The number of nested Hash types to expand is set by count (default is 1 if count&lt;0). See Swig_set_max_hash_expand() to change default.
<pre>
</pre>
</blockquote>
<b><tt>void Swig_print_with_location(DOH *object, int count = -1)</tt></b>
<blockquote>
Prints to stdout a string representation of any DOH type, within [] brackets
for Hash and List types, prefixed by line and file information.
The number of nested Hash types to expand is set by count (default is 1 if count&lt;0). See Swig_set_max_hash_expand() to change default.
<pre>
</pre>
</blockquote>
<p>
The following functions can be used to help debug SWIG parse trees.
</p>
<p>
<b><tt>void Swig_print_tags(Node *node, String_or_char *prefix)</tt></b>
<blockquote>
Prints the tag-structure of the parse tree to standard output. <tt>node</tt> is the top-level parse tree node. <tt>prefix</tt> is
a string prefix thats added to the start of each line. Normally, you would specify the empty string or NIL for <tt>prefix</tt>.
This function is called by the <tt>-debug-tags</tt> option to SWIG.
<pre>
% swig -debug-tags -python example.i
. top (:1)
. top . include (/Users/beazley/Projects/share/swig/1.3.31/swig.swg:0)
. top . include . include (/Users/beazley/Projects/share/swig/1.3.31/swigwarnings.swg:0)
. top . include . include . include (/Users/beazley/Projects/share/swig/1.3.31/swigwarn.swg:0)
...
...
. top . include (example.i:0)
. top . include . module (example.i:2)
. top . include . insert (example.i:7)
. top . include . cdecl (example.i:5)
. top . include . cdecl (example.i:6)
</pre>
Since many language modules include hundreds of typemaps and other information, the output of this can be significantly more complicated than you might expect.
</blockquote>
<p>
<b><tt>void Swig_print_node(Node *node)</tt></b>
<blockquote>
Prints the contents of a parse tree node, including all children, to standard output. The output includes all attributes
and other details.
</blockquote>
<p>
<b><tt>void Swig_print_tree(Node *node)</tt></b>
<blockquote>
Prints the same output as <tt>Swig_print_node()</tt> except that it also processes all of the siblings of <tt>node</tt>. This can
be used to dump the entire parse tree to standard output. The command line options <tt>-debug-module</tt>
and <tt>-debug-top</tt> use this function to display the parse tree for a SWIG input file.
</blockquote>
</body>
</html>

223
winx64/bin/swig-3.0.12/Doc/Devel/wrapobj.html Normal file
View File

@@ -0,0 +1,223 @@
<html>
<head>
<title>Wrapper Objects</title>
</head>
<body>
<center>
<h1>Wrapper Objects</h1>
<p>
David M. Beazley <br>
dave-swig@dabeaz.com<br>
January 15, 2007<br>
</b>
</center>
<h2>Introduction</h2>
This document describes the functions related to management of
wrapper objects. A wrapper object is a low-level
data structure used to contain the C/C++ code that is emitted during the
wrapping process. It contains not only the emitted code, but information
about local variables. These objects are a critical component of almost all
SWIG target language modules.
<p>
The functions described here are declared
in <tt>Source/Swig/swigwrap.h</tt>. This API is considered to be
stable.
<h2>Creating and Destroying Wrappers</h2>
The following functions create and destroy wrapper objects.
<p>
<b><tt>Wrapper *NewWrapper()</tt></b>
<blockquote>
Creates a new wrapper object.
</blockquote>
<p>
<b><tt>void DelWrapper(Wrapper *w)</tt></b>
<blockquote>
Destroys a wrapper object.
</blockquote>
<h2>Wrapper Objects</h2>
The <tt>Wrapper</tt> object returned by <tt>NewWrapper()</tt> has
three public attributes.
<blockquote><pre>
typedef struct Wrapper {
String *def;
String *locals;
String *code;
} Wrapper;
</pre></blockquote>
The <tt>def</tt> attribute is a string that holds the function
definition line. This line declares the function name, return type,
and parameters. Language modules create this declaration by simply printing
the appropriate text into this attribute.
<p>
The <tt>locals</tt> attribute is a string that holds the code
related to any local variables declaration. Normally, language modules
do not emit code to this string directly. They use <tt>Wrapper_add_local()</tt> or <tt>Wrapper_new_local()</tt> to do this.
<p>
The <tt>code</tt> attribute is a string that holds code related to the body of the function. Almost all code emitted by SWIG language modules is printed into this attribute.
<h2>Creating Local Variables</h2>
Perhaps the most useful aspect of <tt>Wrapper</tt> objects is the
management of local variables. When creating a wrapper, it is often
necessary to emit local variables related to the API of the target
language. In addition to this, typemaps and other aspects of SWIG
rely upon their own local variables. The following functions are used
to create local variables, but also provide support for renaming
variables in order to avoid name clashes.
<p>
<b><tt>int Wrapper_add_local(Wrapper *w, const String_or_char *name, const String_or_char *decl)</tt></b>
<blockquote>
Adds a new local variable to the wrapper object. <tt>name</tt> is the
name of the local variable. <tt>decl</tt> is a string containing the
actual variable declaration code. For example, if you wanted to
declare a variable "<tt>int x = 42;</tt>", you would set <tt>name</tt>
to <tt>"x"</tt> and
<tt>decl</tt> to <tt>"int x = 42;"</tt>. On success, the text in
<tt>decl</tt> is added to the <tt>locals</tt> attribute of <tt>w</tt>
and 0 is returned. -1 is returned if a variable with the given name
has already been declared.
</blockquote>
<p>
<b><tt>int Wrapper_add_localv(Wrapper *w, const String_or_char *name, ...)</tt></b>
<blockquote>
The same as <tt>Wrapper_add_local()</tt> except that instead of
passing a single string for the declaration, a NULL-terminated list of
strings can be passed. These strings are joined together when
producing the output. This convention turns out to be fairly useful
since language modules often create their output into pieces.
</blockquote>
<p>
<b><tt>char * Wrapper_new_local(Wrapper *w, const String_or_char *name, const String_or_char *decl)</tt></b>
<blockquote>
The same as <tt>Wrapper_add_local()</tt> except that if a local variable
with the given name already exists, this function picks a new name and adds
the declaration using the new name. The actual name used for the variable
is returned. This function is used when generating code originating from
typemaps. For instance, if a typemap declares a local variable, that variable
might have to be renamed if the same typemap is used more than once in the same function.
</blockquote>
<p>
<b><tt>char * Wrapper_new_localv(Wrapper *w, const String_or_char *name,...)</tt></b>
<blockquote>
The same as <tt>Wrapper_new_localv()</tt>, but accepts a NULL-terminated list
of strings as code output.
</blockquote>
<p>
<b><tt>int Wrapper_check_local(Wrapper *w, const String_or_char *name)</tt></b>
<blockquote>
Checks to see if a local variable with name <tt>name</tt> has been declared. Returns 1 if the local is defined, 0 otherwise.
</blockquote>
<h2>Output</h2>
<p>
<b><tt>void Wrapper_print(Wrapper *w, File *f)</tt></b>
<blockquote>
This function is used to format a wrapper function for output. The
formatted wrapper function is emitted to <tt>f</tt> which may be any
file-like object including a <tt>FILE *</tt> object or a <tt>String
*</tt> object. When emitting the wrapper, the code printed to the
wrapper object is automatically formatted. By default, the formatting
is done according to a "pretty printing" style in which lines are split onto
multiple lines and indented according to reasonable C formatting rules. This produces code that is moderately readable should you want to look at the wrapper
code output. An alternative output mode is "compact printing" in which
lines are collected and compacted. This may result in multiple C statements
appearing on the same line. This mode is sometimes used when the size of
a wrapper file is too large for certain compilers. For example, some compilers
might impose a limit of 65536 lines per source file.
</blockquote>
<p>
<b><tt>void Wrapper_compact_print_mode_set(int flag)</tt></b>
<blockquote>
Sets the output mode of the <tt>Wrapper_print()</tt>
function. If <tt>flag</tt> is set to 1, then wrapper code is formatted
to be compact.
</blockquote>
<p>
<b><tt>void Wrapper_pretty_print(String *str, File *f)</tt></b>
<blockquote>
Utility function that reformats a string containing C/C++ code and outputs
it to the file-like object <tt>f</tt>. The formatting process indents the code
and structures it according to reasonable C formatting rules.
</blockquote>
<p>
<b><tt>void Wrapper_compact_print(String *str, File *f)</tt></b>
<blockquote>
Utility function that reformats a string containing C/C++ code and outputs
it to the file-like object <tt>f</tt>. The formatting process tries to
make the code as compact as possible, without going completely overboard. For
example, multiple C statements may be combined onto a single line and braces may be aligned to not use up extra lines.
</blockquote>
<h2>An Example</h2>
Here is a simple example of how these functions are used. Suppose
you wanted to emit the following C function:
<blockquote>
<pre>
void foo(int n) {
int i;
for (i = 0; i &lt; n; i++) {
printf("%d\n", i);
}
}
</pre>
</blockquote>
Here is code that generates the above function:
<blockquote>
<pre>
Wrapper *w = NewWrapper();
Printf(w-&gt;def,"void foo(int n) {");
Wrapper_add_local(w,"n",""); /* parameter n */
Wrapper_add_local(w,"i", "int i;"); /* local i */
Printv(w-&gt;code,"for (i = 0; i &lt; n; i++) {",
"printf(\"%d\n",i);",
"}\n", NIL);
Printf(w-&gt;code,"}\n");
/* Emit wrapper code */
Wrapper_print(w,outf);
DelWrapper(w);
</pre>
</blockquote>
Within different language modules, this process is obviously much more
involved. However, this example shows the basic idea of how C/C++
code is prepared for output.
</body>
</html>