PageRenderTime 32ms CodeModel.GetById 20ms app.highlight 6ms RepoModel.GetById 1ms app.codeStats 0ms

/trunk/Doc/Devel/wrapobj.html

#
HTML | 223 lines | 188 code | 35 blank | 0 comment | 0 complexity | 96853f591825f0eb8fd20caab4d0cd9a MD5 | raw file
  1<html>
  2<head>
  3<title>Wrapper Objects</title>
  4</head>
  5
  6<body>
  7<center>
  8<h1>Wrapper Objects</h1>
  9
 10<p>
 11David M. Beazley <br>
 12dave-swig@dabeaz.com<br>
 13January 15, 2007<br>
 14
 15</b>
 16</center>
 17
 18<h2>Introduction</h2>
 19
 20This document describes the functions related to management of
 21wrapper objects.  A wrapper object is a low-level
 22data structure used to contain the C/C++ code that is emitted during the
 23wrapping process.  It contains not only the emitted code, but information
 24about local variables.   These objects are a critical component of almost all
 25SWIG target language modules. 
 26
 27<p>
 28The functions described here are declared
 29in <tt>Source/Swig/swigwrap.h</tt>.  This API is considered to be
 30stable.
 31
 32<h2>Creating and Destroying Wrappers</h2>
 33
 34The following functions create and destroy wrapper objects.
 35
 36<p>
 37<b><tt>Wrapper *NewWrapper()</tt></b>
 38
 39<blockquote>
 40Creates a new wrapper object.
 41</blockquote>
 42
 43<p>
 44<b><tt>void DelWrapper(Wrapper *w)</tt></b>
 45<blockquote>
 46Destroys a wrapper object.
 47</blockquote>
 48
 49<h2>Wrapper Objects</h2>
 50
 51The <tt>Wrapper</tt> object returned by <tt>NewWrapper()</tt> has
 52three public attributes.
 53
 54<blockquote><pre>
 55typedef struct Wrapper {
 56    String *def;
 57    String *locals;
 58    String *code;
 59} Wrapper;
 60</pre></blockquote>
 61
 62The <tt>def</tt> attribute is a string that holds the function
 63definition line.  This line declares the function name, return type,
 64and parameters.   Language modules create this declaration by simply printing 
 65the appropriate text into this attribute.
 66
 67<p>
 68The <tt>locals</tt> attribute is a string that holds the code
 69related to any local variables declaration.   Normally, language modules
 70do not emit code to this string directly.  They use <tt>Wrapper_add_local()</tt> or <tt>Wrapper_new_local()</tt> to do this.
 71
 72<p>
 73The <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.
 74
 75<h2>Creating Local Variables</h2>
 76
 77Perhaps the most useful aspect of <tt>Wrapper</tt> objects is the
 78management of local variables.  When creating a wrapper, it is often
 79necessary to emit local variables related to the API of the target
 80language.  In addition to this, typemaps and other aspects of SWIG
 81rely upon their own local variables.  The following functions are used
 82to create local variables, but also provide support for renaming
 83variables in order to avoid name clashes.
 84
 85<p>
 86<b><tt>int Wrapper_add_local(Wrapper *w, const String_or_char *name, const String_or_char *decl)</tt></b>
 87<blockquote>
 88Adds a new local variable to the wrapper object. <tt>name</tt> is the
 89name of the local variable.  <tt>decl</tt> is a string containing the
 90actual variable declaration code.  For example, if you wanted to
 91declare a variable "<tt>int x = 42;</tt>", you would set <tt>name</tt>
 92to <tt>"x"</tt> and
 93<tt>decl</tt> to <tt>"int x = 42;"</tt>.  On success, the text in
 94<tt>decl</tt> is added to the <tt>locals</tt> attribute of <tt>w</tt>
 95and 0 is returned.  -1 is returned if a variable with the given name
 96has already been declared.
 97</blockquote>
 98
 99<p>
100<b><tt>int Wrapper_add_localv(Wrapper *w, const String_or_char *name, ...)</tt></b>
101<blockquote>
102The same as <tt>Wrapper_add_local()</tt> except that instead of
103passing a single string for the declaration, a NULL-terminated list of
104strings can be passed.  These strings are joined together when
105producing the output.  This convention turns out to be fairly useful
106since language modules often create their output into pieces.
107</blockquote>
108
109<p>
110<b><tt>char * Wrapper_new_local(Wrapper *w, const String_or_char *name, const String_or_char *decl)</tt></b>
111<blockquote>
112The same as <tt>Wrapper_add_local()</tt> except that if a local variable
113with the given name already exists, this function picks a new name and adds
114the declaration using the new name.  The actual name used for the variable
115is returned.   This function is used when generating code originating from
116typemaps.  For instance, if a typemap declares a local variable, that variable
117might have to be renamed if the same typemap is used more than once in the same function.
118</blockquote>
119
120<p>
121<b><tt>char * Wrapper_new_localv(Wrapper *w, const String_or_char *name,...)</tt></b>
122<blockquote>
123The same as <tt>Wrapper_new_localv()</tt>, but accepts a NULL-terminated list
124of strings as code output. 
125</blockquote>
126
127<p>
128<b><tt>int Wrapper_check_local(Wrapper *w, const String_or_char *name)</tt></b>
129<blockquote>
130Checks to see if a local variable with name <tt>name</tt> has been declared.  Returns 1 if the local is defined, 0 otherwise.
131</blockquote>
132
133<h2>Output</h2>
134
135<p>
136<b><tt>void Wrapper_print(Wrapper *w, File *f)</tt></b>
137<blockquote>
138This function is used to format a wrapper function for output.  The
139formatted wrapper function is emitted to <tt>f</tt> which may be any
140file-like object including a <tt>FILE *</tt> object or a <tt>String
141*</tt> object.   When emitting the wrapper, the code printed to the
142wrapper object is automatically formatted.  By default, the formatting
143is done according to a "pretty printing" style in which lines are split onto
144multiple lines and indented according to reasonable C formatting rules.   This produces code that is moderately readable should you want to look at the wrapper
145code output.   An alternative output mode is "compact printing" in which
146lines are collected and compacted.   This may result in multiple C statements
147appearing on the same line.   This mode is sometimes used when the size of
148a wrapper file is too large for certain compilers. For example, some compilers
149might impose a limit of 65536 lines per source file.
150</blockquote>
151
152<p>
153<b><tt>void Wrapper_compact_print_mode_set(int flag)</tt></b>
154<blockquote>
155Sets the output mode of the <tt>Wrapper_print()</tt>
156function. If <tt>flag</tt> is set to 1, then wrapper code is formatted
157to be compact.
158</blockquote>
159
160<p>
161<b><tt>void Wrapper_pretty_print(String *str, File *f)</tt></b>
162<blockquote>
163Utility function that reformats a string containing C/C++ code and outputs
164it to the file-like object <tt>f</tt>.   The formatting process indents the code
165and structures it according to reasonable C formatting rules.
166</blockquote>
167
168<p>
169<b><tt>void Wrapper_compact_print(String *str, File *f)</tt></b>
170<blockquote>
171Utility function that reformats a string containing C/C++ code and outputs
172it to the file-like object <tt>f</tt>.   The formatting process tries to
173make the code as compact as possible, without going completely overboard.  For
174example, multiple C statements may be combined onto a single line and braces may be aligned to not use up extra lines.
175</blockquote>
176
177
178<h2>An Example</h2>
179
180Here is a simple example of how these functions are used.  Suppose
181you wanted to emit the following C function:
182
183<blockquote>
184<pre>
185void foo(int n) {
186   int i;
187   for (i = 0; i &lt; n; i++) {
188       printf("%d\n", i);
189   }
190}
191</pre>
192</blockquote>
193
194Here is code that generates the above function:
195
196<blockquote>
197<pre>
198Wrapper *w = NewWrapper();
199Printf(w-&gt;def,"void foo(int n) {");
200Wrapper_add_local(w,"n","");         /* parameter n */
201Wrapper_add_local(w,"i", "int i;");  /* local i */
202Printv(w-&gt;code,"for (i = 0; i &lt; n; i++) {",
203               "printf(\"%d\n",i);",
204               "}\n", NIL);
205Printf(w-&gt;code,"}\n");
206
207/* Emit wrapper code */
208Wrapper_print(w,outf);
209DelWrapper(w);
210</pre>
211</blockquote>
212
213Within different language modules, this process is obviously much more
214involved.  However, this example shows the basic idea of how C/C++
215code is prepared for output.
216
217</body>
218</html>
219
220
221
222
223