/trunk/Doc/Devel/wrapobj.html
HTML | 223 lines | 188 code | 35 blank | 0 comment | 0 complexity | 96853f591825f0eb8fd20caab4d0cd9a MD5 | raw file
Possible License(s): LGPL-2.1, Cube, GPL-3.0, 0BSD, GPL-2.0
- <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>