diff options
Diffstat (limited to 'Doc/Manual')
| -rw-r--r-- | Doc/Manual/Android.html | 2 | ||||
| -rw-r--r-- | Doc/Manual/CPlusPlus11.html | 65 | ||||
| -rw-r--r-- | Doc/Manual/CSharp.html | 1 | ||||
| -rw-r--r-- | Doc/Manual/Contents.html | 75 | ||||
| -rw-r--r-- | Doc/Manual/Customization.html | 10 | ||||
| -rw-r--r-- | Doc/Manual/Extending.html | 100 | ||||
| -rw-r--r-- | Doc/Manual/Go.html | 223 | ||||
| -rw-r--r-- | Doc/Manual/Java.html | 19 | ||||
| -rw-r--r-- | Doc/Manual/Javascript.html | 359 | ||||
| -rw-r--r-- | Doc/Manual/Lisp.html | 22 | ||||
| -rw-r--r-- | Doc/Manual/Lua.html | 92 | ||||
| -rw-r--r-- | Doc/Manual/Makefile | 1 | ||||
| -rw-r--r-- | Doc/Manual/Modula3.html | 40 | ||||
| -rw-r--r-- | Doc/Manual/Mzscheme.html | 8 | ||||
| -rw-r--r-- | Doc/Manual/Ocaml.html | 62 | ||||
| -rw-r--r-- | Doc/Manual/Octave.html | 52 | ||||
| -rw-r--r-- | Doc/Manual/Perl5.html | 108 | ||||
| -rw-r--r-- | Doc/Manual/Php.html | 110 | ||||
| -rw-r--r-- | Doc/Manual/Pike.html | 24 | ||||
| -rw-r--r-- | Doc/Manual/Python.html | 277 | ||||
| -rw-r--r-- | Doc/Manual/R.html | 16 | ||||
| -rw-r--r-- | Doc/Manual/Ruby.html | 236 | ||||
| -rw-r--r-- | Doc/Manual/SWIG.html | 9 | ||||
| -rw-r--r-- | Doc/Manual/SWIGPlus.html | 18 | ||||
| -rw-r--r-- | Doc/Manual/Sections.html | 4 | ||||
| -rw-r--r-- | Doc/Manual/Tcl.html | 112 | ||||
| -rw-r--r-- | Doc/Manual/Typemaps.html | 18 |
27 files changed, 1325 insertions, 738 deletions
diff --git a/Doc/Manual/Android.html b/Doc/Manual/Android.html index e62139797..2890e2415 100644 --- a/Doc/Manual/Android.html +++ b/Doc/Manual/Android.html @@ -56,7 +56,7 @@ Add the SDK tools and NDK tools to your path and create a directory somewhere fo <pre> $ export PATH=$HOME/android/android-sdk-linux_x86/tools:$HOME/android/android-sdk-linux_x86/platform-tools:$HOME/android/android-ndk-r6b:$PATH $ mkdir AndroidApps -$ cd AnrdoidApps +$ cd AndroidApps </pre> </div> diff --git a/Doc/Manual/CPlusPlus11.html b/Doc/Manual/CPlusPlus11.html index ce9174254..b7e1d638c 100644 --- a/Doc/Manual/CPlusPlus11.html +++ b/Doc/Manual/CPlusPlus11.html @@ -495,59 +495,59 @@ struct DerivedStruct : BaseStruct { <H3><a name="CPlusPlus11_strongly_typed_enumerations"></a>7.2.13 Strongly typed enumerations</H3> -<p>SWIG parses the new <tt>enum class</tt> syntax and forward declarator for the enums:</p> +<p>SWIG supports strongly typed enumerations and parses the new <tt>enum class</tt> syntax and forward declarator for the enums, such as:</p> <div class="code"><pre> enum class MyEnum : unsigned int; </pre></div> -<p>The strongly typed enumerations are treated the same as the ordinary and anonymous enums. -This is because the required nested class support in SWIG is new and has not yet been incorporated into the wrapping of these strongly typed enum classes. -This is usually not a problem, however, -there may be some name clashes. For example, the following code:</p> +<p> +Strongly typed enums are often used to avoid name clashes such as the following: +</p> <div class="code"><pre> -class Color { - enum class PrintingColors : unsigned int { - Cyan, Magenta, Yellow, Black +struct Color { + enum class RainbowColors : unsigned int { + Red, Orange, Yellow, Green, Blue, Indigo, Violet }; - enum class BasicColors { - Red, Green, Blue + enum class WarmColors { + Yellow, Orange, Red }; - - enum class AllColors { - // produces warnings because of duplicate names - Yellow, Orange, Red, Magenta, Blue, Cyan, Green, Pink, Black, White + + // Note normal enum + enum PrimeColors { + Red=100, Green, Blue }; }; </pre></div> -<p>A workaround is to write these as a series of separate classes containing anonymous enums:</p> +<p> +There are various ways that the target languages handle enums, so it is not possible to precisely state how they are handled in this section. +However, generally, most scripting languages mangle in the strongly typed enumeration's class name, +but do not use any additional mangling for normal enumerations. For example, in Python, the following code +</p> -<div class="code"><pre> -class PrintingColors { - enum : unsigned int { - Cyan, Magenta, Yellow, Black - }; -}; +<div class="targetlang"><pre> +print Color.RainbowColors_Red, Color.WarmColors_Red, Color.Red +</pre></div> -class BasicColors { - enum : unsigned int { - Red, Green, Blue - }; -}; +<p> +results in +</p> -class AllColors { - enum : unsigned int { - Yellow, Orange, Red, Magenta, Blue, Cyan, Green, Pink, Black, White - }; -}; +<div class="shell"><pre> +0 2 100 </pre></div> <p> -Expect to see this improved in a future version of SWIG. +The strongly typed languages often wrap normal enums into an enum class and so treat normal enums and strongly typed enums the same. +The equivalent in Java is: </p> +<div class="targetlang"><pre> +System.out.println(Color.RainbowColors.Red.swigValue() + " " + Color.WarmColors.Red.swigValue() + " " + Color.PrimeColors.Red.swigValue()); +</pre></div> + <H3><a name="CPlusPlus11_double_angle_brackets"></a>7.2.14 Double angle brackets</H3> @@ -611,6 +611,7 @@ The following is an example of an alias template: <div class="code"><pre> template< typename T1, typename T2, int > class SomeType { +public: T1 a; T2 b; int c; diff --git a/Doc/Manual/CSharp.html b/Doc/Manual/CSharp.html index 7f53423fc..ba49fa004 100644 --- a/Doc/Manual/CSharp.html +++ b/Doc/Manual/CSharp.html @@ -1075,6 +1075,7 @@ try { $action } catch (std::out_of_range e) { SWIG_CSharpSetPendingException(SWIG_CSharpApplicationException, e.what()); + return $null; } %} diff --git a/Doc/Manual/Contents.html b/Doc/Manual/Contents.html index 7cf40b95d..51d4edaa4 100644 --- a/Doc/Manual/Contents.html +++ b/Doc/Manual/Contents.html @@ -841,6 +841,7 @@ <div class="sectiontoc"> <ul> <li><a href="Go.html#Go_overview">Overview</a> +<li><a href="Go.html#Go_examples">Examples</a> <li><a href="Go.html#Go_running_swig">Running SWIG with Go</a> <ul> <li><a href="Go.html#Go_commandline">Additional Commandline Options</a> @@ -854,6 +855,7 @@ <li><a href="Go.html#Go_enumerations">Go Enumerations</a> <li><a href="Go.html#Go_classes">Go Classes</a> <ul> +<li><a href="Go.html#Go_class_memory">Go Class Memory Management</a> <li><a href="Go.html#Go_class_inheritance">Go Class Inheritance</a> </ul> <li><a href="Go.html#Go_templates">Go Templates</a> @@ -861,6 +863,7 @@ <li><a href="Go.html#Go_primitive_type_mappings">Default Go primitive type mappings</a> <li><a href="Go.html#Go_output_arguments">Output arguments</a> <li><a href="Go.html#Go_adding_additional_code">Adding additional go code</a> +<li><a href="Go.html#Go_typemaps">Go typemaps</a> </ul> </ul> </div> @@ -1046,7 +1049,49 @@ </div> <!-- INDEX --> -<h3><a href="Lisp.html#Lisp">26 SWIG and Common Lisp</a></h3> +<h3><a href="Javascript.html#Javascript">26 SWIG and Javascript</a></h3> + +<!-- INDEX --> +<div class="sectiontoc"> +<ul> +<li><a href="Javascript.html#Javascript_overview">Overview</a> +<li><a href="Javascript.html#Javascript_preliminaries">Preliminaries</a> +<ul> +<li><a href="Javascript.html#Javascript_running_swig">Running SWIG</a> +<li><a href="Javascript.html#Javascript_running_tests_examples">Running Tests and Examples</a> +<li><a href="Javascript.html#Javascript_known_issues">Known Issues</a> +</ul> +<li><a href="Javascript.html#Javascript_integration">Integration</a> +<ul> +<li><a href="Javascript.html#Javascript_node_extensions">Creating node.js Extensions</a> +<ul> +<li><a href="Javascript.html#Javascript_troubleshooting">Troubleshooting</a> +</ul> +<li><a href="Javascript.html#Javascript_embedded_webkit">Embedded Webkit</a> +<ul> +<li><a href="Javascript.html#Javascript_osx">OSX</a> +<li><a href="Javascript.html#Javascript_gtk">GTK</a> +</ul> +<li><a href="Javascript.html#Javascript_applications_webkit">Creating Applications with node-webkit</a> +</ul> +<li><a href="Javascript.html#Javascript_nn14">Examples</a> +<ul> +<li><a href="Javascript.html#Javascript_simple_example">Simple</a> +<li><a href="Javascript.html#Javascript_class_example">Class</a> +</ul> +<li><a href="Javascript.html#Javascript_implementation">Implementation</a> +<ul> +<li><a href="Javascript.html#Javascript_source_code">Source Code</a> +<li><a href="Javascript.html#Javascript_code_templates">Code Templates</a> +<li><a href="Javascript.html#Javascript_emitter">Emitter</a> +<li><a href="Javascript.html#Javascript_emitter_states">Emitter states</a> +<li><a href="Javascript.html#Javascript_jsc_exceptions">Handling Exceptions in JavascriptCore</a> +</ul> +</ul> +</div> +<!-- INDEX --> + +<h3><a href="Lisp.html#Lisp">27 SWIG and Common Lisp</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1069,7 +1114,7 @@ </div> <!-- INDEX --> -<h3><a href="Lua.html#Lua">27 SWIG and Lua</a></h3> +<h3><a href="Lua.html#Lua">28 SWIG and Lua</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1137,7 +1182,7 @@ </div> <!-- INDEX --> -<h3><a href="Modula3.html#Modula3">28 SWIG and Modula-3</a></h3> +<h3><a href="Modula3.html#Modula3">29 SWIG and Modula-3</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1175,7 +1220,7 @@ </div> <!-- INDEX --> -<h3><a href="Mzscheme.html#Mzscheme">29 SWIG and MzScheme/Racket</a></h3> +<h3><a href="Mzscheme.html#Mzscheme">30 SWIG and MzScheme/Racket</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1187,7 +1232,7 @@ </div> <!-- INDEX --> -<h3><a href="Ocaml.html#Ocaml">30 SWIG and Ocaml</a></h3> +<h3><a href="Ocaml.html#Ocaml">31 SWIG and Ocaml</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1238,7 +1283,7 @@ </div> <!-- INDEX --> -<h3><a href="Octave.html#Octave">31 SWIG and Octave</a></h3> +<h3><a href="Octave.html#Octave">32 SWIG and Octave</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1274,7 +1319,7 @@ </div> <!-- INDEX --> -<h3><a href="Perl5.html#Perl5">32 SWIG and Perl5</a></h3> +<h3><a href="Perl5.html#Perl5">33 SWIG and Perl5</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1350,7 +1395,7 @@ </div> <!-- INDEX --> -<h3><a href="Php.html#Php">33 SWIG and PHP</a></h3> +<h3><a href="Php.html#Php">34 SWIG and PHP</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1373,6 +1418,7 @@ <li><a href="Php.html#Php_nn2_6_2">Constructors and Destructors</a> <li><a href="Php.html#Php_nn2_6_3">Static Member Variables</a> <li><a href="Php.html#Php_nn2_6_4">Static Member Functions</a> +<li><a href="Php.html#Php_nn2_6_5">Specifying Implemented Interfaces</a> </ul> <li><a href="Php.html#Php_nn2_7">PHP Pragmas, Startup and Shutdown code</a> </ul> @@ -1390,7 +1436,7 @@ </div> <!-- INDEX --> -<h3><a href="Pike.html#Pike">34 SWIG and Pike</a></h3> +<h3><a href="Pike.html#Pike">35 SWIG and Pike</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1414,7 +1460,7 @@ </div> <!-- INDEX --> -<h3><a href="Python.html#Python">35 SWIG and Python</a></h3> +<h3><a href="Python.html#Python">36 SWIG and Python</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1525,12 +1571,13 @@ <li><a href="Python.html#Python_nn74">Function annotation</a> <li><a href="Python.html#Python_nn75">Buffer interface</a> <li><a href="Python.html#Python_nn76">Abstract base classes</a> +<li><a href="Python.html#Python_nn77">Byte string output conversion</a> </ul> </ul> </div> <!-- INDEX --> -<h3><a href="R.html#R">36 SWIG and R</a></h3> +<h3><a href="R.html#R">37 SWIG and R</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1546,7 +1593,7 @@ </div> <!-- INDEX --> -<h3><a href="Ruby.html#Ruby">37 SWIG and Ruby</a></h3> +<h3><a href="Ruby.html#Ruby">38 SWIG and Ruby</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1680,7 +1727,7 @@ </div> <!-- INDEX --> -<h3><a href="Tcl.html#Tcl">38 SWIG and Tcl</a></h3> +<h3><a href="Tcl.html#Tcl">39 SWIG and Tcl</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1746,7 +1793,7 @@ </div> <!-- INDEX --> -<h3><a href="Extending.html#Extending">39 Extending SWIG to support new languages</a></h3> +<h3><a href="Extending.html#Extending">40 Extending SWIG to support new languages</a></h3> <!-- INDEX --> <div class="sectiontoc"> diff --git a/Doc/Manual/Customization.html b/Doc/Manual/Customization.html index a0a89c042..8e26a7e8a 100644 --- a/Doc/Manual/Customization.html +++ b/Doc/Manual/Customization.html @@ -485,12 +485,12 @@ variables are replaced with. </tr> <tr> -<td>$parentname</td> +<td>$parentclassname</td> <td>The parent class name (if any) for a method.</td> </tr> <tr> -<td>$parentsymname</td> +<td>$parentclasssymname</td> <td>The target language parent class name (if any) for a method.</td> </tr> @@ -547,7 +547,7 @@ Below shows the expansions for the 1st of the overloaded <tt>something</tt> wrap The <tt>exception.i</tt> library file provides support for creating language independent exceptions in your interfaces. To use it, simply put an "<tt>%include exception.i</tt>" in your interface file. This -creates a function<tt> SWIG_exception()</tt> that can be used to raise +provides a function <tt>SWIG_exception()</tt> that can be used to raise common scripting language exceptions in a portable manner. For example :</p> <div class="code"><pre> @@ -1082,7 +1082,7 @@ For example: <div class="code"> <pre> -%feature("except") void hello(int i=0, double d=0.0) { ... } +%feature("except") hello(int i=0, double d=0.0) { ... } void hello(int i=0, double d=0.0); </pre> </div> @@ -1105,7 +1105,7 @@ If the default arguments are not specified in the feature: <div class="code"> <pre> -%feature("except") void hello(int i, double d) { ... } +%feature("except") hello(int i, double d) { ... } void hello(int i=0, double d=0.0); </pre> </div> diff --git a/Doc/Manual/Extending.html b/Doc/Manual/Extending.html index 5c209bbb5..00302d7b5 100644 --- a/Doc/Manual/Extending.html +++ b/Doc/Manual/Extending.html @@ -6,7 +6,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Extending"></a>39 Extending SWIG to support new languages</H1> +<H1><a name="Extending"></a>40 Extending SWIG to support new languages</H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -75,7 +75,7 @@ -<H2><a name="Extending_nn2"></a>39.1 Introduction</H2> +<H2><a name="Extending_nn2"></a>40.1 Introduction</H2> <p> @@ -91,7 +91,7 @@ Also, this chapter is not meant to be a hand-holding tutorial. As a starting po you should probably look at one of SWIG's existing modules. </p> -<H2><a name="Extending_nn3"></a>39.2 Prerequisites</H2> +<H2><a name="Extending_nn3"></a>40.2 Prerequisites</H2> <p> @@ -121,7 +121,7 @@ obvious, but almost all SWIG directives as well as the low-level generation of wrapper code are driven by C++ datatypes. </p> -<H2><a name="Extending_nn4"></a>39.3 The Big Picture</H2> +<H2><a name="Extending_nn4"></a>40.3 The Big Picture</H2> <p> @@ -158,7 +158,7 @@ role in making the system work. For example, both typemaps and declaration anno based on pattern matching and interact heavily with the underlying type system. </p> -<H2><a name="Extending_nn5"></a>39.4 Execution Model</H2> +<H2><a name="Extending_nn5"></a>40.4 Execution Model</H2> <p> @@ -203,7 +203,7 @@ latter stage of compilation. The next few sections briefly describe some of these stages. </p> -<H3><a name="Extending_nn6"></a>39.4.1 Preprocessing</H3> +<H3><a name="Extending_nn6"></a>40.4.1 Preprocessing</H3> <p> @@ -284,7 +284,7 @@ been expanded as well as everything else that goes into the low-level construction of the wrapper code. </p> -<H3><a name="Extending_nn7"></a>39.4.2 Parsing</H3> +<H3><a name="Extending_nn7"></a>40.4.2 Parsing</H3> <p> @@ -385,7 +385,7 @@ returning a <tt>foo</tt> and taking types <tt>a</tt> and <tt>b</tt> as arguments). </p> -<H3><a name="Extending_nn8"></a>39.4.3 Parse Trees</H3> +<H3><a name="Extending_nn8"></a>40.4.3 Parse Trees</H3> <p> @@ -640,7 +640,7 @@ $ swig -c++ -python -debug-module 4 example.i </pre> </div> -<H3><a name="Extending_nn9"></a>39.4.4 Attribute namespaces</H3> +<H3><a name="Extending_nn9"></a>40.4.4 Attribute namespaces</H3> <p> @@ -659,7 +659,7 @@ that matches the name of the target language. For example, <tt>python:foo</tt> <tt>perl:foo</tt>. </p> -<H3><a name="Extending_nn10"></a>39.4.5 Symbol Tables</H3> +<H3><a name="Extending_nn10"></a>40.4.5 Symbol Tables</H3> <p> @@ -750,7 +750,7 @@ example.i:5. Previous declaration is foo_i(int ) </pre> </div> -<H3><a name="Extending_nn11"></a>39.4.6 The %feature directive</H3> +<H3><a name="Extending_nn11"></a>40.4.6 The %feature directive</H3> <p> @@ -806,7 +806,7 @@ For example, the exception code above is simply stored without any modifications. </p> -<H3><a name="Extending_nn12"></a>39.4.7 Code Generation</H3> +<H3><a name="Extending_nn12"></a>40.4.7 Code Generation</H3> <p> @@ -928,7 +928,7 @@ public : The role of these functions is described shortly. </p> -<H3><a name="Extending_nn13"></a>39.4.8 SWIG and XML</H3> +<H3><a name="Extending_nn13"></a>40.4.8 SWIG and XML</H3> <p> @@ -941,7 +941,7 @@ internal data structures, it may be useful to keep XML in the back of your mind as a model. </p> -<H2><a name="Extending_nn14"></a>39.5 Primitive Data Structures</H2> +<H2><a name="Extending_nn14"></a>40.5 Primitive Data Structures</H2> <p> @@ -987,7 +987,7 @@ typedef Hash Typetab; </pre> </div> -<H3><a name="Extending_nn15"></a>39.5.1 Strings</H3> +<H3><a name="Extending_nn15"></a>40.5.1 Strings</H3> <p> @@ -1128,7 +1128,7 @@ Returns the number of replacements made (if any). </div> -<H3><a name="Extending_nn16"></a>39.5.2 Hashes</H3> +<H3><a name="Extending_nn16"></a>40.5.2 Hashes</H3> <p> @@ -1205,7 +1205,7 @@ Returns the list of hash table keys. </div> -<H3><a name="Extending_nn17"></a>39.5.3 Lists</H3> +<H3><a name="Extending_nn17"></a>40.5.3 Lists</H3> <p> @@ -1294,7 +1294,7 @@ If <tt>t</tt> is not a standard object, it is assumed to be a <tt>char *</tt> and is used to create a String object. </div> -<H3><a name="Extending_nn18"></a>39.5.4 Common operations</H3> +<H3><a name="Extending_nn18"></a>40.5.4 Common operations</H3> The following operations are applicable to all datatypes. @@ -1349,7 +1349,7 @@ objects and report errors. Gets the line number associated with <tt>x</tt>. </div> -<H3><a name="Extending_nn19"></a>39.5.5 Iterating over Lists and Hashes</H3> +<H3><a name="Extending_nn19"></a>40.5.5 Iterating over Lists and Hashes</H3> To iterate over the elements of a list or a hash table, the following functions are used: @@ -1394,7 +1394,7 @@ for (j = First(j); j.item; j= Next(j)) { </div> -<H3><a name="Extending_nn20"></a>39.5.6 I/O</H3> +<H3><a name="Extending_nn20"></a>40.5.6 I/O</H3> Special I/O functions are used for all internal I/O. These operations @@ -1528,7 +1528,7 @@ Printf(f, "%s\n", s); Similarly, the preprocessor and parser all operate on string-files. </p> -<H2><a name="Extending_nn21"></a>39.6 Navigating and manipulating parse trees</H2> +<H2><a name="Extending_nn21"></a>40.6 Navigating and manipulating parse trees</H2> Parse trees are built as collections of hash tables. Each node is a hash table in which @@ -1662,7 +1662,7 @@ Deletes a node from the parse tree. Deletion reconnects siblings and properly u the parent so that sibling nodes are unaffected. </div> -<H2><a name="Extending_nn22"></a>39.7 Working with attributes</H2> +<H2><a name="Extending_nn22"></a>40.7 Working with attributes</H2> <p> @@ -1779,7 +1779,7 @@ the attribute is optional. <tt>Swig_restore()</tt> must always be called after function. </div> -<H2><a name="Extending_nn23"></a>39.8 Type system</H2> +<H2><a name="Extending_nn23"></a>40.8 Type system</H2> <p> @@ -1788,7 +1788,7 @@ pointers, references, and pointers to members. A detailed discussion of type theory is impossible here. However, let's cover the highlights. </p> -<H3><a name="Extending_nn24"></a>39.8.1 String encoding of types</H3> +<H3><a name="Extending_nn24"></a>40.8.1 String encoding of types</H3> <p> @@ -1889,7 +1889,7 @@ make the final type, the two parts are just joined together using string concatenation. </p> -<H3><a name="Extending_nn25"></a>39.8.2 Type construction</H3> +<H3><a name="Extending_nn25"></a>40.8.2 Type construction</H3> <p> @@ -2058,7 +2058,7 @@ Returns the prefix of a type. For example, if <tt>ty</tt> is <tt>ty</tt> is unmodified. </div> -<H3><a name="Extending_nn26"></a>39.8.3 Type tests</H3> +<H3><a name="Extending_nn26"></a>40.8.3 Type tests</H3> <p> @@ -2145,7 +2145,7 @@ Checks if <tt>ty</tt> is a varargs type. Checks if <tt>ty</tt> is a templatized type. </div> -<H3><a name="Extending_nn27"></a>39.8.4 Typedef and inheritance</H3> +<H3><a name="Extending_nn27"></a>40.8.4 Typedef and inheritance</H3> <p> @@ -2247,7 +2247,7 @@ Fully reduces <tt>ty</tt> according to typedef rules. Resulting datatype will consist only of primitive typenames. </div> -<H3><a name="Extending_nn28"></a>39.8.5 Lvalues</H3> +<H3><a name="Extending_nn28"></a>40.8.5 Lvalues</H3> <p> @@ -2284,7 +2284,7 @@ Literal y; // type = 'Literal', ltype='p.char' </pre> </div> -<H3><a name="Extending_nn29"></a>39.8.6 Output functions</H3> +<H3><a name="Extending_nn29"></a>40.8.6 Output functions</H3> <p> @@ -2346,7 +2346,7 @@ SWIG, but is most commonly associated with type-descriptor objects that appear in wrappers (e.g., <tt>SWIGTYPE_p_double</tt>). </div> -<H2><a name="Extending_nn30"></a>39.9 Parameters</H2> +<H2><a name="Extending_nn30"></a>40.9 Parameters</H2> <p> @@ -2445,7 +2445,7 @@ included. Used to emit prototypes. Returns the number of required (non-optional) arguments in <tt>p</tt>. </div> -<H2><a name="Extending_nn31"></a>39.10 Writing a Language Module</H2> +<H2><a name="Extending_nn31"></a>40.10 Writing a Language Module</H2> <p> @@ -2460,7 +2460,7 @@ describes the creation of a minimal Python module. You should be able to extra this to other languages. </p> -<H3><a name="Extending_nn32"></a>39.10.1 Execution model</H3> +<H3><a name="Extending_nn32"></a>40.10.1 Execution model</H3> <p> @@ -2470,7 +2470,7 @@ the parsing of command line options, all aspects of code generation are controll different methods of the <tt>Language</tt> that must be defined by your module. </p> -<H3><a name="Extending_starting_out"></a>39.10.2 Starting out</H3> +<H3><a name="Extending_starting_out"></a>40.10.2 Starting out</H3> <p> @@ -2578,7 +2578,7 @@ that activates your module. For example, <tt>swig -python foo.i</tt>. The messages from your new module should appear. </p> -<H3><a name="Extending_nn34"></a>39.10.3 Command line options</H3> +<H3><a name="Extending_nn34"></a>40.10.3 Command line options</H3> <p> @@ -2637,7 +2637,7 @@ to mark the option as valid. If you forget to do this, SWIG will terminate wit unrecognized command line option error. </p> -<H3><a name="Extending_nn35"></a>39.10.4 Configuration and preprocessing</H3> +<H3><a name="Extending_nn35"></a>40.10.4 Configuration and preprocessing</H3> <p> @@ -2686,7 +2686,7 @@ an implementation file <tt>python.cxx</tt> and a configuration file <tt>python.swg</tt>. </p> -<H3><a name="Extending_nn36"></a>39.10.5 Entry point to code generation</H3> +<H3><a name="Extending_nn36"></a>40.10.5 Entry point to code generation</H3> <p> @@ -2744,7 +2744,7 @@ int Python::top(Node *n) { </pre> </div> -<H3><a name="Extending_nn37"></a>39.10.6 Module I/O and wrapper skeleton</H3> +<H3><a name="Extending_nn37"></a>40.10.6 Module I/O and wrapper skeleton</H3> <!-- please report bugs in this section to mgossage --> @@ -2892,7 +2892,7 @@ functionWrapper : void Shape_y_set(Shape *self,double y) </pre> </div> -<H3><a name="Extending_nn38"></a>39.10.7 Low-level code generators</H3> +<H3><a name="Extending_nn38"></a>40.10.7 Low-level code generators</H3> <!-- please report bugs in this section to mgossage --> @@ -3046,7 +3046,7 @@ but without the typemaps, there is still work to do. </p> -<H3><a name="Extending_configuration_files"></a>39.10.8 Configuration files</H3> +<H3><a name="Extending_configuration_files"></a>40.10.8 Configuration files</H3> <!-- please report bugs in this section to ttn --> @@ -3190,7 +3190,7 @@ politely displays the ignoring language message. </dl> -<H3><a name="Extending_nn40"></a>39.10.9 Runtime support</H3> +<H3><a name="Extending_nn40"></a>40.10.9 Runtime support</H3> <p> @@ -3199,7 +3199,7 @@ Discuss the kinds of functions typically needed for SWIG runtime support (e.g. the SWIG files that implement those functions. </p> -<H3><a name="Extending_nn41"></a>39.10.10 Standard library files</H3> +<H3><a name="Extending_nn41"></a>40.10.10 Standard library files</H3> <p> @@ -3218,7 +3218,7 @@ The following are the minimum that are usually supported: Please copy these and modify for any new language. </p> -<H3><a name="Extending_nn42"></a>39.10.11 User examples</H3> +<H3><a name="Extending_nn42"></a>40.10.11 User examples</H3> <p> @@ -3247,7 +3247,7 @@ during this process, see the section on <a href="#Extending_configuration_files" files</a>. </p> -<H3><a name="Extending_test_suite"></a>39.10.12 Test driven development and the test-suite</H3> +<H3><a name="Extending_test_suite"></a>40.10.12 Test driven development and the test-suite</H3> <p> @@ -3306,7 +3306,7 @@ It is therefore essential that the runtime tests are written in a manner that di but error/exception out with an error message on stderr on failure. </p> -<H4><a name="Extending_running_test_suite"></a>39.10.12.1 Running the test-suite</H4> +<H4><a name="Extending_running_test_suite"></a>40.10.12.1 Running the test-suite</H4> <p> @@ -3498,7 +3498,7 @@ It can be run in the same way as the other language test-suites, replacing [lang The test cases used and the way it works is described in <tt>Examples/test-suite/errors/Makefile.in</tt>. </p> -<H3><a name="Extending_nn43"></a>39.10.13 Documentation</H3> +<H3><a name="Extending_nn43"></a>40.10.13 Documentation</H3> <p> @@ -3530,7 +3530,7 @@ Some topics that you'll want to be sure to address include: if available. </ul> -<H3><a name="Extending_prerequisites"></a>39.10.14 Prerequisites for adding a new language module to the SWIG distribution</H3> +<H3><a name="Extending_prerequisites"></a>40.10.14 Prerequisites for adding a new language module to the SWIG distribution</H3> <p> @@ -3587,7 +3587,7 @@ should be added should there be an area not already covered by the existing tests. </p> -<H3><a name="Extending_coding_style_guidelines"></a>39.10.15 Coding style guidelines</H3> +<H3><a name="Extending_coding_style_guidelines"></a>40.10.15 Coding style guidelines</H3> <p> @@ -3611,7 +3611,7 @@ The generated C/C++ code should also follow this style as close as possible. How should be avoided as unlike the SWIG developers, users will never have consistent tab settings. </p> -<H2><a name="Extending_debugging_options"></a>39.11 Debugging Options</H2> +<H2><a name="Extending_debugging_options"></a>40.11 Debugging Options</H2> <p> @@ -3638,7 +3638,7 @@ There are various command line options which can aid debugging a SWIG interface The complete list of command line options for SWIG are available by running <tt>swig -help</tt>. </p> -<H2><a name="Extending_nn46"></a>39.12 Guide to parse tree nodes</H2> +<H2><a name="Extending_nn46"></a>40.12 Guide to parse tree nodes</H2> <p> @@ -4046,7 +4046,7 @@ extern "X" { ... } declaration. </pre> </div> -<H2><a name="Extending_further_info"></a>39.13 Further Development Information</H2> +<H2><a name="Extending_further_info"></a>40.13 Further Development Information</H2> <p> diff --git a/Doc/Manual/Go.html b/Doc/Manual/Go.html index 93b87a4a4..9a6de9598 100644 --- a/Doc/Manual/Go.html +++ b/Doc/Manual/Go.html @@ -10,6 +10,7 @@ <div class="sectiontoc"> <ul> <li><a href="#Go_overview">Overview</a> +<li><a href="#Go_examples">Examples</a> <li><a href="#Go_running_swig">Running SWIG with Go</a> <ul> <li><a href="#Go_commandline">Additional Commandline Options</a> @@ -23,6 +24,7 @@ <li><a href="#Go_enumerations">Go Enumerations</a> <li><a href="#Go_classes">Go Classes</a> <ul> +<li><a href="#Go_class_memory">Go Class Memory Management</a> <li><a href="#Go_class_inheritance">Go Class Inheritance</a> </ul> <li><a href="#Go_templates">Go Templates</a> @@ -30,6 +32,7 @@ <li><a href="#Go_primitive_type_mappings">Default Go primitive type mappings</a> <li><a href="#Go_output_arguments">Output arguments</a> <li><a href="#Go_adding_additional_code">Adding additional go code</a> +<li><a href="#Go_typemaps">Go typemaps</a> </ul> </ul> </div> @@ -67,7 +70,22 @@ checking and runtime library are not used with Go. This should be borne in mind when reading the rest of the SWIG documentation. </p> -<H2><a name="Go_running_swig"></a>23.2 Running SWIG with Go</H2> +<H2><a name="Go_examples"></a>23.2 Examples</H2> + + +<p> +Working examples can be found here: +</p> +<ul> +<li><a href="https://golang.org/misc/swig">Examples from the Go source tree</a> +<li><a href="https://github.com/swig/swig/tree/master/Examples/go">Examples from the SWIG source tree</a> +</ul> +<p> +The examples in the 2nd link are shipped with the SWIG distribution under the Examples/go directory. +</p> + + +<H2><a name="Go_running_swig"></a>23.3 Running SWIG with Go</H2> <p> @@ -76,7 +94,7 @@ default SWIG will generate code for the gc compilers. To generate code for gccgo, you should also use the <tt>-gccgo</tt> option. </p> -<H3><a name="Go_commandline"></a>23.2.1 Additional Commandline Options</H3> +<H3><a name="Go_commandline"></a>23.3.1 Additional Commandline Options</H3> <p> @@ -150,7 +168,7 @@ swig -go -help </table> -<H3><a name="Go_outputs"></a>23.2.2 Go Output Files</H3> +<H3><a name="Go_outputs"></a>23.3.2 Go Output Files</H3> <p> When generating Go code, SWIG will generate the following @@ -226,7 +244,7 @@ this: % go tool 6l main.6 </pre></div> -<H2><a name="Go_basic_tour"></a>23.3 A tour of basic C/C++ wrapping</H2> +<H2><a name="Go_basic_tour"></a>23.4 A tour of basic C/C++ wrapping</H2> <p> @@ -236,7 +254,7 @@ modifications have to occur. This section briefly covers the essential aspects of this wrapping. </p> -<H3><a name="Go_package"></a>23.3.1 Go Package Name</H3> +<H3><a name="Go_package"></a>23.4.1 Go Package Name</H3> <p> @@ -246,7 +264,7 @@ directive. You may override this by using SWIG's <tt>-package</tt> command line option. </p> -<H3><a name="Go_names"></a>23.3.2 Go Names</H3> +<H3><a name="Go_names"></a>23.4.2 Go Names</H3> <p> @@ -278,7 +296,7 @@ followed by that name, and the destructor will be named <tt>Delete</tt> followed by that name. </p> -<H3><a name="Go_constants"></a>23.3.3 Go Constants</H3> +<H3><a name="Go_constants"></a>23.4.3 Go Constants</H3> <p> @@ -286,7 +304,7 @@ C/C++ constants created via <tt>#define</tt> or the <tt>%constant</tt> directive become Go constants, declared with a <tt>const</tt> declaration. -<H3><a name="Go_enumerations"></a>23.3.4 Go Enumerations</H3> +<H3><a name="Go_enumerations"></a>23.4.4 Go Enumerations</H3> <p> @@ -296,7 +314,7 @@ usual). The values of the enumeration will become variables in Go; code should avoid modifying those variables. </p> -<H3><a name="Go_classes"></a>23.3.5 Go Classes</H3> +<H3><a name="Go_classes"></a>23.4.5 Go Classes</H3> <p> @@ -374,7 +392,43 @@ returns a go interface. If the returned pointer can be null, you can check for this by calling the Swigcptr() method. </p> -<H4><a name="Go_class_inheritance"></a>23.3.5.1 Go Class Inheritance</H4> +<H4><a name="Go_class_memory"></a>23.4.5.1 Go Class Memory Management</H4> + + +<p> +Calling <tt>NewClassName</tt> for some C++ class <tt>ClassName</tt> +will allocate memory using the C++ memory allocator. This memory will +not be automatically freed by Go's garbage collector as the object ownership is +not tracked. When you are done with the C++ object you must free it manually +using <tt>DeleteClassName</tt>. +</p> + +<p> +A common technique is to store the C++ object into a Go object, and +use the Go function <tt>runtime.SetFinalizer</tt> to free the C++ object when +the Go object is freed. It is strongly recommended to read the +<a href="https://golang.org/pkg/runtime/#SetFinalizer">runtime.SetFinalizer</a> +documentation before using this technique to understand its limitations. +For example, if the SWIG package is imported as "wrap": +</p> +<div class="code"> +<pre> +type GoClassName struct { + w wrap.ClassName +} + +func NewGoClassName() *GoClassName { + r := &GoClassName{wrap.NewClassName()} + runtime.SetFinalizer(r, + func(r *GoClassName) { + wrap.DeleteClassName(r.w) + }) + return r +} +</pre> +</div> + +<H4><a name="Go_class_inheritance"></a>23.4.5.2 Go Class Inheritance</H4> <p> @@ -386,7 +440,7 @@ Doing the reverse will require an explicit type assertion, which will be checked dynamically. </p> -<H3><a name="Go_templates"></a>23.3.6 Go Templates</H3> +<H3><a name="Go_templates"></a>23.4.6 Go Templates</H3> <p> @@ -394,7 +448,7 @@ In order to use C++ templates in Go, you must tell SWIG to create wrappers for a particular template instantation. To do this, use the <tt>%template</tt> directive. -<H3><a name="Go_director_classes"></a>23.3.7 Go Director Classes</H3> +<H3><a name="Go_director_classes"></a>23.4.7 Go Director Classes</H3> <p> @@ -437,7 +491,7 @@ method defined in Go. The Go code may of course call other methods on itself, and those methods may be defined either in Go or in C++. </p> -<H3><a name="Go_primitive_type_mappings"></a>23.3.8 Default Go primitive type mappings</H3> +<H3><a name="Go_primitive_type_mappings"></a>23.4.8 Default Go primitive type mappings</H3> <p> @@ -544,7 +598,7 @@ that typemap, or add new values, to control how C/C++ types are mapped into Go types. </p> -<H3><a name="Go_output_arguments"></a>23.3.9 Output arguments</H3> +<H3><a name="Go_output_arguments"></a>23.4.9 Output arguments</H3> <p>Because of limitations in the way output arguments are processed in swig, @@ -597,7 +651,7 @@ void f(char *output); </pre> </div> -<H3><a name="Go_adding_additional_code"></a>23.3.10 Adding additional go code</H3> +<H3><a name="Go_adding_additional_code"></a>23.4.10 Adding additional go code</H3> <p>Often the APIs generated by swig are not very natural in go, especially if @@ -692,5 +746,144 @@ func bar() { </pre> </div> +<H3><a name="Go_typemaps"></a>23.4.11 Go typemaps</H3> + + +<p> +You can use the <tt>%typemap</tt> directive to modify SWIG's default +wrapping behavior for specific C/C++ types. You need to be familiar +with the material in the general +"<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. That chapter +explains how to define a typemap. This section describes some +specific typemaps used for Go. +</p> + +<p> +In general type conversion code may be written either in C/C++ or in +Go. The choice to make normally depends on where memory should be +allocated. To allocate memory controlled by the Go garbage collector, +write Go code. To allocate memory in the C/C++ heap, write C code. +</p> + +<table BORDER summary="Go Typemaps"> +<tr> +<td><b>Typemap</b></td> +<td><b>Description</b></td> +</tr> + +<tr> +<td>gotype</td> +<td> +The Go type to use for a C++ type. This type will appear in the +generated Go wrapper function. If this is not defined SWIG will use a +default as <a href="#Go_primitive_type_mappings">described above</a>. +</td> +</tr> + +<tr> +<td>imtype</td> +<td> +An intermediate Go type used by the "goin", "goout", "godirectorin", +and "godirectorout" typemaps. If this typemap is not defined for a +C/C++ type, the gotype typemape will be used. This is useful when +gotype is best converted to C/C++ using Go code. +</td> +</tr> + +<tr> +<td>goin</td> +<td> +Go code to convert from gotype to imtype when calling a C/C++ +function. SWIG will then internally convert imtype to a C/C++ type +and pass it down. If this is not defined no conversion is done. +</td> +</tr> + +<tr> +<td>in</td> +<td> +C/C++ code to convert the internally generated C/C++ type, based on +imtype, into the C/C++ type that a function call expects. If this is +not defined the value will simply be cast to the desired type. +</td> +</tr> + +<tr> +<td>out</td> +<td> +C/C++ code to convert the C/C++ type that a function call returns into +the internally generated C/C++ type, based on imtype, that will be +returned to Go. If this is not defined the value will simply be cast +to the desired type. +</td> +</tr> + +<tr> +<td>goout</td> +<td> +Go code to convert a value returned from a C/C++ function from imtype +to gotype. If this is not defined no conversion is done. +</td> +</tr> + +<tr> +<td>argout</td> +<td> +C/C++ code to adjust an argument value when returning from a function. +This is called after the real C/C++ function has run. This uses the +internally generated C/C++ type, based on imtype. This is only useful +for a pointer type of some sort. If this is not defined nothing will +be done. +</td> +</tr> + +<tr> +<td>goargout</td> +<td> +Go code to adjust an argument value when returning from a function. +This is called after the real C/C++ function has run. The value will +be in imtype. This is only useful for a pointer type of some sort. +If this is not defined nothing will be done. +</td> +</tr> + +<tr> +<td>directorin</td> +<td> +C/C++ code to convert the C/C++ type used to call a director method +into the internally generated C/C++ type, based on imtype, that will +be passed to Go. If this is not defined the value will simply be cast +to the desired type. +</td> +</tr> + +<tr> +<td>godirectorin</td> +<td> +Go code to convert a value used to call a director method from imtype +to gotype. If this is not defined no conversion is done. +</td> +</tr> + +<tr> +<td>godirectorout</td> +<td> +Go code to convert a value returned from a director method from gotype +to imtype. If this is not defined no conversion is done. +</td> +</tr> + +<tr> +<td>directorout</td> +<td> +C/C++ code to convert a value returned from a director method from the +internally generated C/C++ type, based on imtype, into the type that +the method should return If this is not defined the value will simply +be cast to the desired type. +</td> +</tr> + +</table> + </body> </html> diff --git a/Doc/Manual/Java.html b/Doc/Manual/Java.html index fb8e5d694..3a4f7ee5d 100644 --- a/Doc/Manual/Java.html +++ b/Doc/Manual/Java.html @@ -358,7 +358,7 @@ more aggressive from gcc-4.0 onwards and will result in code that fails with str <p> The name of the shared library output file is important. If the name of your SWIG module is "<tt>example</tt>", the name of the corresponding shared library file should be "<tt>libexample.so</tt>" (or equivalent depending on your machine, see <a href="#Java_dynamic_linking_problems">Dynamic linking problems</a> for more information). -The name of the module is specified using the <tt>%module</tt> directive or<tt> -module</tt> command line option.</p> +The name of the module is specified using the <tt>%module</tt> directive or <tt>-module</tt> command line option.</p> <H3><a name="Java_using_module"></a>25.2.5 Using your module</H3> @@ -2441,7 +2441,7 @@ It also contains all the methods in the C++ class it is proxying plus getters an member variables. These functions call the native methods in the intermediary JNI class. The advantage of having this extra layer is the type safety that the proxy class functions offer. It adds static type checking which leads to fewer surprises at runtime. -For example, you can see that if you attempt to use the <tt> spam() </tt> +For example, you can see that if you attempt to use the <tt>spam()</tt> function it will only compile when the parameters passed are an <tt>int</tt> and a <tt>Foo</tt>. From a user's point of view, it makes the class work as if it were a Java class: </p> @@ -4173,8 +4173,8 @@ void *malloc(size_t nbytes); <p> If no declaration name is given to <tt>%exception</tt>, it is applied to all wrapper functions. -The <tt> $action </tt> is a SWIG special variable and is replaced by the C/C++ function call being wrapped. -The <tt> return $null; </tt> handles all native method return types, namely those that have a void return and those that do not. +The <tt>$action</tt> is a SWIG special variable and is replaced by the C/C++ function call being wrapped. +The <tt>return $null;</tt> handles all native method return types, namely those that have a void return and those that do not. This is useful for typemaps that will be used in native method returning all return types. See the section on <a href="#Java_special_variables">Java special variables</a> for further explanation. @@ -5490,6 +5490,15 @@ These are listed below: <td>Use for mapping NULL terminated arrays of C strings to Java String arrays</td> </tr> +<tr> +<td>unsigned char *</td> +<td>NIOBUFFER</td> +<td>various.i</td> +<td>input<br> output</td> +<td>java.nio.Buffer</td> +<td>Use for mapping directly allocated buffers to c/c++. useful with directors and long lived memory objects</td> +</tr> + </table> <H3><a name="Java_typemap_attributes"></a>25.9.6 Java typemap attributes</H3> @@ -5570,7 +5579,7 @@ This special variable is usually used for making calls to a function in the inte </p> <p> -<b><tt>$null </tt></b><br> +<b><tt>$null</tt></b><br> Used in input typemaps to return early from JNI functions that have either void or a non-void return type. Example: </p> diff --git a/Doc/Manual/Javascript.html b/Doc/Manual/Javascript.html index e589d9d09..cae199048 100644 --- a/Doc/Manual/Javascript.html +++ b/Doc/Manual/Javascript.html @@ -6,21 +6,67 @@ </head> <body> -<H1>SWIG and Javascript</H1> +<H1><a name="Javascript"></a>26 SWIG and Javascript</H1> +<!-- INDEX --> +<div class="sectiontoc"> +<ul> +<li><a href="#Javascript_overview">Overview</a> +<li><a href="#Javascript_preliminaries">Preliminaries</a> +<ul> +<li><a href="#Javascript_running_swig">Running SWIG</a> +<li><a href="#Javascript_running_tests_examples">Running Tests and Examples</a> +<li><a href="#Javascript_known_issues">Known Issues</a> +</ul> +<li><a href="#Javascript_integration">Integration</a> +<ul> +<li><a href="#Javascript_node_extensions">Creating node.js Extensions</a> +<ul> +<li><a href="#Javascript_troubleshooting">Troubleshooting</a> +</ul> +<li><a href="#Javascript_embedded_webkit">Embedded Webkit</a> +<ul> +<li><a href="#Javascript_osx">OSX</a> +<li><a href="#Javascript_gtk">GTK</a> +</ul> +<li><a href="#Javascript_applications_webkit">Creating Applications with node-webkit</a> +</ul> +<li><a href="#Javascript_nn14">Examples</a> +<ul> +<li><a href="#Javascript_simple_example">Simple</a> +<li><a href="#Javascript_class_example">Class</a> +</ul> +<li><a href="#Javascript_implementation">Implementation</a> +<ul> +<li><a href="#Javascript_source_code">Source Code</a> +<li><a href="#Javascript_code_templates">Code Templates</a> +<li><a href="#Javascript_emitter">Emitter</a> +<li><a href="#Javascript_emitter_states">Emitter states</a> +<li><a href="#Javascript_jsc_exceptions">Handling Exceptions in JavascriptCore</a> +</ul> +</ul> +</div> +<!-- INDEX --> + + + <p>This chapter describes SWIG's support of Javascript. It does not cover SWIG basics, but only information that is specific to this module.</p> -<H2>Overview</H2> +<H2><a name="Javascript_overview"></a>26.1 Overview</H2> + + <p>Javascript is a prototype-based scripting language that is dynamic, weakly typed and has first-class functions. Its arguably the most popular language for web development. Javascript has gone beyond being a browser-based scripting language and with <a href="http://nodejs.org">node.js</a>, it is also used as a backend development language.</p> <p>Native Javascript extensions can be used for applications that embed a web-browser view or that embed a Javascript engine (such as <em>node.js</em>). Extending a general purpose web-browser is not possible as this would be a severe security issue.</p> -<p>SWIG Javascript currently supports <strong>JavascriptCore</strong>, the Javascript engine used by <code>Safari/Webkit</code>, and <strong>v8</strong>, which is used by <code>Chromium</code> and <code>node.js</code>.</p> +<p>SWIG Javascript currently supports <strong>JavascriptCore</strong>, the Javascript engine used by <code>Safari/Webkit</code>, and <a href="https://developers.google.com/v8"><strong>v8</strong></a>, which is used by <code>Chromium</code> and <code>node.js</code>.</p> <p><a href="http://www.webkit.org/">WebKit</a> is a modern browser implementation available as open-source which can be embedded into an application. With <a href="https://github.com/rogerwang/node-webkit">node-webkit</a> there is a platform which uses Google's <code>Chromium</code> as Web-Browser widget and <code>node.js</code> for javascript extensions. </p> -<H2>Preliminaries</H2> +<H2><a name="Javascript_preliminaries"></a>26.2 Preliminaries</H2> + + +<H3><a name="Javascript_running_swig"></a>26.2.1 Running SWIG</H3> -<H3>Running SWIG</H3> <p>Suppose that you defined a SWIG module such as the following:</p> <div class="code"> @@ -42,6 +88,12 @@ $ swig -javascript -jsc example.i</pre> <pre> $ swig -c++ -javascript -jsc example.i</pre> </div> +<p>The V8 code that SWIG generates should work with most versions from 3.11.10 up to 3.29.14 and later.</p> +<p>Specify the V8 version when running SWIG (e.g. 3.25.30)</p> +<div class="shell"> +<pre> +$ swig -c++ -javascript -v8 -DV8_VERSION=0x032530 example.i</pre> +</div> <p>This creates a C/C++ source file <code>example_wrap.c</code> or <code>example_wrap.cxx</code>. The generated C source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application to create an extension module.</p> <p>The name of the wrapper file is derived from the name of the input file. For example, if the input file is <code>example.i</code>, the name of the wrapper file is <code>example_wrap.c</code>. To change this, you can use the -o option. The wrapped module will export one function which must be called to register the module with the Javascript interpreter. For example, if your module is named <code>example</code> the corresponding initializer for JavascriptCore would be</p> <div class="code"> @@ -51,13 +103,15 @@ bool example_initialize(JSGlobalContextRef context, JSObjectRef *exports)</pre> <p>and for v8:</p> <div class="code"> <pre> -void example_initialize(v8::Handle<v8::Object> exports)</pre> +void example_initialize(v8::Handle<v8::Object> exports)</pre> </div> <p> -<p><b>Note</b>: be aware that <code>v8</code> has a C++ API, and thus, the generated modules must be compiled as C++.</p> +<b>Note</b>: be aware that <code>v8</code> has a C++ API, and thus, the generated modules must be compiled as C++. </p> -<H3>Running Tests and Examples</H3> +<H3><a name="Javascript_running_tests_examples"></a>26.2.2 Running Tests and Examples</H3> + + <p>The configuration for tests and examples currently supports Linux and Mac only and not MinGW (Windows) yet.</p> <p>The default interpreter is <code>node.js</code> as it is available on all platforms and convenient to use.</p> <p>Running the examples with JavascriptCore requires <code>libjavascriptcoregtk-1.0</code> to be installed, e.g., under Ubuntu with</p> @@ -81,36 +135,37 @@ $ make check-javascript-examples ENGINE=jsc</pre> <pre> $ make check-javascript-test-suite ENGINE=jsc</pre> </div> -<p>Tests should run without any problems, i.e., have been tried out, on the following platforms/interpreters:</p> -<div class="code"> +<p>You can specify a specific <code>V8</code> version for running the examples and tests</p> +<div class="shell"> <pre> -- Ubuntu Precise 12.04 64bit - - JavascriptCore (Webkit 1.8.3) - - Node.js (0.10.26) - - v8 (3.7.12) -- Ubuntu Saucy 13.10 64bit - - JavascriptCore (Webkit 1.10.2) - - Node.js - - v8 (3.14.5) -- Mac OSX Mountain Lion 10.8 - - JavascriptCore (built-in) - - Node.js -- Windows 7 64bit (VS 2010) - - Node.js</pre> +$ make check-javascript-examples V8_VERSION=0x032530 ENGINE=v8</pre> </div> -<p> -<H3>Future work</H3> -<p>The Javascript module is not yet as mature as other modules and some things are still missing. As it makes use of SWIG's Unified Typemap Library (UTL), many typemaps are inherited. We could work on that if requested:</p> +<H3><a name="Javascript_known_issues"></a>26.2.3 Known Issues</H3> + + +<p>At the moment, the Javascript generators pass all tests syntactically, i.e., the generated source code compiles. However, there are still remaining runtime issues.</p> + <ul> -<li><p>More typemaps: compared to other modules there are only a few typemaps implemented. For instance a lot of the <code>std_*.i</code> typemaps are missing, such as <code>std_iostream</code>, for instance.</p></li> -<li><p>Director support: this would allow to extend a C++ abstract base class in Javascript. A pragmatic intermediate step for the most important usecase would be to support Javascript callbacks as arguments.</p></li> + <li><p>Default optional arguments do not work for all targeted interpreters</p></li> + <li><p>Multiple output arguments do not work for JSC</p></li> + <li><p>C89 incompatibily: the JSC generator might still generate C89 violating code</p></li> + <li><p><code>long long</code> is not supported</p></li> + <li><p><code>%native</code> is not supported</p></li> + <li><p>Javascript callbacks are not supported</p></li> + <li><p><code>instanceOf</code> does not work under JSC</p></li> </ul> -<H2>Integration</H2> +<p>The primary development environment has been Linux (Ubuntu 12.04). Windows and OSX have been tested sporadically. Therefore, the generators might have more issues on those platforms. Please report back any problem you observe to help us improving this module quickly.</p> + +<H2><a name="Javascript_integration"></a>26.3 Integration</H2> + + <p>This chapter gives a short introduction how to use a native Javascript extension: as a <code>node.js</code> module, and as an extension for an embedded Webkit.</p> -<H3>Creating <code>node.js</code> Extensions</H3> +<H3><a name="Javascript_node_extensions"></a>26.3.1 Creating node.js Extensions</H3> + + <p>To install <code>node.js</code> you can download an installer from their <a href="https://launchpad.net/~chris-lea/+archive/node.js">web-site</a> for OSX and Windows. For Linux you can either build the source yourself and run <code>sudo checkinstall</code> or keep to the (probably stone-age) packaged version. For Ubuntu there is a <a href="https://launchpad.net/~chris-lea/+archive/node.js/">PPA</a> available.</p> <div class="shell"> <pre> @@ -140,7 +195,7 @@ $ sudo npm install -g node-gyp</pre> <p>First create the wrapper using SWIG:</p> <div class="shell"> <pre> -$ swig -javascript -node -c++ example.cxx</pre> +$ swig -javascript -node -c++ example.i</pre> </div> <p>Then run <code>node-gyp</code></p> <div class="shell"> @@ -154,7 +209,9 @@ require("./build/Release/example")</pre> </div> <p>A more detailed explanation is given in the <a href="#Javascript_examples">Examples</a> section.</p> -<H4>Troubleshooting</H4> +<H4><a name="Javascript_troubleshooting"></a>26.3.1.1 Troubleshooting</H4> + + <ul> <li><em>'module' object has no attribute 'script_main'</em></li> </ul> @@ -164,23 +221,35 @@ require("./build/Release/example")</pre> $ sudo apt-get remove gyp</pre> </div> -<H3>Embedded Webkit</H3> +<H3><a name="Javascript_embedded_webkit"></a>26.3.2 Embedded Webkit</H3> + + <p>Webkit is pre-installed on OSX and available as a library for GTK.</p> -<H4>OSX</H4> +<H4><a name="Javascript_osx"></a>26.3.2.1 OSX</H4> + + <p>There is general information about programming with WebKit on <a href="https://developer.apple.com/library/mac/documentation/cocoa/conceptual/DisplayWebContent/DisplayWebContent.html">Apple Developer Documentation</a>. Details about <code>Cocoa</code> programming are not covered here.</p> <p>An integration of a native extension 'example' would look like this:</p> <div class="code"> <pre> #import "appDelegate.h" -extern bool example_initialize(JSGlobalContextRef context); +extern bool example_initialize(JSGlobalContextRef context, JSObjectRef* exports); @implementation ExampleAppDelegate @synthesize webView; +- (void)addGlobalObject:(JSContextRef) context:(NSString *)objectName:(JSObjectRef) theObject { + JSObjectRef global = JSContextGetGlobalObject(context); + JSStringRef objectJSName = JSStringCreateWithCFString( (CFStringRef) objectName ) + if ( objectJSName != NULL ) { + JSObjectSetProperty(context, global, objectJSName, theObject, kJSPropertyAttributeReadOnly, NULL); + JSStringRelease( objectJSName ); + } +} - (void)applicationDidFinishLaunching:(NSNotification *)aNotification { @@ -191,7 +260,11 @@ extern bool example_initialize(JSGlobalContextRef context); WebFrame *webframe = [webView mainFrame]; JSGlobalContextRef context = [webframe globalContext]; - example_initialize(context); + JSObjectRef example; + example_initialize(context, &example); + [self addGlobalObject:context:@"example":example] + + JSObjectSetProperty(context, global, JSStringRef propertyName, example, JSPropertyAttributes attributes, NULL); [ [webView mainFrame] loadRequest: [NSURLRequest requestWithURL: [NSURL URLWithString:url] ] @@ -201,20 +274,22 @@ extern bool example_initialize(JSGlobalContextRef context); @end</pre> </div> -<H4>GTK</H4> +<H4><a name="Javascript_gtk"></a>26.3.2.2 GTK</H4> + + <p>There is general information about programming GTK at <a href="https://developer.gnome.org/gtk2/">GTK documentation</a> and in the <a href="https://developer.gnome.org/gtk-tutorial">GTK tutorial</a>, and for Webkit there is a <a href="http://webkitgtk.org/reference/webkitgtk/stable/index.html">Webkit GTK+ API Reference</a>.</p> <p>An integration of a native extension 'example' would look like this:</p> <div class="code"> <pre> -#include <gtk/gtk.h> -#include <webkit/webkit.h> +#include <gtk/gtk.h> +#include <webkit/webkit.h> extern bool example_initialize(JSGlobalContextRef context); int main(int argc, char* argv[]) { // Initialize GTK+ - gtk_init(&argc, &argv); + gtk_init(&argc, &argv); ... @@ -222,7 +297,13 @@ int main(int argc, char* argv[]) WebKitWebView *webView = WEBKIT_WEB_VIEW(webkit_web_view_new()); WebFrame *webframe = webkit_web_view_get_main_frame(webView); JSGlobalContextRef context = webkit_web_frame_get_global_context(webFrame); - example_initialize(context); + JSObjectRef global = JSContextGetGlobalObject(context); + + JSObjectRef exampleModule; + example_initialize(context, &exampleModule); + JSStringRef jsName = JSStringCreateWithUTF8CString("example"); + JSObjectSetProperty(context, global, jsName, exampleModule, kJSPropertyAttributeReadOnly, NULL); + JSStringRelease(jsName); ... @@ -238,8 +319,9 @@ int main(int argc, char* argv[]) }</pre> </div> -<H3>Creating Applications with <code>node-webkit</code></H3> -<p> +<H3><a name="Javascript_applications_webkit"></a>26.3.3 Creating Applications with node-webkit</H3> + + <p>To get started with <code>node-webkit</code> there is a very informative set of <a href="https://github.com/rogerwang/node-webkit/wiki">wiki pages</a>.</p> <p>Similar to <code>node.js</code>, <code>node-webkit</code> is started from command line within a <code>node.js</code> project directory. Native extensions are created in the very same way as for <code>node.js</code>, except that a customized <code>gyp</code> derivate has to be used: <a href="https://github.com/rogerwang/nw-gyp">nw-gyp</a>. @@ -262,7 +344,7 @@ A simple example would have the following structure: <p> The configuration file essentially conforms to <code>node.js</code> syntax. -It has some extras to configure <code>node-webkit</code>. See the <a href="">Manifest</a> specification for more details. +It has some extras to configure <code>node-webkit</code>. See the <a href="https://github.com/rogerwang/node-webkit/wiki/Manifest-format">Manifest</a> specification for more details. </p> <p> @@ -271,8 +353,8 @@ It has some extras to configure <code>node-webkit</code>. See the <a href="">Man <div class="code"> <pre> { - "name": "example" - "main": "app.html" + "name": "example", + "main": "app.html", "window": { "show": true, "width": 800, @@ -328,10 +410,14 @@ open new windows, and many more things. };</pre> </div> -<H2><a name="Javascript_examples">Examples</H2> +<H2><a name="Javascript_nn14"></a>26.4 Examples</H2> + + <p>Some basic examples are shown here in more detail.</p> -<H3>Simple</H3> +<H3><a name="Javascript_simple_example"></a>26.4.1 Simple</H3> + + <p>The common example <code>simple</code> looks like this:</p> <div class="code"> <pre> @@ -371,16 +457,17 @@ var x = 42; var y = 105; var g = example.gcd(x,y); -// Accessing the globak variable +// Accessing the global variable var f = example.Foo; example.Foo = 3.1415926;</pre> </div> <p>First the module <code>example</code> is loaded from the previously built extension. Global methods and variables are available in the scope of the module.</p> -<p> + <p><b>Note</b>: ECMAScript 5, the currently implemented Javascript standard, does not have modules. <code>node.js</code> and other implementations provide this mechanism defined by the <a href="http://wiki.commonjs.org/wiki/CommonJS">CommonJS</a> group. For browsers this is provided by <a href="http://browserify.org">Browserify</a>, for instance.</p> -</p> -<H3>Class</H3> +<H3><a name="Javascript_class_example"></a>26.4.2 Class</H3> + + <p>The common example <code>class</code> defines three classes, <code>Shape</code>, <code>Circle</code>, and <code>Square</code>:</p> <div class="code"> <pre> @@ -391,7 +478,7 @@ public: } virtual ~Shape() { nshapes--; - }; + } double x, y; void move(double dx, double dy); virtual double area(void) = 0; @@ -403,7 +490,7 @@ class Circle : public Shape { private: double radius; public: - Circle(double r) : radius(r) { }; + Circle(double r) : radius(r) { } virtual double area(void); virtual double perimeter(void); }; @@ -412,7 +499,7 @@ class Square : public Shape { private: double width; public: - Square(double w) : width(w) { }; + Square(double w) : width(w) { } virtual double area(void); virtual double perimeter(void); };</pre> @@ -455,47 +542,47 @@ new Shape();</pre> <div class="shell"> <pre> $ node -i -> var example = require("./build/Release/example"); +& var example = require("./build/Release/example"); undefined -> var Shape = example.Shape; +& var Shape = example.Shape; undefined -> var Circle = example.Circle; +& var Circle = example.Circle; undefined -> var Square = example.Square; +& var Square = example.Square; undefined -> var c = new Circle(10); +& var c = new Circle(10); undefined -> var s = new Square(10); +& var s = new Square(10); undefined -> Shape.nshapes; +& Shape.nshapes; 2 -> c.x = 20; +& c.x = 20; 20 -> c.y = 30; +& c.y = 30; 30 -> s.x = -10; +& s.x = -10; -10 -> s.y = 5; +& s.y = 5; 5 -> c.area(); +& c.area(); 314.1592653589793 -> c.perimeter(); +& c.perimeter(); 62.83185307179586 -> s.area(); +& s.area(); 100 -> s.perimeter(); +& s.perimeter(); 40 -> c.move(40, 40) +& c.move(40, 40) undefined -> c.x +& c.x 60 -> c.y +& c.y 70 -> new Shape() +& new Shape() Error: Class Shape can not be instantiated at repl:1:2 at REPLServer.self.eval (repl.js:110:21) -at Interface.<anonymous> (repl.js:239:12) +at Interface.<anonymous> (repl.js:239:12) at Interface.EventEmitter.emit (events.js:95:17) at Interface._onLine (readline.js:202:10) at Interface._line (readline.js:531:8) @@ -505,13 +592,17 @@ at ReadStream.EventEmitter.emit (events.js:98:17) at emitKey (readline.js:1095:12)</pre> </div> <p> -<p><b>Note</b>: In ECMAScript 5 there is no concept for classes. Instead each function can be used as a constructor function which is executed by the 'new' operator. Furthermore, during construction the key property <code>prototype</code> of the constructor function is used to attach a prototype instance to the created object. A prototype is essentially an object itself that is the first-class delegate of a class used whenever the access to a property of an object fails. The very same prototype instance is shared among all instances of one type. Prototypal inheritance is explained in more detail on in <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain">Inheritance and the prototype chain</a>, for instance.</p> +<b>Note</b>: In ECMAScript 5 there is no concept for classes. Instead each function can be used as a constructor function which is executed by the 'new' operator. Furthermore, during construction the key property <code>prototype</code> of the constructor function is used to attach a prototype instance to the created object. A prototype is essentially an object itself that is the first-class delegate of a class used whenever the access to a property of an object fails. The very same prototype instance is shared among all instances of one type. Prototypal inheritance is explained in more detail on in <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain">Inheritance and the prototype chain</a>, for instance. </p> -<H2>Implementation</H2> +<H2><a name="Javascript_implementation"></a>26.5 Implementation</H2> + + <p>The Javascript Module implementation has taken a very different approach compared to other language modules in order to support different Javascript interpreters.</p> -<H3>Source Code</H3> +<H3><a name="Javascript_source_code"></a>26.5.1 Source Code</H3> + + <p>The Javascript module is implemented in <code>Source/Modules/javascript.cxx</code>. It dispatches the code generation to a <code>JSEmitter</code> instance, <code>V8Emitter</code> or <code>JSCEmitter</code>. Additionally there are some helpers: <code>Template</code>, for templated code generation, and <code>JSEmitterState</code>, which is used to manage state information during AST traversal. This rough map shall make it easier to find a way through this huge source file:</p> <div class="code"> <pre> @@ -610,7 +701,9 @@ Template::Template(const String *code_) { ... } ...</pre> </div> -<H3>Code Templates</H3> +<H3><a name="Javascript_code_templates"></a>26.5.2 Code Templates</H3> + + <p>All generated code is created on the basis of code templates. The templates for <em>JavascriptCore</em> can be found in <code>Lib/javascript/jsc/javascriptcode.swg</code>, for <em>v8</em> in <code>Lib/javascript/v8/javascriptcode.swg</code>.</p> <p>To track the originating code template for generated code you can run</p> <div class="shell"> @@ -647,7 +740,9 @@ t_register.replace("$jsparent", state.clazz(NAME_MANGLED)) </div> <p><code>Template</code> creates a copy of that string and <code>Template::replace</code> uses Swig's <code>Replaceall</code> to replace variables in the template. <code>Template::trim</code> can be used to eliminate leading and trailing whitespaces. <code>Template::print</code> is used to write the final template string to a Swig <code>DOH</code> (based on <code>Printv</code>). All methods allow chaining.</p> -<H3>Emitter</H3> +<H3><a name="Javascript_emitter"></a>26.5.3 Emitter</H3> + + <p>The Javascript module delegates code generation to a <code>JSEmitter</code> instance. The following extract shows the essential interface:</p> <div class="code"> <pre> @@ -681,7 +776,7 @@ class JSEmitter { */ virtual int exitClass(Node *) { return SWIG_OK; - }; + } /** * Invoked at the beginning of the variableHandler. @@ -693,7 +788,7 @@ class JSEmitter { */ virtual int exitVariable(Node *) { return SWIG_OK; - }; + } /** * Invoked at the beginning of the functionHandler. @@ -705,7 +800,7 @@ class JSEmitter { */ virtual int exitFunction(Node *) { return SWIG_OK; - }; + } /** * Invoked by functionWrapper callback after call to Language::functionWrapper. @@ -730,7 +825,7 @@ class JSEmitter { */ Template getTemplate(const String *name); - State &getState(); + State &getState(); ... @@ -740,12 +835,12 @@ class JSEmitter { <div class="code"> <pre> int JAVASCRIPT::top(Node *n) { - emitter->initialize(n); + emitter->initialize(n); Language::top(n); - emitter->dump(n); - emitter->close(); + emitter->dump(n); + emitter->close(); return SWIG_OK; }</pre> @@ -755,16 +850,18 @@ int JAVASCRIPT::top(Node *n) { <pre> int JAVASCRIPT::classHandler(Node *n) { - emitter->enterClass(n); + emitter->enterClass(n); Language::classHandler(n); - emitter->exitClass(n); + emitter->exitClass(n); return SWIG_OK; }</pre> </div> <p>In <code>enterClass</code> the emitter stores state information that is necessary when processing class members. In <code>exitClass</code> the wrapper code for the whole class is generated.</p> -<H3>Emitter states</H3> +<H3><a name="Javascript_emitter_states"></a>26.5.4 Emitter states</H3> + + <p>For storing information during the AST traversal the emitter provides a <code>JSEmitterState</code> with different slots to store data representing the scopes global, class, function, and variable.</p> <div class="code"> <pre> @@ -804,5 +901,87 @@ state.clazz(RESET); state.clazz(NAME, Getattr(n, "sym:name"));</pre> </div> <p>State information can be retrieved using <code>state.clazz(NAME)</code> or with <code>Getattr</code> on <code>state.clazz()</code> which actually returns a <code>Hash</code> instance.</p> + + +<H3><a name="Javascript_jsc_exceptions"></a>26.5.5 Handling Exceptions in JavascriptCore</H3> + + +<p>Applications with an embedded JavascriptCore should be able to present detailed exception messages that occur in the Javascript engine. Below is an example derived from code provided by Brian Barnes on how these exception details can be extracted.</p> +<div class="code"> +<pre> +void script_exception_to_string(JSContextRef js_context,JSValueRef exception_value_ref,char* return_error_string, int return_error_string_max_length) +{ + JSObjectRef exception_object; + JSValueRef value_ref; + JSStringRef jsstring_property_name = NULL; + JSValueRef temporary_exception = NULL; + JSStringRef js_return_string = NULL; + size_t bytes_needed; + char* c_result_string = NULL; + exception_object = JSValueToObject(js_context, exception_value_ref, NULL); + + /* source url */ + strcpy(return_error_string,"["); + jsstring_property_name = JSStringCreateWithUTF8CString("sourceURL"); + value_ref = JSObjectGetProperty(js_context, exception_object, jsstring_property_name, &temporary_exception); + JSStringRelease(jsstring_property_name); + js_return_string = JSValueToStringCopy(js_context, value_ref, NULL); + bytes_needed = JSStringGetMaximumUTF8CStringSize(js_return_string); + c_result_string = (char*)calloc(bytes_needed, sizeof(char)); + JSStringGetUTF8CString(js_return_string, c_result_string, bytes_needed); + JSStringRelease(js_return_string); + strncat(return_error_string, c_result_string, return_error_string_max_length-1); + free(c_result_string); + + strncat(return_error_string, ":", return_error_string_max_length-1); + + /* line number */ + + jsstring_property_name = JSStringCreateWithUTF8CString("line"); + value_ref = JSObjectGetProperty(js_context, exception_object, jsstring_property_name, &temporary_exception); + JSStringRelease(jsstring_property_name); + js_return_string = JSValueToStringCopy(js_context, value_ref, NULL); + bytes_needed = JSStringGetMaximumUTF8CStringSize(js_return_string); + c_result_string = (char*)calloc(bytes_needed, sizeof(char)); + JSStringGetUTF8CString(js_return_string, c_result_string, bytes_needed); + JSStringRelease(js_return_string); + strncat(return_error_string, c_result_string, return_error_string_max_length-1); + free(c_result_string); + + strncat(return_error_string, "]", return_error_string_max_length-1); + + /* error message */ + + jsstring_property_name = JSStringCreateWithUTF8CString("message"); + value_ref = JSObjectGetProperty(js_context, exception_object, jsstring_property_name, &temporary_exception); + JSStringRelease(jsstring_property_name); + if(NULL == value_ref) + { + strncat(return_error_string, "Unknown Error", return_error_string_max_length-1); + } + else + { + js_return_string = JSValueToStringCopy(js_context, value_ref, NULL); + bytes_needed = JSStringGetMaximumUTF8CStringSize(js_return_string); + c_result_string = (char*)calloc(bytes_needed, sizeof(char)); + JSStringGetUTF8CString(js_return_string, c_result_string, bytes_needed); + JSStringRelease(js_return_string); + strncat(return_error_string, c_result_string, return_error_string_max_length-1); + free(c_result_string); + } +}</pre> +</div> + +<p>It would be used in the following way:</p> +<div class="code"> +<pre> +if(js_exception) +{ + char return_error_string[256]; + script_exception_to_string(js_context, js_exception, return_error_string, 256); + printf("Compile error is %s", return_error_string); +}</pre> +</div> + </body> </html> diff --git a/Doc/Manual/Lisp.html b/Doc/Manual/Lisp.html index 7ea9139ac..0b8d47846 100644 --- a/Doc/Manual/Lisp.html +++ b/Doc/Manual/Lisp.html @@ -6,7 +6,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Lisp"></a>26 SWIG and Common Lisp</H1> +<H1><a name="Lisp"></a>27 SWIG and Common Lisp</H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -41,7 +41,7 @@ Lisp, Common Foreign Function Interface(CFFI), CLisp and UFFI foreign function interfaces. </p> -<H2><a name="Lisp_nn2"></a>26.1 Allegro Common Lisp</H2> +<H2><a name="Lisp_nn2"></a>27.1 Allegro Common Lisp</H2> <p> @@ -50,7 +50,7 @@ <a href="Allegrocl.html#Allegrocl">here</a> </p> -<H2><a name="Lisp_nn3"></a>26.2 Common Foreign Function Interface(CFFI)</H2> +<H2><a name="Lisp_nn3"></a>27.2 Common Foreign Function Interface(CFFI)</H2> <p> @@ -77,7 +77,7 @@ swig -cffi -module <i>module-name</i> <i>file-name</i> files and the various things which you can do with them. </p> -<H3><a name="Lisp_nn4"></a>26.2.1 Additional Commandline Options </H3> +<H3><a name="Lisp_nn4"></a>27.2.1 Additional Commandline Options </H3> <p> @@ -118,7 +118,7 @@ swig -cffi -help </table> -<H3><a name="Lisp_nn5"></a>26.2.2 Generating CFFI bindings</H3> +<H3><a name="Lisp_nn5"></a>27.2.2 Generating CFFI bindings</H3> As we mentioned earlier the ideal way to use SWIG is to use interface @@ -392,7 +392,7 @@ The feature <i>intern_function</i> ensures that all C names are </pre></div> -<H3><a name="Lisp_nn6"></a>26.2.3 Generating CFFI bindings for C++ code</H3> +<H3><a name="Lisp_nn6"></a>27.2.3 Generating CFFI bindings for C++ code</H3> <p>This feature to SWIG (for CFFI) is very new and still far from @@ -568,7 +568,7 @@ If you have any questions, suggestions, patches, etc., related to CFFI module feel free to contact us on the SWIG mailing list, and also please add a "[CFFI]" tag in the subject line. -<H3><a name="Lisp_nn7"></a>26.2.4 Inserting user code into generated files</H3> +<H3><a name="Lisp_nn7"></a>27.2.4 Inserting user code into generated files</H3> <p> @@ -608,7 +608,7 @@ Note that the block <tt>%{ ... %}</tt> is effectively a shortcut for </p> -<H2><a name="Lisp_nn8"></a>26.3 CLISP</H2> +<H2><a name="Lisp_nn8"></a>27.3 CLISP</H2> <p> @@ -638,7 +638,7 @@ swig -clisp -module <i>module-name</i> <i>file-name</i> interface file for the CLISP module. The CLISP module tries to produce code which is both human readable and easily modifyable. </p> -<H3><a name="Lisp_nn9"></a>26.3.1 Additional Commandline Options </H3> +<H3><a name="Lisp_nn9"></a>27.3.1 Additional Commandline Options </H3> <p> @@ -671,7 +671,7 @@ and global variables will be created otherwise only definitions for<br/> </table> -<H3><a name="Lisp_nn10"></a>26.3.2 Details on CLISP bindings</H3> +<H3><a name="Lisp_nn10"></a>27.3.2 Details on CLISP bindings</H3> <p> @@ -795,7 +795,7 @@ struct bar { </pre></div> -<H2><a name="Lisp_nn11"></a>26.4 UFFI </H2> +<H2><a name="Lisp_nn11"></a>27.4 UFFI </H2> </body> diff --git a/Doc/Manual/Lua.html b/Doc/Manual/Lua.html index c67e08834..61f19be68 100644 --- a/Doc/Manual/Lua.html +++ b/Doc/Manual/Lua.html @@ -6,7 +6,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Lua"></a>27 SWIG and Lua</H1> +<H1><a name="Lua"></a>28 SWIG and Lua</H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -82,14 +82,14 @@ Lua is an extension programming language designed to support general procedural eLua stands for Embedded Lua (can be thought of as a flavor of Lua) and offers the full implementation of the Lua programming language to the embedded world, extending it with specific features for efficient and portable software embedded development. eLua runs on smaller devices like microcontrollers and provides the full features of the regular Lua desktop version. More information on eLua can be found here: <a href="http://www.eluaproject.net">http://www.eluaproject.net</a> </p> -<H2><a name="Lua_nn2"></a>27.1 Preliminaries</H2> +<H2><a name="Lua_nn2"></a>28.1 Preliminaries</H2> <p> The current SWIG implementation is designed to work with Lua 5.0.x, 5.1.x and 5.2.x. It should work with later versions of Lua, but certainly not with Lua 4.0 due to substantial API changes. It is possible to either static link or dynamic link a Lua module into the interpreter (normally Lua static links its libraries, as dynamic linking is not available on all platforms). SWIG also has support for eLua starting from eLua 0.8. Due to substantial changes between SWIG 2.x and SWIG 3.0 and unavailability of testing platform, eLua status was downgraded to 'experimental'. </p> -<H2><a name="Lua_nn3"></a>27.2 Running SWIG</H2> +<H2><a name="Lua_nn3"></a>28.2 Running SWIG</H2> <p> @@ -137,7 +137,7 @@ $ swig -lua -eluac example.i The <tt>-elua</tt> option puts all the C function wrappers and variable get/set wrappers in rotables. It also generates a metatable which will control the access to these variables from eLua. It also offers a significant amount of module size compression. On the other hand, the <tt>-eluac</tt> option puts all the wrappers in a single rotable. With this option, no matter how huge the module, it will consume no additional microcontroller SRAM (crass compression). There is a catch though: Metatables are not generated with <tt>-eluac</tt>. To access any value from eLua, one must directly call the wrapper function associated with that value. </p> -<H3><a name="Lua_commandline"></a>27.2.1 Additional command line options</H3> +<H3><a name="Lua_commandline"></a>28.2.1 Additional command line options</H3> <p> @@ -178,7 +178,7 @@ swig -lua -help </tr> </table> -<H3><a name="Lua_nn4"></a>27.2.2 Compiling and Linking and Interpreter</H3> +<H3><a name="Lua_nn4"></a>28.2.2 Compiling and Linking and Interpreter</H3> <p> @@ -249,7 +249,7 @@ LUALIB_API int ( luaopen_mod )(lua_State *L ); More information on building and configuring eLua can be found here: <a href="http://www.eluaproject.net/doc/v0.8/en_building.html">http://www.eluaproject.net/doc/v0.8/en_building.html</a> </p> -<H3><a name="Lua_nn5"></a>27.2.3 Compiling a dynamic module</H3> +<H3><a name="Lua_nn5"></a>28.2.3 Compiling a dynamic module</H3> <p> @@ -317,7 +317,7 @@ Is quite obvious (Go back and consult the Lua documents on how to enable loadlib -<H3><a name="Lua_nn6"></a>27.2.4 Using your module</H3> +<H3><a name="Lua_nn6"></a>28.2.4 Using your module</H3> <p> @@ -335,19 +335,19 @@ $ ./my_lua > </pre></div> -<H2><a name="Lua_nn7"></a>27.3 A tour of basic C/C++ wrapping</H2> +<H2><a name="Lua_nn7"></a>28.3 A tour of basic C/C++ wrapping</H2> <p> By default, SWIG tries to build a very natural Lua interface to your C/C++ code. This section briefly covers the essential aspects of this wrapping. </p> -<H3><a name="Lua_nn8"></a>27.3.1 Modules</H3> +<H3><a name="Lua_nn8"></a>28.3.1 Modules</H3> <p> The SWIG module directive specifies the name of the Lua module. If you specify `module example', then everything is wrapped into a Lua table 'example' containing all the functions and variables. When choosing a module name, make sure you don't use the same name as a built-in Lua command or standard module name. </p> -<H3><a name="Lua_nn9"></a>27.3.2 Functions</H3> +<H3><a name="Lua_nn9"></a>28.3.2 Functions</H3> <p> @@ -388,7 +388,7 @@ It is also possible to rename the module with an assignment. 24 </pre></div> -<H3><a name="Lua_nn10"></a>27.3.3 Global variables</H3> +<H3><a name="Lua_nn10"></a>28.3.3 Global variables</H3> <p> @@ -476,7 +476,7 @@ If you have used the <tt>-eluac</tt> option for your eLua module, you will have In general, functions of the form <tt>"variable_get()"</tt> and <tt>"variable_set()"</tt> are automatically generated by SWIG for use with <tt>-eluac</tt>. </p> -<H3><a name="Lua_nn11"></a>27.3.4 Constants and enums</H3> +<H3><a name="Lua_nn11"></a>28.3.4 Constants and enums</H3> <p> @@ -511,7 +511,7 @@ If you're using eLua and have used <tt>-elua</tt> or <tt>-eluac</tt> to generate Hello World </pre></div> -<H4><a name="Lua_nn13"></a>27.3.4.1 Constants/enums and classes/structures</H4> +<H4><a name="Lua_nn13"></a>28.3.4.1 Constants/enums and classes/structures</H4> <p> @@ -567,7 +567,7 @@ If the <tt>-no-old-metatable-bindings</tt> option is used, then these old-style It is worth mentioning, that <tt>example.Test.TEST1</tt> and <tt>example.Test_TEST1</tt> are different entities and changing one does not change the other. Given the fact that these are constantes and they are not supposed to be changed, it is up to you to avoid such issues. </p> -<H3><a name="Lua_nn12"></a>27.3.5 Pointers</H3> +<H3><a name="Lua_nn12"></a>28.3.5 Pointers</H3> <p> @@ -605,7 +605,7 @@ Lua enforces the integrity of its userdata, so it is virtually impossible to cor nil </pre></div> -<H3><a name="Lua_structures"></a>27.3.6 Structures</H3> +<H3><a name="Lua_structures"></a>28.3.6 Structures</H3> <p> @@ -709,7 +709,7 @@ For eLua with the <tt>-eluac</tt> option, structure manipulation has to be perfo In general, functions of the form <tt>"new_struct()"</tt>, <tt>"struct_member_get()"</tt>, <tt>"struct_member_set()"</tt> and <tt>"free_struct()"</tt> are automatically generated by SWIG for each structure defined in C. (Please note: This doesn't apply for modules generated with the <tt>-elua</tt> option) </p> -<H3><a name="Lua_nn14"></a>27.3.7 C++ classes</H3> +<H3><a name="Lua_nn14"></a>28.3.7 C++ classes</H3> <p> @@ -784,7 +784,7 @@ Both style names are generated by default now. However, if the <tt>-no-old-metatable-bindings</tt> option is used, then the backward compatible names are not generated in addition to ordinary ones. </p> -<H3><a name="Lua_nn15"></a>27.3.8 C++ inheritance</H3> +<H3><a name="Lua_nn15"></a>28.3.8 C++ inheritance</H3> <p> @@ -809,7 +809,7 @@ then the function <tt>spam()</tt> accepts a Foo pointer or a pointer to any clas <p> It is safe to use multiple inheritance with SWIG. </p> -<H3><a name="Lua_nn16"></a>27.3.9 Pointers, references, values, and arrays</H3> +<H3><a name="Lua_nn16"></a>28.3.9 Pointers, references, values, and arrays</H3> <p> @@ -840,7 +840,7 @@ Foo spam7(); <p> then all three functions will return a pointer to some Foo object. Since the third function (spam7) returns a value, newly allocated memory is used to hold the result and a pointer is returned (Lua will release this memory when the return value is garbage collected). The other two are pointers which are assumed to be managed by the C code and so will not be garbage collected. </p> -<H3><a name="Lua_nn17"></a>27.3.10 C++ overloaded functions</H3> +<H3><a name="Lua_nn17"></a>28.3.10 C++ overloaded functions</H3> <p> @@ -926,7 +926,7 @@ Please refer to the "SWIG and C++" chapter for more information about overloadin <p> Dealing with the Lua coercion mechanism, the priority is roughly (integers, floats, strings, userdata). But it is better to rename the functions rather than rely upon the ordering. </p> -<H3><a name="Lua_nn18"></a>27.3.11 C++ operators</H3> +<H3><a name="Lua_nn18"></a>28.3.11 C++ operators</H3> <p> @@ -993,7 +993,7 @@ The current list of operators which can be overloaded (and the alternative funct <li><tt>__unm__</tt> unary minus <li><tt>__call__</tt> operator<tt>()</tt> (often used in functor classes) <li><tt>__pow__</tt> the exponential fn (no C++ equivalent, Lua uses <tt>^</tt>) -<li><tt>__concat__</tt> the concatenation operator (SWIG maps C++'s <tt>~</tt> to Lua's <tt>..</tt>) +<li><tt>__concat__</tt> the concatenation operator (Lua's <tt>..</tt>) <li><tt>__eq__</tt> operator<tt>==</tt> <li><tt>__lt__</tt> operator<tt><</tt> <li><tt>__le__</tt> operator<tt><=</tt> @@ -1058,9 +1058,9 @@ operators and pseudo-operators):</p> <li><tt>__setitem__</tt> <li><tt>__tostring</tt> used internally by Lua for tostring() function. __str__ is mapped to this function </ul> -<p>No other lua metafunction is inherited. For example, __gc is not inherited and must be redefined in every class. <tt>__tostring</tt> is subject to a special handling. If absent in class and in class bases, a default one will be provided by SWIG</p> +<p>No other lua metafunction is inherited. For example, __gc is not inherited and must be redefined in every class. <tt>__tostring</tt> is subject to a special handling. If absent in class and in class bases, a default one will be provided by SWIG. </p> -<H3><a name="Lua_nn19"></a>27.3.12 Class extension with %extend</H3> +<H3><a name="Lua_nn19"></a>28.3.12 Class extension with %extend</H3> <p> @@ -1116,7 +1116,7 @@ true Extend works with both C and C++ code, on classes and structs. It does not modify the underlying object in any way---the extensions only show up in the Lua interface. The only item to take note of is the code has to use the '$self' instead of 'this', and that you cannot access protected/private members of the code (as you are not officially part of the class). </p> -<H3><a name="Lua_nn20"></a>27.3.13 Using %newobject to release memory</H3> +<H3><a name="Lua_nn20"></a>28.3.13 Using %newobject to release memory</H3> <p> If you have a function that allocates memory like this,</p> @@ -1140,7 +1140,7 @@ char *foo(); </div> <p> This will release the allocated memory.</p> -<H3><a name="Lua_nn21"></a>27.3.14 C++ templates</H3> +<H3><a name="Lua_nn21"></a>28.3.14 C++ templates</H3> <p> @@ -1175,7 +1175,7 @@ In Lua: <p> Obviously, there is more to template wrapping than shown in this example. More details can be found in the SWIG and C++ chapter. Some more complicated examples will appear later. </p> -<H3><a name="Lua_nn22"></a>27.3.15 C++ Smart Pointers</H3> +<H3><a name="Lua_nn22"></a>28.3.15 C++ Smart Pointers</H3> <p> @@ -1227,7 +1227,7 @@ If you ever need to access the underlying pointer returned by <tt>operator->( > f = p:__deref__() -- Returns underlying Foo * </pre></div> -<H3><a name="Lua_nn23"></a>27.3.16 C++ Exceptions</H3> +<H3><a name="Lua_nn23"></a>28.3.16 C++ Exceptions</H3> <p> @@ -1370,7 +1370,7 @@ and the "<a href="Customization.html#Customization_exception">Exception handling add exception specification to functions or globally (respectively). </p> -<H3><a name="Lua_namespaces"></a>27.3.17 Namespaces </H3> +<H3><a name="Lua_namespaces"></a>28.3.17 Namespaces </H3> <p> @@ -1421,7 +1421,7 @@ Now, from Lua usage is as follows: 19 > </pre></div> -<H4><a name="Lua_nn27"></a>27.3.17.1 Compatibility Note </H4> +<H4><a name="Lua_nn27"></a>28.3.17.1 Compatibility Note </H4> <p> @@ -1437,7 +1437,7 @@ If SWIG is running in a backwards compatible way, i.e. without the <tt>-no-old-m </pre></div> -<H4><a name="Lua_nn29"></a>27.3.17.2 Names </H4> +<H4><a name="Lua_nn29"></a>28.3.17.2 Names </H4> <p> If SWIG is launched without <tt>-no-old-metatable-bindings</tt> option, then it enters backward-compatible mode. While in this mode, it tries @@ -1481,7 +1481,7 @@ surrounding scope without any prefixing. Pretending that Test2 is a struct, not > </pre></div> -<H4><a name="Lua_nn30"></a>27.3.17.3 Inheritance </H4> +<H4><a name="Lua_nn30"></a>28.3.17.3 Inheritance </H4> <p> The internal organization of inheritance has changed. @@ -1522,12 +1522,12 @@ function > </pre></div> -<H2><a name="Lua_nn24"></a>27.4 Typemaps</H2> +<H2><a name="Lua_nn24"></a>28.4 Typemaps</H2> <p>This section explains what typemaps are and how to use them. The default wrapping behaviour of SWIG is enough in most cases. However sometimes SWIG may need a little additional assistance to know which typemap to apply to provide the best wrapping. This section will be explaining how to use typemaps to best effect</p> -<H3><a name="Lua_nn25"></a>27.4.1 What is a typemap?</H3> +<H3><a name="Lua_nn25"></a>28.4.1 What is a typemap?</H3> <p>A typemap is nothing more than a code generation rule that is attached to a specific C datatype. For example, to convert integers from Lua to C, you might define a typemap like this:</p> @@ -1555,7 +1555,7 @@ Received an integer : 6 720 </pre></div> -<H3><a name="Lua_nn26"></a>27.4.2 Using typemaps</H3> +<H3><a name="Lua_nn26"></a>28.4.2 Using typemaps</H3> <p>There are many ready written typemaps built into SWIG for all common types (int, float, short, long, char*, enum and more), which SWIG uses automatically, with no effort required on your part.</p> @@ -1608,7 +1608,7 @@ void swap(int *sx, int *sy); <p>Note: C++ references must be handled exactly the same way. However SWIG will automatically wrap a <tt>const int&</tt> as an input parameter (since that it obviously input).</p> -<H3><a name="Lua_typemap_arrays"></a>27.4.3 Typemaps and arrays</H3> +<H3><a name="Lua_typemap_arrays"></a>28.4.3 Typemaps and arrays</H3> <p>Arrays present a challenge for SWIG, because like pointers SWIG does not know whether these are input or output values, nor @@ -1672,7 +1672,7 @@ and Lua tables to be 1..N, (the indexing follows the norm for the language). In <p>Note: SWIG also can support arrays of pointers in a similar manner.</p> -<H3><a name="Lua_typemaps_ptr_ptr_functions"></a>27.4.4 Typemaps and pointer-pointer functions</H3> +<H3><a name="Lua_typemaps_ptr_ptr_functions"></a>28.4.4 Typemaps and pointer-pointer functions</H3> <p>Several C++ libraries use a pointer-pointer functions to create its objects. These functions require a pointer to a pointer which is then filled with the pointer to the new object. Microsoft's COM and DirectX as well as many other libraries have this kind of function. An example is given below:</p> @@ -1706,7 +1706,7 @@ int Create_Math(iMath** pptr); // its creator (assume it mallocs) ptr=nil -- the iMath* will be GC'ed as normal </pre></div> -<H2><a name="Lua_writing_typemaps"></a>27.5 Writing typemaps</H2> +<H2><a name="Lua_writing_typemaps"></a>28.5 Writing typemaps</H2> <p>This section describes how you can modify SWIG's default wrapping behavior for various C/C++ datatypes using the <tt>%typemap</tt> directive. This is an advanced topic that assumes familiarity with the Lua C API as well as the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter.</p> @@ -1715,7 +1715,7 @@ ptr=nil -- the iMath* will be GC'ed as normal <p>Before proceeding, you should read the previous section on using typemaps, and look at the existing typemaps found in luatypemaps.swg and typemaps.i. These are both well documented and fairly easy to read. You should not attempt to write your own typemaps until you have read and can understand both of these files (they may well also give you an idea to base your work on).</p> -<H3><a name="Lua_typemaps_write"></a>27.5.1 Typemaps you can write</H3> +<H3><a name="Lua_typemaps_write"></a>28.5.1 Typemaps you can write</H3> <p>There are many different types of typemap that can be written, the full list can be found in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. However the following are the most commonly used ones.</p> @@ -1728,7 +1728,7 @@ ptr=nil -- the iMath* will be GC'ed as normal (the syntax for the typecheck is different from the typemap, see typemaps for details).</li> </ul> -<H3><a name="Lua_nn31"></a>27.5.2 SWIG's Lua-C API</H3> +<H3><a name="Lua_nn31"></a>28.5.2 SWIG's Lua-C API</H3> <p>This section explains the SWIG specific Lua-C API. It does not cover the main Lua-C api, as this is well documented and not worth covering.</p> @@ -1777,7 +1777,7 @@ This macro, when called within the context of a SWIG wrapped function, will disp <div class="indent"> Similar to SWIG_fail_arg, except that it will display the swig_type_info information instead.</div> -<H2><a name="Lua_nn32"></a>27.6 Customization of your Bindings</H2> +<H2><a name="Lua_nn32"></a>28.6 Customization of your Bindings</H2> <p> @@ -1786,7 +1786,7 @@ This section covers adding of some small extra bits to your module to add the la -<H3><a name="Lua_nn33"></a>27.6.1 Writing your own custom wrappers</H3> +<H3><a name="Lua_nn33"></a>28.6.1 Writing your own custom wrappers</H3> <p> @@ -1805,7 +1805,7 @@ int native_function(lua_State*L) // my native code The <tt>%native</tt> directive in the above example, tells SWIG that there is a function <tt>int native_function(lua_State*L);</tt> which is to be added into the module under the name '<tt>my_func</tt>'. SWIG will not add any wrapper for this function, beyond adding it into the function table. How you write your code is entirely up to you. </p> -<H3><a name="Lua_nn34"></a>27.6.2 Adding additional Lua code</H3> +<H3><a name="Lua_nn34"></a>28.6.2 Adding additional Lua code</H3> <p> @@ -1843,7 +1843,7 @@ Good uses for this feature is adding of new code, or writing helper functions to See Examples/lua/arrays for an example of this code. </p> -<H2><a name="Lua_nn35"></a>27.7 Details on the Lua binding</H2> +<H2><a name="Lua_nn35"></a>28.7 Details on the Lua binding</H2> <p> @@ -1854,7 +1854,7 @@ See Examples/lua/arrays for an example of this code. </i> </p> -<H3><a name="Lua_nn36"></a>27.7.1 Binding global data into the module.</H3> +<H3><a name="Lua_nn36"></a>28.7.1 Binding global data into the module.</H3> <p> @@ -1914,7 +1914,7 @@ end <p> That way when you call '<tt>a=example.Foo</tt>', the interpreter looks at the table 'example' sees that there is no field 'Foo' and calls __index. This will in turn check in '.get' table and find the existence of 'Foo' and then return the value of the C function call 'Foo_get()'. Similarly for the code '<tt>example.Foo=10</tt>', the interpreter will check the table, then call the __newindex which will then check the '.set' table and call the C function 'Foo_set(10)'. </p> -<H3><a name="Lua_nn37"></a>27.7.2 Userdata and Metatables</H3> +<H3><a name="Lua_nn37"></a>28.7.2 Userdata and Metatables</H3> <p> @@ -1994,7 +1994,7 @@ Note: Both the opaque structures (like the FILE*) and normal wrapped classes/str <p> Note: Operator overloads are basically done in the same way, by adding functions such as '__add' & '__call' to the class' metatable. The current implementation is a bit rough as it will add any member function beginning with '__' into the metatable too, assuming its an operator overload. </p> -<H3><a name="Lua_nn38"></a>27.7.3 Memory management</H3> +<H3><a name="Lua_nn38"></a>28.7.3 Memory management</H3> <p> diff --git a/Doc/Manual/Makefile b/Doc/Manual/Makefile index 42149ba3a..5112afa33 100644 --- a/Doc/Manual/Makefile +++ b/Doc/Manual/Makefile @@ -75,4 +75,3 @@ linkchecker: @echo Note linkchecker versions prior to 6.1 do not work properly wrt anchors @echo ----------------------------------------------------------------------- linkchecker --config=./linkchecker.config index.html - diff --git a/Doc/Manual/Modula3.html b/Doc/Manual/Modula3.html index 0bf9f2995..ffbf6132d 100644 --- a/Doc/Manual/Modula3.html +++ b/Doc/Manual/Modula3.html @@ -5,7 +5,7 @@ <link rel="stylesheet" type="text/css" href="style.css"> </head> <body bgcolor="#FFFFFF"> -<H1><a name="Modula3"></a>28 SWIG and Modula-3</H1> +<H1><a name="Modula3"></a>29 SWIG and Modula-3</H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -54,7 +54,7 @@ especially <a href="Typemaps.html#Typemaps">typemaps</a>. </p> -<H2><a name="Modula3_modula3_overview"></a>28.1 Overview</H2> +<H2><a name="Modula3_modula3_overview"></a>29.1 Overview</H2> <p> @@ -84,7 +84,7 @@ FFTW </li> </ol> -<H3><a name="Modula3_motivation"></a>28.1.1 Motivation</H3> +<H3><a name="Modula3_motivation"></a>29.1.1 Motivation</H3> <p> @@ -131,10 +131,10 @@ functions), but it doesn't allow you to easily integrate a Modula-3 module into a C/C++ project. </p> -<H2><a name="Modula3_conception"></a>28.2 Conception</H2> +<H2><a name="Modula3_conception"></a>29.2 Conception</H2> -<H3><a name="Modula3_cinterface"></a>28.2.1 Interfaces to C libraries</H3> +<H3><a name="Modula3_cinterface"></a>29.2.1 Interfaces to C libraries</H3> <p> @@ -283,7 +283,7 @@ and the principal type must be renamed (<tt>%typemap</tt>). </p> -<H3><a name="Modula3_cppinterface"></a>28.2.2 Interfaces to C++ libraries</H3> +<H3><a name="Modula3_cppinterface"></a>29.2.2 Interfaces to C++ libraries</H3> <p> @@ -384,10 +384,10 @@ There is no C++ library I wrote a SWIG interface for, so I'm not sure if this is possible or sensible, yet. </p> -<H2><a name="Modula3_preliminaries"></a>28.3 Preliminaries</H2> +<H2><a name="Modula3_preliminaries"></a>29.3 Preliminaries</H2> -<H3><a name="Modula3_compilers"></a>28.3.1 Compilers</H3> +<H3><a name="Modula3_compilers"></a>29.3.1 Compilers</H3> <p> @@ -400,7 +400,7 @@ For testing examples I use Critical Mass cm3. </p> -<H3><a name="Modula3_commandline"></a>28.3.2 Additional Commandline Options</H3> +<H3><a name="Modula3_commandline"></a>29.3.2 Additional Commandline Options</H3> <p> @@ -477,10 +477,10 @@ Instead generate templates for some basic typemaps. </tr> </table> -<H2><a name="Modula3_typemaps"></a>28.4 Modula-3 typemaps</H2> +<H2><a name="Modula3_typemaps"></a>29.4 Modula-3 typemaps</H2> -<H3><a name="Modula3_inoutparam"></a>28.4.1 Inputs and outputs</H3> +<H3><a name="Modula3_inoutparam"></a>29.4.1 Inputs and outputs</H3> <p> @@ -694,7 +694,7 @@ consist of the following parts: </table> -<H3><a name="Modula3_ordinals"></a>28.4.2 Subranges, Enumerations, Sets</H3> +<H3><a name="Modula3_ordinals"></a>29.4.2 Subranges, Enumerations, Sets</H3> <p> @@ -746,7 +746,7 @@ that I'd like to automate. </p> -<H3><a name="Modula3_class"></a>28.4.3 Objects</H3> +<H3><a name="Modula3_class"></a>29.4.3 Objects</H3> <p> @@ -759,7 +759,7 @@ is not really useful, yet. </p> -<H3><a name="Modula3_imports"></a>28.4.4 Imports</H3> +<H3><a name="Modula3_imports"></a>29.4.4 Imports</H3> <p> @@ -792,7 +792,7 @@ IMPORT M3toC; </pre></div> -<H3><a name="Modula3_exceptions"></a>28.4.5 Exceptions</H3> +<H3><a name="Modula3_exceptions"></a>29.4.5 Exceptions</H3> <p> @@ -816,7 +816,7 @@ you should declare <tt>%typemap("m3wrapinconv:throws") blah * %{OSError.E%}</tt>. </p> -<H3><a name="Modula3_typemap_example"></a>28.4.6 Example</H3> +<H3><a name="Modula3_typemap_example"></a>29.4.6 Example</H3> <p> @@ -863,10 +863,10 @@ where almost everything is generated by a typemap: </pre></div> -<H2><a name="Modula3_hints"></a>28.5 More hints to the generator</H2> +<H2><a name="Modula3_hints"></a>29.5 More hints to the generator</H2> -<H3><a name="Modula3_features"></a>28.5.1 Features</H3> +<H3><a name="Modula3_features"></a>29.5.1 Features</H3> <table border summary="Modula-3 features"> @@ -903,7 +903,7 @@ where almost everything is generated by a typemap: </tr> </table> -<H3><a name="Modula3_pragmas"></a>28.5.2 Pragmas</H3> +<H3><a name="Modula3_pragmas"></a>29.5.2 Pragmas</H3> <table border summary="Modula-3 pragmas"> @@ -926,7 +926,7 @@ where almost everything is generated by a typemap: </tr> </table> -<H2><a name="Modula3_remarks"></a>28.6 Remarks</H2> +<H2><a name="Modula3_remarks"></a>29.6 Remarks</H2> <ul> diff --git a/Doc/Manual/Mzscheme.html b/Doc/Manual/Mzscheme.html index 40173d720..fadda5fc9 100644 --- a/Doc/Manual/Mzscheme.html +++ b/Doc/Manual/Mzscheme.html @@ -8,7 +8,7 @@ <body bgcolor="#ffffff"> -<H1><a name="Mzscheme"></a>29 SWIG and MzScheme/Racket</H1> +<H1><a name="Mzscheme"></a>30 SWIG and MzScheme/Racket</H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -24,7 +24,7 @@ <p> This section contains information on SWIG's support of Racket, formally known as MzScheme. -<H2><a name="MzScheme_nn2"></a>29.1 Creating native structures</H2> +<H2><a name="MzScheme_nn2"></a>30.1 Creating native structures</H2> <p> @@ -65,7 +65,7 @@ Then in scheme, you can use regular struct access procedures like </pre> </div> -<H2><a name="MzScheme_simple"></a>29.2 Simple example</H2> +<H2><a name="MzScheme_simple"></a>30.2 Simple example</H2> <p> @@ -166,7 +166,7 @@ Some points of interest: <li> The above requests mzc to create an extension using the CGC garbage-collector. The alternative -- the 3m collector -- has generally better performance, but work is still required for SWIG to emit code which is compatible with it. </ul> -<H2><a name="MzScheme_external_docs"></a>29.3 External documentation</H2> +<H2><a name="MzScheme_external_docs"></a>30.3 External documentation</H2> <p> diff --git a/Doc/Manual/Ocaml.html b/Doc/Manual/Ocaml.html index ec46d6e50..aa6679f9a 100644 --- a/Doc/Manual/Ocaml.html +++ b/Doc/Manual/Ocaml.html @@ -6,7 +6,7 @@ </head> <body bgcolor="#ffffff"> <a name="n1"></a> -<H1><a name="Ocaml"></a>30 SWIG and Ocaml</H1> +<H1><a name="Ocaml"></a>31 SWIG and Ocaml</H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -80,7 +80,7 @@ If you're not familiar with the Objective Caml language, you can visit <a href="http://www.ocaml.org/">The Ocaml Website</a>. </p> -<H2><a name="Ocaml_nn2"></a>30.1 Preliminaries</H2> +<H2><a name="Ocaml_nn2"></a>31.1 Preliminaries</H2> <p> @@ -99,7 +99,7 @@ file Examples/Makefile illustrate how to compile and link SWIG modules that will be loaded dynamically. This has only been tested on Linux so far. </p> -<H3><a name="Ocaml_nn3"></a>30.1.1 Running SWIG</H3> +<H3><a name="Ocaml_nn3"></a>31.1.1 Running SWIG</H3> <p> @@ -122,7 +122,7 @@ you will compile the file <tt>example_wrap.c</tt> with <tt>ocamlc</tt> or the resulting .ml and .mli files as well, and do the final link with -custom (not needed for native link). </p> -<H3><a name="Ocaml_nn4"></a>30.1.2 Compiling the code</H3> +<H3><a name="Ocaml_nn4"></a>31.1.2 Compiling the code</H3> <p> @@ -158,7 +158,7 @@ the user more freedom with respect to custom typing. </pre> </div> -<H3><a name="Ocaml_nn5"></a>30.1.3 The camlp4 module</H3> +<H3><a name="Ocaml_nn5"></a>31.1.3 The camlp4 module</H3> <p> @@ -234,7 +234,7 @@ let b = C_string (getenv "PATH") </td></tr> </table> -<H3><a name="Ocaml_nn6"></a>30.1.4 Using your module</H3> +<H3><a name="Ocaml_nn6"></a>31.1.4 Using your module</H3> <p> @@ -248,7 +248,7 @@ When linking any ocaml bytecode with your module, use the -custom option is not needed when you build native code. </p> -<H3><a name="Ocaml_nn7"></a>30.1.5 Compilation problems and compiling with C++</H3> +<H3><a name="Ocaml_nn7"></a>31.1.5 Compilation problems and compiling with C++</H3> <p> @@ -259,7 +259,7 @@ liberal with pointer types may not compile under the C++ compiler. Most code meant to be compiled as C++ will not have problems. </p> -<H2><a name="Ocaml_nn8"></a>30.2 The low-level Ocaml/C interface</H2> +<H2><a name="Ocaml_nn8"></a>31.2 The low-level Ocaml/C interface</H2> <p> @@ -360,7 +360,7 @@ is that you must append them to the return list with swig_result = caml_list_a signature for a function that uses value in this way. </p> -<H3><a name="Ocaml_nn9"></a>30.2.1 The generated module</H3> +<H3><a name="Ocaml_nn9"></a>31.2.1 The generated module</H3> <p> @@ -394,7 +394,7 @@ it describes the output SWIG will generate for class definitions. </td></tr> </table> -<H3><a name="Ocaml_nn10"></a>30.2.2 Enums</H3> +<H3><a name="Ocaml_nn10"></a>31.2.2 Enums</H3> <p> @@ -457,7 +457,7 @@ val x : Enum_test.c_obj = C_enum `a </pre> </div> -<H4><a name="Ocaml_nn11"></a>30.2.2.1 Enum typing in Ocaml</H4> +<H4><a name="Ocaml_nn11"></a>31.2.2.1 Enum typing in Ocaml</H4> <p> @@ -470,10 +470,10 @@ functions imported from different modules. You must convert values to master values using the swig_val function before sharing them with another module. </p> -<H3><a name="Ocaml_nn12"></a>30.2.3 Arrays</H3> +<H3><a name="Ocaml_nn12"></a>31.2.3 Arrays</H3> -<H4><a name="Ocaml_nn13"></a>30.2.3.1 Simple types of bounded arrays</H4> +<H4><a name="Ocaml_nn13"></a>31.2.3.1 Simple types of bounded arrays</H4> <p> @@ -494,7 +494,7 @@ arrays of simple types with known bounds in your code, but this only works for arrays whose bounds are completely specified. </p> -<H4><a name="Ocaml_nn14"></a>30.2.3.2 Complex and unbounded arrays</H4> +<H4><a name="Ocaml_nn14"></a>31.2.3.2 Complex and unbounded arrays</H4> <p> @@ -507,7 +507,7 @@ SWIG can't predict which of these methods will be used in the array, so you have to specify it for yourself in the form of a typemap. </p> -<H4><a name="Ocaml_nn15"></a>30.2.3.3 Using an object</H4> +<H4><a name="Ocaml_nn15"></a>31.2.3.3 Using an object</H4> <p> @@ -521,7 +521,7 @@ Consider writing an object when the ending condition of your array is complex, such as using a required sentinel, etc. </p> -<H4><a name="Ocaml_nn16"></a>30.2.3.4 Example typemap for a function taking float * and int</H4> +<H4><a name="Ocaml_nn16"></a>31.2.3.4 Example typemap for a function taking float * and int</H4> <p> @@ -572,7 +572,7 @@ void printfloats( float *tab, int len ); </pre></td></tr></table> -<H3><a name="Ocaml_nn17"></a>30.2.4 C++ Classes</H3> +<H3><a name="Ocaml_nn17"></a>31.2.4 C++ Classes</H3> <p> @@ -615,7 +615,7 @@ the underlying pointer, so using create_[x]_from_ptr alters the returned value for the same object. </p> -<H4><a name="Ocaml_nn18"></a>30.2.4.1 STL vector and string Example</H4> +<H4><a name="Ocaml_nn18"></a>31.2.4.1 STL vector and string Example</H4> <p> @@ -695,7 +695,7 @@ baz # </pre></div> -<H4><a name="Ocaml_nn19"></a>30.2.4.2 C++ Class Example</H4> +<H4><a name="Ocaml_nn19"></a>31.2.4.2 C++ Class Example</H4> <p> @@ -725,7 +725,7 @@ public: }; </pre></td></tr></table> -<H4><a name="Ocaml_nn20"></a>30.2.4.3 Compiling the example</H4> +<H4><a name="Ocaml_nn20"></a>31.2.4.3 Compiling the example</H4> <div class="code"><pre> @@ -743,7 +743,7 @@ bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \ -L$QTPATH/lib -cclib -lqt </pre></div> -<H4><a name="Ocaml_nn21"></a>30.2.4.4 Sample Session</H4> +<H4><a name="Ocaml_nn21"></a>31.2.4.4 Sample Session</H4> <div class="code"><pre> @@ -770,10 +770,10 @@ Assuming you have a working installation of QT, you will see a window containing the string "hi" in a button. </p> -<H3><a name="Ocaml_nn22"></a>30.2.5 Director Classes</H3> +<H3><a name="Ocaml_nn22"></a>31.2.5 Director Classes</H3> -<H4><a name="Ocaml_nn23"></a>30.2.5.1 Director Introduction</H4> +<H4><a name="Ocaml_nn23"></a>31.2.5.1 Director Introduction</H4> <p> @@ -800,7 +800,7 @@ class foo { }; </pre></div> -<H4><a name="Ocaml_nn24"></a>30.2.5.2 Overriding Methods in Ocaml</H4> +<H4><a name="Ocaml_nn24"></a>31.2.5.2 Overriding Methods in Ocaml</H4> <p> @@ -828,7 +828,7 @@ In this example, I'll examine the objective caml code involved in providing an overloaded class. This example is contained in Examples/ocaml/shapes. </p> -<H4><a name="Ocaml_nn25"></a>30.2.5.3 Director Usage Example</H4> +<H4><a name="Ocaml_nn25"></a>31.2.5.3 Director Usage Example</H4> <table border="1" bgcolor="#dddddd" summary="Director usage example"> @@ -887,7 +887,7 @@ in a more effortless style in ocaml, while leaving the "engine" part of the program in C++. </p> -<H4><a name="Ocaml_nn26"></a>30.2.5.4 Creating director objects</H4> +<H4><a name="Ocaml_nn26"></a>31.2.5.4 Creating director objects</H4> <p> @@ -928,7 +928,7 @@ object from causing a core dump, as long as the object is destroyed properly. </p> -<H4><a name="Ocaml_nn27"></a>30.2.5.5 Typemaps for directors, <tt>directorin, directorout, directorargout</tt></H4> +<H4><a name="Ocaml_nn27"></a>31.2.5.5 Typemaps for directors, <tt>directorin, directorout, directorargout</tt></H4> <p> @@ -939,7 +939,7 @@ well as a function return value in the same way you provide function arguments, and to receive arguments the same way you normally receive function returns. </p> -<H4><a name="Ocaml_nn28"></a>30.2.5.6 <tt>directorin</tt> typemap</H4> +<H4><a name="Ocaml_nn28"></a>31.2.5.6 <tt>directorin</tt> typemap</H4> <p> @@ -950,7 +950,7 @@ code receives when you are called. In general, a simple <tt>directorin</tt> typ can use the same body as a simple <tt>out</tt> typemap. </p> -<H4><a name="Ocaml_nn29"></a>30.2.5.7 <tt>directorout</tt> typemap</H4> +<H4><a name="Ocaml_nn29"></a>31.2.5.7 <tt>directorout</tt> typemap</H4> <p> @@ -961,7 +961,7 @@ for the same type, except when there are special requirements for object ownership, etc. </p> -<H4><a name="Ocaml_nn30"></a>30.2.5.8 <tt>directorargout</tt> typemap</H4> +<H4><a name="Ocaml_nn30"></a>31.2.5.8 <tt>directorargout</tt> typemap</H4> <p> @@ -978,7 +978,7 @@ In the event that you don't specify all of the necessary values, integral values will read zero, and struct or object returns have undefined results. </p> -<H3><a name="Ocaml_nn31"></a>30.2.6 Exceptions</H3> +<H3><a name="Ocaml_nn31"></a>31.2.6 Exceptions</H3> <p> diff --git a/Doc/Manual/Octave.html b/Doc/Manual/Octave.html index bc6873c4b..46a8941c2 100644 --- a/Doc/Manual/Octave.html +++ b/Doc/Manual/Octave.html @@ -8,7 +8,7 @@ <body bgcolor="#ffffff"> -<H1><a name="Octave"></a>31 SWIG and Octave</H1> +<H1><a name="Octave"></a>32 SWIG and Octave</H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -55,15 +55,15 @@ More information can be found at <a href="http://www.gnu.org/software/octave/">O Also, there are a dozen or so examples in the Examples/octave directory, and hundreds in the test suite (Examples/test-suite and Examples/test-suite/octave). </p> -<H2><a name="Octave_nn2"></a>31.1 Preliminaries</H2> +<H2><a name="Octave_nn2"></a>32.1 Preliminaries</H2> <p> -As of SWIG 3.0.0, the Octave module has been tested with Octave versions 3.0.5, 3.2.4, 3.4.3, 3.6.4, and 3.8.0. -Use of Octave versions older than 3.x.x is not recommended, as these versions are no longer tested with SWIG. +As of SWIG 3.0.3, the Octave module has been tested with Octave versions 3.2.4, 3.4.3, 3.6.4, and 3.8.1. +Use of older Octave versions is not recommended, as these versions are no longer tested with SWIG. </p> -<H2><a name="Octave_nn3"></a>31.2 Running SWIG</H2> +<H2><a name="Octave_nn3"></a>32.2 Running SWIG</H2> <p> @@ -95,7 +95,7 @@ The <tt>-c++</tt> option is also required when wrapping C++ code: This creates a C++ source file "example_wrap.cpp". A C++ file is generated even when wrapping C code as Octave is itself written in C++ and requires wrapper code to be in the same language. The generated C++ source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application (in this case, the gcd implementation) to create an extension module. </p> -<H3><a name="Octave_nn4"></a>31.2.1 Command-line options</H3> +<H3><a name="Octave_nn4"></a>32.2.1 Command-line options</H3> <p> @@ -118,7 +118,7 @@ The special name "." loads C global variables into the module namespace, i.e. al The <em>-opprefix</em> options sets the prefix of the names of global/friend <a href="#Octave_nn18">operator</a> functions. </p> -<H3><a name="Octave_nn5"></a>31.2.2 Compiling a dynamic module</H3> +<H3><a name="Octave_nn5"></a>32.2.2 Compiling a dynamic module</H3> <p> @@ -145,7 +145,7 @@ $ mkoctfile example_wrap.cpp example.c <div class="targetlang"><pre>octave:1> swigexample</pre></div> -<H3><a name="Octave_nn6"></a>31.2.3 Using your module</H3> +<H3><a name="Octave_nn6"></a>32.2.3 Using your module</H3> <p> @@ -163,10 +163,10 @@ octave:4> swigexample.cvar.Foo=4; octave:5> swigexample.cvar.Foo ans = 4 </pre></div> -<H2><a name="Octave_nn7"></a>31.3 A tour of basic C/C++ wrapping</H2> +<H2><a name="Octave_nn7"></a>32.3 A tour of basic C/C++ wrapping</H2> -<H3><a name="Octave_nn8"></a>31.3.1 Modules</H3> +<H3><a name="Octave_nn8"></a>32.3.1 Modules</H3> <p> @@ -211,7 +211,7 @@ octave:4> swigexample.gcd(4,6) ans = 2 </pre></div> -<H3><a name="Octave_nn9"></a>31.3.2 Functions</H3> +<H3><a name="Octave_nn9"></a>32.3.2 Functions</H3> <p> @@ -228,7 +228,7 @@ int fact(int n); </pre></div> <div class="targetlang"><pre>octave:1> swigexample.fact(4) 24 </pre></div> -<H3><a name="Octave_nn10"></a>31.3.3 Global variables</H3> +<H3><a name="Octave_nn10"></a>32.3.3 Global variables</H3> <p> @@ -281,7 +281,7 @@ octave:2> swigexample.PI=3.142; octave:3> swigexample.PI ans = 3.1420 </pre></div> -<H3><a name="Octave_nn11"></a>31.3.4 Constants and enums</H3> +<H3><a name="Octave_nn11"></a>32.3.4 Constants and enums</H3> <p> @@ -303,7 +303,7 @@ swigexample.SCONST="Hello World" swigexample.SUNDAY=0 .... </pre></div> -<H3><a name="Octave_nn12"></a>31.3.5 Pointers</H3> +<H3><a name="Octave_nn12"></a>32.3.5 Pointers</H3> <p> @@ -350,7 +350,7 @@ octave:2> f=swigexample.fopen("not there","r"); error: value on right hand side of assignment is undefined error: evaluating assignment expression near line 2, column 2 </pre></div> -<H3><a name="Octave_nn13"></a>31.3.6 Structures and C++ classes</H3> +<H3><a name="Octave_nn13"></a>32.3.6 Structures and C++ classes</H3> <p> @@ -485,7 +485,7 @@ ans = 1 Depending on the ownership setting of a <tt>swig_ref</tt>, it may call C++ destructors when its reference count goes to zero. See the section on memory management below for details. </p> -<H3><a name="Octave_nn15"></a>31.3.7 C++ inheritance</H3> +<H3><a name="Octave_nn15"></a>32.3.7 C++ inheritance</H3> <p> @@ -494,7 +494,7 @@ This information contains the full class hierarchy. When an indexing operation ( the tree is walked to find a match in the current class as well as any of its bases. The lookup is then cached in the <tt>swig_ref</tt>. </p> -<H3><a name="Octave_nn17"></a>31.3.8 C++ overloaded functions</H3> +<H3><a name="Octave_nn17"></a>32.3.8 C++ overloaded functions</H3> <p> @@ -504,7 +504,7 @@ The dispatch function selects which overload to call (if any) based on the passe <tt>typecheck</tt> typemaps are used to analyze each argument, as well as assign precedence. See the chapter on typemaps for details. </p> -<H3><a name="Octave_nn18"></a>31.3.9 C++ operators</H3> +<H3><a name="Octave_nn18"></a>32.3.9 C++ operators</H3> <p> @@ -608,7 +608,7 @@ On the C++ side, the default mappings are as follows: Octave can also utilise friend (i.e. non-member) operators with a simple %rename: see the example in the Examples/octave/operator directory. </p> -<H3><a name="Octave_nn19"></a>31.3.10 Class extension with %extend</H3> +<H3><a name="Octave_nn19"></a>32.3.10 Class extension with %extend</H3> <p> @@ -638,7 +638,7 @@ octave:3> printf("%s\n",a); octave:4> a.__str() 4 </pre></div> -<H3><a name="Octave_nn20"></a>31.3.11 C++ templates</H3> +<H3><a name="Octave_nn20"></a>32.3.11 C++ templates</H3> <p> @@ -715,14 +715,14 @@ ans = </pre></div> -<H3><a name="Octave_nn21"></a>31.3.12 C++ Smart Pointers</H3> +<H3><a name="Octave_nn21"></a>32.3.12 C++ Smart Pointers</H3> <p> C++ smart pointers are fully supported as in other modules. </p> -<H3><a name="Octave_nn22"></a>31.3.13 Directors (calling Octave from C++ code)</H3> +<H3><a name="Octave_nn22"></a>32.3.13 Directors (calling Octave from C++ code)</H3> <p> @@ -803,14 +803,14 @@ c-side routine called octave-side routine called </pre></div> -<H3><a name="Octave_nn23"></a>31.3.14 Threads</H3> +<H3><a name="Octave_nn23"></a>32.3.14 Threads</H3> <p> The use of threads in wrapped Director code is not supported; i.e., an Octave-side implementation of a C++ class must be called from the Octave interpreter's thread. Anything fancier (apartment/queue model, whatever) is left to the user. Without anything fancier, this amounts to the limitation that Octave must drive the module... like, for example, an optimization package that calls Octave to evaluate an objective function. </p> -<H3><a name="Octave_nn24"></a>31.3.15 Memory management</H3> +<H3><a name="Octave_nn24"></a>32.3.15 Memory management</H3> <p> @@ -844,14 +844,14 @@ The %newobject directive may be used to control this behavior for pointers retur In the case where one wishes for the C++ side to own an object that was created in Octave (especially a Director object), one can use the __disown() method to invert this logic. Then letting the Octave reference count go to zero will not destroy the object, but destroying the object will invalidate the Octave-side object if it still exists (and call destructors of other C++ bases in the case of multiple inheritance/<tt>subclass()</tt>'ing). </p> -<H3><a name="Octave_nn25"></a>31.3.16 STL support</H3> +<H3><a name="Octave_nn25"></a>32.3.16 STL support</H3> <p> Various STL library files are provided for wrapping STL containers. </p> -<H3><a name="Octave_nn26"></a>31.3.17 Matrix typemaps</H3> +<H3><a name="Octave_nn26"></a>32.3.17 Matrix typemaps</H3> <p> diff --git a/Doc/Manual/Perl5.html b/Doc/Manual/Perl5.html index 010eb48df..8bc7cbfd3 100644 --- a/Doc/Manual/Perl5.html +++ b/Doc/Manual/Perl5.html @@ -6,7 +6,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Perl5"></a>32 SWIG and Perl5</H1> +<H1><a name="Perl5"></a>33 SWIG and Perl5</H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -96,7 +96,7 @@ later. We're no longer testing regularly with older versions, but Perl 5.6 seems to mostly work, while older versions don't. </p> -<H2><a name="Perl5_nn2"></a>32.1 Overview</H2> +<H2><a name="Perl5_nn2"></a>33.1 Overview</H2> <p> @@ -117,7 +117,7 @@ described. Advanced customization features, typemaps, and other options are found near the end of the chapter. </p> -<H2><a name="Perl5_nn3"></a>32.2 Preliminaries</H2> +<H2><a name="Perl5_nn3"></a>33.2 Preliminaries</H2> <p> @@ -142,7 +142,7 @@ To build the module, you will need to compile the file <tt>example_wrap.c</tt> and link it with the rest of your program. </p> -<H3><a name="Perl5_nn4"></a>32.2.1 Getting the right header files</H3> +<H3><a name="Perl5_nn4"></a>33.2.1 Getting the right header files</H3> <p> @@ -174,7 +174,7 @@ $ perl -e 'use Config; print "$Config{archlib}\n";' </pre> </div> -<H3><a name="Perl5_nn5"></a>32.2.2 Compiling a dynamic module</H3> +<H3><a name="Perl5_nn5"></a>33.2.2 Compiling a dynamic module</H3> <p> @@ -207,7 +207,7 @@ the target should be named `<tt>example.so</tt>', `<tt>example.sl</tt>', or the appropriate dynamic module name on your system. </p> -<H3><a name="Perl5_nn6"></a>32.2.3 Building a dynamic module with MakeMaker</H3> +<H3><a name="Perl5_nn6"></a>33.2.3 Building a dynamic module with MakeMaker</H3> <p> @@ -241,7 +241,7 @@ the preferred approach to compilation. More information about MakeMaker can be found in "Programming Perl, 2nd ed." by Larry Wall, Tom Christiansen, and Randal Schwartz.</p> -<H3><a name="Perl5_nn7"></a>32.2.4 Building a static version of Perl</H3> +<H3><a name="Perl5_nn7"></a>33.2.4 Building a static version of Perl</H3> <p> @@ -310,7 +310,7 @@ added to it. Depending on your machine, you may need to link with additional libraries such as <tt>-lsocket, -lnsl, -ldl</tt>, etc. </p> -<H3><a name="Perl5_nn8"></a>32.2.5 Using the module</H3> +<H3><a name="Perl5_nn8"></a>33.2.5 Using the module</H3> <p> @@ -463,7 +463,7 @@ system configuration (this requires root access and you will need to read the man pages). </p> -<H3><a name="Perl5_nn9"></a>32.2.6 Compilation problems and compiling with C++</H3> +<H3><a name="Perl5_nn9"></a>33.2.6 Compilation problems and compiling with C++</H3> <p> @@ -606,7 +606,7 @@ have to find the macro that conflicts and add an #undef into the .i file. Pleas any conflicting macros you find to <a href="http://www.swig.org/mail.html">swig-user mailing list</a>. </p> -<H3><a name="Perl5_nn10"></a>32.2.7 Compiling for 64-bit platforms</H3> +<H3><a name="Perl5_nn10"></a>33.2.7 Compiling for 64-bit platforms</H3> <p> @@ -633,7 +633,7 @@ also introduce problems on platforms that support more than one linking standard (e.g., -o32 and -n32 on Irix). </p> -<H2><a name="Perl5_nn11"></a>32.3 Building Perl Extensions under Windows</H2> +<H2><a name="Perl5_nn11"></a>33.3 Building Perl Extensions under Windows</H2> <p> @@ -644,7 +644,7 @@ section assumes you are using SWIG with Microsoft Visual C++ although the procedure may be similar with other compilers. </p> -<H3><a name="Perl5_nn12"></a>32.3.1 Running SWIG from Developer Studio</H3> +<H3><a name="Perl5_nn12"></a>33.3.1 Running SWIG from Developer Studio</H3> <p> @@ -707,7 +707,7 @@ print "$a\n"; </pre></div> -<H3><a name="Perl5_nn13"></a>32.3.2 Using other compilers</H3> +<H3><a name="Perl5_nn13"></a>33.3.2 Using other compilers</H3> <p> @@ -715,7 +715,7 @@ SWIG is known to work with Cygwin and may work with other compilers on Windows. For general hints and suggestions refer to the <a href="Windows.html#Windows">Windows</a> chapter. </p> -<H2><a name="Perl5_nn14"></a>32.4 The low-level interface</H2> +<H2><a name="Perl5_nn14"></a>33.4 The low-level interface</H2> <p> @@ -725,7 +725,7 @@ can be used to control your application. However, it is also used to construct more user-friendly proxy classes as described in the next section. </p> -<H3><a name="Perl5_nn15"></a>32.4.1 Functions</H3> +<H3><a name="Perl5_nn15"></a>33.4.1 Functions</H3> <p> @@ -748,7 +748,7 @@ use example; $a = &example::fact(2); </pre></div> -<H3><a name="Perl5_nn16"></a>32.4.2 Global variables</H3> +<H3><a name="Perl5_nn16"></a>33.4.2 Global variables</H3> <p> @@ -818,7 +818,7 @@ extern char *path; // Declared later in the input </pre> </div> -<H3><a name="Perl5_nn17"></a>32.4.3 Constants</H3> +<H3><a name="Perl5_nn17"></a>33.4.3 Constants</H3> <p> @@ -858,7 +858,7 @@ print example::FOO,"\n"; </pre> </div> -<H3><a name="Perl5_nn18"></a>32.4.4 Pointers</H3> +<H3><a name="Perl5_nn18"></a>33.4.4 Pointers</H3> <p> @@ -967,7 +967,7 @@ as XS and <tt>xsubpp</tt>. Given the advancement of the SWIG typesystem and the SWIG and XS, this is no longer supported. </p> -<H3><a name="Perl5_nn19"></a>32.4.5 Structures</H3> +<H3><a name="Perl5_nn19"></a>33.4.5 Structures</H3> <p> @@ -1101,7 +1101,7 @@ void Bar_f_set(Bar *b, Foo *val) { </div> -<H3><a name="Perl5_nn20"></a>32.4.6 C++ classes</H3> +<H3><a name="Perl5_nn20"></a>33.4.6 C++ classes</H3> <p> @@ -1166,7 +1166,7 @@ provides direct access to C++ objects. A higher level interface using Perl prox can be built using these low-level accessors. This is described shortly. </p> -<H3><a name="Perl5_nn21"></a>32.4.7 C++ classes and type-checking</H3> +<H3><a name="Perl5_nn21"></a>33.4.7 C++ classes and type-checking</H3> <p> @@ -1202,7 +1202,7 @@ If necessary, the type-checker also adjusts the value of the pointer (as is nece multiple inheritance is used). </p> -<H3><a name="Perl5_nn22"></a>32.4.8 C++ overloaded functions</H3> +<H3><a name="Perl5_nn22"></a>33.4.8 C++ overloaded functions</H3> <p> @@ -1246,7 +1246,7 @@ example::Spam_foo_d($s,3.14); Please refer to the "SWIG Basics" chapter for more information. </p> -<H3><a name="Perl5_nn23"></a>32.4.9 Operators</H3> +<H3><a name="Perl5_nn23"></a>33.4.9 Operators</H3> <p> @@ -1273,7 +1273,7 @@ The following C++ operators are currently supported by the Perl module: <li>operator or </li> </ul> -<H3><a name="Perl5_nn24"></a>32.4.10 Modules and packages</H3> +<H3><a name="Perl5_nn24"></a>33.4.10 Modules and packages</H3> <p> @@ -1368,7 +1368,7 @@ print Foo::fact(4),"\n"; # Call a function in package FooBar </pre></div> --> -<H2><a name="Perl5_nn25"></a>32.5 Input and output parameters</H2> +<H2><a name="Perl5_nn25"></a>33.5 Input and output parameters</H2> <p> @@ -1587,7 +1587,7 @@ print "$c\n"; <b>Note:</b> The <tt>REFERENCE</tt> feature is only currently supported for numeric types (integers and floating point). </p> -<H2><a name="Perl5_nn26"></a>32.6 Exception handling</H2> +<H2><a name="Perl5_nn26"></a>33.6 Exception handling</H2> <p> @@ -1752,7 +1752,7 @@ This is still supported, but it is deprecated. The newer <tt>%exception</tt> di functionality, but it has additional capabilities that make it more powerful. </p> -<H2><a name="Perl5_nn27"></a>32.7 Remapping datatypes with typemaps</H2> +<H2><a name="Perl5_nn27"></a>33.7 Remapping datatypes with typemaps</H2> <p> @@ -1769,7 +1769,7 @@ Typemaps are only used if you want to change some aspect of the primitive C-Perl interface. </p> -<H3><a name="Perl5_nn28"></a>32.7.1 A simple typemap example</H3> +<H3><a name="Perl5_nn28"></a>33.7.1 A simple typemap example</H3> <p> @@ -1873,7 +1873,7 @@ example::count("e","Hello World"); </div> -<H3><a name="Perl5_nn29"></a>32.7.2 Perl5 typemaps</H3> +<H3><a name="Perl5_nn29"></a>33.7.2 Perl5 typemaps</H3> <p> @@ -1978,7 +1978,7 @@ Return of C++ member data (all languages). Check value of input parameter. </div> -<H3><a name="Perl5_nn30"></a>32.7.3 Typemap variables</H3> +<H3><a name="Perl5_nn30"></a>33.7.3 Typemap variables</H3> <p> @@ -2049,7 +2049,7 @@ properly assigned. The Perl name of the wrapper function being created. </div> -<H3><a name="Perl5_nn31"></a>32.7.4 Useful functions</H3> +<H3><a name="Perl5_nn31"></a>33.7.4 Useful functions</H3> <p> @@ -2118,7 +2118,7 @@ int sv_isa(SV *, char *0; </div> -<H2><a name="Perl5_nn32"></a>32.8 Typemap Examples</H2> +<H2><a name="Perl5_nn32"></a>33.8 Typemap Examples</H2> <p> @@ -2127,7 +2127,7 @@ might look at the files "<tt>perl5.swg</tt>" and "<tt>typemaps.i</tt>" in the SWIG library. </p> -<H3><a name="Perl5_nn33"></a>32.8.1 Converting a Perl5 array to a char **</H3> +<H3><a name="Perl5_nn33"></a>33.8.1 Converting a Perl5 array to a char **</H3> <p> @@ -2219,7 +2219,7 @@ print @$b,"\n"; # Print it out </pre></div> -<H3><a name="Perl5_nn34"></a>32.8.2 Return values</H3> +<H3><a name="Perl5_nn34"></a>33.8.2 Return values</H3> <p> @@ -2248,7 +2248,7 @@ can be done using the <tt>EXTEND()</tt> macro as in: } </pre></div> -<H3><a name="Perl5_nn35"></a>32.8.3 Returning values from arguments</H3> +<H3><a name="Perl5_nn35"></a>33.8.3 Returning values from arguments</H3> <p> @@ -2302,7 +2302,7 @@ print "multout(7,13) = @r\n"; ($x,$y) = multout(7,13); </pre></div> -<H3><a name="Perl5_nn36"></a>32.8.4 Accessing array structure members</H3> +<H3><a name="Perl5_nn36"></a>33.8.4 Accessing array structure members</H3> <p> @@ -2365,7 +2365,7 @@ the "in" typemap in the previous section would be used to convert an to copy the converted array into a C data structure. </p> -<H3><a name="Perl5_nn37"></a>32.8.5 Turning Perl references into C pointers</H3> +<H3><a name="Perl5_nn37"></a>33.8.5 Turning Perl references into C pointers</H3> <p> @@ -2430,7 +2430,7 @@ print "$c\n"; </pre></div> -<H3><a name="Perl5_nn38"></a>32.8.6 Pointer handling</H3> +<H3><a name="Perl5_nn38"></a>33.8.6 Pointer handling</H3> <p> @@ -2509,7 +2509,7 @@ For example: </pre> </div> -<H2><a name="Perl5_nn39"></a>32.9 Proxy classes</H2> +<H2><a name="Perl5_nn39"></a>33.9 Proxy classes</H2> <p> @@ -2525,7 +2525,7 @@ to the underlying code. This section describes the implementation details of the proxy interface. </p> -<H3><a name="Perl5_nn40"></a>32.9.1 Preliminaries</H3> +<H3><a name="Perl5_nn40"></a>33.9.1 Preliminaries</H3> <p> @@ -2547,7 +2547,7 @@ SWIG creates a collection of high-level Perl wrappers. In your scripts, you wil high level wrappers. The wrappers, in turn, interact with the low-level procedural module. </p> -<H3><a name="Perl5_nn41"></a>32.9.2 Structure and class wrappers</H3> +<H3><a name="Perl5_nn41"></a>33.9.2 Structure and class wrappers</H3> <p> @@ -2673,7 +2673,7 @@ $v->DESTROY(); </pre></div> -<H3><a name="Perl5_nn42"></a>32.9.3 Object Ownership</H3> +<H3><a name="Perl5_nn42"></a>33.9.3 Object Ownership</H3> <p> @@ -2760,7 +2760,7 @@ counting, garbage collection, or advanced features one might find in sophisticated languages. </p> -<H3><a name="Perl5_nn43"></a>32.9.4 Nested Objects</H3> +<H3><a name="Perl5_nn43"></a>33.9.4 Nested Objects</H3> <p> @@ -2813,7 +2813,7 @@ $p->{f}->{x} = 0.0; %${$p->{v}} = ( x=>0, y=>0, z=>0); </pre></div> -<H3><a name="Perl5_nn44"></a>32.9.5 Proxy Functions</H3> +<H3><a name="Perl5_nn44"></a>33.9.5 Proxy Functions</H3> <p> @@ -2847,7 +2847,7 @@ This function replaces the original function, but operates in an identical manner. </p> -<H3><a name="Perl5_nn45"></a>32.9.6 Inheritance</H3> +<H3><a name="Perl5_nn45"></a>33.9.6 Inheritance</H3> <p> @@ -2923,7 +2923,7 @@ particular, inheritance of data members is extremely tricky (and I'm not even sure if it really works). </p> -<H3><a name="Perl5_nn46"></a>32.9.7 Modifying the proxy methods</H3> +<H3><a name="Perl5_nn46"></a>33.9.7 Modifying the proxy methods</H3> <p> @@ -2951,7 +2951,7 @@ public: }; </pre></div> -<H2><a name="Perl5_nn47"></a>32.10 Adding additional Perl code</H2> +<H2><a name="Perl5_nn47"></a>33.10 Adding additional Perl code</H2> <p> @@ -3002,7 +3002,7 @@ set_transform($im, $a); </pre> </div> -<H2><a name="Perl5_directors"></a>32.11 Cross language polymorphism</H2> +<H2><a name="Perl5_directors"></a>33.11 Cross language polymorphism</H2> <p> @@ -3036,7 +3036,7 @@ proxy classes, director classes, and C wrapper functions takes care of all the cross-language method routing transparently. </p> -<H3><a name="Perl5_nn48"></a>32.11.1 Enabling directors</H3> +<H3><a name="Perl5_nn48"></a>33.11.1 Enabling directors</H3> <p> @@ -3126,7 +3126,7 @@ sub one { </div> -<H3><a name="Perl5_nn49"></a>32.11.2 Director classes</H3> +<H3><a name="Perl5_nn49"></a>33.11.2 Director classes</H3> @@ -3206,7 +3206,7 @@ so there is no need for the extra overhead involved with routing the calls through Perl. </p> -<H3><a name="Perl5_nn50"></a>32.11.3 Ownership and object destruction</H3> +<H3><a name="Perl5_nn50"></a>33.11.3 Ownership and object destruction</H3> <p> @@ -3255,7 +3255,7 @@ sub DESTROY { </div> -<H3><a name="Perl5_nn51"></a>32.11.4 Exception unrolling</H3> +<H3><a name="Perl5_nn51"></a>33.11.4 Exception unrolling</H3> <p> @@ -3311,7 +3311,7 @@ Swig::DirectorMethodException is thrown, Perl will register the exception as soon as the C wrapper function returns. </p> -<H3><a name="Perl5_nn52"></a>32.11.5 Overhead and code bloat</H3> +<H3><a name="Perl5_nn52"></a>33.11.5 Overhead and code bloat</H3> <p> @@ -3345,7 +3345,7 @@ directive) for only those methods that are likely to be extended in Perl. </p> -<H3><a name="Perl5_nn53"></a>32.11.6 Typemaps</H3> +<H3><a name="Perl5_nn53"></a>33.11.6 Typemaps</H3> <p> diff --git a/Doc/Manual/Php.html b/Doc/Manual/Php.html index 493c861f8..623adb68a 100644 --- a/Doc/Manual/Php.html +++ b/Doc/Manual/Php.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Php"></a>33 SWIG and PHP</H1> +<H1><a name="Php"></a>34 SWIG and PHP</H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -29,6 +29,7 @@ <li><a href="#Php_nn2_6_2">Constructors and Destructors</a> <li><a href="#Php_nn2_6_3">Static Member Variables</a> <li><a href="#Php_nn2_6_4">Static Member Functions</a> +<li><a href="#Php_nn2_6_5">Specifying Implemented Interfaces</a> </ul> <li><a href="#Php_nn2_7">PHP Pragmas, Startup and Shutdown code</a> </ul> @@ -79,7 +80,7 @@ your extension into php directly, you will need the complete PHP source tree available. </p> -<H2><a name="Php_nn1"></a>33.1 Generating PHP Extensions</H2> +<H2><a name="Php_nn1"></a>34.1 Generating PHP Extensions</H2> <p> @@ -113,9 +114,7 @@ more detail in <a href="#Php_nn2_6">section 27.2.6</a>. <p> The usual (and recommended) way is to build the extension as a separate dynamically loaded module (which is supported by all modern operating -systems). You can then specify that this be loaded -automatically in <tt>php.ini</tt> or load it explicitly for any script which -needs it. +systems). </p> <p> @@ -126,7 +125,7 @@ and it doesn't play nicely with package system. We don't recommend this approach, or provide explicit support for it. </p> -<H3><a name="Php_nn1_1"></a>33.1.1 Building a loadable extension</H3> +<H3><a name="Php_nn1_1"></a>34.1.1 Building a loadable extension</H3> <p> @@ -137,16 +136,16 @@ least work for Linux though): </p> <div class="code"><pre> - gcc `php-config --includes` -fpic -c example_wrap.c - gcc -shared example_wrap.o -o example.so + gcc `php-config --includes` -fpic -c example_wrap.c example.c + gcc -shared example_wrap.o example.o -o example.so </pre></div> -<H3><a name="Php_nn1_3"></a>33.1.2 Using PHP Extensions</H3> +<H3><a name="Php_nn1_3"></a>34.1.2 Using PHP Extensions</H3> <p> -To test the extension from a PHP script, you need to load it first. You -can load it for every script by adding this line to the <tt>[PHP]</tt> section of +To test the extension from a PHP script, you first need to tell PHP to +load it. To do this, add a line like this to the <tt>[PHP]</tt> section of <tt>php.ini</tt>: </p> @@ -155,8 +154,14 @@ can load it for every script by adding this line to the <tt>[PHP]</tt> section o </pre></div> <p> -Alternatively, you can load it explicitly only for scripts which need it -by adding this line to the start of each such PHP script:: +If the module is in PHP's default extension directory, you can omit the path. +</p> + +<p> +For some SAPIs (for example, the CLI SAPI) you can instead use the +<a href="http://php.net/manual/en/function.dl.php">dl() function</a> to load +an extension at run time, by adding a like like this to the start of each +PHP script which uses your extension: </p> <div class="code"><pre> @@ -164,15 +169,26 @@ by adding this line to the start of each such PHP script:: </pre></div> <p> -SWIG also generates a php module, which -attempts to do the <tt>dl()</tt> call for you: +But note that this doesn't work when running PHP through a webserver in PHP5.3 +and later - you'll need to use <tt>extension</tt> in <tt>php.ini</tt> as +described above. +</p> + +<p> +The PHP module which SWIG generates will also attempt to do the <tt>dl()</tt> +call for you if the extension isn't already loaded: </p> <div class="code"><pre> include("example.php"); </pre></div> -<H2><a name="Php_nn2"></a>33.2 Basic PHP interface</H2> +<p> +This PHP module also defines the PHP classes for the wrapped API, so you'll +almost certainly want to include it anyway. +</p> + +<H2><a name="Php_nn2"></a>34.2 Basic PHP interface</H2> <p> @@ -183,7 +199,7 @@ other symbols unless care is taken to <tt>%rename</tt> them. At present SWIG doesn't have support for the namespace feature added in PHP 5.3. </p> -<H3><a name="Php_nn2_1"></a>33.2.1 Constants</H3> +<H3><a name="Php_nn2_1"></a>34.2.1 Constants</H3> <p> @@ -220,9 +236,9 @@ echo "E = " . E . "\n"; <p> There's one peculiarity of how constants work in PHP which it is useful to note (this is not specific to SWIG though) - if you try to use an undeclared -constant, PHP will issue a warning and then expand the constant to a string -version of the constant's name. The warning will often be missed though as -if you're using PHP in a webserver, it will probably end up in error.log or +constant, PHP will emit a notice and then expand the constant to a string +version of the constant's name. Unfortunately it is easy to miss the notice +if you're using PHP in a webserver, as it will probably end up in error.log or similar. </p> @@ -260,7 +276,7 @@ is treated as true by the if test, when the value of the intended constant would be treated as false! </p> -<H3><a name="Php_nn2_2"></a>33.2.2 Global Variables</H3> +<H3><a name="Php_nn2_2"></a>34.2.2 Global Variables</H3> <p> @@ -309,7 +325,7 @@ undefined. At this time SWIG does not support custom accessor methods. </p> -<H3><a name="Php_nn2_3"></a>33.2.3 Functions</H3> +<H3><a name="Php_nn2_3"></a>34.2.3 Functions</H3> <p> @@ -362,7 +378,7 @@ print $s; # The value of $s was not changed. --> -<H3><a name="Php_nn2_4"></a>33.2.4 Overloading</H3> +<H3><a name="Php_nn2_4"></a>34.2.4 Overloading</H3> <p> @@ -418,7 +434,7 @@ taking the integer argument. </p> --> -<H3><a name="Php_nn2_5"></a>33.2.5 Pointers and References</H3> +<H3><a name="Php_nn2_5"></a>34.2.5 Pointers and References</H3> <p> @@ -563,7 +579,7 @@ PHP in a number of ways: by using <tt>unset</tt> on an existing variable, or assigning <tt>NULL</tt> to a variable. </p> -<H3><a name="Php_nn2_6"></a>33.2.6 Structures and C++ classes</H3> +<H3><a name="Php_nn2_6"></a>34.2.6 Structures and C++ classes</H3> <p> @@ -624,7 +640,7 @@ Would be used in the following way from PHP5: Member variables and methods are accessed using the <tt>-></tt> operator. </p> -<H4><a name="Php_nn2_6_1"></a>33.2.6.1 Using <tt>-noproxy</tt></H4> +<H4><a name="Php_nn2_6_1"></a>34.2.6.1 Using <tt>-noproxy</tt></H4> <p> @@ -650,7 +666,7 @@ Complex_im_set($obj,$d); Complex_im_get($obj); </pre></div> -<H4><a name="Php_nn2_6_2"></a>33.2.6.2 Constructors and Destructors</H4> +<H4><a name="Php_nn2_6_2"></a>34.2.6.2 Constructors and Destructors</H4> <p> @@ -691,7 +707,7 @@ the programmer can either reassign the variable or call <tt>unset($v)</tt> </p> -<H4><a name="Php_nn2_6_3"></a>33.2.6.3 Static Member Variables</H4> +<H4><a name="Php_nn2_6_3"></a>34.2.6.3 Static Member Variables</H4> <p> @@ -734,7 +750,7 @@ Ko::threats(10); echo "There have now been " . Ko::threats() . " threats\n"; </pre></div> -<H4><a name="Php_nn2_6_4"></a>33.2.6.4 Static Member Functions</H4> +<H4><a name="Php_nn2_6_4"></a>34.2.6.4 Static Member Functions</H4> <p> @@ -756,7 +772,25 @@ Ko::threats(); </pre></div> -<H3><a name="Php_nn2_7"></a>33.2.7 PHP Pragmas, Startup and Shutdown code</H3> +<H4><a name="Php_nn2_6_5"></a>34.2.6.5 Specifying Implemented Interfaces</H4> + + +<p> +PHP supports the concept of abstract interfaces which a class can implement. +Since SWIG 3.0.3, you can tell SWIG that a wrapped class (for example +<code>MyIterator</code>) implements the <code>Iterator</code> interface like +so: +</p> + +<div class="code"><pre> +%typemap("phpinterfaces") MyIterator "Iterator"; +</pre></div> + +<p> +If there are multiple interfaces, just list them separated by commas. +</p> + +<H3><a name="Php_nn2_7"></a>34.2.7 PHP Pragmas, Startup and Shutdown code</H3> <p> @@ -844,7 +878,7 @@ The <tt>%rinit</tt> and <tt>%rshutdown</tt> statements are very similar but inse into the request init (PHP_RINIT_FUNCTION) and request shutdown (PHP_RSHUTDOWN_FUNCTION) code respectively. </p> -<H2><a name="Php_nn3"></a>33.3 Cross language polymorphism</H2> +<H2><a name="Php_nn3"></a>34.3 Cross language polymorphism</H2> <p> @@ -879,7 +913,7 @@ wrapper functions takes care of all the cross-language method routing transparently. </p> -<H3><a name="Php_nn3_1"></a>33.3.1 Enabling directors</H3> +<H3><a name="Php_nn3_1"></a>34.3.1 Enabling directors</H3> <p> @@ -968,7 +1002,7 @@ class MyFoo extends Foo { </div> -<H3><a name="Php_nn3_2"></a>33.3.2 Director classes</H3> +<H3><a name="Php_nn3_2"></a>34.3.2 Director classes</H3> @@ -1048,7 +1082,7 @@ so there is no need for the extra overhead involved with routing the calls through PHP. </p> -<H3><a name="Php_nn3_3"></a>33.3.3 Ownership and object destruction</H3> +<H3><a name="Php_nn3_3"></a>34.3.3 Ownership and object destruction</H3> <p> @@ -1104,7 +1138,7 @@ In this example, we are assuming that FooContainer will take care of deleting all the Foo pointers it contains at some point. </p> -<H3><a name="Php_nn3_4"></a>33.3.4 Exception unrolling</H3> +<H3><a name="Php_nn3_4"></a>34.3.4 Exception unrolling</H3> <p> @@ -1163,7 +1197,7 @@ Swig::DirectorMethodException is thrown, PHP will register the exception as soon as the C wrapper function returns. </p> -<H3><a name="Php_nn3_5"></a>33.3.5 Overhead and code bloat</H3> +<H3><a name="Php_nn3_5"></a>34.3.5 Overhead and code bloat</H3> <p> @@ -1196,7 +1230,7 @@ optimized by selectively enabling director methods (using the %feature directive) for only those methods that are likely to be extended in PHP. </p> -<H3><a name="Php_nn3_6"></a>33.3.6 Typemaps</H3> +<H3><a name="Php_nn3_6"></a>34.3.6 Typemaps</H3> <p> @@ -1210,7 +1244,7 @@ need to be supported. </p> -<H3><a name="Php_nn3_7"></a>33.3.7 Miscellaneous</H3> +<H3><a name="Php_nn3_7"></a>34.3.7 Miscellaneous</H3> <p> Director typemaps for STL classes are mostly in place, and hence you diff --git a/Doc/Manual/Pike.html b/Doc/Manual/Pike.html index 3ede1a992..44c6930f8 100644 --- a/Doc/Manual/Pike.html +++ b/Doc/Manual/Pike.html @@ -6,7 +6,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Pike"></a>34 SWIG and Pike</H1> +<H1><a name="Pike"></a>35 SWIG and Pike</H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -46,10 +46,10 @@ least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>" chapter.<br> </p> -<H2><a name="Pike_nn2"></a>34.1 Preliminaries</H2> +<H2><a name="Pike_nn2"></a>35.1 Preliminaries</H2> -<H3><a name="Pike_nn3"></a>34.1.1 Running SWIG</H3> +<H3><a name="Pike_nn3"></a>35.1.1 Running SWIG</H3> <p> @@ -94,7 +94,7 @@ can use the <tt>-o</tt> option: <div class="code"> <pre>$ <b>swig -pike -o pseudonym.c example.i</b><br></pre> </div> -<H3><a name="Pike_nn4"></a>34.1.2 Getting the right header files</H3> +<H3><a name="Pike_nn4"></a>35.1.2 Getting the right header files</H3> <p> @@ -114,7 +114,7 @@ You're looking for files with the names <tt>global.h</tt>, <tt>program.h</tt> and so on. </p> -<H3><a name="Pike_nn5"></a>34.1.3 Using your module</H3> +<H3><a name="Pike_nn5"></a>35.1.3 Using your module</H3> <p> @@ -129,10 +129,10 @@ Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend) (1) Result: 24 </pre></div> -<H2><a name="Pike_nn6"></a>34.2 Basic C/C++ Mapping</H2> +<H2><a name="Pike_nn6"></a>35.2 Basic C/C++ Mapping</H2> -<H3><a name="Pike_nn7"></a>34.2.1 Modules</H3> +<H3><a name="Pike_nn7"></a>35.2.1 Modules</H3> <p> @@ -143,7 +143,7 @@ concerned), SWIG's <tt>%module</tt> directive doesn't really have any significance. </p> -<H3><a name="Pike_nn8"></a>34.2.2 Functions</H3> +<H3><a name="Pike_nn8"></a>35.2.2 Functions</H3> <p> @@ -168,7 +168,7 @@ exactly as you'd expect it to: (1) Result: 24 </pre></div> -<H3><a name="Pike_nn9"></a>34.2.3 Global variables</H3> +<H3><a name="Pike_nn9"></a>35.2.3 Global variables</H3> <p> @@ -197,7 +197,7 @@ will result in two functions, <tt>Foo_get()</tt> and <tt>Foo_set()</tt>: (3) Result: 3.141590 </pre></div> -<H3><a name="Pike_nn10"></a>34.2.4 Constants and enumerated types</H3> +<H3><a name="Pike_nn10"></a>35.2.4 Constants and enumerated types</H3> <p> @@ -205,7 +205,7 @@ Enumerated types in C/C++ declarations are wrapped as Pike constants, not as Pike enums. </p> -<H3><a name="Pike_nn11"></a>34.2.5 Constructors and Destructors</H3> +<H3><a name="Pike_nn11"></a>35.2.5 Constructors and Destructors</H3> <p> @@ -213,7 +213,7 @@ Constructors are wrapped as <tt>create()</tt> methods, and destructors are wrapped as <tt>destroy()</tt> methods, for Pike classes. </p> -<H3><a name="Pike_nn12"></a>34.2.6 Static Members</H3> +<H3><a name="Pike_nn12"></a>35.2.6 Static Members</H3> <p> diff --git a/Doc/Manual/Python.html b/Doc/Manual/Python.html index dcfd7427e..eb102aa3e 100644 --- a/Doc/Manual/Python.html +++ b/Doc/Manual/Python.html @@ -6,7 +6,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Python"></a>35 SWIG and Python</H1> +<H1><a name="Python"></a>36 SWIG and Python</H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -116,6 +116,7 @@ <li><a href="#Python_nn74">Function annotation</a> <li><a href="#Python_nn75">Buffer interface</a> <li><a href="#Python_nn76">Abstract base classes</a> +<li><a href="#Python_nn77">Byte string output conversion</a> </ul> </ul> </div> @@ -141,7 +142,7 @@ very least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>" chapter. </p> -<H2><a name="Python_nn2"></a>35.1 Overview</H2> +<H2><a name="Python_nn2"></a>36.1 Overview</H2> <p> @@ -168,10 +169,10 @@ described followed by a discussion of low-level implementation details. </p> -<H2><a name="Python_nn3"></a>35.2 Preliminaries</H2> +<H2><a name="Python_nn3"></a>36.2 Preliminaries</H2> -<H3><a name="Python_nn4"></a>35.2.1 Running SWIG</H3> +<H3><a name="Python_nn4"></a>36.2.1 Running SWIG</H3> <p> @@ -193,7 +194,7 @@ int fact(int n); </div> <p> -The <tt> #define SWIG_FILE_WITH_INIT </tt> line inserts a macro that specifies that the +The <tt>#define SWIG_FILE_WITH_INIT</tt> line inserts a macro that specifies that the resulting C file should be built as a python extension, inserting the module <tt>init</tt> code. This <tt>.i</tt> file wraps the following simple C file: </p> @@ -269,7 +270,7 @@ The following sections have further practical examples and details on how you might go about compiling and using the generated files. </p> -<H3><a name="Python_nn6"></a>35.2.2 Using distutils</H3> +<H3><a name="Python_nn6"></a>36.2.2 Using distutils</H3> <p> @@ -361,7 +362,7 @@ This same approach works on all platforms if the appropriate compiler is install can even build extensions to the standard Windows Python using MingGW) </p> -<H3><a name="Python_nn7"></a>35.2.3 Hand compiling a dynamic module</H3> +<H3><a name="Python_nn7"></a>36.2.3 Hand compiling a dynamic module</H3> <p> @@ -394,7 +395,7 @@ of the module prefixed by an underscore</b>. If the name of your module is "<tt name of the corresponding object file should be "<tt>_example.so</tt>" or "<tt>_examplemodule.so</tt>". The name of the module is specified using the <tt>%module</tt> directive or the -<tt> -module</tt> command line option. +<tt>-module</tt> command line option. </p> <p> @@ -409,7 +410,7 @@ module actually consists of two files; <tt>socket.py</tt> and </p> -<H3><a name="Python_nn8"></a>35.2.4 Static linking</H3> +<H3><a name="Python_nn8"></a>36.2.4 Static linking</H3> <p> @@ -488,7 +489,7 @@ If using static linking, you might want to rely on a different approach (perhaps using distutils). </p> -<H3><a name="Python_nn9"></a>35.2.5 Using your module</H3> +<H3><a name="Python_nn9"></a>36.2.5 Using your module</H3> <p> @@ -645,7 +646,7 @@ system configuration (this requires root access and you will need to read the man pages). </p> -<H3><a name="Python_nn10"></a>35.2.6 Compilation of C++ extensions</H3> +<H3><a name="Python_nn10"></a>36.2.6 Compilation of C++ extensions</H3> <p> @@ -737,7 +738,7 @@ erratic program behavior. If working with lots of software components, you might want to investigate using a more formal standard such as COM. </p> -<H3><a name="Python_nn11"></a>35.2.7 Compiling for 64-bit platforms</H3> +<H3><a name="Python_nn11"></a>36.2.7 Compiling for 64-bit platforms</H3> <p> @@ -774,7 +775,7 @@ and -m64 allow you to choose the desired binary format for your python extension. </p> -<H3><a name="Python_nn12"></a>35.2.8 Building Python Extensions under Windows</H3> +<H3><a name="Python_nn12"></a>36.2.8 Building Python Extensions under Windows</H3> <p> @@ -782,8 +783,8 @@ Building a SWIG extension to Python under Windows is roughly similar to the process used with Unix. Using the distutils, it is essentially identical. If you have the same version of the MS compiler that Python was built with (the python2.4 and python2.5 distributed by python.org -are built with Visual Studio 2003), the standard <tt> python setup.py -build </tt> should just work. +are built with Visual Studio 2003), the standard <tt>python setup.py +build</tt> should just work. </p> <p> @@ -903,7 +904,7 @@ SWIG Wiki</a>. </p> -<H2><a name="Python_nn13"></a>35.3 A tour of basic C/C++ wrapping</H2> +<H2><a name="Python_nn13"></a>36.3 A tour of basic C/C++ wrapping</H2> <p> @@ -912,7 +913,7 @@ to your C/C++ code. Functions are wrapped as functions, classes are wrapped as This section briefly covers the essential aspects of this wrapping. </p> -<H3><a name="Python_nn14"></a>35.3.1 Modules</H3> +<H3><a name="Python_nn14"></a>36.3.1 Modules</H3> <p> @@ -925,7 +926,7 @@ module name, make sure you don't use the same name as a built-in Python command or standard module name. </p> -<H3><a name="Python_nn15"></a>35.3.2 Functions</H3> +<H3><a name="Python_nn15"></a>36.3.2 Functions</H3> <p> @@ -949,7 +950,7 @@ like you think it does: >>> </pre></div> -<H3><a name="Python_nn16"></a>35.3.3 Global variables</H3> +<H3><a name="Python_nn16"></a>36.3.3 Global variables</H3> <p> @@ -1087,7 +1088,7 @@ that starts with a leading underscore. SWIG does not create <tt>cvar</tt> if there are no global variables in a module. </p> -<H3><a name="Python_nn17"></a>35.3.4 Constants and enums</H3> +<H3><a name="Python_nn17"></a>36.3.4 Constants and enums</H3> <p> @@ -1127,7 +1128,7 @@ other object. Unfortunately, there is no easy way for SWIG to generate code that prevents this. You will just have to be careful. </p> -<H3><a name="Python_nn18"></a>35.3.5 Pointers</H3> +<H3><a name="Python_nn18"></a>36.3.5 Pointers</H3> <p> @@ -1268,7 +1269,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return <tt>None</tt> if the conversion can't be performed. </p> -<H3><a name="Python_nn19"></a>35.3.6 Structures</H3> +<H3><a name="Python_nn19"></a>36.3.6 Structures</H3> <p> @@ -1457,7 +1458,7 @@ everything works just like you would expect. For example: </pre> </div> -<H3><a name="Python_nn20"></a>35.3.7 C++ classes</H3> +<H3><a name="Python_nn20"></a>36.3.7 C++ classes</H3> <p> @@ -1546,7 +1547,7 @@ they are accessed through <tt>cvar</tt> like this: </pre> </div> -<H3><a name="Python_nn21"></a>35.3.8 C++ inheritance</H3> +<H3><a name="Python_nn21"></a>36.3.8 C++ inheritance</H3> <p> @@ -1601,7 +1602,7 @@ then the function <tt>spam()</tt> accepts <tt>Foo *</tt> or a pointer to any cla It is safe to use multiple inheritance with SWIG. </p> -<H3><a name="Python_nn22"></a>35.3.9 Pointers, references, values, and arrays</H3> +<H3><a name="Python_nn22"></a>36.3.9 Pointers, references, values, and arrays</H3> <p> @@ -1662,7 +1663,7 @@ treated as a returning value, and it will follow the same allocation/deallocation process. </p> -<H3><a name="Python_nn23"></a>35.3.10 C++ overloaded functions</H3> +<H3><a name="Python_nn23"></a>36.3.10 C++ overloaded functions</H3> <p> @@ -1785,7 +1786,7 @@ first declaration takes precedence. Please refer to the "SWIG and C++" chapter for more information about overloading. </p> -<H3><a name="Python_nn24"></a>35.3.11 C++ operators</H3> +<H3><a name="Python_nn24"></a>36.3.11 C++ operators</H3> <p> @@ -1874,7 +1875,7 @@ Also, be aware that certain operators don't map cleanly to Python. For instance overloaded assignment operators don't map to Python semantics and will be ignored. </p> -<H3><a name="Python_nn25"></a>35.3.12 C++ namespaces</H3> +<H3><a name="Python_nn25"></a>36.3.12 C++ namespaces</H3> <p> @@ -1941,7 +1942,7 @@ utilizes thousands of small deeply nested namespaces each with identical symbol names, well, then you get what you deserve. </p> -<H3><a name="Python_nn26"></a>35.3.13 C++ templates</H3> +<H3><a name="Python_nn26"></a>36.3.13 C++ templates</H3> <p> @@ -1995,7 +1996,7 @@ Some more complicated examples will appear later. </p> -<H3><a name="Python_nn27"></a>35.3.14 C++ Smart Pointers</H3> +<H3><a name="Python_nn27"></a>36.3.14 C++ Smart Pointers</H3> <p> @@ -2079,7 +2080,7 @@ simply use the <tt>__deref__()</tt> method. For example: </pre> </div> -<H3><a name="Python_nn27a"></a>35.3.15 C++ reference counted objects</H3> +<H3><a name="Python_nn27a"></a>36.3.15 C++ reference counted objects</H3> <p> @@ -2088,7 +2089,7 @@ Python examples of memory management using referencing counting. </p> -<H2><a name="Python_nn28"></a>35.4 Further details on the Python class interface</H2> +<H2><a name="Python_nn28"></a>36.4 Further details on the Python class interface</H2> <p> @@ -2111,7 +2112,7 @@ the <tt>-builtin</tt> option are in the <a href="#Python_builtin_types">Built-in section. </p> -<H3><a name="Python_nn29"></a>35.4.1 Proxy classes</H3> +<H3><a name="Python_nn29"></a>36.4.1 Proxy classes</H3> <p> @@ -2200,7 +2201,7 @@ you can attach new Python methods to the class and you can even inherit from it by Python built-in types until Python 2.2). </p> -<H3><a name="Python_builtin_types"></a>35.4.2 Built-in Types</H3> +<H3><a name="Python_builtin_types"></a>36.4.2 Built-in Types</H3> <p> @@ -2244,7 +2245,7 @@ please refer to the python documentation:</p> <p><a href="http://docs.python.org/extending/newtypes.html">http://docs.python.org/extending/newtypes.html</a></p> -<H4><a name="Python_builtin_limitations"></a>35.4.2.1 Limitations</H4> +<H4><a name="Python_builtin_limitations"></a>36.4.2.1 Limitations</H4> <p>Use of the <tt>-builtin</tt> option implies a couple of limitations: @@ -2412,7 +2413,7 @@ assert(issubclass(B.Derived, A.Base)) </li> </ul> -<H4><a name="Python_builtin_overloads"></a>35.4.2.2 Operator overloads -- use them!</H4> +<H4><a name="Python_builtin_overloads"></a>36.4.2.2 Operator overloads -- use them!</H4> <p>The entire justification for the <tt>-builtin</tt> option is improved @@ -2513,7 +2514,7 @@ structs. </p> -<H3><a name="Python_nn30"></a>35.4.3 Memory management</H3> +<H3><a name="Python_nn30"></a>36.4.3 Memory management</H3> <p>NOTE: Although this section refers to proxy objects, everything here also applies @@ -2708,7 +2709,7 @@ It is also possible to deal with situations like this using typemaps--an advanced topic discussed later. </p> -<H3><a name="Python_nn31"></a>35.4.4 Python 2.2 and classic classes</H3> +<H3><a name="Python_nn31"></a>36.4.4 Python 2.2 and classic classes</H3> <p> @@ -2745,7 +2746,7 @@ class itself. In Python-2.1 and earlier, they have to be accessed as a global function or through an instance (see the earlier section). </p> -<H2><a name="Python_directors"></a>35.5 Cross language polymorphism</H2> +<H2><a name="Python_directors"></a>36.5 Cross language polymorphism</H2> <p> @@ -2779,7 +2780,7 @@ proxy classes, director classes, and C wrapper functions takes care of all the cross-language method routing transparently. </p> -<H3><a name="Python_nn33"></a>35.5.1 Enabling directors</H3> +<H3><a name="Python_nn33"></a>36.5.1 Enabling directors</H3> <p> @@ -2869,7 +2870,7 @@ class MyFoo(mymodule.Foo): </div> -<H3><a name="Python_nn34"></a>35.5.2 Director classes</H3> +<H3><a name="Python_nn34"></a>36.5.2 Director classes</H3> @@ -2951,7 +2952,7 @@ so there is no need for the extra overhead involved with routing the calls through Python. </p> -<H3><a name="Python_nn35"></a>35.5.3 Ownership and object destruction</H3> +<H3><a name="Python_nn35"></a>36.5.3 Ownership and object destruction</H3> <p> @@ -3018,7 +3019,7 @@ deleting all the Foo pointers it contains at some point. Note that no hard references to the Foo objects remain in Python. </p> -<H3><a name="Python_nn36"></a>35.5.4 Exception unrolling</H3> +<H3><a name="Python_nn36"></a>36.5.4 Exception unrolling</H3> <p> @@ -3077,7 +3078,7 @@ Swig::DirectorMethodException is thrown, Python will register the exception as soon as the C wrapper function returns. </p> -<H3><a name="Python_nn37"></a>35.5.5 Overhead and code bloat</H3> +<H3><a name="Python_nn37"></a>36.5.5 Overhead and code bloat</H3> <p> @@ -3111,7 +3112,7 @@ directive) for only those methods that are likely to be extended in Python. </p> -<H3><a name="Python_nn38"></a>35.5.6 Typemaps</H3> +<H3><a name="Python_nn38"></a>36.5.6 Typemaps</H3> <p> @@ -3125,7 +3126,7 @@ need to be supported. </p> -<H3><a name="Python_nn39"></a>35.5.7 Miscellaneous</H3> +<H3><a name="Python_nn39"></a>36.5.7 Miscellaneous</H3> <p> @@ -3172,7 +3173,7 @@ methods that return const references. </p> -<H2><a name="Python_nn40"></a>35.6 Common customization features</H2> +<H2><a name="Python_nn40"></a>36.6 Common customization features</H2> <p> @@ -3185,7 +3186,7 @@ This section describes some common SWIG features that are used to improve your the interface to an extension module. </p> -<H3><a name="Python_nn41"></a>35.6.1 C/C++ helper functions</H3> +<H3><a name="Python_nn41"></a>36.6.1 C/C++ helper functions</H3> <p> @@ -3266,7 +3267,7 @@ hard to implement. It is possible to clean this up using Python code, typemaps, customization features as covered in later sections. </p> -<H3><a name="Python_nn42"></a>35.6.2 Adding additional Python code</H3> +<H3><a name="Python_nn42"></a>36.6.2 Adding additional Python code</H3> <p> @@ -3367,6 +3368,18 @@ print("Loading", "Whizz", "Bang", sep=' ... ') </pre> </div> +<p>When using <tt>%pythoncode</tt> and <tt>%pythonbegin</tt> you generally +want to make sure that the block is delimited by <tt>%{</tt> and <tt>%}</tt>. +If you delimit it with <tt>{</tt> and <tt>}</tt> then any lines with a +leading <tt>#</tt> will be handled by SWIG as preprocessor directives, when +you probably meant them as Python comments. Prior to SWIG 3.0.3, invalid +preprocessor directives were silently ignored, so generally using the wrong +delimiters resulted in such comments not appearing in the generated output +(though a comment starting with a valid preprocessor directive could cause +problems, for example: <tt># error handling</tt>). SWIG 3.0.3 and later report +an error for invalid preprocessor directives, so you may have to update +existing interface files to delimit blocks of Python code correctly.</p> + <p>Sometimes you may want to replace or modify the wrapper function that SWIG creates in the proxy <tt>.py</tt> file. The Python module in SWIG provides some features that enable you to do this. First, to @@ -3494,7 +3507,7 @@ The same applies for overloaded constructors. </p> -<H3><a name="Python_nn43"></a>35.6.3 Class extension with %extend</H3> +<H3><a name="Python_nn43"></a>36.6.3 Class extension with %extend</H3> <p> @@ -3583,7 +3596,7 @@ Vector(12,14,16) in any way---the extensions only show up in the Python interface. </p> -<H3><a name="Python_nn44"></a>35.6.4 Exception handling with %exception</H3> +<H3><a name="Python_nn44"></a>36.6.4 Exception handling with %exception</H3> <p> @@ -3709,7 +3722,7 @@ The language-independent <tt>exception.i</tt> library file can also be used to raise exceptions. See the <a href="Library.html#Library">SWIG Library</a> chapter. </p> -<H2><a name="Python_nn45"></a>35.7 Tips and techniques</H2> +<H2><a name="Python_nn45"></a>36.7 Tips and techniques</H2> <p> @@ -3719,7 +3732,7 @@ strings, binary data, and arrays. This chapter discusses the common techniques solving these problems. </p> -<H3><a name="Python_nn46"></a>35.7.1 Input and output parameters</H3> +<H3><a name="Python_nn46"></a>36.7.1 Input and output parameters</H3> <p> @@ -3932,7 +3945,7 @@ void foo(Bar *OUTPUT); may not have the intended effect since <tt>typemaps.i</tt> does not define an OUTPUT rule for <tt>Bar</tt>. </p> -<H3><a name="Python_nn47"></a>35.7.2 Simple pointers</H3> +<H3><a name="Python_nn47"></a>36.7.2 Simple pointers</H3> <p> @@ -4001,7 +4014,7 @@ If you replace <tt>%pointer_functions()</tt> by <tt>%pointer_class(type,name)</t See the <a href="Library.html#Library">SWIG Library</a> chapter for further details. </p> -<H3><a name="Python_nn48"></a>35.7.3 Unbounded C Arrays</H3> +<H3><a name="Python_nn48"></a>36.7.3 Unbounded C Arrays</H3> <p> @@ -4063,7 +4076,7 @@ well suited for applications in which you need to create buffers, package binary data, etc. </p> -<H3><a name="Python_nn49"></a>35.7.4 String handling</H3> +<H3><a name="Python_nn49"></a>36.7.4 String handling</H3> <p> @@ -4132,7 +4145,7 @@ If you need to return binary data, you might use the also be used to extra binary data from arbitrary pointers. </p> -<H2><a name="Python_nn53"></a>35.8 Typemaps</H2> +<H2><a name="Python_nn53"></a>36.8 Typemaps</H2> <p> @@ -4149,7 +4162,7 @@ Typemaps are only used if you want to change some aspect of the primitive C-Python interface or if you want to elevate your guru status. </p> -<H3><a name="Python_nn54"></a>35.8.1 What is a typemap?</H3> +<H3><a name="Python_nn54"></a>36.8.1 What is a typemap?</H3> <p> @@ -4265,7 +4278,7 @@ parameter is omitted): </pre> </div> -<H3><a name="Python_nn55"></a>35.8.2 Python typemaps</H3> +<H3><a name="Python_nn55"></a>36.8.2 Python typemaps</H3> <p> @@ -4306,7 +4319,7 @@ a look at the SWIG library version 1.3.20 or so. </p> -<H3><a name="Python_nn56"></a>35.8.3 Typemap variables</H3> +<H3><a name="Python_nn56"></a>36.8.3 Typemap variables</H3> <p> @@ -4377,7 +4390,7 @@ properly assigned. The Python name of the wrapper function being created. </div> -<H3><a name="Python_nn57"></a>35.8.4 Useful Python Functions</H3> +<H3><a name="Python_nn57"></a>36.8.4 Useful Python Functions</H3> <p> @@ -4505,7 +4518,7 @@ write me </pre> </div> -<H2><a name="Python_nn58"></a>35.9 Typemap Examples</H2> +<H2><a name="Python_nn58"></a>36.9 Typemap Examples</H2> <p> @@ -4514,7 +4527,7 @@ might look at the files "<tt>python.swg</tt>" and "<tt>typemaps.i</tt>" in the SWIG library. </p> -<H3><a name="Python_nn59"></a>35.9.1 Converting Python list to a char ** </H3> +<H3><a name="Python_nn59"></a>36.9.1 Converting Python list to a char ** </H3> <p> @@ -4594,7 +4607,7 @@ memory allocation is used to allocate memory for the array, the the C function. </p> -<H3><a name="Python_nn60"></a>35.9.2 Expanding a Python object into multiple arguments</H3> +<H3><a name="Python_nn60"></a>36.9.2 Expanding a Python object into multiple arguments</H3> <p> @@ -4673,7 +4686,7 @@ to supply the argument count. This is automatically set by the typemap code. F </pre> </div> -<H3><a name="Python_nn61"></a>35.9.3 Using typemaps to return arguments</H3> +<H3><a name="Python_nn61"></a>36.9.3 Using typemaps to return arguments</H3> <p> @@ -4761,7 +4774,7 @@ function can now be used as follows: >>> </pre></div> -<H3><a name="Python_nn62"></a>35.9.4 Mapping Python tuples into small arrays</H3> +<H3><a name="Python_nn62"></a>36.9.4 Mapping Python tuples into small arrays</H3> <p> @@ -4810,7 +4823,7 @@ array, such an approach would not be recommended for huge arrays, but for small structures, this approach works fine. </p> -<H3><a name="Python_nn63"></a>35.9.5 Mapping sequences to C arrays</H3> +<H3><a name="Python_nn63"></a>36.9.5 Mapping sequences to C arrays</H3> <p> @@ -4899,7 +4912,7 @@ static int convert_darray(PyObject *input, double *ptr, int size) { </pre> </div> -<H3><a name="Python_nn64"></a>35.9.6 Pointer handling</H3> +<H3><a name="Python_nn64"></a>36.9.6 Pointer handling</H3> <p> @@ -4996,7 +5009,7 @@ class object (if applicable). -<H2><a name="Python_nn65"></a>35.10 Docstring Features</H2> +<H2><a name="Python_nn65"></a>36.10 Docstring Features</H2> <p> @@ -5024,7 +5037,7 @@ of your users much simpler. </p> -<H3><a name="Python_nn66"></a>35.10.1 Module docstring</H3> +<H3><a name="Python_nn66"></a>36.10.1 Module docstring</H3> <p> @@ -5058,7 +5071,7 @@ layout of controls on a panel, etc. to be loaded from an XML file." </div> -<H3><a name="Python_nn67"></a>35.10.2 %feature("autodoc")</H3> +<H3><a name="Python_nn67"></a>36.10.2 %feature("autodoc")</H3> <p> @@ -5086,7 +5099,7 @@ four levels for autodoc controlled by the value given to the feature, <tt>%feature("autodoc", "<i>level</i>")</tt>. The four values for <i>level</i> are covered in the following sub-sections. -<H4><a name="Python_nn68"></a>35.10.2.1 %feature("autodoc", "0")</H4> +<H4><a name="Python_nn68"></a>36.10.2.1 %feature("autodoc", "0")</H4> <p> @@ -5115,7 +5128,7 @@ def function_name(*args, **kwargs): </div> -<H4><a name="Python_nn69"></a>35.10.2.2 %feature("autodoc", "1")</H4> +<H4><a name="Python_nn69"></a>36.10.2.2 %feature("autodoc", "1")</H4> <p> @@ -5140,7 +5153,7 @@ def function_name(*args, **kwargs): </div> -<H4><a name="Python_autodoc2"></a>35.10.2.3 %feature("autodoc", "2")</H4> +<H4><a name="Python_autodoc2"></a>36.10.2.3 %feature("autodoc", "2")</H4> <p> @@ -5200,7 +5213,7 @@ def function_name(*args, **kwargs): </pre> </div> -<H4><a name="Python_autodoc3"></a>35.10.2.4 %feature("autodoc", "3")</H4> +<H4><a name="Python_autodoc3"></a>36.10.2.4 %feature("autodoc", "3")</H4> <p> @@ -5225,7 +5238,7 @@ def function_name(*args, **kwargs): </div> -<H4><a name="Python_nn70"></a>35.10.2.5 %feature("autodoc", "docstring")</H4> +<H4><a name="Python_nn70"></a>36.10.2.5 %feature("autodoc", "docstring")</H4> <p> @@ -5244,7 +5257,7 @@ void GetPosition(int* OUTPUT, int* OUTPUT); </div> -<H3><a name="Python_nn71"></a>35.10.3 %feature("docstring")</H3> +<H3><a name="Python_nn71"></a>36.10.3 %feature("docstring")</H3> <p> @@ -5276,7 +5289,7 @@ with more than one line. </pre> </div> -<H2><a name="Python_nn72"></a>35.11 Python Packages</H2> +<H2><a name="Python_nn72"></a>36.11 Python Packages</H2> <p>Python has concepts of modules and packages. Modules are separate units of @@ -5334,7 +5347,7 @@ users may need to use special features such as the <tt>package</tt> option in th <tt>%module</tt> directive or import related command line options. These are explained in the following sections.</p> -<H3><a name="Python_modulepackage"></a>35.11.1 Setting the Python package</H3> +<H3><a name="Python_modulepackage"></a>36.11.1 Setting the Python package</H3> <p> @@ -5388,7 +5401,7 @@ pkg1/pkg2/_foo.so # (shared library built from C/C++ code generated by SWI </pre> </div> -<H3><a name="Python_absrelimports"></a>35.11.2 Absolute and relative imports</H3> +<H3><a name="Python_absrelimports"></a>36.11.2 Absolute and relative imports</H3> <p>Suppose, we have the following hierarchy of files:</p> @@ -5412,7 +5425,7 @@ class M3: pass <p> We edit <tt>pkg1/mod2.py</tt> and want to import module -<tt>pkg1/pkg2/pkg3.py</tt> in order to derive from class <tt>M3</tt>. We can +<tt>pkg1/pkg2/mod3.py</tt> in order to derive from class <tt>M3</tt>. We can write appropriate Python code in several ways, for example: </p> @@ -5527,7 +5540,7 @@ uses relative imports. Second case is, when one puts import directives in <tt>__init__.py</tt> to import symbols from submodules or subpackages and the submodule depends on other submodules (discussed later).</p> -<H3><a name="Python_absimport"></a>35.11.3 Enforcing absolute import semantics</H3> +<H3><a name="Python_absimport"></a>36.11.3 Enforcing absolute import semantics</H3> <p>As you may know, there is an incompatibility in import semantics (for the @@ -5564,14 +5577,14 @@ from __future__ import absolute_import </pre> </div> -<H3><a name="Python_importfrominit"></a>35.11.4 Importing from __init__.py</H3> +<H3><a name="Python_importfrominit"></a>36.11.4 Importing from __init__.py</H3> <p>Imports in <tt>__init__.py</tt> are handy when you want to populate a package's namespace with names imported from other modules. In SWIG based projects this approach may also be used to split large pieces of code into -smaller modules, compile them in parallel and then re-assemble everything at another -level by importing submodules' contents in <tt>__init__.py</tt>, for +smaller modules, compile them in parallel and then re-assemble everything at +runtime by importing submodules' contents in <tt>__init__.py</tt>, for example.</p> <p>Unfortunately import directives in <tt>__init__.py</tt> may cause problems, @@ -5675,7 +5688,7 @@ effect (note, that the Python 2 case also needs the <tt>-relativeimport</tt> workaround).</p> -<H2><a name="Python_python3support"></a>35.12 Python 3 Support</H2> +<H2><a name="Python_python3support"></a>36.12 Python 3 Support</H2> <p> @@ -5702,7 +5715,7 @@ The following are Python 3.0 new features that are currently supported by SWIG. </p> -<H3><a name="Python_nn74"></a>35.12.1 Function annotation</H3> +<H3><a name="Python_nn74"></a>36.12.1 Function annotation</H3> <p> @@ -5735,7 +5748,7 @@ For detailed usage of function annotation, see <a href="http://www.python.org/dev/peps/pep-3107/">PEP 3107</a>. </p> -<H3><a name="Python_nn75"></a>35.12.2 Buffer interface</H3> +<H3><a name="Python_nn75"></a>36.12.2 Buffer interface</H3> <p> @@ -5887,7 +5900,7 @@ modify the buffer. </div> -<H3><a name="Python_nn76"></a>35.12.3 Abstract base classes</H3> +<H3><a name="Python_nn76"></a>36.12.3 Abstract base classes</H3> <p> @@ -5928,6 +5941,92 @@ For details of abstract base class, please see <a href="http://www.python.org/dev/peps/pep-3119/">PEP 3119</a>. </p> +<H3><a name="Python_nn77"></a>36.12.4 Byte string output conversion</H3> + + +<p> +By default, any byte string (<tt>char*</tt> or <tt>std::string</tt>) returned +from C or C++ code is decoded to text as UTF-8. This decoding uses the +<tt>surrogateescape</tt> error handler under Python 3.1 or higher -- this +error handler decodes invalid byte sequences to high surrogate characters +in the range U+DC80 to U+DCFF. + +As an example, consider the following SWIG interface, which exposes a byte +string that cannot be completely decoded as UTF-8: +</p> + +<div class="code"><pre> +%module example + +%include <std_string.i> + +%inline %{ + +const char* non_utf8_c_str(void) { + return "h\xe9llo w\xc3\xb6rld"; +} + +%} +</pre></div> + +<p> +When this method is called from Python 3, the return value is the following +text string: +</p> + +<div class="targetlang"><pre> +>>> s = example.non_utf8_c_str() +>>> s +'h\udce9llo wörld' +</pre></div> + +<p> +Since the C string contains bytes that cannot be decoded as UTF-8, those raw +bytes are represented as high surrogate characters that can be used to obtain +the original byte sequence: +</p> + +<div class="targetlang"><pre> +>>> b = s.encode('utf-8', errors='surrogateescape') +>>> b +b'h\xe9llo w\xc3\xb6rld' +</pre></div> + +<p> +One can then attempt a different encoding, if desired (or simply leave the +byte string as a raw sequence of bytes for use in binary protocols): +</p> + +<div class="targetlang"><pre> +>>> b.decode('latin-1') +'héllo wörld' +</pre></div> + +<p> +Note, however, that text strings containing surrogate characters are rejected +with the default <tt>strict</tt> codec error handler. For example: +</p> + +<div class="targetlang"><pre> +>>> with open('test', 'w') as f: +... print(s, file=f) +... +Traceback (most recent call last): + File "<stdin>", line 2, in <module> +UnicodeEncodeError: 'utf-8' codec can't encode character '\udce9' in position 1: surrogates not allowed +</pre></div> + +<p> +This requires the user to check most strings returned by SWIG bindings, but +the alternative is for a non-UTF8 byte string to be completely inaccessible +in Python 3 code. +</p> + +<p> +For more details about the <tt>surrogateescape</tt> error handler, please see +<a href="http://www.python.org/dev/peps/pep-0383/">PEP 383</a>. +</p> + </body> </html> diff --git a/Doc/Manual/R.html b/Doc/Manual/R.html index ce9523ced..5de390eab 100644 --- a/Doc/Manual/R.html +++ b/Doc/Manual/R.html @@ -6,7 +6,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="R"></a>36 SWIG and R</H1> +<H1><a name="R"></a>37 SWIG and R</H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -33,7 +33,7 @@ compile and run an R interface to QuantLib running on Mandriva Linux with gcc. The R bindings also work on Microsoft Windows using Visual C++. </p> -<H2><a name="R_nn2"></a>36.1 Bugs</H2> +<H2><a name="R_nn2"></a>37.1 Bugs</H2> <p> @@ -45,7 +45,7 @@ Currently the following features are not implemented or broken: <li>C Array wrappings </ul> -<H2><a name="R_nn3"></a>36.2 Using R and SWIG</H2> +<H2><a name="R_nn3"></a>37.2 Using R and SWIG</H2> <p> @@ -119,7 +119,7 @@ Without it, inheritance of wrapped objects may fail. These two files can be loaded in any order </p> -<H2><a name="R_nn4"></a>36.3 Precompiling large R files</H2> +<H2><a name="R_nn4"></a>37.3 Precompiling large R files</H2> In cases where the R file is large, one make save a lot of loading @@ -137,7 +137,7 @@ will save a large amount of loading time. -<H2><a name="R_nn5"></a>36.4 General policy</H2> +<H2><a name="R_nn5"></a>37.4 General policy</H2> <p> @@ -146,7 +146,7 @@ wrapping over the underlying functions and rely on the R type system to provide R syntax. </p> -<H2><a name="R_language_conventions"></a>36.5 Language conventions</H2> +<H2><a name="R_language_conventions"></a>37.5 Language conventions</H2> <p> @@ -155,7 +155,7 @@ and [ are overloaded to allow for R syntax (one based indices and slices) </p> -<H2><a name="R_nn6"></a>36.6 C++ classes</H2> +<H2><a name="R_nn6"></a>37.6 C++ classes</H2> <p> @@ -167,7 +167,7 @@ keep track of the pointer object which removes the necessity for a lot of the proxy class baggage you see in other languages. </p> -<H2><a name="R_nn7"></a>36.7 Enumerations</H2> +<H2><a name="R_nn7"></a>37.7 Enumerations</H2> <p> diff --git a/Doc/Manual/Ruby.html b/Doc/Manual/Ruby.html index 9719239a9..e78447b92 100644 --- a/Doc/Manual/Ruby.html +++ b/Doc/Manual/Ruby.html @@ -7,7 +7,7 @@ <body bgcolor="#ffffff"> -<H1><a name="Ruby"></a>37 SWIG and Ruby</H1> +<H1><a name="Ruby"></a>38 SWIG and Ruby</H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -144,10 +144,10 @@ <p>This chapter describes SWIG's support of Ruby.</p> -<H2><a name="Ruby_nn2"></a>37.1 Preliminaries</H2> +<H2><a name="Ruby_nn2"></a>38.1 Preliminaries</H2> -<p> SWIG 1.3 is known to work with Ruby versions 1.6 and later. +<p> SWIG 3.0 is known to work with Ruby versions 1.8 and later. Given the choice, you should use the latest stable version of Ruby. You should also determine if your system supports shared libraries and dynamic loading. SWIG will work with or without dynamic loading, but @@ -159,7 +159,7 @@ read the "<a href="SWIG.html#SWIG">SWIG Basics</a>" chapter. It is also assumed that the reader has a basic understanding of Ruby. </p> -<H3><a name="Ruby_nn3"></a>37.1.1 Running SWIG</H3> +<H3><a name="Ruby_nn3"></a>38.1.1 Running SWIG</H3> <p> To build a Ruby module, run SWIG using the <tt>-ruby</tt> @@ -183,7 +183,7 @@ if compiling a C++ extension) that contains all of the code needed to build a Ruby extension module. To finish building the module, you need to compile this file and link it with the rest of your program. </p> -<H3><a name="Ruby_nn4"></a>37.1.2 Getting the right header files</H3> +<H3><a name="Ruby_nn4"></a>38.1.2 Getting the right header files</H3> <p> In order to compile the wrapper code, the compiler needs the <tt>ruby.h</tt> @@ -191,7 +191,7 @@ header file. This file is usually contained in a directory such as </p> <div class="code shell diagram"> <pre>/usr/lib/ruby/1.8/x86_64-linux-gnu/ruby.h -/usr/local/lib/ruby/1.6/i686-linux/ruby.h +/usr/include/ruby-2.1.0/ruby.h </pre> </div> @@ -201,12 +201,18 @@ installed, you can run Ruby to find out. For example: </p> <div class="code shell"> <pre>$ ruby -e 'puts $:.join("\n")' -/usr/local/lib/ruby/site_ruby/1.6 /usr/local/lib/ruby/site_ruby/1.6/i686-linux -/usr/local/lib/ruby/site_ruby /usr/local/lib/ruby/1.6 /usr/local/lib/ruby/1.6/i686-linux . +/usr/local/lib/site_ruby/2.1.0 +/usr/local/lib/x86_64-linux-gnu/site_ruby +/usr/local/lib/site_ruby +/usr/lib/ruby/vendor_ruby/2.1.0 +/usr/lib/x86_64-linux-gnu/ruby/vendor_ruby/2.1.0 +/usr/lib/ruby/vendor_ruby +/usr/lib/ruby/2.1.0 +/usr/lib/x86_64-linux-gnu/ruby/2.1.0 </pre> </div> -<H3><a name="Ruby_nn5"></a>37.1.3 Compiling a dynamic module</H3> +<H3><a name="Ruby_nn5"></a>38.1.3 Compiling a dynamic module</H3> <p> Ruby extension modules are typically compiled into shared @@ -260,7 +266,7 @@ operating system would look something like this: </p> <div class="code shell"> <pre>$ swig -ruby example.i $ gcc -O2 -fPIC -c example.c -$ gcc -O2 -fPIC -c example_wrap.c -I/usr/local/lib/ruby/1.6/i686-linux +$ gcc -O2 -fPIC -c example_wrap.c -I/usr/include/ruby-2.1.0 $ gcc -shared example.o example_wrap.o -o example.so </pre> </div> @@ -279,7 +285,7 @@ manual pages for your compiler and linker to determine the correct set of options. You might also check the <a href="http://www.dabeaz.com/cgi-bin/wiki.pl">SWIG Wiki</a> for additional information. </p> -<H3><a name="Ruby_nn6"></a>37.1.4 Using your module</H3> +<H3><a name="Ruby_nn6"></a>38.1.4 Using your module</H3> <p> Ruby <i>module</i> names must be capitalized, @@ -309,7 +315,7 @@ begins with: </p> <p> will result in an extension module using the feature name "example" and Ruby module name "Example". </p> -<H3><a name="Ruby_nn7"></a>37.1.5 Static linking</H3> +<H3><a name="Ruby_nn7"></a>38.1.5 Static linking</H3> <p> An alternative approach to dynamic linking is to rebuild the @@ -324,7 +330,7 @@ finding the Ruby source, adding an entry to the <tt>ext/Setup</tt> file, adding your directory to the list of extensions in the file, and finally rebuilding Ruby. </p> -<H3><a name="Ruby_nn8"></a>37.1.6 Compilation of C++ extensions</H3> +<H3><a name="Ruby_nn8"></a>38.1.6 Compilation of C++ extensions</H3> <p> On most machines, C++ extension modules should be linked @@ -334,7 +340,7 @@ using the C++ compiler. For example: </p> <pre> $ swig -c++ -ruby example.i $ g++ -fPIC -c example.cxx -$ g++ -fPIC -c example_wrap.cxx -I/usr/local/lib/ruby/1.6/i686-linux +$ g++ -fPIC -c example_wrap.cxx -I/usr/include/ruby-2.1.0 $ g++ -shared example.o example_wrap.o -o example.so </pre> </div> @@ -356,7 +362,7 @@ $libs = append_library($libs, "supc++") create_makefile('example')</pre> </div> -<H2><a name="Ruby_nn9"></a>37.2 Building Ruby Extensions under Windows 95/NT</H2> +<H2><a name="Ruby_nn9"></a>38.2 Building Ruby Extensions under Windows 95/NT</H2> <p> Building a SWIG extension to Ruby under Windows 95/NT is @@ -381,7 +387,7 @@ order to build extensions, you may need to download the source distribution to the Ruby package, as you will need the Ruby header files. </p> -<H3><a name="Ruby_nn10"></a>37.2.1 Running SWIG from Developer Studio</H3> +<H3><a name="Ruby_nn10"></a>38.2.1 Running SWIG from Developer Studio</H3> <p> If you are developing your application within Microsoft @@ -445,13 +451,13 @@ Foo = 3.0 </pre> </div> -<H2><a name="Ruby_nn11"></a>37.3 The Ruby-to-C/C++ Mapping</H2> +<H2><a name="Ruby_nn11"></a>38.3 The Ruby-to-C/C++ Mapping</H2> <p> This section describes the basics of how SWIG maps C or C++ declarations in your SWIG interface files to Ruby constructs. </p> -<H3><a name="Ruby_nn12"></a>37.3.1 Modules</H3> +<H3><a name="Ruby_nn12"></a>38.3.1 Modules</H3> <p> The SWIG <tt>%module</tt> directive specifies @@ -523,7 +529,7 @@ option to wrap everything into the global module, take care that the names of your constants, classes and methods don't conflict with any of Ruby's built-in names. </p> -<H3><a name="Ruby_nn13"></a>37.3.2 Functions</H3> +<H3><a name="Ruby_nn13"></a>38.3.2 Functions</H3> <p> Global functions are wrapped as Ruby module methods. For @@ -557,7 +563,7 @@ irb(main):002:0> <b>Example.fact(4)</b> 24</pre> </div> -<H3><a name="Ruby_nn14"></a>37.3.3 Variable Linking</H3> +<H3><a name="Ruby_nn14"></a>38.3.3 Variable Linking</H3> <p> C/C++ global variables are wrapped as a pair of singleton @@ -619,7 +625,7 @@ directive. For example: </p> effect until it is explicitly disabled using <tt>%mutable</tt>. </p> -<H3><a name="Ruby_nn15"></a>37.3.4 Constants</H3> +<H3><a name="Ruby_nn15"></a>38.3.4 Constants</H3> <p> C/C++ constants are wrapped as module constants initialized @@ -647,7 +653,7 @@ irb(main):002:0> <b>Example::PI</b> 3.14159</pre> </div> -<H3><a name="Ruby_nn16"></a>37.3.5 Pointers</H3> +<H3><a name="Ruby_nn16"></a>38.3.5 Pointers</H3> <p> "Opaque" pointers to arbitrary C/C++ types (i.e. types that @@ -671,7 +677,7 @@ returns an instance of an internally generated Ruby class: </p> <p> A <tt>NULL</tt> pointer is always represented by the Ruby <tt>nil</tt> object. </p> -<H3><a name="Ruby_nn17"></a>37.3.6 Structures</H3> +<H3><a name="Ruby_nn17"></a>38.3.6 Structures</H3> <p> C/C++ structs are wrapped as Ruby classes, with accessor @@ -685,7 +691,7 @@ For example, this struct declaration: </p> </div> <p> gets wrapped as a <tt>Vector</tt> class, with -Ruby instance methods <tt>x</tt>, <tt> x=</tt>, +Ruby instance methods <tt>x</tt>, <tt>x=</tt>, <tt>y</tt> and <tt>y=</tt>. These methods can be used to access structure data from Ruby as follows: </p> @@ -776,7 +782,7 @@ void Bar_f_set(Bar *b, Foo *val) { }</pre> </div> -<H3><a name="Ruby_nn18"></a>37.3.7 C++ classes</H3> +<H3><a name="Ruby_nn18"></a>38.3.7 C++ classes</H3> <p> Like structs, C++ classes are wrapped by creating a new Ruby @@ -831,7 +837,7 @@ Ale 3</pre> </div> -<H3><a name="Ruby_nn19"></a>37.3.8 C++ Inheritance</H3> +<H3><a name="Ruby_nn19"></a>38.3.8 C++ Inheritance</H3> <p> The SWIG type-checker is fully aware of C++ inheritance. @@ -984,7 +990,7 @@ inherit from both <tt>Base1</tt> and <tt>Base2</tt> (i.e. they exhibit <a href="http://c2.com/cgi/wiki?DuckTyping">"Duck Typing"</a>). </p> -<H3><a name="Ruby_nn20"></a>37.3.9 C++ Overloaded Functions</H3> +<H3><a name="Ruby_nn20"></a>38.3.9 C++ Overloaded Functions</H3> <p> C++ overloaded functions, methods, and constructors are @@ -1074,7 +1080,7 @@ arises--in this case, the first declaration takes precedence. </p> <p>Please refer to the <a href="SWIGPlus.html#SWIGPlus">"SWIG and C++"</a> chapter for more information about overloading. </p> -<H3><a name="Ruby_nn21"></a>37.3.10 C++ Operators</H3> +<H3><a name="Ruby_nn21"></a>38.3.10 C++ Operators</H3> <p> For the most part, overloaded operators are handled @@ -1116,7 +1122,7 @@ c = Example.add_complex(a, b)</pre> is discussed in the <a href="#Ruby_operator_overloading">section on operator overloading</a>. </p> -<H3><a name="Ruby_nn22"></a>37.3.11 C++ namespaces</H3> +<H3><a name="Ruby_nn22"></a>38.3.11 C++ namespaces</H3> <p> SWIG is aware of C++ namespaces, but namespace names do not @@ -1173,7 +1179,7 @@ and create extension modules for each namespace separately. If your program utilizes thousands of small deeply nested namespaces each with identical symbol names, well, then you get what you deserve. </p> -<H3><a name="Ruby_nn23"></a>37.3.12 C++ templates</H3> +<H3><a name="Ruby_nn23"></a>38.3.12 C++ templates</H3> <p> C++ templates don't present a huge problem for SWIG. However, @@ -1215,7 +1221,7 @@ irb(main):004:0> <b>p.second</b> 4</pre> </div> -<H3><a name="Ruby_nn23_1"></a>37.3.13 C++ Standard Template Library (STL)</H3> +<H3><a name="Ruby_nn23_1"></a>38.3.13 C++ Standard Template Library (STL)</H3> <p> On a related note, the standard SWIG library contains a @@ -1308,12 +1314,12 @@ puts v shown in these examples. More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a> chapter.</p> -<H3><a name="Ruby_C_STL_Functors"></a>37.3.14 C++ STL Functors</H3> +<H3><a name="Ruby_C_STL_Functors"></a>38.3.14 C++ STL Functors</H3> <p>Some containers in the STL allow you to modify their default behavior by using so called functors or function objects. -Functors are often just a very simple struct with<tt> operator()</tt> +Functors are often just a very simple struct with <tt>operator()</tt> redefined or an actual C/C++ function. This allows you, for example, to always keep the sort order of a STL container to your liking.</p> @@ -1327,7 +1333,7 @@ this includes <tt>std::set</tt>, <tt>std::multiset</tt> and <tt>std::multimap</tt>.</p> -<p>The functors in swig are called<tt> swig::UnaryFunction</tt> +<p>The functors in swig are called <tt>swig::UnaryFunction</tt> and <tt>swig::BinaryFunction</tt>. For C++ predicates (ie. functors that must return bool as a result) <tt>swig::UnaryPredicate</tt> @@ -1369,7 +1375,7 @@ b </pre> </div> -<H3><a name="Ruby_C_Iterators"></a>37.3.15 C++ STL Iterators</H3> +<H3><a name="Ruby_C_Iterators"></a>38.3.15 C++ STL Iterators</H3> <p>The STL is well known for the use of iterators. There @@ -1380,8 +1386,8 @@ values they point at, while the non-const iterators can both read and modify the values.</p> <p>The Ruby STL wrappings support both type of iterators by using -a proxy class in-between. This proxy class is <tt>swig::Iterator or -swig::ConstIterator. </tt> Derived from them are template +a proxy class in-between. This proxy class is <tt>swig::Iterator</tt> or +<tt>swig::ConstIterator</tt>. Derived from them are template classes that need to be initialized with the actual iterator for the container you are wrapping and often times with the beginning and ending points of the iteration range.</p> @@ -1450,9 +1456,9 @@ i </pre> </div> -<p>If you'd rather have STL classes without any iterators, you should define<tt> -DSWIG_NO_EXPORT_ITERATOR_METHODS </tt>when running swig.</p> +<p>If you'd rather have STL classes without any iterators, you should define <tt>-DSWIG_NO_EXPORT_ITERATOR_METHODS</tt> when running swig.</p> -<H3><a name="Ruby_nn24"></a>37.3.16 C++ Smart Pointers</H3> +<H3><a name="Ruby_nn24"></a>38.3.16 C++ Smart Pointers</H3> <p> In certain C++ programs, it is common to use classes that @@ -1517,7 +1523,7 @@ method. For example: </p> <pre>irb(main):004:0> <b>f = p.__deref__()</b> # Returns underlying Foo *</pre> </div> -<H3><a name="Ruby_nn25"></a>37.3.17 Cross-Language Polymorphism</H3> +<H3><a name="Ruby_nn25"></a>38.3.17 Cross-Language Polymorphism</H3> <p> SWIG's Ruby module supports cross-language polymorphism @@ -1526,7 +1532,7 @@ module. Rather than duplicate the information presented in the <a href="Python.h section just notes the differences that you need to be aware of when using this feature with Ruby. </p> -<H4><a name="Ruby_nn26"></a>37.3.17.1 Exception Unrolling</H4> +<H4><a name="Ruby_nn26"></a>38.3.17.1 Exception Unrolling</H4> <p> Whenever a C++ director class routes one of its virtual @@ -1549,7 +1555,7 @@ method is "wrapped" using the <tt>rb_rescue2()</tt> function from Ruby's C API. If any Ruby exception is raised, it will be caught here and a C++ exception is raised in its place. </p> -<H2><a name="Ruby_nn27"></a>37.4 Naming</H2> +<H2><a name="Ruby_nn27"></a>38.4 Naming</H2> <p>Ruby has several common naming conventions. Constants are @@ -1587,7 +1593,7 @@ generated by SWIG, it is turned off by default in SWIG 1.3.28. However, it is planned to become the default option in future releases.</p> -<H3><a name="Ruby_nn28"></a>37.4.1 Defining Aliases</H3> +<H3><a name="Ruby_nn28"></a>38.4.1 Defining Aliases</H3> <p> It's a fairly common practice in the Ruby built-ins and @@ -1657,7 +1663,7 @@ matching rules used for other kinds of features apply (see the chapter on <a href="Customization.html#Customization">"Customization Features"</a>) for more details).</p> -<H3><a name="Ruby_nn29"></a>37.4.2 Predicate Methods</H3> +<H3><a name="Ruby_nn29"></a>38.4.2 Predicate Methods</H3> <p> Ruby methods that return a boolean value and end in a @@ -1706,7 +1712,7 @@ using SWIG's "features" mechanism and so the same name matching rules used for other kinds of features apply (see the chapter on <a href="Customization.html#Customization">"Customization Features"</a>) for more details). </p> -<H3><a name="Ruby_nn30"></a>37.4.3 Bang Methods</H3> +<H3><a name="Ruby_nn30"></a>38.4.3 Bang Methods</H3> <p> Ruby methods that modify an object in-place and end in an @@ -1738,7 +1744,7 @@ using SWIG's "features" mechanism and so the same name matching rules used for other kinds of features apply (see the chapter on <a href="Customization.html#Customization">"Customization Features"</a>) for more details). </p> -<H3><a name="Ruby_nn31"></a>37.4.4 Getters and Setters</H3> +<H3><a name="Ruby_nn31"></a>38.4.4 Getters and Setters</H3> <p> Often times a C++ library will expose properties through @@ -1773,7 +1779,7 @@ irb(main):003:0> <b>puts foo.value</b></pre> %rename("value=") Foo::setValue(int value);</pre> </div> -<H2><a name="Ruby_nn32"></a>37.5 Input and output parameters</H2> +<H2><a name="Ruby_nn32"></a>38.5 Input and output parameters</H2> <p> A common problem in some C programs is handling parameters @@ -1912,10 +1918,10 @@ void get_dimensions(Matrix *m, int *rows, int*columns);</pre> <pre>r, c = Example.get_dimensions(m)</pre> </div> -<H2><a name="Ruby_nn33"></a>37.6 Exception handling </H2> +<H2><a name="Ruby_nn33"></a>38.6 Exception handling </H2> -<H3><a name="Ruby_nn34"></a>37.6.1 Using the %exception directive </H3> +<H3><a name="Ruby_nn34"></a>38.6.1 Using the %exception directive </H3> <p>The SWIG <tt>%exception</tt> directive can be @@ -2024,7 +2030,7 @@ methods and functions named <tt>getitem</tt> and <tt>setitem</tt>. limited to C++ exception handling. See the chapter on <a href="Customization.html#Customization">Customization Features</a> for more examples.</p> -<H3><a name="Ruby_nn34_2"></a>37.6.2 Handling Ruby Blocks </H3> +<H3><a name="Ruby_nn34_2"></a>38.6.2 Handling Ruby Blocks </H3> <p>One of the highlights of Ruby and most of its standard library @@ -2091,7 +2097,7 @@ a special in typemap, like:</p> <p>For more information on typemaps, see <a href="#Ruby_nn37">Typemaps</a>.</p> -<H3><a name="Ruby_nn35"></a>37.6.3 Raising exceptions </H3> +<H3><a name="Ruby_nn35"></a>38.6.3 Raising exceptions </H3> <p>There are three ways to raise exceptions from C++ code to @@ -2248,7 +2254,7 @@ function. The first argument passed to <tt>rb_raise()</tt> is the exception type. You can raise a custom exception type or one of the built-in Ruby exception types.</p> -<H3><a name="Ruby_nn36"></a>37.6.4 Exception classes </H3> +<H3><a name="Ruby_nn36"></a>38.6.4 Exception classes </H3> <p>Starting with SWIG 1.3.28, the Ruby module supports the <tt>%exceptionclass</tt> @@ -2285,7 +2291,7 @@ end </pre> <p>For another example look at swig/Examples/ruby/exception_class. </p> -<H2><a name="Ruby_nn37"></a>37.7 Typemaps</H2> +<H2><a name="Ruby_nn37"></a>38.7 Typemaps</H2> <p> This section describes how you can modify SWIG's default @@ -2300,7 +2306,7 @@ a required part of using SWIG---the default wrapping behavior is enough in most cases. Typemaps are only used if you want to change some aspect of the primitive C-Ruby interface.</p> -<H3><a name="Ruby_nn38"></a>37.7.1 What is a typemap?</H3> +<H3><a name="Ruby_nn38"></a>38.7.1 What is a typemap?</H3> <p> A typemap is nothing more than a code generation rule that is @@ -2457,7 +2463,7 @@ to be used as follows (notice how the length parameter is omitted): </p> 2</pre> </div> -<H3><a name="Ruby_Typemap_scope"></a>37.7.2 Typemap scope</H3> +<H3><a name="Ruby_Typemap_scope"></a>38.7.2 Typemap scope</H3> <p> Once defined, a typemap remains in effect for all of the @@ -2503,7 +2509,7 @@ where the class itself is defined. For example:</p> };</pre> </div> -<H3><a name="Ruby_Copying_a_typemap"></a>37.7.3 Copying a typemap</H3> +<H3><a name="Ruby_Copying_a_typemap"></a>38.7.3 Copying a typemap</H3> <p> A typemap is copied by using assignment. For example:</p> @@ -2545,7 +2551,7 @@ rules as for <tt> %apply (char *buf, int len) { (char *buffer, int size) }; // Multiple arguments</pre> </div> -<H3><a name="Ruby_Deleting_a_typemap"></a>37.7.4 Deleting a typemap</H3> +<H3><a name="Ruby_Deleting_a_typemap"></a>38.7.4 Deleting a typemap</H3> <p> A typemap can be deleted by simply defining no code. For @@ -2570,7 +2576,7 @@ defined by typemaps, clearing a fundamental type like <tt>int</tt> will make that type unusable unless you also define a new set of typemaps immediately after the clear operation.</p> -<H3><a name="Ruby_Placement_of_typemaps"></a>37.7.5 Placement of typemaps</H3> +<H3><a name="Ruby_Placement_of_typemaps"></a>38.7.5 Placement of typemaps</H3> <p> Typemap declarations can be declared in the global scope, @@ -2641,13 +2647,13 @@ In this example, this is done using the class declaration <tt>class string</tt> .</p> -<H3><a name="Ruby_nn39"></a>37.7.6 Ruby typemaps</H3> +<H3><a name="Ruby_nn39"></a>38.7.6 Ruby typemaps</H3> <p>The following list details all of the typemap methods that can be used by the Ruby module: </p> -<H4><a name="Ruby_in_typemap"></a>37.7.6.1 "in" typemap</H4> +<H4><a name="Ruby_in_typemap"></a>38.7.6.1 "in" typemap</H4> <p>Converts Ruby objects to input @@ -2714,7 +2720,7 @@ arguments to be specified. For example:</p> <p> At this time, only zero or one arguments may be converted.</p> -<H4><a name="Ruby_typecheck_typemap"></a>37.7.6.2 "typecheck" typemap</H4> +<H4><a name="Ruby_typecheck_typemap"></a>38.7.6.2 "typecheck" typemap</H4> <p> The "typecheck" typemap is used to support overloaded @@ -2736,7 +2742,7 @@ program uses overloaded methods, you should also define a collection of "typecheck" typemaps. More details about this follow in a later section on "Typemaps and Overloading."</p> -<H4><a name="Ruby_out_typemap"></a>37.7.6.3 "out" typemap</H4> +<H4><a name="Ruby_out_typemap"></a>38.7.6.3 "out" typemap</H4> <p>Converts return value of a C function @@ -2787,7 +2793,7 @@ version of the C datatype matched by the typemap.</td> </table> </div> -<H4><a name="Ruby_arginit_typemap"></a>37.7.6.4 "arginit" typemap</H4> +<H4><a name="Ruby_arginit_typemap"></a>38.7.6.4 "arginit" typemap</H4> <p> The "arginit" typemap is used to set the initial value of a @@ -2802,7 +2808,7 @@ applications. For example:</p> }</pre> </div> -<H4><a name="Ruby_default_typemap"></a>37.7.6.5 "default" typemap</H4> +<H4><a name="Ruby_default_typemap"></a>38.7.6.5 "default" typemap</H4> <p> The "default" typemap is used to turn an argument into a @@ -2823,11 +2829,11 @@ not support optional arguments, such as Java and C#, effectively ignore the value specified by this typemap as all arguments must be given.</p> <p> Once a default typemap has been applied to an argument, all -arguments that follow must have default values. See the <a href="http://www.swig.org/Doc1.3/SWIGDocumentation.html#SWIG_default_args"> +arguments that follow must have default values. See the <a href="SWIG.html#SWIG_default_args"> Default/optional arguments</a> section for further information on default argument wrapping.</p> -<H4><a name="Ruby_check_typemap"></a>37.7.6.6 "check" typemap</H4> +<H4><a name="Ruby_check_typemap"></a>38.7.6.6 "check" typemap</H4> <p> The "check" typemap is used to supply value checking code @@ -2842,7 +2848,7 @@ arguments have been converted. For example:</p> }</pre> </div> -<H4><a name="Ruby_argout_typemap_"></a>37.7.6.7 "argout" typemap</H4> +<H4><a name="Ruby_argout_typemap_"></a>38.7.6.7 "argout" typemap</H4> <p> The "argout" typemap is used to return values from arguments. @@ -2896,7 +2902,7 @@ some function like SWIG_Ruby_AppendOutput.</p> <p> See the <tt>typemaps.i</tt> library for examples.</p> -<H4><a name="Ruby_freearg_typemap_"></a>37.7.6.8 "freearg" typemap</H4> +<H4><a name="Ruby_freearg_typemap_"></a>38.7.6.8 "freearg" typemap</H4> <p> The "freearg" typemap is used to cleanup argument data. It is @@ -2923,7 +2929,7 @@ This code is also placed into a special variable <tt>$cleanup</tt> that may be used in other typemaps whenever a wrapper function needs to abort prematurely.</p> -<H4><a name="Ruby_newfree_typemap"></a>37.7.6.9 "newfree" typemap</H4> +<H4><a name="Ruby_newfree_typemap"></a>38.7.6.9 "newfree" typemap</H4> <p> The "newfree" typemap is used in conjunction with the <tt>%newobject</tt> @@ -2947,7 +2953,7 @@ string *foo();</pre> <p> See <a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for further details.</p> -<H4><a name="Ruby_memberin_typemap"></a>37.7.6.10 "memberin" typemap</H4> +<H4><a name="Ruby_memberin_typemap"></a>38.7.6.10 "memberin" typemap</H4> <p> The "memberin" typemap is used to copy data from<em> an @@ -2965,21 +2971,21 @@ example:</p> already provides a default implementation for arrays, strings, and other objects.</p> -<H4><a name="Ruby_varin_typemap"></a>37.7.6.11 "varin" typemap</H4> +<H4><a name="Ruby_varin_typemap"></a>38.7.6.11 "varin" typemap</H4> <p> The "varin" typemap is used to convert objects in the target language to C for the purposes of assigning to a C/C++ global variable. This is implementation specific.</p> -<H4><a name="Ruby_varout_typemap_"></a>37.7.6.12 "varout" typemap</H4> +<H4><a name="Ruby_varout_typemap_"></a>38.7.6.12 "varout" typemap</H4> <p> The "varout" typemap is used to convert a C/C++ object to an object in the target language when reading a C/C++ global variable. This is implementation specific.</p> -<H4><a name="Ruby_throws_typemap"></a>37.7.6.13 "throws" typemap</H4> +<H4><a name="Ruby_throws_typemap"></a>38.7.6.13 "throws" typemap</H4> <p> The "throws" typemap is only used when SWIG parses a C++ @@ -3017,10 +3023,10 @@ catch(char const *_e) { <p> Note that if your methods do not have an exception specification yet they do throw exceptions, SWIG cannot know how to -deal with them. For a neat way to handle these, see the <a href="http://www.swig.org/Doc1.3/SWIGDocumentation.html#exception">Exception +deal with them. For a neat way to handle these, see the <a href="Customization.html#Customization_exception">Exception handling with %exception</a> section.</p> -<H4><a name="Ruby_directorin_typemap"></a>37.7.6.14 directorin typemap</H4> +<H4><a name="Ruby_directorin_typemap"></a>38.7.6.14 directorin typemap</H4> <p>Converts C++ objects in director @@ -3079,7 +3085,7 @@ referring to the class itself.</td> </table> </div> -<H4><a name="Ruby_directorout_typemap"></a>37.7.6.15 directorout typemap</H4> +<H4><a name="Ruby_directorout_typemap"></a>38.7.6.15 directorout typemap</H4> <p>Converts Ruby objects in director @@ -3152,7 +3158,7 @@ exception. </p> -<H4><a name="Ruby_directorargout_typemap"></a>37.7.6.16 directorargout typemap</H4> +<H4><a name="Ruby_directorargout_typemap"></a>38.7.6.16 directorargout typemap</H4> <p>Output argument processing in director @@ -3210,19 +3216,19 @@ referring to the instance of the class itself</td> </table> </div> -<H4><a name="Ruby_ret_typemap"></a>37.7.6.17 ret typemap</H4> +<H4><a name="Ruby_ret_typemap"></a>38.7.6.17 ret typemap</H4> <p>Cleanup of function return values </p> -<H4><a name="Ruby_globalin_typemap"></a>37.7.6.18 globalin typemap</H4> +<H4><a name="Ruby_globalin_typemap"></a>38.7.6.18 globalin typemap</H4> <p>Setting of C global variables </p> -<H3><a name="Ruby_nn40"></a>37.7.7 Typemap variables</H3> +<H3><a name="Ruby_nn40"></a>38.7.7 Typemap variables</H3> <p> @@ -3272,7 +3278,7 @@ so that their values can be properly assigned. </div> <div class="indent">The Ruby name of the wrapper function being created. </div> -<H3><a name="Ruby_nn41"></a>37.7.8 Useful Functions</H3> +<H3><a name="Ruby_nn41"></a>38.7.8 Useful Functions</H3> <p> When you write a typemap, you usually have to work directly @@ -3287,7 +3293,7 @@ stick to the swig functions instead of the native Ruby functions. That should help you avoid having to rewrite a lot of typemaps across multiple languages.</p> -<H4><a name="Ruby_nn42"></a>37.7.8.1 C Datatypes to Ruby Objects</H4> +<H4><a name="Ruby_nn42"></a>38.7.8.1 C Datatypes to Ruby Objects</H4> <div class="diagram"> @@ -3329,7 +3335,7 @@ SWIG_From_float(float)</td> </table> </div> -<H4><a name="Ruby_nn43"></a>37.7.8.2 Ruby Objects to C Datatypes</H4> +<H4><a name="Ruby_nn43"></a>38.7.8.2 Ruby Objects to C Datatypes</H4> <p>Here, while the Ruby versions return the value directly, the SWIG @@ -3397,7 +3403,7 @@ versions do not, but return a status value to indicate success (<tt>SWIG_OK</tt> </table> </div> -<H4><a name="Ruby_nn44"></a>37.7.8.3 Macros for VALUE</H4> +<H4><a name="Ruby_nn44"></a>38.7.8.3 Macros for VALUE</H4> <p> <tt>RSTRING_LEN(str)</tt> </p> @@ -3420,7 +3426,7 @@ versions do not, but return a status value to indicate success (<tt>SWIG_OK</tt> <div class="indent">pointer to array storage</div> -<H4><a name="Ruby_nn45"></a>37.7.8.4 Exceptions</H4> +<H4><a name="Ruby_nn45"></a>38.7.8.4 Exceptions</H4> <p> <tt>void rb_raise(VALUE exception, const char *fmt, @@ -3499,7 +3505,7 @@ message to standard error if Ruby was invoked with the <tt>-w</tt> flag. The given format string <i>fmt</i> and remaining arguments are interpreted as with <tt>printf()</tt>. </div> -<H4><a name="Ruby_nn46"></a>37.7.8.5 Iterators</H4> +<H4><a name="Ruby_nn46"></a>38.7.8.5 Iterators</H4> <p> <tt>void rb_iter_break()</tt> </p> @@ -3545,14 +3551,14 @@ VALUE), VALUE value)</tt></p> <div class="indent"> Equivalent to Ruby's <tt>throw</tt>. </div> -<H3><a name="Ruby_nn47"></a>37.7.9 Typemap Examples</H3> +<H3><a name="Ruby_nn47"></a>38.7.9 Typemap Examples</H3> <p> This section includes a few examples of typemaps. For more examples, you might look at the examples in the <tt>Example/ruby</tt> directory. </p> -<H3><a name="Ruby_nn48"></a>37.7.10 Converting a Ruby array to a char **</H3> +<H3><a name="Ruby_nn48"></a>38.7.10 Converting a Ruby array to a char **</H3> <p> A common problem in many C programs is the processing of @@ -3617,7 +3623,7 @@ array. Since dynamic memory allocation is used to allocate memory for the array, the "freearg" typemap is used to later release this memory after the execution of the C function. </p> -<H3><a name="Ruby_nn49"></a>37.7.11 Collecting arguments in a hash</H3> +<H3><a name="Ruby_nn49"></a>38.7.11 Collecting arguments in a hash</H3> <p> Ruby's solution to the "keyword arguments" capability of some @@ -3831,7 +3837,7 @@ memory leak. Fortunately, this typemap is a lot easier to write: </p> program that uses the extension, can be found in the <tt>Examples/ruby/hashargs</tt> directory of the SWIG distribution. </p> -<H3><a name="Ruby_nn50"></a>37.7.12 Pointer handling</H3> +<H3><a name="Ruby_nn50"></a>38.7.12 Pointer handling</H3> <p> Occasionally, it might be necessary to convert pointer values @@ -3890,7 +3896,7 @@ For example: </p> }</pre> </div> -<H4><a name="Ruby_nn51"></a>37.7.12.1 Ruby Datatype Wrapping</H4> +<H4><a name="Ruby_nn51"></a>38.7.12.1 Ruby Datatype Wrapping</H4> <p> <tt>VALUE Data_Wrap_Struct(VALUE class, void @@ -3917,7 +3923,7 @@ as above. </div> type <i>c-type</i> from the data object <i>obj</i> and assigns that pointer to <i>ptr</i>. </div> -<H3><a name="Ruby_nn52"></a>37.7.13 Example: STL Vector to Ruby Array</H3> +<H3><a name="Ruby_nn52"></a>38.7.13 Example: STL Vector to Ruby Array</H3> <p>Another use for macros and type maps is to create a Ruby array @@ -4009,7 +4015,7 @@ STL with ruby, you are advised to use the standard swig STL library, which does much more than this. Refer to the section called the<a href="#Ruby_nn23_1"> C++ Standard Template Library</a>. -<H2><a name="Ruby_nn65"></a>37.8 Docstring Features</H2> +<H2><a name="Ruby_nn65"></a>38.8 Docstring Features</H2> <p> @@ -4043,7 +4049,7 @@ generate ri documentation from a c wrap file, you could do:</p> $ rdoc -r file_wrap.c </pre></div> -<H3><a name="Ruby_nn66"></a>37.8.1 Module docstring</H3> +<H3><a name="Ruby_nn66"></a>38.8.1 Module docstring</H3> <p> @@ -4073,7 +4079,7 @@ layout of controls on a panel, etc. to be loaded from an XML file." %module(docstring=DOCSTRING) xrc</pre> </div> -<H3><a name="Ruby_nn67"></a>37.8.2 %feature("autodoc")</H3> +<H3><a name="Ruby_nn67"></a>38.8.2 %feature("autodoc")</H3> <p>Since SWIG does know everything about the function it wraps, @@ -4094,7 +4100,7 @@ several options for autodoc controlled by the value given to the feature, described below. </p> -<H4><a name="Ruby_nn68"></a>37.8.2.1 %feature("autodoc", "0")</H4> +<H4><a name="Ruby_nn68"></a>38.8.2.1 %feature("autodoc", "0")</H4> <p> @@ -4118,7 +4124,7 @@ Then Ruby code like this will be generated: ...</pre> </div> -<H4><a name="Ruby_autodoc1"></a>37.8.2.2 %feature("autodoc", "1")</H4> +<H4><a name="Ruby_autodoc1"></a>38.8.2.2 %feature("autodoc", "1")</H4> <p> @@ -4138,7 +4144,7 @@ this: ...</pre> </div> -<H4><a name="Ruby_autodoc2"></a>37.8.2.3 %feature("autodoc", "2")</H4> +<H4><a name="Ruby_autodoc2"></a>38.8.2.3 %feature("autodoc", "2")</H4> <p> @@ -4150,7 +4156,7 @@ parameter types with the "2" option will result in Ruby code like this: </p> -<H4><a name="Ruby_feature_autodoc3"></a>37.8.2.4 %feature("autodoc", "3")</H4> +<H4><a name="Ruby_feature_autodoc3"></a>38.8.2.4 %feature("autodoc", "3")</H4> <p> @@ -4171,7 +4177,7 @@ Parameters: bar - Bar</pre> </div> -<H4><a name="Ruby_nn70"></a>37.8.2.5 %feature("autodoc", "docstring")</H4> +<H4><a name="Ruby_nn70"></a>38.8.2.5 %feature("autodoc", "docstring")</H4> <p> @@ -4187,7 +4193,7 @@ generated string. For example: void GetPosition(int* OUTPUT, int* OUTPUT);</pre> </div> -<H3><a name="Ruby_nn71"></a>37.8.3 %feature("docstring")</H3> +<H3><a name="Ruby_nn71"></a>38.8.3 %feature("docstring")</H3> <p> @@ -4198,10 +4204,10 @@ docstring associated with classes, function or methods are output. If an item already has an autodoc string then it is combined with the docstring and they are output together. </p> -<H2><a name="Ruby_nn53"></a>37.9 Advanced Topics</H2> +<H2><a name="Ruby_nn53"></a>38.9 Advanced Topics</H2> -<H3><a name="Ruby_operator_overloading"></a>37.9.1 Operator overloading</H3> +<H3><a name="Ruby_operator_overloading"></a>38.9.1 Operator overloading</H3> <p> SWIG allows operator overloading with, by using the <tt>%extend</tt> @@ -4382,7 +4388,7 @@ separate method for handling <i>inequality</i> since Ruby parses the expression <i>a != b</i> as <i>!(a == b)</i>. </p> -<H3><a name="Ruby_nn55"></a>37.9.2 Creating Multi-Module Packages</H3> +<H3><a name="Ruby_nn55"></a>38.9.2 Creating Multi-Module Packages</H3> <p> The chapter on <a href="Modules.html#Modules">Working @@ -4466,7 +4472,7 @@ and then type <tt>make</tt> to build the shared library: </p> <pre>$ <b>ruby extconf.rb</b> creating Makefile $ <b>make</b> -g++ -fPIC -g -O2 -I. -I/usr/local/lib/ruby/1.7/i686-linux \ +g++ -fPIC -g -O2 -I. -I/usr/include/ruby-2.1.0 \ -I. -c shape_wrap.cxx gcc -shared -L/usr/local/lib -o shape.so shape_wrap.o -L. \ -lruby -lruby -lc</pre> @@ -4508,7 +4514,7 @@ irb(main):005:0> <b>c.getX()</b> 5.0</pre> </div> -<H3><a name="Ruby_nn56"></a>37.9.3 Specifying Mixin Modules</H3> +<H3><a name="Ruby_nn56"></a>38.9.3 Specifying Mixin Modules</H3> <p> The Ruby language doesn't support multiple inheritance, but @@ -4575,7 +4581,7 @@ matching rules used for other kinds of features apply (see the chapter on <a href="Customization.html#Customization">"Customization Features"</a>) for more details). </p> -<H2><a name="Ruby_nn57"></a>37.10 Memory Management</H2> +<H2><a name="Ruby_nn57"></a>38.10 Memory Management</H2> <p>One of the most common issues in generating SWIG bindings for @@ -4598,7 +4604,7 @@ to C++ (or vice versa) depending on what function or methods are invoked. Clearly, developing a SWIG wrapper requires a thorough understanding of how the underlying library manages memory.</p> -<H3><a name="Ruby_nn58"></a>37.10.1 Mark and Sweep Garbage Collector </H3> +<H3><a name="Ruby_nn58"></a>38.10.1 Mark and Sweep Garbage Collector </H3> <p>Ruby uses a mark and sweep garbage collector. When the garbage @@ -4630,7 +4636,7 @@ any memory has been allocated in creating the underlying C struct or C++ struct, then a "free" function must be defined that deallocates this memory. </p> -<H3><a name="Ruby_nn59"></a>37.10.2 Object Ownership</H3> +<H3><a name="Ruby_nn59"></a>38.10.2 Object Ownership</H3> <p>As described above, memory management depends on clearly @@ -4775,7 +4781,7 @@ public: <p> This code can be seen in swig/examples/ruby/tracking.</p> -<H3><a name="Ruby_nn60"></a>37.10.3 Object Tracking</H3> +<H3><a name="Ruby_nn60"></a>38.10.3 Object Tracking</H3> <p>The remaining parts of this section will use the class library @@ -4997,10 +5003,10 @@ object from its underlying C++ object.</p> <p>In general, you will only need to use the <tt>SWIG_RubyInstanceFor</tt>, which is required for implementing mark functions as shown below. However, if you implement your own free functions (see below) you may -also have to call the<tt> SWIG_RubyRemoveTracking</tt> and <tt>RubyUnlinkObjects</tt> +also have to call the <tt>SWIG_RubyRemoveTracking</tt> and <tt>RubyUnlinkObjects</tt> methods.</p> -<H3><a name="Ruby_nn61"></a>37.10.4 Mark Functions</H3> +<H3><a name="Ruby_nn61"></a>38.10.4 Mark Functions</H3> <p>With a bit more testing, we see that our class library still @@ -5129,7 +5135,7 @@ irb(main):016:0></pre> <p>This code can be seen in swig/examples/ruby/mark_function.</p> -<H3><a name="Ruby_nn62"></a>37.10.5 Free Functions</H3> +<H3><a name="Ruby_nn62"></a>38.10.5 Free Functions</H3> <p>By default, SWIG creates a "free" function that is called when @@ -5296,7 +5302,7 @@ been freed, and thus raises a runtime exception.</p> <p>This code can be seen in swig/examples/ruby/free_function.</p> -<H3><a name="Ruby_nn63"></a>37.10.6 Embedded Ruby and the C++ Stack</H3> +<H3><a name="Ruby_nn63"></a>38.10.6 Embedded Ruby and the C++ Stack</H3> <p>As has been said, the Ruby GC runs and marks objects before @@ -5351,7 +5357,7 @@ used for callbacks, for example. </p> <p>To solve the problem, SWIG can now generate code with director functions containing the optional macros SWIG_INIT_STACK and SWIG_RELEASE_STACK. These macros will try to force Ruby to -reinitiliaze the beginning of the stack the first time a +reinitialize the beginning of the stack the first time a director function is called. This will lead Ruby to measure and not collect any VALUE objects defined from that point on. </p> diff --git a/Doc/Manual/SWIG.html b/Doc/Manual/SWIG.html index bd929f7d4..4c33aeab8 100644 --- a/Doc/Manual/SWIG.html +++ b/Doc/Manual/SWIG.html @@ -138,6 +138,7 @@ can be obtained by typing <tt>swig -help</tt> or <tt>swig -xml Generate XML wrappers -c++ Enable C++ parsing +-cppext <em>ext</em> Change file extension of C++ generated files to <em>ext</em> (default is cxx, except for PHP which uses cpp) -D<em>symbol</em> Define a preprocessor symbol -Fstandard Display error/warning messages in commonly used format -Fmicrosoft Display error/warning messages in Microsoft format @@ -146,7 +147,7 @@ can be obtained by typing <tt>swig -help</tt> or <tt>swig -l<em>file</em> Include a SWIG library file. -module <em>name</em> Set the name of the SWIG module -o <em>outfile</em> Name of output file --outcurrentdir Set default output dir to current dir instead of input file's path +-outcurrentdir Set default output dir to current dir instead of input file's path -outdir <em>dir</em> Set language specific files output directory -pcreversion Display PCRE version information -swiglib Show location of SWIG library @@ -1046,7 +1047,7 @@ def filecopy(source,target): </pre></div> <p> -In this case <tt>f1</tt>,<tt> f2</tt>, and <tt>buffer</tt> are all +In this case <tt>f1</tt>, <tt>f2</tt>, and <tt>buffer</tt> are all opaque objects containing C pointers. It doesn't matter what value they contain--our program works just fine without this knowledge.</p> @@ -1711,7 +1712,7 @@ wrapping a header file like this: </pre></div> <p> -<tt>%rename </tt>applies a renaming operation to all future +<tt>%rename</tt> applies a renaming operation to all future occurrences of a name. The renaming applies to functions, variables, class and structure names, member functions, and member data. For example, if you had two-dozen C++ classes, all with a member function @@ -3316,7 +3317,7 @@ Most importantly, define a type before it is used! A C compiler will tell you if the full type information is not available if it is needed, whereas SWIG will usually not warn or error out as it is designed to work without full type information. However, if type information is not specified -correctly, the wrappers can be sub-optimal and even result in uncompileable C/C++ code. +correctly, the wrappers can be sub-optimal and even result in uncompilable C/C++ code. <li>If your program has a main() function, you may need to rename it (read on). diff --git a/Doc/Manual/SWIGPlus.html b/Doc/Manual/SWIGPlus.html index f9558994b..62c0e8d1e 100644 --- a/Doc/Manual/SWIGPlus.html +++ b/Doc/Manual/SWIGPlus.html @@ -1184,15 +1184,17 @@ public: </div> <p> -This produces uncompileable wrapper code because default values in C++ are +This produces uncompilable wrapper code because default values in C++ are evaluated in the same scope as the member function whereas SWIG evaluates them in the scope of a wrapper function (meaning that the values have to be public). </p> <p> -This feature is automatically turned on when wrapping <a href="SWIG.html#SWIG_default_args">C code with default arguments</a> -and whenever keyword arguments (kwargs) are specified for either C or C++ code. +The <tt>compactdefaultargs</tt> feature is automatically turned on when wrapping <a href="SWIG.html#SWIG_default_args">C code with default arguments</a>. +Some target languages will also automatically turn on this feature +if the keyword arguments feature (kwargs) is specified for either C or C++ functions, and the target language supports kwargs, +the <tt>compactdefaultargs</tt> feature is also automatically turned on. Keyword arguments are a language feature of some scripting languages, for example Ruby and Python. SWIG is unable to support kwargs when wrapping overloaded methods, so the default approach cannot be used. </p> @@ -1203,7 +1205,7 @@ SWIG is unable to support kwargs when wrapping overloaded methods, so the defaul <p> SWIG wraps class members that are public following the C++ conventions, i.e., by explicit public declaration or by the use of - the <tt> using</tt> directive. In general, anything specified in a + the <tt>using</tt> directive. In general, anything specified in a private or protected section will be ignored, although the internal code generator sometimes looks at the contents of the private and protected sections so that it can properly generate code for default @@ -2798,7 +2800,7 @@ public: </pre></div> <p> -This code adds a<tt> __str__</tt> method to our class for producing a +This code adds a <tt>__str__</tt> method to our class for producing a string representation of the object. In Python, such a method would allow us to print the value of an object using the <tt>print</tt> command. @@ -2847,12 +2849,12 @@ struct Derived : Base { <p> The following special variables are expanded if used within a %extend block: -$name, $symname, $overname, $decl, $fulldecl, $parentname and $parentsymname. +$name, $symname, $overname, $decl, $fulldecl, $parentclassname and $parentclasssymname. The <a href="Customization.html#Customization_exception_special_variables">Special variables</a> section provides more information each of these special variables. </p> <p> -The<tt> %extend</tt> directive follows all of the same conventions +The <tt>%extend</tt> directive follows all of the same conventions as its use with C structures. Please refer to the <a href="SWIG.html#SWIG_adding_member_functions">Adding member functions to C structures</a> section for further details. </p> @@ -3565,7 +3567,7 @@ It is also possible to separate these declarations from the template class. For template<class T> class List { ... public: - List() { }; + List() { } T get(int index); ... }; diff --git a/Doc/Manual/Sections.html b/Doc/Manual/Sections.html index 99d1dfe0d..897d274ed 100644 --- a/Doc/Manual/Sections.html +++ b/Doc/Manual/Sections.html @@ -6,7 +6,7 @@ <body bgcolor="#ffffff"> <H1><a name="Sections"></a>SWIG-3.0 Documentation</H1> -Last update : SWIG-3.0.1 (in progress) +Last update : SWIG-3.0.4 (14 Jan 2015) <H2>Sections</H2> @@ -42,7 +42,7 @@ Last update : SWIG-3.0.1 (in progress) <li><a href="Go.html#Go">Go support</a></li> <li><a href="Guile.html#Guile">Guile support</a></li> <li><a href="Java.html#Java">Java support</a></li> -<li><a href="Javascript.html#Java">Javascript support</a></li> +<li><a href="Javascript.html#Javascript">Javascript support</a></li> <li><a href="Lisp.html#Lisp">Common Lisp support</a></li> <li><a href="Lua.html#Lua">Lua support</a></li> <li><a href="Modula3.html#Modula3">Modula3 support</a></li> diff --git a/Doc/Manual/Tcl.html b/Doc/Manual/Tcl.html index 45eebbf5e..45218f303 100644 --- a/Doc/Manual/Tcl.html +++ b/Doc/Manual/Tcl.html @@ -6,7 +6,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Tcl"></a>38 SWIG and Tcl</H1> +<H1><a name="Tcl"></a>39 SWIG and Tcl</H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -83,7 +83,7 @@ Tcl 8.0 or a later release. Earlier releases of SWIG supported Tcl 7.x, but this is no longer supported. </p> -<H2><a name="Tcl_nn2"></a>38.1 Preliminaries</H2> +<H2><a name="Tcl_nn2"></a>39.1 Preliminaries</H2> <p> @@ -109,7 +109,7 @@ build a Tcl extension module. To finish building the module, you need to compile this file and link it with the rest of your program. </p> -<H3><a name="Tcl_nn3"></a>38.1.1 Getting the right header files</H3> +<H3><a name="Tcl_nn3"></a>39.1.1 Getting the right header files</H3> <p> @@ -127,7 +127,7 @@ this is the case, you should probably make a symbolic link so that <tt>tcl.h</tt header file. </p> -<H3><a name="Tcl_nn4"></a>38.1.2 Compiling a dynamic module</H3> +<H3><a name="Tcl_nn4"></a>39.1.2 Compiling a dynamic module</H3> <p> @@ -160,10 +160,10 @@ of the module. If the name of your SWIG module is "<tt>example</tt>", the name of the corresponding object file should be "<tt>example.so</tt>". The name of the module is specified using the <tt>%module</tt> directive or the -<tt> -module</tt> command line option. + <tt>-module</tt> command line option. </p> -<H3><a name="Tcl_nn5"></a>38.1.3 Static linking</H3> +<H3><a name="Tcl_nn5"></a>39.1.3 Static linking</H3> <p> @@ -229,7 +229,7 @@ minimal in most situations (and quite frankly not worth the extra hassle in the opinion of this author). </p> -<H3><a name="Tcl_nn6"></a>38.1.4 Using your module</H3> +<H3><a name="Tcl_nn6"></a>39.1.4 Using your module</H3> <p> @@ -357,7 +357,7 @@ to the default system configuration (this requires root access and you will need the man pages). </p> -<H3><a name="Tcl_nn7"></a>38.1.5 Compilation of C++ extensions</H3> +<H3><a name="Tcl_nn7"></a>39.1.5 Compilation of C++ extensions</H3> <p> @@ -440,7 +440,7 @@ erratic program behavior. If working with lots of software components, you might want to investigate using a more formal standard such as COM. </p> -<H3><a name="Tcl_nn8"></a>38.1.6 Compiling for 64-bit platforms</H3> +<H3><a name="Tcl_nn8"></a>39.1.6 Compiling for 64-bit platforms</H3> <p> @@ -467,7 +467,7 @@ also introduce problems on platforms that support more than one linking standard (e.g., -o32 and -n32 on Irix). </p> -<H3><a name="Tcl_nn9"></a>38.1.7 Setting a package prefix</H3> +<H3><a name="Tcl_nn9"></a>39.1.7 Setting a package prefix</H3> <p> @@ -486,7 +486,7 @@ option will append the prefix to the name when creating a command and call it "<tt>Foo_bar</tt>". </p> -<H3><a name="Tcl_nn10"></a>38.1.8 Using namespaces</H3> +<H3><a name="Tcl_nn10"></a>39.1.8 Using namespaces</H3> <p> @@ -504,11 +504,11 @@ name, but you can override it using the <tt>-prefix</tt> option. </p> <p> -When the<tt> -namespace</tt> option is used, objects in the module +When the <tt>-namespace</tt> option is used, objects in the module are always accessed with the namespace name such as <tt>Foo::bar</tt>. </p> -<H2><a name="Tcl_nn11"></a>38.2 Building Tcl/Tk Extensions under Windows 95/NT</H2> +<H2><a name="Tcl_nn11"></a>39.2 Building Tcl/Tk Extensions under Windows 95/NT</H2> <p> @@ -519,7 +519,7 @@ covers the process of using SWIG with Microsoft Visual C++. although the procedure may be similar with other compilers. </p> -<H3><a name="Tcl_nn12"></a>38.2.1 Running SWIG from Developer Studio</H3> +<H3><a name="Tcl_nn12"></a>39.2.1 Running SWIG from Developer Studio</H3> <p> @@ -577,7 +577,7 @@ MSDOS > tclsh80 % </pre></div> -<H3><a name="Tcl_nn13"></a>38.2.2 Using NMAKE</H3> +<H3><a name="Tcl_nn13"></a>39.2.2 Using NMAKE</H3> <p> @@ -640,7 +640,7 @@ to get you started. With a little practice, you'll be making lots of Tcl extensions. </p> -<H2><a name="Tcl_nn14"></a>38.3 A tour of basic C/C++ wrapping</H2> +<H2><a name="Tcl_nn14"></a>39.3 A tour of basic C/C++ wrapping</H2> <p> @@ -651,7 +651,7 @@ classes. This section briefly covers the essential aspects of this wrapping. </p> -<H3><a name="Tcl_nn15"></a>38.3.1 Modules</H3> +<H3><a name="Tcl_nn15"></a>39.3.1 Modules</H3> <p> @@ -685,7 +685,7 @@ To fix this, supply an extra argument to <tt>load</tt> like this: </pre> </div> -<H3><a name="Tcl_nn16"></a>38.3.2 Functions</H3> +<H3><a name="Tcl_nn16"></a>39.3.2 Functions</H3> <p> @@ -710,7 +710,7 @@ like you think it does: % </pre></div> -<H3><a name="Tcl_nn17"></a>38.3.3 Global variables</H3> +<H3><a name="Tcl_nn17"></a>39.3.3 Global variables</H3> <p> @@ -790,7 +790,7 @@ extern char *path; // Read-only (due to %immutable) </pre> </div> -<H3><a name="Tcl_nn18"></a>38.3.4 Constants and enums</H3> +<H3><a name="Tcl_nn18"></a>39.3.4 Constants and enums</H3> <p> @@ -874,7 +874,7 @@ When an identifier name is given, it is used to perform an implicit hash-table l conversion. This allows the <tt>global</tt> statement to be omitted. </p> -<H3><a name="Tcl_nn19"></a>38.3.5 Pointers</H3> +<H3><a name="Tcl_nn19"></a>39.3.5 Pointers</H3> <p> @@ -970,7 +970,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return <tt>None</tt> if the conversion can't be performed. </p> -<H3><a name="Tcl_nn20"></a>38.3.6 Structures</H3> +<H3><a name="Tcl_nn20"></a>39.3.6 Structures</H3> <p> @@ -1252,7 +1252,7 @@ Note: Tcl only destroys the underlying object if it has ownership. See the memory management section that appears shortly. </p> -<H3><a name="Tcl_nn21"></a>38.3.7 C++ classes</H3> +<H3><a name="Tcl_nn21"></a>39.3.7 C++ classes</H3> <p> @@ -1283,7 +1283,7 @@ you can use it in Tcl like this: % x insert Lager % x get 1 Stout -% puts [l cget -length] +% puts [x cget -length] 3 % </pre></div> @@ -1319,7 +1319,7 @@ In Tcl, the static member is accessed as follows: </pre> </div> -<H3><a name="Tcl_nn22"></a>38.3.8 C++ inheritance</H3> +<H3><a name="Tcl_nn22"></a>39.3.8 C++ inheritance</H3> <p> @@ -1368,7 +1368,7 @@ For instance: It is safe to use multiple inheritance with SWIG. </p> -<H3><a name="Tcl_nn23"></a>38.3.9 Pointers, references, values, and arrays</H3> +<H3><a name="Tcl_nn23"></a>39.3.9 Pointers, references, values, and arrays</H3> <p> @@ -1422,7 +1422,7 @@ to hold the result and a pointer is returned (Tcl will release this memory when the return value is garbage collected). </p> -<H3><a name="Tcl_nn24"></a>38.3.10 C++ overloaded functions</H3> +<H3><a name="Tcl_nn24"></a>39.3.10 C++ overloaded functions</H3> <p> @@ -1545,7 +1545,7 @@ first declaration takes precedence. Please refer to the "SWIG and C++" chapter for more information about overloading. </p> -<H3><a name="Tcl_nn25"></a>38.3.11 C++ operators</H3> +<H3><a name="Tcl_nn25"></a>39.3.11 C++ operators</H3> <p> @@ -1647,7 +1647,7 @@ There are ways to make this operator appear as part of the class using the <tt>% Keep reading. </p> -<H3><a name="Tcl_nn26"></a>38.3.12 C++ namespaces</H3> +<H3><a name="Tcl_nn26"></a>39.3.12 C++ namespaces</H3> <p> @@ -1711,7 +1711,7 @@ utilizes thousands of small deeply nested namespaces each with identical symbol names, well, then you get what you deserve. </p> -<H3><a name="Tcl_nn27"></a>38.3.13 C++ templates</H3> +<H3><a name="Tcl_nn27"></a>39.3.13 C++ templates</H3> <p> @@ -1763,7 +1763,7 @@ More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</ examples will appear later. </p> -<H3><a name="Tcl_nn28"></a>38.3.14 C++ Smart Pointers</H3> +<H3><a name="Tcl_nn28"></a>39.3.14 C++ Smart Pointers</H3> <p> @@ -1847,7 +1847,7 @@ simply use the <tt>__deref__()</tt> method. For example: </pre> </div> -<H2><a name="Tcl_nn29"></a>38.4 Further details on the Tcl class interface</H2> +<H2><a name="Tcl_nn29"></a>39.4 Further details on the Tcl class interface</H2> <p> @@ -1860,7 +1860,7 @@ of low-level details were omitted. This section provides a brief overview of how the proxy classes work. </p> -<H3><a name="Tcl_nn30"></a>38.4.1 Proxy classes</H3> +<H3><a name="Tcl_nn30"></a>39.4.1 Proxy classes</H3> <p> @@ -1925,7 +1925,7 @@ function. This allows objects to be encapsulated objects that look a lot like as shown in the last section. </p> -<H3><a name="Tcl_nn31"></a>38.4.2 Memory management</H3> +<H3><a name="Tcl_nn31"></a>39.4.2 Memory management</H3> <p> @@ -2113,7 +2113,7 @@ typemaps--an advanced topic discussed later. </p> -<H2><a name="Tcl_nn32"></a>38.5 Input and output parameters</H2> +<H2><a name="Tcl_nn32"></a>39.5 Input and output parameters</H2> <p> @@ -2301,7 +2301,7 @@ set c [lindex $dim 1] </pre> </div> -<H2><a name="Tcl_nn33"></a>38.6 Exception handling </H2> +<H2><a name="Tcl_nn33"></a>39.6 Exception handling </H2> <p> @@ -2365,7 +2365,7 @@ Tcl extension by specifying the following in an interface file : $action // Gets substituted by actual function call } catch (RangeError) { - Tcl_SetStringObj(tcl_result,"Array index out-of-bounds"); + Tcl_SetResult(interp, (char *)"Array index out-of-bounds", TCL_STATIC); return TCL_ERROR; } } @@ -2384,7 +2384,7 @@ exception handler to only apply to specific methods like this: $action } catch (RangeError) { - Tcl_SetStringObj(tcl_result,"Array index out-of-bounds"); + Tcl_SetResult(interp, (char *)"Array index out-of-bounds", TCL_STATIC); return TCL_ERROR; } } @@ -2394,7 +2394,7 @@ exception handler to only apply to specific methods like this: $action } catch (RangeError) { - Tcl_SetStringObj(tcl_result,"Array index out-of-bounds"); + Tcl_SetResult(interp, (char *)"Array index out-of-bounds", TCL_STATIC); return TCL_ERROR; } } @@ -2419,7 +2419,7 @@ For example: $action } catch (RangeError) { - Tcl_SetStringObj(tcl_result,"Array index out-of-bounds"); + Tcl_SetResult(interp, (char *)"Array index out-of-bounds", TCL_STATIC); return TCL_ERROR; } } @@ -2435,7 +2435,7 @@ Since SWIG's exception handling is user-definable, you are not limited to C++ ex See the chapter on "<a href="Customization.html#Customization">Customization Features</a>" for more examples. </p> -<H2><a name="Tcl_nn34"></a>38.7 Typemaps</H2> +<H2><a name="Tcl_nn34"></a>39.7 Typemaps</H2> <p> @@ -2452,7 +2452,7 @@ Typemaps are only used if you want to change some aspect of the primitive C-Tcl interface. </p> -<H3><a name="Tcl_nn35"></a>38.7.1 What is a typemap?</H3> +<H3><a name="Tcl_nn35"></a>39.7.1 What is a typemap?</H3> <p> @@ -2569,7 +2569,7 @@ parameter is omitted): </pre> </div> -<H3><a name="Tcl_nn36"></a>38.7.2 Tcl typemaps</H3> +<H3><a name="Tcl_nn36"></a>39.7.2 Tcl typemaps</H3> <p> @@ -2707,7 +2707,7 @@ Initialize an argument to a value before any conversions occur. Examples of these methods will appear shortly. </p> -<H3><a name="Tcl_nn37"></a>38.7.3 Typemap variables</H3> +<H3><a name="Tcl_nn37"></a>39.7.3 Typemap variables</H3> <p> @@ -2778,7 +2778,7 @@ properly assigned. The Tcl name of the wrapper function being created. </div> -<H3><a name="Tcl_nn38"></a>38.7.4 Converting a Tcl list to a char ** </H3> +<H3><a name="Tcl_nn38"></a>39.7.4 Converting a Tcl list to a char ** </H3> <p> @@ -2840,7 +2840,7 @@ argv[2] = Larry 3 </pre></div> -<H3><a name="Tcl_nn39"></a>38.7.5 Returning values in arguments</H3> +<H3><a name="Tcl_nn39"></a>39.7.5 Returning values in arguments</H3> <p> @@ -2882,7 +2882,7 @@ result, a Tcl function using these typemaps will work like this : % </pre></div> -<H3><a name="Tcl_nn40"></a>38.7.6 Useful functions</H3> +<H3><a name="Tcl_nn40"></a>39.7.6 Useful functions</H3> <p> @@ -2921,7 +2921,6 @@ int Tcl_GetDoubleFromObj(Tcl_Interp *, Tcl_Obj *o, double *dp); <div class="code"> <pre> Tcl_Obj *Tcl_NewStringObj(char *str, int len); -void Tcl_SetStringObj(Tcl_Obj *obj, char *str, int len); char *Tcl_GetStringFromObj(Tcl_Obj *obj, int *len); void Tcl_AppendToObj(Tcl_Obj *obj, char *str, int len); </pre> @@ -2959,7 +2958,7 @@ int Tcl_IsShared(Tcl_Obj *obj); </pre> </div> -<H3><a name="Tcl_nn41"></a>38.7.7 Standard typemaps</H3> +<H3><a name="Tcl_nn41"></a>39.7.7 Standard typemaps</H3> <p> @@ -3037,13 +3036,14 @@ work) <div class="code"> <pre> -%typemap(out) char * { - Tcl_SetStringObj($result,$1); +%typemap(out,noblock=1,fragment="SWIG_FromCharPtr") char *, const char * { + Tcl_SetObjResult(interp,SWIG_FromCharPtr((const char *)$1)); } + </pre> </div> -<H3><a name="Tcl_nn42"></a>38.7.8 Pointer handling</H3> +<H3><a name="Tcl_nn42"></a>39.7.8 Pointer handling</H3> <p> @@ -3119,7 +3119,7 @@ For example: </pre> </div> -<H2><a name="Tcl_nn43"></a>38.8 Turning a SWIG module into a Tcl Package.</H2> +<H2><a name="Tcl_nn43"></a>39.8 Turning a SWIG module into a Tcl Package.</H2> <p> @@ -3191,7 +3191,7 @@ As a final note, most SWIG examples do not yet use the to use the <tt>load</tt> command instead. </p> -<H2><a name="Tcl_nn44"></a>38.9 Building new kinds of Tcl interfaces (in Tcl)</H2> +<H2><a name="Tcl_nn44"></a>39.9 Building new kinds of Tcl interfaces (in Tcl)</H2> <p> @@ -3290,7 +3290,7 @@ danger of blowing something up (although it is easily accomplished with an out of bounds array access). </p> -<H3><a name="Tcl_nn45"></a>38.9.1 Proxy classes</H3> +<H3><a name="Tcl_nn45"></a>39.9.1 Proxy classes</H3> <p> @@ -3411,7 +3411,7 @@ short, but clever Tcl script can be combined with SWIG to do many interesting things. </p> -<H2><a name="Tcl_nn46"></a>38.10 Tcl/Tk Stubs</H2> +<H2><a name="Tcl_nn46"></a>39.10 Tcl/Tk Stubs</H2> <p> diff --git a/Doc/Manual/Typemaps.html b/Doc/Manual/Typemaps.html index cba524149..040244d45 100644 --- a/Doc/Manual/Typemaps.html +++ b/Doc/Manual/Typemaps.html @@ -2050,6 +2050,22 @@ wrap_foo() { </pre> </div> +<p>There is an exception: if the variable name starts with the <tt>_global_</tt> prefix, +the argument number is not appended. Such variables can be used throughout the generated +wrapper function. For example, the above typemap could be rewritten to use <tt>_global_temp</tt> +instead of <tt>temp</tt> and the generated code would then contain a single <tt>_global_temp</tt> variable +instead of <tt>temp1</tt>, <tt>temp2</tt> and <tt>temp3</tt>: +</p> + +<div class="code"> +<pre> +%typemap(in) std::string * <b>(std::string _global_temp)</b> { + ... as above ... +} +</pre> +</div> + + <p> Some typemaps do not recognize local variables (or they may simply not apply). At this time, only typemaps that apply to argument conversion support this (input typemaps such as the "in" typemap). @@ -3360,7 +3376,7 @@ list of strings like this: </div> <p> -To do this, you not only need to map a list of strings to <tt> char *argv[]</tt>, but the +To do this, you not only need to map a list of strings to <tt>char *argv[]</tt>, but the value of <tt>int argc</tt> is implicitly determined by the length of the list. Using only simple typemaps, this type of conversion is possible, but extremely painful. Multi-argument typemaps help in this situation. |