[D] Replaced the term "wrap D module" with "intermediary D module" (including names derived from it).
This was suggested by wsfulton on the mailing list in order to bring the D module in line with the C# one, the naming scheme of which is intended to be language-independent. git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@12319 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
David Nadlinger
parent
a22df2eca9
commit
3477a9dff1
19 changed files with 423 additions and 424 deletions
|
|
@ -15,7 +15,7 @@
|
|||
<li><a href="#D_typemaps">Typemaps</a>
|
||||
<ul>
|
||||
<li><a href="#D_typemap_name_comparison">C# <-> D name comparison</a>
|
||||
<li><a href="#D_cwtype_dwtype_dptype">cwtype, dwtype, dptype</a>
|
||||
<li><a href="#D_ctype_imtype_dtype">ctype, imtype, dtype</a>
|
||||
<li><a href="#D_in_out_directorin_direcetorout">in, out, directorin, directorout</a>
|
||||
<li><a href="#D_din_dout_ddirectorin_ddirectorout">din, dout, ddirectorin, ddirectorout</a>
|
||||
<li><a href="#D_typecheck_typemaps">typecheck typemaps</a>
|
||||
|
|
@ -64,18 +64,18 @@
|
|||
|
||||
<dt id="D_splitproxy"><tt>-splitproxy</tt></dt>
|
||||
<dd>
|
||||
<p>By default, SWIG generates two D modules: the <em>proxy</em> module, named like the source module (either specified via the <tt>%module</tt> directive or via the <tt>module</tt> command line switch), which contains all the proxy classes, functions, enums, etc., and the <em>wrap</em> module (named like the proxy module, but suffixed with <tt>_wrap</tt>), which contains all the <tt>extern(C)</tt> function declarations and other private parts only used internally by the proxy module.</p>
|
||||
<p>By default, SWIG generates two D modules: the <em>proxy</em> module, named like the source module (either specified via the <tt>%module</tt> directive or via the <tt>module</tt> command line switch), which contains all the proxy classes, functions, enums, etc., and the <em>intermediary</em> module (named like the proxy module, but suffixed with <tt>_im</tt>), which contains all the <tt>extern(C)</tt> function declarations and other private parts only used internally by the proxy module.</p>
|
||||
<p>If the split proxy mode is enabled by passing this switch at the command line, all proxy classes and enums are emitted to their own D module instead. The main proxy module only contains free functions and constants in this case.</p>
|
||||
</dd>
|
||||
|
||||
<dt><tt>-package <pkg></tt></dt>
|
||||
<dd>
|
||||
<p>By default, the proxy D modules and the wrap D module are written to the root package. Using this option, you can specify another target package instead.</p>
|
||||
<p>By default, the proxy D modules and the intermediary D module are written to the root package. Using this option, you can specify another target package instead.</p>
|
||||
</dd>
|
||||
|
||||
<dt><tt>-wrapperlibrary <wl></tt></dt>
|
||||
<dd>
|
||||
<p>The code SWIG generates to dynamically load the C/C++ wrapper layer looks for a library called <tt>$module_wrap</tt>, just like the wrap D module is. With this switch, you can override the name of the file the wrapper code loads at runtime (the <tt>lib</tt> prefix and the suffix for shared libraries are appended automatically, depending on the OS).</p>
|
||||
<p>The code SWIG generates to dynamically load the C/C++ wrapper layer looks for a library called <tt>$module_wrap</tt> by default. With this switch, you can override the name of the file the wrapper code loads at runtime (the <tt>lib</tt> prefix and the suffix for shared libraries are appended automatically, depending on the OS).</p>
|
||||
<p>This might especially be useful if you want to invoke SWIG several times on separate modules, but compile the resulting code into a single shared library.</p>
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -90,9 +90,9 @@
|
|||
<p>If you already know the SWIG C# module, you might find the following name comparison table useful:</p>
|
||||
|
||||
<div class="diagram"><pre>
|
||||
ctype <-> cwtype
|
||||
imtype <-> dwtype
|
||||
cstype <-> dptype
|
||||
ctype <-> ctype
|
||||
imtype <-> imtype
|
||||
cstype <-> dtype
|
||||
csin <-> din
|
||||
csout <-> dout
|
||||
csdirectorin <-> ddirectorin
|
||||
|
|
@ -110,12 +110,12 @@
|
|||
</pre></div>
|
||||
|
||||
|
||||
<H3><a name="D_cwtype_dwtype_dptype"></a>20.3.2 cwtype, dwtype, dptype</H3>
|
||||
<H3><a name="D_ctype_imtype_dtype"></a>20.3.2 ctype, imtype, dtype</H3>
|
||||
|
||||
|
||||
<p>Mapping of types between the C/C++ library, the C/C++ library wrapper exposing the C functions, the D wrapper module importing these functions and the D proxy code.</p>
|
||||
|
||||
<p>The <tt>cwtype</tt> typemap is used to determine the types to use in the C wrapper functions. The types from the <tt>dwtype</tt> typemap are used in the extern(C) declarations of these functions in the D wrap module. The <tt>dptype</tt> typemap contains the D types used in the D proxy module/class.</p>
|
||||
<p>The <tt>ctype</tt> typemap is used to determine the types to use in the C wrapper functions. The types from the <tt>imtype</tt> typemap are used in the extern(C) declarations of these functions in the intermediary D module. The <tt>dtype</tt> typemap contains the D types used in the D proxy module/class.</p>
|
||||
|
||||
|
||||
<H3><a name="D_in_out_directorin_direcetorout"></a>20.3.3 in, out, directorin, directorout</H3>
|
||||
|
|
@ -123,7 +123,7 @@
|
|||
|
||||
<p>Used for converting between the types for C/C++ and D when generating the code for the wrapper functions (on the C++ side).</p>
|
||||
|
||||
<p>The code from the <tt>in</tt> typemap is used to convert arguments to the C wrapper function to the type used in the wrapped code (<tt>cwtype</tt>->original C++ type), the <tt>out</tt> typemap is utilized to convert values from the wrapped code to wrapper function return types (original C++ type-><tt>cwtype</tt>).</p>
|
||||
<p>The code from the <tt>in</tt> typemap is used to convert arguments to the C wrapper function to the type used in the wrapped code (<tt>ctype</tt>->original C++ type), the <tt>out</tt> typemap is utilized to convert values from the wrapped code to wrapper function return types (original C++ type-><tt>ctype</tt>).</p>
|
||||
|
||||
<p>The <tt>directorin</tt> typemap is used to convert parameters to the type used in the D director callback function, its return value is processed by <tt>directorout</tt> (see below).</p>
|
||||
|
||||
|
|
@ -133,11 +133,11 @@
|
|||
|
||||
<p>Typemaps for code generation in D proxy and type wrapper classes.</p>
|
||||
|
||||
<p id="D_din">The <tt>din</tt> typemap is used for converting function parameter types from the type used in the proxy module or class to the type used in the D wrap module (the <a href="D.html#D_dinput"><tt>$dinput</tt></a> macro is replaced).</p>
|
||||
<p id="D_din">The <tt>din</tt> typemap is used for converting function parameter types from the type used in the proxy module or class to the type used in the intermediary D module (the <a href="D.html#D_dinput"><tt>$dinput</tt></a> macro is replaced).</p>
|
||||
|
||||
<p id="D_dout">The <tt>dout</tt> typemap is used for converting function return values from the return type used in the wrap D module to the type returned by the proxy function. The <tt>$excode</tt> special variable in <tt>dout</tt> typemaps is replaced by the <tt>excode</tt> typemap attribute code if the method can throw any exceptions from unmanaged code, otherwise by nothing (the <a href="D.html#D_wcall"><tt>$wcall</tt> and <tt>$owner</tt></a> macros are replaced).</p>
|
||||
<p id="D_dout">The <tt>dout</tt> typemap is used for converting function return values from the return type used in the intermediary D module to the type returned by the proxy function. The <tt>$excode</tt> special variable in <tt>dout</tt> typemaps is replaced by the <tt>excode</tt> typemap attribute code if the method can throw any exceptions from unmanaged code, otherwise by nothing (the <a href="D.html#D_wcall"><tt>$imcall</tt> and <tt>$owner</tt></a> macros are replaced).</p>
|
||||
|
||||
<p id="D_ddirectorinout">The code from the <tt>ddirectorin</tt> and <tt>ddirectorout</tt> typemaps is used for conversion in director callback functions. Arguments are converted to the type used in the proxy class method they are calling by using the code from <tt>ddirectorin</tt>, the proxy class method return value is converted to the type the C++ code expects via the <tt>ddirectorout</tt> typemap (the <a href="D.html#D_dpcall"><tt>$dpcall</tt> and <tt>$winput</tt></a> macros are replaced).</p>
|
||||
<p id="D_ddirectorinout">The code from the <tt>ddirectorin</tt> and <tt>ddirectorout</tt> typemaps is used for conversion in director callback functions. Arguments are converted to the type used in the proxy class method they are calling by using the code from <tt>ddirectorin</tt>, the proxy class method return value is converted to the type the C++ code expects via the <tt>ddirectorout</tt> typemap (the <a href="D.html#D_dpcall"><tt>$dcall</tt> and <tt>$winput</tt></a> macros are replaced).</p>
|
||||
|
||||
<p>The full chain of type conversions when a director callback is invoked looks like this:</p>
|
||||
|
||||
|
|
@ -145,13 +145,13 @@
|
|||
↑ ↓
|
||||
<directorout> <directorin>
|
||||
↑ ↓
|
||||
cwtype methodCallback(cwtype a) C++
|
||||
ctype methodCallback(ctype a) C++
|
||||
::::::::::::::::::::::::::::::::::::::::::
|
||||
dwtype methodCallback(dwtype a) D
|
||||
imtype methodCallback(imtype a) D
|
||||
↑ ↓
|
||||
<ddirectorout> <ddirectorin>
|
||||
↑ ↓
|
||||
dptype DClass.method(dptype a)</pre></div>
|
||||
dtype DClass.method(dtype a)</pre></div>
|
||||
|
||||
|
||||
<H3><a name="D_typecheck_typemaps"></a>20.3.5 typecheck typemaps</H3>
|
||||
|
|
@ -202,16 +202,16 @@
|
|||
<p>leads to the following D proxy code being generated:</p>
|
||||
<div class="targetlang"><pre>
|
||||
void foo(SomeClass arg) {
|
||||
example_wrap.foo(SomeClass.getCPointer(arg));
|
||||
example_im.foo(SomeClass.getCPointer(arg));
|
||||
}</pre></div></dd>
|
||||
|
||||
<dt id="D_wcall"><tt>$wcall</tt> and <tt>$owner</tt> (C#: <tt>$imcall</tt>)</dt>
|
||||
<dt id="D_wcall"><tt>$imcall</tt> and <tt>$owner</tt> (C#: <tt>$imcall</tt>)</dt>
|
||||
<dd>
|
||||
<p>These variables are used in <tt><a href="D.html#D_dout">dout</a></tt> typemaps. <tt>$wcall</tt> contains the call to the wrapper layer which provides the value to be used, and <tt>$owner</tt> signals if the caller is responsible for managing the object lifetime (that is, if the called method is a constructor or has been marked via <tt>%newobject</tt>).</p>
|
||||
<p>These variables are used in <tt><a href="D.html#D_dout">dout</a></tt> typemaps. <tt>$imcall</tt> contains the call to the intermediary module which provides the value to be used, and <tt>$owner</tt> signals if the caller is responsible for managing the object lifetime (that is, if the called method is a constructor or has been marked via <tt>%newobject</tt>).</p>
|
||||
<p>Consider the following example:</p>
|
||||
<div class="code"><pre>
|
||||
%typemap(dout) SomeClass * {
|
||||
return new SomeClass($wcall, $owner);
|
||||
return new SomeClass($imcall, $owner);
|
||||
}
|
||||
|
||||
%inline %{
|
||||
|
|
@ -224,17 +224,17 @@ void foo(SomeClass arg) {
|
|||
<p>The code generated for <tt>foo()</tt> and <tt>bar()</tt> looks like this:</p>
|
||||
<div class="targetlang"><pre>
|
||||
SomeClass foo() {
|
||||
return new SomeClass(example_wrap.foo(), false);
|
||||
return new SomeClass(example_im.foo(), false);
|
||||
}
|
||||
|
||||
SomeClass bar() {
|
||||
return new SomeClass(example_wrap.bar(), true);
|
||||
return new SomeClass(example_im.bar(), true);
|
||||
}
|
||||
</pre></div>
|
||||
</dd>
|
||||
|
||||
<dt><tt>$dpcall</tt> and <tt>$winput</tt> (C#: <tt>$cscall</tt>, <tt>$iminput</tt>)</dt>
|
||||
<dd id="D_dpcall"><p>These variables are used in the director-specific typemaps <a href="D.html#D_ddirectorinout"><tt>ddirectorin</tt></a> and <a href="D.html#D_ddirectorinout"><tt>ddirectorout</tt></a>. They are more or less the reverse of the <tt>$wcall</tt> and <tt>$dinput</tt> macros: <tt>$dpcall</tt> contains the invocation of the D proxy method of which the return value is to be passed back to C++, <tt>$winput</tt> contains the parameter value from C++.</p></dd>
|
||||
<dt><tt>$dcall</tt> and <tt>$winput</tt> (C#: <tt>$cscall</tt>, <tt>$iminput</tt>)</dt>
|
||||
<dd id="D_dpcall"><p>These variables are used in the director-specific typemaps <a href="D.html#D_ddirectorinout"><tt>ddirectorin</tt></a> and <a href="D.html#D_ddirectorinout"><tt>ddirectorout</tt></a>. They are more or less the reverse of the <tt>$imcall</tt> and <tt>$dinput</tt> macros: <tt>$dcall</tt> contains the invocation of the D proxy method of which the return value is to be passed back to C++, <tt>$winput</tt> contains the parameter value from C++.</p></dd>
|
||||
|
||||
<dt><tt>$excode</tt></dt>
|
||||
<dd><p>This variable is used in <tt>dout</tt> and <tt>dconstructor</tt> typemaps and is filled with the contents of the <tt>excode</tt> typemap attribute if an exception could be thrown from the C++ side. See the <a href="CSharp.html#CSharp_exceptions">C# documentation</a> for details.</p></dd>
|
||||
|
|
@ -248,7 +248,7 @@ SomeClass bar() {
|
|||
<p>This is how the default <tt>dconstructor</tt> typemap looks like (you usually do not want to specify a custom one):</p>
|
||||
<div class="code"><pre>
|
||||
%typemap(dconstructor, excode=SWIGEXCODE,directorconnect="\n swigDirectorConnect();") SWIGTYPE {
|
||||
this($wcall, true);$excode$directorconnect
|
||||
this($imcall, true);$excode$directorconnect
|
||||
}
|
||||
</pre></div>
|
||||
</dd>
|
||||
|
|
@ -280,8 +280,8 @@ $importtype(AnotherInterface)
|
|||
<dt><tt>$module</tt></dt>
|
||||
<dd><p>Expands to the name of the main proxy D module.</p></dd>
|
||||
|
||||
<dt><tt>$wrapdmodule</tt></dt>
|
||||
<dd><p>Contains the fully qualified name of the wrap D module.</p></dd>
|
||||
<dt><tt>$imdmodule</tt></dt>
|
||||
<dd><p>Contains the fully qualified name of the intermediary D module.</p></dd>
|
||||
</dl>
|
||||
|
||||
|
||||
|
|
@ -295,7 +295,7 @@ $importtype(AnotherInterface)
|
|||
<dt><tt>%dmanifestconst</tt> and <tt>%dconstvalue(value)</tt></dt>
|
||||
<dd>
|
||||
<p>Out of the box, SWIG generates accessor methods for C <tt>#defines</tt> and C++ constants. The <tt>%dmanifestconst</tt> directive enables wrapping these constants as D manifest constants (<tt>const</tt> in D1, <tt>enum</tt> in D2).</p>
|
||||
<p>For this to work, the C/C++ code for the constant value must directly compile as D code, though. If this is not the case, you can manually override the expression written to the D wrapper using the <tt>%dconstvalue</tt> directive, passing the new value as parameter.</p>
|
||||
<p>For this to work, the C/C++ code for the constant value must directly compile as D code, though. If this is not the case, you can manually override the expression written to the D proxy module using the <tt>%dconstvalue</tt> directive, passing the new value as parameter.</p>
|
||||
<p>For <tt>enum</tt>s, again <tt>%dconstvalue</tt> can be used to override the value of an enum item if the initializer should not compile in D.</p>
|
||||
</dd>
|
||||
|
||||
|
|
@ -321,11 +321,11 @@ struct A {
|
|||
<p>There are a few SWIG pragmas specific to the D module, which you can use to influence the D code SWIG generates:</p>
|
||||
|
||||
<dl>
|
||||
<dt><tt>%pragma(d) wrapdmodulecode</tt></dt>
|
||||
<dd><p>The passed text (D code) is copied verbatim to the wrap D module. For example, it can be (and is, internally) used to emit additional private helper code for the use by proxy typemaps.</p></dd>
|
||||
<dt><tt>%pragma(d) imdmodulecode</tt></dt>
|
||||
<dd><p>The passed text (D code) is copied verbatim to the intermediary D module. For example, it can be (and is, internally) used to emit additional private helper code for the use by proxy typemaps.</p></dd>
|
||||
|
||||
<dt><tt>%pragma(d) wrapdmoduleimports</tt></dt>
|
||||
<dd><p>Additional code to be emitted to the imports section of the wrap D module (the <a href="D.html#D_importtype">$importtype</a> macro can be used here). You probably want to use this in conjunction with the <tt>wrapdmodulecode</tt> pragma.</p></dd>
|
||||
<dt><tt>%pragma(d) imdmoduleimports</tt></dt>
|
||||
<dd><p>Additional code to be emitted to the imports section of the intermediary D module (the <a href="D.html#D_importtype">$importtype</a> macro can be used here). You probably want to use this in conjunction with the <tt>imdmodulecode</tt> pragma.</p></dd>
|
||||
|
||||
<dt><tt>%pragma(d) proxydmodulecode</tt></dt>
|
||||
<dd><p>Just like <tt>proxydmodulecode</tt>, the argument is copied to the proxy D module (if SWIG is in <a href="D.html#D_splitproxy">split proxy mode</a>, it is emitted to the main proxy D module only).</p></dd>
|
||||
|
|
@ -342,13 +342,13 @@ struct A {
|
|||
|
||||
<dt><tt>%pragma(d) wrapperloadercode</tt></dt>
|
||||
<dd>
|
||||
<p>The D code for loading the wrapper library (it is copied to the wrap D module). The <tt>$wrapperloaderbindcode</tt> variable is replaced by the list of commands for binding the functions from the wrapper library to the symbols in the wrap D module.</p>
|
||||
<p>The D code for loading the wrapper library (it is copied to the intermediary D module). The <tt>$wrapperloaderbindcode</tt> variable is replaced by the list of commands for binding the functions from the wrapper library to the symbols in the intermediary D module.</p>
|
||||
<p>Each time this pragma is specified, the previous value is overwritten.</p>
|
||||
</dd>
|
||||
|
||||
<dt><tt>%pragma(d) wrapperloaderbindcommand</tt></dt>
|
||||
<dd>
|
||||
<p>The D command to use for binding the wrapper functions from the C/C++ library to the symbols in the wrap D module. The <tt>$function</tt> variable contains the name of the D function in the wrap module, the <tt>$symbol</tt> variable is replaced by the name of the symbol in the library.</p>
|
||||
<p>The D command to use for binding the wrapper functions from the C/C++ library to the symbols in the intermediary D module. The <tt>$function</tt> variable contains the name of the D function in the wrap module, the <tt>$symbol</tt> variable is replaced by the name of the symbol in the library.</p>
|
||||
<p>Each time this pragma is specified, the previous value is overwritten.</p>
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
@ -384,11 +384,11 @@ struct A {
|
|||
|
||||
<p>Contrary to many of the scripting languages supported by SWIG, D fully supports C-style pointers. The D module thus includes a custom mechanism to wrap C pointers directly as D pointers where applicable, that is, if the type that is pointed to is represented the same in C and D (on the bit-level), dubbed a »primtive type« below.</p>
|
||||
|
||||
<p>Central to this custom pointer handling scheme are two typemap attributes: the <tt>cprimitive</tt> attribute on the <tt>dptype</tt> typemap and the <tt>nativepointer</tt> attribute on all the typemaps which influence the D side of the code (<tt>dptype</tt>, <tt>din</tt>, <tt>dout</tt>, …). When a D typemap is looked up, the following happens behind the scenes:</p>
|
||||
<p>Central to this custom pointer handling scheme are two typemap attributes: the <tt>cprimitive</tt> attribute on the <tt>dtype</tt> typemap and the <tt>nativepointer</tt> attribute on all the typemaps which influence the D side of the code (<tt>dtype</tt>, <tt>din</tt>, <tt>dout</tt>, …). When a D typemap is looked up, the following happens behind the scenes:</p>
|
||||
|
||||
<p>First, the matching typemap is determined by the usual typemap lookup rules. Then, it is checked if the result has the <tt>nativepointer</tt> attribute set. If it is present, it means that its value should replace the typemap value <em>if and only if</em> the actual type the typemap is looked up for is a primitive type, a pointer to a primitive type (through an arbitrary level of indirections), or a function pointer with only primitive types in its signature.</p>
|
||||
|
||||
<p>To determine if a type should be considered primitive, the <tt>cprimitive</tt> attribute on its <tt>dptype</tt> attribute is used. For example, the <tt>dptype</tt> typemap for <tt>float</tt> has <tt>cprimitive="1"</tt>, so the code from the <tt>nativepointer</tt> attribute is taken into account e.g. for <tt>float **</tt> or the function pointer <tt>float (*)(float *)</tt>.</p>
|
||||
<p>To determine if a type should be considered primitive, the <tt>cprimitive</tt> attribute on its <tt>dtype</tt> attribute is used. For example, the <tt>dtype</tt> typemap for <tt>float</tt> has <tt>cprimitive="1"</tt>, so the code from the <tt>nativepointer</tt> attribute is taken into account e.g. for <tt>float **</tt> or the function pointer <tt>float (*)(float *)</tt>.</p>
|
||||
|
||||
|
||||
<H3><a name="D_test_suite"></a>20.8.2 Running the test-suite</H3>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue