5d0c155688
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@9641 626c5289-ae23-0410-ae9c-e8d60b6d4f22
223 lines
7.4 KiB
HTML
223 lines
7.4 KiB
HTML
<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>
|
|
|
|
|
|
|
|
|
|
|