From: <kli...@us...> - 2010-11-26 23:23:32
|
Revision: 12317 http://swig.svn.sourceforge.net/swig/?rev=12317&view=rev Author: klickverbot Date: 2010-11-26 23:23:26 +0000 (Fri, 26 Nov 2010) Log Message: ----------- [D] Document "-d2" switch, native pointer support and D_VERSION=2. Modified Paths: -------------- trunk/Doc/Manual/D.html Modified: trunk/Doc/Manual/D.html =================================================================== --- trunk/Doc/Manual/D.html 2010-11-26 20:32:23 UTC (rev 12316) +++ trunk/Doc/Manual/D.html 2010-11-26 23:23:26 UTC (rev 12317) @@ -27,6 +27,10 @@ <li><a href="#D_exceptions">D Exceptions</a> <li><a href="#D_directors">D Directors</a> <li><a href="#D_other_features">Other features</a> +<ul> +<li><a href="#D_native_pointer_support">Native pointer support</a> +<li><a href="#D_test_suite">Running the test-suite</a> +</ul> <li><a href="#D_typemap_examples">D Typemap examples</a> <li><a href="#D_planned_features">Work in progress and planned features</a> </ul> @@ -53,6 +57,11 @@ <p>To activate the D module, pass the <tt>-d</tt> option to SWIG at the command line. The same standard command line switches as with any other language module are available, plus the following D specific ones:</p> <dl> + <dt><tt>-d2</tt></dt> + <dd> + <p>By default, SWIG generates code for D1/Tango. Use the <tt>-d2</tt> flag to target D2/Phobos instead.</p> + </dd> + <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> @@ -78,6 +87,8 @@ <H3><a name="D_typemap_name_comparison"></a>20.3.1 C# <-> D name comparison</H3> +<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 @@ -367,9 +378,27 @@ <p>The <a href="SWIGPlus.html#SWIGPlus_nspace"><tt>nspace</tt></a> feature of SWIG is not yet supported for D – all class modules are written to the same package, regardless of which C++ namespace they are in.</p> -<p>Support of pointers to primitive types.</p> +<H3><a name="D_native_pointer_support"></a>20.8.1 Native pointer support</H3> + +<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>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> + + +<H3><a name="D_test_suite"></a>20.8.2 Running the test-suite</H3> + + +<p>As with any other language, the SWIG test-suite can be built for D using the <tt>*-d-test-suite</tt> targets of the top-level Makefile. By default, D1 is targeted, to build it with D2, use the optional <tt>D_VERSION</tt> variable, e.g. <tt>make check-d-test-suite D_VERSION=2</tt>.</p> + +<p>Note: If you want to use GDC on Linux or another platform which requires you to link <tt>libdl</tt> for dynamically loading the shared library, you might have to add <tt>-ldl</tt> manually to the <tt>d_compile</tt> target in <tt>Examples/Makefile</tt>, because GDC does not currently honor the <tt>pragma(lib,…)</tt> statement.</p> + + <H2><a name="D_typemap_examples"></a>20.9 D Typemap examples</H2> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <wsf...@us...> - 2011-01-07 20:26:28
|
Revision: 12377 http://swig.svn.sourceforge.net/swig/?rev=12377&view=rev Author: wsfulton Date: 2011-01-07 20:26:21 +0000 (Fri, 07 Jan 2011) Log Message: ----------- Fix most of the html errors in D.html Modified Paths: -------------- trunk/Doc/Manual/D.html Modified: trunk/Doc/Manual/D.html =================================================================== --- trunk/Doc/Manual/D.html 2011-01-07 20:05:44 UTC (rev 12376) +++ trunk/Doc/Manual/D.html 2011-01-07 20:26:21 UTC (rev 12377) @@ -43,7 +43,7 @@ <H2><a name="D_introduction"></a>20.1 Introduction</H2> -<p>From the <a href="http://www.digitalmars.com/d/">D Programming Language</a> web site: <em>»D is a systems programming language. Its focus is on combining the power and high performance of C and C++ with the programmer productivity of modern languages like Ruby and Python. […] The D language is statically typed and compiles directly to machine code.«</em> As such, it is not very surprising that D is able to directly <a href="http://www.digitalmars.com/d/1.0/interfaceToC.html">interface with C libraries</a>. Why would a SWIG module for D be needed then in the first place?</p> +<p>From the <a href="http://www.digitalmars.com/d/">D Programming Language</a> web site: <em>»D is a systems programming language. Its focus is on combining the power and high performance of C and C++ with the programmer productivity of modern languages like Ruby and Python. [...] The D language is statically typed and compiles directly to machine code.«</em> As such, it is not very surprising that D is able to directly <a href="http://www.digitalmars.com/d/1.0/interfaceToC.html">interface with C libraries</a>. Why would a SWIG module for D be needed then in the first place?</p> <p>Well, besides the obvious downside that the C header files have to be manually converted to D modules for this to work, there is one major inconvenience with this approach: D code usually is on a higher abstraction level than C, and many of the features that make D interesting are simply not available when dealing with C libraries, requiring you e.g. to manually convert strings between pointers to <tt>\0</tt>-terminated char arrays and D char arrays, making the algorithms from the D2 standard library unusable with C arrays and data structures, and so on.</p> @@ -182,7 +182,7 @@ <dl> <dt><tt>$dclassname</tt> (C#: <tt>$csclassname</tt>)</dt> <dd> - <p>This special variable works similar to <a href="Typemaps.html#Typemaps_special_variables"><tt>$n_type</tt></a> in that it returns the name of a type – it expands to the D proxy class name of the type being wrapped. If the type does not have an associated proxy class, it expands to the type wrapper class name, for example, <tt>SWIGTYPE_p_p_SomeCppClass</tt> is generated when wrapping <tt>SomeCppClass **</tt>.</p> + <p>This special variable works similar to <a href="Typemaps.html#Typemaps_special_variables"><tt>$n_type</tt></a> in that it returns the name of a type - it expands to the D proxy class name of the type being wrapped. If the type does not have an associated proxy class, it expands to the type wrapper class name, for example, <tt>SWIGTYPE_p_p_SomeCppClass</tt> is generated when wrapping <tt>SomeCppClass **</tt>.</p> <p>There are two other variants available, <tt>$&dclassname</tt> and <tt>$*dclassname</tt>. The former adds a level of indirection, while the latter removes one. For instance, when wrapping <tt>Foo **</tt>, <tt>$*dclassname</tt> would be replaced by the proxy class name corresponding to <tt>Foo *</tt>.</p> </dd> @@ -264,7 +264,7 @@ <p>This causes SWIG to add <tt>AnInterface</tt> and <tt>AnotherInterface</tt> to the base class list of <tt>SomeClass</tt>:</p> <div class="targetlang"><pre> class SomeClass : AnInterface, AnotherInterface { - … + ... } </pre></div> <p>For this to work, <tt>AnInterface</tt> and <tt>AnotherInterface</tt> have to be in scope. If SWIG is not in split proxy mode, this is already the case, but it it is, they have to be added to the import list via the <tt>dimports</tt> typemap. Additionally, the import statement depends on the package SWIG is configured to emit the modules to.</p> @@ -360,7 +360,7 @@ <p>Out of the box, C++ exceptions are fundamentally incompatible to their equivalent in the D world and cannot simply be propagated to a calling D method. There is, however, an easy way to solve this problem: Just catch the exception in the C/C++ wrapper layer, pass the contents to D, and make the wrapper code rethrow the exception in the D world.</p> -<p>The implementation details of this are a bit crude, but the SWIG D module automatically takes care of this, as long as it is able to detect that an exception could potentially be thrown (e.g. because the C++ method has a <tt>throw(…)</tt> exception specification).</p> +<p>The implementation details of this are a bit crude, but the SWIG D module automatically takes care of this, as long as it is able to detect that an exception could potentially be thrown (e.g. because the C++ method has a <tt>throw(...)</tt> exception specification).</p> <p>As this feature is implemented in exactly the same way it is for C#, please see the <a href="CSharp.html#CSharp_exceptions">C# documentation</a> for a more detailed explanation.</p> @@ -377,7 +377,7 @@ <H2><a name="D_other_features"></a>20.8 Other features</H2> -<p>The <a href="SWIGPlus.html#SWIGPlus_nspace"><tt>nspace</tt></a> feature of SWIG is not yet supported for D – all class modules are written to the same package, regardless of which C++ namespace they are in.</p> +<p>The <a href="SWIGPlus.html#SWIGPlus_nspace"><tt>nspace</tt></a> feature of SWIG is not yet supported for D - all class modules are written to the same package, regardless of which C++ namespace they are in.</p> <H3><a name="D_native_pointer_support"></a>20.8.1 Native pointer support</H3> @@ -385,7 +385,7 @@ <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>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>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> @@ -399,9 +399,9 @@ <p>The first key difference is that C++ supports free functions as operators (along with argument-dependent lookup), while D requires operators to be member functions of the class they are operating on. SWIG can only automatically generate wrapping code for member function operators; if you want to use operators defined as free functions in D, you need to handle them manually.</p> -<p>Another set of differences between C++ and D concerns individual operators. For example, there are quite a few operators which are overloadable in C++, but not in D, for example <tt>&&</tt> and <tt>||</tt>, but also <tt>!</tt>, and prefix increment/decrement operators in <a href="http://www.digitalmars.com/d/1.0/operatoroverloading.html">D1</a> resp. their postfix pendants in <a href="http://www.digitalmars.com/d/2.0/operatoroverloading.html">D2</a>.</p> +<p>Another set of differences between C++ and D concerns individual operators. For example, there are quite a few operators which are overloadable in C++, but not in D, for example <tt>&&</tt> and <tt>||</tt>, but also <tt>!</tt>, and prefix increment/decrement operators in <a href="http://www.digitalmars.com/d/1.0/operatoroverloading.html">D1</a> resp. their postfix pendants in <a href="http://www.digitalmars.com/d/2.0/operatoroverloading.html">D2</a>.</p> -<p>There are also some cases where the operators can be translated to D, but the differences in the implementation details are big enough that a rather involved scheme would be required for automatic wrapping them, which has not been implemented yet. This affects, for example, the array subscript operator, <tt>[]</tt>, in combination with assignments – while <tt>operator []</tt> in C++ simply returns a reference which is then written to, D resorts to a separate <tt>opIndexAssign</tt> method –, or implicit casting (which was introduced in D2 via <tt>alias this</tt>). Despite the lack of automatic support, manually handling these cases should be perfectly possible.</p> +<p>There are also some cases where the operators can be translated to D, but the differences in the implementation details are big enough that a rather involved scheme would be required for automatic wrapping them, which has not been implemented yet. This affects, for example, the array subscript operator, <tt>[]</tt>, in combination with assignments - while <tt>operator []</tt> in C++ simply returns a reference which is then written to, D resorts to a separate <tt>opIndexAssign</tt> method -, or implicit casting (which was introduced in D2 via <tt>alias this</tt>). Despite the lack of automatic support, manually handling these cases should be perfectly possible.</p> <H3><a name="D_test_suite"></a>20.8.3 Running the test-suite</H3> @@ -409,7 +409,7 @@ <p>As with any other language, the SWIG test-suite can be built for D using the <tt>*-d-test-suite</tt> targets of the top-level Makefile. By default, D1 is targeted, to build it with D2, use the optional <tt>D_VERSION</tt> variable, e.g. <tt>make check-d-test-suite D_VERSION=2</tt>.</p> -<p>Note: If you want to use GDC on Linux or another platform which requires you to link <tt>libdl</tt> for dynamically loading the shared library, you might have to add <tt>-ldl</tt> manually to the <tt>d_compile</tt> target in <tt>Examples/Makefile</tt>, because GDC does not currently honor the <tt>pragma(lib,…)</tt> statement.</p> +<p>Note: If you want to use GDC on Linux or another platform which requires you to link <tt>libdl</tt> for dynamically loading the shared library, you might have to add <tt>-ldl</tt> manually to the <tt>d_compile</tt> target in <tt>Examples/Makefile</tt>, because GDC does not currently honor the <tt>pragma(lib,...)</tt> statement.</p> <H2><a name="D_typemap_examples"></a>20.9 D Typemap examples</H2> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <wsf...@us...> - 2011-01-08 00:20:04
|
Revision: 12378 http://swig.svn.sourceforge.net/swig/?rev=12378&view=rev Author: wsfulton Date: 2011-01-08 00:19:58 +0000 (Sat, 08 Jan 2011) Log Message: ----------- fixes for html tidy in D.html Modified Paths: -------------- trunk/Doc/Manual/D.html Modified: trunk/Doc/Manual/D.html =================================================================== --- trunk/Doc/Manual/D.html 2011-01-07 20:26:21 UTC (rev 12377) +++ trunk/Doc/Manual/D.html 2011-01-08 00:19:58 UTC (rev 12378) @@ -143,15 +143,15 @@ <p>The full chain of type conversions when a director callback is invoked looks like this:</p> <div class="diagram"><pre> type CPPClass::method(type a) - ↑ ↓ + ↑ ↓ <directorout> <directorin> - ↑ ↓ + ↑ ↓ ctype methodCallback(ctype a) C++ :::::::::::::::::::::::::::::::::::::::::: imtype methodCallback(imtype a) D - ↑ ↓ + ↑ ↓ <ddirectorout> <ddirectorin> - ↑ ↓ + ↑ ↓ dtype DClass.method(dtype a)</pre></div> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <wsf...@us...> - 2011-01-08 23:30:31
|
Revision: 12382 http://swig.svn.sourceforge.net/swig/?rev=12382&view=rev Author: wsfulton Date: 2011-01-08 23:30:25 +0000 (Sat, 08 Jan 2011) Log Message: ----------- ascii 'art' improvement Modified Paths: -------------- trunk/Doc/Manual/D.html Modified: trunk/Doc/Manual/D.html =================================================================== --- trunk/Doc/Manual/D.html 2011-01-08 23:17:23 UTC (rev 12381) +++ trunk/Doc/Manual/D.html 2011-01-08 23:30:25 UTC (rev 12382) @@ -142,17 +142,18 @@ <p>The full chain of type conversions when a director callback is invoked looks like this:</p> - <div class="diagram"><pre> type CPPClass::method(type a) + <div class="diagram"><pre> + type CPPClass::method(type a) + ↑ ↓ + <directorout> <directorin> ↑ ↓ - <directorout> <directorin> - ↑ ↓ - ctype methodCallback(ctype a) C++ - :::::::::::::::::::::::::::::::::::::::::: - imtype methodCallback(imtype a) D - ↑ ↓ - <ddirectorout> <ddirectorin> - ↑ ↓ - dtype DClass.method(dtype a)</pre></div> + ctype methodCallback(ctype a) C++ + ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: + imtype methodCallback(imtype a) D + ↑ ↓ + <ddirectorout> <ddirectorin> + ↑ ↓ + dtype DClass.method(dtype a)</pre></div> <H3><a name="D_typecheck_typemaps"></a>20.3.5 typecheck typemaps</H3> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <kli...@us...> - 2011-01-29 23:03:57
|
Revision: 12411 http://swig.svn.sourceforge.net/swig/?rev=12411&view=rev Author: klickverbot Date: 2011-01-29 23:03:51 +0000 (Sat, 29 Jan 2011) Log Message: ----------- [D] Docs: Cosmetic fix to $imcall HTML anchor name. Modified Paths: -------------- trunk/Doc/Manual/D.html Modified: trunk/Doc/Manual/D.html =================================================================== --- trunk/Doc/Manual/D.html 2011-01-29 21:53:16 UTC (rev 12410) +++ trunk/Doc/Manual/D.html 2011-01-29 23:03:51 UTC (rev 12411) @@ -136,7 +136,7 @@ <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 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_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_imcall"><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>$dcall</tt> and <tt>$winput</tt></a> macros are replaced).</p> @@ -207,7 +207,7 @@ example_im.foo(SomeClass.getCPointer(arg)); }</pre></div></dd> - <dt id="D_wcall"><tt>$imcall</tt> and <tt>$owner</tt> (C#: <tt>$imcall</tt>)</dt> + <dt id="D_imcall"><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>$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> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <kli...@us...> - 2011-01-29 23:04:12
|
Revision: 12412 http://swig.svn.sourceforge.net/swig/?rev=12412&view=rev Author: klickverbot Date: 2011-01-29 23:04:06 +0000 (Sat, 29 Jan 2011) Log Message: ----------- [D] Docs: Mention the "pre", "post" and "terminator" din typemap attributes. Modified Paths: -------------- trunk/Doc/Manual/D.html Modified: trunk/Doc/Manual/D.html =================================================================== --- trunk/Doc/Manual/D.html 2011-01-29 23:03:51 UTC (rev 12411) +++ trunk/Doc/Manual/D.html 2011-01-29 23:04:06 UTC (rev 12412) @@ -134,7 +134,7 @@ <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 intermediary D 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). To inject further parameter processing code before or after the call to the intermediary layer, the <tt>pre</tt>, <tt>post</tt> and <tt>terminator</tt> attributes can be used (please refer to the <a href="CSharp.html#CSharp_date_marshalling">C# date marshalling example</a> for more information on these).</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_imcall"><tt>$imcall</tt> and <tt>$owner</tt></a> macros are replaced).</p> @@ -146,7 +146,7 @@ type CPPClass::method(type a) ↑ ↓ <directorout> <directorin> - ↑ ↓ + ↑ ↓ ctype methodCallback(ctype a) C++ ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: imtype methodCallback(imtype a) D This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |