Doc/Devel/wrapobj.html - third_party/swig - Git at Google

 <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 &lt; n; i++) {
        printf("%d\n", i);
    }
 }
 </pre>
 </blockquote>

 Here is code that generates the above function:

 <blockquote>
 <pre>
 Wrapper *w = NewWrapper();
 Printf(w-&gt;def,"void foo(int n) {");
 Wrapper_add_local(w,"n","");         /* parameter n */
 Wrapper_add_local(w,"i", "int i;");  /* local i */
 Printv(w-&gt;code,"for (i = 0; i &lt; n; i++) {",
                "printf(\"%d\n",i);",
                "}\n", NIL);
 Printf(w-&gt;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>
	<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>