API cleanup and documentation (Wrapper objects)
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@9641 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Dave Beazley
parent
9f88801914
commit
5d0c155688
5 changed files with 255 additions and 19 deletions
|
|
@ -20,6 +20,7 @@ The following documentation describe the internal APIs used by SWIG. These may
|
|||
<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>.
|
||||
</ul>
|
||||
|
||||
<hr>
|
||||
|
|
|
|||
223
Doc/Devel/wrapobj.html
Normal file
223
Doc/Devel/wrapobj.html
Normal 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 < n; i++) {
|
||||
printf("%d\n", i);
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
Here is code that generates the above function:
|
||||
|
||||
<blockquote>
|
||||
<pre>
|
||||
Wrapper *w = NewWrapper();
|
||||
Printf(w->def,"void foo(int n) {");
|
||||
Wrapper_add_local(w,"n",""); /* parameter n */
|
||||
Wrapper_add_local(w,"i", "int i;"); /* local i */
|
||||
Printv(w->code,"for (i = 0; i < n; i++) {",
|
||||
"printf(\"%d\n",i);",
|
||||
"}\n", NIL);
|
||||
Printf(w->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>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -238,24 +238,7 @@ extern int ParmList_is_compactdefargs(ParmList *p);
|
|||
|
||||
/* -- Wrapper function Object */
|
||||
|
||||
typedef struct {
|
||||
Hash *localh;
|
||||
String *def;
|
||||
String *locals;
|
||||
String *code;
|
||||
} Wrapper;
|
||||
|
||||
extern Wrapper *NewWrapper();
|
||||
extern void DelWrapper(Wrapper *w);
|
||||
extern void Wrapper_compact_print_mode_set(int flag);
|
||||
extern void Wrapper_pretty_print(String *str, File *f);
|
||||
extern void Wrapper_compact_print(String *str, File *f);
|
||||
extern void Wrapper_print(Wrapper *w, File *f);
|
||||
extern int Wrapper_add_local(Wrapper *w, const String_or_char *name, const String_or_char *decl);
|
||||
extern int Wrapper_add_localv(Wrapper *w, const String_or_char *name, ...);
|
||||
extern int Wrapper_check_local(Wrapper *w, const String_or_char *name);
|
||||
extern char *Wrapper_new_local(Wrapper *w, const String_or_char *name, const String_or_char *decl);
|
||||
extern char *Wrapper_new_localv(Wrapper *w, const String_or_char *name, ...);
|
||||
#include "swigwrap.h"
|
||||
|
||||
/* --- Naming functions --- */
|
||||
|
||||
|
|
|
|||
29
Source/Swig/swigwrap.h
Normal file
29
Source/Swig/swigwrap.h
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
/* -----------------------------------------------------------------------------
|
||||
* See the LICENSE file for information on copyright, usage and redistribution
|
||||
* of SWIG, and the README file for authors - http://www.swig.org/release.html.
|
||||
*
|
||||
* swigwrap.h
|
||||
*
|
||||
* Functions related to wrapper objects.
|
||||
* ----------------------------------------------------------------------------- */
|
||||
|
||||
/* $Id: swig.h 9635 2007-01-12 01:44:16Z beazley $ */
|
||||
|
||||
typedef struct Wrapper {
|
||||
Hash *localh;
|
||||
String *def;
|
||||
String *locals;
|
||||
String *code;
|
||||
} Wrapper;
|
||||
|
||||
extern Wrapper *NewWrapper();
|
||||
extern void DelWrapper(Wrapper *w);
|
||||
extern void Wrapper_compact_print_mode_set(int flag);
|
||||
extern void Wrapper_pretty_print(String *str, File *f);
|
||||
extern void Wrapper_compact_print(String *str, File *f);
|
||||
extern void Wrapper_print(Wrapper *w, File *f);
|
||||
extern int Wrapper_add_local(Wrapper *w, const String_or_char *name, const String_or_char *decl);
|
||||
extern int Wrapper_add_localv(Wrapper *w, const String_or_char *name, ...);
|
||||
extern int Wrapper_check_local(Wrapper *w, const String_or_char *name);
|
||||
extern char *Wrapper_new_local(Wrapper *w, const String_or_char *name, const String_or_char *decl);
|
||||
extern char *Wrapper_new_localv(Wrapper *w, const String_or_char *name, ...);
|
||||
|
|
@ -489,7 +489,7 @@ char *Wrapper_new_local(Wrapper *w, const String_or_char *name, const String_or_
|
|||
|
||||
|
||||
/* -----------------------------------------------------------------------------
|
||||
* Wrapper_add_localv()
|
||||
* Wrapper_new_localv()
|
||||
*
|
||||
* Same as add_local(), but allows a NULL terminated list of strings to be
|
||||
* used as a replacement for decl. This saves the caller the trouble of having
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue