| <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> |
| |
| |
| |
| |
| |