diff options
Diffstat (limited to 'Doc')
52 files changed, 7666 insertions, 3135 deletions
diff --git a/Doc/Devel/plan-gsoc-2012.txt b/Doc/Devel/plan-gsoc-2012.txt new file mode 100644 index 000000000..ac764fb2a --- /dev/null +++ b/Doc/Devel/plan-gsoc-2012.txt @@ -0,0 +1,341 @@ + + + + + Project Plan + ============ + SWIG Code Comments + Google Summer of Code 2012 + + +This document describes goals for the Google Summer of Code 2012, +SWIG code documentation project. + +Author: Marko Klopcic, Dmitry Kabak + + +Introduction +============ + +The goal of this project is _not_ to translate _any_ possible Doxygen +formatted comment to JavaDoc or PyDoc, but to make it possible to +translate a subset of comment types in C/C++ code to +JavaDoc and PyDoc. Covering all the Doxygen functionality would be to +complex for the limited time. However, the code must be flexible so +that implementing missing features would not require redesign of the +comment handling code in SWIG. + +There will also be a possibility to add untranslated comments to Java +and Python code (## comments, see Doxygen manual), if the user will +prefer to use Doxygen on the generated code. + +Note: +'-OK-' tick below means that the item is implemented, committed and +working. + +Abbreviations: + JD - JavaDoc + PD - PyDoc + + +Functionality +============= + + Types of comments + ----------------- + + Note: + See 'http://www.stack.nl/~dimitri/doxygen/docblocks.html' for + the detailed description of Doxygen syntax and terms used in this + section. + + 1. -OK- Only JavaDoc (/** */) and Qt (/*! */) styles of comment blocks + will be supported by SWIG translator. + + 2. -OK- The following doc after members will be supported: + + int var; ///< Detailed description after the member + //!< + + int var; //!< Brief description after the member + + int var; ///< Brief description after the member + + + 3. -OK- Only comments before or after declaration/definition will be + supported. Comments with structural commands will be ignored + (warning will be written). (What about writing them to + 'package.info.java' for JD?) + + + Tags + ---- + + This section contains all doxygen tags taken from + http://www.stack.nl/~dimitri/doxygen/commands.html. If a tag is + marked as 'ignored', then the tag is ignored, but the text is copied + to the destination documentation. 'Not implemented' means that the + tag with it's contents is stripped out of the output. + + Doxygen tags: + + All tags: -OK- + + \a - translated to <i></i> in JD, surrounded with _ in PD + \addindex - ignored + \addtogroup - ignored + \anchor - ignored, not supported by JD and PD + \arg - equivalent to \li + \attention - ignored + \authors, \author - translated to @author in JD, 'Author:' in PD + \b - <b></b> in JD, surrounded with __ in PD + \brief - ignored + \bug - ignored + \c - translated to <code></code> in JD, ignored in PD + \callgraph - ignored, not supported by JD and PD + \callergraph - ignored, not supported by JD and PD + \category - ignored, used only in Objective C + \cite - translated to <i></i> in JD, single quotes in PD + \class - ignored (structural command) + \code - translated to {@code ...} in JD, ignored in PD + \cond - translated to 'Conditional comment: <condition>'. Later + SWIG may support definitions of conditions in config file. + \copybrief - ignored. Later SWIG may support this command by + performing copy + \copydetails - ignored. Later SWIG may support this command by + performing copy + \copydoc - ignored. Later SWIG may support this command by + performing copy + \copyright - replaced with text 'Copyright' in PD and PD + \date - ignored + \def - ignored (structural command) + \defgroup - not supported + \deprecated - translated to @deprecated in JD, 'Deprecated:' in PD + \details - ignored + \dir - not supported + \dontinclude - not supported + \dot - not supported. Later SWIG may call dot and produce the graph image + to include in JD and PD + \dotfile - see note for \dot + \e - equivalent \a + \else - see note for \cond + \elseif - see note for \cond + \em - equivalent to \a + \endcode - see note for \code + \endcond - translated to 'End of conditional comment: <condition>'. Later + SWIG may support definitions of conditions in config file. + \enddot - see note for \dot + \endhtmlonly - ignored + \endif - see note for \cond + \endinternal - ignored + \endlatexonly - ignored + \endlink - see note for \link + \endmanonly - ignored + \endmsc - see note for \msc + \endrtfonly - ignored + \endverbatim - see note for \verbatim + \endxmlonly - ignored + \enum - ignored (structural command) + \example - translated to 'Example:' in JD and PD + \exception - equivalent to throws, but translates to @exception in JD + \extends - not supported + \f$ - ignored. Later swig may call LATeX to produce bitmaps with formulas + to include in JD and PD + \f[ - see note for \f$ + \f] - see note for \f$ + \f{ - see note for \f$ + \f} - see note for \f$ + \file - ignored (structural command) + \fn - ignored (structural command) + \headerfile - not supported + \hideinitializer - not supported + \htmlinclude - not supported + \htmlonly - ignored + \if - see note for \cond + \ifnot - see note for \cond + \image - translated to <img/> in JD only when target=HTML, translated to + 'Image: filename(Title)' + \implements - not supported + \include - not supported + \includelineno - not supported + \ingroup - not supported. Later swig may print group names as plain text + in comments like 'Code group: something' in both JD and PD + \internal - ignored + \invariant - ignored + \interface - ignored (structural command) + \latexonly - ignored + \li - trabslated to <li></li> in JD, ignored in PD + \line - not supported + \link - translated to {@link ...} in JD, ignored in PD + \mainpage - ignored + \manonly - ignored + \memberof - not supported + \msc - not supported. Later SWIG may call dot and produce the graph image + to include in JD and PD + \mscfile - see note for \msc + \n - prints the new line + \name - ignored + \namespace - included in package-info.java if nspace feature is enabled, + otherwise ignored, ignored in PD + \nosubgrouping - ignored + \note - translated to 'Note:' in both JD and PD + \overload - prints 'This is an overloaded member function, provided for + convenience. It differs from the above function only in what + argument(s) it accepts.' to the output in both JD and PD + \p - equivalent to \c + \package - is kept same in JD (it is already a JD tag), ignored in PD + \page - ignored + \par - translated to <p alt='title'></p> in JD, 'Title: ...' in PD + \paragraph - ignored + \param - translated to @param in JD, special formatting in PD + \post - ignored + \pre - ignored + \private - ignored + \privatesection - ignored + \property - ignored + \protected - ignored + \protectedsection - ignored + \protocol - ignored (Objective-C tag) + \public - ignored + \publicsection - ignored + \ref - ignored, not supported by JD and PD + \related - ignored + \relates - ignored + \relatedalso - ignored + \relatesalso - ignored + \remark - translated to 'Remarks:' in both JD and PD + \remarks - equivalent to remark + \result - translated to @return in JD, 'Return:' in PD + \return - equivalent to result + \returns - equivalent to result + \retval - ignored + \rtfonly - ignored + \sa - translated to @see in JD, 'See also:' in PD + \section - not supported + \see - equivalent to \sa + \short - equivalent to \brief + \showinitializer - not supported + \since - translated to @since in JD, 'Since:' in PD + \skip - not supported + \skipline - not supported + \snippet - not supported + \struct - ignored (structural command) + \subpage - not supported + \subsection - not supported + \subsubsection - not supported + \tableofcontents - not supported + \test - ignored + \throw - translated to @throws in JD, 'Throws:' in PD + \throws - equivalent to \throw + \todo - translated to 'TODO:' in both JD and PD + \tparam - similar to \arg + \typedef - ignored (structural command) + \union - ignored (structural command) + \until - not supported + \var - ignored (structural command) + \verbatim - translated to {@literal ...} in JD, ignored in PD + \verbinclude - ignored + \version - translated to @version in JD, 'Version:' in PD + \warning - translated to 'Warning:' in both JD and PD + \weakgroup - not supported + \xmlonly - ignored + \xrefitem - ignored + \$ - this and all the others below: these commands insert single char, + it is escaped as HTML char in JD, kept as-is in PD + \@ + \\ + \& + \~ + \< + \> + \# + \% + \" + \. + \:: + +Optional functionality +====================== + +That section describes some complex cases where the current code +does not behave really well. Like a short to-do list of special cases. + +-OK- When translating functions with default parameters in swig to +java, it creates overloaded functions with all the parameters +except the default ones. We need to copy the doxygen comment to +such functions and correct the list of @param tags. + +-OK- In doxygen there is a special tags (and even a special option) +to create links to some code members from the current comment. +Sometimes it needs a type of parameters specified because of the +overloaded functions. And the same linking tags are supported in JD, +but it has a completely different typesystem, so we need to translate +the types of function parameters in comments also. For example: +{@link MyClass#doSomething(const std::string &)} +does not make sense in Java, so the type should be converted. +{@link MyClass#doSomething(String)} + + +Tests +===== + +The following test cases will be implemented: + +-OK- Class comments. + +-OK- Struct comments. +-OK- Enum comments. +-OK- Function comments. +-OK- Var comments. + +-OK- Class attributes, comment before and after declaration. +-OK- Class methods, comment of parameters in function + comment. +-OK- Class methods, comment of parameters + after parameter declaration. + +-OK- Struct attributes, comment before and after declaration. +-OK- Struct methods, comment of parameters in function + comment. +-OK- Struct methods, comment of parameters + after parameter declaration. + +-OK- Enum items JD and Qt style, comment before items +-OK- Enum items JD and Qt style, comment after items + +-OK- Class comment, with all supported tags. +-OK- Class comment, with all doxygen tags, including + ignored ones. + +The list of all tests, in form of shell commands to make it simple +to test project by copying the text below into terminal program. +make doxygen_parsing.cpptest -s +make doxygen_translate.cpptest -s +make doxygen_translate_all_tags.cpptest -s +make doxygen_basic_translate.cpptest -s +make doxygen_basic_notranslate.cpptest -s +make doxygen_translate_links.cpptest -s +make doxygen_tricky_constructs.cpptest -s + + +Refactoring +=========== + +All the code in directory _Doxygen_ should be refactored: +-OK- all methods should be class members +-OK- most static methods should be normal members +-OK- replace C arrays of strings and sequential searches with STL data + structures and algorithms. +-OK- use singletons instead of class instantiaion for each comment found. + + +Documentation +============= + +SWIG documentation will contain: +-OK- command line options +-OK- list of implemented features (types and placements of comments) +-OK- list of unimplemented features (types and placements of comments) +-OK- list of tags and their translations (all Doxygen tags). +-OK- some amount of debugging and development information + diff --git a/Doc/Devel/runtime.txt b/Doc/Devel/runtime.txt index f88edf767..ae9c83275 100644 --- a/Doc/Devel/runtime.txt +++ b/Doc/Devel/runtime.txt @@ -57,7 +57,7 @@ Alternatively, if the language supports modules, a module named named "type_table" SWIG_TYPE_TABLE_NAME can be created inside it. The most common approach is to store the mod pointer in some global variable in the target language, but if the language provides an alternative place to store data -(like the chicken module), then that is good too. +then that is good too. The way the code is set up, SetModule should only be called when GetModule returns NULL, and if SetModule is called a second time, the behavior is @@ -105,7 +105,7 @@ Standard Functions These functions are not required and their API is not formalized, but almost all language modules implement them for consistency across languages. Throughout this discussion, I will use LangType to represent the underlying language type -(C_word in chicken, Scheme_Object * in mzscheme, PyObject * in python, etc) +(Scheme_Object * in mzscheme, PyObject * in python, etc) diff --git a/Doc/Devel/tree.html b/Doc/Devel/tree.html index 73a49ed55..5bb4b6a1e 100644 --- a/Doc/Devel/tree.html +++ b/Doc/Devel/tree.html @@ -236,7 +236,7 @@ The following functions can be used to help debug SWIG parse trees. <blockquote> Prints the tag-structure of the parse tree to standard output. <tt>node</tt> is the top-level parse tree node. <tt>prefix</tt> is -a string prefix thats added to the start of each line. Normally, you would specify the empty string or NIL for <tt>prefix</tt>. +a string prefix that's added to the start of each line. Normally, you would specify the empty string or NIL for <tt>prefix</tt>. This function is called by the <tt>-debug-tags</tt> option to SWIG. <pre> diff --git a/Doc/Manual/Allegrocl.html b/Doc/Manual/Allegrocl.html index ddb6fba55..4069ecd8b 100644 --- a/Doc/Manual/Allegrocl.html +++ b/Doc/Manual/Allegrocl.html @@ -8,7 +8,7 @@ <body bgcolor="#ffffff"> -<H1><a name="Allegrocl">18 SWIG and Allegro Common Lisp</a></H1> +<H1><a name="Allegrocl">20 SWIG and Allegro Common Lisp</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -129,16 +129,16 @@ It is significant to note that, while this is a vendor-specific module, we would like to acknowledge the current and ongoing work by developers in the open source lisp community that are working on similar interfaces to implementation-independent -foreign function interfaces (UFFI or CFFI, for example). Such +foreign function interfaces (CFFI, for example). Such work can only benefit the lisp community, and we would not be unhappy to see some enterprising folk use this work to add to it. </p> -<H2><a name="Allegrocl_nn2">18.1 Basics</a></H2> +<H2><a name="Allegrocl_nn2">20.1 Basics</a></H2> -<H3><a name="Allegrocl_nn3">18.1.1 Running SWIG</a></H3> +<H3><a name="Allegrocl_nn3">20.1.1 Running SWIG</a></H3> <p> @@ -155,7 +155,7 @@ SWIG directives. SWIG can be furnished with a header file, but an interface can also be generated without library headers by supplying a simple text file--called the interface file, which is typically named with a <tt>.i</tt> extension--containing any foreign declarations of -identifiers you wish to use. The most common approach is to use a an +identifiers you wish to use. The most common approach is to use an interface file with directives to parse the needed headers. A straight parse of library headers will result in usable code, but SWIG directives provides much freedom in how a user might tailor the @@ -360,7 +360,7 @@ need to link in the Allegro shared library. The library you create from the C++ wrapper will be what you then load into Allegro CL. </p> -<H3><a name="Allegrocl_nn4">18.1.2 Command Line Options</a></H3> +<H3><a name="Allegrocl_nn4">20.1.2 Command Line Options</a></H3> <p> @@ -396,7 +396,7 @@ See <a href="#Allegrocl_nn47">Section 17.5 Identifier converter functions</a> for more details. </p> -<H3><a name="Allegrocl_nn5">18.1.3 Inserting user code into generated files</a></H3> +<H3><a name="Allegrocl_nn5">20.1.3 Inserting user code into generated files</a></H3> <p> @@ -436,7 +436,7 @@ Note that the block <tt>%{ ... %}</tt> is effectively a shortcut for </p> -<H2><a name="Allegrocl_nn6">18.2 Wrapping Overview</a></H2> +<H2><a name="Allegrocl_nn6">20.2 Wrapping Overview</a></H2> <p> @@ -446,7 +446,7 @@ New users to SWIG are encouraged to read interested in generating an interface to C++. </p> -<H3><a name="Allegrocl_nn7">18.2.1 Function Wrapping</a></H3> +<H3><a name="Allegrocl_nn7">20.2.1 Function Wrapping</a></H3> <p> @@ -499,7 +499,7 @@ interested in generating an interface to C++. </pre> </div> -<H3><a name="Allegrocl_nn8">18.2.2 Foreign Wrappers</a></H3> +<H3><a name="Allegrocl_nn8">20.2.2 Foreign Wrappers</a></H3> <p> @@ -512,7 +512,7 @@ interested in generating an interface to C++. typemap. </p> -<H3><a name="Allegrocl_nn9">18.2.3 FFI Wrappers</a></H3> +<H3><a name="Allegrocl_nn9">20.2.3 FFI Wrappers</a></H3> <p> @@ -593,7 +593,7 @@ char *xxx(); ff:def-foreign-call's. </p> -<H3><a name="Allegrocl_nn10">18.2.4 Non-overloaded Defuns</a></H3> +<H3><a name="Allegrocl_nn10">20.2.4 Non-overloaded Defuns</a></H3> <p> @@ -606,11 +606,11 @@ char *xxx(); this function can be manipulated via the <tt>lout</tt> typemap. </p> -<H3><a name="Allegrocl_nn11">18.2.5 Overloaded Defuns</a></H3> +<H3><a name="Allegrocl_nn11">20.2.5 Overloaded Defuns</a></H3> <p> - In the case of overloaded functions, mulitple layers are + In the case of overloaded functions, multiple layers are generated. First, all the overloads for a given name are separated out into groups based on arity, and are wrapped in defmethods. Each method calls a distinct wrapper function, but are @@ -622,7 +622,7 @@ char *xxx(); can be manipulated via the <tt>lout</tt> typemap. </p> -<H3><a name="Allegrocl_nn12">18.2.6 What about constant and variable access?</a></H3> +<H3><a name="Allegrocl_nn12">20.2.6 What about constant and variable access?</a></H3> <p> @@ -635,7 +635,7 @@ char *xxx(); into the foreign module. </p> -<H3><a name="Allegrocl_nn13">18.2.7 Object Wrapping</a></H3> +<H3><a name="Allegrocl_nn13">20.2.7 Object Wrapping</a></H3> <p> @@ -657,7 +657,7 @@ char *xxx(); foreign function interface. </p> -<H2><a name="Allegrocl_nn14">18.3 Wrapping Details</a></H2> +<H2><a name="Allegrocl_nn14">20.3 Wrapping Details</a></H2> <p> @@ -665,7 +665,7 @@ char *xxx(); translated into lisp. </p> -<H3><a name="Allegrocl_nn15">18.3.1 Namespaces</a></H3> +<H3><a name="Allegrocl_nn15">20.3.1 Namespaces</a></H3> <p> @@ -742,7 +742,7 @@ namespace car { function such as <tt>(car '(1 2 3)</tt>. </p> -<H3><a name="Allegrocl_nn16">18.3.2 Constants</a></H3> +<H3><a name="Allegrocl_nn16">20.3.2 Constants</a></H3> @@ -803,7 +803,7 @@ namespace car { not use the <tt>-nocwrap</tt> command-line option. </p> -<H3><a name="Allegrocl_nn17">18.3.3 Variables</a></H3> +<H3><a name="Allegrocl_nn17">20.3.3 Variables</a></H3> <p> @@ -881,7 +881,7 @@ globalvar> (globalvar.nnn::glob_float) </pre> </div> -<H3><a name="Allegrocl_nn18">18.3.4 Enumerations</a></H3> +<H3><a name="Allegrocl_nn18">20.3.4 Enumerations</a></H3> <p> @@ -957,7 +957,7 @@ EXPORT const int ACL_ENUM___FOO3__SWIG_0 = FOO3; </pre> </div> -<H3><a name="Allegrocl_nn19">18.3.5 Arrays</a></H3> +<H3><a name="Allegrocl_nn19">20.3.5 Arrays</a></H3> <p> @@ -1105,10 +1105,10 @@ namespace BAR { </pre> </div> -<H3><a name="Allegrocl_nn20">18.3.6 Classes and Structs and Unions (oh my!)</a></H3> +<H3><a name="Allegrocl_nn20">20.3.6 Classes and Structs and Unions (oh my!)</a></H3> -<H4><a name="Allegrocl_nn21">18.3.6.1 CLOS wrapping of</a></H4> +<H4><a name="Allegrocl_nn21">20.3.6.1 CLOS wrapping of</a></H4> <p> @@ -1123,7 +1123,7 @@ namespace BAR { integer values. </p> -<H4><a name="Allegrocl_nn22">18.3.6.2 CLOS Inheritance</a></H4> +<H4><a name="Allegrocl_nn22">20.3.6.2 CLOS Inheritance</a></H4> <p> @@ -1136,7 +1136,7 @@ namespace BAR { parameter. </p> -<H4><a name="Allegrocl_nn23">18.3.6.3 Member fields and functions</a></H4> +<H4><a name="Allegrocl_nn23">20.3.6.3 Member fields and functions</a></H4> <p> @@ -1152,7 +1152,7 @@ namespace BAR { the interface does nothing for <tt>friend</tt> directives, </p> -<H4><a name="Allegrocl_nn24">18.3.6.4 Why not directly access C++ classes using foreign types?</a></H4> +<H4><a name="Allegrocl_nn24">20.3.6.4 Why not directly access C++ classes using foreign types?</a></H4> <p> @@ -1170,11 +1170,11 @@ namespace BAR { use the more robust wrapper functions. </p> -<H3><a name="Allegrocl_nn25">18.3.7 Templates</a></H3> +<H3><a name="Allegrocl_nn25">20.3.7 Templates</a></H3> -<H4><a name="Allegrocl_nn26">18.3.7.1 Generating wrapper code for templates</a></H4> +<H4><a name="Allegrocl_nn26">20.3.7.1 Generating wrapper code for templates</a></H4> <p> @@ -1187,7 +1187,7 @@ them. This is done via the directive. </p> -<H4><a name="Allegrocl_nn27">18.3.7.2 Implicit Template instantiation</a></H4> +<H4><a name="Allegrocl_nn27">20.3.7.2 Implicit Template instantiation</a></H4> <p> @@ -1197,7 +1197,7 @@ to include these templated classes in the foreign-type and CLOS class schema. </p> -<H3><a name="Allegrocl_nn28">18.3.8 Typedef, Templates, and Synonym Types</a></H3> +<H3><a name="Allegrocl_nn28">20.3.8 Typedef, Templates, and Synonym Types</a></H3> <p> @@ -1239,7 +1239,7 @@ int zzz(A *inst = 0); /* return inst->x + inst->y */ We resolve this issue, by noting synonym relationships between types while generating the interface. A Primary type is selected (more on this below) from the candidate list of synonyms. For - all other synonyms, intead of generating a distinct CLOS class + all other synonyms, instead of generating a distinct CLOS class definition, we generate a form that expands to: </p> <div class="targetlang"> @@ -1277,7 +1277,7 @@ synonym> </pre> </div> -<H4><a name="Allegrocl_nn29">18.3.8.1 Choosing a primary type</a></H4> +<H4><a name="Allegrocl_nn29">20.3.8.1 Choosing a primary type</a></H4> <p> @@ -1298,7 +1298,7 @@ synonym> </li> </ul> -<H3><a name="Allegrocl_nn30">18.3.9 Function overloading/Parameter defaulting</a></H3> +<H3><a name="Allegrocl_nn30">20.3.9 Function overloading/Parameter defaulting</a></H3> <p> @@ -1461,7 +1461,7 @@ overload> </pre> </div> -<H3><a name="Allegrocl_nn31">18.3.10 Operator wrapping and Operator overloading</a></H3> +<H3><a name="Allegrocl_nn31">20.3.10 Operator wrapping and Operator overloading</a></H3> <p> @@ -1607,7 +1607,7 @@ opoverload> </pre> </div> -<H3><a name="Allegrocl_nn32">18.3.11 Varargs</a></H3> +<H3><a name="Allegrocl_nn32">20.3.11 Varargs</a></H3> <p> @@ -1628,7 +1628,7 @@ opoverload> with other ways such functions can be wrapped. </p> -<H3><a name="Allegrocl_nn33">18.3.12 C++ Exceptions</a></H3> +<H3><a name="Allegrocl_nn33">20.3.12 C++ Exceptions</a></H3> <p> @@ -1640,7 +1640,7 @@ opoverload> implemented. </p> -<H3><a name="Allegrocl_nn34">18.3.13 Pass by value, pass by reference</a></H3> +<H3><a name="Allegrocl_nn34">20.3.13 Pass by value, pass by reference</a></H3> <p> @@ -1652,7 +1652,7 @@ opoverload> newly defined types. </p> -<H2><a name="Allegrocl_nn35">18.4 Typemaps</a></H2> +<H2><a name="Allegrocl_nn35">20.4 Typemaps</a></H2> <p> @@ -1663,7 +1663,7 @@ opoverload> on <a href="Typemaps.html#Typemaps">Typemaps</a> for more information. </p> -<H3><a name="Allegrocl_nn36">18.4.1 Code Generation in the C++ Wrapper</a></H3> +<H3><a name="Allegrocl_nn36">20.4.1 Code Generation in the C++ Wrapper</a></H3> @@ -1693,7 +1693,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) </pre> </div> -<H4><a name="Allegrocl_nn37">18.4.1.1 IN Typemap</a></H4> +<H4><a name="Allegrocl_nn37">20.4.1.1 IN Typemap</a></H4> <p> @@ -1728,7 +1728,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) </pre> </div> -<H4><a name="Allegrocl_nn38">18.4.1.2 OUT Typemap</a></H4> +<H4><a name="Allegrocl_nn38">20.4.1.2 OUT Typemap</a></H4> <p> @@ -1752,7 +1752,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) </pre> </div> -<H4><a name="Allegrocl_nn39">18.4.1.3 CTYPE Typemap</a></H4> +<H4><a name="Allegrocl_nn39">20.4.1.3 CTYPE Typemap</a></H4> <p> @@ -1784,7 +1784,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) these <a href="Typemaps.html#Typemaps_nn25">common typemaps</a> here. </p> -<H3><a name="Allegrocl_nn40">18.4.2 Code generation in Lisp wrappers</a></H3> +<H3><a name="Allegrocl_nn40">20.4.2 Code generation in Lisp wrappers</a></H3> <p> @@ -1803,7 +1803,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) <a href="#Allegrocl_nn15">16.3.1 Namespaces</a> for details. </p> -<H4><a name="Allegrocl_nn41">18.4.2.1 LIN Typemap</a></H4> +<H4><a name="Allegrocl_nn41">20.4.2.1 LIN Typemap</a></H4> <p> @@ -1846,7 +1846,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) </pre> </div> -<H4><a name="Allegrocl_nn42">18.4.2.2 LOUT Typemap</a></H4> +<H4><a name="Allegrocl_nn42">20.4.2.2 LOUT Typemap</a></H4> <p> @@ -1889,7 +1889,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) </pre> </div> -<H4><a name="Allegrocl_nn43">18.4.2.3 FFITYPE Typemap</a></H4> +<H4><a name="Allegrocl_nn43">20.4.2.3 FFITYPE Typemap</a></H4> @@ -1939,7 +1939,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) </pre> </div> -<H4><a name="Allegrocl_nn44">18.4.2.4 LISPTYPE Typemap</a></H4> +<H4><a name="Allegrocl_nn44">20.4.2.4 LISPTYPE Typemap</a></H4> <p> @@ -1959,7 +1959,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) </pre> </div> -<H4><a name="Allegrocl_nn45">18.4.2.5 LISPCLASS Typemap</a></H4> +<H4><a name="Allegrocl_nn45">20.4.2.5 LISPCLASS Typemap</a></H4> <p> @@ -1983,7 +1983,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) </pre> </div> -<H3><a name="Allegrocl_nn46">18.4.3 Modifying SWIG behavior using typemaps</a></H3> +<H3><a name="Allegrocl_nn46">20.4.3 Modifying SWIG behavior using typemaps</a></H3> <p> @@ -2017,10 +2017,10 @@ return-val wrapper-name(parm0, parm1, ..., parmN) </pre> </div> -<H2><a name="Allegrocl_nn47">18.5 Identifier Converter functions</a></H2> +<H2><a name="Allegrocl_nn47">20.5 Identifier Converter functions</a></H2> -<H3><a name="Allegrocl_nn48">18.5.1 Creating symbols in the lisp environment</a></H3> +<H3><a name="Allegrocl_nn48">20.5.1 Creating symbols in the lisp environment</a></H3> <p> @@ -2041,11 +2041,11 @@ return-val wrapper-name(parm0, parm1, ..., parmN) of arguments. </p> -<H3><a name="Allegrocl_nn49">18.5.2 Existing identifier-converter functions</a></H3> +<H3><a name="Allegrocl_nn49">20.5.2 Existing identifier-converter functions</a></H3> <p>Two basic identifier routines have been defined. -<H4><a name="Allegrocl_nn50">18.5.2.1 identifier-convert-null</a></H4> +<H4><a name="Allegrocl_nn50">20.5.2.1 identifier-convert-null</a></H4> <p> @@ -2054,7 +2054,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) strings, from which a symbol will be created. </p> -<H4><a name="Allegrocl_nn51">18.5.2.2 identifier-convert-lispify</a></H4> +<H4><a name="Allegrocl_nn51">20.5.2.2 identifier-convert-lispify</a></H4> <p> @@ -2063,7 +2063,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) same symbol transformations. </p> -<H4><a name="Allegrocl_nn52">18.5.2.3 Default identifier to symbol conversions</a></H4> +<H4><a name="Allegrocl_nn52">20.5.2.3 Default identifier to symbol conversions</a></H4> <p> @@ -2072,7 +2072,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) default naming conventions. </p> -<H3><a name="Allegrocl_nn53">18.5.3 Defining your own identifier-converter</a></H3> +<H3><a name="Allegrocl_nn53">20.5.3 Defining your own identifier-converter</a></H3> <p> @@ -2128,7 +2128,7 @@ indicating the number of arguments passed to the routine indicated by this identifier. </p> -<H3><a name="Allegrocl_nn54">18.5.4 Instructing SWIG to use a particular identifier-converter</a></H3> +<H3><a name="Allegrocl_nn54">20.5.4 Instructing SWIG to use a particular identifier-converter</a></H3> <p> diff --git a/Doc/Manual/Android.html b/Doc/Manual/Android.html index b295b5e04..944a88d65 100644 --- a/Doc/Manual/Android.html +++ b/Doc/Manual/Android.html @@ -6,7 +6,7 @@ <meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head> <body bgcolor="#FFFFFF"> -<H1><a name="Android">19 SWIG and Android</a></H1> +<H1><a name="Android">21 SWIG and Android</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -31,7 +31,7 @@ This chapter describes SWIG's support of Android. -<H2><a name="Android_overview">19.1 Overview</a></H2> +<H2><a name="Android_overview">21.1 Overview</a></H2> <p> @@ -41,14 +41,14 @@ Everything in the <a href="Java.html#Java">Java chapter</a> applies to generatin This chapter contains a few Android specific notes and examples. </p> -<H2><a name="Android_examples">19.2 Android examples</a></H2> +<H2><a name="Android_examples">21.2 Android examples</a></H2> -<H3><a name="Android_examples_intro">19.2.1 Examples introduction</a></H3> +<H3><a name="Android_examples_intro">21.2.1 Examples introduction</a></H3> <p> -The examples require the <a href="http://developer.android.com/sdk/index.html">Android SDK</a> and <a href="http://developer.android.com/tools/sdk/ndk/index.html">Android NDK</a> which can be installed as per instructions in the links. +The examples require the <a href="https://developer.android.com/sdk/">Android SDK</a> and <a href="https://developer.android.com/ndk/">Android NDK</a> which can be installed as per instructions in the links. The Eclipse version is not required for these examples as just the command line tools are used (shown for Linux as the host, but Windows will be very similar, if not identical in most places). Add the SDK tools and NDK tools to your path and create a directory somewhere for your Android projects (adjust PATH as necessary to where you installed the tools): </p> @@ -77,7 +77,7 @@ $ android list targets The following examples are shipped with SWIG under the Examples/android directory and include a Makefile to build and install each example. </p> -<H3><a name="Android_example_simple">19.2.2 Simple C example</a></H3> +<H3><a name="Android_example_simple">21.2.2 Simple C example</a></H3> <p> @@ -326,7 +326,7 @@ include $(BUILD_SHARED_LIBRARY) </div> <p> -See the <a href="http://developer.android.com/sdk/ndk/index.html">Android NDK documentation</a> for more on the NDK build system and getting started with the NDK. +See the <a href="https://developer.android.com/ndk/">Android NDK documentation</a> for more on the NDK build system and getting started with the NDK. A simple invocation of ndk-build will compile the .c files and generate a shared object/system library. Output will be similar to: </p> @@ -399,7 +399,7 @@ Run the app again and this time you will see the output pictured below, showing <center><img src="android-simple.png" alt="Android screenshot of SwigSimple example"></center> -<H3><a name="Android_example_class">19.2.3 C++ class example</a></H3> +<H3><a name="Android_example_class">21.2.3 C++ class example</a></H3> <p> @@ -409,7 +409,7 @@ All the steps required to compile and use a simple hierarchy of classes for shap <p> First create an Android project called <tt>SwigClass</tt> in a subdirectory called <tt>class</tt>. -The steps below create and build a the JNI C++ app. +The steps below create and build the JNI C++ app. Adjust the <tt>--target</tt> id as mentioned earlier in the <a href="Android.html#Android_examples_intro">Examples introduction</a>. </p> @@ -747,7 +747,7 @@ Run the app to see the result of calling the C++ code from Java: <center><img src="android-class.png" alt="Android screenshot of SwigClass example"></center> -<H3><a name="Android_examples_other">19.2.4 Other examples</a></H3> +<H3><a name="Android_examples_other">21.2.4 Other examples</a></H3> <p> @@ -759,7 +759,7 @@ Note that the 'extend' example is demonstrates the directors feature. Normally C++ exception handling and the STL is not available by default in the version of g++ shipped with Android, but this example turns these features on as described in the next section. </p> -<H2><a name="Android_stl">19.3 C++ STL</a></H2> +<H2><a name="Android_stl">21.3 C++ STL</a></H2> <p> diff --git a/Doc/Manual/Arguments.html b/Doc/Manual/Arguments.html index 9dae9fdcd..2828bf4df 100644 --- a/Doc/Manual/Arguments.html +++ b/Doc/Manual/Arguments.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Arguments">10 Argument Handling</a></H1> +<H1><a name="Arguments">12 Argument Handling</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -32,7 +32,7 @@ <p> -In Chapter 3, SWIG's treatment of basic datatypes and pointers was +In Chapter 5, SWIG's treatment of basic datatypes and pointers was described. In particular, primitive types such as <tt>int</tt> and <tt>double</tt> are mapped to corresponding types in the target language. For everything else, pointers are used to refer to @@ -43,7 +43,7 @@ return multiple values through the arguments of a function. This chapter describes some of the techniques for doing this. </p> -<H2><a name="Arguments_nn2">10.1 The typemaps.i library</a></H2> +<H2><a name="Arguments_nn2">12.1 The typemaps.i library</a></H2> <p> @@ -51,7 +51,7 @@ This section describes the <tt>typemaps.i</tt> library file--commonly used to change certain properties of argument conversion. </p> -<H3><a name="Arguments_nn3">10.1.1 Introduction</a></H3> +<H3><a name="Arguments_nn3">12.1.1 Introduction</a></H3> <p> @@ -195,7 +195,7 @@ else. To clear a typemap, the <tt>%clear</tt> directive should be used. For e </pre> </div> -<H3><a name="Arguments_nn4">10.1.2 Input parameters</a></H3> +<H3><a name="Arguments_nn4">12.1.2 Input parameters</a></H3> <p> @@ -248,7 +248,7 @@ When the function is used in the scripting language interpreter, it will work li result = add(3, 4) </pre></div> -<H3><a name="Arguments_nn5">10.1.3 Output parameters</a></H3> +<H3><a name="Arguments_nn5">12.1.3 Output parameters</a></H3> <p> @@ -315,7 +315,7 @@ iresult, dresult = foo(3.5, 2) </pre> </div> -<H3><a name="Arguments_nn6">10.1.4 Input/Output parameters</a></H3> +<H3><a name="Arguments_nn6">12.1.4 Input/Output parameters</a></H3> <p> @@ -380,7 +380,7 @@ rather than directly overwriting the value of the original input object. SWIG. Backwards compatibility is preserved, but deprecated. </p> -<H3><a name="Arguments_nn7">10.1.5 Using different names</a></H3> +<H3><a name="Arguments_nn7">12.1.5 Using different names</a></H3> <p> @@ -414,7 +414,7 @@ Typemap declarations are lexically scoped so a typemap takes effect from the poi file or a matching <tt>%clear</tt> declaration. </p> -<H2><a name="Arguments_nn8">10.2 Applying constraints to input values</a></H2> +<H2><a name="Arguments_nn8">12.2 Applying constraints to input values</a></H2> <p> @@ -424,7 +424,7 @@ insure that a value is positive, or that a pointer is non-NULL. This can be accomplished including the <tt>constraints.i</tt> library file. </p> -<H3><a name="Arguments_nn9">10.2.1 Simple constraint example</a></H3> +<H3><a name="Arguments_nn9">12.2.1 Simple constraint example</a></H3> <p> @@ -450,7 +450,7 @@ the arguments violate the constraint condition, a scripting language exception will be raised. As a result, it is possible to catch bad values, prevent mysterious program crashes and so on.</p> -<H3><a name="Arguments_nn10">10.2.2 Constraint methods</a></H3> +<H3><a name="Arguments_nn10">12.2.2 Constraint methods</a></H3> <p> @@ -466,7 +466,7 @@ NONNULL Non-NULL pointer (pointers only). </pre></div> -<H3><a name="Arguments_nn11">10.2.3 Applying constraints to new datatypes</a></H3> +<H3><a name="Arguments_nn11">12.2.3 Applying constraints to new datatypes</a></H3> <p> diff --git a/Doc/Manual/CCache.html b/Doc/Manual/CCache.html index d23b0cb2f..edd435fa1 100644 --- a/Doc/Manual/CCache.html +++ b/Doc/Manual/CCache.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="CCache">17 Using SWIG with ccache - ccache-swig(1) manpage</a></H1> +<H1><a name="CCache">20 Using SWIG with ccache - ccache-swig(1) manpage</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -35,7 +35,7 @@ <p> -<H2><a name="CCache_nn2">17.1 NAME</a></H2> +<H2><a name="CCache_nn2">20.1 NAME</a></H2> <p> @@ -43,7 +43,7 @@ ccache-swig - a fast compiler cache <p> -<H2><a name="CCache_nn3">17.2 SYNOPSIS</a></H2> +<H2><a name="CCache_nn3">20.2 SYNOPSIS</a></H2> <p> @@ -53,7 +53,7 @@ ccache-swig <compiler> [COMPILER OPTIONS] <p> <compiler> [COMPILER OPTIONS] <p> -<H2><a name="CCache_nn4">17.3 DESCRIPTION</a></H2> +<H2><a name="CCache_nn4">20.3 DESCRIPTION</a></H2> <p> @@ -62,7 +62,7 @@ by caching previous compiles and detecting when the same compile is being done again. ccache-swig is ccache plus support for SWIG. ccache and ccache-swig are used interchangeably in this document. <p> -<H2><a name="CCache_nn5">17.4 OPTIONS SUMMARY</a></H2> +<H2><a name="CCache_nn5">20.4 OPTIONS SUMMARY</a></H2> <p> @@ -82,7 +82,7 @@ Here is a summary of the options to ccache-swig. </pre> <p> -<H2><a name="CCache_nn6">17.5 OPTIONS</a></H2> +<H2><a name="CCache_nn6">20.5 OPTIONS</a></H2> <p> @@ -124,7 +124,7 @@ rounded down to the nearest multiple of 16 kilobytes. <p> </dl> <p> -<H2><a name="CCache_nn7">17.6 INSTALLATION</a></H2> +<H2><a name="CCache_nn7">20.6 INSTALLATION</a></H2> <p> @@ -156,7 +156,7 @@ This will work as long as /usr/local/bin comes before the path to gcc Note! Do not use a hard link, use a symbolic link. A hardlink will cause "interesting" problems. <p> -<H2><a name="CCache_nn8">17.7 EXTRA OPTIONS</a></H2> +<H2><a name="CCache_nn8">20.7 EXTRA OPTIONS</a></H2> <p> @@ -176,7 +176,7 @@ file). By using --ccache-skip you can force an option to not be treated as an input file name and instead be passed along to the compiler as a command line option. <p> -<H2><a name="CCache_nn9">17.8 ENVIRONMENT VARIABLES</a></H2> +<H2><a name="CCache_nn9">20.8 ENVIRONMENT VARIABLES</a></H2> <p> @@ -315,7 +315,7 @@ the use of '#pragma SWIG'. <p> </dl> <p> -<H2><a name="CCache_nn10">17.9 CACHE SIZE MANAGEMENT</a></H2> +<H2><a name="CCache_nn10">20.9 CACHE SIZE MANAGEMENT</a></H2> <p> @@ -328,7 +328,7 @@ When these limits are reached ccache will reduce the cache to 20% below the numbers you specified in order to avoid doing the cache clean operation too often. <p> -<H2><a name="CCache_nn11">17.10 CACHE COMPRESSION</a></H2> +<H2><a name="CCache_nn11">20.10 CACHE COMPRESSION</a></H2> <p> @@ -339,7 +339,7 @@ performance slowdown, it significantly increases the number of files that fit in the cache. You can turn off compression setting the CCACHE_NOCOMPRESS environment variable. <p> -<H2><a name="CCache_nn12">17.11 HOW IT WORKS</a></H2> +<H2><a name="CCache_nn12">20.11 HOW IT WORKS</a></H2> <p> @@ -364,7 +364,7 @@ compiler output that you would get without the cache. If you ever discover a case where ccache changes the output of your compiler then please let me know. <p> -<H2><a name="CCache_nn13">17.12 USING CCACHE WITH DISTCC</a></H2> +<H2><a name="CCache_nn13">20.12 USING CCACHE WITH DISTCC</a></H2> <p> @@ -378,7 +378,7 @@ option. You just need to set the environment variable CCACHE_PREFIX to 'distcc' and ccache will prefix the command line used with the compiler with the command 'distcc'. <p> -<H2><a name="CCache_nn14">17.13 SHARING A CACHE</a></H2> +<H2><a name="CCache_nn14">20.13 SHARING A CACHE</a></H2> <p> @@ -407,11 +407,11 @@ following conditions need to be met: versions of ccache that do not support compression. </ul> <p> -<H2><a name="CCache_nn15">17.14 HISTORY</a></H2> +<H2><a name="CCache_nn15">20.14 HISTORY</a></H2> <p> -ccache was inspired by the compilercache shell script script written +ccache was inspired by the compilercache shell script written by Erik Thiele and I would like to thank him for an excellent piece of work. See <a href="http://www.erikyyy.de/compilercache/">http://www.erikyyy.de/compilercache/</a> @@ -423,7 +423,7 @@ I wrote ccache because I wanted to get a bit more speed out of a compiler cache and I wanted to remove some of the limitations of the shell-script version. <p> -<H2><a name="CCache_nn16">17.15 DIFFERENCES FROM COMPILERCACHE</a></H2> +<H2><a name="CCache_nn16">20.15 DIFFERENCES FROM COMPILERCACHE</a></H2> <p> @@ -441,7 +441,7 @@ are: <li> ccache avoids a double call to cpp on a cache miss </ul> <p> -<H2><a name="CCache_nn17">17.16 CREDITS</a></H2> +<H2><a name="CCache_nn17">20.16 CREDITS</a></H2> <p> @@ -453,12 +453,12 @@ Thanks to the following people for their contributions to ccache <li> Paul Russell for many suggestions and the debian packaging </ul> <p> -<H2><a name="CCache_nn18">17.17 AUTHOR</a></H2> +<H2><a name="CCache_nn18">20.17 AUTHOR</a></H2> <p> ccache was written by Andrew Tridgell -<a href="http://samba.org/~tridge/">http://samba.org/~tridge/</a>. +<a href="https://www.samba.org/~tridge/">https://www.samba.org/~tridge/</a>. ccache was adapted to create ccache-swig for use with SWIG by William Fulton. <p> If you wish to report a problem or make a suggestion then please email diff --git a/Doc/Manual/CPlusPlus11.html b/Doc/Manual/CPlusPlus11.html index 4d4261cd7..11335a251 100644 --- a/Doc/Manual/CPlusPlus11.html +++ b/Doc/Manual/CPlusPlus11.html @@ -32,6 +32,7 @@ <li><a href="#CPlusPlus11_alias_templates">Type alias and alias templates</a> <li><a href="#CPlusPlus11_unrestricted_unions">Unrestricted unions</a> <li><a href="#CPlusPlus11_variadic_templates">Variadic templates</a> +<li><a href="#CPlusPlus11_new_char_literals">New character literals</a> <li><a href="#CPlusPlus11_new_string_literals">New string literals</a> <li><a href="#CPlusPlus11_user_defined_literals">User-defined literals</a> <li><a href="#CPlusPlus11_thread_local_storage">Thread-local storage</a> @@ -42,6 +43,7 @@ <li><a href="#CPlusPlus11_noexcept">Exception specifications and noexcept</a> <li><a href="#CPlusPlus11_alignment">Control and query object alignment</a> <li><a href="#CPlusPlus11_attributes">Attributes</a> +<li><a href="#CPlusPlus11_ref_qualifiers">Methods with ref-qualifiers</a> </ul> <li><a href="#CPlusPlus11_standard_library_changes">Standard library changes</a> <ul> @@ -713,7 +715,24 @@ const int SIZE = sizeof...(ClassName<int, int>); In the above example <tt>SIZE</tt> is of course wrapped as a constant. </p> -<H3><a name="CPlusPlus11_new_string_literals">7.2.19 New string literals</a></H3> +<H3><a name="CPlusPlus11_new_char_literals">7.2.19 New character literals</a></H3> + + +<p> +C++11 adds support for UCS-2 and UCS-4 character literals. +These character literals are preceded by either 'u' or 'U'. +</p> + +<div class="code"><pre> +char16_t a = u'a'; +char32_t b = U'b'; +</pre></div> + +<p> +<b>Compatibility note:</b> SWIG-4.0.0 was the first version to support these Universal Coded Character Set (UCS) character literals. +</p> + +<H3><a name="CPlusPlus11_new_string_literals">7.2.20 New string literals</a></H3> <p>SWIG supports wide string and Unicode string constants and raw string literals.</p> @@ -743,7 +762,7 @@ Note: There is a bug currently where SWIG's preprocessor incorrectly parses an o inside raw string literals. </p> -<H3><a name="CPlusPlus11_user_defined_literals">7.2.20 User-defined literals</a></H3> +<H3><a name="CPlusPlus11_user_defined_literals">7.2.21 User-defined literals</a></H3> <p> @@ -810,7 +829,7 @@ OutputType var2 = 1234_suffix; OutputType var3 = 3.1416_suffix; </pre></div> -<H3><a name="CPlusPlus11_thread_local_storage">7.2.21 Thread-local storage</a></H3> +<H3><a name="CPlusPlus11_thread_local_storage">7.2.22 Thread-local storage</a></H3> <p>SWIG correctly parses the <tt>thread_local</tt> keyword. For example, variables @@ -830,7 +849,7 @@ A variable will be thread local if accessed from different threads from the targ same way that it will be thread local if accessed from C++ code. </p> -<H3><a name="CPlusPlus11_defaulted_deleted">7.2.22 Explicitly defaulted functions and deleted functions</a></H3> +<H3><a name="CPlusPlus11_defaulted_deleted">7.2.23 Explicitly defaulted functions and deleted functions</a></H3> <p>SWIG handles explicitly defaulted functions, that is, <tt>= default</tt> added to a function declaration. Deleted definitions, which are also called deleted functions, have <tt>= delete</tt> added to the function declaration. @@ -868,16 +887,17 @@ This is a C++ compile time check and SWIG does not make any attempt to detect if so in this case it is entirely possible to pass an int instead of a double to <tt>f</tt> from Java, Python etc. </p> -<H3><a name="CPlusPlus11_type_long_long_int">7.2.23 Type long long int</a></H3> +<H3><a name="CPlusPlus11_type_long_long_int">7.2.24 Type long long int</a></H3> <p>SWIG correctly parses and uses the new <tt>long long</tt> type already introduced in C99 some time ago.</p> -<H3><a name="CPlusPlus11_static_assertions">7.2.24 Static assertions</a></H3> +<H3><a name="CPlusPlus11_static_assertions">7.2.25 Static assertions</a></H3> <p> -SWIG correctly parses the new <tt>static_assert</tt> declarations. +SWIG correctly parses the new <tt>static_assert</tt> declarations (though 3.0.12 and earlier +had a bug which meant this wasn't accepted at file scope). This is a C++ compile time directive so there isn't anything useful that SWIG can do with it. </p> @@ -888,7 +908,7 @@ struct Check { }; </pre></div> -<H3><a name="CPlusPlus11_sizeof">7.2.25 Allow sizeof to work on members of classes without an explicit object</a></H3> +<H3><a name="CPlusPlus11_sizeof">7.2.26 Allow sizeof to work on members of classes without an explicit object</a></H3> <p> @@ -909,7 +929,7 @@ const int SIZE = sizeof(A::member); // does not work with C++03. Okay with C++11 8 </pre></div> -<H3><a name="CPlusPlus11_noexcept">7.2.26 Exception specifications and noexcept</a></H3> +<H3><a name="CPlusPlus11_noexcept">7.2.27 Exception specifications and noexcept</a></H3> <p> @@ -925,7 +945,7 @@ int noex2(int) noexcept(true); int noex3(int, bool) noexcept(false); </pre></div> -<H3><a name="CPlusPlus11_alignment">7.2.27 Control and query object alignment</a></H3> +<H3><a name="CPlusPlus11_alignment">7.2.28 Control and query object alignment</a></H3> <p> @@ -957,7 +977,7 @@ Use the preprocessor to work around this for now: </pre></div> -<H3><a name="CPlusPlus11_attributes">7.2.28 Attributes</a></H3> +<H3><a name="CPlusPlus11_attributes">7.2.29 Attributes</a></H3> <p> @@ -970,6 +990,104 @@ int [[attr1]] i [[attr2, attr3]]; [[noreturn, nothrow]] void f [[noreturn]] (); </pre></div> + +<H3><a name="CPlusPlus11_ref_qualifiers">7.2.30 Methods with ref-qualifiers</a></H3> + + +<p> +C++11 non-static member functions can be declared with ref-qualifiers. +Member functions declared with a <tt>&</tt> lvalue ref-qualifiers are wrapped like any other function without ref-qualifiers. +Member functions declared with a <tt>&&</tt> rvalue ref-qualifiers are ignored by default +as they are unlikely to be required from non-C++ languages where the concept of <i>rvalue-ness</i> +for the implied *this pointer does not apply. +The warning is hidden by default, but can be displayed as described in the section on <a href="Warnings.html#Warnings_nn4">Enabling extra warnings</a>. +</p> + +<p> +Consider: +</p> + +<div class="code"><pre> +struct RQ { + void m1(int x) &; + void m2(int x) &&; +}; +</pre></div> + +<p> +The only wrapped method will be the lvalue ref-qualified method <tt>m1</tt> +and if SWIG is run with the <tt>-Wextra</tt> command-line option, the following warning will be issued indicating <tt>m2</tt> is not wrapped: +</p> + +<div class="shell"> +<pre> +example.i:7: Warning 405: Method with rvalue ref-qualifier m2(int) && ignored. +</pre> +</div> + +<p> +If you unignore the method as follows, wrappers for <tt>m2</tt> will be generated: +</p> + +<div class="code"><pre> +%feature("ignore", "0") RQ::m2(int x) &&; +struct RQ { + void m1(int x) &; + void m2(int x) &&; +}; +</pre></div> + +<p> +Inspection of the generated C++ code, will show that <tt>std::move</tt> is used on the instance +of the <tt>RQ *</tt> class: +</p> + +<div class="code"><pre> + RQ *arg1 = (RQ *) 0 ; + int arg2 ; + + arg1 = ...marshalled from target language... + arg2 = ...marshalled from target language... + + std::move(*arg1).m2(arg2); +</pre></div> + +<p> +This will compile but when run, the move effects may not be what you want. +As stated earlier, rvalue ref-qualifiers aren't really applicable outside the world of C++. +However, if you really know what you are doing, full control over the call to the method is +possible via the low-level "action" feature. +This feature completely replaces the call to the underlying function, that is, the last line in the snippet of code above. +</p> + +<div class="code"><pre> +%feature("ignore", "0") RQ::m2(int x) &&; +%feature("action") RQ::m2(int x) && %{ + RQ().m2(arg2); +%} +struct RQ { + void m1(int x) &; + void m2(int x) &&; +}; +</pre></div> + +<p> +resulting in: +</p> + +<div class="code"><pre> + RQ *arg1 = (RQ *) 0 ; + int arg2 ; + + arg1 = ...marshalled from target language... + arg2 = ...marshalled from target language... + + RQ().m2(arg2); +</pre></div> + +<p> +<b>Compatibility note:</b> SWIG-4.0.0 was the first version to support ref-qualifiers. +</p> <H2><a name="CPlusPlus11_standard_library_changes">7.3 Standard library changes</a></H2> @@ -994,7 +1112,8 @@ Variadic template support requires further work to provide substantial tuple wra <p> The new hash tables in the STL are <tt>unordered_set</tt>, <tt>unordered_multiset</tt>, <tt>unordered_map</tt>, <tt>unordered_multimap</tt>. -These are not available in SWIG, but in principle should be easily implemented by adapting the current STL containers. +These are not available in all target languages. +Any missing support can in principle be easily implemented by adapting the current STL containers. </p> <H3><a name="CPlusPlus11_regular_expressions">7.3.4 Regular expressions</a></H3> @@ -1175,5 +1294,6 @@ Phew, that is a lot of hard work to get a callback working. You could just go with the more attractive option of just using <tt>double</tt> as the return type in the function declaration instead of <tt>result_of</tt>! </p> + </body> </html> diff --git a/Doc/Manual/CPlusPlus14.html b/Doc/Manual/CPlusPlus14.html new file mode 100644 index 000000000..b162c7818 --- /dev/null +++ b/Doc/Manual/CPlusPlus14.html @@ -0,0 +1,60 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<head> +<title>SWIG and C++14</title> +<link rel="stylesheet" type="text/css" href="style.css"> +<meta http-equiv="content-type" content="text/html; charset=UTF-8"> +</head> + +<body bgcolor="#ffffff"> +<H1><a name="CPlusPlus14">8 SWIG and C++14</a></H1> +<!-- INDEX --> +<div class="sectiontoc"> +<ul> +<li><a href="#CPlusPlus14_introduction">Introduction</a> +<li><a href="#CPlusPlus14_core_language_changes">Core language changes</a> +<ul> +<li><a href="#CPlusPlus14_binary_literals">Binary integer literals</a> +</ul> +<li><a href="#CPlusPlus14_standard_library_changes">Standard library changes</a> +</ul> +</div> +<!-- INDEX --> + + + +<H2><a name="CPlusPlus14_introduction">8.1 Introduction</a></H2> + + +<p>This chapter gives you a brief overview about the SWIG +implementation of the C++14 standard. +There isn't much in C++14 that affects SWIG, however, work has only just begun on adding +C++14 support. +</p> + +<p> +<b>Compatibility note:</b> SWIG-4.0.0 is the first version to support any C++14 features. +</p> + +<H2><a name="CPlusPlus14_core_language_changes">8.2 Core language changes</a></H2> + + +<H3><a name="CPlusPlus14_binary_literals">8.2.1 Binary integer literals</a></H3> + + +<p> +C++14 added binary integer literals and SWIG supports these. +Example: +</p> + +<div class="code"> +<pre> +int b = 0b101011; +</pre> +</div> + +<H2><a name="CPlusPlus14_standard_library_changes">8.3 Standard library changes</a></H2> + + +</body> +</html> diff --git a/Doc/Manual/CPlusPlus17.html b/Doc/Manual/CPlusPlus17.html new file mode 100644 index 000000000..a2346660a --- /dev/null +++ b/Doc/Manual/CPlusPlus17.html @@ -0,0 +1,109 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<head> +<title>SWIG and C++17</title> +<link rel="stylesheet" type="text/css" href="style.css"> +<meta http-equiv="content-type" content="text/html; charset=UTF-8"> +</head> + +<body bgcolor="#ffffff"> +<H1><a name="CPlusPlus17">9 SWIG and C++17</a></H1> +<!-- INDEX --> +<div class="sectiontoc"> +<ul> +<li><a href="#CPlusPlus17_introduction">Introduction</a> +<li><a href="#CPlusPlus17_core_language_changes">Core language changes</a> +<ul> +<li><a href="#CPlusPlus17_nested_namespaces">Nested namespace definitions</a> +<li><a href="#CPlusPlus17_u8_char_literals">UTF-8 character literals</a> +<li><a href="#CPlusPlus17_hexadecimal_floating_literals">Hexadecimal floating literals</a> +</ul> +<li><a href="#CPlusPlus17_standard_library_changes">Standard library changes</a> +</ul> +</div> +<!-- INDEX --> + + + +<H2><a name="CPlusPlus17_introduction">9.1 Introduction</a></H2> + + +<p>This chapter gives you a brief overview about the SWIG +implementation of the C++17 standard. +There isn't much in C++17 that affects SWIG, however, work has only just begun on adding +C++17 support. +</p> + +<p> +<b>Compatibility note:</b> SWIG-4.0.0 is the first version to support any C++17 features. +</p> + +<H2><a name="CPlusPlus17_core_language_changes">9.2 Core language changes</a></H2> + + +<H3><a name="CPlusPlus17_nested_namespaces">9.2.1 Nested namespace definitions</a></H3> + + +<p> +C++17 offers a more concise syntax for defining namespaces. +SWIG has support for nested namespace definitions such as: +</p> + +<div class="code"> +<pre> +namespace A::B::C { + ... +} +</pre> +</div> + +<p> +This is the equivalent to the C++98 namespace definitions: +</p> + +<div class="code"> +<pre> +namespace A { + namespace B { + namespace C { + ... + } + } +} +</pre> +</div> + +<H3><a name="CPlusPlus17_u8_char_literals">9.2.2 UTF-8 character literals</a></H3> + + +<p> +C++17 added UTF-8 (u8) character literals. +These are of type char. +Example: +</p> + +<div class="code"> +<pre> +char a = u8'a'; +</pre> +</div> + +<H3><a name="CPlusPlus17_hexadecimal_floating_literals">9.2.3 Hexadecimal floating literals</a></H3> + + +<p> +C++17 added hexadecimal floating literals. +For example: +</p> + +<div class="code"> +<pre> +double f = 0xF.68p2; +</pre> +</div> + +<H2><a name="CPlusPlus17_standard_library_changes">9.3 Standard library changes</a></H2> + + +</body> +</html> diff --git a/Doc/Manual/CSharp.html b/Doc/Manual/CSharp.html index 5be63a340..1fc2d211e 100644 --- a/Doc/Manual/CSharp.html +++ b/Doc/Manual/CSharp.html @@ -6,7 +6,7 @@ <meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head> <body bgcolor="#FFFFFF"> -<H1><a name="CSharp">20 SWIG and C#</a></H1> +<H1><a name="CSharp">22 SWIG and C#</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -44,7 +44,8 @@ <li><a href="#CSharp_date_marshalling">Date marshalling using the csin typemap and associated attributes</a> <li><a href="#CSharp_date_properties">A date example demonstrating marshalling of C# properties</a> <li><a href="#CSharp_date_pre_post_directors">Date example demonstrating the 'pre' and 'post' typemap attributes for directors</a> -<li><a href="#CSharp_partial_classes">Turning wrapped classes into partial classes</a> +<li><a href="#CSharp_partial_classes">Turning proxy classes into partial classes</a> +<li><a href="#CSharp_sealed_proxy_class">Turning proxy classes into sealed classes</a> <li><a href="#CSharp_extending_proxy_class">Extending proxy classes with additional C# code</a> <li><a href="#CSharp_enum_underlying_type">Underlying type for enums</a> </ul> @@ -54,7 +55,7 @@ -<H2><a name="CSharp_introduction">20.1 Introduction</a></H2> +<H2><a name="CSharp_introduction">22.1 Introduction</a></H2> <p> @@ -63,18 +64,18 @@ The wrapper code implementation uses C# and the Platform Invoke (PInvoke) interf The PInvoke interface has been chosen over Microsoft's Managed C++ interface as it is portable to both Microsoft Windows and non-Microsoft platforms. PInvoke is part of the ECMA/ISO C# specification. It is also better suited for robust production environments due to the Managed C++ flaw called the -<a href="http://msdn.microsoft.com/en-us/library/aa290048(VS.71).aspx">Mixed DLL Loading Problem</a>. +<a href="https://msdn.microsoft.com/en-us/ie/aa290048(v=vs.94)">Mixed DLL Loading Problem</a>. SWIG C# works equally well on non-Microsoft operating systems such as Linux, Solaris and Apple Mac using -<a href="http://www.mono-project.com/Main_Page">Mono</a> and <a href="http://www.dotgnu.org/pnet.html">Portable.NET</a>. +<a href="https://www.mono-project.com/Main_Page/">Mono</a> and <a href="http://www.dotgnu.org/pnet.html">Portable.NET</a>. </p> <p> To get the most out of this chapter an understanding of interop is required. -The <a href="http://msdn.microsoft.com">Microsoft Developer Network (MSDN)</a> has a good reference guide in a section titled "Interop Marshaling". -Monodoc, available from the Mono project, has a very useful section titled <a href="http://www.mono-project.com/docs/advanced/pinvoke/">Interop with native libraries</a>. +The <a href="https://msdn.microsoft.com">Microsoft Developer Network (MSDN)</a> has a good reference guide in a section titled "Interop Marshaling". +Monodoc, available from the Mono project, has a very useful section titled <a href="https://www.mono-project.com/docs/advanced/pinvoke/">Interop with native libraries</a>. </p> -<H3><a name="CSharp_introduction_swig2_compatibility">20.1.1 SWIG 2 Compatibility</a></H3> +<H3><a name="CSharp_introduction_swig2_compatibility">22.1.1 SWIG 2 Compatibility</a></H3> <p> @@ -82,7 +83,7 @@ In order to minimize name collisions between names generated based on input to S </p> -<H3><a name="CSharp_commandline">20.1.2 Additional command line options</a></H3> +<H3><a name="CSharp_commandline">22.1.2 Additional command line options</a></H3> <p> @@ -134,7 +135,7 @@ Note that the file extension (.cs) will not be automatically added and needs to Due to possible compiler limits it is not advisable to use <tt>-outfile</tt> for large projects. </p> -<H2><a name="CSharp_differences_java">20.2 Differences to the Java module</a></H2> +<H2><a name="CSharp_differences_java">22.2 Differences to the Java module</a></H2> <p> @@ -231,8 +232,8 @@ javacode -> cscode javaimports -> csimports javabody -> csbody javafinalize -> csfinalize -javadestruct -> csdestruct -javadestruct_derived -> csdestruct_derived +javadestruct -> csdisposing and csdispose +javadestruct_derived -> csdisposing_derived and csdispose_derived javainterfacecode -> csinterfacecode </pre></div> @@ -555,7 +556,7 @@ Windows users can also get the examples working using a <a href="http://www.cygwin.com">Cygwin</a> or <a href="http://www.mingw.org">MinGW</a> environment for automatic configuration of the example makefiles. Any one of the C# compilers (Mono or Microsoft) can be detected from within a Cygwin or Mingw environment if installed in your path. -<H2><a name="CSharp_void_pointers">20.3 Void pointers</a></H2> +<H2><a name="CSharp_void_pointers">22.3 Void pointers</a></H2> <p> @@ -573,7 +574,7 @@ void * f(void *v); </pre> </div> -<H2><a name="CSharp_arrays">20.4 C# Arrays</a></H2> +<H2><a name="CSharp_arrays">22.4 C# Arrays</a></H2> <p> @@ -585,7 +586,7 @@ with one of the following three approaches; namely the SWIG C arrays library, P/ pinned arrays. </p> -<H3><a name="CSharp_arrays_swig_library">20.4.1 The SWIG C arrays library</a></H3> +<H3><a name="CSharp_arrays_swig_library">22.4.1 The SWIG C arrays library</a></H3> <p> @@ -622,7 +623,7 @@ example.print_array(c.cast()); // Pass to C </div> -<H3><a name="CSharp_arrays_pinvoke_default_array_marshalling">20.4.2 Managed arrays using P/Invoke default array marshalling</a></H3> +<H3><a name="CSharp_arrays_pinvoke_default_array_marshalling">22.4.2 Managed arrays using P/Invoke default array marshalling</a></H3> <p> @@ -642,7 +643,7 @@ passing a direct reference as described in the next section. <p> For more information on the subject, see the -<a href="http://msdn.microsoft.com/en-us/library/z6cfh6e6(VS.80).aspx">Default Marshaling for Arrays</a> article +<a href="https://docs.microsoft.com/en-us/dotnet/framework/interop/default-marshaling-for-arrays">Default Marshaling for Arrays</a> article on MSDN. </p> @@ -677,7 +678,7 @@ As a result, we get the following method in the module class: <div class="code"> <pre> public static void myArrayCopy(int[] sourceArray, int[] targetArray, int nitems) { - examplePINVOKE.myArrayCopy(sourceArray, targetArray, nitems); + examplePINVOKE.myArrayCopy(sourceArray, targetArray, nitems); } </pre> </div> @@ -749,7 +750,7 @@ and intermediary class method </div> -<H3><a name="CSharp_arrays_pinning">20.4.3 Managed arrays using pinning</a></H3> +<H3><a name="CSharp_arrays_pinning">22.4.3 Managed arrays using pinning</a></H3> <p> @@ -762,7 +763,7 @@ another thread may produce enough garbage to trigger garbage collection. </p> <p> -For more information, see the <a href="http://msdn.microsoft.com/en-us/library/f58wzh21(VS.80).aspx">fixed statement</a> in the C# language reference. +For more information, see the <a href="https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/fixed-statement">fixed statement</a> in the C# language reference. </p> @@ -844,7 +845,7 @@ public static extern void myArrayCopy(global::System.IntPtr jarg1, global::Syste -<H2><a name="CSharp_exceptions">20.5 C# Exceptions</a></H2> +<H2><a name="CSharp_exceptions">22.5 C# Exceptions</a></H2> <p> @@ -941,7 +942,7 @@ set so should only be used when a C# exception is not created. </p> -<H3><a name="CSharp_exception_example_check_typemap">20.5.1 C# exception example using "check" typemap</a></H3> +<H3><a name="CSharp_exception_example_check_typemap">22.5.1 C# exception example using "check" typemap</a></H3> <p> @@ -997,9 +998,9 @@ When the following C# code is executed: <div class="code"> <pre> public class runme { - static void Main() { - example.positivesonly(-1); - } + static void Main() { + example.positivesonly(-1); + } } </pre> </div> @@ -1123,7 +1124,7 @@ method and C# code does not handle pending exceptions via the canthrow attribute Actually it will issue this warning for any function beginning with <tt>SWIG_CSharpSetPendingException</tt>. </P> -<H3><a name="CSharp_exception_example_percent_exception">20.5.2 C# exception example using %exception</a></H3> +<H3><a name="CSharp_exception_example_percent_exception">22.5.2 C# exception example using %exception</a></H3> <p> @@ -1188,7 +1189,7 @@ The managed code generated does check for the pending exception as mentioned ear </pre> </div> -<H3><a name="CSharp_exception_example_exception_specifications">20.5.3 C# exception example using exception specifications</a></H3> +<H3><a name="CSharp_exception_example_exception_specifications">22.5.3 C# exception example using exception specifications</a></H3> <p> @@ -1244,7 +1245,7 @@ SWIGEXPORT void SWIGSTDCALL CSharp_evensonly(int jarg1) { Multiple catch handlers are generated should there be more than one exception specifications declared. </p> -<H3><a name="CSharp_custom_application_exception">20.5.4 Custom C# ApplicationException example</a></H3> +<H3><a name="CSharp_custom_application_exception">22.5.4 Custom C# ApplicationException example</a></H3> <p> @@ -1378,7 +1379,7 @@ try { </pre> </div> -<H2><a name="CSharp_directors">20.6 C# Directors</a></H2> +<H2><a name="CSharp_directors">22.6 C# Directors</a></H2> <p> @@ -1391,7 +1392,7 @@ The following sections provide information on the C# director implementation and However, the <a href="Java.html#Java_directors">Java directors</a> section should also be read in order to gain more insight into directors. </p> -<H3><a name="CSharp_directors_example">20.6.1 Directors example</a></H3> +<H3><a name="CSharp_directors_example">22.6.1 Directors example</a></H3> <p> @@ -1512,7 +1513,7 @@ CSharpDerived - UIntMethod(123) </pre> </div> -<H3><a name="CSharp_directors_implementation">20.6.2 Directors implementation</a></H3> +<H3><a name="CSharp_directors_implementation">22.6.2 Directors implementation</a></H3> <p> @@ -1574,9 +1575,9 @@ public class Base : global::System.IDisposable { private void SwigDirectorConnect() { if (SwigDerivedClassHasMethod("UIntMethod", swigMethodTypes0)) - swigDelegate0 = new SwigDelegateBase_0(SwigDirectorUIntMethod); + swigDelegate0 = new SwigDelegateBase_0(SwigDirectorMethodUIntMethod); if (SwigDerivedClassHasMethod("BaseBoolMethod", swigMethodTypes1)) - swigDelegate1 = new SwigDelegateBase_1(SwigDirectorBaseBoolMethod); + swigDelegate1 = new SwigDelegateBase_1(SwigDirectorMethodBaseBoolMethod); examplePINVOKE.Base_director_connect(swigCPtr, swigDelegate0, swigDelegate1); } @@ -1586,11 +1587,11 @@ public class Base : global::System.IDisposable { return hasDerivedMethod; } - private uint SwigDirectorUIntMethod(uint x) { + private uint SwigDirectorMethodUIntMethod(uint x) { return UIntMethod(x); } - private void SwigDirectorBaseBoolMethod(global::System.IntPtr b, bool flag) { + private void SwigDirectorMethodBaseBoolMethod(global::System.IntPtr b, bool flag) { BaseBoolMethod(new Base(b, false), flag); } @@ -1619,9 +1620,9 @@ It uses a support method, <tt>SwigDerivedClassHasMethod()</tt>, which simply use BaseBoolMethod, with the list of required parameter types, exists in a subclass. If it does not exist, the delegate is not initialised as there is no need for unmanaged code to call back into managed C# code. However, if there is an overridden method in any subclass, the delegate is required. -It is then initialised to the <tt>SwigDirectorBaseBoolMethod</tt> which in turn will call <tt>BaseBoolMethod</tt> if invoked. +It is then initialised to the <tt>SwigDirectorMethodBaseBoolMethod</tt> which in turn will call <tt>BaseBoolMethod</tt> if invoked. The delegate is not initialised to the <tt>BaseBoolMethod</tt> directly as quite often types will need marshalling from the unmanaged type -to the managed type in which case an intermediary method (<tt>SwigDirectorBaseBoolMethod</tt>) is required for the marshalling. +to the managed type in which case an intermediary method (<tt>SwigDirectorMethodBaseBoolMethod</tt>) is required for the marshalling. In this case, the C# <tt>Base</tt> class needs to be created from the unmanaged <tt>IntPtr</tt> type. </p> @@ -1720,7 +1721,7 @@ before SWIG parses the Base class will change all the delegates to <tt>internal< </pre> </div> -<H3><a name="CSharp_director_caveats">20.6.3 Director caveats</a></H3> +<H3><a name="CSharp_director_caveats">22.6.3 Director caveats</a></H3> <p> @@ -1768,11 +1769,11 @@ However, a call from C# to <tt>CSharpDefaults.DefaultMethod()</tt> will of cours should pass the call on to <tt>CSharpDefaults.DefaultMethod(int)</tt>using the C++ default value, as shown above. </p> -<H2><a name="CSharp_multiple_modules">20.7 Multiple modules</a></H2> +<H2><a name="CSharp_multiple_modules">22.7 Multiple modules</a></H2> <p> -When using <a href="Modules.html#Modules">multiple modules</a> it is is possible to compile each SWIG generated wrapper +When using <a href="Modules.html#Modules">multiple modules</a> it is possible to compile each SWIG generated wrapper into a different assembly. However, by default the generated code may not compile if generated classes in one assembly use generated classes in another assembly. @@ -1803,7 +1804,7 @@ the <tt>[System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrows if you don't want users to easily stumble upon these so called 'internal workings' of the wrappers. </p> -<H2><a name="CSharp_typemap_examples">20.8 C# Typemap examples</a></H2> +<H2><a name="CSharp_typemap_examples">22.8 C# Typemap examples</a></H2> This section includes a few examples of typemaps. For more examples, you @@ -1811,7 +1812,7 @@ might look at the files "<tt>csharp.swg</tt>" and "<tt>typemaps.i</tt>" in the SWIG library. -<H3><a name="CSharp_memory_management_member_variables">20.8.1 Memory management when returning references to member variables</a></H3> +<H3><a name="CSharp_memory_management_member_variables">22.8.1 Memory management when returning references to member variables</a></H3> <p> @@ -1827,7 +1828,7 @@ Consider the following C++ code: <pre> struct Wheel { int size; - Wheel(int sz) : size(sz) {} + Wheel(int sz = 0) : size(sz) {} }; class Bike { @@ -1846,12 +1847,12 @@ and the following usage from C# after running the code through SWIG: <div class="code"> <pre> - Wheel wheel = new Bike(10).getWheel(); - Console.WriteLine("wheel size: " + wheel.size); - // Simulate a garbage collection - global::System.GC.Collect(); - global::System.GC.WaitForPendingFinalizers(); - global::System.Console.WriteLine("wheel size: " + wheel.size); + Wheel wheel = new Bike(10).getWheel(); + Console.WriteLine("wheel size: " + wheel.size); + // Simulate a garbage collection + global::System.GC.Collect(); + global::System.GC.WaitForPendingFinalizers(); + global::System.Console.WriteLine("wheel size: " + wheel.size); </pre> </div> @@ -1935,7 +1936,7 @@ public class Bike : global::System.IDisposable { Note the <tt>addReference</tt> call. </p> -<H3><a name="CSharp_memory_management_objects">20.8.2 Memory management for objects passed to the C++ layer</a></H3> +<H3><a name="CSharp_memory_management_objects">22.8.2 Memory management for objects passed to the C++ layer</a></H3> <p> @@ -1980,27 +1981,27 @@ and more or less equivalent usage from C# <div class="code"> <pre> - Container container = new Container(); - Element element = new Element(20); - container.setElement(element); + Container container = new Container(); + Element element = new Element(20); + container.setElement(element); </pre> </div> <p> The C++ code will always print out 20, but the value printed out may not be this in the C# equivalent code. -In order to understand why, consider a garbage collection occuring... +In order to understand why, consider a garbage collection occurring... </p> <div class="code"> <pre> - Container container = new Container(); - Element element = new Element(20); - container.setElement(element); - Console.WriteLine("element.value: " + container.getElement().value); - // Simulate a garbage collection - global::System.GC.Collect(); - global::System.GC.WaitForPendingFinalizers(); - global::System.Console.WriteLine("element.value: " + container.getElement().value); + Container container = new Container(); + Element element = new Element(20); + container.setElement(element); + Console.WriteLine("element.value: " + container.getElement().value); + // Simulate a garbage collection + global::System.GC.Collect(); + global::System.GC.WaitForPendingFinalizers(); + global::System.Console.WriteLine("element.value: " + container.getElement().value); </pre> </div> @@ -2019,42 +2020,55 @@ public class Container : global::System.IDisposable { // Ensure that the GC doesn't collect any Element set from C# // as the underlying C++ class stores a shallow copy private Element elementReference; - private global::System.Runtime.InteropServices.HandleRef getCPtrAndAddReference(Element element) { - elementReference = element; - return Element.getCPtr(element); - } public void setElement(Element e) { - examplePINVOKE.Container_setElement(swigCPtr, getCPtrAndAddReference(e)); + examplePINVOKE.Container_setElement(swigCPtr, Element.getCPtr(e)); + elementReference = e; } } </pre> </div> <p> -The following typemaps will generate the desired code. -The 'csin' typemap matches the input parameter type for the <tt>setElement</tt> method. -The 'cscode' typemap simply adds in the specified code into the C# proxy class. +The following typemaps can be used to generate this code: </p> <div class="code"> <pre> -%typemap(csin) Element *e "getCPtrAndAddReference($csinput)" - %typemap(cscode) Container %{ // Ensure that the GC doesn't collect any Element set from C# // as the underlying C++ class stores a shallow copy private Element elementReference; - private global::System.Runtime.InteropServices.HandleRef getCPtrAndAddReference(Element element) { - elementReference = element; - return Element.getCPtr(element); - } %} + +%typemap(csin, + post=" elementReference = $csinput;" + ) Element *e "Element.getCPtr($csinput)" </pre> </div> +<p> +The 'cscode' typemap simply adds in the specified code into the C# proxy class. +The 'csin' typemap matches the input parameter type and name for the <tt>setElement</tt> method and +the 'post' typemap attribute allows adding code after the PInvoke call. +The 'post' code is generated into a finally block after the PInvoke call so the resulting code isn't quite +as mentioned earlier, <tt>setElement</tt> is actually: +</p> + +<div class="code"> +<pre> + public void setElement(Element e) { + try { + examplePINVOKE.Container_setElement(swigCPtr, Element.getCPtr(e)); + } finally { + elementReference = e; + } + } +</pre> +</div> -<H3><a name="CSharp_date_marshalling">20.8.3 Date marshalling using the csin typemap and associated attributes</a></H3> + +<H3><a name="CSharp_date_marshalling">22.8.3 Date marshalling using the csin typemap and associated attributes</a></H3> <p> @@ -2127,7 +2141,7 @@ The <tt>CDate &</tt> and <tt>const CDate &</tt> C# code is generated fro <p> where '$csclassname' is translated into the proxy class name, <tt>CDate</tt> and '$csinput' is translated into the name of the parameter, eg <tt>dateIn</tt>. -From C#, the intention is then to call into a modifed API with something like: +From C#, the intention is then to call into a modified API with something like: </p> <div class="code"> @@ -2340,7 +2354,7 @@ public class example { </pre> </div> -<H3><a name="CSharp_date_properties">20.8.4 A date example demonstrating marshalling of C# properties</a></H3> +<H3><a name="CSharp_date_properties">22.8.4 A date example demonstrating marshalling of C# properties</a></H3> <p> @@ -2440,7 +2454,7 @@ Some points to note: <li>The 'csin' typemap has 'pre', 'post' and 'cshin' attributes, and these are all ignored in the property set. The code in these attributes must instead be replicated within the 'csvarin' typemap. The line creating the <tt>temp$csinput</tt> variable is such an example; it is identical to what is in the 'pre' attribute. </ul> -<H3><a name="CSharp_date_pre_post_directors">20.8.5 Date example demonstrating the 'pre' and 'post' typemap attributes for directors</a></H3> +<H3><a name="CSharp_date_pre_post_directors">22.8.5 Date example demonstrating the 'pre' and 'post' typemap attributes for directors</a></H3> <p> @@ -2483,7 +2497,7 @@ The generated proxy class code will then contain the following wrapper for calli <div class="code"><pre> ... - private void SwigDirectorsomeCallback(global::System.IntPtr date) { + private void SwigDirectorMethodsomeCallback(global::System.IntPtr date) { System.DateTime tempdate = new System.DateTime(); try { someCallback(out tempdate); @@ -2502,7 +2516,7 @@ Pay special attention to the memory management issues, using these attributes. </p> -<H3><a name="CSharp_partial_classes">20.8.6 Turning wrapped classes into partial classes</a></H3> +<H3><a name="CSharp_partial_classes">22.8.6 Turning proxy classes into partial classes</a></H3> <p> @@ -2602,7 +2616,97 @@ demonstrating that the class contains methods calling both unmanaged code - <tt> The following example is an alternative approach to adding managed code to the generated proxy class. </p> -<H3><a name="CSharp_extending_proxy_class">20.8.7 Extending proxy classes with additional C# code</a></H3> +<H3><a name="CSharp_sealed_proxy_class">22.8.7 Turning proxy classes into sealed classes</a></H3> + + +<p> +The technique in the previous section can be used to make the proxy class a sealed class. +Consider a C++ class <tt>NotABaseClass</tt> that you don't want to be derived from in C#: +</p> + +<div class="code"> +<pre> +struct NotABaseClass { + NotABaseClass(); + ~NotABaseClass(); +}; +</pre> +</div> + +<p> +The default C# proxy class method generated with Dispose method is: +</p> + +<div class="code"> +<pre> +public class NotABaseClass : global::System.IDisposable { + ... + public virtual void Dispose() { + ... + } +} +</pre> +</div> + +<p> +The <tt>csclassmodifiers</tt> typemap can be used to modify the class modifiers and +the <tt>csmethodmodifiers</tt> feature can be used on the destructor to modify the proxy's <tt>Dispose</tt> method: +</p> + +<div class="code"> +<pre> +%typemap(csclassmodifiers) NotABaseClass "public sealed class" +%csmethodmodifiers NotABaseClass::~NotABaseClass "public /*virtual*/"; +</pre> +</div> + +<p> +The relevant generated code is thus: +</p> + +<div class="code"> +<pre> +public sealed class NotABaseClass : global::System.IDisposable { + ... + public /*virtual*/ void Dispose() { + ... + } +} +</pre> +</div> + +<p> +Any attempt to derive from the <tt>NotABaseClass</tt> in C# will result in a C# compiler error, for example: +</p> + +<div class="code"> +<pre> +public class Derived : NotABaseClass { +}; +</pre> +</div> +<div class="shell"> +<pre> +runme.cs(6,14): error CS0509: `Derived': cannot derive from sealed type `NotABaseClass' +</pre> +</div> + +<p> +Finally, if you get a warning about use of 'protected' in the generated base class: +</p> + +<div class="shell"> +<pre> +NotABaseClass.cs(14,18): warning CS0628: `NotABaseClass.swigCMemOwn': new protected member declared in sealed class +</pre> +</div> + +<p> +Either suppress the warning or modify the generated code by copying and tweaking the default +'csbody' typemap code in csharp.swg by modifying swigCMemOwn to not be protected. +</p> + +<H3><a name="CSharp_extending_proxy_class">22.8.8 Extending proxy classes with additional C# code</a></H3> <p> @@ -2641,13 +2745,13 @@ public class ExtendMe : global::System.IDisposable { </pre> </div> -<H3><a name="CSharp_enum_underlying_type">20.8.8 Underlying type for enums</a></H3> +<H3><a name="CSharp_enum_underlying_type">22.8.9 Underlying type for enums</a></H3> <P> C# enums use int as the underlying type for each enum item. If you wish to change the underlying type to something else, then use the <tt>csbase</tt> typemap. -For example when your C++ code uses a value larget than int, this is necessary as the C# compiler will not compile values which are too large to fit into an int. +For example when your C++ code uses a value larger than int, this is necessary as the C# compiler will not compile values which are too large to fit into an int. Here is an example: </p> diff --git a/Doc/Manual/Chicken.html b/Doc/Manual/Chicken.html index b2f434a88..3a80811bd 100644 --- a/Doc/Manual/Chicken.html +++ b/Doc/Manual/Chicken.html @@ -8,7 +8,7 @@ <body bgcolor="#ffffff"> -<H1><a name="Chicken">21 SWIG and Chicken</a></H1> +<H1><a name="Chicken">23 SWIG and Chicken</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -72,7 +72,7 @@ </p> -<H2><a name="Chicken_nn2">21.1 Preliminaries</a></H2> +<H2><a name="Chicken_nn2">23.1 Preliminaries</a></H2> <p> @@ -89,7 +89,7 @@ directory for the basic steps to run SWIG CHICKEN. </p> -<H3><a name="Chicken_nn3">21.1.1 Running SWIG in C mode</a></H3> +<H3><a name="Chicken_nn3">23.1.1 Running SWIG in C mode</a></H3> <p> @@ -122,7 +122,7 @@ object files and linked into your project. </p> -<H3><a name="Chicken_nn4">21.1.2 Running SWIG in C++ mode</a></H3> +<H3><a name="Chicken_nn4">23.1.2 Running SWIG in C++ mode</a></H3> <p> @@ -151,10 +151,10 @@ object files and linked into your project. </p> -<H2><a name="Chicken_nn5">21.2 Code Generation</a></H2> +<H2><a name="Chicken_nn5">23.2 Code Generation</a></H2> -<H3><a name="Chicken_nn6">21.2.1 Naming Conventions</a></H3> +<H3><a name="Chicken_nn6">23.2.1 Naming Conventions</a></H3> <p> @@ -170,7 +170,7 @@ <tt>%rename</tt> SWIG directive in the SWIG interface file. </p> -<H3><a name="Chicken_nn7">21.2.2 Modules</a></H3> +<H3><a name="Chicken_nn7">23.2.2 Modules</a></H3> <p> @@ -192,7 +192,7 @@ (uses <i>modulename</i>))</code> CHICKEN Scheme form. </p> -<H3><a name="Chicken_nn8">21.2.3 Constants and Variables</a></H3> +<H3><a name="Chicken_nn8">23.2.3 Constants and Variables</a></H3> <p> @@ -229,7 +229,7 @@ for info on how to apply the %feature. </p> -<H3><a name="Chicken_nn9">21.2.4 Functions</a></H3> +<H3><a name="Chicken_nn9">23.2.4 Functions</a></H3> <p> @@ -248,7 +248,7 @@ parameters). The return values can then be accessed with <code>(call-with-values)</code>. </p> -<H3><a name="Chicken_nn10">21.2.5 Exceptions</a></H3> +<H3><a name="Chicken_nn10">23.2.5 Exceptions</a></H3> <p>The SWIG chicken module has support for exceptions thrown from @@ -290,7 +290,7 @@ </pre></div> -<H2><a name="Chicken_nn11">21.3 TinyCLOS</a></H2> +<H2><a name="Chicken_nn11">23.3 TinyCLOS</a></H2> <p> @@ -333,7 +333,7 @@ </p> -<H2><a name="Chicken_nn12">21.4 Linkage</a></H2> +<H2><a name="Chicken_nn12">23.4 Linkage</a></H2> <p> @@ -354,7 +354,7 @@ </p> -<H3><a name="Chicken_nn13">21.4.1 Static binary or shared library linked at compile time</a></H3> +<H3><a name="Chicken_nn13">23.4.1 Static binary or shared library linked at compile time</a></H3> <p>We can easily use csc to build a static binary.</p> @@ -395,7 +395,7 @@ in which case the test script does not need to be linked with example.so. The t be run with <tt>csi</tt>. </p> -<H3><a name="Chicken_nn14">21.4.2 Building chicken extension libraries</a></H3> +<H3><a name="Chicken_nn14">23.4.2 Building chicken extension libraries</a></H3> <p>Building a shared library like in the above section only works if the library @@ -453,7 +453,7 @@ distributed and used by anyone, even if SWIG is not installed.</p> <p>See the <tt>Examples/chicken/egg</tt> directory in the SWIG source for an example that builds two eggs, one using the first method and one using the second method.</p> -<H3><a name="Chicken_nn15">21.4.3 Linking multiple SWIG modules with TinyCLOS</a></H3> +<H3><a name="Chicken_nn15">23.4.3 Linking multiple SWIG modules with TinyCLOS</a></H3> <p>Linking together multiple modules that share type information using the <code>%import</code> @@ -477,7 +477,7 @@ with <code>(declare (uses ...))</code>. To create an extension library or an egg, just create a <tt>module_load.scm</tt> file that <code>(declare (uses ...))</code> all the modules.</p> -<H2><a name="Chicken_nn16">21.5 Typemaps</a></H2> +<H2><a name="Chicken_nn16">23.5 Typemaps</a></H2> <p> @@ -486,7 +486,7 @@ all the modules.</p> <code>Lib/chicken/chicken.swg</code>. </p> -<H2><a name="Chicken_nn17">21.6 Pointers</a></H2> +<H2><a name="Chicken_nn17">23.6 Pointers</a></H2> <p> @@ -519,7 +519,7 @@ all the modules.</p> type. flags is either zero or SWIG_POINTER_DISOWN (see below). </p> -<H3><a name="Chicken_collection">21.6.1 Garbage collection</a></H3> +<H3><a name="Chicken_collection">23.6.1 Garbage collection</a></H3> <p>If the owner flag passed to <code>SWIG_NewPointerObj</code> is 1, <code>NewPointerObj</code> will add a @@ -550,7 +550,7 @@ all the modules.</p> must be called manually. </p> -<H2><a name="Chicken_nn18">21.7 Unsupported features and known problems</a></H2> +<H2><a name="Chicken_nn18">23.7 Unsupported features and known problems</a></H2> <ul> @@ -560,7 +560,7 @@ all the modules.</p> <a href="SWIGPlus.html#SWIGPlus_default_args">%feature(compactdefaultargs)</a>.</li> </ul> -<H3><a name="Chicken_nn19">21.7.1 TinyCLOS problems with Chicken version <= 1.92</a></H3> +<H3><a name="Chicken_nn19">23.7.1 TinyCLOS problems with Chicken version <= 1.92</a></H3> <p>In Chicken versions equal to or below 1.92, TinyCLOS has a limitation such that generic methods do not properly work on methods diff --git a/Doc/Manual/Contents.html b/Doc/Manual/Contents.html index f196da53c..57aef5b8a 100644 --- a/Doc/Manual/Contents.html +++ b/Doc/Manual/Contents.html @@ -46,6 +46,11 @@ <ul> <li><a href="Introduction.html#Introduction_nn2">What is SWIG?</a> <li><a href="Introduction.html#Introduction_nn3">Why use SWIG?</a> +<li><a href="Introduction.html#Introduction_target_languages">Target languages</a> +<ul> +<li><a href="Introduction.html#Introduction_supported_status">Supported status</a> +<li><a href="Introduction.html#Introduction_experimental_status">Experimental status</a> +</ul> <li><a href="Introduction.html#Introduction_nn4">A SWIG example</a> <ul> <li><a href="Introduction.html#Introduction_nn5">SWIG interface file</a> @@ -228,7 +233,6 @@ <li><a href="SWIGPlus.html#SWIGPlus_nn12">Static members</a> <li><a href="SWIGPlus.html#SWIGPlus_member_data">Member data</a> </ul> -<li><a href="SWIGPlus.html#SWIGPlus_default_args">Default arguments</a> <li><a href="SWIGPlus.html#SWIGPlus_nn15">Protection</a> <li><a href="SWIGPlus.html#SWIGPlus_nn16">Enums and constants</a> <li><a href="SWIGPlus.html#SWIGPlus_nn17">Friends</a> @@ -236,16 +240,27 @@ <li><a href="SWIGPlus.html#SWIGPlus_nn19">Pass and return by value</a> <li><a href="SWIGPlus.html#SWIGPlus_nn20">Inheritance</a> <li><a href="SWIGPlus.html#SWIGPlus_nn21">A brief discussion of multiple inheritance, pointers, and type checking</a> -<li><a href="SWIGPlus.html#SWIGPlus_overloaded_methods">Wrapping Overloaded Functions and Methods</a> +<li><a href="SWIGPlus.html#SWIGPlus_default_args">Default arguments</a> +<li><a href="SWIGPlus.html#SWIGPlus_overloaded_methods">Overloaded functions and methods</a> <ul> <li><a href="SWIGPlus.html#SWIGPlus_nn24">Dispatch function generation</a> -<li><a href="SWIGPlus.html#SWIGPlus_nn25">Ambiguity in Overloading</a> -<li><a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn25">Ambiguity in overloading</a> +<li><a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a> <li><a href="SWIGPlus.html#SWIGPlus_nn27">Comments on overloading</a> </ul> -<li><a href="SWIGPlus.html#SWIGPlus_nn28">Wrapping overloaded operators</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn28">Overloaded operators</a> <li><a href="SWIGPlus.html#SWIGPlus_class_extension">Class extension</a> <li><a href="SWIGPlus.html#SWIGPlus_nn30">Templates</a> +<ul> +<li><a href="SWIGPlus.html#SWIGPlus_template_directive">The %template directive</a> +<li><a href="SWIGPlus.html#SWIGPlus_template_functions">Function templates</a> +<li><a href="SWIGPlus.html#SWIGPlus_template_classes">Default template arguments</a> +<li><a href="SWIGPlus.html#SWIGPlus_template_class_inheritance">Template base classes</a> +<li><a href="SWIGPlus.html#SWIGPlus_template_specialization">Template specialization</a> +<li><a href="SWIGPlus.html#SWIGPlus_template_member">Member templates</a> +<li><a href="SWIGPlus.html#SWIGPlus_template_scoping">Scoping and templates</a> +<li><a href="SWIGPlus.html#SWIGPlus_template_more">More on templates</a> +</ul> <li><a href="SWIGPlus.html#SWIGPlus_namespaces">Namespaces</a> <ul> <li><a href="SWIGPlus.html#SWIGPlus_nspace">The nspace feature for namespaces</a> @@ -259,6 +274,11 @@ <li><a href="SWIGPlus.html#SWIGPlus_nn35">Using declarations and inheritance</a> <li><a href="SWIGPlus.html#SWIGPlus_nested_classes">Nested classes</a> <li><a href="SWIGPlus.html#SWIGPlus_const">A brief rant about const-correctness</a> +<li><a href="SWIGPlus.html#SWIGPlus_target_language_callbacks">Callbacks to the target language</a> +<ul> +<li><a href="SWIGPlus.html#SWIGPlus_director_classes_introduction">Introduction to director classes</a> +<li><a href="SWIGPlus.html#SWIGPlus_directors_for_function_pointers">Using directors and target language callbacks</a> +</ul> <li><a href="SWIGPlus.html#SWIGPlus_nn42">Where to go for more information</a> </ul> </div> @@ -290,6 +310,7 @@ <li><a href="CPlusPlus11.html#CPlusPlus11_alias_templates">Type alias and alias templates</a> <li><a href="CPlusPlus11.html#CPlusPlus11_unrestricted_unions">Unrestricted unions</a> <li><a href="CPlusPlus11.html#CPlusPlus11_variadic_templates">Variadic templates</a> +<li><a href="CPlusPlus11.html#CPlusPlus11_new_char_literals">New character literals</a> <li><a href="CPlusPlus11.html#CPlusPlus11_new_string_literals">New string literals</a> <li><a href="CPlusPlus11.html#CPlusPlus11_user_defined_literals">User-defined literals</a> <li><a href="CPlusPlus11.html#CPlusPlus11_thread_local_storage">Thread-local storage</a> @@ -300,6 +321,7 @@ <li><a href="CPlusPlus11.html#CPlusPlus11_noexcept">Exception specifications and noexcept</a> <li><a href="CPlusPlus11.html#CPlusPlus11_alignment">Control and query object alignment</a> <li><a href="CPlusPlus11.html#CPlusPlus11_attributes">Attributes</a> +<li><a href="CPlusPlus11.html#CPlusPlus11_ref_qualifiers">Methods with ref-qualifiers</a> </ul> <li><a href="CPlusPlus11.html#CPlusPlus11_standard_library_changes">Standard library changes</a> <ul> @@ -318,7 +340,39 @@ </div> <!-- INDEX --> -<h3><a href="Preprocessor.html#Preprocessor">8 Preprocessing</a></h3> +<h3><a href="CPlusPlus14.html#CPlusPlus14">8 SWIG and C++14</a></h3> + +<!-- INDEX --> +<div class="sectiontoc"> +<ul> +<li><a href="CPlusPlus14.html#CPlusPlus14_introduction">Introduction</a> +<li><a href="CPlusPlus14.html#CPlusPlus14_core_language_changes">Core language changes</a> +<ul> +<li><a href="CPlusPlus14.html#CPlusPlus14_binary_literals">Binary integer literals</a> +</ul> +<li><a href="CPlusPlus14.html#CPlusPlus14_standard_library_changes">Standard library changes</a> +</ul> +</div> +<!-- INDEX --> + +<h3><a href="CPlusPlus17.html#CPlusPlus17">9 SWIG and C++17</a></h3> + +<!-- INDEX --> +<div class="sectiontoc"> +<ul> +<li><a href="CPlusPlus17.html#CPlusPlus17_introduction">Introduction</a> +<li><a href="CPlusPlus17.html#CPlusPlus17_core_language_changes">Core language changes</a> +<ul> +<li><a href="CPlusPlus17.html#CPlusPlus17_nested_namespaces">Nested namespace definitions</a> +<li><a href="CPlusPlus17.html#CPlusPlus17_u8_char_literals">UTF-8 character literals</a> +<li><a href="CPlusPlus17.html#CPlusPlus17_hexadecimal_floating_literals">Hexadecimal floating literals</a> +</ul> +<li><a href="CPlusPlus17.html#CPlusPlus17_standard_library_changes">Standard library changes</a> +</ul> +</div> +<!-- INDEX --> + +<h3><a href="Preprocessor.html#Preprocessor">10 Preprocessing</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -341,32 +395,39 @@ </div> <!-- INDEX --> -<h3><a href="Library.html#Library">9 SWIG library</a></h3> +<h3><a href="Library.html#Library">11 SWIG library</a></h3> <!-- INDEX --> <div class="sectiontoc"> <ul> <li><a href="Library.html#Library_nn2">The %include directive and library search path</a> -<li><a href="Library.html#Library_nn3">C Arrays and Pointers</a> +<li><a href="Library.html#Library_nn3">C arrays and pointers</a> <ul> <li><a href="Library.html#Library_nn4">cpointer.i</a> <li><a href="Library.html#Library_carrays">carrays.i</a> <li><a href="Library.html#Library_nn6">cmalloc.i</a> <li><a href="Library.html#Library_nn7">cdata.i</a> </ul> -<li><a href="Library.html#Library_nn8">C String Handling</a> +<li><a href="Library.html#Library_nn8">C string handling</a> <ul> <li><a href="Library.html#Library_nn9">Default string handling</a> <li><a href="Library.html#Library_nn10">Passing binary data</a> <li><a href="Library.html#Library_nn11">Using %newobject to release memory</a> <li><a href="Library.html#Library_nn12">cstring.i</a> </ul> -<li><a href="Library.html#Library_stl_cpp_library">STL/C++ Library</a> +<li><a href="Library.html#Library_stl_cpp_library">STL/C++ library</a> <ul> <li><a href="Library.html#Library_std_string">std::string</a> <li><a href="Library.html#Library_std_vector">std::vector</a> <li><a href="Library.html#Library_stl_exceptions">STL exceptions</a> <li><a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a> +<ul> +<li><a href="Library.html#Library_shared_ptr_basics">shared_ptr basics</a> +<li><a href="Library.html#Library_shared_ptr_inheritance">shared_ptr and inheritance</a> +<li><a href="Library.html#Library_shared_ptr_overloading">shared_ptr and method overloading</a> +<li><a href="Library.html#Library_shared_ptr_templates">shared_ptr and templates</a> +<li><a href="Library.html#Library_shared_ptr_directors">shared_ptr and directors</a> +</ul> <li><a href="Library.html#Library_std_auto_ptr">auto_ptr smart pointer</a> </ul> <li><a href="Library.html#Library_nn16">Utility Libraries</a> @@ -377,7 +438,7 @@ </div> <!-- INDEX --> -<h3><a href="Arguments.html#Arguments">10 Argument Handling</a></h3> +<h3><a href="Arguments.html#Arguments">12 Argument Handling</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -400,7 +461,7 @@ </div> <!-- INDEX --> -<h3><a href="Typemaps.html#Typemaps">11 Typemaps</a></h3> +<h3><a href="Typemaps.html#Typemaps">13 Typemaps</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -461,7 +522,7 @@ <li><a href="Typemaps.html#Typemaps_nn35">"memberin" typemap</a> <li><a href="Typemaps.html#Typemaps_nn36">"varin" typemap</a> <li><a href="Typemaps.html#Typemaps_nn37">"varout" typemap</a> -<li><a href="Typemaps.html#throws_typemap">"throws" typemap</a> +<li><a href="Typemaps.html#Typemaps_throws_typemap">"throws" typemap</a> </ul> <li><a href="Typemaps.html#Typemaps_nn39">Some typemap examples</a> <ul> @@ -483,6 +544,9 @@ <li><a href="Typemaps.html#Typemaps_runtime_type_checker_usage">Usage</a> </ul> <li><a href="Typemaps.html#Typemaps_overloading">Typemaps and overloading</a> +<ul> +<li><a href="Typemaps.html#Typemaps_typecheck_pointer">SWIG_TYPECHECK_POINTER precedence level and the typecheck typemap</a> +</ul> <li><a href="Typemaps.html#Typemaps_nn48">More about %apply and %clear</a> <li><a href="Typemaps.html#Typemaps_nn47">Passing data between typemaps</a> <li><a href="Typemaps.html#Typemaps_nn52">C++ "this" pointer</a> @@ -491,7 +555,7 @@ </div> <!-- INDEX --> -<h3><a href="Customization.html#Customization">12 Customization Features</a></h3> +<h3><a href="Customization.html#Customization">14 Customization Features</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -519,7 +583,7 @@ </div> <!-- INDEX --> -<h3><a href="Contract.html#Contract">13 Contracts</a></h3> +<h3><a href="Contract.html#Contract">15 Contracts</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -532,7 +596,7 @@ </div> <!-- INDEX --> -<h3><a href="Varargs.html#Varargs">14 Variable Length Arguments</a></h3> +<h3><a href="Varargs.html#Varargs">16 Variable Length Arguments</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -550,7 +614,55 @@ </div> <!-- INDEX --> -<h3><a href="Warnings.html#Warnings">15 Warning Messages</a></h3> +<h3><a href="Doxygen.html#Doxygen">17 SWIG and Doxygen Translation</a></h3> + +<!-- INDEX --> +<div class="sectiontoc"> +<ul> +<li><a href="Doxygen.html#Doxygen_translation_overview">Doxygen translation overview</a> +<li><a href="Doxygen.html#Doxygen_file_preparation">Preparations</a> +<ul> +<li><a href="Doxygen.html#Doxygen_running_swig">Enabling Doxygen translation</a> +<li><a href="Doxygen.html#Doxygen_features">Doxygen-specific %feature directives</a> +<ul> +<li><a href="Doxygen.html#Doxygen_notranslate">doxygen:notranslate</a> +<li><a href="Doxygen.html#Doxygen_alias">doxygen:alias:<command-name></a> +<li><a href="Doxygen.html#Doxygen_ignore">doxygen:ignore:<command-name></a> +<li><a href="Doxygen.html#Doxygen_nolinktranslate">doxygen:nolinktranslate</a> +<li><a href="Doxygen.html#Doxygen_nostripparams">doxygen:nostripparams</a> +</ul> +<li><a href="Doxygen.html#Doxygen_additional_options">Additional command line options</a> +</ul> +<li><a href="Doxygen.html#Doxygen_to_javadoc">Doxygen to Javadoc</a> +<ul> +<li><a href="Doxygen.html#Doxygen_basic_example">Basic example</a> +<li><a href="Doxygen.html#Doxygen_javadoc_tags">Javadoc tags</a> +<li><a href="Doxygen.html#Doxygen_unsupported_tags">Unsupported tags</a> +<li><a href="Doxygen.html#Doxygen_further_details">Further details</a> +</ul> +<li><a href="Doxygen.html#Doxygen_to_pydoc">Doxygen to Pydoc</a> +<ul> +<li><a href="Doxygen.html#Doxygen_python_basic_example">Basic example</a> +<li><a href="Doxygen.html#Doxygen_pydoc_tags">Pydoc translator</a> +<li><a href="Doxygen.html#Doxygen_python_unsupported_tags">Unsupported tags</a> +<li><a href="Doxygen.html#Doxygen_python_further_details">Further details</a> +</ul> +<li><a href="Doxygen.html#Doxygen_troubleshooting">Troubleshooting</a> +<ul> +<li><a href="Doxygen.html#troubleshooting_ifndef">Problem with conditional compilation</a> +</ul> +<li><a href="Doxygen.html#Doxygen_developer_details">Developer information</a> +<ul> +<li><a href="Doxygen.html#Doxygen_translator_design">Doxygen translator design</a> +<li><a href="Doxygen.html#Doxygen_debugging_commands">Debugging the Doxygen parser and translator</a> +<li><a href="Doxygen.html#Doxygen_tests">Tests</a> +</ul> +<li><a href="Doxygen.html#Doxygen_language_extension">Extending to other languages</a> +</ul> +</div> +<!-- INDEX --> + +<h3><a href="Warnings.html#Warnings">18 Warning Messages</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -569,7 +681,8 @@ <li><a href="Warnings.html#Warnings_nn11">Preprocessor (200-299)</a> <li><a href="Warnings.html#Warnings_nn12">C/C++ Parser (300-399)</a> <li><a href="Warnings.html#Warnings_nn13">Types and typemaps (400-499) </a> -<li><a href="Warnings.html#Warnings_nn14">Code generation (500-599)</a> +<li><a href="Warnings.html#Warnings_nn14">Code generation (500-559)</a> +<li><a href="Warnings.html#Warnings_doxygen">Doxygen comments (560-599)</a> <li><a href="Warnings.html#Warnings_nn15">Language module specific (700-899) </a> <li><a href="Warnings.html#Warnings_nn16">User defined (900-999)</a> </ul> @@ -578,7 +691,7 @@ </div> <!-- INDEX --> -<h3><a href="Modules.html#Modules">16 Working with Modules</a></h3> +<h3><a href="Modules.html#Modules">19 Working with Modules</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -594,7 +707,7 @@ </div> <!-- INDEX --> -<h3><a href="CCache.html#CCache">17 Using SWIG with ccache - ccache-swig(1) manpage</a></h3> +<h3><a href="CCache.html#CCache">20 Using SWIG with ccache - ccache-swig(1) manpage</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -620,91 +733,7 @@ </div> <!-- INDEX --> -<h3><a href="Allegrocl.html#Allegrocl">18 SWIG and Allegro Common Lisp</a></h3> - -<!-- INDEX --> -<div class="sectiontoc"> -<ul> -<li><a href="Allegrocl.html#Allegrocl_nn2">Basics</a> -<ul> -<li><a href="Allegrocl.html#Allegrocl_nn3">Running SWIG</a> -<li><a href="Allegrocl.html#Allegrocl_nn4">Command Line Options</a> -<li><a href="Allegrocl.html#Allegrocl_nn5">Inserting user code into generated files</a> -</ul> -<li><a href="Allegrocl.html#Allegrocl_nn6">Wrapping Overview</a> -<ul> -<li><a href="Allegrocl.html#Allegrocl_nn7">Function Wrapping</a> -<li><a href="Allegrocl.html#Allegrocl_nn8">Foreign Wrappers</a> -<li><a href="Allegrocl.html#Allegrocl_nn9">FFI Wrappers</a> -<li><a href="Allegrocl.html#Allegrocl_nn10">Non-overloaded Defuns</a> -<li><a href="Allegrocl.html#Allegrocl_nn11">Overloaded Defuns</a> -<li><a href="Allegrocl.html#Allegrocl_nn12">What about constant and variable access?</a> -<li><a href="Allegrocl.html#Allegrocl_nn13">Object Wrapping</a> -</ul> -<li><a href="Allegrocl.html#Allegrocl_nn14">Wrapping Details</a> -<ul> -<li><a href="Allegrocl.html#Allegrocl_nn15">Namespaces</a> -<li><a href="Allegrocl.html#Allegrocl_nn16">Constants</a> -<li><a href="Allegrocl.html#Allegrocl_nn17">Variables</a> -<li><a href="Allegrocl.html#Allegrocl_nn18">Enumerations</a> -<li><a href="Allegrocl.html#Allegrocl_nn19">Arrays</a> -<li><a href="Allegrocl.html#Allegrocl_nn20">Classes and Structs and Unions (oh my!)</a> -<ul> -<li><a href="Allegrocl.html#Allegrocl_nn21">CLOS wrapping of</a> -<li><a href="Allegrocl.html#Allegrocl_nn22">CLOS Inheritance</a> -<li><a href="Allegrocl.html#Allegrocl_nn23">Member fields and functions</a> -<li><a href="Allegrocl.html#Allegrocl_nn24">Why not directly access C++ classes using foreign types?</a> -</ul> -<li><a href="Allegrocl.html#Allegrocl_nn25">Templates</a> -<ul> -<li><a href="Allegrocl.html#Allegrocl_nn26">Generating wrapper code for templates</a> -<li><a href="Allegrocl.html#Allegrocl_nn27">Implicit Template instantiation</a> -</ul> -<li><a href="Allegrocl.html#Allegrocl_nn28">Typedef, Templates, and Synonym Types</a> -<ul> -<li><a href="Allegrocl.html#Allegrocl_nn29">Choosing a primary type</a> -</ul> -<li><a href="Allegrocl.html#Allegrocl_nn30">Function overloading/Parameter defaulting</a> -<li><a href="Allegrocl.html#Allegrocl_nn31">Operator wrapping and Operator overloading</a> -<li><a href="Allegrocl.html#Allegrocl_nn32">Varargs</a> -<li><a href="Allegrocl.html#Allegrocl_nn33">C++ Exceptions</a> -<li><a href="Allegrocl.html#Allegrocl_nn34">Pass by value, pass by reference</a> -</ul> -<li><a href="Allegrocl.html#Allegrocl_nn35">Typemaps</a> -<ul> -<li><a href="Allegrocl.html#Allegrocl_nn36">Code Generation in the C++ Wrapper</a> -<ul> -<li><a href="Allegrocl.html#Allegrocl_nn37">IN Typemap</a> -<li><a href="Allegrocl.html#Allegrocl_nn38">OUT Typemap</a> -<li><a href="Allegrocl.html#Allegrocl_nn39">CTYPE Typemap</a> -</ul> -<li><a href="Allegrocl.html#Allegrocl_nn40">Code generation in Lisp wrappers</a> -<ul> -<li><a href="Allegrocl.html#Allegrocl_nn41">LIN Typemap</a> -<li><a href="Allegrocl.html#Allegrocl_nn42">LOUT Typemap</a> -<li><a href="Allegrocl.html#Allegrocl_nn43">FFITYPE Typemap</a> -<li><a href="Allegrocl.html#Allegrocl_nn44">LISPTYPE Typemap</a> -<li><a href="Allegrocl.html#Allegrocl_nn45">LISPCLASS Typemap</a> -</ul> -<li><a href="Allegrocl.html#Allegrocl_nn46">Modifying SWIG behavior using typemaps</a> -</ul> -<li><a href="Allegrocl.html#Allegrocl_nn47">Identifier Converter functions</a> -<ul> -<li><a href="Allegrocl.html#Allegrocl_nn48">Creating symbols in the lisp environment</a> -<li><a href="Allegrocl.html#Allegrocl_nn49">Existing identifier-converter functions</a> -<ul> -<li><a href="Allegrocl.html#Allegrocl_nn50">identifier-convert-null</a> -<li><a href="Allegrocl.html#Allegrocl_nn51">identifier-convert-lispify</a> -<li><a href="Allegrocl.html#Allegrocl_nn52">Default identifier to symbol conversions</a> -</ul> -<li><a href="Allegrocl.html#Allegrocl_nn53">Defining your own identifier-converter</a> -<li><a href="Allegrocl.html#Allegrocl_nn54">Instructing SWIG to use a particular identifier-converter</a> -</ul> -</ul> -</div> -<!-- INDEX --> - -<h3><a href="Android.html#Android">19 SWIG and Android</a></h3> +<h3><a href="Android.html#Android">21 SWIG and Android</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -722,7 +751,7 @@ </div> <!-- INDEX --> -<h3><a href="CSharp.html#CSharp">20 SWIG and C#</a></h3> +<h3><a href="CSharp.html#CSharp">22 SWIG and C#</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -761,7 +790,8 @@ <li><a href="CSharp.html#CSharp_date_marshalling">Date marshalling using the csin typemap and associated attributes</a> <li><a href="CSharp.html#CSharp_date_properties">A date example demonstrating marshalling of C# properties</a> <li><a href="CSharp.html#CSharp_date_pre_post_directors">Date example demonstrating the 'pre' and 'post' typemap attributes for directors</a> -<li><a href="CSharp.html#CSharp_partial_classes">Turning wrapped classes into partial classes</a> +<li><a href="CSharp.html#CSharp_partial_classes">Turning proxy classes into partial classes</a> +<li><a href="CSharp.html#CSharp_sealed_proxy_class">Turning proxy classes into sealed classes</a> <li><a href="CSharp.html#CSharp_extending_proxy_class">Extending proxy classes with additional C# code</a> <li><a href="CSharp.html#CSharp_enum_underlying_type">Underlying type for enums</a> </ul> @@ -769,45 +799,7 @@ </div> <!-- INDEX --> -<h3><a href="Chicken.html#Chicken">21 SWIG and Chicken</a></h3> - -<!-- INDEX --> -<div class="sectiontoc"> -<ul> -<li><a href="Chicken.html#Chicken_nn2">Preliminaries</a> -<ul> -<li><a href="Chicken.html#Chicken_nn3">Running SWIG in C mode</a> -<li><a href="Chicken.html#Chicken_nn4">Running SWIG in C++ mode</a> -</ul> -<li><a href="Chicken.html#Chicken_nn5">Code Generation</a> -<ul> -<li><a href="Chicken.html#Chicken_nn6">Naming Conventions</a> -<li><a href="Chicken.html#Chicken_nn7">Modules</a> -<li><a href="Chicken.html#Chicken_nn8">Constants and Variables</a> -<li><a href="Chicken.html#Chicken_nn9">Functions</a> -<li><a href="Chicken.html#Chicken_nn10">Exceptions</a> -</ul> -<li><a href="Chicken.html#Chicken_nn11">TinyCLOS</a> -<li><a href="Chicken.html#Chicken_nn12">Linkage</a> -<ul> -<li><a href="Chicken.html#Chicken_nn13">Static binary or shared library linked at compile time</a> -<li><a href="Chicken.html#Chicken_nn14">Building chicken extension libraries</a> -<li><a href="Chicken.html#Chicken_nn15">Linking multiple SWIG modules with TinyCLOS</a> -</ul> -<li><a href="Chicken.html#Chicken_nn16">Typemaps</a> -<li><a href="Chicken.html#Chicken_nn17">Pointers</a> -<ul> -<li><a href="Chicken.html#Chicken_collection">Garbage collection</a> -</ul> -<li><a href="Chicken.html#Chicken_nn18">Unsupported features and known problems</a> -<ul> -<li><a href="Chicken.html#Chicken_nn19">TinyCLOS problems with Chicken version <= 1.92</a> -</ul> -</ul> -</div> -<!-- INDEX --> - -<h3><a href="D.html#D">22 SWIG and D</a></h3> +<h3><a href="D.html#D">23 SWIG and D</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -841,7 +833,7 @@ </div> <!-- INDEX --> -<h3><a href="Go.html#Go">23 SWIG and Go</a></h3> +<h3><a href="Go.html#Go">24 SWIG and Go</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -885,7 +877,7 @@ </div> <!-- INDEX --> -<h3><a href="Guile.html#Guile">24 SWIG and Guile</a></h3> +<h3><a href="Guile.html#Guile">25 SWIG and Guile</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -921,7 +913,7 @@ </div> <!-- INDEX --> -<h3><a href="Java.html#Java">25 SWIG and Java</a></h3> +<h3><a href="Java.html#Java">26 SWIG and Java</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1010,6 +1002,9 @@ <li><a href="Java.html#Java_directors_threading">Director threading issues</a> <li><a href="Java.html#Java_directors_performance">Director performance tuning</a> <li><a href="Java.html#Java_exceptions_from_directors">Java exceptions from directors</a> +<ul> +<li><a href="Java.html#Java_customizing_director_exceptions">Customizing director exceptions</a> +</ul> </ul> <li><a href="Java.html#Java_allprotected">Accessing protected members</a> <li><a href="Java.html#Java_common_customization">Common customization features</a> @@ -1072,7 +1067,7 @@ </div> <!-- INDEX --> -<h3><a href="Javascript.html#Javascript">26 SWIG and Javascript</a></h3> +<h3><a href="Javascript.html#Javascript">27 SWIG and Javascript</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1114,29 +1109,6 @@ </div> <!-- INDEX --> -<h3><a href="Lisp.html#Lisp">27 SWIG and Common Lisp</a></h3> - -<!-- INDEX --> -<div class="sectiontoc"> -<ul> -<li><a href="Lisp.html#Lisp_nn2">Allegro Common Lisp</a> -<li><a href="Lisp.html#Lisp_nn3">Common Foreign Function Interface(CFFI)</a> -<ul> -<li><a href="Lisp.html#Lisp_nn4">Additional Commandline Options </a> -<li><a href="Lisp.html#Lisp_nn5">Generating CFFI bindings</a> -<li><a href="Lisp.html#Lisp_nn6">Generating CFFI bindings for C++ code</a> -<li><a href="Lisp.html#Lisp_nn7">Inserting user code into generated files</a> -</ul> -<li><a href="Lisp.html#Lisp_nn8">CLISP</a> -<ul> -<li><a href="Lisp.html#Lisp_nn9">Additional Commandline Options </a> -<li><a href="Lisp.html#Lisp_nn10">Details on CLISP bindings</a> -</ul> -<li><a href="Lisp.html#Lisp_nn11">UFFI </a> -</ul> -</div> -<!-- INDEX --> - <h3><a href="Lua.html#Lua">28 SWIG and Lua</a></h3> <!-- INDEX --> @@ -1205,108 +1177,7 @@ </div> <!-- INDEX --> -<h3><a href="Modula3.html#Modula3">29 SWIG and Modula-3</a></h3> - -<!-- INDEX --> -<div class="sectiontoc"> -<ul> -<li><a href="Modula3.html#Modula3_modula3_overview">Overview</a> -<ul> -<li><a href="Modula3.html#Modula3_motivation">Motivation</a> -</ul> -<li><a href="Modula3.html#Modula3_conception">Conception</a> -<ul> -<li><a href="Modula3.html#Modula3_cinterface">Interfaces to C libraries</a> -<li><a href="Modula3.html#Modula3_cppinterface">Interfaces to C++ libraries</a> -</ul> -<li><a href="Modula3.html#Modula3_preliminaries">Preliminaries</a> -<ul> -<li><a href="Modula3.html#Modula3_compilers">Compilers</a> -<li><a href="Modula3.html#Modula3_commandline">Additional Commandline Options</a> -</ul> -<li><a href="Modula3.html#Modula3_typemaps">Modula-3 typemaps</a> -<ul> -<li><a href="Modula3.html#Modula3_inoutparam">Inputs and outputs</a> -<li><a href="Modula3.html#Modula3_ordinals">Subranges, Enumerations, Sets</a> -<li><a href="Modula3.html#Modula3_class">Objects</a> -<li><a href="Modula3.html#Modula3_imports">Imports</a> -<li><a href="Modula3.html#Modula3_exceptions">Exceptions</a> -<li><a href="Modula3.html#Modula3_typemap_example">Example</a> -</ul> -<li><a href="Modula3.html#Modula3_hints">More hints to the generator</a> -<ul> -<li><a href="Modula3.html#Modula3_features">Features</a> -<li><a href="Modula3.html#Modula3_pragmas">Pragmas</a> -</ul> -<li><a href="Modula3.html#Modula3_remarks">Remarks</a> -</ul> -</div> -<!-- INDEX --> - -<h3><a href="Mzscheme.html#Mzscheme">30 SWIG and MzScheme/Racket</a></h3> - -<!-- INDEX --> -<div class="sectiontoc"> -<ul> -<li><a href="Mzscheme.html#MzScheme_nn2">Creating native structures</a> -<li><a href="Mzscheme.html#MzScheme_simple">Simple example</a> -<li><a href="Mzscheme.html#MzScheme_external_docs">External documentation</a> -</ul> -</div> -<!-- INDEX --> - -<h3><a href="Ocaml.html#Ocaml">31 SWIG and Ocaml</a></h3> - -<!-- INDEX --> -<div class="sectiontoc"> -<ul> -<li><a href="Ocaml.html#Ocaml_nn2">Preliminaries</a> -<ul> -<li><a href="Ocaml.html#Ocaml_nn3">Running SWIG</a> -<li><a href="Ocaml.html#Ocaml_nn4">Compiling the code</a> -<li><a href="Ocaml.html#Ocaml_nn5">The camlp4 module</a> -<li><a href="Ocaml.html#Ocaml_nn6">Using your module</a> -<li><a href="Ocaml.html#Ocaml_nn7">Compilation problems and compiling with C++</a> -</ul> -<li><a href="Ocaml.html#Ocaml_nn8">The low-level Ocaml/C interface</a> -<ul> -<li><a href="Ocaml.html#Ocaml_nn9">The generated module</a> -<li><a href="Ocaml.html#Ocaml_nn10">Enums</a> -<ul> -<li><a href="Ocaml.html#Ocaml_nn11">Enum typing in Ocaml</a> -</ul> -<li><a href="Ocaml.html#Ocaml_nn12">Arrays</a> -<ul> -<li><a href="Ocaml.html#Ocaml_nn13">Simple types of bounded arrays</a> -<li><a href="Ocaml.html#Ocaml_nn14">Complex and unbounded arrays</a> -<li><a href="Ocaml.html#Ocaml_nn15">Using an object</a> -<li><a href="Ocaml.html#Ocaml_nn16">Example typemap for a function taking float * and int</a> -</ul> -<li><a href="Ocaml.html#Ocaml_nn17">C++ Classes</a> -<ul> -<li><a href="Ocaml.html#Ocaml_nn18">STL vector and string Example</a> -<li><a href="Ocaml.html#Ocaml_nn19">C++ Class Example</a> -<li><a href="Ocaml.html#Ocaml_nn20">Compiling the example</a> -<li><a href="Ocaml.html#Ocaml_nn21">Sample Session</a> -</ul> -<li><a href="Ocaml.html#Ocaml_nn22">Director Classes</a> -<ul> -<li><a href="Ocaml.html#Ocaml_nn23">Director Introduction</a> -<li><a href="Ocaml.html#Ocaml_nn24">Overriding Methods in Ocaml</a> -<li><a href="Ocaml.html#Ocaml_nn25">Director Usage Example</a> -<li><a href="Ocaml.html#Ocaml_nn26">Creating director objects</a> -<li><a href="Ocaml.html#Ocaml_nn27">Typemaps for directors, directorin, directorout, directorargout</a> -<li><a href="Ocaml.html#Ocaml_nn28">typemap</a> -<li><a href="Ocaml.html#Ocaml_nn29">directorout typemap</a> -<li><a href="Ocaml.html#Ocaml_nn30">directorargout typemap</a> -</ul> -<li><a href="Ocaml.html#Ocaml_nn31">Exceptions</a> -</ul> -</ul> -</div> -<!-- INDEX --> - -<h3><a href="Octave.html#Octave">32 SWIG and Octave</a></h3> +<h3><a href="Octave.html#Octave">29 SWIG and Octave</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1346,7 +1217,7 @@ </div> <!-- INDEX --> -<h3><a href="Perl5.html#Perl5">33 SWIG and Perl5</a></h3> +<h3><a href="Perl5.html#Perl5">30 SWIG and Perl5</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1422,7 +1293,7 @@ </div> <!-- INDEX --> -<h3><a href="Php.html#Php">34 SWIG and PHP</a></h3> +<h3><a href="Php.html#Php">31 SWIG and PHP</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1463,31 +1334,7 @@ </div> <!-- INDEX --> -<h3><a href="Pike.html#Pike">35 SWIG and Pike</a></h3> - -<!-- INDEX --> -<div class="sectiontoc"> -<ul> -<li><a href="Pike.html#Pike_nn2">Preliminaries</a> -<ul> -<li><a href="Pike.html#Pike_nn3">Running SWIG</a> -<li><a href="Pike.html#Pike_nn4">Getting the right header files</a> -<li><a href="Pike.html#Pike_nn5">Using your module</a> -</ul> -<li><a href="Pike.html#Pike_nn6">Basic C/C++ Mapping</a> -<ul> -<li><a href="Pike.html#Pike_nn7">Modules</a> -<li><a href="Pike.html#Pike_nn8">Functions</a> -<li><a href="Pike.html#Pike_nn9">Global variables</a> -<li><a href="Pike.html#Pike_nn10">Constants and enumerated types</a> -<li><a href="Pike.html#Pike_nn11">Constructors and Destructors</a> -<li><a href="Pike.html#Pike_nn12">Static Members</a> -</ul> -</ul> -</div> -<!-- INDEX --> - -<h3><a href="Python.html#Python">36 SWIG and Python</a></h3> +<h3><a href="Python.html#Python">32 SWIG and Python</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1502,7 +1349,8 @@ <li><a href="Python.html#Python_nn9">Using your module</a> <li><a href="Python.html#Python_nn10">Compilation of C++ extensions</a> <li><a href="Python.html#Python_nn11">Compiling for 64-bit platforms</a> -<li><a href="Python.html#Python_nn12">Building Python Extensions under Windows</a> +<li><a href="Python.html#Python_nn12">Building Python extensions under Windows</a> +<li><a href="Python.html#Python_commandline">Additional Python commandline options</a> </ul> <li><a href="Python.html#Python_nn13">A tour of basic C/C++ wrapping</a> <ul> @@ -1535,7 +1383,6 @@ <li><a href="Python.html#Python_builtin_overloads">Operator overloads and slots -- use them!</a> </ul> <li><a href="Python.html#Python_nn30">Memory management</a> -<li><a href="Python.html#Python_nn31">Python 2.2 and classic classes</a> </ul> <li><a href="Python.html#Python_directors">Cross language polymorphism</a> <ul> @@ -1553,6 +1400,10 @@ <li><a href="Python.html#Python_nn42">Adding additional Python code</a> <li><a href="Python.html#Python_nn43">Class extension with %extend</a> <li><a href="Python.html#Python_nn44">Exception handling with %exception</a> +<li><a href="Python.html#Python_optimization">Optimization options</a> +<ul> +<li><a href="Python.html#Python_fastproxy">-fastproxy</a> +</ul> </ul> <li><a href="Python.html#Python_nn45">Tips and techniques</a> <ul> @@ -1577,6 +1428,7 @@ <li><a href="Python.html#Python_nn62">Mapping Python tuples into small arrays</a> <li><a href="Python.html#Python_nn63">Mapping sequences to C arrays</a> <li><a href="Python.html#Python_nn64">Pointer handling</a> +<li><a href="Python.html#Python_memory_management_member_variables">Memory management when returning references to member variables</a> </ul> <li><a href="Python.html#Python_nn65">Docstring Features</a> <ul> @@ -1597,12 +1449,13 @@ <li><a href="Python.html#Python_absrelimports">Absolute and relative imports</a> <li><a href="Python.html#Python_absimport">Enforcing absolute import semantics</a> <li><a href="Python.html#Python_importfrominit">Importing from __init__.py</a> -<li><a href="Python.html#Python_implicit_namespace_packages">Implicit Namespace Packages</a> -<li><a href="Python.html#Python_package_search">Searching for the wrapper module</a> +<li><a href="Python.html#Python_implicit_namespace_packages">Implicit namespace packages</a> +<li><a href="Python.html#Python_package_search">Location of modules</a> <ul> <li><a href="Python.html#Python_package_search_both_package_modules">Both modules in the same package</a> -<li><a href="Python.html#Python_package_search_wrapper_split">Split modules</a> <li><a href="Python.html#Python_package_search_both_global_modules">Both modules are global</a> +<li><a href="Python.html#Python_package_search_wrapper_split">Split modules custom configuration</a> +<li><a href="Python.html#Python_custom_module_import">More on customizing the module import code</a> <li><a href="Python.html#Python_package_search_static">Statically linked C modules</a> </ul> </ul> @@ -1614,11 +1467,16 @@ <li><a href="Python.html#Python_nn77">Byte string output conversion</a> <li><a href="Python.html#Python_2_unicode">Python 2 Unicode</a> </ul> +<li><a href="Python.html#Python_multithreaded">Support for Multithreaded Applications</a> +<ul> +<li><a href="Python.html#Python_thread_UI">UI for Enabling Multithreading Support</a> +<li><a href="Python.html#Python_thread_performance">Multithread Performance</a> +</ul> </ul> </div> <!-- INDEX --> -<h3><a href="R.html#R">37 SWIG and R</a></h3> +<h3><a href="R.html#R">33 SWIG and R</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1634,7 +1492,7 @@ </div> <!-- INDEX --> -<h3><a href="Ruby.html#Ruby">38 SWIG and Ruby</a></h3> +<h3><a href="Ruby.html#Ruby">34 SWIG and Ruby</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1772,7 +1630,7 @@ </div> <!-- INDEX --> -<h3><a href="Scilab.html#Scilab">39 SWIG and Scilab</a></h3> +<h3><a href="Scilab.html#Scilab">35 SWIG and Scilab</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1803,7 +1661,7 @@ </ul> <li><a href="Scilab.html#Scilab_wrapping_pointers">Pointers</a> <ul> -<li><a href="Scilab.html#Scilab_wrapping_pointers_pointer_adresses">Utility functions</a> +<li><a href="Scilab.html#Scilab_wrapping_pointers_utility_functions">Utility functions</a> <li><a href="Scilab.html#Scilab_wrapping_pointers_null_pointers">Null pointers:</a> </ul> <li><a href="Scilab.html#Scilab_wrapping_structs">Structures</a> @@ -1841,7 +1699,7 @@ </div> <!-- INDEX --> -<h3><a href="Tcl.html#Tcl">40 SWIG and Tcl</a></h3> +<h3><a href="Tcl.html#Tcl">36 SWIG and Tcl</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1907,7 +1765,74 @@ </div> <!-- INDEX --> -<h3><a href="Extending.html#Extending">41 Extending SWIG to support new languages</a></h3> +<h3><a href="Mzscheme.html#Mzscheme">37 SWIG and MzScheme/Racket</a></h3> + +<!-- INDEX --> +<div class="sectiontoc"> +<ul> +<li><a href="Mzscheme.html#MzScheme_nn2">Creating native structures</a> +<li><a href="Mzscheme.html#MzScheme_simple">Simple example</a> +<li><a href="Mzscheme.html#MzScheme_external_docs">External documentation</a> +</ul> +</div> +<!-- INDEX --> + +<h3><a href="Ocaml.html#Ocaml">38 SWIG and OCaml</a></h3> + +<!-- INDEX --> +<div class="sectiontoc"> +<ul> +<li><a href="Ocaml.html#Ocaml_nn2">Preliminaries</a> +<ul> +<li><a href="Ocaml.html#Ocaml_nn3">Running SWIG</a> +<li><a href="Ocaml.html#Ocaml_nn4">Compiling the code</a> +<li><a href="Ocaml.html#Ocaml_nn5">The camlp4 module</a> +<li><a href="Ocaml.html#Ocaml_nn6">Using your module</a> +<li><a href="Ocaml.html#Ocaml_nn7">Compilation problems and compiling with C++</a> +</ul> +<li><a href="Ocaml.html#Ocaml_nn8">The low-level Ocaml/C interface</a> +<ul> +<li><a href="Ocaml.html#Ocaml_nn9">The generated module</a> +<li><a href="Ocaml.html#Ocaml_nn10">Enums</a> +<ul> +<li><a href="Ocaml.html#Ocaml_nn11">Enum typing in Ocaml</a> +</ul> +<li><a href="Ocaml.html#Ocaml_nn12">Arrays</a> +<ul> +<li><a href="Ocaml.html#Ocaml_nn13">Simple types of bounded arrays</a> +<li><a href="Ocaml.html#Ocaml_nn14">Complex and unbounded arrays</a> +<li><a href="Ocaml.html#Ocaml_nn15">Using an object</a> +<li><a href="Ocaml.html#Ocaml_nn16">Example typemap for a function taking float * and int</a> +</ul> +<li><a href="Ocaml.html#Ocaml_nn17">C++ Classes</a> +<ul> +<li><a href="Ocaml.html#Ocaml_nn18">STL vector and string Example</a> +<li><a href="Ocaml.html#Ocaml_nn19">C++ Class Example</a> +<li><a href="Ocaml.html#Ocaml_nn20">Compiling the example</a> +<li><a href="Ocaml.html#Ocaml_nn21">Sample Session</a> +</ul> +<li><a href="Ocaml.html#Ocaml_nn22">Director Classes</a> +<ul> +<li><a href="Ocaml.html#Ocaml_nn23">Director Introduction</a> +<li><a href="Ocaml.html#Ocaml_nn24">Overriding Methods in Ocaml</a> +<li><a href="Ocaml.html#Ocaml_nn25">Director Usage Example</a> +<li><a href="Ocaml.html#Ocaml_nn26">Creating director objects</a> +<li><a href="Ocaml.html#Ocaml_nn27">Typemaps for directors, directorin, directorout, directorargout</a> +<li><a href="Ocaml.html#Ocaml_nn28">directorin typemap</a> +<li><a href="Ocaml.html#Ocaml_nn29">directorout typemap</a> +<li><a href="Ocaml.html#Ocaml_nn30">directorargout typemap</a> +</ul> +<li><a href="Ocaml.html#Ocaml_nn31">Exceptions</a> +</ul> +<li><a href="Ocaml.html#Ocaml_nn32">Documentation Features</a> +<ul> +<li><a href="Ocaml.html#Ocaml_nn33">Module docstring</a> +</ul> +</ul> +</div> +<!-- INDEX --> + +<h3><a href="Extending.html#Extending">39 Extending SWIG to support new languages</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1965,8 +1890,13 @@ <li><a href="Extending.html#Extending_running_test_suite">Running the test-suite</a> </ul> <li><a href="Extending.html#Extending_nn43">Documentation</a> -<li><a href="Extending.html#Extending_prerequisites">Prerequisites for adding a new language module to the SWIG distribution</a> <li><a href="Extending.html#Extending_coding_style_guidelines">Coding style guidelines</a> +<li><a href="Extending.html#Extending_language_status">Target language status</a> +<ul> +<li><a href="Extending.html#Extending_supported_status">Supported status</a> +<li><a href="Extending.html#Extending_experimental_status">Experimental status</a> +</ul> +<li><a href="Extending.html#Extending_prerequisites">Prerequisites for adding a new language module to the SWIG distribution</a> </ul> <li><a href="Extending.html#Extending_debugging_options">Debugging Options</a> <li><a href="Extending.html#Extending_nn46">Guide to parse tree nodes</a> diff --git a/Doc/Manual/Contract.html b/Doc/Manual/Contract.html index ef1228cfb..93fb8c003 100644 --- a/Doc/Manual/Contract.html +++ b/Doc/Manual/Contract.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Contract">13 Contracts</a></H1> +<H1><a name="Contract">15 Contracts</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -39,7 +39,7 @@ When one of the rules is violated by a script, a runtime exception is generated rather than having the program continue to execute. </p> -<H2><a name="Contract_nn2">13.1 The %contract directive</a></H2> +<H2><a name="Contract_nn2">15.1 The %contract directive</a></H2> <p> @@ -95,7 +95,7 @@ RuntimeError: Contract violation: require: (arg1>=0) </pre> </div> -<H2><a name="Contract_nn3">13.2 %contract and classes</a></H2> +<H2><a name="Contract_nn3">15.2 %contract and classes</a></H2> <p> @@ -174,7 +174,7 @@ specified for the derived class all must hold. In the above example, this means that both the arguments to <tt>Spam::bar</tt> must be positive. </p> -<H2><a name="Contract_nn4">13.3 Constant aggregation and %aggregate_check</a></H2> +<H2><a name="Contract_nn4">15.3 Constant aggregation and %aggregate_check</a></H2> <p> @@ -263,7 +263,7 @@ Regrettably, there is no automatic way to perform similar checks with enums valu release. </p> -<H2><a name="Contract_nn5">13.4 Notes</a></H2> +<H2><a name="Contract_nn5">15.4 Notes</a></H2> <p> diff --git a/Doc/Manual/Customization.html b/Doc/Manual/Customization.html index 0e5fb2869..328bc2391 100644 --- a/Doc/Manual/Customization.html +++ b/Doc/Manual/Customization.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Customization">12 Customization Features</a></H1> +<H1><a name="Customization">14 Customization Features</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -46,7 +46,7 @@ of exception handling is presented. Then, a more general-purpose customization mechanism known as "features" is described. </p> -<H2><a name="Customization_exception">12.1 Exception handling with %exception</a></H2> +<H2><a name="Customization_exception">14.1 Exception handling with %exception</a></H2> <p> @@ -101,7 +101,7 @@ for exception handling. That directive is deprecated--<tt>%exception</tt> provides the same functionality, but is substantially more flexible. </p> -<H3><a name="Customization_nn3">12.1.1 Handling exceptions in C code</a></H3> +<H3><a name="Customization_nn3">14.1.1 Handling exceptions in C code</a></H3> <p> @@ -169,7 +169,7 @@ Each target language has its own approach to creating a runtime error/exception and for Perl it is the <tt>croak</tt> method shown above. </p> -<H3><a name="Customization_nn4">12.1.2 Exception handling with longjmp()</a></H3> +<H3><a name="Customization_nn4">14.1.2 Exception handling with longjmp()</a></H3> <p> @@ -245,7 +245,7 @@ Note: This implementation is only intended to illustrate the general idea. To m modify it to handle nested <tt>try</tt> declarations. </p> -<H3><a name="Customization_nn5">12.1.3 Handling C++ exceptions</a></H3> +<H3><a name="Customization_nn5">14.1.3 Handling C++ exceptions</a></H3> <p> @@ -280,7 +280,7 @@ class OutOfMemory {}; </pre> </div> -<H3><a name="Customization_allowexcept">12.1.4 Exception handlers for variables</a></H3> +<H3><a name="Customization_allowexcept">14.1.4 Exception handlers for variables</a></H3> <p> @@ -305,7 +305,7 @@ The <tt>%allowexception</tt> feature works like any other feature and so can be </pre> </div> -<H3><a name="Customization_nn6">12.1.5 Defining different exception handlers</a></H3> +<H3><a name="Customization_nn6">14.1.5 Defining different exception handlers</a></H3> <p> @@ -356,7 +356,7 @@ In this case, the exception handler is only attached to declarations named "allocate". This would include both global and member functions. The names supplied to <tt>%exception</tt> follow the same rules as for <tt>%rename</tt> described in the section on -<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>. +<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a>. For example, if you wanted to define an exception handler for a specific class, you might write this: </p> @@ -442,7 +442,7 @@ declarations. However, it never really worked that well and the new %exception directive is much better. </p> -<H3><a name="Customization_exception_special_variables">12.1.6 Special variables for %exception</a></H3> +<H3><a name="Customization_exception_special_variables">14.1.6 Special variables for %exception</a></H3> <p> @@ -516,7 +516,7 @@ The special variables are often used in situations where method calls are logged $action } catch (MemoryError) { - croak("Out of memory in $decl"); + croak("Out of memory in $decl"); } } void log(const char *message); @@ -545,7 +545,7 @@ Below shows the expansions for the 1st of the overloaded <tt>something</tt> wrap </pre></div> -<H3><a name="Customization_nn7">12.1.7 Using The SWIG exception library</a></H3> +<H3><a name="Customization_nn7">14.1.7 Using The SWIG exception library</a></H3> <p> @@ -600,7 +600,7 @@ SWIG_NullReferenceError The <tt>SWIG_exception()</tt> function can also be used in typemaps. </p> -<H2><a name="Customization_ownership">12.2 Object ownership and %newobject</a></H2> +<H2><a name="Customization_ownership">14.2 Object ownership and %newobject</a></H2> <p> @@ -757,7 +757,7 @@ char *strdup(const char *s); The results might not be what you expect. </p> -<H2><a name="Customization_features">12.3 Features and the %feature directive</a></H2> +<H2><a name="Customization_features">14.3 Features and the %feature directive</a></H2> <p> @@ -796,7 +796,7 @@ involving <tt>%feature</tt>: </div> <p> -The name matching rules outlined in the <a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> +The name matching rules outlined in the <a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a> section applies to all <tt>%feature</tt> directives. In fact the <tt>%rename</tt> directive is just a special form of <tt>%feature</tt>. The matching rules mean that features are very flexible and can be applied with @@ -839,7 +839,7 @@ The following are all equivalent: The syntax in the first variation will generate the <tt>{ }</tt> delimiters used whereas the other variations will not. </p> -<H3><a name="Customization_feature_attributes">12.3.1 Feature attributes</a></H3> +<H3><a name="Customization_feature_attributes">14.3.1 Feature attributes</a></H3> <p> @@ -880,7 +880,7 @@ In the following example, <tt>MyExceptionClass</tt> is the name of the Java clas Further details can be obtained from the <a href="Java.html#Java_exception_handling">Java exception handling</a> section. </p> -<H3><a name="Customization_feature_flags">12.3.2 Feature flags</a></H3> +<H3><a name="Customization_feature_flags">14.3.2 Feature flags</a></H3> <p> @@ -978,7 +978,7 @@ in the <tt>swig.swg</tt> Library file. The following shows the alternative synta The concept of clearing features is discussed next. </p> -<H3><a name="Customization_clearing_features">12.3.3 Clearing features</a></H3> +<H3><a name="Customization_clearing_features">14.3.3 Clearing features</a></H3> <p> @@ -1071,7 +1071,7 @@ The three macros below show this for the "except" feature: </pre> </div> -<H3><a name="Customization_features_default_args">12.3.4 Features and default arguments</a></H3> +<H3><a name="Customization_features_default_args">14.3.4 Features and default arguments</a></H3> <p> @@ -1146,7 +1146,7 @@ specifying or not specifying default arguments in a feature is not applicable as in SWIG-1.3.23 when the approach to wrapping methods with default arguments was changed. </p> -<H3><a name="Customization_features_example">12.3.5 Feature example</a></H3> +<H3><a name="Customization_features_example">14.3.5 Feature example</a></H3> <p> diff --git a/Doc/Manual/D.html b/Doc/Manual/D.html index 45b57e18b..d97267a5b 100644 --- a/Doc/Manual/D.html +++ b/Doc/Manual/D.html @@ -6,7 +6,7 @@ <meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head> <body bgcolor="#FFFFFF"> -<H1><a name="D">22 SWIG and D</a></H1> +<H1><a name="D">23 SWIG and D</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -41,7 +41,7 @@ -<H2><a name="D_introduction">22.1 Introduction</a></H2> +<H2><a name="D_introduction">23.1 Introduction</a></H2> <p>From the <a href="http://www.digitalmars.com/d/">D Programming Language</a> web site: <em>D is a systems programming language. Its focus is on combining the power and high performance of C and C++ with the programmer productivity of modern languages like Ruby and Python. [...] The D language is statically typed and compiles directly to machine code.</em> As such, it is not very surprising that D is able to directly <a href="http://www.digitalmars.com/d/1.0/interfaceToC.html">interface with C libraries</a>. Why would a SWIG module for D be needed then in the first place?</p> @@ -53,10 +53,10 @@ <p>To help addressing these issues, the SWIG C# module has been forked to support D. Is has evolved quite a lot since then, but there are still many similarities, so if you do not find what you are looking for on this page, it might be worth having a look at the chapter on <a href="CSharp.html#CSharp">C#</a> (and also on <a href="Java.html#Java">Java</a>, since the C# module was in turn forked from it).</p> -<H2><a name="D_command_line_invocation">22.2 Command line invocation</a></H2> +<H2><a name="D_command_line_invocation">23.2 Command line invocation</a></H2> -<p>To activate the D module, pass the <tt>-d</tt> option to SWIG at the command line. The same standard command line switches as with any other language module are available, plus the following D specific ones:</p> +<p>To activate the D module, pass the <tt>-d</tt> option to SWIG at the command line. The same standard command line options as with any other language module are available, plus the following D specific ones:</p> <dl> <dt><tt>-d2</tt></dt> @@ -66,8 +66,8 @@ <dt><a name="D_splitproxy"></a><tt>-splitproxy</tt></dt> <dd> - <p>By default, SWIG generates two D modules: the <em>proxy</em> module, named like the source module (either specified via the <tt>%module</tt> directive or via the <tt>module</tt> command line switch), which contains all the proxy classes, functions, enums, etc., and the <em>intermediary</em> module (named like the proxy module, but suffixed with <tt>_im</tt>), which contains all the <tt>extern(C)</tt> function declarations and other private parts only used internally by the proxy module.</p> - <p>If the split proxy mode is enabled by passing this switch at the command line, all proxy classes and enums are emitted to their own D module instead. The main proxy module only contains free functions and constants in this case.</p> + <p>By default, SWIG generates two D modules: the <em>proxy</em> module, named like the source module (either specified via the <tt>%module</tt> directive or via the <tt>module</tt> command line option), which contains all the proxy classes, functions, enums, etc., and the <em>intermediary</em> module (named like the proxy module, but suffixed with <tt>_im</tt>), which contains all the <tt>extern(C)</tt> function declarations and other private parts only used internally by the proxy module.</p> + <p>If the split proxy mode is enabled by passing this option at the command line, all proxy classes and enums are emitted to their own D module instead. The main proxy module only contains free functions and constants in this case.</p> </dd> <dt><tt>-package <pkg></tt></dt> @@ -77,16 +77,16 @@ <dt><tt>-wrapperlibrary <wl></tt></dt> <dd> - <p>The code SWIG generates to dynamically load the C/C++ wrapper layer looks for a library called <tt>$module_wrap</tt> by default. With this switch, you can override the name of the file the wrapper code loads at runtime (the <tt>lib</tt> prefix and the suffix for shared libraries are appended automatically, depending on the OS).</p> + <p>The code SWIG generates to dynamically load the C/C++ wrapper layer looks for a library called <tt>$module_wrap</tt> by default. With this option, you can override the name of the file the wrapper code loads at runtime (the <tt>lib</tt> prefix and the suffix for shared libraries are appended automatically, depending on the OS).</p> <p>This might especially be useful if you want to invoke SWIG several times on separate modules, but compile the resulting code into a single shared library.</p> </dd> </dl> -<H2><a name="D_typemaps">22.3 Typemaps</a></H2> +<H2><a name="D_typemaps">23.3 Typemaps</a></H2> -<H3><a name="D_typemap_name_comparison">22.3.1 C# <-> D name comparison</a></H3> +<H3><a name="D_typemap_name_comparison">23.3.1 C# <-> D name comparison</a></H3> <p>If you already know the SWIG C# module, you might find the following name comparison table useful:</p> @@ -107,12 +107,12 @@ csimports <-> dimports csbody <-> dbody csfinalize <-> ddestructor - csdestruct <-> ddispose - csdestruct_derived <-> ddispose_derived + csdisposing <-> ddispose + csdisposing_derived <-> ddispose_derived </pre></div> -<H3><a name="D_ctype_imtype_dtype">22.3.2 ctype, imtype, dtype</a></H3> +<H3><a name="D_ctype_imtype_dtype">23.3.2 ctype, imtype, dtype</a></H3> <p>Mapping of types between the C/C++ library, the C/C++ library wrapper exposing the C functions, the D wrapper module importing these functions and the D proxy code.</p> @@ -120,7 +120,7 @@ <p>The <tt>ctype</tt> typemap is used to determine the types to use in the C wrapper functions. The types from the <tt>imtype</tt> typemap are used in the extern(C) declarations of these functions in the intermediary D module. The <tt>dtype</tt> typemap contains the D types used in the D proxy module/class.</p> -<H3><a name="D_in_out_directorin_direcetorout">22.3.3 in, out, directorin, directorout</a></H3> +<H3><a name="D_in_out_directorin_direcetorout">23.3.3 in, out, directorin, directorout</a></H3> <p>Used for converting between the types for C/C++ and D when generating the code for the wrapper functions (on the C++ side).</p> @@ -130,7 +130,7 @@ <p>The <tt>directorin</tt> typemap is used to convert parameters to the type used in the D director callback function, its return value is processed by <tt>directorout</tt> (see below).</p> -<H3><a name="D_din_dout_ddirectorin_ddirectorout">22.3.4 din, dout, ddirectorin, ddirectorout</a></H3> +<H3><a name="D_din_dout_ddirectorin_ddirectorout">23.3.4 din, dout, ddirectorin, ddirectorout</a></H3> <p>Typemaps for code generation in D proxy and type wrapper classes.</p> @@ -157,13 +157,13 @@ dtype DClass.method(dtype a)</pre></div> -<H3><a name="D_typecheck_typemaps">22.3.5 typecheck typemaps</a></H3> +<H3><a name="D_typecheck_typemaps">23.3.5 typecheck typemaps</a></H3> <p>Because, unlike many scripting languages supported by SWIG, D does not need any dynamic dispatch helper to access an overloaded function, the purpose of these is merely to issue a warning for overloaded C++ functions that cannot be overloaded in D (as more than one C++ type maps to a single D type).</p> -<H3><a name="D_code_injection_typemaps">22.3.6 Code injection typemaps</a></H3> +<H3><a name="D_code_injection_typemaps">23.3.6 Code injection typemaps</a></H3> <p>These typemaps are used for generating the skeleton of proxy classes for C++ types.</p> @@ -178,7 +178,7 @@ Code can also be injected into the D proxy class using <tt>%proxycode</tt>. </p> -<H3><a name="D_special_variables">22.3.7 Special variable macros</a></H3> +<H3><a name="D_special_variables">23.3.7 Special variable macros</a></H3> <p>The standard SWIG special variables are available for use within typemaps as described in the <a href="Typemaps.html#Typemaps">Typemaps documentation</a>, for example <tt>$1</tt>, <tt>$input</tt>, <tt>$result</tt> etc.</p> @@ -280,7 +280,7 @@ class SomeClass : AnInterface, AnotherInterface { ... } </pre></div> - <p>For this to work, <tt>AnInterface</tt> and <tt>AnotherInterface</tt> have to be in scope. If SWIG is not in split proxy mode, this is already the case, but it it is, they have to be added to the import list via the <tt>dimports</tt> typemap. Additionally, the import statement depends on the package SWIG is configured to emit the modules to.</p> + <p>For this to work, <tt>AnInterface</tt> and <tt>AnotherInterface</tt> have to be in scope. If SWIG is not in split proxy mode, this is already the case, but if it is, they have to be added to the import list via the <tt>dimports</tt> typemap. Additionally, the import statement depends on the package SWIG is configured to emit the modules to.</p> <p>The <tt>$importtype</tt> macro helps you to elegantly solve this problem:</p> <div class="code"><pre> %typemap(dimports) RemoteMpe %{ @@ -299,7 +299,7 @@ $importtype(AnotherInterface) </dl> -<H2><a name="D_features">22.4 D and %feature</a></H2> +<H2><a name="D_features">23.4 D and %feature</a></H2> <p>The D module defines a number of directives which modify the <a href="Customization.html#Customization_features">SWIG features</a> set globally or for a specific declaration:</p> @@ -329,7 +329,7 @@ struct A { </dl> -<H2><a name="D_pragmas">22.5 Pragmas</a></H2> +<H2><a name="D_pragmas">23.5 Pragmas</a></H2> <p>There are a few SWIG pragmas specific to the D module, which you can use to influence the D code SWIG generates:</p> @@ -368,7 +368,7 @@ struct A { </dl> -<H2><a name="D_exceptions">22.6 D Exceptions</a></H2> +<H2><a name="D_exceptions">23.6 D Exceptions</a></H2> <p>Out of the box, C++ exceptions are fundamentally incompatible to their equivalent in the D world and cannot simply be propagated to a calling D method. There is, however, an easy way to solve this problem: Just catch the exception in the C/C++ wrapper layer, pass the contents to D, and make the wrapper code rethrow the exception in the D world.</p> @@ -378,7 +378,7 @@ struct A { <p>As this feature is implemented in exactly the same way it is for C#, please see the <a href="CSharp.html#CSharp_exceptions">C# documentation</a> for a more detailed explanation.</p> -<H2><a name="D_directors">22.7 D Directors</a></H2> +<H2><a name="D_directors">23.7 D Directors</a></H2> <p>When the directors feature is activated, SWIG generates extra code on both the C++ and the D side to enable cross-language polymorphism. Essentially, this means that if you subclass a proxy class in D, C++ code can access any overridden virtual methods just as if you created a derived class in C++.</p> @@ -387,16 +387,16 @@ struct A { </p> -<H2><a name="D_other_features">22.8 Other features</a></H2> +<H2><a name="D_other_features">23.8 Other features</a></H2> -<H3><a name="D_nspace">22.8.1 Extended namespace support (nspace)</a></H3> +<H3><a name="D_nspace">23.8.1 Extended namespace support (nspace)</a></H3> <p>By default, SWIG flattens all C++ namespaces into a single target language namespace, but as for Java and C#, the <a href="SWIGPlus.html#SWIGPlus_nspace"><tt>nspace</tt></a> feature is supported for D. If it is active, C++ namespaces are mapped to D packages/modules. Note, however, that like for the other languages, <em>free</em> variables and functions are not supported yet; currently, they are all allows written to the main proxy D module.</p> -<H3><a name="D_native_pointer_support">22.8.2 Native pointer support</a></H3> +<H3><a name="D_native_pointer_support">23.8.2 Native pointer support</a></H3> <p>Contrary to many of the scripting languages supported by SWIG, D fully supports C-style pointers. The D module thus includes a custom mechanism to wrap C pointers directly as D pointers where applicable, that is, if the type that is pointed to is represented the same in C and D (on the bit-level), dubbed a <em>primitive type</em> below.</p> @@ -408,7 +408,7 @@ struct A { <p>To determine if a type should be considered primitive, the <tt>cprimitive</tt> attribute on its <tt>dtype</tt> attribute is used. For example, the <tt>dtype</tt> typemap for <tt>float</tt> has <tt>cprimitive="1"</tt>, so the code from the <tt>nativepointer</tt> attribute is taken into account e.g. for <tt>float **</tt> or the function pointer <tt>float (*)(float *)</tt>.</p> -<H3><a name="D_operator_overloading">22.8.3 Operator overloading</a></H3> +<H3><a name="D_operator_overloading">23.8.3 Operator overloading</a></H3> <p>The D module comes with basic operator overloading support for both D1 and D2. There are, however, a few limitations arising from conceptual differences between C++ and D:</p> @@ -420,7 +420,7 @@ struct A { <p>There are also some cases where the operators can be translated to D, but the differences in the implementation details are big enough that a rather involved scheme would be required for automatic wrapping them, which has not been implemented yet. This affects, for example, the array subscript operator, <tt>[]</tt>, in combination with assignments - while <tt>operator []</tt> in C++ simply returns a reference which is then written to, D resorts to a separate <tt>opIndexAssign</tt> method -, or implicit casting (which was introduced in D2 via <tt>alias this</tt>). Despite the lack of automatic support, manually handling these cases should be perfectly possible.</p> -<H3><a name="D_test_suite">22.8.4 Running the test-suite</a></H3> +<H3><a name="D_test_suite">23.8.4 Running the test-suite</a></H3> <p>As with any other language, the SWIG test-suite can be built for D using the <tt>*-d-test-suite</tt> targets of the top-level Makefile. By default, D1 is targeted, to build it with D2, use the optional <tt>D_VERSION</tt> variable, e.g. <tt>make check-d-test-suite D_VERSION=2</tt>.</p> @@ -428,14 +428,14 @@ struct A { <p>Note: If you want to use GDC on Linux or another platform which requires you to link <tt>libdl</tt> for dynamically loading the shared library, you might have to add <tt>-ldl</tt> manually to the <tt>d_compile</tt> target in <tt>Examples/Makefile</tt>, because GDC does not currently honor the <tt>pragma(lib, ...)</tt> statement.</p> -<H2><a name="D_typemap_examples">22.9 D Typemap examples</a></H2> +<H2><a name="D_typemap_examples">23.9 D Typemap examples</a></H2> <p>There are no D-specific typemap examples yet. However, with the above <a href="D.html#D_typemap_name_comparison">name comparison table</a>, you should be able to get an idea what can be done by looking at the <a href="CSharp.html#CSharp_typemap_examples">corresponding C# section</a>.</p> -<H2><a name="D_planned_features">22.10 Work in progress and planned features</a></H2> +<H2><a name="D_planned_features">23.10 Work in progress and planned features</a></H2> <p>There are a couple of features which are not implemented yet, but would be very useful and might be added in the near future:</p> diff --git a/Doc/Manual/Doxygen.html b/Doc/Manual/Doxygen.html new file mode 100644 index 000000000..ff025c047 --- /dev/null +++ b/Doc/Manual/Doxygen.html @@ -0,0 +1,1838 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<title>SWIG and Doxygen Translation</title> +<link rel="stylesheet" type="text/css" href="style.css"> +</head> +<body bgcolor="#FFFFFF"> +<H1><a name="Doxygen">17 SWIG and Doxygen Translation</a></H1> +<!-- INDEX --> +<div class="sectiontoc"> +<ul> +<li><a href="#Doxygen_translation_overview">Doxygen translation overview</a> +<li><a href="#Doxygen_file_preparation">Preparations</a> +<ul> +<li><a href="#Doxygen_running_swig">Enabling Doxygen translation</a> +<li><a href="#Doxygen_features">Doxygen-specific %feature directives</a> +<ul> +<li><a href="#Doxygen_notranslate">doxygen:notranslate</a> +<li><a href="#Doxygen_alias">doxygen:alias:<command-name></a> +<li><a href="#Doxygen_ignore">doxygen:ignore:<command-name></a> +<li><a href="#Doxygen_nolinktranslate">doxygen:nolinktranslate</a> +<li><a href="#Doxygen_nostripparams">doxygen:nostripparams</a> +</ul> +<li><a href="#Doxygen_additional_options">Additional command line options</a> +</ul> +<li><a href="#Doxygen_to_javadoc">Doxygen to Javadoc</a> +<ul> +<li><a href="#Doxygen_basic_example">Basic example</a> +<li><a href="#Doxygen_javadoc_tags">Javadoc tags</a> +<li><a href="#Doxygen_unsupported_tags">Unsupported tags</a> +<li><a href="#Doxygen_further_details">Further details</a> +</ul> +<li><a href="#Doxygen_to_pydoc">Doxygen to Pydoc</a> +<ul> +<li><a href="#Doxygen_python_basic_example">Basic example</a> +<li><a href="#Doxygen_pydoc_tags">Pydoc translator</a> +<li><a href="#Doxygen_python_unsupported_tags">Unsupported tags</a> +<li><a href="#Doxygen_python_further_details">Further details</a> +</ul> +<li><a href="#Doxygen_troubleshooting">Troubleshooting</a> +<ul> +<li><a href="#troubleshooting_ifndef">Problem with conditional compilation</a> +</ul> +<li><a href="#Doxygen_developer_details">Developer information</a> +<ul> +<li><a href="#Doxygen_translator_design">Doxygen translator design</a> +<li><a href="#Doxygen_debugging_commands">Debugging the Doxygen parser and translator</a> +<li><a href="#Doxygen_tests">Tests</a> +</ul> +<li><a href="#Doxygen_language_extension">Extending to other languages</a> +</ul> +</div> +<!-- INDEX --> + + + +<p> +This chapter describes SWIG's support for translating Doxygen comments +found in interface and header files into a target language's normal +documentation language. Currently only Javadoc and Pydoc is +supported. +</p> + +<H2><a name="Doxygen_translation_overview">17.1 Doxygen translation overview</a></H2> + + +<p> +The Doxygen Translation module of SWIG adds an extra layer of +functionality to SWIG, allowing automated translation of <a href= +"http://www.doxygen.nl/manual/">Doxygen</a> formatted comments +from input files into a documentation language more suited for the +target language. Currently this module only translates into Javadoc +and Pydoc for the SWIG Java and Python modules. +Other extensions could be added at a later date. +The Doxygen Translation module originally started as +a <a href="https://developers.google.com/open-source/gsoc/2008/">Google Summer of +Code</a> proposal from Summer 2008. +</p> + +<H2><a name="Doxygen_file_preparation">17.2 Preparations</a></H2> + + +<p> +To make use of the comment translation system, your documentation +comments must be in properly formatted <a href= +"http://www.doxygen.nl/manual/">Doxygen.</a> Doxygen comments can be +present in your main SWIG interface file or any header file that it +imports. You are advised to be validate that your comments compile +properly with Doxygen before you try to translate them. Doxygen +itself is a more comprehensive tool and can provide you better feedback for +correcting any syntax errors that may be present. Please look at +Doxygen's <a href= +"http://www.doxygen.nl/manual/docblocks.html"> Documenting the +code</a> for the full comment format specifications. However, SWIG's +Doxygen parser will still report many errors and warnings found +in comments (like unterminated strings or missing ending tags). +</p> + +<p> +Currently, the whole subset of Doxygen comment styles is supported +(See <a href="http://www.doxygen.nl/manual/docblocks.html"> +Documenting the code</a>). Here they are: +</p> + +<div class="code"><pre> +/** + * Javadoc style comment, multiline + */ +/*! + * QT-style comment, multiline + */ +/** + Any of the above, but without intermediate *'s + */ +/// Single-line comment +//! Another single-line comment +</pre></div> + +<p> +Also any of the above with '<' added after comment-starting symbol, +like <i>/**<, /*!<, ///<, </i> or <i> //!<</i> will be +treated as a post-comment and will be assigned to the code before the +comment. + +Any number of '*' or '/' within a Doxygen comment is considered to be a +separator and is not included in the final comment, so you may safely use +comments like <i>/*********/</i> or <i>//////////</i>. +</p> + +<p> +Please note, as SWIG parses the input file by itself with strict grammar, +there is only a limited support for various cases of comment placement +in the file. +</p> +<p> +Comments can be placed before C/C++ expressions on separate lines: +</p> + +<div class="code"><pre> +/** + * Some comment + */ +void someOtherFunction(); +/** + * Some comment + */ +void someFunction(); + +class Shape { + /* + * Calculate the area in cm^2 + */ + int getArea(); +} +</pre></div> + +<p> +After C/C++ expressions at the end of the line: +</p> + +<div class="code"><pre> +int someVariable = 9; ///< This is a var holding magic number 9 +void doNothing(); ///< This does nothing, nop +</pre></div> + +<p> +and in some special cases, like function parameter comments: +</p> + +<div class="code"><pre> +void someFunction( + int a ///< Some parameter + ); +</pre></div> + +<p> +or enum element comments: +</p> + +<div class="code"><pre> +enum E_NUMBERS +{ + EN_ZERO, ///< The first enum item, gets zero as it's value + EN_ONE, ///< The second, EN_ONE=1 + EN_THREE +}; +</pre></div> + +<p> +Currently only comments directly before or after the code items +are supported. Doxygen also supports comments containing structural commands, +where the comments for a code item are not put directly before or after the code item. +These structural commands are stripped out by SWIG and are not assigned to anything. +</p> + +<H3><a name="Doxygen_running_swig">17.2.1 Enabling Doxygen translation</a></H3> + + +<p> +Doxygen comments translation is disabled by default and needs to be explicitly +enabled using the command line <tt>-doxygen</tt> option for the languages that +do support it (currently Java and Python). +</p> + +<H3><a name="Doxygen_features">17.2.2 Doxygen-specific %feature directives</a></H3> + + +<p> +Translation of Doxygen comments is influenced by the following <a +href="Customization.html#Customization_features">%feature directives</a>: +</p> + +<H4><a name="Doxygen_notranslate">17.2.2.1 doxygen:notranslate</a></H4> + + +<p> +Turns off translation of Doxygen comments to the target language syntax: the +original comment will be copied to the output unchanged. This is useful if you +want to use Doxygen itself to generate documentation for the target language +instead of the corresponding language tool (<tt>javadoc</tt>, <tt>sphinx</tt>, +...). +</p> + + +<H4><a name="Doxygen_alias">17.2.2.2 doxygen:alias:<command-name></a></H4> + + +<p> +Specify an alias for a Doxygen command with the given name. This can be useful +for custom Doxygen commands which can be defined using <tt>ALIASES</tt> option +for Doxygen itself but which are unknown to SWIG. <tt>"command-name"</tt> is the +name of the command in the Doxyfile, e.g. if it contains +</p> + +<div class="code"><pre> +ALIASES = "sideeffect=\par Side Effects:\n" +</pre></div> + +<p> +Then you could also specify the same expansion for SWIG with: +</p> + +<div class="code"><pre> +%feature("doxygen:alias:sideeffect") "\par Side Effects:\n" +</pre></div> + +<p> +Please note that command arguments are not currently supported with this +feature. +</p> + +<p> +Notice that it is perfectly possible and potentially useful to define the alias +expansion differently depending on the target language, e.g. with +</p> + +<div class="code"><pre> +#ifdef SWIGJAVA +%feature("doxygen:alias:not_for_java") "This functionality is not available for Java" +#else +%feature("doxygen:alias:not_for_java") "" +#endif +</pre></div> + +<p> +you could use <tt>@not_for_java</tt> in the documentation comments of all +functions which can't, for whatever reason, be currently exposed in Java +wrappers of the C++ API. +</p> + + +<H4><a name="Doxygen_ignore">17.2.2.3 doxygen:ignore:<command-name></a></H4> + + +<p> +This feature makes it possible to just ignore an unknown Doxygen command, instead of +replacing it with the predefined text that <tt>doxygen:alias</tt> does. +For example, you could use +</p> + +<div class="code"><pre> +%feature("doxygen:ignore:transferfull") Fantastic(); +/** + A fantastic function. + + @transferfull Command ignored, but anything here is still included. + */ +int * Fantastic(); +</pre></div> + +<p> +if you use a custom Doxygen <tt>transferfull</tt> command to indicate that the +return value ownership is transferred to the caller, as this information doesn't +make much sense for the other languages without explicit ownership management. +</p> + +<p> +Doxygen syntax is rather rich and, in addition to simple commands such as +<tt>@transferfull</tt>, it is also possible to define commands with arguments. +As explained in <a href="http://www.doxygen.nl/manual/commands.html">Doxygen documentation</a>, +the arguments can have a range of a single word, everything until the end of +line or everything until the end of the next paragraph. Currently, only the "end +of line" case is supported using the <tt>range="line"</tt> argument of the +feature directive: +</p> + +<div class="code"><pre> +// Ignore occurrences of +// +// @compileroptions Some special C++ compiler options. +// +// in Doxygen comments as C++ options are not interesting for the target language +// developers. +%feature("doxygen:ignore:compileroptions", range="line") Amazing(); + +/** + An amazing function. + + @compileroptions This function must be compiled with /EHa when using MSVC. + */ +void Amazing(); + +</pre></div> + +<p> +In addition, it is also possible to have custom pairs of begin/end tags, +similarly to the standard Doxygen <tt>@code/@endcode</tt>, for example. Such +tags can also be ignored using the special value of <tt>range</tt> starting with +<tt>end</tt> to indicate that the range is an interval, for example: +</p> + +<div class="code"><pre> +%feature("doxygen:ignore:forcpponly", range="end"); // same as "end:endforcpponly" +/** + An incredible function. + + @forcpponly + This is C++-specific. + @endforcpponly + */ +void Incredible(); +</pre></div> + +<p> +would ignore everything between <tt>@forcpponly</tt> and <tt>@endforcpponly</tt> +commands in Doxygen comments. By default, the name of the end command is the +same as of the start one with "end" prefix, following Doxygen conventions, but +this can be overridden by providing the end command name after the colon. +</p> +<p> +This example shows how custom tags can be used to bracket anything specific to +C++ and prevent it from appearing in the target language documentation. +Conversely, another pair of custom tags could be used to put target language +specific information in the C++ comments. In this case, only the custom tags +themselves should be ignored, but their contents should be parsed as usual and +<tt>contents="parse"</tt> can be used for this: +</p> + +<div class="code"><pre> +%feature("doxygen:ignore:beginPythonOnly", range="end:endPythonOnly", contents="parse"); +/** + A splendid function. + + @beginPythonOnly + This is specific to @b Python. + @endPythonOnly + */ +void Splendid(); + +</pre></div> + +<p> +Putting everything together, if these directives are in effect: +</p> + +<div class="code"><pre> +%feature("doxygen:ignore:transferfull"); +%feature("doxygen:ignore:compileroptions", range="line"); +%feature("doxygen:ignore:forcpponly", range="end"); +%feature("doxygen:ignore:beginPythonOnly", range="end:endPythonOnly", contents="parse"); +</pre></div> + +<p> +then the following C++ Doxygen comment: +</p> + +<div class="code"><pre> +/** + A contrived example of ignoring too many commands in one comment. + + @forcpponly + This is C++-specific. + @endforcpponly + + @beginPythonOnly + This is specific to @b Python. + @endPythonOnly + + @transferfull Command ignored, but anything here is still included. + + @compileroptions This function must be compiled with /EHa when using MSVC. + */ +int * Contrived(); +</pre></div> + +<p> +would be translated to this comment in Python: +</p> + +<div class="code"><pre> +def func(): + r""" + A contrived example of ignoring too many commands in one comment. + + This is specific to **Python**. + + Command ignored, but anything here is still included. + """ + ... +</pre></div> + + +<H4><a name="Doxygen_nolinktranslate">17.2.2.4 doxygen:nolinktranslate</a></H4> + + +<p> +Turn off automatic link-objects translation. +This is only applicable to Java at the moment. +</p> + + +<H4><a name="Doxygen_nostripparams">17.2.2.5 doxygen:nostripparams</a></H4> + + +<p> +Turn off stripping of <tt>@param</tt> and <tt>@tparam</tt> +Doxygen commands if the parameter is not found in the function signature. +This is only applicable to Java at the moment. +</p> + + +<H3><a name="Doxygen_additional_options">17.2.3 Additional command line options</a></H3> + + +<p> +ALSO TO BE ADDED (Javadoc auto brief?) +</p> + +<H2><a name="Doxygen_to_javadoc">17.3 Doxygen to Javadoc</a></H2> + + +<p> +If translation is enabled, Javadoc formatted comments should be +automatically placed in the correct locations in the resulting module +and proxy files. +</p> + +<H3><a name="Doxygen_basic_example">17.3.1 Basic example</a></H3> + + +<p> +Here is an example segment from an included header file +</p> +<div class="code"><pre> +/*! This is describing class Shape + \author Bob + */ + +class Shape { +public: + Shape() { + nshapes++; + } + virtual ~Shape() { + nshapes--; + }; + double x, y; /*!< Important Variables */ + void move(double dx, double dy); /*!< Moves the Shape */ + virtual double area(void) = 0; /*!< \return the area */ + virtual double perimeter(void) = 0; /*!< \return the perimeter */ + static int nshapes; +}; +</pre></div> + +<p> +Simply running SWIG should result in the following code being present in Shapes.java +</p> + +<div class="targetlang"><pre> + +/** + * This is describing class Shape + * @author Bob + * + */ + +public class Shape { + +... + +/** + * Important Variables + */ + public void setX(double value) { + ShapesJNI.Shape_x_set(swigCPtr, this, value); + } + +/** + * Important Variables + */ + public double getX() { + return ShapesJNI.Shape_x_get(swigCPtr, this); + } + +/** + * Moves the Shape + */ + public void move(double dx, double dy) { + ShapesJNI.Shape_move(swigCPtr, this, dx, dy); + } + +/** + * @return the area + */ + public double area() { + return ShapesJNI.Shape_area(swigCPtr, this); + } + +/** + * @return the perimeter + */ + public double perimeter() { + return ShapesJNI.Shape_perimeter(swigCPtr, this); + } +} + +</pre></div> + +<p> +The code Java-wise should be identical to what would have been +generated without the doxygen functionality enabled. When the Doxygen Translator +module encounters a comment that contains nothing useful or a doxygen comment that it cannot +parse, it will not affect the functionality of the SWIG generated +code. +</p> + +<p> +The Javadoc translator will handle most of the tags conversions (see the +table below). It will also automatically translate link-objects +params, in \see and \link...\endlink commands. For example, +'someFunction(std::string)' will be converted to +'someFunction(String)'. If +you don't want such behaviour, you could turn this off by using the +'doxygen:nolinktranslate' feature. Also all '\param' and '\tparam' +commands are stripped out, if the specified parameter is not present in +the function. Use 'doxygen:nostripparams' to avoid. +</p> + +<p> +Javadoc translator features summary +(see <a href="Customization.html#Customization_features">%feature +directives</a>): +</p> + +<H3><a name="Doxygen_javadoc_tags">17.3.2 Javadoc tags</a></H3> + + +<p> +Here is the list of all Doxygen tags and the description of how they are translated to Javadoc +</p> +<div class="diagram"> +<table border="0" summary="Java Doxygen tags"> +<tr> + <th align="left">Doxygen tags</th> +</tr> +<tr> +<td>\a</td> +<td>wrapped with <i> html tag</td> +</tr> +<tr> +<td>\arg</td> +<td>wrapped with <li> html tag</td> +</tr> +<tr> +<td>\author</td> +<td>translated to @author</td> +</tr> +<tr> +<td>\authors</td> +<td>translated to @author</td> +</tr> +<tr> +<td>\b</td> +<td>wrapped with <b> html tag</td> +</tr> +<tr> +<td>\c</td> +<td>wrapped with <code> html tag</td> +</tr> +<tr> +<td>\cite</td> +<td>wrapped with <i> html tag</td> +</tr> +<tr> +<td>\code</td> +<td>translated to {@code ...}</td> +</tr> +<tr> +<td>\cond</td> +<td>translated to 'Conditional comment: <condition>'</td> +</tr> +<tr> +<td>\copyright</td> +<td>replaced with 'Copyright:'</td> +</tr> +<tr> +<td>\deprecated</td> +<td>translated to @deprecated</td> +</tr> +<tr> +<td>\e</td> +<td>wrapped with <i> html tag</td> +</tr> +<tr> +<td>\else</td> +<td>replaced with '}Else:{'</td> +</tr> +<tr> +<td>\elseif</td> +<td>replaced with '}Else if: <condition>{'</td> +</tr> +<tr> +<td>\em</td> +<td>wrapped with <i> html tag</td> +</tr> +<tr> +<td>\endcode</td> +<td>see note for \code</td> +</tr> +<tr> +<td>\endcond</td> +<td>replaced with 'End of conditional comment.'</td> +</tr> +<tr> +<td>\endif</td> +<td>replaced with '}'</td> +</tr> +<tr> +<td>\endlink</td> +<td>see note for \link</td> +</tr> +<tr> +<td>\endverbatim</td> +<td>see note for \verbatim</td> +</tr> +<tr> +<td>\exception</td> +<td>translated to @exception</td> +</tr> +<tr> +<td>\f$, \f[, \f], \f{, \f}</td> +<td>LateX formulas are left unchanged</td> +</tr> +<tr> +<td>\if</td> +<td>replaced with 'If: <condition> {'</td> +</tr> +<tr> +<td>\ifnot</td> +<td>replaced with 'If not: <condition> {'</td> +</tr> +<tr> +<td>\image</td> +<td>translated to <img/> html tag only if target=HTML</td> +</tr> +<tr> +<td>\li</td> +<td>wrapped with <li> html tag</td> +</tr> +<tr> +<td>\link</td> +<td>translated to {@link ...}</td> +</tr> +<tr> +<td>\n</td> +<td>replaced with new line char</td> +</tr> +<tr> +<td>\note</td> +<td>replaced with 'Note:'</td> +</tr> +<tr> +<td>\overload</td> +<td>prints 'This is an overloaded ...' according to Doxygen docs</td> +</tr> +<tr> +<td>\p</td> +<td>wrapped with <code> html tag</td> +</tr> +<tr> +<td>\par</td> +<td>replaced with <p alt='title'>...</p></td> +</tr> +<tr> +<td>\param</td> +<td>translated to @param</td> +</tr> +<tr> +<td>\remark</td> +<td>replaced with 'Remarks:'</td> +</tr> +<tr> +<td>\remarks</td> +<td>replaced with 'Remarks:'</td> +</tr> +<tr> +<td>\result</td> +<td>translated to @return</td> +</tr> +<tr> +<td>\return</td> +<td>translated to @return</td> +</tr> +<tr> +<td>\returns</td> +<td>translated to @return</td> +</tr> +<tr> +<td>\sa</td> +<td>translated to @see</td> +</tr> +<tr> +<td>\see</td> +<td>translated to @see</td> +</tr> +<tr> +<td>\since</td> +<td>translated to @since</td> +</tr> +<tr> +<td>\throw</td> +<td>translated to @throws</td> +</tr> +<tr> +<td>\throws</td> +<td>translated to @throws</td> +</tr> +<tr> +<td>\todo</td> +<td>replaced with 'TODO:'</td> +</tr> +<tr> +<td>\tparam</td> +<td>translated to @param</td> +</tr> +<tr> +<td>\verbatim</td> +<td>translated to {@literal ...}</td> +</tr> +<tr> +<td>\version</td> +<td>translated to @version</td> +</tr> +<tr> +<td>\warning</td> +<td>translated to 'Warning:'</td> +</tr> +<tr> +<td>\$</td> +<td>prints $ char</td> +</tr> +<tr> +<td>\@</td> +<td>prints @ char</td> +</tr> +<tr> +<td>\\</td> +<td>prints \ char</td> +</tr> +<tr> +<td>\&</td> +<td>prints & char</td> +</tr> +<tr> +<td>\~</td> +<td>prints ~ char</td> +</tr> +<tr> +<td>\<</td> +<td>prints < char</td> +</tr> +<tr> +<td>\></td> +<td>prints > char</td> +</tr> +<tr> +<td>\#</td> +<td>prints # char</td> +</tr> +<tr> +<td>\%</td> +<td>prints % char</td> +</tr> +<tr> +<td>\"</td> +<td>prints " char</td> +</tr> +<tr> +<td>\.</td> +<td>prints . char</td> +</tr> +<tr> +<td>\::</td> +<td>prints ::</td> +</tr> +</table> +</div> + +<H3><a name="Doxygen_unsupported_tags">17.3.3 Unsupported tags</a></H3> + + +<p> +Doxygen has a wealth of tags such as @latexonly that have no +equivalent in Javadoc (all supported tags are listed in +<a href="https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html">Javadoc documentation</a>). +As a result several tags have no +translation or particular use, such as some linking and section tags. +These are suppressed with their content just printed out (if the tag has any +sense, typically text content). +Here is the list of these tags: +</p> +<div class="diagram"> +<table border="0" summary="Unsupported Java Doxygen Tags"> +<tr> + <th align="left">Unsupported Doxygen tags</th> +</tr> +<tr> +<td>\addindex</td> +<td>\addtogroup</td> +<td>\anchor</td> +<td>\attention</td> +</tr> +<tr> +<td>\brief</td> +<td>\bug</td> +<td>\callgraph</td> +<td>\callergraph</td> +</tr> +<tr> +<td>\class</td> +<td>\copybrief</td> +<td>\copydetails</td> +<td>\copydoc</td> +</tr> +<tr> +<td>\date</td> +<td>\def</td> +<td>\defgroup</td> +<td>\details</td> +</tr> +<tr> +<td>\dir</td> +<td>\dontinclude</td> +<td>\dot</td> +<td>\dotfile</td> +</tr> +<tr> +<td>\enddot</td> +<td>\endhtmlonly</td> +<td>\endinternal</td> +<td>\endlatexonly</td> +</tr> +<tr> +<td>\endmanonly</td> +<td>\endmsc</td> +<td>\endrtfonly</td> +<td>\endxmlonly</td> +</tr> +<tr> +<td>\enum</td> +<td>\example</td> +<td>\extends</td> +</tr> +<tr> +<td>\file</td> +<td>\fn</td> +<td>\headerfile</td> +<td>\hideinitializer</td> +</tr> +<tr> +<td>\htmlinclude</td> +<td>\htmlonly</td> +<td>\implements</td> +<td>\include</td> +</tr> +<tr> +<td>\includelineno</td> +<td>\ingroup</td> +<td>\internal</td> +<td>\invariant</td> +</tr> +<tr> +<td>\interface</td> +<td>\latexonly</td> +<td>\line</td> +<td>\mainpage</td> +</tr> +<tr> +<td>\manonly</td> +<td>\memberof</td> +<td>\msc</td> +<td>\mscfile</td> +</tr> +<tr> +<td>\name</td> +<td>\namespace</td> +<td>\nosubgrouping</td> +<td>\package</td> +</tr> +<tr> +<td>\page</td> +<td>\paragraph</td> +<td>\post</td> +<td>\pre</td> +</tr> +<tr> +<td>\private</td> +<td>\privatesection</td> +<td>\property</td> +<td>\protected</td> +</tr> +<tr> +<td>\protectedsection</td> +<td>\protocol</td> +<td>\public</td> +<td>\publicsection</td> +</tr> +<tr> +<td>\ref</td> +<td>\related</td> +<td>\relates</td> +<td>\relatedalso</td> +</tr> +<tr> +<td>\relatesalso</td> +<td>\retval</td> +<td>\rtfonly</td> +<td>\section</td> +</tr> +<tr> +<td>\short</td> +<td>\showinitializer</td> +<td>\skip</td> +<td>\skipline</td> +</tr> +<tr> +<td>\snippet</td> +<td>\struct</td> +<td>\subpage</td> +<td>\subsection</td> +</tr> +<tr> +<td>\subsubsection</td> +<td>\tableofcontents</td> +<td>\test</td> +<td>\typedef</td> +</tr> +<tr> +<td>\union</td> +<td>\until</td> +<td>\var</td> +<td>\verbinclude</td> +</tr> +<tr> +<td>\weakgroup</td> +<td>\xmlonly</td> +<td>\xrefitem</td> +<td>\category</td> +</tr> +</table> +</div> + +<p> + +If one of the following Doxygen tags appears as the first tag in a +comment, the whole comment block is ignored: +<!-- see parser.y, function isStructuralDoxygen() --> + +</p> +<div class="diagram"> +<table border="0" summary="Ignored Java Doxygen Tags"> +<tr> + <th align="left">Ignored Doxygen tags</th> +</tr> +<tr> +<td>\addtogroup</td> +<td>\callgraph</td> +<td>\callergraph</td> +<td>\category</td> +</tr> +<tr> +<td>\class</td> +<td>\def</td> +<td>\defgroup</td> +<td>\dir</td> +</tr> +<tr> +<td>\enum</td> +<td>\example</td> +<td>\file</td> +<td>\fn</td> +</tr> +<tr> +<td>\headerfile</td> +<td>\hideinitializer</td> +<td>\interface</td> +<td>\internal</td> +</tr> +<tr> +<td>\mainpage</td> +<td>\name</td> +<td>\namespace</td> +<td>\nosubgrouping</td> +</tr> +<tr> +<td>\overload</td> +<td>\package</td> +<td>\page</td> +<td>\property</td> +</tr> +<tr> +<td>\protocol</td> +<td>\relates</td> +<td>\relatesalso</td> +<td>\showinitializer</td> +</tr> +<tr> +<td>\struct</td> +<td>\name</td> +<td>\namespace</td> +<td>\nosubgrouping</td> +</tr> +<tr> +<td>\typedef</td> +<td>\union</td> +<td>\var</td> +<td>\weakgroup</td> +</tr> + +</table> +</div> + + + +<H3><a name="Doxygen_further_details">17.3.4 Further details</a></H3> + + +<p> +TO BE ADDED. +</p> + +<H2><a name="Doxygen_to_pydoc">17.4 Doxygen to Pydoc</a></H2> + + +<p> +If translation is enabled, Pydoc formatted comments should be +automatically placed in the correct locations in the resulting module +and proxy files. The problem is that Pydoc has no tag mechanism like +Doxygen or Javadoc, so most of Doxygen commands are translated by merely +copying the appropriate command text. +</p> + +<H3><a name="Doxygen_python_basic_example">17.4.1 Basic example</a></H3> + + +<p> +Here is an example segment from an included header file +</p> +<div class="code"><pre> +/*! This is describing class Shape + \author Bob + */ + +class Shape { +public: + Shape() { + nshapes++; + } + virtual ~Shape() { + nshapes--; + }; + double x, y; /*!< Important Variables */ + void move(double dx, double dy); /*!< Moves the Shape */ + virtual double area(void) = 0; /*!< \return the area */ + virtual double perimeter(void) = 0; /*!< \return the perimeter */ + static int nshapes; +}; +</pre></div> + +<p> +Simply running SWIG should result in the following code being present in Shapes.py +</p> + +<div class="targetlang"><pre> + +... + +class Shape(_object): + """ + This is describing class Shape + Authors: + Bob + + """ + + ... + + def move(self, *args): + """ + Moves the Shape + """ + return _Shapes.Shape_move(self, *args) + + def area(self): + """ + Return: + the area + """ + return _Shapes.Shape_area(self) + + def perimeter(self): + """ + Return: + the perimeter + """ + return _Shapes.Shape_perimeter(self) +</pre></div> + +<p> +If any parameters of a function or a method are documented in the Doxygen comment, +their description is copied into the generated output using +<a href="http://sphinx-doc.org/">Sphinx </a> documentation conventions. For example +</p> +<div class="code"><pre> +/** + Set a breakpoint at the given location. + + @param filename The full path to the file. + @param line_number The line number in the file. + */ +bool SetBreakpoint(const char* filename, int line_number); +</pre></div> + +<p> +would be translated to +</p> + +<div class="targetlang"><pre> +def SetBreakpoint(filename, line_number): + r""" + Set a breakpoint at the given location. + + :type filename: string + :param filename: The full path to the file. + :type line_number: int + :param line_number: The line number in the file. + """ +</pre></div> +<p> +The types used for the parameter documentation come from the "doctype" typemap which +is defined for all the primitive types and a few others (e.g. <tt>std::string</tt> and +<tt>shared_ptr<T></tt>) but for non-primitive types is taken to be just the C++ +name of the type with namespace scope delimiters (<tt>::</tt>) replaced with a dot. To +change this, you can define your own typemaps for the custom types, e.g: +</p> +<div class="code"><pre> +%typemap(doctype) MyDate "datetime.date"; +</pre></div> + +<p> +Currently Doxygen comments assigned to global variables and static member variables +are not present in generated code, so they have no comment translated for them. +</p> + +<p> + <b>Whitespace and tables</b> + Whitespace is preserved when translating comments, so it makes + sense to have Doxygen comments formatted in a readable way. This + includes tables, where tags <th>, <td> and </tr>are translated + to '|'. The line after line with <th> tags contains dashes. + If we take care about whitespace, comments in Python are much more + readable. Example: + +<div class="code"><pre> +/** + * <table border = '1'> + * <caption>Animals</caption> + * <tr><th> Column 1 </th><th> Column 2 </th></tr> + * <tr><td> cow </td><td> dog </td></tr> + * <tr><td> cat </td><td> mouse </td></tr> + * <tr><td> horse </td><td> parrot </td></tr> + * </table> + */ +</pre></div> +<p> +translates to Python as: +</p> +<div class="diagram"><pre> + Animals + | Column 1 | Column 2 | + ----------------------- + | cow | dog | + | cat | mouse | + | horse | parrot | +</pre></div> + +<p> + <b>Overloaded functions</b> +Since all the overloaded functions in c++ are wrapped into one Python +function, Pydoc translator will combine every comment of every +overloaded function and put it into the comment for the one wrapper function. +</p> +<p> +If you intend to use resulting generated Python file with the Doxygen docs +generator, rather than Pydoc, you may want to turn off translation +completely (doxygen:notranslate feature). Then SWIG will just copy +the comments to the proxy file and reformat them if needed, but all +the comment content will be left as is. As Doxygen doesn't support +special commands in Python comments +(see <a href="http://www.doxygen.nl/manual/docblocks.html#pythonblocks">Doxygen +docs</a>), you may want to use some tool like doxypy +(<a href="https://pypi.org/project/doxypy/">doxypy</a>) +to do the work. +</p> + +<H3><a name="Doxygen_pydoc_tags">17.4.2 Pydoc translator</a></H3> + + +<p> +Here is the list of all Doxygen tags and the description of how they are translated to Pydoc +</p> +<div class="diagram"> +<table border="0" summary="Python Doxygen tags"> +<tr> + <th align="left">Doxygen tags</th> +</tr> +<tr> +<td>\a</td> +<td>wrapped with '_'</td> +</tr> +<tr> +<td>\arg</td> +<td>prepended with ' --'</td> +</tr> +<tr> +<td>\author</td> +<td>prints 'Author:'</td> +</tr> +<tr> +<td>\authors</td> +<td>prints 'Author:'</td> +</tr> +<tr> +<td>\b</td> +<td>wrapped with '__'</td> +</tr> +<tr> +<td>\cite</td> +<td>wrapped with single quotes</td> +</tr> +<tr> +<td>\cond</td> +<td>translated to 'Conditional comment: <condition>'</td> +</tr> +<tr> +<td>\copyright</td> +<td>prints 'Copyright:'</td> +</tr> +<tr> +<td>\deprecated</td> +<td>prints 'Deprecated:'</td> +</tr> +<tr> +<td>\e</td> +<td>wrapped with '_'</td> +</tr> +<tr> +<td>\else</td> +<td>replaced with '}Else:{'</td> +</tr> +<tr> +<td>\elseif</td> +<td>replaced with '}Else if: <condition>{'</td> +</tr> +<tr> +<td>\em</td> +<td>wrapped with '_'</td> +</tr> +<tr> +<td>\endcond</td> +<td>replaced with 'End of conditional comment.'</td> +</tr> +<tr> +<td>\endif</td> +<td>replaced with '}'</td> +</tr> +<tr> +<td>\exception</td> +<td>replaced with 'Throws:'</td> +</tr> +<tr> +<td>\if</td> +<td>replaced with 'If: <condition> {'</td> +</tr> +<tr> +<td>\ifnot</td> +<td>replaced with 'If not: <condition> {'</td> +</tr> +<tr> +<td>\li</td> +<td>prepended with ' --'</td> +</tr> +<tr> +<td>\n</td> +<td>replaced with new line char</td> +</tr> +<tr> +<td>\note</td> +<td>replaced with 'Note:'</td> +</tr> +<tr> +<td>\overload</td> +<td>prints 'This is an overloaded ...' according to Doxygen docs</td> +</tr> +<tr> +<td>\par</td> +<td>replaced with 'Title: ...'</td> +</tr> +<tr> +<td>\param</td> +<td>translated to 'Arguments:\n param(type) --description'</td> +</tr> +<tr> +<td>\remark</td> +<td>replaced with 'Remarks:'</td> +</tr> +<tr> +<td>\remarks</td> +<td>replaced with 'Remarks:'</td> +</tr> +<tr> +<td>\result</td> +<td>replaced with 'Result:'</td> +</tr> +<tr> +<td>\return</td> +<td>replaced with 'Result:'</td> +</tr> +<tr> +<td>\returns</td> +<td>replaced with 'Result:'</td> +</tr> +<tr> +<td>\sa</td> +<td>replaced with 'See also:'</td> +</tr> +<tr> +<td>\see</td> +<td>replaced with 'See also:'</td> +</tr> +<tr> +<td>\since</td> +<td>replaced with 'Since:'</td> +</tr> +<tr> +<td>\throw</td> +<td>replaced with 'Throws:'</td> +</tr> +<tr> +<td>\throws</td> +<td>replaced wih 'Throws:'</td> +</tr> +<tr> +<td>\todo</td> +<td>replaced with 'TODO:'</td> +</tr> +<tr> +<td>\tparam</td> +<td>translated to 'Arguments:\n param(type) --description'</td> +</tr> +<tr> +<td>\version</td> +<td>replaced with 'Version:'</td> +</tr> +<tr> +<td>\warning</td> +<td>translated to 'Warning:'</td> +</tr> +<tr> +<td>\$</td> +<td>prints $ char</td> +</tr> +<tr> +<td>\@</td> +<td>prints @ char</td> +</tr> +<tr> +<td>\\</td> +<td>prints \ char</td> +</tr> +<tr> +<td>\&</td> +<td>prints & char</td> +</tr> +<tr> +<td>\~</td> +<td>prints ~ char</td> +</tr> +<tr> +<td>\<</td> +<td>prints < char</td> +</tr> +<tr> +<td>\></td> +<td>prints > char</td> +</tr> +<tr> +<td>\#</td> +<td>prints # char</td> +</tr> +<tr> +<td>\%</td> +<td>prints % char</td> +</tr> +<tr> +<td>\"</td> +<td>prints " char</td> +</tr> +<tr> +<td>\.</td> +<td>prints . character</td> +</tr> +<tr> +<td>\::</td> +<td>prints ::</td> +</tr> +</table> +</div> + +<H3><a name="Doxygen_python_unsupported_tags">17.4.3 Unsupported tags</a></H3> + + +<p> +Doxygen has a wealth of tags such as @latexonly that have no +equivalent in Pydoc. As a result several tags that have no +translation (or particular use, such as some linking and section tags) +are suppressed with their content just printed out (if it has any +sense, typically text content). +Here is the list of these tags: +</p> +<div class="diagram"> +<table border="0" summary="Unsupported Python Doxygen Tags"> +<tr> + <th align="left">Unsupported Doxygen tags</th> +</tr> +<tr> +<td>\addindex</td> +<td>\addtogroup</td> +<td>\anchor</td> +<td>\attention</td> +</tr> +<tr> +<td>\brief</td> +<td>\bug</td> +<td>\callgraph</td> +<td>\callergraph</td> +</tr> +<tr> +<td>\class</td> +<td>\copybrief</td> +<td>\copydetails</td> +<td>\copydoc</td> +</tr> +<tr> +<td>\date</td> +<td>\def</td> +<td>\defgroup</td> +<td>\details</td> +</tr> +<tr> +<td>\dir</td> +<td>\dontinclude</td> +<td>\dot</td> +<td>\dotfile</td> +</tr> +<tr> +<td>\code</td> +<td>\endcode</td> +<td>\endverbatim</td> +<td>\endlink</td> +</tr> +<tr> +<td>\enddot</td> +<td>\endhtmlonly</td> +<td>\endinternal</td> +<td>\endlatexonly</td> +</tr> +<tr> +<td>\endmanonly</td> +<td>\endmsc</td> +<td>\endrtfonly</td> +<td>\endxmlonly</td> +</tr> +<tr> +<td>\enum</td> +<td>\example</td> +<td>\extends</td> +<td>\f$</td> +</tr> +<tr> +<td>\f[</td> +<td>\f]</td> +<td>\f{</td> +<td>\f}</td> +</tr> +<tr> +<td>\file</td> +<td>\fn</td> +<td>\headerfile</td> +<td>\hideinitializer</td> +</tr> +<tr> +<td>\htmlinclude</td> +<td>\htmlonly</td> +<td>\implements</td> +<td>\include</td> +</tr> +<tr> +<td>\image</td> +<td>\link</td> +<td>\verbatim</td> +<td>\p</td> +</tr> +<tr> +<td>\includelineno</td> +<td>\ingroup</td> +<td>\internal</td> +<td>\invariant</td> +</tr> +<tr> +<td>\interface</td> +<td>\latexonly</td> +<td>\line</td> +<td>\mainpage</td> +</tr> +<tr> +<td>\manonly</td> +<td>\memberof</td> +<td>\msc</td> +<td>\mscfile</td> +</tr> +<tr> +<td>\name</td> +<td>\namespace</td> +<td>\nosubgrouping</td> +<td>\package</td> +</tr> +<tr> +<td>\page</td> +<td>\paragraph</td> +<td>\post</td> +<td>\pre</td> +</tr> +<tr> +<td>\private</td> +<td>\privatesection</td> +<td>\property</td> +<td>\protected</td> +</tr> +<tr> +<td>\protectedsection</td> +<td>\protocol</td> +<td>\public</td> +<td>\publicsection</td> +</tr> +<tr> +<td>\ref</td> +<td>\related</td> +<td>\relates</td> +<td>\relatedalso</td> +</tr> +<tr> +<td>\relatesalso</td> +<td>\retval</td> +<td>\rtfonly</td> +<td>\section</td> +</tr> +<tr> +<td>\short</td> +<td>\showinitializer</td> +<td>\skip</td> +<td>\skipline</td> +</tr> +<tr> +<td>\snippet</td> +<td>\struct</td> +<td>\subpage</td> +<td>\subsection</td> +</tr> +<tr> +<td>\subsubsection</td> +<td>\tableofcontents</td> +<td>\test</td> +<td>\typedef</td> +</tr> +<tr> +<td>\union</td> +<td>\until</td> +<td>\var</td> +<td>\verbinclude</td> +</tr> +<tr> +<td>\weakgroup</td> +<td>\xmlonly</td> +<td>\xrefitem</td> +<td>\category</td> +</tr> +<tr> +<td>\c</td> +</tr> +</table> +</div> + +<H3><a name="Doxygen_python_further_details">17.4.4 Further details</a></H3> + + +<p> +TO BE ADDED. +</p> + +<H2><a name="Doxygen_troubleshooting">17.5 Troubleshooting</a></H2> + + +<p> +When running SWIG with command line option <tt>-doxygen</tt>, it may happen +that SWIG will fail to parse the code, which is valid C++ code and +is parsed without problems without the option. The problem is, +that Doxygen comments are not tokens (the C/C++ compiler actually never +sees them) and that they can appear anywhere in the code. That's why it is +practically impossible to handle all corner cases with the parser. +However, these problems can usually be avoided by minor changes in the +code or comment. Known problems and solutions are shown in this section. +</p> + + +<p> +Recommended approach is to first run SWIG without command line +option <tt>-doxygen</tt>. When it successfully processes the code, +include the option and fix problems with Doxygen comments. +</p> + + +<H3><a name="troubleshooting_ifndef">17.5.1 Problem with conditional compilation</a></H3> + + +<p> + Inserting a conditional compilation preprocessor directive between a + Doxygen comment and a commented item may break parsing: +</p> + + +<div class="code"><pre> +class A { + /** + * Some func. + */ + <font color='#ff0000'>#ifndef SWIG</font> + void myfunc() + { + } + #endif +}; +</pre></div> + +<p> + The solution is to move the directive above the comment: +</p> + +<div class="code"><pre> +class A { + <font color='#00d000'>#ifndef SWIG</font> + /** + * Some func. + */ + void myfunc() + { + } + #endif +}; +</pre></div> + + +<H2><a name="Doxygen_developer_details">17.6 Developer information</a></H2> + + +<p> +This section contains information for developers enhancing the Doxygen translator. +</p> + +<H3><a name="Doxygen_translator_design">17.6.1 Doxygen translator design</a></H3> + + +<p> +If this functionality is turned on, SWIG places all comments found +into the SWIG parse tree. Nodes contain an additional attribute +called <tt>doxygen</tt> when a comment is present. Individual nodes +containing Doxygen with Structural Indicators, such as @file, as their +first command, are also present in the parse tree. These individual +"blobs" of Doxygen such as : +</p> +<div class="code"><pre> +/*! This is describing function Foo + \param x some random variable + \author Bob + \return Foo + */ +</pre></div> + +<p> +are passed on individually to the Doxygen Translator module. This +module builds its own private parse tree and hands it to a separate +class for translation into the target documentation language. For +example, <tt>JavaDocConverter</tt> is the Javadoc module class. +</p> + +<H3><a name="Doxygen_debugging_commands">17.6.2 Debugging the Doxygen parser and translator</a></H3> + + +<p> +There are two handy command line options, that enable lots of +detailed debug information printing. +</p> + +<div class="shell"><pre> + -debug-doxygen-parser - Display Doxygen parser module debugging information + -debug-doxygen-translator - Display Doxygen translator module debugging information +</pre></div> + +<H3><a name="Doxygen_tests">17.6.3 Tests</a></H3> + + +<p> +Doxygen tests have been added to the regular SWIG test-suite. +There are a number of tests beginning <tt>doxygen_</tt> in the Examples/test-suite sub-directory. +</p> + +<p> +Like any other SWIG test case, the tests are included in Examples/test-suite/common.mk and can be tested with +commands like <tt>make check-test-suite</tt> or <tt>make check-python-test-suite</tt>. +To run them individually, type +<tt>make -s <testname>.cpptest</tt> in the language-specific sub-directory in +<tt>Examples/test-suite</tt> directory. For example: +</p> + +<div class="shell"><pre> + Examples/test-suite/java $ make -s doxygen_parsing.cpptest +</pre></div> + +<p> +If the test fails, both expected and translated comments are printed to +std out, but also written to files <i>expected.txt</i> +and <i>got.txt</i>. Since it is often difficult to find a single +character difference in several lines of text, we can use some diff +tool, for example: +</p> + +<div class="shell"><pre> + Examples/test-suite/java $ kdiff3 expected.txt got.txt +</pre></div> + + +<p> +Runtime tests in Java are implemented using Javadoc doclets. To make that work, you +should have tools.jar from the JDK in your classpath. Or you should have JAVA_HOME +environment variable defined and pointing to the JDK location. +</p> +<p> +The Java's comment parsing code (the testing part) is located in commentParser.java. +It checks the generated code. It is possible +to run this file as a stand-alone program, with <tt>java commentParser <some java package></tt>, +and it will print the list of comments found in the specified directory (in the format it has used +in the runtime tests). So, when you want to create a new Doxygen test case, +just copy an existing one and replace the actual comment content (section of entries in +form 'wantedComments.put(...)' with the output of the above command. +</p> +<p> +Runtime tests in Python are just plain string comparisons of the __doc__ +properties. +</p> + +<H2><a name="Doxygen_language_extension">17.7 Extending to other languages</a></H2> + + +<p> +In general, an extension to another language requires a fairly deep understanding of the target language module, such as Modules/python.cxx for Python. +Searching for "doxygen" in the java.cxx module can give you a good idea of the process for placing documentation comments into the correct areas. +The basic gist is that anywhere a comment may reside on a node, there needs to be a catch for it in front of where that function, class, or other object is written out to a target language file. +The other half of extension is building a target documentation language comment generator that handles one blob at a time. +However, this is relatively simple and nowhere near as complex as the wrapper generating modules in SWIG. +See Source/Doxygen/javadoc.cxx for a good example. +The target language module passes the Doxygen Translator the blob to translate, and receives back the translated text. +</p> +<p> +<b> What is given to the Doxygen Translator</b> +</p> +<div class="code"><pre> +/*! This is describing function Foo + \param x some random variable + \author Bob + \return Foo + */ +</pre></div> +<p> +<b> What is received back by java.cxx </b> +</p> +<div class="targetlang"><pre> +/** This is describing function Foo + * + * @param x some random variable + * @author Bob + * @return Foo + */ +</pre></div> +<p> Development of the comment translator itself is simplified by the fact that the Doxygen Translator module can easily include a <tt>main</tt> function and thus be developed, compiled, and tested independently of SWIG. +</p> + +</body> +</html> diff --git a/Doc/Manual/Extending.html b/Doc/Manual/Extending.html index 80fe77d4d..5a640fbdc 100644 --- a/Doc/Manual/Extending.html +++ b/Doc/Manual/Extending.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Extending">41 Extending SWIG to support new languages</a></H1> +<H1><a name="Extending">39 Extending SWIG to support new languages</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -64,8 +64,13 @@ <li><a href="#Extending_running_test_suite">Running the test-suite</a> </ul> <li><a href="#Extending_nn43">Documentation</a> -<li><a href="#Extending_prerequisites">Prerequisites for adding a new language module to the SWIG distribution</a> <li><a href="#Extending_coding_style_guidelines">Coding style guidelines</a> +<li><a href="#Extending_language_status">Target language status</a> +<ul> +<li><a href="#Extending_supported_status">Supported status</a> +<li><a href="#Extending_experimental_status">Experimental status</a> +</ul> +<li><a href="#Extending_prerequisites">Prerequisites for adding a new language module to the SWIG distribution</a> </ul> <li><a href="#Extending_debugging_options">Debugging Options</a> <li><a href="#Extending_nn46">Guide to parse tree nodes</a> @@ -76,7 +81,7 @@ -<H2><a name="Extending_nn2">41.1 Introduction</a></H2> +<H2><a name="Extending_nn2">39.1 Introduction</a></H2> <p> @@ -92,7 +97,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">41.2 Prerequisites</a></H2> +<H2><a name="Extending_nn3">39.2 Prerequisites</a></H2> <p> @@ -122,7 +127,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">41.3 The Big Picture</a></H2> +<H2><a name="Extending_nn4">39.3 The Big Picture</a></H2> <p> @@ -159,7 +164,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">41.4 Execution Model</a></H2> +<H2><a name="Extending_nn5">39.4 Execution Model</a></H2> <p> @@ -204,7 +209,7 @@ latter stage of compilation. The next few sections briefly describe some of these stages. </p> -<H3><a name="Extending_nn6">41.4.1 Preprocessing</a></H3> +<H3><a name="Extending_nn6">39.4.1 Preprocessing</a></H3> <p> @@ -278,14 +283,14 @@ or <tt>perl5.swg</tt>. </p> <p> -As a debugging aide, the text that SWIG feeds to its C++ parser can be +As a debugging aid, the text that SWIG feeds to its C++ parser can be obtained by running <tt>swig -E interface.i</tt>. This output probably isn't too useful in general, but it will show how macros have been expanded as well as everything else that goes into the low-level construction of the wrapper code. </p> -<H3><a name="Extending_nn7">41.4.2 Parsing</a></H3> +<H3><a name="Extending_nn7">39.4.2 Parsing</a></H3> <p> @@ -386,7 +391,7 @@ returning a <tt>foo</tt> and taking types <tt>a</tt> and <tt>b</tt> as arguments). </p> -<H3><a name="Extending_nn8">41.4.3 Parse Trees</a></H3> +<H3><a name="Extending_nn8">39.4.3 Parse Trees</a></H3> <p> @@ -641,7 +646,7 @@ $ swig -c++ -python -debug-module 4 example.i </pre> </div> -<H3><a name="Extending_nn9">41.4.4 Attribute namespaces</a></H3> +<H3><a name="Extending_nn9">39.4.4 Attribute namespaces</a></H3> <p> @@ -660,7 +665,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">41.4.5 Symbol Tables</a></H3> +<H3><a name="Extending_nn10">39.4.5 Symbol Tables</a></H3> <p> @@ -729,7 +734,7 @@ For instance, the following example uses <tt>%rename</tt> in reverse to generate <div class="code"> <pre> %rename(foo) foo_i(int); -%rename(foo) foo_d(double; +%rename(foo) foo_d(double); void foo_i(int); void foo_d(double); @@ -751,7 +756,7 @@ example.i:5. Previous declaration is foo_i(int ) </pre> </div> -<H3><a name="Extending_nn11">41.4.6 The %feature directive</a></H3> +<H3><a name="Extending_nn11">39.4.6 The %feature directive</a></H3> <p> @@ -807,7 +812,7 @@ For example, the exception code above is simply stored without any modifications. </p> -<H3><a name="Extending_nn12">41.4.7 Code Generation</a></H3> +<H3><a name="Extending_nn12">39.4.7 Code Generation</a></H3> <p> @@ -929,7 +934,7 @@ public : The role of these functions is described shortly. </p> -<H3><a name="Extending_nn13">41.4.8 SWIG and XML</a></H3> +<H3><a name="Extending_nn13">39.4.8 SWIG and XML</a></H3> <p> @@ -942,7 +947,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">41.5 Primitive Data Structures</a></H2> +<H2><a name="Extending_nn14">39.5 Primitive Data Structures</a></H2> <p> @@ -988,7 +993,7 @@ typedef Hash Typetab; </pre> </div> -<H3><a name="Extending_nn15">41.5.1 Strings</a></H3> +<H3><a name="Extending_nn15">39.5.1 Strings</a></H3> <p> @@ -1129,7 +1134,7 @@ Returns the number of replacements made (if any). </div> -<H3><a name="Extending_nn16">41.5.2 Hashes</a></H3> +<H3><a name="Extending_nn16">39.5.2 Hashes</a></H3> <p> @@ -1206,7 +1211,7 @@ Returns the list of hash table keys. </div> -<H3><a name="Extending_nn17">41.5.3 Lists</a></H3> +<H3><a name="Extending_nn17">39.5.3 Lists</a></H3> <p> @@ -1295,7 +1300,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">41.5.4 Common operations</a></H3> +<H3><a name="Extending_nn18">39.5.4 Common operations</a></H3> The following operations are applicable to all datatypes. @@ -1350,7 +1355,7 @@ objects and report errors. Gets the line number associated with <tt>x</tt>. </div> -<H3><a name="Extending_nn19">41.5.5 Iterating over Lists and Hashes</a></H3> +<H3><a name="Extending_nn19">39.5.5 Iterating over Lists and Hashes</a></H3> To iterate over the elements of a list or a hash table, the following functions are used: @@ -1395,7 +1400,7 @@ for (j = First(j); j.item; j= Next(j)) { </div> -<H3><a name="Extending_nn20">41.5.6 I/O</a></H3> +<H3><a name="Extending_nn20">39.5.6 I/O</a></H3> Special I/O functions are used for all internal I/O. These operations @@ -1529,7 +1534,7 @@ Printf(f, "%s\n", s); Similarly, the preprocessor and parser all operate on string-files. </p> -<H2><a name="Extending_nn21">41.6 Navigating and manipulating parse trees</a></H2> +<H2><a name="Extending_nn21">39.6 Navigating and manipulating parse trees</a></H2> Parse trees are built as collections of hash tables. Each node is a hash table in which @@ -1576,7 +1581,7 @@ return the node for the first class member. <div class="indent"> Returns the last child node. You might use this if you wanted to append a new -node to the of a class. +node to the children of a class. </div> <p> @@ -1663,7 +1668,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">41.7 Working with attributes</a></H2> +<H2><a name="Extending_nn22">39.7 Working with attributes</a></H2> <p> @@ -1780,7 +1785,7 @@ the attribute is optional. <tt>Swig_restore()</tt> must always be called after function. </div> -<H2><a name="Extending_nn23">41.8 Type system</a></H2> +<H2><a name="Extending_nn23">39.8 Type system</a></H2> <p> @@ -1789,7 +1794,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">41.8.1 String encoding of types</a></H3> +<H3><a name="Extending_nn24">39.8.1 String encoding of types</a></H3> <p> @@ -1890,7 +1895,7 @@ make the final type, the two parts are just joined together using string concatenation. </p> -<H3><a name="Extending_nn25">41.8.2 Type construction</a></H3> +<H3><a name="Extending_nn25">39.8.2 Type construction</a></H3> <p> @@ -2059,7 +2064,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">41.8.3 Type tests</a></H3> +<H3><a name="Extending_nn26">39.8.3 Type tests</a></H3> <p> @@ -2146,7 +2151,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">41.8.4 Typedef and inheritance</a></H3> +<H3><a name="Extending_nn27">39.8.4 Typedef and inheritance</a></H3> <p> @@ -2248,7 +2253,7 @@ Fully reduces <tt>ty</tt> according to typedef rules. Resulting datatype will consist only of primitive typenames. </div> -<H3><a name="Extending_nn28">41.8.5 Lvalues</a></H3> +<H3><a name="Extending_nn28">39.8.5 Lvalues</a></H3> <p> @@ -2285,7 +2290,7 @@ Literal y; // type = 'Literal', ltype='p.char' </pre> </div> -<H3><a name="Extending_nn29">41.8.6 Output functions</a></H3> +<H3><a name="Extending_nn29">39.8.6 Output functions</a></H3> <p> @@ -2347,7 +2352,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">41.9 Parameters</a></H2> +<H2><a name="Extending_nn30">39.9 Parameters</a></H2> <p> @@ -2446,7 +2451,7 @@ included. Used to emit prototypes. Returns the number of required (non-optional) arguments in <tt>p</tt>. </div> -<H2><a name="Extending_nn31">41.10 Writing a Language Module</a></H2> +<H2><a name="Extending_nn31">39.10 Writing a Language Module</a></H2> <p> @@ -2461,7 +2466,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">41.10.1 Execution model</a></H3> +<H3><a name="Extending_nn32">39.10.1 Execution model</a></H3> <p> @@ -2471,7 +2476,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">41.10.2 Starting out</a></H3> +<H3><a name="Extending_starting_out">39.10.2 Starting out</a></H3> <p> @@ -2579,7 +2584,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">41.10.3 Command line options</a></H3> +<H3><a name="Extending_nn34">39.10.3 Command line options</a></H3> <p> @@ -2592,36 +2597,36 @@ command line options, simply use code similar to this: <pre> void Language::main(int argc, char *argv[]) { for (int i = 1; i < argc; i++) { - if (argv[i]) { - if (strcmp(argv[i], "-interface") == 0) { - if (argv[i+1]) { - interface = NewString(argv[i+1]); - Swig_mark_arg(i); - Swig_mark_arg(i+1); - i++; - } else { - Swig_arg_error(); - } - } else if (strcmp(argv[i], "-globals") == 0) { - if (argv[i+1]) { - global_name = NewString(argv[i+1]); - Swig_mark_arg(i); - Swig_mark_arg(i+1); - i++; - } else { - Swig_arg_error(); - } - } else if ((strcmp(argv[i], "-proxy") == 0)) { - proxy_flag = 1; - Swig_mark_arg(i); - } else if (strcmp(argv[i], "-keyword") == 0) { - use_kw = 1; - Swig_mark_arg(i); - } else if (strcmp(argv[i], "-help") == 0) { - fputs(usage, stderr); - } - ... + if (argv[i]) { + if (strcmp(argv[i], "-interface") == 0) { + if (argv[i+1]) { + interface = NewString(argv[i+1]); + Swig_mark_arg(i); + Swig_mark_arg(i+1); + i++; + } else { + Swig_arg_error(); + } + } else if (strcmp(argv[i], "-globals") == 0) { + if (argv[i+1]) { + global_name = NewString(argv[i+1]); + Swig_mark_arg(i); + Swig_mark_arg(i+1); + i++; + } else { + Swig_arg_error(); + } + } else if ((strcmp(argv[i], "-proxy") == 0)) { + proxy_flag = 1; + Swig_mark_arg(i); + } else if (strcmp(argv[i], "-keyword") == 0) { + use_kw = 1; + Swig_mark_arg(i); + } else if (strcmp(argv[i], "-help") == 0) { + fputs(usage, stderr); } + ... + } } } </pre> @@ -2638,7 +2643,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">41.10.4 Configuration and preprocessing</a></H3> +<H3><a name="Extending_nn35">39.10.4 Configuration and preprocessing</a></H3> <p> @@ -2687,7 +2692,7 @@ an implementation file <tt>python.cxx</tt> and a configuration file <tt>python.swg</tt>. </p> -<H3><a name="Extending_nn36">41.10.5 Entry point to code generation</a></H3> +<H3><a name="Extending_nn36">39.10.5 Entry point to code generation</a></H3> <p> @@ -2745,7 +2750,7 @@ int Python::top(Node *n) { </pre> </div> -<H3><a name="Extending_nn37">41.10.6 Module I/O and wrapper skeleton</a></H3> +<H3><a name="Extending_nn37">39.10.6 Module I/O and wrapper skeleton</a></H3> <!-- please report bugs in this section to mgossage --> @@ -2893,7 +2898,7 @@ functionWrapper : void Shape_y_set(Shape *self, double y) </pre> </div> -<H3><a name="Extending_nn38">41.10.7 Low-level code generators</a></H3> +<H3><a name="Extending_nn38">39.10.7 Low-level code generators</a></H3> <!-- please report bugs in this section to mgossage --> @@ -3026,7 +3031,7 @@ virtual int functionWrapper(Node *n) { /* Close the function(error) */ Printv(wrapper->code, "return ERROR;\n", "}\n", NIL); - /* final substititions if applicable */ + /* final substitutions if applicable */ ... /* Dump the function out */ @@ -3047,7 +3052,7 @@ but without the typemaps, there is still work to do. </p> -<H3><a name="Extending_configuration_files">41.10.8 Configuration files</a></H3> +<H3><a name="Extending_configuration_files">39.10.8 Configuration files</a></H3> <!-- please report bugs in this section to ttn --> @@ -3164,7 +3169,7 @@ these kinds of problems. </p> <dt> <b>Examples/Makefile.in</b> -<dd> Nothing special here; see comments at top the of this file +<dd> Nothing special here; see comments at the top of this file and look to the existing languages for examples. <dt> <b>Examples/qux99/check.list</b> @@ -3191,7 +3196,7 @@ politely displays the ignoring language message. </dl> -<H3><a name="Extending_nn40">41.10.9 Runtime support</a></H3> +<H3><a name="Extending_nn40">39.10.9 Runtime support</a></H3> <p> @@ -3200,7 +3205,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">41.10.10 Standard library files</a></H3> +<H3><a name="Extending_nn41">39.10.10 Standard library files</a></H3> <p> @@ -3219,7 +3224,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">41.10.11 User examples</a></H3> +<H3><a name="Extending_nn42">39.10.11 User examples</a></H3> <p> @@ -3248,7 +3253,7 @@ during this process, see the section on <a href="#Extending_configuration_files" files</a>. </p> -<H3><a name="Extending_test_suite">41.10.12 Test driven development and the test-suite</a></H3> +<H3><a name="Extending_test_suite">39.10.12 Test driven development and the test-suite</a></H3> <p> @@ -3307,7 +3312,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">41.10.12.1 Running the test-suite</a></H4> +<H4><a name="Extending_running_test_suite">39.10.12.1 Running the test-suite</a></H4> <p> @@ -3499,7 +3504,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">41.10.13 Documentation</a></H3> +<H3><a name="Extending_nn43">39.10.13 Documentation</a></H3> <p> @@ -3531,27 +3536,172 @@ Some topics that you'll want to be sure to address include: if available. </ul> -<H3><a name="Extending_prerequisites">41.10.14 Prerequisites for adding a new language module to the SWIG distribution</a></H3> +<H3><a name="Extending_coding_style_guidelines">39.10.14 Coding style guidelines</a></H3> + + +<p> +The coding guidelines for the C/C++ source code are pretty much K&R C style. +The style can be inferred from the existing code base and is +largely dictated by the <tt>indent</tt> code beautifier tool set to K&R style. +The code can formatted using the make targets in the Source directory. +Below is an example of how to format the emit.cxx file: +</p> + +<blockquote> +<pre> +$ cd Source +$ make beautify-file INDENTFILE=Modules/emit.cxx +</pre> +</blockquote> + +<p> +Of particular note is indentation is set to 2 spaces and a tab is used instead of 8 spaces. +The generated C/C++ code should also follow this style as close as possible. However, tabs +should be avoided as unlike the SWIG developers, users will never have consistent tab settings. +</p> + + +<H3><a name="Extending_language_status">39.10.15 Target language status</a></H3> + + +<p> +Target languages are given a status of either 'Supported' or 'Experimental' depending on their maturity as broadly outlined in +the <a href="Introduction.html#Introduction_target_languages">Target language introduction</a>. +This section provides more details on how this status is given. +</p> + +<H4><a name="Extending_supported_status">39.10.15.1 Supported status</a></H4> + + +<p> +A target language is given the 'Supported' status when +</p> + +<ul> +<li> + It is in a mature, well functioning state. +</li> +<li> + It has its own comprehensive chapter in the documentation. + The level of documentation should be comprehensive and match the standard of the other mature modules. + Python and Java are good references.</li> +<li> + It passes all of the main SWIG test-suite. + The main test-suite is defined by the tests in the C_TEST_CASES, CPP_TEST_CASES and MULTI_CPP_TEST_CASES lists in Examples/test-suite/common.mk. + The tests in CPP11_TEST_CASES will also be required in the near future. +</li> +<li> + The test-suite must also include at least twenty wide-ranging runtime tests. + The most mature languages have a few hundred runtime tests. + Note that porting runtime tests from another language module is a quick and easy way to achieve this. +</li> +<li> + It supports the vast majority of SWIG features. + Some more advanced features, such as, directors, full nested class support and target language namespaces (nspace) may be unimplemented. + A few support libraries may be missing, for example, a small number of STL libraries.</li> +<li> + It provides strong backwards compatibility between releases. + Each point release must aim to be fully backwards compatible. + A point release version is the 3rd version digit, so each of the x.y.* versions should be backwards compatible. + Backwards compatibility breakages can occur in a new major or minor version if absolutely necessary and if documented. + A major or minor version is the first or second digit in the three digit version. +</li> +<li> + Fixing unintended regressions in the Supported languages will be given higher priority over experimental languages by the core SWIG developers. +</li> +<li> + Examples must be available and run successfully. +</li> +<li> + The examples and test-suite must be fully functioning on the Travis Continuous Integration platform. +</li> +</ul> + +<H4><a name="Extending_experimental_status">39.10.15.2 Experimental status</a></H4> <p> -If you wish for a new language module to be distributed with SWIG, -which we encourage for all popular languages, there are a few requirements. -While we appreciate that getting all aspects of a new language working -won't happen at the outset, there are a set of minimum requirements before -a module can be committed into the official Github repository for distribution with future -versions of SWIG. The following are really a summary of this whole section with -details being outlined earlier on. +A target language is given the 'Experimental' status when +</p> + +<ul> +<li> + It is of sub-standard quality, failing to meet the above 'Supported' status. +</li> +<li> + It is somewhere between the mid to mature stage of development. +</li> +<li> + It is in need of help to finish development. +</li> +</ul> + +<p> +Some minimum requirements and notes about languages with the 'Experimental' status: +</p> + +<ul> +<li> + Will at least implement basic functionality - support wrapping C functions and simple C++ classes and templates. +</li> +<li> + Have its own documentation chapter containing a reasonable level of detail. + The documentation must provide enough basic functionality for a user to get started. +</li> +<li> + Have fully functional examples of basic functionality (the simple and class examples). +</li> +<li> + The test-suite must be implemented and include a few runtime tests for both C and C++ test cases. +</li> +<li> + Failing tests must be put into one of the FAILING_CPP_TESTS or FAILING_C_TESTS lists in the test-suite. + This will ensure the test-suite can be superficially made to pass by ignoring failing tests. + The number of tests in these lists should be no greater than half of the number of tests in the full test-suite. +</li> +<li> + The examples and test-suite must also be fully functioning on the Travis Continuous Integration platform. + However, experimental languages will be set as 'allow_failures'. + This means that pull requests and normal development commits will not break the entire Travis build should an experimental language fail. +</li> +<li> + Any new failed tests will be fixed on a 'best effort' basis by core developers with no promises made. +</li> +<li> + If a language module has an official maintainer, then the maintainer will be requested to focus on fixing test-suite regressions and commit to migrating the module to become a 'Supported' module. +</li> +<li> + If a module does not have an official maintainer, then, as maintenance will be on a 'best efforts' basis by the core maintainers, no guarantees will be provided from one release to the next and regressions may creep in. +</li> +<li> + Experimental target languages will have a (suppressible) warning explaining the Experimental sub-standard status and encourage users to help improve it. +</li> +<li> + No backwards compatibility is guaranteed as the module is effectively 'in development'. + If a language module has an official maintainer, then a backwards compatibility guarantee may be provided at the maintainer's discretion and should be documented as such. +</li> +</ul> + +<H3><a name="Extending_prerequisites">39.10.16 Prerequisites for adding a new language module to the SWIG distribution</a></H3> + + +<p> +New target language modules can be included in SWIG and contributions are encouraged for popular languages. +In order to be considered for inclusion, a language must at a minimum fit the 'Experimental' status described above. +</p> + +<p> +Below are some practical steps that should help meet these requirements. </p> <ol> <li> - Demonstrate basic C code working by porting the "simple" example including - a runtime test, see for example <tt>Examples/python/simple</tt>. + The "simple" example needs to be working to demonstrate basic C code wrappers. + Port the example from another language, such as from <tt>Examples/python/simple</tt>. </li> <li> - Demonstrate basic C++ code working by porting the "class" example including - a runtime test, see for example <tt>Examples/python/class</tt>. + The "class" example needs to be working to demonstrate basic C++ code wrappers. + Port the example from another language, such as from <tt>Examples/python/class</tt>. </li> <li> Modify <tt>configure.ac</tt>, <tt>Makefile.in</tt> and <tt>Examples/Makefile.in</tt> to run @@ -3560,21 +3710,27 @@ details being outlined earlier on. skipping the tests and examples for the new language module. </li> <li> - Get the test-suite running for the new language (<tt>make check-[lang]-test-suite</tt>). + Copying an existing language module and adapting the source for it is likely to be the most efficient + approach to fully developing a new module as a number of corner cases are covered in the existing implementations. + The most advanced scripting languages are Python and Ruby. + The most advanced compiled target languages are Java and C#. + </li> + <li> + Get the <a href="#Extending_running_test_suite">test-suite</a> running for the new language (<tt>make check-[lang]-test-suite</tt>). While the test-suite tests many corner cases, - we'd expect the majority of it to work by compiling the generated code - correctly as most of the corner cases are covered in the SWIG core. Get - at least one C and one C++ runtime test running in the test-suite. + we'd expect the majority of it to work without much effort once the generated code is compiling + correctly for basic functionality as most of the corner cases are covered in the SWIG core. Aim to first get + one C and one C++ runtime test running in the test-suite. + Adding further runtime tests should be a lot easier afterwards by porting existing runtime tests from another language module. </li> <li> - Provide a chapter in the html documentation on the basics of using - the language module. + The structure and contents of the html documentation chapter can be copied and adapted from one of the other language modules. </li> <li> - Ensure your source code is formatted according to the <a href="#Extending_coding_style_guidelines">coding style guidelines</a>. + Source code can be formatted correctly using the info in the <a href="#Extending_coding_style_guidelines">coding style guidelines</a> section. </li> <li> - Finally, email the SWIG developers with a patch and a demonstration of + When ready, post a patch on Github, join the swig-devel mailing list and email the SWIG developers with a demonstration of commitment to maintaining the language module, certainly in the short term and ideally long term. </li> @@ -3582,37 +3738,15 @@ details being outlined earlier on. <p> Once accepted into the official Git repository, development efforts should concentrate on -getting the entire test-suite to work with plenty of runtime tests. -Runtime tests should be for existing testcases and new test cases -should be added should there be an area not already covered by +getting the entire test-suite to work +in order to migrate the language module to the 'Supported' status. +Runtime tests should be added for existing testcases and new test cases +can be added should there be an area not already covered by the existing tests. </p> -<H3><a name="Extending_coding_style_guidelines">41.10.15 Coding style guidelines</a></H3> - - -<p> -The coding guidelines for the C/C++ source code are pretty much K&R C style. -The style can be inferred from the existing code base and is -largely dictated by the <tt>indent</tt> code beautifier tool set to K&R style. -The code can formatted using the make targets in the Source directory. -Below is an example of how to format the emit.cxx file: -</p> - -<blockquote> -<pre> -$ cd Source -$ make beautify-file INDENTFILE=Modules/emit.cxx -</pre> -</blockquote> - -<p> -Of particular note is indentation is set to 2 spaces and a tab is used instead of 8 spaces. -The generated C/C++ code should also follow this style as close as possible. However, tabs -should be avoided as unlike the SWIG developers, users will never have consistent tab settings. -</p> -<H2><a name="Extending_debugging_options">41.11 Debugging Options</a></H2> +<H2><a name="Extending_debugging_options">39.11 Debugging Options</a></H2> <p> @@ -3639,7 +3773,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">41.12 Guide to parse tree nodes</a></H2> +<H2><a name="Extending_nn46">39.12 Guide to parse tree nodes</a></H2> <p> @@ -4047,7 +4181,7 @@ extern "X" { ... } declaration. </pre> </div> -<H2><a name="Extending_further_info">41.13 Further Development Information</a></H2> +<H2><a name="Extending_further_info">39.13 Further Development Information</a></H2> <p> diff --git a/Doc/Manual/Go.html b/Doc/Manual/Go.html index f25e9850b..c28cc03e1 100644 --- a/Doc/Manual/Go.html +++ b/Doc/Manual/Go.html @@ -6,7 +6,7 @@ <meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head> <body bgcolor="#FFFFFF"> -<H1><a name="Go">23 SWIG and Go</a></H1> +<H1><a name="Go">24 SWIG and Go</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -57,7 +57,7 @@ the Go programming language see <a href="http://golang.org/">golang.org</a>. </p> -<H2><a name="Go_overview">23.1 Overview</a></H2> +<H2><a name="Go_overview">24.1 Overview</a></H2> <p> @@ -86,7 +86,7 @@ type-safe as well. In case of type issues the build will fail and hence SWIG's are not used. </p> -<H2><a name="Go_examples">23.2 Examples</a></H2> +<H2><a name="Go_examples">24.2 Examples</a></H2> <p> @@ -101,7 +101,7 @@ SWIG interface file extension for backwards compatibility with Go 1. </p> -<H2><a name="Go_running_swig">23.3 Running SWIG with Go</a></H2> +<H2><a name="Go_running_swig">24.3 Running SWIG with Go</a></H2> <p> @@ -125,16 +125,15 @@ Go distribution. To generate code for gccgo, you should also use the </p> <p> -When using the <tt>-cgo</tt> option, SWIG will generate files that can be used -directly by <tt>go build</tt>. Starting with the Go 1.5 distribution the -<tt>-cgo</tt> option has to be given. Put your SWIG interface file in a -directory under GOPATH/src, and give it a name that does <b>not</b> end in the -.swig or .swigcxx extension. Typically the SWIG interface file extension is .i -in this case. +By default SWIG will generate files that can be used directly +by <tt>go build</tt>. This requires Go 1.2 or later. Put your SWIG +interface file in a directory under GOPATH/src, and give it a name +that does <b>not</b> end in the .swig or .swigcxx extension. +Typically the SWIG interface file extension is .i in this case. </p> <div class="code"><pre> -% swig -go -cgo example.i +% swig -go example.i % go install </pre></div> @@ -144,15 +143,16 @@ usual. </p> <p> -To use SWIG without the <tt>-cgo</tt> option, more steps are required. Recall -that this only works with Go versions before 1.5. When using Go version 1.2 or -later, or when using gccgo, the code generated by SWIG can be linked directly -into the Go program. A typical command sequence when using the Go compiler of -the Go distribution would look like this: +SWIG can be used without cgo, via the <tt>-no-cgo</tt> option, but +more steps are required. This only works with Go versions before 1.5. +When using Go version 1.2 or later, or when using gccgo, the code +generated by SWIG can be linked directly into the Go program. A +typical command sequence when using the Go compiler of the Go +distribution would look like this: </p> <div class="code"><pre> -% swig -go example.i +% swig -go -no-cgo example.i % gcc -c code.c # The C library being wrapped. % gcc -c example_wrap.c % go tool 6g example.go @@ -169,7 +169,7 @@ sequence for this approach would look like this: </p> <div class="code"><pre> -% swig -go -use-shlib example.i +% swig -go -no-cgo -use-shlib example.i % gcc -c -fpic example.c % gcc -c -fpic example_wrap.c % gcc -shared example.o example_wrap.o -o example.so @@ -181,7 +181,7 @@ sequence for this approach would look like this: </pre></div> -<H3><a name="Go_commandline">23.3.1 Go-specific Commandline Options</a></H3> +<H3><a name="Go_commandline">24.3.1 Go-specific Commandline Options</a></H3> <p> @@ -200,10 +200,15 @@ swig -go -help <tr> <td>-cgo</td> -<td>Generate files to be used as input for the Go cgo tool. This - option is required for Go 1.5 and later, and works for Go 1.2 and - later. In the future this option will likely become the - default.</td> +<td>Generate files to be used as input for the Go cgo tool. This is + the default.</td> +</tr> + +<tr> +<td>-no-cgo</td> +<td>Generate files that can be used directly, rather than via the Go + cgo tool. This option does not work with Go 1.5 or later. It is + required for versions of Go before 1.2.</td> </tr> <tr> @@ -261,18 +266,25 @@ swig -go -help ignored.</td> </tr> +<tr> +<td>-import-prefix <prefix></td> +<td>A prefix to add when turning a %import prefix in the SWIG + interface file into an import statement in the Go file. For + example, with <code>-import-prefix mymodule</code>, a SWIG + interface file <code>%import mypackage</code> will become a Go + import statement <code>import "mymodule/mypackage"</code>.</td> </table> -<H3><a name="Go_outputs">23.3.2 Generated Wrapper Files</a></H3> +<H3><a name="Go_outputs">24.3.2 Generated Wrapper Files</a></H3> <p>There are two different approaches to generating wrapper files, - controlled by SWIG's <tt>-cgo</tt> option. The <tt>-cgo</tt> option - works with Go version 1.2 or later. It is required when using Go - version 1.5 or later.</p> + controlled by SWIG's <tt>-no-cgo</tt> option. The <tt>-no-cgo</tt> + option only works with version of Go before 1.5. It is required + when using versions of Go before 1.2.</p> -<p>With or without the <tt>-cgo</tt> option, SWIG will generate the +<p>With or without the <tt>-no-cgo</tt> option, SWIG will generate the following files when generating wrapper code:</p> <ul> @@ -296,8 +308,8 @@ or C++ compiler. </li> </ul> -<p>When neither the <tt>-cgo</tt> nor the <tt>-gccgo</tt> option is - used, SWIG will also generate an additional file:</p> +<p>When the <tt>-no-cgo</tt> option is used, and the <tt>-gccgo</tt> + option is not used, SWIG will also generate an additional file:</p> <ul> <li> @@ -308,7 +320,7 @@ combined with the compiled MODULE.go using go tool pack. </ul> -<H2><a name="Go_basic_tour">23.4 A tour of basic C/C++ wrapping</a></H2> +<H2><a name="Go_basic_tour">24.4 A tour of basic C/C++ wrapping</a></H2> <p> @@ -318,7 +330,7 @@ modifications have to occur. This section briefly covers the essential aspects of this wrapping. </p> -<H3><a name="Go_package">23.4.1 Go Package Name</a></H3> +<H3><a name="Go_package">24.4.1 Go Package Name</a></H3> <p> @@ -328,7 +340,7 @@ directive. You may override this by using SWIG's <tt>-package</tt> command line option. </p> -<H3><a name="Go_names">23.4.2 Go Names</a></H3> +<H3><a name="Go_names">24.4.2 Go Names</a></H3> <p> @@ -360,7 +372,7 @@ followed by that name, and the destructor will be named <tt>Delete</tt> followed by that name. </p> -<H3><a name="Go_constants">23.4.3 Go Constants</a></H3> +<H3><a name="Go_constants">24.4.3 Go Constants</a></H3> <p> @@ -368,7 +380,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">23.4.4 Go Enumerations</a></H3> +<H3><a name="Go_enumerations">24.4.4 Go Enumerations</a></H3> <p> @@ -378,7 +390,7 @@ usual). The values of the enumeration will become variables in Go; code should avoid modifying those variables. </p> -<H3><a name="Go_classes">23.4.5 Go Classes</a></H3> +<H3><a name="Go_classes">24.4.5 Go Classes</a></H3> <p> @@ -456,7 +468,7 @@ 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_memory">23.4.5.1 Go Class Memory Management</a></H4> +<H4><a name="Go_class_memory">24.4.5.1 Go Class Memory Management</a></H4> <p> @@ -471,7 +483,7 @@ The most Go idiomatic way to manage the memory for some C++ class is to call <tt><a href="https://golang.org/doc/effective_go.html#defer">defer</a></tt> of the <tt>DeleteClassName</tt> call. Using <tt>defer</tt> ensures that the memory of the C++ object is freed as soon as the function containing the <tt>defer</tt> -statement returns. Furthemore <tt>defer</tt> works great for short-lived +statement returns. Furthermore <tt>defer</tt> works great for short-lived objects and fits nicely C++'s RAII idiom. Example: </p> <div class="code"> @@ -512,7 +524,7 @@ func main() { <p> Using <tt>defer</tt> has limitations though, especially when it comes to -long-lived C++ objects whichs lifetimes are hard to predict. For such C++ +long-lived C++ objects whose lifetimes are hard to predict. For such C++ objects a common technique is to store the C++ object into a Go object, and to use the Go function <tt>runtime.SetFinalizer</tt> to add a finalizer which frees the C++ object when the Go object is freed. It is strongly recommended to read @@ -578,7 +590,7 @@ func (o *GoClassName) Close() { </pre> </div> -<H4><a name="Go_class_inheritance">23.4.5.2 Go Class Inheritance</a></H4> +<H4><a name="Go_class_inheritance">24.4.5.2 Go Class Inheritance</a></H4> <p> @@ -590,16 +602,16 @@ Doing the reverse will require an explicit type assertion, which will be checked dynamically. </p> -<H3><a name="Go_templates">23.4.6 Go Templates</a></H3> +<H3><a name="Go_templates">24.4.6 Go Templates</a></H3> <p> In order to use C++ templates in Go, you must tell SWIG to create -wrappers for a particular template instantation. To do this, use +wrappers for a particular template instantiation. To do this, use the <tt>%template</tt> directive. -<H3><a name="Go_director_classes">23.4.7 Go Director Classes</a></H3> +<H3><a name="Go_director_classes">24.4.7 Go Director Classes</a></H3> <p> @@ -611,13 +623,13 @@ work is necessary. </p> <p> -This subchapter gives a step by step guide how to properly sublass a C++ class +This subchapter gives a step by step guide how to properly subclass a C++ class with a Go type. In general it is strongly recommended to follow this guide completely to avoid common pitfalls with directors in Go. </p> -<H4><a name="Go_director_example_cpp_code">23.4.7.1 Example C++ code</a></H4> +<H4><a name="Go_director_example_cpp_code">24.4.7.1 Example C++ code</a></H4> <p> @@ -639,12 +651,12 @@ public: virtual ~FooBarAbstract() {}; std::string FooBar() { - return this->Foo() + ", " + this->Bar(); + return this->Foo() + ", " + this->Bar(); }; protected: virtual std::string Foo() { - return "Foo"; + return "Foo"; }; virtual std::string Bar() = 0; @@ -689,7 +701,7 @@ be found in <a href="#Go_director_foobargo_class">the end of the guide</a>. </p> -<H4><a name="Go_director_enable">23.4.7.2 Enable director feature</a></H4> +<H4><a name="Go_director_enable">24.4.7.2 Enable director feature</a></H4> <p> @@ -724,7 +736,7 @@ documentation on directors. </p> -<H4><a name="Go_director_ctor_dtor">23.4.7.3 Constructor and destructor</a></H4> +<H4><a name="Go_director_ctor_dtor">24.4.7.3 Constructor and destructor</a></H4> <p> @@ -777,7 +789,7 @@ embedding</a>. </p> -<H4><a name="Go_director_overriding">23.4.7.4 Override virtual methods</a></H4> +<H4><a name="Go_director_overriding">24.4.7.4 Override virtual methods</a></H4> <p> @@ -785,10 +797,12 @@ In order to override virtual methods on a C++ class with Go methods the <tt>NewDirectorClassName</tt> constructor functions receives a <tt>DirectorInterface</tt> argument. The methods in the <tt> DirectorInterface</tt> are a subset of the public and protected virtual methods -of the C++ class. If the <tt>DirectorInterface</tt> contains a method with a +of the C++ class. +Virtual methods that have a final specifier are unsurprisingly excluded. +If the <tt>DirectorInterface</tt> contains a method with a matching signature to a virtual method of the C++ class then the virtual C++ method will be overwritten with the Go method. As Go doesn't support protected -methods all overriden protected virtual C++ methods will be public in Go. +methods all overridden protected virtual C++ methods will be public in Go. </p> <p> @@ -843,7 +857,7 @@ the Go methods. </p> -<H4><a name="Go_director_base_methods">23.4.7.5 Call base methods</a></H4> +<H4><a name="Go_director_base_methods">24.4.7.5 Call base methods</a></H4> <p> @@ -880,7 +894,7 @@ be found in <a href="#Go_director_foobargo_class">the end of the guide</a>. </p> -<H4><a name="Go_director_subclass">23.4.7.6 Subclass via embedding</a></H4> +<H4><a name="Go_director_subclass">24.4.7.6 Subclass via embedding</a></H4> <p> @@ -941,14 +955,14 @@ methods of the <tt>FooBarAbstract</tt> C++ class by means of embedding. The public <tt>FooBarGo</tt> interface type includes the <tt>FooBarAbstract</tt> interface and hence <tt>FooBarGo</tt> can be used as a drop in replacement for <tt>FooBarAbstract</tt> while the reverse isn't possible and would raise a -compile time error. Furthemore the constructor and destructor functions <tt> +compile time error. Furthermore the constructor and destructor functions <tt> NewFooBarGo</tt> and <tt>DeleteFooBarGo</tt> take care of all the director specifics and to the user the class appears as any other SWIG wrapped C++ class. </p> -<H4><a name="Go_director_finalizer">23.4.7.7 Memory management with runtime.SetFinalizer</a></H4> +<H4><a name="Go_director_finalizer">24.4.7.7 Memory management with runtime.SetFinalizer</a></H4> <p> @@ -1013,7 +1027,7 @@ before using <tt>runtime.SetFinalizer</tt> to know all of its gotchas. </p> -<H4><a name="Go_director_foobargo_class">23.4.7.8 Complete FooBarGo example class</a></H4> +<H4><a name="Go_director_foobargo_class">24.4.7.8 Complete FooBarGo example class</a></H4> <p> @@ -1054,7 +1068,7 @@ type overwrittenMethodsOnFooBarAbstract struct { fb FooBarAbstract // If additional constructor arguments have been given they are typically - // stored here so that the overriden methods can use them. + // stored here so that the overridden methods can use them. } func (om *overwrittenMethodsOnFooBarAbstract) Foo() string { @@ -1081,7 +1095,7 @@ func NewFooBarGo() FooBarGo { // The memory of the FooBarAbstract director object instance can be // automatically freed once the FooBarGo instance is garbage collected by // uncommenting the following line. Please make sure to understand the - // runtime.SetFinalizer specific gotchas before doing this. Furthemore + // runtime.SetFinalizer specific gotchas before doing this. Furthermore // DeleteFooBarGo should be deleted if a finalizer is in use or the fooBarGo // struct needs additional data to prevent double deletion. // runtime.SetFinalizer(fbgs, FooBarGo.deleteFooBarAbstract) @@ -1142,7 +1156,7 @@ SWIG/Examples/go/director/</a>. </p> -<H3><a name="Go_primitive_type_mappings">23.4.8 Default Go primitive type mappings</a></H3> +<H3><a name="Go_primitive_type_mappings">24.4.8 Default Go primitive type mappings</a></H3> <p> @@ -1249,7 +1263,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">23.4.9 Output arguments</a></H3> +<H3><a name="Go_output_arguments">24.4.9 Output arguments</a></H3> <p>Because of limitations in the way output arguments are processed in swig, @@ -1289,7 +1303,7 @@ fraction := modulename.Modf(5.0, ptr) </pre> </div> <p>Since this is ugly, you may want to wrap the swig-generated API with -some <a href="#Embedded_go_code">additional functions written in go</a> that +some <a href="#Go_adding_additional_code">additional functions written in go</a> that hide the ugly details.</p> <p>There are no <code>char *OUTPUT</code> typemaps. However you can @@ -1302,7 +1316,7 @@ void f(char *output); </pre> </div> -<H3><a name="Go_adding_additional_code">23.4.10 Adding additional go code</a></H3> +<H3><a name="Go_adding_additional_code">24.4.10 Adding additional go code</a></H3> <p>Often the APIs generated by swig are not very natural in go, especially if @@ -1397,7 +1411,7 @@ func bar() { </pre> </div> -<H3><a name="Go_typemaps">23.4.11 Go typemaps</a></H3> +<H3><a name="Go_typemaps">24.4.11 Go typemaps</a></H3> <p> diff --git a/Doc/Manual/Guile.html b/Doc/Manual/Guile.html index 6acdd2dc3..31d822599 100644 --- a/Doc/Manual/Guile.html +++ b/Doc/Manual/Guile.html @@ -8,7 +8,7 @@ <body bgcolor="#ffffff"> -<H1><a name="Guile">24 SWIG and Guile</a></H1> +<H1><a name="Guile">25 SWIG and Guile</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -48,7 +48,7 @@ <p> This section details guile-specific support in SWIG. -<H2><a name="Guile_nn1">24.1 Supported Guile Versions</a></H2> +<H2><a name="Guile_nn1">25.1 Supported Guile Versions</a></H2> <p> @@ -62,7 +62,7 @@ improved performance. This is currently not tested with swig so your mileage may vary. To be safe set environment variable GUILE_AUTO_COMPILE to 0 when using swig generated guile code. -<H2><a name="Guile_nn2">24.2 Meaning of "Module"</a></H2> +<H2><a name="Guile_nn2">25.2 Meaning of "Module"</a></H2> <p> @@ -70,7 +70,7 @@ There are three different concepts of "module" involved, defined separately for SWIG, Guile, and Libtool. To avoid horrible confusion, we explicitly prefix the context, e.g., "guile-module". -<H2><a name="Guile_nn3">24.3 Old GH Guile API</a></H2> +<H2><a name="Guile_nn3">25.3 Old GH Guile API</a></H2> <p>Guile 1.8 and older could be interfaced using two different api's, the SCM @@ -81,7 +81,7 @@ or the GH API. The GH interface to guile is deprecated. Read more about why in version of SWIG that can still generate guile GH wrapper code is 2.0.9. Please use that version if you really need the GH wrapper code. -<H2><a name="Guile_nn4">24.4 Linkage</a></H2> +<H2><a name="Guile_nn4">25.4 Linkage</a></H2> <p> @@ -89,7 +89,7 @@ Guile support is complicated by a lack of user community cohesiveness, which manifests in multiple shared-library usage conventions. A set of policies implementing a usage convention is called a <b>linkage</b>. -<H3><a name="Guile_nn5">24.4.1 Simple Linkage</a></H3> +<H3><a name="Guile_nn5">25.4.1 Simple Linkage</a></H3> <p> @@ -194,7 +194,7 @@ placed between the <code>define-module</code> form and the <code>SWIG_init</code> via a preprocessor define to avoid symbol clashes. For this case, however, passive linkage is available. -<H3><a name="Guile_nn6">24.4.2 Passive Linkage</a></H3> +<H3><a name="Guile_nn6">25.4.2 Passive Linkage</a></H3> <p>Passive linkage is just like simple linkage, but it generates an @@ -204,7 +204,7 @@ package name (see below). <p>You should use passive linkage rather than simple linkage when you are using multiple modules. -<H3><a name="Guile_nn7">24.4.3 Native Guile Module Linkage</a></H3> +<H3><a name="Guile_nn7">25.4.3 Native Guile Module Linkage</a></H3> <p>SWIG can also generate wrapper code that does all the Guile module @@ -245,7 +245,7 @@ Newer Guile versions have a shorthand procedure for this: </div> </ul> -<H3><a name="Guile_nn8">24.4.4 Old Auto-Loading Guile Module Linkage</a></H3> +<H3><a name="Guile_nn8">25.4.4 Old Auto-Loading Guile Module Linkage</a></H3> <p>Guile used to support an autoloading facility for object-code @@ -271,7 +271,7 @@ option, SWIG generates an exported module initialization function with an appropriate name. -<H3><a name="Guile_nn9">24.4.5 Hobbit4D Linkage</a></H3> +<H3><a name="Guile_nn9">25.4.5 Hobbit4D Linkage</a></H3> <p> @@ -296,7 +296,7 @@ my/lib/libfoo.so.X.Y.Z and friends. This scheme is still very experimental; the (hobbit4d link) conventions are not well understood. </p> -<H2><a name="Guile_nn10">24.5 Underscore Folding</a></H2> +<H2><a name="Guile_nn10">25.5 Underscore Folding</a></H2> <p> @@ -308,7 +308,7 @@ complained so far. <code>%rename</code> to specify the Guile name of the wrapped functions and variables (see CHANGES). -<H2><a name="Guile_nn11">24.6 Typemaps</a></H2> +<H2><a name="Guile_nn11">25.6 Typemaps</a></H2> <p> @@ -400,7 +400,7 @@ constant will appear as a scheme variable. See <a href="Customization.html#Customization_features">Features and the %feature directive</a> for info on how to apply the %feature.</p> -<H2><a name="Guile_nn12">24.7 Representation of pointers as smobs</a></H2> +<H2><a name="Guile_nn12">25.7 Representation of pointers as smobs</a></H2> <p> @@ -421,7 +421,7 @@ representing the expected pointer type. See also If the Scheme object passed was not a SWIG smob representing a compatible pointer, a <code>wrong-type-arg</code> exception is raised. -<H3><a name="Guile_nn14">24.7.1 Smobs</a></H3> +<H3><a name="Guile_nn14">25.7.1 Smobs</a></H3> <p> @@ -440,7 +440,7 @@ structure describing this type. If a generated GOOPS module has been loaded, sm the corresponding GOOPS class.</p> -<H3><a name="Guile_nn15">24.7.2 Garbage Collection</a></H3> +<H3><a name="Guile_nn15">25.7.2 Garbage Collection</a></H3> <p>Garbage collection is a feature of Guile since version 1.6. As SWIG now requires Guile > 1.8, @@ -454,14 +454,14 @@ is exactly like described in <a href="Customization.html#Customization_ownership Object ownership and %newobject</a> in the SWIG manual. All typemaps use an $owner var, and the guile module replaces $owner with 0 or 1 depending on feature:new.</p> -<H2><a name="Guile_nn16">24.8 Native Guile pointers</a></H2> +<H2><a name="Guile_nn16">25.8 Native Guile pointers</a></H2> <p> In addition to SWIG smob pointers, <a href="https://www.gnu.org/software/guile/manual/html_node/Foreign-Pointers.html">Guile's native pointer type</a> are accepted as arguments to wrapped SWIG functions. This can be useful for passing <a href="https://www.gnu.org/software/guile/manual/html_node/Void-Pointers-and-Byte-Access.html#">pointers to bytevector data</a> to wrapped functions. </p> -<H2><a name="Guile_nn17">24.9 Exception Handling</a></H2> +<H2><a name="Guile_nn17">25.9 Exception Handling</a></H2> <p> @@ -487,7 +487,7 @@ mapping: The default when not specified here is to use "swig-error". See Lib/exception.i for details. -<H2><a name="Guile_nn18">24.10 Procedure documentation</a></H2> +<H2><a name="Guile_nn18">25.10 Procedure documentation</a></H2> <p>If invoked with the command-line option <code>-procdoc @@ -522,7 +522,7 @@ like this: typemap argument <code>doc</code>. See <code>Lib/guile/typemaps.i</code> for details. -<H2><a name="Guile_nn19">24.11 Procedures with setters</a></H2> +<H2><a name="Guile_nn19">25.11 Procedures with setters</a></H2> <p>For global variables, SWIG creates a single wrapper procedure @@ -550,7 +550,7 @@ struct members, the procedures <code>(<var>struct</var>-<var>member</var>-get pointer)</code> and <code>(<var>struct-member</var>-set pointer value)</code> are <em>not</em> generated. -<H2><a name="Guile_nn20">24.12 GOOPS Proxy Classes</a></H2> +<H2><a name="Guile_nn20">25.12 GOOPS Proxy Classes</a></H2> <p>SWIG can also generate classes and generic functions for use with @@ -696,7 +696,7 @@ Notice that <Foo> is used before it is defined. The fix is to just put th <code>%import "foo.h"</code> before the <code>%inline</code> block. </p> -<H3><a name="Guile_nn21">24.12.1 Naming Issues</a></H3> +<H3><a name="Guile_nn21">25.12.1 Naming Issues</a></H3> <p>As you can see in the example above, there are potential naming conflicts. The default exported @@ -733,7 +733,7 @@ guile-modules. For example,</p> (use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:))) </pre></div> -<H3><a name="Guile_nn22">24.12.2 Linking</a></H3> +<H3><a name="Guile_nn22">25.12.2 Linking</a></H3> <p>The guile-modules generated above all need to be linked together. GOOPS support requires diff --git a/Doc/Manual/Introduction.html b/Doc/Manual/Introduction.html index 0140bfa57..8d161b73d 100644 --- a/Doc/Manual/Introduction.html +++ b/Doc/Manual/Introduction.html @@ -13,6 +13,11 @@ <ul> <li><a href="#Introduction_nn2">What is SWIG?</a> <li><a href="#Introduction_nn3">Why use SWIG?</a> +<li><a href="#Introduction_target_languages">Target languages</a> +<ul> +<li><a href="#Introduction_supported_status">Supported status</a> +<li><a href="#Introduction_experimental_status">Experimental status</a> +</ul> <li><a href="#Introduction_nn4">A SWIG example</a> <ul> <li><a href="#Introduction_nn5">SWIG interface file</a> @@ -144,7 +149,79 @@ it provides a wide variety of customization features that let you change almost every aspect of the language bindings. This is the main reason why SWIG has such a large user manual ;-). -<H2><a name="Introduction_nn4">2.3 A SWIG example</a></H2> +<H2><a name="Introduction_target_languages">2.3 Target languages</a></H2> + + +<p> +SWIG in essence is a tool to generate code for making C/C++ code available to various other programming languages. +These higher level programming languages are the target languages for the SWIG code generator and C or C++ are the input languages. +A single target language must be specified when SWIG is run. +This results in generating code for C/C++ and the specified target language to interface with each other. +SWIG can be invoked multiple times, but with a different target language specified on each invocation. +This ability to interface C/C++ to many different target languages is one of SWIG's core strengths and features. +</p> + +<p> +SWIG is very broadly composed of two components. +A core component creates a parse tree from the input ISO C/C++ and SWIG directives (extensions to the C/C++ standards). +The parse tree is then passed to a second component, one of the target language modules for generating code specific to a higher level language. +SWIG supports many different target languages. +These target languages are given a status of either Supported or Experimental. +This status is provided to indicate the level of maturity to expect when using a particular target language as not all target languages are fully developed. +</p> + +<p> +The second part of the SWIG documentation contains a chapter for each target level language. +Each chapter will state the status (Supported or Experimental) for that language. +</p> + +<H3><a name="Introduction_supported_status">2.3.1 Supported status</a></H3> + + +<p> +A target language is given the 'Supported' status when +</p> + +<ul> +<li>It is in a mature, well functioning state.</li> +<li>It has its own comprehensive chapter in the documentation.</li> +<li>It passes all of the main SWIG test-suite and has a range of working examples.</li> +<li>It supports the vast majority of SWIG features.</li> +<li>It provides strong backwards compatibility between releases.</li> +</ul> + +<p> +The above is a short summary and further details are outlined in the <a href="Extending.html#Extending_supported_status">Supported status</a> section in the Extending chapter. +The good news is that all the well-known and most popular languages have this status. +</p> + +<H3><a name="Introduction_experimental_status">2.3.2 Experimental status</a></H3> + + +<p> +A target language is given the 'Experimental' status when +</p> + +<ul> +<li>It is of sub-standard quality, failing to meet the above 'Supported' status.</li> +<li>It is somewhere between the mid to mature stage of development.</li> +<li>It does not guarantee any backwards compatibility between releases.</li> +<li>It is in need of help to finish development.</li> +</ul> + +<p> +Anyone using an experimental target language is strongly urged to assist with development of the target language module if they wish to use it. +</p> +<p> +SWIG displays a warning when an experimental target language is used in order to set expectations and emphasize the experimental status of the target language. +The usual <a href="Warnings.html#Warnings_suppression">warning suppression</a> techniques can be used if required. +</p> + +<p> +The above is a short summary and further details are outlined in the <a href="Extending.html#Extending_experimental_status">Experimental status</a> section in the Extending chapter. +</p> + +<H2><a name="Introduction_nn4">2.4 A SWIG example</a></H2> <p> @@ -155,7 +232,7 @@ following C code: <div class="code"><pre> /* File : example.c */ -double My_variable = 3.0; +double My_variable = 3.0; /* Compute factorial of n */ int fact(int n) { @@ -177,7 +254,7 @@ variable <tt>My_variable</tt> from Tcl. You start by making a SWIG interface file as shown below (by convention, these files carry a .i suffix) : -<H3><a name="Introduction_nn5">2.3.1 SWIG interface file</a></H3> +<H3><a name="Introduction_nn5">2.4.1 SWIG interface file</a></H3> <div class="code"><pre> @@ -196,13 +273,13 @@ extern int my_mod(int n, int m); </pre></div> <p> -The interface file contains ANSI C function prototypes and variable +The interface file contains ISO C function prototypes and variable declarations. The <tt>%module</tt> directive defines the name of the module that will be created by SWIG. The <tt>%{ %}</tt> block provides a location for inserting additional code, such as C header files or additional C declarations, into the generated C wrapper code. -<H3><a name="Introduction_nn6">2.3.2 The swig command</a></H3> +<H3><a name="Introduction_nn6">2.4.2 The swig command</a></H3> <p> @@ -235,7 +312,7 @@ and variables declared in the SWIG interface. A look at the file <tt>example_wrap.c</tt> reveals a hideous mess. However, you almost never need to worry about it. -<H3><a name="Introduction_nn7">2.3.3 Building a Perl5 module</a></H3> +<H3><a name="Introduction_nn7">2.4.3 Building a Perl5 module</a></H3> <p> @@ -261,7 +338,7 @@ unix > </pre></div> -<H3><a name="Introduction_nn8">2.3.4 Building a Python module</a></H3> +<H3><a name="Introduction_nn8">2.4.4 Building a Python module</a></H3> <p> @@ -285,7 +362,7 @@ Type "copyright", "credits" or "license" for more information. 7.5 </pre></div> -<H3><a name="Introduction_nn9">2.3.5 Shortcuts</a></H3> +<H3><a name="Introduction_nn9">2.4.5 Shortcuts</a></H3> <p> @@ -311,7 +388,7 @@ print $example::My_variable + 4.5, "\n"; 7.5 </pre></div> -<H2><a name="Introduction_nn10">2.4 Supported C/C++ language features</a></H2> +<H2><a name="Introduction_nn10">2.5 Supported C/C++ language features</a></H2> <p> @@ -323,7 +400,7 @@ major features include: <ul> <li>Full C99 preprocessing. -<li>All ANSI C and C++ datatypes. +<li>All ISO C and C++ datatypes. <li>Functions, variables, and constants. <li>Classes. <li>Single and multiple inheritance. @@ -336,7 +413,9 @@ major features include: </ul> <p> -Most of C++11 is also supported. Details are in the <a href="CPlusPlus11.html#CPlusPlus11">C++11</a> section. +Most of C++11 is also supported. Details are in the <a href="CPlusPlus11.html#CPlusPlus11">C++11</a> chapter. +C++14 support is covered in the <a href="CPlusPlus14.html#CPlusPlus14">C++14</a> chapter. +C++17 support is covered in the <a href="CPlusPlus17.html#CPlusPlus17">C++17</a> chapter. </p> <p> @@ -350,7 +429,7 @@ wrapping simple C++ code. In fact, SWIG is able to handle C++ code that stresses the very limits of many C++ compilers. -<H2><a name="Introduction_nn11">2.5 Non-intrusive interface building</a></H2> +<H2><a name="Introduction_nn11">2.6 Non-intrusive interface building</a></H2> <p> @@ -362,7 +441,7 @@ interface and reuse the code in other applications. It is also possible to support different types of interfaces depending on the application. </p> -<H2><a name="Introduction_build_system">2.6 Incorporating SWIG into a build system</a></H2> +<H2><a name="Introduction_build_system">2.7 Incorporating SWIG into a build system</a></H2> <p> @@ -385,13 +464,13 @@ for further information on this and other Autoconf macros. </p> <p> -There is growing support for SWIG in some build tools, for example <a href="http://cmake.org">CMake</a> +There is growing support for SWIG in some build tools, for example <a href="https://cmake.org">CMake</a> is a cross-platform, open-source build manager with built in support for SWIG. CMake can detect the SWIG executable and many of the target language libraries for linking against. CMake knows how to build shared libraries and loadable modules on many different operating systems. This allows easy cross platform SWIG development. It can also generate the custom commands necessary for driving SWIG from IDEs and makefiles. All of this can be done from a single cross platform input file. -The following example is a CMake input file for creating a python wrapper for the SWIG interface file, example.i: +The following example is a CMake input file for creating a Python wrapper for the SWIG interface file, example.i: </p> <div class="code"><pre> @@ -420,7 +499,7 @@ which will invoke SWIG and compile the generated C++ files into _example.so (UNI For other target languages on Windows a dll, instead of a .pyd file, is usually generated. </p> -<H2><a name="Introduction_nn12">2.7 Hands off code generation</a></H2> +<H2><a name="Introduction_nn12">2.8 Hands off code generation</a></H2> <p> @@ -433,7 +512,7 @@ it allows others to forget about the low-level implementation details. </p> -<H2><a name="Introduction_nn13">2.8 SWIG and freedom</a></H2> +<H2><a name="Introduction_nn13">2.9 SWIG and freedom</a></H2> <p> @@ -452,7 +531,7 @@ to work with complicated and unusual C/C++ applications. Ironically, the freedom that SWIG provides is countered by an extremely conservative approach to code generation. At its core, SWIG tries to distill even the most advanced C++ code down to a small -well-defined set of interface building techniques based on ANSI C +well-defined set of interface building techniques based on ISO C programming. Because of this, you will find that SWIG interfaces can be easily compiled by virtually every C/C++ compiler and that they can be used on any platform. Again, this is an important part of staying out diff --git a/Doc/Manual/Java.html b/Doc/Manual/Java.html index bd259e60d..db5f041e4 100644 --- a/Doc/Manual/Java.html +++ b/Doc/Manual/Java.html @@ -6,7 +6,7 @@ <meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head> <body bgcolor="#FFFFFF"> -<H1><a name="Java">25 SWIG and Java</a></H1> +<H1><a name="Java">26 SWIG and Java</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -94,6 +94,9 @@ <li><a href="#Java_directors_threading">Director threading issues</a> <li><a href="#Java_directors_performance">Director performance tuning</a> <li><a href="#Java_exceptions_from_directors">Java exceptions from directors</a> +<ul> +<li><a href="#Java_customizing_director_exceptions">Customizing director exceptions</a> +</ul> </ul> <li><a href="#Java_allprotected">Accessing protected members</a> <li><a href="#Java_common_customization">Common customization features</a> @@ -164,7 +167,7 @@ It covers most SWIG features, but certain low-level details are covered in less </p> -<H2><a name="Java_overview">25.1 Overview</a></H2> +<H2><a name="Java_overview">26.1 Overview</a></H2> <p> @@ -199,7 +202,7 @@ Various customisation tips and techniques using SWIG directives are covered. The latter sections cover the advanced techniques of using typemaps for complete control of the wrapping process. </p> -<H2><a name="Java_preliminaries">25.2 Preliminaries</a></H2> +<H2><a name="Java_preliminaries">26.2 Preliminaries</a></H2> <p> @@ -219,7 +222,7 @@ This is the commonly used method to load JNI code so your system will more than Android uses Java JNI and also works with SWIG. Please read the <a href="Android.html#Android">Android chapter</a> in conjunction with this one if you are targeting Android. </p> -<H3><a name="Java_running_swig">25.2.1 Running SWIG</a></H3> +<H3><a name="Java_running_swig">26.2.1 Running SWIG</a></H3> <p> @@ -278,7 +281,7 @@ The following sections have further practical examples and details on how you mi compiling and using the generated files. </p> -<H3><a name="Java_commandline">25.2.2 Additional Commandline Options</a></H3> +<H3><a name="Java_commandline">26.2.2 Additional Commandline Options</a></H3> <p> @@ -315,7 +318,7 @@ swig -java -help Their use will become clearer by the time you have finished reading this section on SWIG and Java. </p> -<H3><a name="Java_getting_right_headers">25.2.3 Getting the right header files</a></H3> +<H3><a name="Java_getting_right_headers">26.2.3 Getting the right header files</a></H3> <p> @@ -330,7 +333,7 @@ They are usually in directories like this:</p> <p> The exact location may vary on your machine, but the above locations are typical. </p> -<H3><a name="Java_compiling_dynamic">25.2.4 Compiling a dynamic module</a></H3> +<H3><a name="Java_compiling_dynamic">26.2.4 Compiling a dynamic module</a></H3> <p> @@ -365,7 +368,7 @@ 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> -<H3><a name="Java_using_module">25.2.5 Using your module</a></H3> +<H3><a name="Java_using_module">26.2.5 Using your module</a></H3> <p> @@ -400,7 +403,7 @@ $ If it doesn't work have a look at the following section which discusses problems loading the shared library. </p> -<H3><a name="Java_dynamic_linking_problems">25.2.6 Dynamic linking problems</a></H3> +<H3><a name="Java_dynamic_linking_problems">26.2.6 Dynamic linking problems</a></H3> <p> @@ -474,7 +477,7 @@ Exception in thread "main" java.lang.UnsatisfiedLinkError: exampleJNI.gcd(II)I <p> where <tt>gcd</tt> is the missing JNI function that SWIG generated into the wrapper file. Also make sure you pass all of the required libraries to the linker. -The <tt>java -verbose:jni</tt> commandline switch is also a great way to get more information on unresolved symbols. +The <tt>java -verbose:jni</tt> commandline option is also a great way to get more information on unresolved symbols. One last piece of advice is to beware of the common faux pas of having more than one native library version in your path. </p> @@ -487,7 +490,7 @@ The following section also contains some C++ specific linking problems and solut </p> -<H3><a name="Java_compilation_problems_cpp">25.2.7 Compilation problems and compiling with C++</a></H3> +<H3><a name="Java_compilation_problems_cpp">26.2.7 Compilation problems and compiling with C++</a></H3> <p> @@ -539,7 +542,7 @@ Finally make sure the version of JDK header files matches the version of Java th </p> -<H3><a name="Java_building_windows">25.2.8 Building on Windows</a></H3> +<H3><a name="Java_building_windows">26.2.8 Building on Windows</a></H3> <p> @@ -548,7 +551,7 @@ You will want to produce a DLL that can be loaded by the Java Virtual Machine. This section covers the process of using SWIG with Microsoft Visual C++ 6 although the procedure may be similar with other compilers. In order for everything to work, you will need to have a JDK installed on your machine in order to read the JNI header files.</p> -<H4><a name="Java_visual_studio">25.2.8.1 Running SWIG from Visual Studio</a></H4> +<H4><a name="Java_visual_studio">26.2.8.1 Running SWIG from Visual Studio</a></H4> <p> @@ -587,7 +590,7 @@ To run the native code in the DLL (example.dll), make sure that it is in your pa If the library fails to load have a look at <a href="#Java_dynamic_linking_problems">Dynamic linking problems</a>. </p> -<H4><a name="Java_nmake">25.2.8.2 Using NMAKE</a></H4> +<H4><a name="Java_nmake">26.2.8.2 Using NMAKE</a></H4> <p> @@ -642,11 +645,11 @@ java:: <p> To build the DLL and compile the java code, run NMAKE (you may need to run <tt>vcvars32</tt> first). This is a pretty simplistic Makefile, but hopefully its enough to get you started. -Of course you may want to make changes for it to work for C++ by adding in the -c++ command line switch for swig and replacing .c with .cxx. +Of course you may want to make changes for it to work for C++ by adding in the -c++ command line option for swig and replacing .c with .cxx. </p> -<H2><a name="Java_basic_tour">25.3 A tour of basic C/C++ wrapping</a></H2> +<H2><a name="Java_basic_tour">26.3 A tour of basic C/C++ wrapping</a></H2> <p> @@ -656,7 +659,7 @@ variables are wrapped with JavaBean type getters and setters and so forth. This section briefly covers the essential aspects of this wrapping. </p> -<H3><a name="Java_module_packages_classes">25.3.1 Modules, packages and generated Java classes</a></H3> +<H3><a name="Java_module_packages_classes">26.3.1 Modules, packages and generated Java classes</a></H3> <p> @@ -692,7 +695,7 @@ swig -java -package com.bloggs.swig -outdir com/bloggs/swig example.i SWIG won't create the directory, so make sure it exists beforehand. </p> -<H3><a name="Java_functions">25.3.2 Functions</a></H3> +<H3><a name="Java_functions">26.3.2 Functions</a></H3> <p> @@ -726,7 +729,7 @@ System.out.println(example.fact(4)); </pre></div> -<H3><a name="Java_global_variables">25.3.3 Global variables</a></H3> +<H3><a name="Java_global_variables">26.3.3 Global variables</a></H3> <p> @@ -813,7 +816,7 @@ extern char *path; // Read-only (due to %immutable) </div> -<H3><a name="Java_constants">25.3.4 Constants</a></H3> +<H3><a name="Java_constants">26.3.4 Constants</a></H3> <p> @@ -953,7 +956,7 @@ Or if you decide this practice isn't so bad and your own class implements <tt>ex </p> -<H3><a name="Java_enumerations">25.3.5 Enumerations</a></H3> +<H3><a name="Java_enumerations">26.3.5 Enumerations</a></H3> <p> @@ -967,7 +970,7 @@ The final two approaches use simple integers for each enum item. Before looking at the various approaches for wrapping named C/C++ enums, anonymous enums are considered. </p> -<H4><a name="Java_anonymous_enums">25.3.5.1 Anonymous enums</a></H4> +<H4><a name="Java_anonymous_enums">26.3.5.1 Anonymous enums</a></H4> <p> @@ -1030,7 +1033,7 @@ As in the case of constants, you can access them through either the module class </p> -<H4><a name="Java_typesafe_enums">25.3.5.2 Typesafe enums</a></H4> +<H4><a name="Java_typesafe_enums">26.3.5.2 Typesafe enums</a></H4> <p> @@ -1110,11 +1113,10 @@ Typesafe enums have their advantages over using plain integers in that they can However, there are limitations. For example, they cannot be used in switch statements and serialization is an issue. Please look at the following references for further information: -http://java.sun.com/developer/Books/shiftintojava/page1.html#replaceenums <a href="http://java.sun.com/developer/Books/shiftintojava/page1.html#replaceenums">Replace Enums with Classes</a> in <i>Effective Java Programming</i> on the Sun website, -<a href="http://www.javaworld.com/javaworld/jw-07-1997/jw-07-enumerated.html">Create enumerated constants in Java</a> JavaWorld article, -<a href="http://www.javaworld.com/javaworld/javatips/jw-javatip133.html">Java Tip 133: More on typesafe enums</a> and -<a href="http://www.javaworld.com/javaworld/javatips/jw-javatip122.html">Java Tip 122: Beware of Java typesafe enumerations</a> JavaWorld tips. +<a href="https://www.javaworld.com/article/2076970/create-enumerated-constants-in-java.html">Create enumerated constants in Java</a> JavaWorld article, +<a href="https://www.javaworld.com/article/2077499/java-tip-133--more-on-typesafe-enums.html">Java Tip 133: More on typesafe enums</a> and +<a href="https://www.javaworld.com/article/2077487/java-tip-122--beware-of-java-typesafe-enumerations.html">Java Tip 122: Beware of Java typesafe enumerations</a> JavaWorld tips. </p> <p> @@ -1124,7 +1126,7 @@ When upgrading to JDK 1.5 or later, proper Java enums could be used instead, wit The following section details proper Java enum generation. </p> -<H4><a name="Java_proper_enums">25.3.5.3 Proper Java enums</a></H4> +<H4><a name="Java_proper_enums">26.3.5.3 Proper Java enums</a></H4> <p> @@ -1177,7 +1179,7 @@ The additional support methods need not be generated if none of the enum items h <a href="#Java_simpler_enum_classes">Simpler Java enums for enums without initializers</a> section. </p> -<H4><a name="Java_typeunsafe_enums">25.3.5.4 Type unsafe enums</a></H4> +<H4><a name="Java_typeunsafe_enums">26.3.5.4 Type unsafe enums</a></H4> <p> @@ -1225,7 +1227,7 @@ Note that unlike typesafe enums, this approach requires users to mostly use diff Thus the upgrade path to proper enums provided in JDK 1.5 is more painful. </p> -<H4><a name="Java_simple_enums">25.3.5.5 Simple enums</a></H4> +<H4><a name="Java_simple_enums">26.3.5.5 Simple enums</a></H4> <p> @@ -1244,7 +1246,7 @@ SWIG-1.3.21 and earlier versions wrapped all enums using this approach. The type unsafe approach is preferable to this one and this simple approach is only included for backwards compatibility with these earlier versions of SWIG. </p> -<H3><a name="Java_pointers">25.3.6 Pointers</a></H3> +<H3><a name="Java_pointers">26.3.6 Pointers</a></H3> <p> @@ -1332,7 +1334,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return a NULL pointer if the conversion can't be performed. </p> -<H3><a name="Java_structures">25.3.7 Structures</a></H3> +<H3><a name="Java_structures">26.3.7 Structures</a></H3> <p> @@ -1500,7 +1502,7 @@ x.setA(3); // Modify x.a - this is the same as b.f.a </div> -<H3><a name="Java_classes">25.3.8 C++ classes</a></H3> +<H3><a name="Java_classes">26.3.8 C++ classes</a></H3> <p> @@ -1563,7 +1565,7 @@ int bar = Spam.getBar(); </div> -<H3><a name="Java_inheritance">25.3.9 C++ inheritance</a></H3> +<H3><a name="Java_inheritance">26.3.9 C++ inheritance</a></H3> <p> @@ -1624,7 +1626,7 @@ Note that Java does not support multiple inheritance so any multiple inheritance A warning is given when multiple inheritance is detected and only the first base class is used. </p> -<H3><a name="Java_pointers_refs_arrays">25.3.10 Pointers, references, arrays and pass by value</a></H3> +<H3><a name="Java_pointers_refs_arrays">26.3.10 Pointers, references, arrays and pass by value</a></H3> <p> @@ -1679,7 +1681,7 @@ to hold the result and a pointer is returned (Java will release this memory when the returned object's finalizer is run by the garbage collector). </p> -<H4><a name="Java_null_pointers">25.3.10.1 Null pointers</a></H4> +<H4><a name="Java_null_pointers">26.3.10.1 Null pointers</a></H4> <p> @@ -1703,7 +1705,7 @@ For <tt>spam1</tt> and <tt>spam4</tt> above the Java <tt>null</tt> gets translat The converse also occurs, that is, NULL pointers are translated into <tt>null</tt> Java objects when returned from a C/C++ function. </p> -<H3><a name="Java_overloaded_functions">25.3.11 C++ overloaded functions</a></H3> +<H3><a name="Java_overloaded_functions">26.3.11 C++ overloaded functions</a></H3> <p> @@ -1818,7 +1820,7 @@ void spam(unsigned short); // Ignored </pre> </div> -<H3><a name="Java_default_arguments">25.3.12 C++ default arguments</a></H3> +<H3><a name="Java_default_arguments">26.3.12 C++ default arguments</a></H3> <p> @@ -1861,7 +1863,7 @@ Further details on default arguments and how to restore this approach are given </p> -<H3><a name="Java_namespaces">25.3.13 C++ namespaces</a></H3> +<H3><a name="Java_namespaces">26.3.13 C++ namespaces</a></H3> <p> @@ -1951,7 +1953,7 @@ If the resulting use of the nspace feature and hence packages results in a proxy you will need to open up the visibility for the pointer constructor and <tt>getCPtr</tt> method from the default 'protected' to 'public' with the <tt>SWIG_JAVABODY_PROXY</tt> macro. See <a href="#Java_code_typemaps">Java code typemaps</a>. </p> -<H3><a name="Java_templates">25.3.14 C++ templates</a></H3> +<H3><a name="Java_templates">26.3.14 C++ templates</a></H3> <p> @@ -2000,10 +2002,10 @@ Obviously, there is more to template wrapping than shown in this example. More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a> chapter. </p> -<H3><a name="Java_smart_pointers">25.3.15 C++ Smart Pointers</a></H3> +<H3><a name="Java_smart_pointers">26.3.15 C++ Smart Pointers</a></H3> -<H4><a name="Java_smart_pointers_shared_ptr">25.3.15.1 The shared_ptr Smart Pointer</a></H4> +<H4><a name="Java_smart_pointers_shared_ptr">26.3.15.1 The shared_ptr Smart Pointer</a></H4> <p> @@ -2014,7 +2016,7 @@ in the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a </p> -<H4><a name="Java_smart_pointers_generic">25.3.15.2 Generic Smart Pointers</a></H4> +<H4><a name="Java_smart_pointers_generic">26.3.15.2 Generic Smart Pointers</a></H4> <p> @@ -2098,7 +2100,7 @@ Foo f = p.__deref__(); // Returns underlying Foo * </pre> </div> -<H2><a name="Java_further_details">25.4 Further details on the generated Java classes</a></H2> +<H2><a name="Java_further_details">26.4 Further details on the generated Java classes</a></H2> <p> @@ -2113,7 +2115,7 @@ Finally enum classes are covered. First, the crucial intermediary JNI class is considered. </p> -<H3><a name="Java_imclass">25.4.1 The intermediary JNI class</a></H3> +<H3><a name="Java_imclass">26.4.1 The intermediary JNI class</a></H3> <p> @@ -2233,7 +2235,7 @@ If <tt>name</tt> is the same as <tt>modulename</tt> then the module class name g from <tt>modulename</tt> to <tt>modulenameModule</tt>. </p> -<H4><a name="Java_imclass_pragmas">25.4.1.1 The intermediary JNI class pragmas</a></H4> +<H4><a name="Java_imclass_pragmas">26.4.1.1 The intermediary JNI class pragmas</a></H4> <p> @@ -2315,7 +2317,7 @@ For example, let's change the intermediary JNI class access to just the default All the methods in the intermediary JNI class will then not be callable outside of the package as the method modifiers have been changed from public access to default access. This is useful if you want to prevent users calling these low level functions. </p> -<H3><a name="Java_module_class">25.4.2 The Java module class</a></H3> +<H3><a name="Java_module_class">26.4.2 The Java module class</a></H3> <p> @@ -2346,7 +2348,7 @@ example.egg(new Foo()); The primary reason for having the module class wrapping the calls in the intermediary JNI class is to implement static type checking. In this case only a <tt>Foo</tt> can be passed to the <tt>egg</tt> function, whereas any <tt>long</tt> can be passed to the <tt>egg</tt> function in the intermediary JNI class. </p> -<H4><a name="Java_module_class_pragmas">25.4.2.1 The Java module class pragmas</a></H4> +<H4><a name="Java_module_class_pragmas">26.4.2.1 The Java module class pragmas</a></H4> <p> @@ -2397,7 +2399,7 @@ See <a href="#Java_imclass_pragmas">The intermediary JNI class pragmas</a> secti </p> -<H3><a name="Java_proxy_classes">25.4.3 Java proxy classes</a></H3> +<H3><a name="Java_proxy_classes">26.4.3 Java proxy classes</a></H3> <p> @@ -2473,7 +2475,7 @@ int y = f.spam(5, new Foo()); </pre> </div> -<H4><a name="Java_memory_management">25.4.3.1 Memory management</a></H4> +<H4><a name="Java_memory_management">26.4.3.1 Memory management</a></H4> <p> @@ -2635,7 +2637,7 @@ and </p> -<H4><a name="Java_inheritance_mirroring">25.4.3.2 Inheritance</a></H4> +<H4><a name="Java_inheritance_mirroring">26.4.3.2 Inheritance</a></H4> <p> @@ -2751,7 +2753,7 @@ However, true cross language polymorphism can be achieved using the <a href="#Ja </p> -<H4><a name="Java_proxy_classes_gc">25.4.3.3 Proxy classes and garbage collection</a></H4> +<H4><a name="Java_proxy_classes_gc">26.4.3.3 Proxy classes and garbage collection</a></H4> <p> @@ -2760,7 +2762,7 @@ The <tt>finalize()</tt> method calls <tt>delete()</tt> which frees any malloc'd The idea is for <tt>delete()</tt> to be called when you have finished with the C/C++ object. Ideally you need not call <tt>delete()</tt>, but rather leave it to the garbage collector to call it from the finalizer. When a program exits, the garbage collector does not guarantee to call all finalizers. -An insight into the reasoning behind this can be obtained from <a href="http://www.hpl.hp.com/techreports/2002/HPL-2002-335.html">Hans Boehm's Destructors, Finalizers, and Synchronization</a> paper. +An insight into the reasoning behind this can be obtained from <a href="https://www.hpl.hp.com/techreports/2002/HPL-2002-335.html">Hans Boehm's Destructors, Finalizers, and Synchronization</a> paper. Depending on what the finalizers do and which operating system you use, this may or may not be a problem. </p> @@ -2784,7 +2786,7 @@ Call the <tt>System.runFinalizersOnExit(true)</tt> or <tt>Runtime.getRuntime().r This method is inherently unsafe. It may result in finalizers being called on live objects while other threads are concurrently manipulating those objects, resulting in erratic behavior or deadlock. </i></div> <p>In many cases you will be lucky and find that it works, but it is not to be advocated. -Have a look at <a href="http://www.oracle.com/technetwork/java/index.html">Java web site</a> and search for <tt>runFinalizersOnExit</tt>. +Have a look at <a href="https://www.oracle.com/technetwork/java/index.html">Java web site</a> and search for <tt>runFinalizersOnExit</tt>. </p></li> <li><p> @@ -2834,7 +2836,7 @@ The section on <a href="#Java_typemaps">Java typemaps</a> details how to specify See the <a href="http://www.devx.com/Java/Article/30192">How to Handle Java Finalization's Memory-Retention Issues</a> article for alternative approaches to managing memory by avoiding finalizers altogether. </p> -<H4><a name="Java_pgcpp">25.4.3.4 The premature garbage collection prevention parameter for proxy class marshalling</a></H4> +<H4><a name="Java_pgcpp">26.4.3.4 The premature garbage collection prevention parameter for proxy class marshalling</a></H4> <p> @@ -2956,7 +2958,7 @@ For example: <b>Compatibility note:</b> The generation of this additional parameter did not occur in versions prior to SWIG-1.3.30. </p> -<H4><a name="Java_multithread_libraries">25.4.3.5 Single threaded applications and thread safety</a></H4> +<H4><a name="Java_multithread_libraries">26.4.3.5 Single threaded applications and thread safety</a></H4> <p> @@ -3044,7 +3046,7 @@ for (int i=0; i<100000; i++) { </pre></div> -<H3><a name="Java_type_wrapper_classes">25.4.4 Type wrapper classes</a></H3> +<H3><a name="Java_type_wrapper_classes">26.4.4 Type wrapper classes</a></H3> <p> @@ -3131,7 +3133,7 @@ public static void spam(SWIGTYPE_p_int x, SWIGTYPE_p_int y, int z) { ... } </div> -<H3><a name="Java_enum_classes">25.4.5 Enum classes</a></H3> +<H3><a name="Java_enum_classes">26.4.5 Enum classes</a></H3> <p> @@ -3140,7 +3142,7 @@ The <a href="#Java_enumerations">Enumerations</a> section discussed these but om The following sub-sections detail the various types of enum classes that can be generated. </p> -<H4><a name="Java_typesafe_enums_classes">25.4.5.1 Typesafe enum classes</a></H4> +<H4><a name="Java_typesafe_enums_classes">26.4.5.1 Typesafe enum classes</a></H4> <p> @@ -3224,7 +3226,7 @@ The <tt>swigValue</tt> method is used for marshalling in the other direction. The <tt>toString</tt> method is overridden so that the enum name is available. </p> -<H4><a name="Java_proper_enums_classes">25.4.5.2 Proper Java enum classes</a></H4> +<H4><a name="Java_proper_enums_classes">26.4.5.2 Proper Java enum classes</a></H4> <p> @@ -3302,7 +3304,7 @@ These needn't be generated if the enum being wrapped does not have any initializ <a href="#Java_simpler_enum_classes">Simpler Java enums for enums without initializers</a> section describes how typemaps can be used to achieve this. </p> -<H4><a name="Java_typeunsafe_enums_classes">25.4.5.3 Type unsafe enum classes</a></H4> +<H4><a name="Java_typeunsafe_enums_classes">26.4.5.3 Type unsafe enum classes</a></H4> <p> @@ -3333,7 +3335,7 @@ public final class Beverage { </pre> </div> -<H3><a name="Java_interfaces">25.4.6 Interfaces</a></H3> +<H3><a name="Java_interfaces">26.4.6 Interfaces</a></H3> <p> @@ -3578,7 +3580,7 @@ typemap which is only used when a class is marked with the <tt>interface</tt> fe See <a href="Java.html#Java_code_typemaps">Java code typemaps</a> for details. </p> -<H2><a name="Java_directors">25.5 Cross language polymorphism using directors</a></H2> +<H2><a name="Java_directors">26.5 Cross language polymorphism using directors</a></H2> <p> @@ -3600,7 +3602,7 @@ The upshot is that C++ classes can be extended in Java and from C++ these extens Neither C++ code nor Java code needs to know where a particular method is implemented: the combination of proxy classes, director classes, and C wrapper functions transparently takes care of all the cross-language method routing. </p> -<H3><a name="Java_enabling_directors">25.5.1 Enabling directors</a></H3> +<H3><a name="Java_enabling_directors">26.5.1 Enabling directors</a></H3> <p> @@ -3626,7 +3628,7 @@ The %feature directive can be applied globally, to specific classes, and to spec // generate directors for all classes that have virtual methods %feature("director"); -// generate directors for all virtual methods in class Foo +// generate directors for the virtual methods in class Foo %feature("director") Foo; </pre> </div> @@ -3644,7 +3646,7 @@ So for example, </div> <p> -will generate directors for all virtual methods of class Foo except bar(). +will generate directors for the virtual methods of class Foo except bar(). </p> <p> @@ -3668,7 +3670,7 @@ public: </pre> </div> -<H3><a name="Java_directors_classes">25.5.2 Director classes</a></H3> +<H3><a name="Java_directors_classes">26.5.2 Director classes</a></H3> <p> @@ -3680,7 +3682,8 @@ The director classes store a pointer to their underlying Java proxy classes. <p> For simplicity let's ignore the <tt>Swig::Director</tt> class and refer to the original C++ class as the director's base class. By default, a director class extends all virtual methods in the inheritance chain of its base class (see the preceding section for how to modify this behavior). -Thus all virtual method calls, whether they originate in C++ or in Java via proxy classes, eventually end up in at the implementation in the director class. +Virtual methods that have a final specifier are unsurprisingly excluded. +Thus the virtual method calls, whether they originate in C++ or in Java via proxy classes, eventually end up in at the implementation in the director class. The job of the director methods is to route these method calls to the appropriate place in the inheritance chain. By "appropriate place" we mean the method that would have been called if the C++ base class and its Java derived classes were seamlessly integrated. That seamless integration is exactly what the director classes provide, transparently skipping over all the messy JNI glue code that binds the two languages together. @@ -3695,7 +3698,7 @@ If the correct implementation is in Java, the Java API is used to call the metho </p> -<H3><a name="Java_directors_overhead">25.5.3 Overhead and code bloat</a></H3> +<H3><a name="Java_directors_overhead">26.5.3 Overhead and code bloat</a></H3> <p> @@ -3713,7 +3716,7 @@ This situation can be optimized by selectively enabling director methods (using </p> -<H3><a name="Java_directors_example">25.5.4 Simple directors example</a></H3> +<H3><a name="Java_directors_example">26.5.4 Simple directors example</a></H3> <p> @@ -3746,12 +3749,10 @@ Naturally, the SWIG generated C++ code and the generated Java intermediary class <div class="code"> <pre> -public class DirectorDerived extends DirectorBase { - public DirectorDerived() { - } - +class DirectorDerived extends DirectorBase { + @Override public void upcall_method() { - System.out.println("DirectorDerived::upcall_method() invoked."); + System.out.println("DirectorDerived.upcall_method() invoked."); } } </pre> @@ -3774,11 +3775,11 @@ will result in the following being output: <div class="code"> <pre> -DirectorDerived::upcall_method() invoked. +DirectorDerived.upcall_method() invoked. </pre> </div> -<H3><a name="Java_directors_threading">25.5.5 Director threading issues</a></H3> +<H3><a name="Java_directors_threading">26.5.5 Director threading issues</a></H3> <p> @@ -3798,7 +3799,7 @@ Macros can be defined on the commandline when compiling your C++ code, or altern </pre> </div> -<H3><a name="Java_directors_performance">25.5.6 Director performance tuning</a></H3> +<H3><a name="Java_directors_performance">26.5.6 Director performance tuning</a></H3> <p> @@ -3819,51 +3820,192 @@ However, if all director methods are expected to usually be overridden by Java s The disadvantage is that invocation of director methods from C++ when Java doesn't actually override the method will require an additional call up into Java and back to C++. As such, this option is only useful when overrides are extremely common and instantiation is frequent enough that its performance is critical. </p> -<H3><a name="Java_exceptions_from_directors">25.5.7 Java exceptions from directors</a></H3> +<H3><a name="Java_exceptions_from_directors">26.5.7 Java exceptions from directors</a></H3> <p> With directors routing method calls to Java, and proxies routing them to C++, the handling of exceptions is an important concern. -The default behavior from SWIG 3.0 -onwards is to convert the thrown Java exception into a SWIG defined -<code>DirectorException</code> C++ exception. -SWIG 2.0 and earlier versions didn't provide any mechanism to handle the Java director method exceptions in C++. +The default behavior for Java exceptions thrown in a director method overridden in Java is +to store the thrown Java exception into a SWIG defined +<code>Swig::DirectorException</code> C++ class exception in the C++ layer and then throw this C++ exception. </p> <p> -Converting Java exceptions into C++ exceptions can be done in two different ways using +Of course, should this exception be thrown, your C++ code must catch it and handle it before returning back to Java. +The default generated code <b>does not</b> attempt to handle the C++ exception, but there is a simple way +to make this all work by catching the C++ exception and extracting the original Java exception by using <tt>%catches</tt> for <tt>Swig::DirectorException</tt>. +Consider the example shown earlier with a modification to the <tt>upcall_method</tt> Java method to throw a Java exception: +</p> + +<div class="code"> +<pre> +class DirectorDerived extends DirectorBase { + @Override + public void upcall_method() { + System.out.println("DirectorDerived.upcall_method() invoked."); + throw new RuntimeException("There was a problem!"); + } +} +</pre> +</div> + +<p> +Now, by default, the JVM will abort when <tt>example.callup(director)</tt> is called as the C++ +<tt>Swig::DirectorException</tt> (storing the Java exception) is thrown and not handled by the <tt>callup</tt> method. +Needless to say this is not very user friendly and so the recommendation is to add the following +simple <tt>%catches</tt> directive before SWIG parses the <tt>callup</tt> function: +</p> + +<div class="code"> +<pre> +%catches(Swig::DirectorException) callup; +</pre> +</div> + +<p> +Or target all wrapped methods using: +</p> + +<div class="code"> +<pre> +%catches(Swig::DirectorException); +</pre> +</div> + +<p> +This tells SWIG to generate a C++ catch handler using some code from the <a href="Typemaps.html#Typemaps_throws_typemap">throws typemap</a> for <tt>Swig::DirectorException</tt> that SWIG supplies by default, see <a href="SWIGPlus.html#SWIGPlus_catches">Exception handling with %catches</a>. +This typemap code is written to simply catch the C++ <tt>Swig::DirectorException</tt> class and immediately +return to Java throwing the original Java exception that it has stored. +The net result is a stack trace containing the original Java exception including the location that the exception was thrown from. +</p> + +<div class="shell"> +<pre> +DirectorDerived.upcall_method() invoked. +Exception in thread "main" java.lang.RuntimeException: There was a problem! + at DirectorDerived.upcall_method(runme.java:4) + at exampleJNI.SwigDirector_DirectorBase_upcall_method(exampleJNI.java:20) + at exampleJNI.callup(Native Method) + at example.callup(example.java:12) + at runme.main(runme.java:21) +</pre> +</div> + +<p> +More on the <tt>Swig::DirectorException</tt> class can be found in the next section which details how to customize the handling of director exceptions. +</p> + +<H4><a name="Java_customizing_director_exceptions">26.5.7.1 Customizing director exceptions</a></H4> + + +<p> +This section is for advanced customization of director exceptions. +The recommendation for most users is to use the simple <tt>%catches</tt> directive described above as it should be sufficient for most users needs. +</p> + +<p> +The conversion of Java exceptions into C++ exceptions can be customized in two different ways using the <code>director:except</code> <a href="Customization.html#Customization_features">feature</a>. -In the simplest approach, a code block is attached to each director method to +In the first approach, a code block is attached to each director method to handle the mapping of Java exceptions into C++ exceptions. +The code block is generated just after the call up from the C++ director method into the overloaded method in Java. Its primary function is to check if a Java exception has been thrown and then handle it in C++. +The example below converts a +<tt>java.lang.IndexOutOfBoundsException</tt> into a C++ <tt>std::out_of_range</tt> exception and converts a +user's Java <tt>MyJavaException</tt> into a C++ <tt>MyCppException</tt> exception. +If the Java exception doesn't match either of these, a fallback <tt>std::runtime_error</tt> C++ exception is thrown. </p> <div class="code"> <pre> -%feature("director:except") MyClass::method(int x) { +%feature("director:except") MyClass::dirmethod(int x) { jthrowable $error = jenv->ExceptionOccurred(); if ($error) { - jenv->ExceptionClear(); if (Swig::ExceptionMatches(jenv, $error, "java/lang/IndexOutOfBoundsException")) throw std::out_of_range(Swig::JavaExceptionMessage(jenv, $error).message()); if (Swig::ExceptionMatches(jenv, $error, "$packagepath/MyJavaException")) throw MyCppException(Swig::JavaExceptionMessage(jenv, $error).message()); - throw std::runtime_error("Unexpected exception thrown in MyClass::method"); + throw std::runtime_error("Unexpected exception thrown in MyClass::dirmethod"); } } class MyClass { +public: /** Throws either a std::out_of_range or MyCppException on error */ - void method(int x); + virtual void dirmethod(int x); + virtual ~MyClass(); +}; +</pre> +</div> + +<p> +A few special variables are expanded within the <tt>director:except</tt> feature. +</p> +<ul> + <li> The special variable <tt>$error</tt> is expanded into a unique variable name (swigerror) + and should be used for the assignment of the jthrowable exception that occurred.</li> + <li> The special variable <tt>$packagepath</tt> is + replaced by the outer package provided for SWIG generation by the -package option. </li> + <li> The special variable <tt>$directorthrowshandlers</tt> is not shown above, but is replaced + by applicable "directorthrows" typemap contents (covered later in this section). </li> + <li> The special variable <tt>$null</tt> is not shown above, but is replaced + by a suitable default constructed object for returning from the director method (or nothing if + the director method has a void return). + </li> +</ul> + +<p> +Utility functions/classes in director.swg are provided to aid the exception conversion as follows: +</p> + +<div class="code"> +<pre> +namespace Swig { + + // Helper method to determine if a Java throwable matches a particular Java class type + // Note side effect of clearing any pending exceptions + bool ExceptionMatches(JNIEnv *jenv, jthrowable throwable, const char *classname); + + // Helper class to extract the exception message from a Java throwable + class JavaExceptionMessage { + public: + JavaExceptionMessage(JNIEnv *jenv, jthrowable throwable); + + // Return a C string of the exception message in the jthrowable passed in the constructor + // If no message is available, null_string is return instead + const char *message(const char *null_string = + "Could not get exception message in JavaExceptionMessage") const; + }; + + // C++ Exception class for handling Java exceptions thrown during a director method Java upcall + class DirectorException : public std::exception { + public: + + // Construct exception from a Java throwable + DirectorException(JNIEnv *jenv, jthrowable throwable); + + // More general constructor for handling as a java.lang.RuntimeException + DirectorException(const char *msg); + + // Return exception message extracted from the Java throwable + const char *what() const throw(); + + // Reconstruct and raise/throw the Java Exception that caused the DirectorException + // Note that any error in the JNI exception handling results in a Java RuntimeException + void throwException(JNIEnv *jenv) const; + + // Create and throw the DirectorException + static void raise(JNIEnv *jenv, jthrowable throwable) { + throw DirectorException(jenv, throwable); + } + }; + } </pre> </div> <p> -This approach allows a flexible mapping of Java exceptions thrown by director methods into -C++ exceptions expected by a C++ caller. There -need not be any C++ <em>exception specifications</em> on the C++ method. The -utility function <code>Swig::ExceptionMatches</code> +The utility function <code>Swig::ExceptionMatches</code> and class <code>Swig::JavaExceptionMessage</code> are provided to simplify writing code for wrappers that use the <code>director:except</code> feature. The function <code>Swig::ExceptionMatches</code> matches the type of the @@ -3871,13 +4013,10 @@ function <code>Swig::ExceptionMatches</code> matches the type of the name, such as <code>"java/lang/IOError"</code>. If the throwable class is the same type, or derives from the given type, <code>Swig::ExceptionMatches</code> will return true. Care must be taken to provide the correct fully qualified name, since for wrapped exceptions the -generated proxy class will have additional package qualification, depending on +generated proxy class will have an additional package qualification, depending on the '-package' argument and use of the <a href="#Java_namespaces">nspace - feature</a>. The special variable <code>$error</code> is expanded by SWIG into a unique variable name and -should be used for the -assignment of the exception that occurred. The special variable <code>$packagepath</code> is -replaced by the outer package provided for SWIG generation by the -package -option. The utility class <code>Swig::JavaExceptionMessage</code> is a holder + feature</a>. +The utility class <code>Swig::JavaExceptionMessage</code> is a holder providing access to the message from the thrown Java exception. The <code>message()</code> method returns the exception message as a <code>const char *</code>, which is only valid during the lifetime of the holder. Any code using this message @@ -3885,20 +4024,27 @@ needs to copy it, for example into a std::string or a newly constructed C++ exce </p> <p> -Using the above approach to +Using the first approach above to write handlers for a large number of methods will require -repetitive duplication of the <code>director:except</code> feature code. -To mitigate this, an alternative approach is provided via typemaps in a -fashion analagous to -the <a href="Typemaps.html#throws_typemap">"throws" typemap.</a> The -"throws" typemap provides an approach to automatically map all the C++ +repetitive duplication of the <code>director:except</code> feature code +for each director method. +To mitigate this, a second approach is provided via typemaps in a +fashion analogous to +the <a href="Typemaps.html#throws_typemap">"throws" typemap</a>. +The "throws" typemap provides a way to map all the C++ exceptions listed in a method's defined exceptions (either from a C++ <em>exception specification</em> or a <code>%catches</code> feature) into Java exceptions. The "directorthrows" typemap provides the inverse mapping and should contain code to convert a suitably matching Java exception into a C++ exception. +Only use this typemap if you wish to write custom conversions of Java exceptions into C++ exceptions +and apply them to many different methods. +The default handling which uses the <code>Swig::DirectorException</code> class should otherwise meet your needs. +</p> + +<p> The example below converts a Java <code>java.lang.IndexOutOfBoundsException</code> exception -to the typemap's type, that is <code>std::out_of_range</code>: +to the typemap's type, that is a <code>std::out_of_range</code> C++ exception: <div class="code"> <pre> @@ -3913,7 +4059,7 @@ to the typemap's type, that is <code>std::out_of_range</code>: <p> The "directorthrows" typemap is then used in conjunction with the <code>director:except</code> feature if the <code>$directorthrowshandlers</code> special variable -is used in the feature code. Consider the following, which also happens to be the default: +is used in the code block. Consider the following, which also happens to be the default: </p> <div class="code"> @@ -3921,31 +4067,41 @@ is used in the feature code. Consider the following, which also happens to be th %feature("director:except") %{ jthrowable $error = jenv->ExceptionOccurred(); if ($error) { - jenv->ExceptionClear(); $directorthrowshandlers - throw Swig::DirectorException(jenv, $error); + Swig::DirectorException::raise(jenv, $error); } %} </pre> </div> -<p>The code generated using the <code>director:except</code> feature -replaces the <code>$directorthrowshandlers</code> special variable with the code in -the "directorthrows" typemaps, for each and every exception defined for the method. -The possible exceptions can be defined either with a C++ exception +<p> +where <tt>Swig::DirectorException::raise</tt> is the helper method to throw a C++ <tt>Swig::DirectorException</tt>, see above. +The code generated from the <code>director:except</code> feature +has the <code>$directorthrowshandlers</code> special variable replaced with the code in +the relevant "directorthrows" typemaps, for each and every exception defined for the method. +The relevant exceptions can be defined either with a C++ exception specification or <code>%catches</code> as described for the <a href="Typemaps.html#throws_typemap">"throws" typemap</a>. </p> <p> -Consider the following director method: +Let's try and put all this together by considering the following director method: </p> <div class="code"> <pre> - ... +struct X { virtual void doSomething(int index) throw (std::out_of_range); ... +}; + +OR + +%catches(std::out_of_range) X::doSomething; +struct X { + virtual void doSomething(int index); + ... +}; </pre> </div> @@ -3958,12 +4114,10 @@ the resulting code generated in the director method after calling up to Java wil <pre> jthrowable swigerror = jenv->ExceptionOccurred(); if (swigerror) { - jenv->ExceptionClear(); if (Swig::ExceptionMatches(jenv, swigerror, "java/lang/IndexOutOfBoundsException")) { throw std::out_of_range(Swig::JavaExceptionMessage(jenv, swigerror).message()); } - - throw Swig::DirectorException(jenv, swigerror); + Swig::DirectorException::raise(jenv, swigerror); } </pre> </div> @@ -3971,7 +4125,7 @@ if (swigerror) { <p><em> Note: Beware of using exception specifications as the SWIG director methods will be generated with the same exception specifications and if the -director method throws an exception that is not specified it is likely +director method throws an exception that is not specified in the exception specifications list it is likely to terminate your program. See the C++ standard for more details. Using the %catches feature instead to define the handled exceptions does not suffer this potential fate. @@ -3979,8 +4133,9 @@ this potential fate. <p>Because the default code generation maps any unhandled Java exceptions to <code>Swig::DirectorException</code>, any director methods that have exception -specifications may cause program termination. To simply ignore -unexpected exceptions, the default handling can be changed with: +specifications may cause program termination as this exception class won't be in the exception specifications list. +You can avoid throwing <tt>Swig::DirectorException</tt> by changing the default handling for all methods by adding a <tt>director:except</tt> feature without any method name. +For example, you can just ignore them: </p> <div class="code"> @@ -3988,8 +4143,8 @@ unexpected exceptions, the default handling can be changed with: %feature("director:except") %{ jthrowable $error = jenv->ExceptionOccurred(); if ($error) { - jenv->ExceptionClear(); $directorthrowshandlers + jenv->ExceptionClear(); return $null; // exception is ignored } %} @@ -3999,7 +4154,7 @@ unexpected exceptions, the default handling can be changed with: <p>Alternatively an exception compatible with the existing director method exception specifications can be thrown. Assuming that all methods allow std::runtime_error to be thrown, -the <code>return $null;</code> could be changed to: +the <code>return $null</code> line above could be changed to: </p> <div class="code"> @@ -4009,125 +4164,297 @@ the <code>return $null;</code> could be changed to: </div> <p>In more complex situations, a separate <code>director:except</code> feature -may need to be attached to specific methods. +may need to be attached to specific methods by providing a method name to the <tt>director:except</tt> feature. </p> -<p>Below is a complete example demonstrating the use -of the "directorthrows" typemaps. In this example, a -generic "directorthrows" typemap is appropriate for all three exceptions - all -take single string constructors. If the exceptions had different constructors, -it would be necessary to have separate typemaps for each exception type. +<p>This is all no doubt quite hard to follow without seeing a full example and some code. +Below is a complete example demonstrating the use +of most of the exception customizations one can use, that is, +"directorthrows" and "throws" typemaps, %exception and %catches. +See the <a href="#Java_exception_handling">Exception handling with %exception and %javaexception</a> +section for more on converting C++ exceptions to Java exceptions. +The example also has a user defined C++ exception class called <tt>MyNS::MyException</tt> and this is wrapped as a Java exception. +The director class being wrapped is <tt>MyClass</tt> and the director method is called <tt>MyClass::dirmethod</tt>. +A number of <tt>std::cout</tt> calls have been added to help understand code flow. +You can copy the code below into an interface file and run SWIG on it and examine the generated code. -<!-- All the DEFINE_ and DECLARE_EXCEPTIONS CAN BE OMITTED to make - this more succinct. They are included to make this a complete - example interface that could be generated and built. --> <div class="code"> <pre> %module(directors="1") example %{ - #include <string> #include <stdexcept> + #include <iostream> %} -// Define exceptions in header section using std::runtime_error -%define DEFINE_EXCEPTION(NAME) -%{ - namespace MyNS { - struct NAME : public std::runtime_error { NAME(const std::string &what) : runtime_error(what) {} }; +// Generic catch handler for all wrapped methods +%exception %{ + try { + $action + } catch (const std::exception &e) { + std::cout << "Generic std::exception catch handler" << std::endl; + jclass clazz = jenv->FindClass("java/lang/RuntimeException"); + jenv->ThrowNew(clazz, e.what()); + return $null; } %} -%enddef -// Expose C++ exceptions as Java Exceptions by changing the Java base class and providing a getMessage() -%define DECLARE_EXCEPTION(NAME) -%typemap(javabase) MyNS::NAME "java.lang.Exception"; -%rename(getMessage) MyNS::NAME::what; +// Expose C++ exception as a Java Exception by changing the Java base class and providing a getMessage() +%typemap(javabase) MyNS::MyException "java.lang.RuntimeException"; +%rename(getMessage) MyNS::MyException::whatsup; + +%inline %{ namespace MyNS { - struct NAME { - NAME(const std::string& what); - const char * what(); + class MyException { + std::string msg; + public: + MyException(const char *msg) : msg(msg) {} + const char * whatsup() const { return msg.c_str(); } }; } -%enddef - -DEFINE_EXCEPTION(ExceptionA) -DEFINE_EXCEPTION(ExceptionB) -DEFINE_EXCEPTION(Unexpected) - -// Mark three methods to map director thrown exceptions. -%feature("director:except") MyClass::meth1(int); -%feature("director:except") MyClass::meth2; -%feature("director:except") meth3; +%} -%typemap(directorthrows) MyNS::ExceptionA, MyNS::ExceptionB, MyNS::Unexpected %{ - if (Swig::ExceptionMatches(jenv, $error, "$packagepath/$javaclassname")) +%typemap(directorthrows) MyNS::MyException %{ + if (Swig::ExceptionMatches(jenv, $error, "$packagepath/MyException")) { + std::cout << "$1_type exception matched (directorthrows typemap)" << std::endl; throw $1_type(Swig::JavaExceptionMessage(jenv, $error).message()); + } %} -DECLARE_EXCEPTION(ExceptionA) -DECLARE_EXCEPTION(ExceptionB) -DECLARE_EXCEPTION(Unexpected) +%typemap(throws) MyNS::MyException %{ + std::cout << "$1_type caught (throws typemap)" << std::endl; + jclass excep = jenv->FindClass("MyException"); + if (excep) { + std::cout << "$1_type class found (throws typemap)" << std::endl; + jenv->ThrowNew(excep, $1.whatsup()); + } + return $null; +%} -%catches(MyNS::ExceptionA, MyNS::ExceptionB, MyNS::Unexpected) MyClass::meth2(); +// These are the exceptions that the director method MyClass::dirmethod will have catch handlers for. +// Note that this is also a virtual method / director method and the C++ exceptions listed can be +// thrown after converting them from Java exceptions. +%catches(MyNS::MyException, Swig::DirectorException) MyClass::dirmethod; -%inline { - class MyClass { - public: - virtual void meth1(int x) throw(MyNS::ExceptionA, MyNS::ExceptionB) = 0; - virtual void meth2() = 0; /* throws MyNS::ExceptionA, MyNS::ExceptionB, MyNS::Unexpected */ - virtual void meth3(float x) throw(MyNS::Unexpected) = 0; - virtual ~MyClass() {} - }; +// These are the exceptions that call_dirmethod C++ wrapper will have catch handlers for. +// Note that this is not a virtual method, hence not a director method. +%catches(MyNS::MyException, Swig::DirectorException) call_dirmethod; + +%feature("director") MyClass; + +%feature("director:except") MyClass::dirmethod(int x) { + jthrowable $error = jenv->ExceptionOccurred(); + if ($error) { + std::cout << "Upcall finished, an exception was thrown in Java" << std::endl; + $directorthrowshandlers + std::cout << "Upcall finished, no exception conversion, throwing DirectorException" << std::endl; + Swig::DirectorException::raise(jenv, $error); + } } + +%inline %{ +class MyClass { +public: + /** Throws either a std::out_of_range or MyException on error */ + virtual void dirmethod(int x) { + if (x <= 0) + throw std::out_of_range("MyClass::dirmethod index is out of range"); + else if (x == 1) + throw MyNS::MyException("MyClass::dirmethod some problem!"); + } + virtual ~MyClass() {} + static void call_dirmethod(MyClass& c, int x) { + return c.dirmethod(x); + } +}; +%} </pre> </div> <p> -In this case the three different "directorthrows" typemaps will be used -to generate the three different exception handlers for -<code>meth1</code>, <code>meth2</code> and <code>meth3</code>. The generated -handlers will have "if" blocks for each exception type specified, in -the exception specification or <code>%catches</code> feature. +The generated code for the <tt>call_dirmethod</tt> wrapper contains the various exception handlers. +The outer exception handler is from the <tt>%exception</tt> directive and the others +are from the "throws" typemaps. </p> -<p>Note that the "directorthrows" typemaps are important -only if it is important for the the exceptions passed through the C++ -layer to be mapped to distinct C++ exceptions. If director methods -are being called by C++ code that is itself wrapped in a -SWIG generated Java wrapper and access is always through this wrapper, -the default <code>Swig::DirectorException</code> class provides enough information -to reconstruct the original exception. In this case removing the -<code>$directorthrowshandlers</code> special variable from the -default <code>director:except</code> feature and simply always -throwing a <code>Swig::DirectorException</code> will achieve the desired result. -Along with this a generic exception feature is added to convert any -caught <code>Swig::DirectorException</code>s back into the underlying -Java exceptions via the <code>Swig::DirectorException::raiseJavaException</code> method, -as demonstrated with <code>%javaexception</code> below: +<div class="code"> +<pre> +SWIGEXPORT void JNICALL Java_exampleJNI_MyClass_1call_1dirmethod(JNIEnv *jenv, jclass jcls, jlong jarg1, jobject jarg1_, jint jarg2) { + ... + try { + try { + MyClass::call_dirmethod(*arg1,arg2); + } catch(MyNS::MyException &_e) { + std::cout << "MyNS::MyException caught (throws typemap)" << std::endl; + jclass excep = jenv->FindClass("MyException"); + if (excep) { + std::cout << "MyNS::MyException class found (throws typemap)" << std::endl; + jenv->ThrowNew(excep, (&_e)->whatsup()); + } + return ; + + } catch(Swig::DirectorException &_e) { + (&_e)->throwException(jenv); + return ; + } + } catch (const std::exception &e) { + std::cout << "Generic std::exception catch handler" << std::endl; + jclass clazz = jenv->FindClass("java/lang/RuntimeException"); + jenv->ThrowNew(clazz, e.what()); + return ; + } +</pre> +</div> + +<p> +The director method calling up to Java contains the exception handling code from the "directorthrows" typemaps and <tt>director:except</tt> feature. </p> <div class="code"> <pre> -%javaexception("Exception") MyClass::myMethod %{ - try { - $action - } catch (Swig::DirectorException &e) { - // raise/throw the Java exception that originally caused the DirectorException - e.raiseJavaException(jenv); - return $null; +void SwigDirector_MyClass::dirmethod(int x) { + ... [call up to Java using CallStaticVoidMethod] + jthrowable swigerror = jenv->ExceptionOccurred(); + if (swigerror) { + std::cout << "Upcall finished, an exception was thrown in Java" << std::endl; + + if (Swig::ExceptionMatches(jenv, swigerror, "MyException")) { + std::cout << "MyNS::MyException exception matched (directorthrows typemap)" << std::endl; + throw MyNS::MyException(Swig::JavaExceptionMessage(jenv, swigerror).message()); + } + + std::cout << "Upcall finished, no exception conversion, throwing DirectorException" << std::endl; + Swig::DirectorException::raise(jenv, swigerror); + } +</pre> +</div> + +<p> +Let's use the following Java class to override the director method. +</p> + +<div class="code"> +<pre> +class DerivedClass extends MyClass { + @Override + public void dirmethod(int x) { + if (x < 0) + throw new IndexOutOfBoundsException("Index is negative"); + else if (x == 0) + throw new MyException("MyException: bad dirmethod"); } -%} +} +public class runme { + public static void main(String argv[]) { + System.loadLibrary("example"); + ... code snippets shown below ... + } +} </pre> </div> <p> -See the <a href="#Java_exception_handling">Exception handling with %exception and %javaexception</a> -section for more on converting C++ exceptions to Java exceptions. +Consider the output using the Java code in the four slightly different scenarios below. +</p> + +<p> +1. Non-director C++ class is used, thus, no upcall to a Java director method is made. +A <tt>std::out_of_range</tt> exception is thrown, which is derived from <tt>std::exception</tt>, +and hence caught by the generic exception handler in the <tt>call_dirmethod</tt> wrapper. +The Java code snippet and resulting output is: +</p> + + +<div class="code"> +<pre> +MyClass.call_dirmethod(new MyClass(), 0); +</pre> +</div> + +<div class="shell"> +<pre> +Generic std::exception catch handler +Exception in thread "main" java.lang.RuntimeException: MyClass::dirmethod index is out of range + at exampleJNI.MyClass_call_dirmethod(Native Method) + at MyClass.call_dirmethod(MyClass.java:57) + at runme.main(runme.java:14) +</pre> +</div> + +<p> +2. Non-director C++ class again but this time the <tt>MyNS::MyException</tt> class is thrown and caught: +</p> + +<div class="code"> +<pre> +MyClass.call_dirmethod(new MyClass(), 1); +</pre> +</div> + +<div class="shell"> +<pre> +MyNS::MyException caught (throws typemap) +MyNS::MyException class found (throws typemap) +Exception in thread "main" MyException: MyClass::dirmethod some problem! + at exampleJNI.MyClass_call_dirmethod(Native Method) + at MyClass.call_dirmethod(MyClass.java:57) + at runme.main(runme.java:15) +</pre> +</div> + +<p> +3. The <tt>DerivedClass</tt> director class is used so the upcall to Java occurs, but it throws +a Java <tt>MyException</tt>, which gets converted into a C++ <tt>MyNS::MyException</tt>, then caught and converted back +into a Java <tt>MyException</tt>: +</p> + +<div class="code"> +<pre> +MyClass.call_dirmethod(new DerivedClass(), 0); +</pre> +</div> + +<div class="shell"> +<pre> +Upcall finished, an exception was thrown in Java +MyNS::MyException exception matched (directorthrows typemap) +MyNS::MyException caught (throws typemap) +MyNS::MyException class found (throws typemap) +Exception in thread "main" MyException: MyException: bad dirmethod + at exampleJNI.MyClass_call_dirmethod(Native Method) + at MyClass.call_dirmethod(MyClass.java:57) + at runme.main(runme.java:16) +</pre> +</div> + +<p> +4. The director class is used again, but this time the director method throws a Java <tt>IndexOutOfBoundsException</tt> exception which is converted into a C++ <tt>Swig::DirectorException</tt>, thrown and caught again. +This time the original Java exception is extracted from the <tt>Swig::DirectorException</tt> and rethrown. +Note that this approach keeps the stack trace information of the original exception, so it has the exact location of where the <tt>IndexOutOfBoundsException</tt> exception was thrown. +This is arguably an improvement over the approach above that converts from a Java excepton to C++ exception and then back to a new Java exception, losing the location of the original exception. </p> -<H2><a name="Java_allprotected">25.6 Accessing protected members</a></H2> +<div class="code"> +<pre> +MyClass.call_dirmethod(new DerivedClass(), -1); +</pre> +</div> + +<div class="shell"> +<pre> +Upcall finished, an exception was thrown in Java +Upcall finished, no exception conversion, throwing DirectorException +Exception in thread "main" java.lang.IndexOutOfBoundsException: Index is negative + at DerivedClass.dirmethod(runme.java:5) + at exampleJNI.SwigDirector_MyClass_dirmethod(exampleJNI.java:23) + at exampleJNI.MyClass_call_dirmethod(Native Method) + at MyClass.call_dirmethod(MyClass.java:57) + at runme.main(runme.java:17) +</pre> +</div> + +<H2><a name="Java_allprotected">26.6 Accessing protected members</a></H2> <p> @@ -4223,7 +4550,7 @@ class MyProtectedBase extends ProtectedBase -<H2><a name="Java_common_customization">25.7 Common customization features</a></H2> +<H2><a name="Java_common_customization">26.7 Common customization features</a></H2> <p> @@ -4235,7 +4562,7 @@ be awkward. This section describes some common SWIG features that are used to improve the interface to existing C/C++ code. </p> -<H3><a name="Java_helper_functions">25.7.1 C/C++ helper functions</a></H3> +<H3><a name="Java_helper_functions">26.7.1 C/C++ helper functions</a></H3> <p> @@ -4301,7 +4628,7 @@ hard to implement. It is possible to improve on this using Java code, typemaps, customization features as covered in later sections, but sometimes helper functions are a quick and easy solution to difficult cases. </p> -<H3><a name="Java_class_extension">25.7.2 Class extension with %extend</a></H3> +<H3><a name="Java_class_extension">26.7.2 Class extension with %extend</a></H3> <p> @@ -4323,16 +4650,16 @@ struct Vector { %extend Vector { char *toString() { - static char tmp[1024]; - sprintf(tmp, "Vector(%g, %g, %g)", $self->x, $self->y, $self->z); - return tmp; + static char tmp[1024]; + sprintf(tmp, "Vector(%g, %g, %g)", $self->x, $self->y, $self->z); + return tmp; } Vector(double x, double y, double z) { - Vector *v = (Vector *) malloc(sizeof(Vector)); - v->x = x; - v->y = y; - v->z = z; - return v; + Vector *v = (Vector *) malloc(sizeof(Vector)); + v->x = x; + v->y = y; + v->z = z; + return v; } }; </pre> @@ -4364,7 +4691,7 @@ Vector(2, 3, 4) in any way---the extensions only show up in the Java interface. </p> -<H3><a name="Java_proxycode">25.7.3 Class extension with %proxycode</a></H3> +<H3><a name="Java_proxycode">26.7.3 Class extension with %proxycode</a></H3> <p> @@ -4501,7 +4828,7 @@ public class ValueUnsignedInt { </pre> </div> -<H3><a name="Java_exception_handling">25.7.4 Exception handling with %exception and %javaexception</a></H3> +<H3><a name="Java_exception_handling">26.7.4 Exception handling with %exception and %javaexception</a></H3> <p> @@ -4660,7 +4987,7 @@ to raise exceptions. See the <a href="Library.html#Library">SWIG Library</a> ch The typemap example <a href="#Java_exception_typemap">Handling C++ exception specifications as Java exceptions</a> provides further exception handling capabilities. </p> -<H3><a name="Java_method_access">25.7.5 Method access with %javamethodmodifiers</a></H3> +<H3><a name="Java_method_access">26.7.5 Method access with %javamethodmodifiers</a></H3> <p> @@ -4686,7 +5013,7 @@ protected static void protect_me() { </pre> </div> -<H2><a name="Java_tips_techniques">25.8 Tips and techniques</a></H2> +<H2><a name="Java_tips_techniques">26.8 Tips and techniques</a></H2> <p> @@ -4696,7 +5023,7 @@ strings and arrays. This chapter discusses the common techniques for solving these problems. </p> -<H3><a name="Java_input_output_parameters">25.8.1 Input and output parameters using primitive pointers and references</a></H3> +<H3><a name="Java_input_output_parameters">26.8.1 Input and output parameters using primitive pointers and references</a></H3> <p> @@ -4870,7 +5197,7 @@ void foo(Bar *OUTPUT); will not have the intended effect since <tt>typemaps.i</tt> does not define an OUTPUT rule for <tt>Bar</tt>. </p> -<H3><a name="Java_simple_pointers">25.8.2 Simple pointers</a></H3> +<H3><a name="Java_simple_pointers">26.8.2 Simple pointers</a></H3> <p> @@ -4936,7 +5263,7 @@ System.out.println("3 + 4 = " + result); See the <a href="Library.html#Library">SWIG Library</a> chapter for further details. </p> -<H3><a name="Java_c_arrays">25.8.3 Wrapping C arrays with Java arrays</a></H3> +<H3><a name="Java_c_arrays">26.8.3 Wrapping C arrays with Java arrays</a></H3> <p> @@ -5003,7 +5330,7 @@ Please be aware that the typemaps in this library are not efficient as all the e There is an alternative approach using the SWIG array library and this is covered in the next section. </p> -<H3><a name="Java_unbounded_c_arrays">25.8.4 Unbounded C Arrays</a></H3> +<H3><a name="Java_unbounded_c_arrays">26.8.4 Unbounded C Arrays</a></H3> <p> @@ -5148,7 +5475,7 @@ well suited for applications in which you need to create buffers, package binary data, etc. </p> -<H3><a name="Java_binary_char">25.8.5 Binary data vs Strings</a></H3> +<H3><a name="Java_binary_char">26.8.5 Binary data vs Strings</a></H3> <p> @@ -5192,7 +5519,7 @@ len: 5 data: 68 69 0 6a 6b </pre></div> -<H3><a name="Java_heap_allocations">25.8.6 Overriding new and delete to allocate from Java heap</a></H3> +<H3><a name="Java_heap_allocations">26.8.6 Overriding new and delete to allocate from Java heap</a></H3> <p> @@ -5266,7 +5593,7 @@ void * operator new(size_t t) { throw bad_alloc(); pJalloc->ref = 0; return static_cast<void *>( - static_cast<char *>(static_cast<void *>(pJalloc)) + sizeof(Jalloc)); + static_cast<char *>(static_cast<void *>(pJalloc)) + sizeof(Jalloc)); } } @@ -5309,7 +5636,7 @@ model and use these functions in place of malloc and free in your own code. </p> -<H2><a name="Java_typemaps">25.9 Java typemaps</a></H2> +<H2><a name="Java_typemaps">26.9 Java typemaps</a></H2> <p> @@ -5317,7 +5644,7 @@ This section describes how you can modify SWIG's default wrapping behavior for various C/C++ datatypes using the <tt>%typemap</tt> directive. You are advised to be familiar with the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. While not absolutely essential knowledge, this section assumes some familiarity with the Java Native Interface (JNI). -JNI documentation can be consulted either online at <a href="http://java.sun.com">Sun's Java web site</a> or from a good JNI book. +JNI documentation can be consulted either online at <a href="https://www.oracle.com/technetwork/java/index.html">the Java web site</a> or from a good JNI book. The following two books are recommended:</p> <ul> @@ -5330,7 +5657,7 @@ Before proceeding, it should be stressed that typemaps are not 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 generated code. -<H3><a name="Java_default_primitive_type_mappings">25.9.1 Default primitive type mappings</a></H3> +<H3><a name="Java_default_primitive_type_mappings">26.9.1 Default primitive type mappings</a></H3> <p> @@ -5482,7 +5809,7 @@ However, the mappings allow the full range of values for each C type from Java. </p> -<H3><a name="Java_default_non_primitive_typemaps">25.9.2 Default typemaps for non-primitive types</a></H3> +<H3><a name="Java_default_non_primitive_typemaps">26.9.2 Default typemaps for non-primitive types</a></H3> <p> @@ -5497,7 +5824,7 @@ So in summary, the C/C++ pointer to non-primitive types is cast into the 64 bit The Java type is either the proxy class or type wrapper class. </p> -<H3><a name="Java_jvm64">25.9.3 Sixty four bit JVMs</a></H3> +<H3><a name="Java_jvm64">26.9.3 Sixty four bit JVMs</a></H3> <p> @@ -5510,7 +5837,7 @@ Unfortunately it won't of course hold true for JNI code. </p> -<H3><a name="Java_what_is_typemap">25.9.4 What is a typemap?</a></H3> +<H3><a name="Java_what_is_typemap">26.9.4 What is a typemap?</a></H3> <p> @@ -5633,7 +5960,7 @@ int c = example.count('e', "Hello World"); </pre> </div> -<H3><a name="Java_typemaps_c_to_java_types">25.9.5 Typemaps for mapping C/C++ types to Java types</a></H3> +<H3><a name="Java_typemaps_c_to_java_types">26.9.5 Typemaps for mapping C/C++ types to Java types</a></H3> <p> @@ -5682,6 +6009,17 @@ The most important of these implement the mapping of C/C++ types to Java types: </tr> <tr> +<td>jboxtype</td> +<td>Java boxed type. + These are Java code typemaps to provide the Java boxed type, such as, <tt>Integer</tt> for C type <tt>int</tt>. + As autoboxing is only relevant to the Java primitive types, these are only provided for the + C types that map to Java primitive types. + This typemap is usually only used by C++ STL container wrappers that are wrapped by Java generic + types as the boxed type must be used instead of the unboxed/primitive type when declaring a Java generic type. + </td> +</tr> + +<tr> <td>javadirectorin</td> <td>Conversion from jtype to jstype for director methods. These are Java code typemaps which transform the type used in the Java intermediary JNI class (as specified in the "jtype" typemap) to @@ -5902,7 +6240,7 @@ These are listed below: </table> -<H3><a name="Java_typemap_attributes">25.9.6 Java typemap attributes</a></H3> +<H3><a name="Java_typemap_attributes">26.9.6 Java typemap attributes</a></H3> <p> @@ -5948,7 +6286,7 @@ The "javain" typemap has the optional 'pre', 'post' and 'pgcppname' attributes. Note that when the 'pre' or 'post' attributes are specified and the associated type is used in a constructor, a constructor helper function is generated. This is necessary as the Java proxy constructor wrapper makes a call to a support constructor using a <i>this</i> call. In Java the <i>this</i> call must be the first statement in the constructor body. The constructor body thus calls the helper function and the helper function instead makes the JNI call, ensuring the 'pre' code is called before the JNI call is made. There is a <a href="#Java_date_marshalling">Date marshalling</a> example showing 'pre', 'post' and 'pgcppname' attributes in action. </p> -<H3><a name="Java_special_variables">25.9.7 Java special variables</a></H3> +<H3><a name="Java_special_variables">26.9.7 Java special variables</a></H3> <p> @@ -6130,7 +6468,7 @@ in that it is not fully qualified with the package name when using the <a href="SWIGPlus.html#SWIGPlus_nspace">nspace feature</a>. </p> -<H3><a name="Java_typemaps_for_c_and_cpp">25.9.8 Typemaps for both C and C++ compilation</a></H3> +<H3><a name="Java_typemaps_for_c_and_cpp">26.9.8 Typemaps for both C and C++ compilation</a></H3> <p> @@ -6167,7 +6505,7 @@ If you do not intend your code to be targeting both C and C++ then your typemaps </p> -<H3><a name="Java_code_typemaps">25.9.9 Java code typemaps</a></H3> +<H3><a name="Java_code_typemaps">26.9.9 Java code typemaps</a></H3> <p> @@ -6213,7 +6551,7 @@ As there can only be one "javacode" typemap per class, also consider using the and offers nearly identical functionality. </div> -<p><tt>%typemap(javadestruct, methodname="delete", methodmodifiers="public synchronized")</tt> <br></p> +<p><tt>%typemap(javadestruct, methodname="delete", methodmodifiers="public synchronized", parameters="")</tt> <br></p> <div class="indent"> destructor wrapper - the <tt>delete()</tt> method (proxy classes only), used for all proxy classes except those which have a base class @@ -6222,9 +6560,12 @@ used for all proxy classes except those which have a base class <br> Note that the <tt>delete()</tt> method name is configurable and is specified by the <tt>methodname</tt> attribute. The method modifiers are also configurable via the <tt>methodmodifiers</tt> attribute. +If a <tt>%javamethodmodifiers</tt> is attached to the class' destructor, +it will be used in preference to the <tt>methodmodifiers</tt> typemap attribute for the class. +The <tt>delete</tt> method's parameters declaration can be provided in the optional <tt>parameters</tt> typemap attribute. </div> -<p><tt>%typemap(javadestruct_derived, methodname="delete", methodmodifiers="public synchronized")</tt></p> +<p><tt>%typemap(javadestruct_derived, methodname="delete", methodmodifiers="public synchronized", parameters="")</tt></p> <div class="indent"> destructor wrapper - the <tt>delete()</tt> method (proxy classes only), same as "javadestruct" but only used for derived proxy classes @@ -6233,6 +6574,9 @@ same as "javadestruct" but only used for derived proxy classes <br> Note that the <tt>delete()</tt> method name is configurable and is specified by the <tt>methodname</tt> attribute. The method modifiers are also configurable via the <tt>methodmodifiers</tt> attribute. +If a <tt>%javamethodmodifiers</tt> is attached to the class' destructor, +it will be used in preference to the <tt>methodmodifiers</tt> typemap attribute for the class. +The <tt>delete</tt> method's parameters declaration can be provided in the optional <tt>parameters</tt> typemap attribute. </div> <p><tt>%typemap(javaimports)</tt></p> @@ -6459,7 +6803,7 @@ to make the method and constructor public: </pre> </div> -<H3><a name="Java_directors_typemaps">25.9.10 Director specific typemaps</a></H3> +<H3><a name="Java_directors_typemaps">26.9.10 Director specific typemaps</a></H3> <p> @@ -6736,7 +7080,7 @@ The basic strategy here is to provide a default package typemap for the majority </div> -<H2><a name="Java_typemap_examples">25.10 Typemap Examples</a></H2> +<H2><a name="Java_typemap_examples">26.10 Typemap Examples</a></H2> <p> @@ -6746,7 +7090,7 @@ the SWIG library. </p> -<H3><a name="Java_simpler_enum_classes">25.10.1 Simpler Java enums for enums without initializers</a></H3> +<H3><a name="Java_simpler_enum_classes">26.10.1 Simpler Java enums for enums without initializers</a></H3> <p> @@ -6825,7 +7169,7 @@ This would be done by using the original versions of these typemaps in "enums.sw </p> -<H3><a name="Java_exception_typemap">25.10.2 Handling C++ exception specifications as Java exceptions</a></H3> +<H3><a name="Java_exception_typemap">26.10.2 Handling C++ exception specifications as Java exceptions</a></H3> <p> @@ -6950,7 +7294,7 @@ We could alternatively have used <tt>%rename</tt> to rename <tt>what()</tt> into </p> -<H3><a name="Java_nan_exception_typemap">25.10.3 NaN Exception - exception handling for a particular type</a></H3> +<H3><a name="Java_nan_exception_typemap">26.10.3 NaN Exception - exception handling for a particular type</a></H3> <p> @@ -7105,7 +7449,7 @@ If we were a martyr to the JNI cause, we could replace the succinct code within If we had, we would have put it in the "in" typemap which, like all JNI and Java typemaps, also supports the 'throws' attribute. </p> -<H3><a name="Java_converting_java_string_arrays">25.10.4 Converting Java String arrays to char ** </a></H3> +<H3><a name="Java_converting_java_string_arrays">26.10.4 Converting Java String arrays to char ** </a></H3> <p> @@ -7217,7 +7561,7 @@ public class runme { example.print_args(animals); String args[] = example.get_args(); for (int i=0; i<args.length; i++) - System.out.println(i + ":" + args[i]); + System.out.println(i + ":" + args[i]); } } </pre></div> @@ -7249,7 +7593,7 @@ Lastly the "jni", "jtype" and "jstype" typemaps are also required to specify what Java types to use. </p> -<H3><a name="Java_expanding_java_object">25.10.5 Expanding a Java object to multiple arguments</a></H3> +<H3><a name="Java_expanding_java_object">26.10.5 Expanding a Java object to multiple arguments</a></H3> <p> @@ -7331,7 +7675,7 @@ example.foo(new String[]{"red", "green", "blue", "white"}); </div> -<H3><a name="Java_using_typemaps_return_arguments">25.10.6 Using typemaps to return arguments</a></H3> +<H3><a name="Java_using_typemaps_return_arguments">26.10.6 Using typemaps to return arguments</a></H3> <p> @@ -7449,7 +7793,7 @@ $ java runme 1 12.0 340.0 </pre></div> -<H3><a name="Java_adding_downcasts">25.10.7 Adding Java downcasts to polymorphic return types</a></H3> +<H3><a name="Java_adding_downcasts">26.10.7 Adding Java downcasts to polymorphic return types</a></H3> <p> @@ -7655,7 +7999,7 @@ SWIG usually generates code which constructs the proxy classes using Java code a Note that the JNI code above uses a number of string lookups to call a constructor, whereas this would not occur using byte compiled Java code. </p> -<H3><a name="Java_adding_equals_method">25.10.8 Adding an equals method to the Java classes</a></H3> +<H3><a name="Java_adding_equals_method">26.10.8 Adding an equals method to the Java classes</a></H3> <p> @@ -7699,7 +8043,7 @@ System.out.println("foo1? " + foo1.equals(foo2)); </div> -<H3><a name="Java_void_pointers">25.10.9 Void pointers and a common Java base class</a></H3> +<H3><a name="Java_void_pointers">26.10.9 Void pointers and a common Java base class</a></H3> <p> @@ -7758,7 +8102,7 @@ This example contains some useful functionality which you may want in your code. <li> It also has a function which effectively implements a cast from the type of the proxy/type wrapper class to a void pointer. This is necessary for passing a proxy class or a type wrapper class to a function that takes a void pointer. </ul> -<H3><a name="Java_struct_pointer_pointer">25.10.10 Struct pointer to pointer</a></H3> +<H3><a name="Java_struct_pointer_pointer">26.10.10 Struct pointer to pointer</a></H3> <p> @@ -7938,7 +8282,7 @@ The C functional interface has been completely morphed into an object-oriented i the Butler class would behave much like any pure Java class and feel more natural to Java users. </p> -<H3><a name="Java_memory_management_member_variables">25.10.11 Memory management when returning references to member variables</a></H3> +<H3><a name="Java_memory_management_member_variables">26.10.11 Memory management when returning references to member variables</a></H3> <p> @@ -7953,7 +8297,7 @@ Consider the following C++ code: <pre> struct Wheel { int size; - Wheel(int sz) : size(sz) {} + Wheel(int sz = 0) : size(sz) {} }; class Bike { @@ -8061,7 +8405,7 @@ public class Bike { Note the <tt>addReference</tt> call. </p> -<H3><a name="Java_memory_management_objects">25.10.12 Memory management for objects passed to the C++ layer</a></H3> +<H3><a name="Java_memory_management_objects">26.10.12 Memory management for objects passed to the C++ layer</a></H3> <p> @@ -8113,7 +8457,7 @@ System.out.println("element value: " + container.getElement().getValue()); <p> The C++ code will always print out 20, but the value printed out may not be this in the Java equivalent code. -In order to understand why, consider a garbage collection occuring... +In order to understand why, consider a garbage collection occurring... </p> <div class="code"> @@ -8142,42 +8486,54 @@ public class Container { // Ensure that the GC doesn't collect any Element set from Java // as the underlying C++ class stores a shallow copy private Element elementReference; - private long getCPtrAndAddReference(Element element) { - elementReference = element; - return Element.getCPtr(element); - } public void setElement(Element e) { - exampleJNI.Container_setElement(swigCPtr, this, getCPtrAndAddReference(e), e); + exampleJNI.Container_setElement(swigCPtr, this, Element.getCPtr(e), e); + elementReference = e; } } </pre> </div> <p> -The following typemaps will generate the desired code. -The 'javain' typemap matches the input parameter type for the <tt>setElement</tt> method. -The 'javacode' typemap simply adds in the specified code into the Java proxy class. +The following typemaps can be used to generate this code: </p> <div class="code"> <pre> -%typemap(javain) Element *e "getCPtrAndAddReference($javainput)" - %typemap(javacode) Container %{ // Ensure that the GC doesn't collect any element set from Java // as the underlying C++ class stores a shallow copy private Element elementReference; - private long getCPtrAndAddReference(Element element) { - elementReference = element; - return Element.getCPtr(element); - } %} + +%typemap(javain, + post=" elementReference = $javainput;" + ) Element *e "Element.getCPtr($javainput)" </pre> </div> +<p> +The 'javacode' typemap simply adds in the specified code into the Java proxy class. +The 'javain' typemap matches the input parameter type and name for the <tt>setElement</tt> method and +the 'post' typemap attribute allows adding code after the JNI call. +The 'post' code is generated into a finally block after the JNI call so the resulting code isn't quite +as mentioned earlier, <tt>setElement</tt> is actually: +</p> + +<div class="code"> +<pre> + public void setElement(Element e) { + try { + exampleJNI.Container_setElement(swigCPtr, this, Element.getCPtr(e), e); + } finally { + elementReference = e; + } + } +</pre> +</div> -<H3><a name="Java_date_marshalling">25.10.13 Date marshalling using the javain typemap and associated attributes</a></H3> +<H3><a name="Java_date_marshalling">26.10.13 Date marshalling using the javain typemap and associated attributes</a></H3> <p> @@ -8243,7 +8599,7 @@ The <tt>CDate &</tt> and <tt>const CDate &</tt> Java code is generated f <p> where '$javaclassname' is translated into the proxy class name, <tt>CDate</tt> and '$javainput' is translated into the name of the parameter, eg <tt>dateIn</tt>. -From Java, the intention is then to call into a modifed API with something like: +From Java, the intention is then to call into a modified API with something like: </p> <div class="code"> @@ -8354,7 +8710,7 @@ A few things to note: -<H2><a name="Java_directors_faq">25.11 Living with Java Directors</a></H2> +<H2><a name="Java_directors_faq">26.11 Living with Java Directors</a></H2> <p> @@ -8533,10 +8889,10 @@ public abstract class UserVisibleFoo extends Foo { </li> </ol> -<H2><a name="Java_odds_ends">25.12 Odds and ends</a></H2> +<H2><a name="Java_odds_ends">26.12 Odds and ends</a></H2> -<H3><a name="Java_javadoc_comments">25.12.1 JavaDoc comments</a></H3> +<H3><a name="Java_javadoc_comments">26.12.1 JavaDoc comments</a></H3> <p> @@ -8592,7 +8948,7 @@ public class Barmy { -<H3><a name="Java_functional_interface">25.12.2 Functional interface without proxy classes</a></H3> +<H3><a name="Java_functional_interface">26.12.2 Functional interface without proxy classes</a></H3> <p> @@ -8653,7 +9009,7 @@ All destructors have to be called manually for example the <tt>delete_Foo(foo)</ </p> -<H3><a name="Java_using_own_jni_functions">25.12.3 Using your own JNI functions</a></H3> +<H3><a name="Java_using_own_jni_functions">26.12.3 Using your own JNI functions</a></H3> <p> @@ -8703,7 +9059,7 @@ This directive is only really useful if you want to mix your own hand crafted JN </p> -<H3><a name="Java_performance">25.12.4 Performance concerns and hints</a></H3> +<H3><a name="Java_performance">26.12.4 Performance concerns and hints</a></H3> <p> @@ -8724,7 +9080,7 @@ However, you will have to be careful about memory management and make sure that This method normally calls the C++ destructor or <tt>free()</tt> for C code. </p> -<H3><a name="Java_debugging">25.12.5 Debugging</a></H3> +<H3><a name="Java_debugging">26.12.5 Debugging</a></H3> <p> @@ -8746,7 +9102,7 @@ The -verbose:jni and -verbose:gc are also useful options for monitoring code beh </p> -<H2><a name="Java_examples">25.13 Java Examples</a></H2> +<H2><a name="Java_examples">26.13 Java Examples</a></H2> <p> diff --git a/Doc/Manual/Javascript.html b/Doc/Manual/Javascript.html index b1ec37055..0b301377c 100644 --- a/Doc/Manual/Javascript.html +++ b/Doc/Manual/Javascript.html @@ -1,13 +1,13 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> -<link rel="stylesheet" type="text/css" href="./style.css"> +<link rel="stylesheet" type="text/css" href="style.css"> <title></title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head> <body> -<H1><a name="Javascript">26 SWIG and Javascript</a></H1> +<H1><a name="Javascript">27 SWIG and Javascript</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -52,21 +52,21 @@ <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><a name="Javascript_overview">26.1 Overview</a></H2> +<H2><a name="Javascript_overview">27.1 Overview</a></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> +Javascript has gone beyond being a browser-based scripting language and with <a href="https://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 <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. +<p>SWIG Javascript currently supports <strong>JavascriptCore</strong>, the Javascript engine used by <code>Safari/Webkit</code>, and <a href="https://v8.dev/"><strong>v8</strong></a>, which is used by <code>Chromium</code> and <code>node.js</code>.</p> +<p><a href="https://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><a name="Javascript_preliminaries">26.2 Preliminaries</a></H2> +<H2><a name="Javascript_preliminaries">27.2 Preliminaries</a></H2> -<H3><a name="Javascript_running_swig">26.2.1 Running SWIG</a></H3> +<H3><a name="Javascript_running_swig">27.2.1 Running SWIG</a></H3> <p>Suppose that you defined a SWIG module such as the following:</p> @@ -101,7 +101,7 @@ that era had a component > 99. For example:</p> <pre> $ swig -c++ -javascript -v8 -DV8_VERSION=0x032530 example.i</pre> </div> -<p>If you're targetting V8 >= 4.3.0, you would just run swig like so:</p> +<p>If you're targeting V8 >= 4.3.0, you would just run swig like so:</p> <div class="shell"> <pre> $ swig -c++ -javascript -v8 example.i</pre> @@ -121,7 +121,7 @@ void example_initialize(v8::Handle<v8::Object> exports)</pre> <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><a name="Javascript_running_tests_examples">26.2.2 Running Tests and Examples</a></H3> +<H3><a name="Javascript_running_tests_examples">27.2.2 Running Tests and Examples</a></H3> <p>The configuration for tests and examples currently supports Linux and Mac only and not MinGW (Windows) yet.</p> @@ -153,7 +153,7 @@ $ make check-javascript-test-suite ENGINE=jsc</pre> $ make check-javascript-examples V8_VERSION=0x032530 ENGINE=v8</pre> </div> -<H3><a name="Javascript_known_issues">26.2.3 Known Issues</a></H3> +<H3><a name="Javascript_known_issues">27.2.3 Known Issues</a></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> @@ -161,21 +161,20 @@ $ make check-javascript-examples V8_VERSION=0x032530 ENGINE=v8</pre> <ul> <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>C89 incompatibility: 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> <p>The primary development environment has been Linux (Ubuntu 12.04). Windows and Mac OS X 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">26.3 Integration</a></H2> +<H2><a name="Javascript_integration">27.3 Integration</a></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><a name="Javascript_node_extensions">26.3.1 Creating node.js Extensions</a></H3> +<H3><a name="Javascript_node_extensions">27.3.1 Creating node.js Extensions</a></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 Mac OS X 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/ubuntu/node.js/">PPA</a> available.</p> @@ -221,7 +220,7 @@ require("./build/Release/example")</pre> </div> <p>A more detailed explanation is given in the <a href="#Javascript_examples">Examples</a> section.</p> -<H4><a name="Javascript_troubleshooting">26.3.1.1 Troubleshooting</a></H4> +<H4><a name="Javascript_troubleshooting">27.3.1.1 Troubleshooting</a></H4> <ul> @@ -233,12 +232,12 @@ require("./build/Release/example")</pre> $ sudo apt-get remove gyp</pre> </div> -<H3><a name="Javascript_embedded_webkit">26.3.2 Embedded Webkit</a></H3> +<H3><a name="Javascript_embedded_webkit">27.3.2 Embedded Webkit</a></H3> <p>Webkit is pre-installed on Mac OS X and available as a library for GTK.</p> -<H4><a name="Javascript_osx">26.3.2.1 Mac OS X</a></H4> +<H4><a name="Javascript_osx">27.3.2.1 Mac OS X</a></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> @@ -286,10 +285,10 @@ extern bool example_initialize(JSGlobalContextRef context, JSObjectRef* exports) @end</pre> </div> -<H4><a name="Javascript_gtk">26.3.2.2 GTK</a></H4> +<H4><a name="Javascript_gtk">27.3.2.2 GTK</a></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>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> @@ -331,7 +330,7 @@ int main(int argc, char* argv[]) }</pre> </div> -<H3><a name="Javascript_applications_webkit">26.3.3 Creating Applications with node-webkit</a></H3> +<H3><a name="Javascript_applications_webkit">27.3.3 Creating Applications with node-webkit</a></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> @@ -422,12 +421,12 @@ open new windows, and many more things. };</pre> </div> -<H2><a name="Javascript_examples">26.4 Examples</a></H2> +<H2><a name="Javascript_examples">27.4 Examples</a></H2> <p>Some basic examples are shown here in more detail.</p> -<H3><a name="Javascript_simple_example">26.4.1 Simple</a></H3> +<H3><a name="Javascript_simple_example">27.4.1 Simple</a></H3> <p>The common example <code>simple</code> looks like this:</p> @@ -477,7 +476,7 @@ example.Foo = 3.1415926;</pre> <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> -<H3><a name="Javascript_class_example">26.4.2 Class</a></H3> +<H3><a name="Javascript_class_example">27.4.2 Class</a></H3> <p>The common example <code>class</code> defines three classes, <code>Shape</code>, <code>Circle</code>, and <code>Square</code>:</p> @@ -604,15 +603,15 @@ at ReadStream.EventEmitter.emit (events.js:98:17) at emitKey (readline.js:1095:12)</pre> </div> <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. +<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/Inheritance_and_the_prototype_chain">Inheritance and the prototype chain</a>, for instance. </p> -<H2><a name="Javascript_implementation">26.5 Implementation</a></H2> +<H2><a name="Javascript_implementation">27.5 Implementation</a></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><a name="Javascript_source_code">26.5.1 Source Code</a></H3> +<H3><a name="Javascript_source_code">27.5.1 Source Code</a></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> @@ -713,7 +712,7 @@ Template::Template(const String *code_) { ... } ...</pre> </div> -<H3><a name="Javascript_code_templates">26.5.2 Code Templates</a></H3> +<H3><a name="Javascript_code_templates">27.5.2 Code Templates</a></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> @@ -752,7 +751,7 @@ 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><a name="Javascript_emitter">26.5.3 Emitter</a></H3> +<H3><a name="Javascript_emitter">27.5.3 Emitter</a></H3> <p>The Javascript module delegates code generation to a <code>JSEmitter</code> instance. The following extract shows the essential interface:</p> @@ -871,7 +870,7 @@ int JAVASCRIPT::classHandler(Node *n) { </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><a name="Javascript_emitter_states">26.5.4 Emitter states</a></H3> +<H3><a name="Javascript_emitter_states">27.5.4 Emitter states</a></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> @@ -915,7 +914,7 @@ state.clazz(NAME, Getattr(n, "sym:name"));</pre> <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">26.5.5 Handling Exceptions in JavascriptCore</a></H3> +<H3><a name="Javascript_jsc_exceptions">27.5.5 Handling Exceptions in JavascriptCore</a></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> diff --git a/Doc/Manual/Library.html b/Doc/Manual/Library.html index 4bad9a03e..560859234 100644 --- a/Doc/Manual/Library.html +++ b/Doc/Manual/Library.html @@ -7,31 +7,38 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Library">9 SWIG library</a></H1> +<H1><a name="Library">11 SWIG library</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> <li><a href="#Library_nn2">The %include directive and library search path</a> -<li><a href="#Library_nn3">C Arrays and Pointers</a> +<li><a href="#Library_nn3">C arrays and pointers</a> <ul> <li><a href="#Library_nn4">cpointer.i</a> <li><a href="#Library_carrays">carrays.i</a> <li><a href="#Library_nn6">cmalloc.i</a> <li><a href="#Library_nn7">cdata.i</a> </ul> -<li><a href="#Library_nn8">C String Handling</a> +<li><a href="#Library_nn8">C string handling</a> <ul> <li><a href="#Library_nn9">Default string handling</a> <li><a href="#Library_nn10">Passing binary data</a> <li><a href="#Library_nn11">Using %newobject to release memory</a> <li><a href="#Library_nn12">cstring.i</a> </ul> -<li><a href="#Library_stl_cpp_library">STL/C++ Library</a> +<li><a href="#Library_stl_cpp_library">STL/C++ library</a> <ul> <li><a href="#Library_std_string">std::string</a> <li><a href="#Library_std_vector">std::vector</a> <li><a href="#Library_stl_exceptions">STL exceptions</a> <li><a href="#Library_std_shared_ptr">shared_ptr smart pointer</a> +<ul> +<li><a href="#Library_shared_ptr_basics">shared_ptr basics</a> +<li><a href="#Library_shared_ptr_inheritance">shared_ptr and inheritance</a> +<li><a href="#Library_shared_ptr_overloading">shared_ptr and method overloading</a> +<li><a href="#Library_shared_ptr_templates">shared_ptr and templates</a> +<li><a href="#Library_shared_ptr_directors">shared_ptr and directors</a> +</ul> <li><a href="#Library_std_auto_ptr">auto_ptr smart pointer</a> </ul> <li><a href="#Library_nn16">Utility Libraries</a> @@ -60,7 +67,7 @@ Alternative libraries provide similar functionality. Please read this chapter carefully if you used the old libraries. </p> -<H2><a name="Library_nn2">9.1 The %include directive and library search path</a></H2> +<H2><a name="Library_nn2">11.1 The %include directive and library search path</a></H2> <p> @@ -92,7 +99,7 @@ Set the environment variable to hold an alternative library directory. The directories that are searched are displayed when using <tt>-verbose</tt> commandline option. </p> -<H2><a name="Library_nn3">9.2 C Arrays and Pointers</a></H2> +<H2><a name="Library_nn3">11.2 C arrays and pointers</a></H2> <p> @@ -104,7 +111,7 @@ pointers as class-like objects. Since these functions provide direct access to memory, their use is potentially unsafe and you should exercise caution. </p> -<H3><a name="Library_nn4">9.2.1 cpointer.i</a></H3> +<H3><a name="Library_nn4">11.2.1 cpointer.i</a></H3> <p> @@ -320,7 +327,7 @@ In this example, the function <tt>int_to_uint()</tt> would be used to cast type <b>Note:</b> When working with simple pointers, typemaps can often be used to provide more seamless operation. </p> -<H3><a name="Library_carrays">9.2.2 carrays.i</a></H3> +<H3><a name="Library_carrays">11.2.2 carrays.i</a></H3> <p> @@ -411,13 +418,13 @@ void print_array(double x[10]); Now, in a scripting language, you might write this: </p> -<div class="code"> +<div class="targetlang"> <pre> -a = new_doubleArray(10) # Create an array +a = new_doubleArray(10) # Create an array for i in range(0, 10): - doubleArray_setitem(a, i, 2*i) # Set a value -print_array(a) # Pass to C -delete_doubleArray(a) # Destroy array + doubleArray_setitem(a, i, 2 * i) # Set a value +print_array(a) # Pass to C +delete_doubleArray(a) # Destroy array </pre> </div> @@ -475,12 +482,12 @@ void print_array(double x[10]); Allows you to do this: </p> -<div class="code"> +<div class="targetlang"> <pre> import example c = example.doubleArray(10) # Create double[10] for i in range(0, 10): - c[i] = 2*i # Assign values + c[i] = 2 * i # Assign values example.print_array(c) # Pass to C </pre> </div> @@ -496,9 +503,10 @@ you should consider using a special array object rather than a bare pointer. <p> <b>Note:</b> <tt>%array_functions()</tt> and <tt>%array_class()</tt> should not be used with types of <tt>char</tt> or <tt>char *</tt>. +SWIG's default handling of these types is to handle them as character strings and the two macros do not do enough to change this. </p> -<H3><a name="Library_nn6">9.2.3 cmalloc.i</a></H3> +<H3><a name="Library_nn6">11.2.3 cmalloc.i</a></H3> <p> @@ -659,7 +667,7 @@ Now, in a script: </pre> </div> -<H3><a name="Library_nn7">9.2.4 cdata.i</a></H3> +<H3><a name="Library_nn7">11.2.4 cdata.i</a></H3> <p> @@ -761,7 +769,7 @@ char *cdata_<em>name</em>(type* ptr, int nitems) Clearly they are unsafe. </p> -<H2><a name="Library_nn8">9.3 C String Handling</a></H2> +<H2><a name="Library_nn8">11.3 C string handling</a></H2> <p> @@ -781,7 +789,7 @@ morality. The modules in this section provide basic functionality for manipulating raw C strings. </p> -<H3><a name="Library_nn9">9.3.1 Default string handling</a></H3> +<H3><a name="Library_nn9">11.3.1 Default string handling</a></H3> <p> @@ -801,7 +809,7 @@ target language. In other words, if you were using a language like Tcl, and you wrote this, </p> -<div class="code"> +<div class="targetlang"> <pre> % foo Hello </pre> @@ -822,7 +830,7 @@ interpreter and lead to a crash). Furthermore, the default behavior does not work well with binary data. Instead, strings are assumed to be NULL-terminated. </p> -<H3><a name="Library_nn10">9.3.2 Passing binary data</a></H3> +<H3><a name="Library_nn10">11.3.2 Passing binary data</a></H3> <p> @@ -852,7 +860,7 @@ size_t parity(char *str, size_t len, size_t initial); Now, in the target language, you can use binary string data like this: </p> -<div class="code"> +<div class="targetlang"> <pre> >>> s = "H\x00\x15eg\x09\x20" >>> parity(s, 0) @@ -864,7 +872,7 @@ In the wrapper function, the passed string will be expanded to a pointer and len The <tt>(char *STRING, int LENGTH)</tt> multi-argument typemap is also available in addition to <tt>(char *STRING, size_t LENGTH)</tt>. </p> -<H3><a name="Library_nn11">9.3.3 Using %newobject to release memory</a></H3> +<H3><a name="Library_nn11">11.3.3 Using %newobject to release memory</a></H3> <p> @@ -905,7 +913,7 @@ however, you may need to provide your own "newfree" typemap for other types. See <a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for more details. </p> -<H3><a name="Library_nn12">9.3.4 cstring.i</a></H3> +<H3><a name="Library_nn12">11.3.4 cstring.i</a></H3> <p> @@ -1357,7 +1365,7 @@ to accomplish this in SWIG. This library provides support for a few common tech </li> <li>If used in C++, this library uses <tt>new</tt> and <tt>delete []</tt> for memory -allocation. If using ANSI C, the library uses <tt>malloc()</tt> and <tt>free()</tt>. +allocation. If using C, the library uses <tt>malloc()</tt> and <tt>free()</tt>. </li> <li>Rather than manipulating <tt>char *</tt> directly, you might consider using a special string @@ -1365,7 +1373,7 @@ structure or class instead. </li> </ul> -<H2><a name="Library_stl_cpp_library">9.4 STL/C++ Library</a></H2> +<H2><a name="Library_stl_cpp_library">11.4 STL/C++ library</a></H2> <p> @@ -1385,16 +1393,24 @@ The following table shows which C++ classes are supported and the equivalent SWI <td><b>SWIG Interface library file</b></td> </tr> +<tr> <td>std::array (C++11)</td> <td>array</td> <td>std_array.i</td> </tr> <tr> <td>std::auto_ptr</td> <td>memory</td> <td>std_auto_ptr.i</td> </tr> +<tr> <td>std::complex</td> <td>complex</td> <td>std_complex.i</td> </tr> <tr> <td>std::deque</td> <td>deque</td> <td>std_deque.i</td> </tr> <tr> <td>std::list</td> <td>list</td> <td>std_list.i</td> </tr> <tr> <td>std::map</td> <td>map</td> <td>std_map.i</td> </tr> +<tr> <td>std::multimap (C++11)</td> <td>multimap</td> <td>std_multimap.i</td> </tr> +<tr> <td>std::multiset (C++11)</td> <td>multiset</td> <td>std_multiset.i</td> </tr> <tr> <td>std::pair</td> <td>utility</td> <td>std_pair.i</td> </tr> <tr> <td>std::set</td> <td>set</td> <td>std_set.i</td> </tr> <tr> <td>std::string</td> <td>string</td> <td>std_string.i</td> </tr> +<tr> <td>std::unordered_map (C++11)</td> <td>unordered_map</td> <td>std_unordered_map.i</td> </tr> +<tr> <td>std::unordered_multimap (C++11)</td> <td>unordered_multimap</td> <td>std_unordered_multimap.i</td> </tr> +<tr> <td>std::unordered_multiset (C++11)</td> <td>unordered_multiset</td> <td>std_unordered_multiset.i</td> </tr> +<tr> <td>std::unordered_set (C++11)</td> <td>unordered_set</td> <td>std_unordered_set.i</td> </tr> <tr> <td>std::vector</td> <td>vector</td> <td>std_vector.i</td> </tr> -<tr> <td>std::array</td> <td>array (C++11)</td> <td>std_array.i</td> </tr> -<tr> <td>std::shared_ptr</td> <td>shared_ptr (C++11)</td> <td>std_shared_ptr.i</td> </tr> +<tr> <td>std::wstring</td> <td>wstring</td> <td>std_wstring.i</td> </tr> +<tr> <td>std::shared_ptr (C++11)</td> <td>shared_ptr</td> <td>std_shared_ptr.i</td> </tr> </table> @@ -1404,7 +1420,7 @@ Please look for the library files in the appropriate language library directory. </p> -<H3><a name="Library_std_string">9.4.1 std::string</a></H3> +<H3><a name="Library_std_string">11.4.1 std::string</a></H3> <p> @@ -1460,7 +1476,7 @@ In the target language: <div class="targetlang"> <pre> x = my_struct(); -x.foo="Hello World"; # assign with string +x.foo = "Hello World"; # assign with string print x.foo; # print as string </pre> </div> @@ -1488,7 +1504,7 @@ void foo(string s, const String &t); // std_string typemaps still applie </pre> </div> -<H3><a name="Library_std_vector">9.4.2 std::vector</a></H3> +<H3><a name="Library_std_vector">11.4.2 std::vector</a></H3> <p> @@ -1565,8 +1581,8 @@ std::vector<double> half(const std::vector<double>& v) { } void halve_in_place(std::vector<double>& v) { - std::transform(v.begin(), v.end(), v.begin(), - std::bind2nd(std::divides<double>(), 2.0)); + for (std::vector<double>::iterator it = v.begin(); it != v.end(); ++it) + *it /= 2.0; } </pre> </div> @@ -1667,7 +1683,7 @@ if you want to make their head explode. details and the public API exposed to the interpreter vary. </p> -<H3><a name="Library_stl_exceptions">9.4.3 STL exceptions</a></H3> +<H3><a name="Library_stl_exceptions">11.4.3 STL exceptions</a></H3> <p> @@ -1717,7 +1733,10 @@ The <tt>%exception</tt> directive can be used by placing the following code befo Any thrown STL exceptions will then be gracefully handled instead of causing a crash. </p> -<H3><a name="Library_std_shared_ptr">9.4.4 shared_ptr smart pointer</a></H3> +<H3><a name="Library_std_shared_ptr">11.4.4 shared_ptr smart pointer</a></H3> + + +<H4><a name="Library_shared_ptr_basics">11.4.4.1 shared_ptr basics</a></H4> <p> @@ -1813,8 +1832,11 @@ System.out.println(val1 + " " + val2); </pre> </div> +<H4><a name="Library_shared_ptr_inheritance">11.4.4.2 shared_ptr and inheritance</a></H4> + + <p> -This shared_ptr library works quite differently to SWIG's normal, but somewhat limited, +The shared_ptr library works quite differently to SWIG's normal, but somewhat limited, <a href="SWIGPlus.html#SWIGPlus_smart_pointers">smart pointer handling</a>. The shared_ptr library does not generate extra wrappers, just for smart pointer handling, in addition to the proxy class. The normal proxy class including inheritance relationships is generated as usual. @@ -1892,7 +1914,7 @@ Adding the missing <tt>%shared_ptr</tt> macros will fix this: <div class="code"> <pre> -%include "boost_shared_ptr.i" +%include <boost_shared_ptr.i> %shared_ptr(GrandParent); %shared_ptr(Parent); %shared_ptr(Child); @@ -1901,14 +1923,79 @@ Adding the missing <tt>%shared_ptr</tt> macros will fix this: </pre> </div> +<H4><a name="Library_shared_ptr_overloading">11.4.4.3 shared_ptr and method overloading</a></H4> + + +<p> +A C++ compiler can disambiguate a method overloaded by a shared_ptr and one using the raw underlying type. +For example, either one of these methods can be called in C++: +</p> + +<div class="code"> +<pre> +int age(std::shared_ptr<GrandParent> num); +int age(GrandParent& num); +</pre> +</div> + +<p> +When wrapped by SWIG, disambiguation is not possible using the overloaded names as there is just one equivalent type (<tt>GrandParent</tt>) in the target language. +SWIG will choose to wrap just the first method by default. +<a href="SWIGPlus.html#SWIGPlus_nn25">Ambiguity in overloading</a> discusses ways to control which method(s) gets wrapped using <tt>%ignore</tt> or <tt>%rename</tt>. +For the interested reader, SWIG detects that they are equivalent types via the <a href=Typemaps.html#Typemaps_typecheck_pointer>typecheck typemaps</a> in the shared_ptr library. +</p> + +<H4><a name="Library_shared_ptr_templates">11.4.4.4 shared_ptr and templates</a></H4> + + +<p> +The <tt>%shared_ptr</tt> macro should be used for all the required instantiations +of the template before each of the <tt>%template</tt> instantiations. +For example, consider <tt>number.h</tt> containing the following illustrative template: +</p> + +<div class="code"> +<pre> +#include <memory> + +template<int N> struct Number { + int num; + Number() : num(N) {} + static std::shared_ptr<Number<N>> make() { return std::make_shared<Number<N>>(); } +}; +</pre> +</div> + +<p> +The SWIG code below shows the required ordering: +</p> + +<div class="code"> +<pre> +%include <std_shared_ptr.i> + +%shared_ptr(Number<10>); +%shared_ptr(Number<42>); + +%{ + #include "number.h" +%} +%include "number.h" + +%template(Number10) Number<10>; +%template(Number42) Number<42>; +</pre> +</div> + +<H4><a name="Library_shared_ptr_directors">11.4.4.5 shared_ptr and directors</a></H4> + + <p> -<b>Note:</b> There is somewhat limited support for <tt>%shared_ptr</tt> and the director feature -and the degrees of success varies among the different target languages. -Please help to improve this support by providing patches with improvements. +The languages that support shared_ptr also have support for using shared_ptr with directors. </p> -<H3><a name="Library_std_auto_ptr">9.4.5 auto_ptr smart pointer</a></H3> +<H3><a name="Library_std_auto_ptr">11.4.5 auto_ptr smart pointer</a></H3> <p> @@ -1957,10 +2044,10 @@ int value = k.getValue(); </pre> </div> -<H2><a name="Library_nn16">9.5 Utility Libraries</a></H2> +<H2><a name="Library_nn16">11.5 Utility Libraries</a></H2> -<H3><a name="Library_nn17">9.5.1 exception.i</a></H3> +<H3><a name="Library_nn17">11.5.1 exception.i</a></H3> <p> diff --git a/Doc/Manual/Lisp.html b/Doc/Manual/Lisp.html index ba42f735c..6eb448a12 100644 --- a/Doc/Manual/Lisp.html +++ b/Doc/Manual/Lisp.html @@ -7,11 +7,10 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Lisp">27 SWIG and Common Lisp</a></H1> +<H1><a name="Lisp">29 SWIG and Common Lisp</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> -<li><a href="#Lisp_nn2">Allegro Common Lisp</a> <li><a href="#Lisp_nn3">Common Foreign Function Interface(CFFI)</a> <ul> <li><a href="#Lisp_nn4">Additional Commandline Options </a> @@ -19,12 +18,9 @@ <li><a href="#Lisp_nn6">Generating CFFI bindings for C++ code</a> <li><a href="#Lisp_nn7">Inserting user code into generated files</a> </ul> -<li><a href="#Lisp_nn8">CLISP</a> <ul> <li><a href="#Lisp_nn9">Additional Commandline Options </a> -<li><a href="#Lisp_nn10">Details on CLISP bindings</a> </ul> -<li><a href="#Lisp_nn11">UFFI </a> </ul> </div> <!-- INDEX --> @@ -38,26 +34,17 @@ finance, and also common in computer science education. There are more than 9 different implementations of common lisp which are available, all have different foreign function - interfaces. SWIG currently supports only the Allegro Common - Lisp, Common Foreign Function Interface(CFFI), CLisp and UFFI - foreign function interfaces. + interfaces. SWIG currently supports the + Common Foreign Function Interface(CFFI). </p> -<H2><a name="Lisp_nn2">27.1 Allegro Common Lisp</a></H2> - -<p> - Allegro Common Lisp support in SWIG has been updated to include - support for both C and C++. You can read about the interface - <a href="Allegrocl.html#Allegrocl">here</a> -</p> - -<H2><a name="Lisp_nn3">27.2 Common Foreign Function Interface(CFFI)</a></H2> +<H2><a name="Lisp_nn3">29.2 Common Foreign Function Interface(CFFI)</a></H2> <p> CFFI, the Common Foreign Function Interface, is a portable foreign - function interface for ANSI Common Lisp systems, similar in - spirit to UFFI. Unlike UFFI, CFFI requires only a small set of + function interface for ANSI Common Lisp systems. + CFFI requires only a small set of low-level functionality from the Lisp implementation, such as calling a foreign function by name, allocating foreign memory, and dereferencing pointers. @@ -78,17 +65,8 @@ 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">27.2.1 Additional Commandline Options </a></H3> - - -<p> -The following table list the additional commandline options available for the CLISP module. They can also be seen by using: -</p> +<H3><a name="Lisp_nn4">29.2.1 Additional Commandline Options </a></H3> -<div class="code"><pre> -swig -cffi -help -</pre></div> -<br/> <table summary="CFFI specific options"> <tr> @@ -119,12 +97,15 @@ swig -cffi -help </table> -<H3><a name="Lisp_nn5">27.2.2 Generating CFFI bindings</a></H3> +<H3><a name="Lisp_nn5">29.2.2 Generating CFFI bindings</a></H3> + +<p> As we mentioned earlier the ideal way to use SWIG is to use interface files. To illustrate the use of it, let's assume that we have a file named <i>test.h</i> with the following C code: +</p> <div class="code"><pre> #define y 5 @@ -155,7 +136,10 @@ void lispsort_double (int n, double * array); enum color { RED, BLUE, GREEN}; </pre></div> +<p> Corresponding to this we will write a simple interface file: +</p> + <div class="code"><pre> %module test @@ -163,7 +147,9 @@ Corresponding to this we will write a simple interface file: </pre></div> +<p> The generated SWIG Code will be: +</p> <div class="targetlang"><pre> ;;;SWIG wrapper code starts here @@ -395,7 +381,7 @@ The feature <i>intern_function</i> ensures that all C names are </pre></div> -<H3><a name="Lisp_nn6">27.2.3 Generating CFFI bindings for C++ code</a></H3> +<H3><a name="Lisp_nn6">29.2.3 Generating CFFI bindings for C++ code</a></H3> <p>This feature to SWIG (for CFFI) is very new and still far from @@ -430,8 +416,10 @@ Also, while parsing the C++ file and generating C wrapper code SWIG %include "target/header.h" </pre></div> +<p> Various features which were available for C headers can also be used here. The target header which we are going to use here is: +</p> <div class="code"><pre> namespace OpenDemo { class Test @@ -478,8 +466,10 @@ namespace OpenDemo { %include "test.cpp" </pre></div> +<p> SWIG generates 3 files, the first one is a C wrap which we don't show, the second is the plain CFFI wrapper which is as shown below: +</p> <div class="targetlang"><pre> (cffi:defcfun ("_wrap_Test_x_set" Test_x_set) :void (self :pointer) @@ -528,11 +518,13 @@ SWIG generates 3 files, the first one is a C wrap which we don't show, (cffi:defcfun ("_wrap_RandomUnitVectorOnXZPlane" RandomUnitVectorOnXZPlane) :pointer) </pre></div> +<p> The output is pretty good but it fails in disambiguating overloaded functions such as the constructor, in this case. One way of resolving this problem is to make the interface use the rename directiv, but hopefully there are better solutions. In addition SWIG also generates, a CLOS file +</p> <div class="targetlang"><pre> @@ -568,7 +560,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">27.2.4 Inserting user code into generated files</a></H3> +<H3><a name="Lisp_nn7">29.2.4 Inserting user code into generated files</a></H3> <p> @@ -608,195 +600,5 @@ Note that the block <tt>%{ ... %}</tt> is effectively a shortcut for </p> -<H2><a name="Lisp_nn8">27.3 CLISP</a></H2> - - -<p> -<a href="http://clisp.cons.org">CLISP</a> is a feature-loaded - implementation of common lisp which is portable across most of the - operating system environments and hardware. CLISP includes an - interpreter, a compiler, a debugger, CLOS, MOP, a foreign - language interface, i18n, regular expressions, a socket - interface, and more. An X11 interface is available through CLX, - Garnet and CLUE/CLIO. Command line editing is provided by - readline. CLISP runs Maxima, ACL2 and many other Common Lisp - packages. -</p> -<p> - To run the clisp module of SWIG requires very little effort, you - just need to execute: -</p> -<div class="code"><pre> -swig -clisp -module <i>module-name</i> <i>file-name</i> - -</pre></div> - -<p> - Because of the high level nature of the CLISP FFI, the bindings - generated by SWIG may not be absolutely correct, and you may need - to modify them. The good thing is that you don't need to complex - 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">27.3.1 Additional Commandline Options </a></H3> - - -<p> -The following table list the additional commandline options available for the CLISP module. They can also be seen by using: -</p> - -<div class="code"><pre> -swig -clisp -help -</pre></div> -<br/> -<table summary="CLISP specific options"> -<tr> -<th>CLISP specific options</th> -</tr> - -<tr> -<td>-extern-all</td> -<td>If this option is given then clisp definitions for all the functions<br/> -and global variables will be created otherwise only definitions for<br/> -externed functions and variables are created. -</td> -</tr> - -<tr> -<td>-generate-typedef</td> -<td>If this option is given then def-c-type will be used to generate<br/> -shortcuts according to the typedefs in the input. -</td> -</tr> - -</table> - -<H3><a name="Lisp_nn10">27.3.2 Details on CLISP bindings</a></H3> - - -<p> -As mentioned earlier the CLISP bindings generated by SWIG may need -some modifications. The clisp module creates a lisp file with -the same name as the module name. This -lisp file contains a 'defpackage' declaration, with the -package name same as the module name. This package uses the -'common-lisp' and 'ffi' packages. Also, package exports all -the functions, structures and variables for which an ffi -binding was generated.<br/> -After generating the defpackage statement, the clisp module also -sets the default language. - -<div class="targetlang"><pre> -(defpackage :test - (:use :common-lisp :ffi) - (:export - :make-bar - :bar-x - :bar-y - :bar-a - :bar-b - :bar-z - :bar-n - :pointer_func - :func123 - :make-cfunr - :lispsort_double - :test123)) - -(in-package :test) - -(default-foreign-language :stdc) -</pre></div> -<p> -The ffi wrappers for functions and variables are generated as shown - below. When functions have arguments of type "double * array", - SWIG doesn't knows whether it is an 'out' argument or it is - an array which will be passed, so SWIG plays it safe by - declaring it as an '(array (ffi:c-ptr DOUBLE-FLOAT))'. For - arguments of type "int **z[100]" where SWIG has more - information, i.e., it knows that 'z' is an array of pointers to - pointers of integers, SWIG defines it to be '(z (ffi:c-ptr - (ffi:c-array (ffi:c-ptr (ffi:c-ptr ffi:int)) 100)))' -</p> -<div class="code"><pre> -extern "C" { -int pointer_func(void (*ClosureFun)( void* _fun, void* _data, void* _evt ), int y); - -int func123(div_t * x, int **z[100], int y[][1000][10]); - -void lispsort_double (int n, double * array); - -void test123(float x , double y); - -} -</pre></div> -<div class="targetlang"><pre> -(ffi:def-call-out pointer_func - (:name "pointer_func") - (:arguments (ClosureFun (ffi:c-function (:arguments (arg0 (ffi:c-pointer NIL)) - (arg1 (ffi:c-pointer NIL)) - (arg2 (ffi:c-pointer NIL))) - (:return-type NIL))) - (y ffi:int)) - (:return-type ffi:int) - (:library +library-name+)) - -(ffi:def-call-out func123 - (:name "func123") - (:arguments (x (ffi:c-pointer div_t)) - (z (ffi:c-ptr (ffi:c-array (ffi:c-ptr (ffi:c-ptr ffi:int)) 100))) - (y (ffi:c-ptr (ffi:c-ptr (ffi:c-array ffi:int (1000 10)))))) - (:return-type ffi:int) - (:library +library-name+)) - - -(ffi:def-call-out lispsort_double - (:name "lispsort_double") - (:arguments (n ffi:int) - (array (ffi:c-ptr DOUBLE-FLOAT))) - (:return-type NIL) - (:library +library-name+)) - -(ffi:def-call-out test123 - (:name "test") - (:arguments (x SINGLE-FLOAT) - (y DOUBLE-FLOAT)) - (:return-type NIL) - (:library +library-name+)) - -</pre></div> - -<p> -The module also handles strutcures and #define constants as shown - below. SWIG automatically adds the constructors and accessors - created for the struct to the list of symbols exported by the - package. -</p> -<div class="code"><pre> -struct bar { - short x, y; - char a, b; - int *z[1000]; - struct bar * n; -}; - -#define max 1000 -</pre></div> -<div class="targetlang"><pre> -(ffi:def-c-struct bar - (x :type ffi:short) - (y :type ffi:short) - (a :type character) - (b :type character) - (z :type (ffi:c-array (ffi:c-ptr ffi:int) 1000)) - (n :type (ffi:c-pointer bar))) - -(defconstant max 1000) - -</pre></div> - -<H2><a name="Lisp_nn11">27.4 UFFI </a></H2> - - </body> </html> diff --git a/Doc/Manual/Lua.html b/Doc/Manual/Lua.html index c94fe31dc..6633eaa38 100644 --- a/Doc/Manual/Lua.html +++ b/Doc/Manual/Lua.html @@ -77,7 +77,7 @@ <p> -Lua is an extension programming language designed to support general procedural programming with data description facilities. It also offers good support for object-oriented programming, functional programming, and data-driven programming. Lua is intended to be used as a powerful, light-weight configuration language for any program that needs one. Lua is implemented as a library, written in clean C (that is, in the common subset of ANSI C and C++). It's also a <em>really</em> tiny language, less than 6000 lines of code, which compiles to <100 kilobytes of binary code. It can be found at <a href="http://www.lua.org">http://www.lua.org</a> +Lua is an extension programming language designed to support general procedural programming with data description facilities. It also offers good support for object-oriented programming, functional programming, and data-driven programming. Lua is intended to be used as a powerful, light-weight configuration language for any program that needs one. Lua is implemented as a library, written in clean C (that is, in the common subset of ISO C and C++). It's also a <em>really</em> tiny language, less than 6000 lines of code, which compiles to <100 kilobytes of binary code. It can be found at <a href="http://www.lua.org">http://www.lua.org</a> </p> <p> 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> @@ -984,7 +984,7 @@ There are ways to make this operator appear as part of the class using the <tt>% Also, be aware that certain operators don't map cleanly to Lua, and some Lua operators don't map cleanly to C++ operators. For instance, overloaded assignment operators don't map to Lua semantics and will be ignored, and C++ doesn't support Lua's concatenation operator (<tt>..</tt>). </p> <p> -In order to keep maximum compatibility within the different languages in SWIG, the Lua bindings uses the same set of operator names as python. Although internally it renames the functions to something else (on order to work with Lua). +In order to keep maximum compatibility within the different languages in SWIG, the Lua bindings uses the same set of operator names as Python. Although internally it renames the functions to something else (on order to work with Lua). <p> The current list of operators which can be overloaded (and the alternative function names) are:<ul> <li><tt>__add__</tt> operator+ @@ -1008,11 +1008,10 @@ The following operators cannot be overloaded (mainly because they are not suppor <p> SWIG also accepts the <tt>__str__()</tt> member function which converts an object to a string. This function should return a const char*, preferably to static memory. This will be used for the <tt>print()</tt> and <tt>tostring()</tt> functions in Lua. Assuming the complex class has a function </p> -<div class="code"><pre>const char* __str__() -{ - static char buffer[255]; - sprintf(buffer, "Complex(%g, %g)", this->re(), this->im()); - return buffer; +<div class="code"><pre>const char* __str__() { + static char buffer[255]; + sprintf(buffer, "Complex(%g, %g)", this->re(), this->im()); + return buffer; } </pre></div> <p> @@ -1031,11 +1030,10 @@ Complex(10, 12) <p> It is also possible to overload the operator<tt>[]</tt>, but currently this cannot be automatically performed. To overload the operator<tt>[]</tt> you need to provide two functions, <tt>__getitem__()</tt> and <tt>__setitem__()</tt> </p> -<div class="code"><pre>class Complex -{ - //.... - double __getitem__(int i)const; // i is the index, returns the data - void __setitem__(int i, double d); // i is the index, d is the data +<div class="code"><pre>class Complex { + //.... + double __getitem__(int i)const; // i is the index, returns the data + void __setitem__(int i, double d); // i is the index, d is the data }; </pre></div> <p> diff --git a/Doc/Manual/Makefile b/Doc/Manual/Makefile index ee9a0af34..9505adb91 100644 --- a/Doc/Manual/Makefile +++ b/Doc/Manual/Makefile @@ -89,3 +89,9 @@ linkchecker2: cp *.png linkchecker-tmp (cd linkchecker-tmp && linkchecker --config=../linkchecker.config -F text --no-warnings SWIGDocumentation.html) +# Simple check for relative links (there shouldn't be any), they don't translate properly creating the .pdf doc +# with wkhtmltopdf. For example, href="SWIG.html" needs to be href="SWIG.html#SWIG" +linkchecker3: + @echo "The following list should just contain SWIGDocumentation.html and SWIGDocumentation.pdf," + @echo "as all links should have an anchor (with a #) or be a full url beginning http." + grep 'href="' *.html | sed -e 's/.*href="\(.*\)">.*$$/\1/' | grep -v "#" | grep -v "^http" | grep -v "^style.css" diff --git a/Doc/Manual/Modula3.html b/Doc/Manual/Modula3.html index 75f3f80ff..fc4ffa03c 100644 --- a/Doc/Manual/Modula3.html +++ b/Doc/Manual/Modula3.html @@ -6,7 +6,7 @@ <meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head> <body bgcolor="#FFFFFF"> -<H1><a name="Modula3">29 SWIG and Modula-3</a></H1> +<H1><a name="Modula3">31 SWIG and Modula-3</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -55,7 +55,7 @@ especially <a href="Typemaps.html#Typemaps">typemaps</a>. </p> -<H2><a name="Modula3_modula3_overview">29.1 Overview</a></H2> +<H2><a name="Modula3_modula3_overview">31.1 Overview</a></H2> <p> @@ -85,7 +85,7 @@ FFTW </li> </ol> -<H3><a name="Modula3_motivation">29.1.1 Motivation</a></H3> +<H3><a name="Modula3_motivation">31.1.1 Motivation</a></H3> <p> @@ -132,10 +132,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">29.2 Conception</a></H2> +<H2><a name="Modula3_conception">31.2 Conception</a></H2> -<H3><a name="Modula3_cinterface">29.2.1 Interfaces to C libraries</a></H3> +<H3><a name="Modula3_cinterface">31.2.1 Interfaces to C libraries</a></H3> <p> @@ -284,7 +284,7 @@ and the principal type must be renamed (<tt>%typemap</tt>). </p> -<H3><a name="Modula3_cppinterface">29.2.2 Interfaces to C++ libraries</a></H3> +<H3><a name="Modula3_cppinterface">31.2.2 Interfaces to C++ libraries</a></H3> <p> @@ -385,10 +385,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">29.3 Preliminaries</a></H2> +<H2><a name="Modula3_preliminaries">31.3 Preliminaries</a></H2> -<H3><a name="Modula3_compilers">29.3.1 Compilers</a></H3> +<H3><a name="Modula3_compilers">31.3.1 Compilers</a></H3> <p> @@ -401,7 +401,7 @@ For testing examples I use Critical Mass cm3. </p> -<H3><a name="Modula3_commandline">29.3.2 Additional Commandline Options</a></H3> +<H3><a name="Modula3_commandline">31.3.2 Additional Commandline Options</a></H3> <p> @@ -478,10 +478,10 @@ Instead generate templates for some basic typemaps. </tr> </table> -<H2><a name="Modula3_typemaps">29.4 Modula-3 typemaps</a></H2> +<H2><a name="Modula3_typemaps">31.4 Modula-3 typemaps</a></H2> -<H3><a name="Modula3_inoutparam">29.4.1 Inputs and outputs</a></H3> +<H3><a name="Modula3_inoutparam">31.4.1 Inputs and outputs</a></H3> <p> @@ -695,7 +695,7 @@ consist of the following parts: </table> -<H3><a name="Modula3_ordinals">29.4.2 Subranges, Enumerations, Sets</a></H3> +<H3><a name="Modula3_ordinals">31.4.2 Subranges, Enumerations, Sets</a></H3> <p> @@ -747,7 +747,7 @@ that I'd like to automate. </p> -<H3><a name="Modula3_class">29.4.3 Objects</a></H3> +<H3><a name="Modula3_class">31.4.3 Objects</a></H3> <p> @@ -760,7 +760,7 @@ is not really useful, yet. </p> -<H3><a name="Modula3_imports">29.4.4 Imports</a></H3> +<H3><a name="Modula3_imports">31.4.4 Imports</a></H3> <p> @@ -793,7 +793,7 @@ IMPORT M3toC; </pre></div> -<H3><a name="Modula3_exceptions">29.4.5 Exceptions</a></H3> +<H3><a name="Modula3_exceptions">31.4.5 Exceptions</a></H3> <p> @@ -817,7 +817,7 @@ you should declare <tt>%typemap("m3wrapinconv:throws") blah * %{OSError.E%}</tt>. </p> -<H3><a name="Modula3_typemap_example">29.4.6 Example</a></H3> +<H3><a name="Modula3_typemap_example">31.4.6 Example</a></H3> <p> @@ -864,10 +864,10 @@ where almost everything is generated by a typemap: </pre></div> -<H2><a name="Modula3_hints">29.5 More hints to the generator</a></H2> +<H2><a name="Modula3_hints">31.5 More hints to the generator</a></H2> -<H3><a name="Modula3_features">29.5.1 Features</a></H3> +<H3><a name="Modula3_features">31.5.1 Features</a></H3> <table border summary="Modula-3 features"> @@ -904,7 +904,7 @@ where almost everything is generated by a typemap: </tr> </table> -<H3><a name="Modula3_pragmas">29.5.2 Pragmas</a></H3> +<H3><a name="Modula3_pragmas">31.5.2 Pragmas</a></H3> <table border summary="Modula-3 pragmas"> @@ -927,7 +927,7 @@ where almost everything is generated by a typemap: </tr> </table> -<H2><a name="Modula3_remarks">29.6 Remarks</a></H2> +<H2><a name="Modula3_remarks">31.6 Remarks</a></H2> <ul> diff --git a/Doc/Manual/Modules.html b/Doc/Manual/Modules.html index 2a0ff7985..7efd74e2b 100644 --- a/Doc/Manual/Modules.html +++ b/Doc/Manual/Modules.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Modules">16 Working with Modules</a></H1> +<H1><a name="Modules">19 Working with Modules</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -24,7 +24,7 @@ -<H2><a name="Modules_introduction">16.1 Modules Introduction</a></H2> +<H2><a name="Modules_introduction">19.1 Modules Introduction</a></H2> <p> @@ -78,7 +78,7 @@ where you want to create a collection of modules. Each module in the collection is created via separate invocations of SWIG. </p> -<H2><a name="Modules_nn1">16.2 Basics</a></H2> +<H2><a name="Modules_nn1">19.2 Basics</a></H2> <p> @@ -177,7 +177,7 @@ in parallel from multiple threads as SWIG provides no locking - for more on that issue, read on. </p> -<H2><a name="Modules_nn2">16.3 The SWIG runtime code</a></H2> +<H2><a name="Modules_nn2">19.3 The SWIG runtime code</a></H2> <p> @@ -243,7 +243,7 @@ can peacefully coexist. So the type structures are separated by the is empty. Only modules compiled with the same pair will share type information. </p> -<H2><a name="Modules_external_run_time">16.4 External access to the runtime</a></H2> +<H2><a name="Modules_external_run_time">19.4 External access to the runtime</a></H2> <p>As described in <a href="Typemaps.html#Typemaps_runtime_type_checker">The run-time type checker</a>, @@ -282,7 +282,7 @@ SWIG_TYPE_TABLE to be the same as the module whose types you are trying to access. </p> -<H2><a name="Modules_nn4">16.5 A word of caution about static libraries</a></H2> +<H2><a name="Modules_nn4">19.5 A word of caution about static libraries</a></H2> <p> @@ -293,7 +293,7 @@ into it. This is very often <b>NOT</b> what you want and it can lead to unexpect behavior. When working with dynamically loadable modules, you should try to work exclusively with shared libraries. </p> -<H2><a name="Modules_nn5">16.6 References</a></H2> +<H2><a name="Modules_nn5">19.6 References</a></H2> <p> @@ -301,7 +301,7 @@ Due to the complexity of working with shared libraries and multiple modules, it an outside reference. John Levine's "Linkers and Loaders" is highly recommended. </p> -<H2><a name="Modules_nn6">16.7 Reducing the wrapper file size</a></H2> +<H2><a name="Modules_nn6">19.7 Reducing the wrapper file size</a></H2> <p> diff --git a/Doc/Manual/Mzscheme.html b/Doc/Manual/Mzscheme.html index 385b241aa..aae181ee9 100644 --- a/Doc/Manual/Mzscheme.html +++ b/Doc/Manual/Mzscheme.html @@ -8,7 +8,7 @@ <body bgcolor="#ffffff"> -<H1><a name="Mzscheme">30 SWIG and MzScheme/Racket</a></H1> +<H1><a name="Mzscheme">37 SWIG and MzScheme/Racket</a></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">30.1 Creating native structures</a></H2> +<H2><a name="MzScheme_nn2">37.1 Creating native structures</a></H2> <p> @@ -65,7 +65,7 @@ Then in scheme, you can use regular struct access procedures like </pre> </div> -<H2><a name="MzScheme_simple">30.2 Simple example</a></H2> +<H2><a name="MzScheme_simple">37.2 Simple example</a></H2> <p> @@ -166,11 +166,11 @@ 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">30.3 External documentation</a></H2> +<H2><a name="MzScheme_external_docs">37.3 External documentation</a></H2> <p> -See the <a href="http://docs.racket-lang.org/inside/index.html">C API</a> for more description of using the mechanism for adding extensions. The main documentation is <a href="http://docs.racket-lang.org/">here</a>. +See the <a href="https://docs.racket-lang.org/inside/index.html">C API</a> for more description of using the mechanism for adding extensions. The main documentation is <a href="https://docs.racket-lang.org/">here</a>. </p> <p> diff --git a/Doc/Manual/Ocaml.html b/Doc/Manual/Ocaml.html index 96c93faeb..92b5260fe 100644 --- a/Doc/Manual/Ocaml.html +++ b/Doc/Manual/Ocaml.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Ocaml">31 SWIG and Ocaml</a></H1> +<H1><a name="Ocaml">38 SWIG and OCaml</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -47,12 +47,16 @@ <li><a href="#Ocaml_nn25">Director Usage Example</a> <li><a href="#Ocaml_nn26">Creating director objects</a> <li><a href="#Ocaml_nn27">Typemaps for directors, directorin, directorout, directorargout</a> -<li><a href="#Ocaml_nn28">typemap</a> +<li><a href="#Ocaml_nn28">directorin typemap</a> <li><a href="#Ocaml_nn29">directorout typemap</a> <li><a href="#Ocaml_nn30">directorargout typemap</a> </ul> <li><a href="#Ocaml_nn31">Exceptions</a> </ul> +<li><a href="#Ocaml_nn32">Documentation Features</a> +<ul> +<li><a href="#Ocaml_nn33">Module docstring</a> +</ul> </ul> </div> <!-- INDEX --> @@ -84,11 +88,11 @@ If you're not familiar with the Objective Caml language, you can visit <a href="http://ocaml.org/">The Ocaml Website</a>. </p> -<H2><a name="Ocaml_nn2">31.1 Preliminaries</a></H2> +<H2><a name="Ocaml_nn2">38.1 Preliminaries</a></H2> <p> -SWIG 3.0 works with Ocaml 3.08.3 and above. Given the choice, +SWIG is compatible with OCaml 3.12.0 and above. Given the choice, you should use the latest stable release. The SWIG Ocaml module has been tested on Linux (x86, PPC, Sparc) and Cygwin on Windows. The best way to determine whether your system will work is to compile the @@ -102,7 +106,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">31.1.1 Running SWIG</a></H3> +<H3><a name="Ocaml_nn3">38.1.1 Running SWIG</a></H3> <p> @@ -125,7 +129,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">31.1.2 Compiling the code</a></H3> +<H3><a name="Ocaml_nn4">38.1.2 Compiling the code</a></H3> <p> @@ -142,7 +146,7 @@ Use <tt>ocamlc</tt> or <tt>ocamlopt</tt> to compile your SWIG interface like: <div class="code"> <pre> -% swig -ocaml -co swig.mli ; swig -ocaml co swig.ml +% swig -ocaml -co swig.mli ; swig -ocaml -co swig.ml % ocamlc -c swig.mli ; ocamlc -c swig.ml % ocamlc -c -ccopt "-I/usr/include/foo" example_wrap.c % ocamlc -c example.mli @@ -162,7 +166,7 @@ in C++ mode, you must:</p> </pre> </div> -<H3><a name="Ocaml_nn5">31.1.3 The camlp4 module</a></H3> +<H3><a name="Ocaml_nn5">38.1.3 The camlp4 module</a></H3> <p> @@ -238,7 +242,7 @@ let b = C_string (getenv "PATH") </td></tr> </table> -<H3><a name="Ocaml_nn6">31.1.4 Using your module</a></H3> +<H3><a name="Ocaml_nn6">38.1.4 Using your module</a></H3> <p> @@ -252,7 +256,7 @@ option to build your functions into the primitive list. This option is not needed when you build native code. </p> -<H3><a name="Ocaml_nn7">31.1.5 Compilation problems and compiling with C++</a></H3> +<H3><a name="Ocaml_nn7">38.1.5 Compilation problems and compiling with C++</a></H3> <p> @@ -263,7 +267,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">31.2 The low-level Ocaml/C interface</a></H2> +<H2><a name="Ocaml_nn8">38.2 The low-level Ocaml/C interface</a></H2> <p> @@ -336,7 +340,7 @@ appended. Upon return to caml space, the fnhelper function beautifies the result. A list containing a single item degrades to only that item (i.e. [ C_int 3 ] -> C_int 3), and a list containing more than one item is wrapped in C_list (i.e. [ C_char -'a' ; C_char 'b' -> C_list [ C_char 'a' ; C_char b +'a' ; C_char 'b' ] -> C_list [ C_char 'a' ; C_char 'b' ]). This is in order to make return values easier to handle when functions have only one return value, such as constructors, and operators. In addition, string, pointer, and object @@ -363,7 +367,7 @@ value items pass through directly, but you must make your own type signature for a function that uses value in this way. </p> -<H3><a name="Ocaml_nn9">31.2.1 The generated module</a></H3> +<H3><a name="Ocaml_nn9">38.2.1 The generated module</a></H3> <p> @@ -397,7 +401,7 @@ it describes the output SWIG will generate for class definitions. </td></tr> </table> -<H3><a name="Ocaml_nn10">31.2.2 Enums</a></H3> +<H3><a name="Ocaml_nn10">38.2.2 Enums</a></H3> <p> @@ -460,7 +464,7 @@ val x : Enum_test.c_obj = C_enum `a </pre> </div> -<H4><a name="Ocaml_nn11">31.2.2.1 Enum typing in Ocaml</a></H4> +<H4><a name="Ocaml_nn11">38.2.2.1 Enum typing in Ocaml</a></H4> <p> @@ -473,10 +477,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">31.2.3 Arrays</a></H3> +<H3><a name="Ocaml_nn12">38.2.3 Arrays</a></H3> -<H4><a name="Ocaml_nn13">31.2.3.1 Simple types of bounded arrays</a></H4> +<H4><a name="Ocaml_nn13">38.2.3.1 Simple types of bounded arrays</a></H4> <p> @@ -497,7 +501,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">31.2.3.2 Complex and unbounded arrays</a></H4> +<H4><a name="Ocaml_nn14">38.2.3.2 Complex and unbounded arrays</a></H4> <p> @@ -510,7 +514,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">31.2.3.3 Using an object</a></H4> +<H4><a name="Ocaml_nn15">38.2.3.3 Using an object</a></H4> <p> @@ -524,7 +528,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">31.2.3.4 Example typemap for a function taking float * and int</a></H4> +<H4><a name="Ocaml_nn16">38.2.3.4 Example typemap for a function taking float * and int</a></H4> <p> @@ -575,7 +579,7 @@ void printfloats( float *tab, int len ); </pre></td></tr></table> -<H3><a name="Ocaml_nn17">31.2.4 C++ Classes</a></H3> +<H3><a name="Ocaml_nn17">38.2.4 C++ Classes</a></H3> <p> @@ -618,7 +622,7 @@ the underlying pointer, so using create_[x]_from_ptr alters the returned value for the same object. </p> -<H4><a name="Ocaml_nn18">31.2.4.1 STL vector and string Example</a></H4> +<H4><a name="Ocaml_nn18">38.2.4.1 STL vector and string Example</a></H4> <p> @@ -660,7 +664,7 @@ module. </p> <div class="code"><pre> -bash-2.05a$ ./example_top +bash-2.05a$ ./runme_top Objective Caml version 3.06 Camlp4 Parsing version 3.06 @@ -698,7 +702,7 @@ baz # </pre></div> -<H4><a name="Ocaml_nn19">31.2.4.2 C++ Class Example</a></H4> +<H4><a name="Ocaml_nn19">38.2.4.2 C++ Class Example</a></H4> <p> @@ -728,7 +732,7 @@ public: }; </pre></td></tr></table> -<H4><a name="Ocaml_nn20">31.2.4.3 Compiling the example</a></H4> +<H4><a name="Ocaml_nn20">38.2.4.3 Compiling the example</a></H4> <div class="code"><pre> @@ -746,7 +750,7 @@ bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \ -L$QTPATH/lib -cclib -lqt </pre></div> -<H4><a name="Ocaml_nn21">31.2.4.4 Sample Session</a></H4> +<H4><a name="Ocaml_nn21">38.2.4.4 Sample Session</a></H4> <div class="code"><pre> @@ -773,10 +777,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">31.2.5 Director Classes</a></H3> +<H3><a name="Ocaml_nn22">38.2.5 Director Classes</a></H3> -<H4><a name="Ocaml_nn23">31.2.5.1 Director Introduction</a></H4> +<H4><a name="Ocaml_nn23">38.2.5.1 Director Introduction</a></H4> <p> @@ -803,7 +807,7 @@ class foo { }; </pre></div> -<H4><a name="Ocaml_nn24">31.2.5.2 Overriding Methods in Ocaml</a></H4> +<H4><a name="Ocaml_nn24">38.2.5.2 Overriding Methods in Ocaml</a></H4> <p> @@ -831,11 +835,11 @@ 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">31.2.5.3 Director Usage Example</a></H4> +<H4><a name="Ocaml_nn25">38.2.5.3 Director Usage Example</a></H4> <table border="1" bgcolor="#dddddd" summary="Director usage example"> -<tr><th><center>example_prog.ml</center> +<tr><th><center>runme.ml</center> </th></tr> <tr><td><pre> open Swig @@ -854,13 +858,15 @@ let triangle_class pts ob meth args = | _ -> raise (Failure "cover needs two double arguments.")) | _ -> (invoke ob) meth args ;; +... + let triangle = new_derived_object new_shape - (triangle_class ((0.0, 0.0), (0.5, 1.0), (1.0, 0.0))) + (triangle_class ((0.0, 0.0), (0.5, 1.0), (1.0, 0.6))) '() ;; -let _ = _draw_shape_coverage '(triangle, C_int 60, C_int 20) ;; +let _ = _draw_shape_coverage '(triangle, 60, 20) ;; </pre></td></tr> </table> @@ -890,7 +896,7 @@ in a more effortless style in ocaml, while leaving the "engine" part of the program in C++. </p> -<H4><a name="Ocaml_nn26">31.2.5.4 Creating director objects</a></H4> +<H4><a name="Ocaml_nn26">38.2.5.4 Creating director objects</a></H4> <p> @@ -931,7 +937,7 @@ object from causing a core dump, as long as the object is destroyed properly. </p> -<H4><a name="Ocaml_nn27">31.2.5.5 Typemaps for directors, directorin, directorout, directorargout</a></H4> +<H4><a name="Ocaml_nn27">38.2.5.5 Typemaps for directors, directorin, directorout, directorargout</a></H4> <p> @@ -942,7 +948,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">31.2.5.6 typemap</a></H4> +<H4><a name="Ocaml_nn28">38.2.5.6 directorin typemap</a></H4> <p> @@ -953,7 +959,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">31.2.5.7 directorout typemap</a></H4> +<H4><a name="Ocaml_nn29">38.2.5.7 directorout typemap</a></H4> <p> @@ -964,7 +970,7 @@ for the same type, except when there are special requirements for object ownership, etc. </p> -<H4><a name="Ocaml_nn30">31.2.5.8 directorargout typemap</a></H4> +<H4><a name="Ocaml_nn30">38.2.5.8 directorargout typemap</a></H4> <p> @@ -981,14 +987,134 @@ 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">31.2.6 Exceptions</a></H3> +<H3><a name="Ocaml_nn31">38.2.6 Exceptions</a></H3> + + +<p> +If an error occurs in a C or C++ function, you may want to convert that error into an OCaml +exception. To do this, you can use the <tt>%exception</tt> directive. The <tt>%exception</tt> +directive simply lets you rewrite part of the generated wrapper code to include an error check. +It is detailed in full in the <a href="Customization.html#Customization_exception">Exception handling with %exception</a> section. +</p> + +<p> +In C, a function often indicates an error by returning a status code (e.g. a negative number +or a NULL pointer). Here is a simple example of how you might handle that: +</p> + +<div class="code"> +<pre> +%exception malloc { + $action + if (result == NULL) { + caml_failwith("Not enough memory"); + } +} +void *malloc(size_t nbytes); +</pre> +</div> + +<p> +In OCaml: +</p> + +<div class="code"> +<pre> +# let a = _malloc (C_int 20000000000);; +Exception: Failure "Not enough memory". +# +</pre> +</div> + +<p> +If a library provides some kind of general error handling framework, you can also use +that. For example: +</p> + +<div class="code"> +<pre> +%exception { + $action + if (err_occurred()) { + caml_failwith(err_message()); + } +} +</pre> +</div> + +<p> +If no declaration name is given to <tt>%exception</tt>, it is applied to all wrapper functions. +<tt>$action</tt> is a SWIG special variable and is replaced by the C/C++ function call being wrapped. +</p> + +<p> +C++ exceptions are also easy to handle. We can catch a C++ exception and rethrow it as +an OCaml exception like this: +</p> + +<div class="code"> +<pre> +%exception getitem { + try { + $action + } catch (std::out_of_range &e) { + caml_failwith(e.what()); + } +} + +class FooClass { + public: + int getitem(int index); // Exception handling added + ... +}; +</pre> +</div> + +<p> +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="Ocaml_nn32">38.3 Documentation Features</a></H2> <p> -Catching exceptions is now supported using SWIG's %exception feature. A simple -but not too useful example is provided by the throw_exception testcase in -Examples/test-suite. You can provide your own exceptions, too. +The features described in this section can be used to generate documentation +comments (colloquially referred to as "docstrings") that can be read by +<a href="https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html">OCamldoc</a>. </p> +<H3><a name="Ocaml_nn33">38.3.1 Module docstring</a></H3> + + +<p> +The first documentation comment of an <tt>mli</tt> file is the comment +associated with the entire module. SWIG supports this by setting an +option of the <tt>%module</tt> directive. For example: +</p> + +<div class="code"> +<pre> +%module(docstring="This is the example module's docstring") example +</pre> +</div> + +<p> +When you have more than just a line or so, you can retain the +readability of the <tt>%module</tt> directive by using a macro. For +example: +</p> + +<div class="code"> +<pre> +%define DOCSTRING +"The `XmlResource` class allows program resources defining menus, +controls on a panel, etc. to be loaded from an XML file." +%enddef + +%module(docstring=DOCSTRING) xrc +</pre> +</div> + </body> </html> diff --git a/Doc/Manual/Octave.html b/Doc/Manual/Octave.html index 616b28cf8..bd6b08ff9 100644 --- a/Doc/Manual/Octave.html +++ b/Doc/Manual/Octave.html @@ -9,7 +9,7 @@ <body bgcolor="#ffffff"> -<H1><a name="Octave">32 SWIG and Octave</a></H1> +<H1><a name="Octave">29 SWIG and Octave</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -60,7 +60,7 @@ This chapter is intended to give an introduction to using the module. You should 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">32.1 Preliminaries</a></H2> +<H2><a name="Octave_nn2">29.1 Preliminaries</a></H2> <p> @@ -76,7 +76,7 @@ This cannot be guaranteed however, as in recent times new Octave releases have r The SWIG runtime exports the function <tt>swig_octave_prereq()</tt> for checking the version of Octave. </p> -<H2><a name="Octave_nn3">32.2 Running SWIG</a></H2> +<H2><a name="Octave_nn3">29.2 Running SWIG</a></H2> <p> @@ -108,7 +108,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">32.2.1 Command-line options</a></H3> +<H3><a name="Octave_nn4">29.2.1 Command-line options</a></H3> <p> @@ -131,7 +131,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">32.2.2 Compiling a dynamic module</a></H3> +<H3><a name="Octave_nn5">29.2.2 Compiling a dynamic module</a></H3> <p> @@ -158,7 +158,7 @@ $ mkoctfile example_wrap.cpp example.c <div class="targetlang"><pre>octave:1> swigexample</pre></div> -<H3><a name="Octave_nn6">32.2.3 Using your module</a></H3> +<H3><a name="Octave_nn6">29.2.3 Using your module</a></H3> <p> @@ -176,10 +176,10 @@ octave:4> swigexample.cvar.Foo=4; octave:5> swigexample.cvar.Foo ans = 4 </pre></div> -<H2><a name="Octave_nn7">32.3 A tour of basic C/C++ wrapping</a></H2> +<H2><a name="Octave_nn7">29.3 A tour of basic C/C++ wrapping</a></H2> -<H3><a name="Octave_nn8">32.3.1 Modules</a></H3> +<H3><a name="Octave_nn8">29.3.1 Modules</a></H3> <p> @@ -224,7 +224,7 @@ octave:4> swigexample.gcd(4, 6) ans = 2 </pre></div> -<H3><a name="Octave_nn9">32.3.2 Functions</a></H3> +<H3><a name="Octave_nn9">29.3.2 Functions</a></H3> <p> @@ -241,7 +241,7 @@ int fact(int n); </pre></div> <div class="targetlang"><pre>octave:1> swigexample.fact(4) 24 </pre></div> -<H3><a name="Octave_nn10">32.3.3 Global variables</a></H3> +<H3><a name="Octave_nn10">29.3.3 Global variables</a></H3> <p> @@ -294,7 +294,7 @@ octave:2> swigexample.PI=3.142; octave:3> swigexample.PI ans = 3.1420 </pre></div> -<H3><a name="Octave_nn11">32.3.4 Constants and enums</a></H3> +<H3><a name="Octave_nn11">29.3.4 Constants and enums</a></H3> <p> @@ -316,7 +316,7 @@ swigexample.SCONST="Hello World" swigexample.SUNDAY=0 .... </pre></div> -<H3><a name="Octave_nn12">32.3.5 Pointers</a></H3> +<H3><a name="Octave_nn12">29.3.5 Pointers</a></H3> <p> @@ -363,7 +363,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">32.3.6 Structures and C++ classes</a></H3> +<H3><a name="Octave_nn13">29.3.6 Structures and C++ classes</a></H3> <p> @@ -498,7 +498,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">32.3.7 C++ inheritance</a></H3> +<H3><a name="Octave_nn15">29.3.7 C++ inheritance</a></H3> <p> @@ -507,7 +507,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">32.3.8 C++ overloaded functions</a></H3> +<H3><a name="Octave_nn17">29.3.8 C++ overloaded functions</a></H3> <p> @@ -517,7 +517,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">32.3.9 C++ operators</a></H3> +<H3><a name="Octave_nn18">29.3.9 C++ operators</a></H3> <p> @@ -621,7 +621,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">32.3.10 Class extension with %extend</a></H3> +<H3><a name="Octave_nn19">29.3.10 Class extension with %extend</a></H3> <p> @@ -660,7 +660,7 @@ Similarly, Octave can use the <tt>__float__</tt> method to convert an object to Octave 3.8.0 and later versions will also map unary functions X() to the corresponding <tt>__X__</tt> method, where X includes: abs(), acos(), acosh(), angle(), arg(), asin(), asinh(), atan(), atanh(), cbrt(), ceil(), conj(), cos(), cosh(), dawson(), erf(), erfc(), erfcinv(), erfcx(), erfi(), erfinv(), exp(), expm1(), finite(), fix(), floor(), gamma(), imag(), isalnum(), isalpha(), isascii(), iscntrl(), isdigit(), isgraph(), isinf(), islower(), isna(), isnan(), isprint(), ispunct(), isspace(), isupper(), isxdigit(), lgamma(), log(), log10(), log1p(), log2(), real(), round(), roundb(), signbit(), signum(), sin(), sinh(), sqrt(), tan(), tanh(), toascii(), tolower(), toupper() </p> -<H3><a name="Octave_nn20">32.3.11 C++ templates</a></H3> +<H3><a name="Octave_nn20">29.3.11 C++ templates</a></H3> <p> @@ -737,10 +737,10 @@ ans = </pre></div> -<H3><a name="Octave_nn21">32.3.12 C++ Smart Pointers</a></H3> +<H3><a name="Octave_nn21">29.3.12 C++ Smart Pointers</a></H3> -<H4><a name="Octave_smart_pointers_shared_ptr">32.3.12.1 The shared_ptr Smart Pointer</a></H4> +<H4><a name="Octave_smart_pointers_shared_ptr">29.3.12.1 The shared_ptr Smart Pointer</a></H4> <p> @@ -751,14 +751,14 @@ in the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a </p> -<H4><a name="Octave_smart_pointers_generic">32.3.12.2 Generic Smart Pointers</a></H4> +<H4><a name="Octave_smart_pointers_generic">29.3.12.2 Generic Smart Pointers</a></H4> <p> C++ smart pointers are fully supported as in other modules. </p> -<H3><a name="Octave_nn22">32.3.13 Directors (calling Octave from C++ code)</a></H3> +<H3><a name="Octave_nn22">29.3.13 Directors (calling Octave from C++ code)</a></H3> <p> @@ -839,14 +839,14 @@ c-side routine called octave-side routine called </pre></div> -<H3><a name="Octave_nn23">32.3.14 Threads</a></H3> +<H3><a name="Octave_nn23">29.3.14 Threads</a></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">32.3.15 Memory management</a></H3> +<H3><a name="Octave_nn24">29.3.15 Memory management</a></H3> <p> @@ -880,14 +880,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">32.3.16 STL support</a></H3> +<H3><a name="Octave_nn25">29.3.16 STL support</a></H3> <p> Various STL library files are provided for wrapping STL containers. </p> -<H3><a name="Octave_nn26">32.3.17 Matrix typemaps</a></H3> +<H3><a name="Octave_nn26">29.3.17 Matrix typemaps</a></H3> <p> diff --git a/Doc/Manual/Perl5.html b/Doc/Manual/Perl5.html index 96e9f7517..766ccaede 100644 --- a/Doc/Manual/Perl5.html +++ b/Doc/Manual/Perl5.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Perl5">33 SWIG and Perl5</a></H1> +<H1><a name="Perl5">30 SWIG and Perl5</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -97,7 +97,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">33.1 Overview</a></H2> +<H2><a name="Perl5_nn2">30.1 Overview</a></H2> <p> @@ -118,11 +118,11 @@ described. Advanced customization features, typemaps, and other options are found near the end of the chapter. </p> -<H2><a name="Perl5_nn3">33.2 Preliminaries</a></H2> +<H2><a name="Perl5_nn3">30.2 Preliminaries</a></H2> <p> -To build a Perl5 module, run SWIG using the <tt>-perl</tt> option as +To build a Perl5 module, run SWIG using the <tt>-perl</tt> or <tt>-perl5</tt> option as follows: </p> @@ -143,7 +143,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">33.2.1 Getting the right header files</a></H3> +<H3><a name="Perl5_nn4">30.2.1 Getting the right header files</a></H3> <p> @@ -175,7 +175,7 @@ $ perl -e 'use Config; print "$Config{archlib}\n";' </pre> </div> -<H3><a name="Perl5_nn5">33.2.2 Compiling a dynamic module</a></H3> +<H3><a name="Perl5_nn5">30.2.2 Compiling a dynamic module</a></H3> <p> @@ -208,7 +208,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">33.2.3 Building a dynamic module with MakeMaker</a></H3> +<H3><a name="Perl5_nn6">30.2.3 Building a dynamic module with MakeMaker</a></H3> <p> @@ -242,7 +242,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">33.2.4 Building a static version of Perl</a></H3> +<H3><a name="Perl5_nn7">30.2.4 Building a static version of Perl</a></H3> <p> @@ -311,7 +311,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">33.2.5 Using the module</a></H3> +<H3><a name="Perl5_nn8">30.2.5 Using the module</a></H3> <p> @@ -464,7 +464,7 @@ system configuration (this requires root access and you will need to read the man pages). </p> -<H3><a name="Perl5_nn9">33.2.6 Compilation problems and compiling with C++</a></H3> +<H3><a name="Perl5_nn9">30.2.6 Compilation problems and compiling with C++</a></H3> <p> @@ -607,7 +607,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">33.2.7 Compiling for 64-bit platforms</a></H3> +<H3><a name="Perl5_nn10">30.2.7 Compiling for 64-bit platforms</a></H3> <p> @@ -634,7 +634,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">33.3 Building Perl Extensions under Windows</a></H2> +<H2><a name="Perl5_nn11">30.3 Building Perl Extensions under Windows</a></H2> <p> @@ -645,7 +645,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">33.3.1 Running SWIG from Developer Studio</a></H3> +<H3><a name="Perl5_nn12">30.3.1 Running SWIG from Developer Studio</a></H3> <p> @@ -708,7 +708,7 @@ print "$a\n"; </pre></div> -<H3><a name="Perl5_nn13">33.3.2 Using other compilers</a></H3> +<H3><a name="Perl5_nn13">30.3.2 Using other compilers</a></H3> <p> @@ -716,7 +716,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">33.4 The low-level interface</a></H2> +<H2><a name="Perl5_nn14">30.4 The low-level interface</a></H2> <p> @@ -726,7 +726,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">33.4.1 Functions</a></H3> +<H3><a name="Perl5_nn15">30.4.1 Functions</a></H3> <p> @@ -749,7 +749,7 @@ use example; $a = &example::fact(2); </pre></div> -<H3><a name="Perl5_nn16">33.4.2 Global variables</a></H3> +<H3><a name="Perl5_nn16">30.4.2 Global variables</a></H3> <p> @@ -819,7 +819,7 @@ extern char *path; // Declared later in the input </pre> </div> -<H3><a name="Perl5_nn17">33.4.3 Constants</a></H3> +<H3><a name="Perl5_nn17">30.4.3 Constants</a></H3> <p> @@ -859,7 +859,7 @@ print example::FOO, "\n"; </pre> </div> -<H3><a name="Perl5_nn18">33.4.4 Pointers</a></H3> +<H3><a name="Perl5_nn18">30.4.4 Pointers</a></H3> <p> @@ -949,7 +949,7 @@ Foo *BarToFoo(Bar *b) { } Foo *IncrFoo(Foo *f, int i) { - return f+i; + return f+i; } %} </pre> @@ -968,7 +968,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">33.4.5 Structures</a></H3> +<H3><a name="Perl5_nn19">30.4.5 Structures</a></H3> <p> @@ -1057,7 +1057,7 @@ produces a single accessor function like this: <div class="code"> <pre> int *Foo_x_get(Foo *self) { - return self->x; + return self->x; }; </pre> </div> @@ -1092,17 +1092,17 @@ generates accessor functions such as this: <div class="code"> <pre> Foo *Bar_f_get(Bar *b) { - return &b->f; + return &b->f; } void Bar_f_set(Bar *b, Foo *val) { - b->f = *val; + b->f = *val; } </pre> </div> -<H3><a name="Perl5_nn20">33.4.6 C++ classes</a></H3> +<H3><a name="Perl5_nn20">30.4.6 C++ classes</a></H3> <p> @@ -1167,7 +1167,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">33.4.7 C++ classes and type-checking</a></H3> +<H3><a name="Perl5_nn21">30.4.7 C++ classes and type-checking</a></H3> <p> @@ -1203,7 +1203,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">33.4.8 C++ overloaded functions</a></H3> +<H3><a name="Perl5_nn22">30.4.8 C++ overloaded functions</a></H3> <p> @@ -1247,7 +1247,7 @@ example::Spam_foo_d($s, 3.14); Please refer to the "SWIG Basics" chapter for more information. </p> -<H3><a name="Perl5_nn23">33.4.9 Operators</a></H3> +<H3><a name="Perl5_nn23">30.4.9 Operators</a></H3> <p> @@ -1274,7 +1274,7 @@ The following C++ operators are currently supported by the Perl module: <li>operator or </li> </ul> -<H3><a name="Perl5_nn24">33.4.10 Modules and packages</a></H3> +<H3><a name="Perl5_nn24">30.4.10 Modules and packages</a></H3> <p> @@ -1369,7 +1369,7 @@ print Foo::fact(4), "\n"; # Call a function in package FooBar </pre></div> --> -<H2><a name="Perl5_nn25">33.5 Input and output parameters</a></H2> +<H2><a name="Perl5_nn25">30.5 Input and output parameters</a></H2> <p> @@ -1588,7 +1588,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">33.6 Exception handling</a></H2> +<H2><a name="Perl5_nn26">30.6 Exception handling</a></H2> <p> @@ -1633,9 +1633,8 @@ class DoubleArray { void setitem(int i, double val) { if ((i >= 0) && (i < n)) ptr[i] = val; - else { + else throw RangeError(); - } } }; </pre></div> @@ -1753,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">33.7 Remapping datatypes with typemaps</a></H2> +<H2><a name="Perl5_nn27">30.7 Remapping datatypes with typemaps</a></H2> <p> @@ -1770,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">33.7.1 A simple typemap example</a></H3> +<H3><a name="Perl5_nn28">30.7.1 A simple typemap example</a></H3> <p> @@ -1874,7 +1873,7 @@ example::count("e", "Hello World"); </div> -<H3><a name="Perl5_nn29">33.7.2 Perl5 typemaps</a></H3> +<H3><a name="Perl5_nn29">30.7.2 Perl5 typemaps</a></H3> <p> @@ -1888,9 +1887,9 @@ like this: <div class="targetlang"> <pre> %typemap(out) int { - $result = sv_newmortal(); - set_setiv($result, (IV) $1); - argvi++; + $result = sv_newmortal(); + sv_setiv($result, (IV) $1); + argvi++; } </pre> </div> @@ -1979,7 +1978,7 @@ Return of C++ member data (all languages). Check value of input parameter. </div> -<H3><a name="Perl5_nn30">33.7.3 Typemap variables</a></H3> +<H3><a name="Perl5_nn30">30.7.3 Typemap variables</a></H3> <p> @@ -2050,7 +2049,7 @@ properly assigned. The Perl name of the wrapper function being created. </div> -<H3><a name="Perl5_nn31">33.7.4 Useful functions</a></H3> +<H3><a name="Perl5_nn31">30.7.4 Useful functions</a></H3> <p> @@ -2119,7 +2118,7 @@ int sv_isa(SV *, char *0; </div> -<H2><a name="Perl5_nn32">33.8 Typemap Examples</a></H2> +<H2><a name="Perl5_nn32">30.8 Typemap Examples</a></H2> <p> @@ -2128,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">33.8.1 Converting a Perl5 array to a char **</a></H3> +<H3><a name="Perl5_nn33">30.8.1 Converting a Perl5 array to a char **</a></H3> <p> @@ -2220,7 +2219,7 @@ print @$b, "\n"; # Print it out </pre></div> -<H3><a name="Perl5_nn34">33.8.2 Return values</a></H3> +<H3><a name="Perl5_nn34">30.8.2 Return values</a></H3> <p> @@ -2249,7 +2248,7 @@ can be done using the <tt>EXTEND()</tt> macro as in: } </pre></div> -<H3><a name="Perl5_nn35">33.8.3 Returning values from arguments</a></H3> +<H3><a name="Perl5_nn35">30.8.3 Returning values from arguments</a></H3> <p> @@ -2303,7 +2302,7 @@ print "multout(7, 13) = @r\n"; ($x, $y) = multout(7, 13); </pre></div> -<H3><a name="Perl5_nn36">33.8.4 Accessing array structure members</a></H3> +<H3><a name="Perl5_nn36">30.8.4 Accessing array structure members</a></H3> <p> @@ -2313,8 +2312,8 @@ Consider the following data structure: <div class="code"><pre> #define SIZE 8 typedef struct { - int values[SIZE]; - ... + int values[SIZE]; + ... } Foo; </pre></div> @@ -2328,10 +2327,10 @@ To make the member writable, a "memberin" typemap can be used. <div class="code"><pre> %typemap(memberin) int [SIZE] { - int i; - for (i = 0; i < SIZE; i++) { - $1[i] = $input[i]; - } + int i; + for (i = 0; i < SIZE; i++) { + $1[i] = $input[i]; + } } </pre></div> @@ -2366,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">33.8.5 Turning Perl references into C pointers</a></H3> +<H3><a name="Perl5_nn37">30.8.5 Turning Perl references into C pointers</a></H3> <p> @@ -2431,7 +2430,7 @@ print "$c\n"; </pre></div> -<H3><a name="Perl5_nn38">33.8.6 Pointer handling</a></H3> +<H3><a name="Perl5_nn38">30.8.6 Pointer handling</a></H3> <p> @@ -2516,7 +2515,7 @@ For example: </pre> </div> -<H2><a name="Perl5_nn39">33.9 Proxy classes</a></H2> +<H2><a name="Perl5_nn39">30.9 Proxy classes</a></H2> <p> @@ -2532,7 +2531,7 @@ to the underlying code. This section describes the implementation details of the proxy interface. </p> -<H3><a name="Perl5_nn40">33.9.1 Preliminaries</a></H3> +<H3><a name="Perl5_nn40">30.9.1 Preliminaries</a></H3> <p> @@ -2554,7 +2553,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">33.9.2 Structure and class wrappers</a></H3> +<H3><a name="Perl5_nn41">30.9.2 Structure and class wrappers</a></H3> <p> @@ -2600,48 +2599,48 @@ package example::Vector; %BLESSEDMEMBERS = (); sub new () { - my $self = shift; - my @args = @_; - $self = vectorc::new_Vector(@args); - return undef if (!defined($self)); - bless $self, "example::Vector"; - $OWNER{$self} = 1; - my %retval; - tie %retval, "example::Vector", $self; - return bless \%retval, "Vector"; + my $self = shift; + my @args = @_; + $self = vectorc::new_Vector(@args); + return undef if (!defined($self)); + bless $self, "example::Vector"; + $OWNER{$self} = 1; + my %retval; + tie %retval, "example::Vector", $self; + return bless \%retval, "Vector"; } sub DESTROY { - return unless $_[0]->isa('HASH'); - my $self = tied(%{$_[0]}); - delete $ITERATORS{$self}; - if (exists $OWNER{$self}) { - examplec::delete_Vector($self)); - delete $OWNER{$self}; - } + return unless $_[0]->isa('HASH'); + my $self = tied(%{$_[0]}); + delete $ITERATORS{$self}; + if (exists $OWNER{$self}) { + examplec::delete_Vector($self)); + delete $OWNER{$self}; + } } sub FETCH { - my ($self, $field) = @_; - my $member_func = "vectorc::Vector_${field}_get"; - my $val = &$member_func($self); - if (exists $BLESSEDMEMBERS{$field}) { - return undef if (!defined($val)); - my %retval; - tie %retval, $BLESSEDMEMBERS{$field}, $val; - return bless \%retval, $BLESSEDMEMBERS{$field}; - } - return $val; + my ($self, $field) = @_; + my $member_func = "vectorc::Vector_${field}_get"; + my $val = &$member_func($self); + if (exists $BLESSEDMEMBERS{$field}) { + return undef if (!defined($val)); + my %retval; + tie %retval, $BLESSEDMEMBERS{$field}, $val; + return bless \%retval, $BLESSEDMEMBERS{$field}; + } + return $val; } sub STORE { - my ($self, $field, $newval) = @_; - my $member_func = "vectorc::Vector_${field}_set"; - if (exists $BLESSEDMEMBERS{$field}) { - &$member_func($self, tied(%{$newval})); - } else { - &$member_func($self, $newval); - } + my ($self, $field, $newval) = @_; + my $member_func = "vectorc::Vector_${field}_set"; + if (exists $BLESSEDMEMBERS{$field}) { + &$member_func($self, tied(%{$newval})); + } else { + &$member_func($self, $newval); + } } </pre></div> @@ -2681,7 +2680,7 @@ $v->DESTROY(); </pre></div> -<H3><a name="Perl5_nn42">33.9.3 Object Ownership</a></H3> +<H3><a name="Perl5_nn42">30.9.3 Object Ownership</a></H3> <p> @@ -2768,7 +2767,7 @@ counting, garbage collection, or advanced features one might find in sophisticated languages. </p> -<H3><a name="Perl5_nn43">33.9.4 Nested Objects</a></H3> +<H3><a name="Perl5_nn43">30.9.4 Nested Objects</a></H3> <p> @@ -2821,7 +2820,7 @@ $p->{f}->{x} = 0.0; %${$p->{v}} = ( x=>0, y=>0, z=>0); </pre></div> -<H3><a name="Perl5_nn44">33.9.5 Proxy Functions</a></H3> +<H3><a name="Perl5_nn44">30.9.5 Proxy Functions</a></H3> <p> @@ -2842,11 +2841,11 @@ this: <div class="targetlang"><pre> sub dot_product { - my @args = @_; - $args[0] = tied(%{$args[0]}); # Get the real pointer values - $args[1] = tied(%{$args[1]}); - my $result = vectorc::dot_product(@args); - return $result; + my @args = @_; + $args[0] = tied(%{$args[0]}); # Get the real pointer values + $args[1] = tied(%{$args[1]}); + my $result = vectorc::dot_product(@args); + return $result; } </pre></div> @@ -2855,7 +2854,7 @@ This function replaces the original function, but operates in an identical manner. </p> -<H3><a name="Perl5_nn45">33.9.6 Inheritance</a></H3> +<H3><a name="Perl5_nn45">30.9.6 Inheritance</a></H3> <p> @@ -2931,7 +2930,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">33.9.7 Modifying the proxy methods</a></H3> +<H3><a name="Perl5_nn46">30.9.7 Modifying the proxy methods</a></H3> <p> @@ -2959,7 +2958,7 @@ public: }; </pre></div> -<H2><a name="Perl5_nn47">33.10 Adding additional Perl code</a></H2> +<H2><a name="Perl5_nn47">30.10 Adding additional Perl code</a></H2> <p> @@ -2985,7 +2984,7 @@ sub set_transform for (my $j = 0; $j < 4, $j++) { mat44_set($a, $i, $j, $x->[i][j]) - } + } } example.set_transform($im, $a); free_mat44($a); @@ -3010,7 +3009,7 @@ set_transform($im, $a); </pre> </div> -<H2><a name="Perl5_directors">33.11 Cross language polymorphism</a></H2> +<H2><a name="Perl5_directors">30.11 Cross language polymorphism</a></H2> <p> @@ -3044,7 +3043,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">33.11.1 Enabling directors</a></H3> +<H3><a name="Perl5_nn48">30.11.1 Enabling directors</a></H3> <p> @@ -3071,7 +3070,7 @@ globally, to specific classes, and to specific methods, like this: // generate directors for all classes that have virtual methods %feature("director"); -// generate directors for all virtual methods in class Foo +// generate directors for the virtual methods in class Foo %feature("director") Foo; </pre> </div> @@ -3089,7 +3088,7 @@ directors for specific classes or methods. So for example, </div> <p> -will generate directors for all virtual methods of class Foo except +will generate directors for the virtual methods of class Foo except bar(). </p> @@ -3104,14 +3103,14 @@ the methods one() and two() (but not three()): %feature("director") Foo; class Foo { public: - Foo(int foo); - virtual void one(); - virtual void two(); + Foo(int foo); + virtual void one(); + virtual void two(); }; class Bar: public Foo { public: - virtual void three(); + virtual void three(); }; </pre> </div> @@ -3134,7 +3133,7 @@ sub one { </div> -<H3><a name="Perl5_nn49">33.11.2 Director classes</a></H3> +<H3><a name="Perl5_nn49">30.11.2 Director classes</a></H3> @@ -3154,7 +3153,8 @@ For simplicity let's ignore the <tt>Swig::Director</tt> class and refer to the original C++ class as the director's base class. By default, a director class extends all virtual methods in the inheritance chain of its base class (see the preceding section for how to modify this behavior). -Thus all virtual method calls, whether they originate in C++ or in +Virtual methods that have a final specifier are unsurprisingly excluded. +Thus the virtual method calls, whether they originate in C++ or in Perl via proxy classes, eventually end up in at the implementation in the director class. The job of the director methods is to route these method calls to the appropriate place in the inheritance chain. By @@ -3214,7 +3214,7 @@ so there is no need for the extra overhead involved with routing the calls through Perl. </p> -<H3><a name="Perl5_nn50">33.11.3 Ownership and object destruction</a></H3> +<H3><a name="Perl5_nn50">30.11.3 Ownership and object destruction</a></H3> <p> @@ -3263,7 +3263,7 @@ sub DESTROY { </div> -<H3><a name="Perl5_nn51">33.11.4 Exception unrolling</a></H3> +<H3><a name="Perl5_nn51">30.11.4 Exception unrolling</a></H3> <p> @@ -3279,9 +3279,9 @@ suffice in most cases: <div class="code"> <pre> %feature("director:except") { - if ($error != NULL) { - throw Swig::DirectorMethodException(); - } + if ($error != NULL) { + throw Swig::DirectorMethodException(); + } } </pre> </div> @@ -3305,8 +3305,8 @@ suitable exception handler: <div class="code"> <pre> %exception { - try { $action } - catch (Swig::DirectorException &e) { SWIG_fail; } + try { $action } + catch (Swig::DirectorException &e) { SWIG_fail; } } </pre> </div> @@ -3319,7 +3319,7 @@ Swig::DirectorMethodException is thrown, Perl will register the exception as soon as the C wrapper function returns. </p> -<H3><a name="Perl5_nn52">33.11.5 Overhead and code bloat</a></H3> +<H3><a name="Perl5_nn52">30.11.5 Overhead and code bloat</a></H3> <p> @@ -3353,7 +3353,7 @@ directive) for only those methods that are likely to be extended in Perl. </p> -<H3><a name="Perl5_nn53">33.11.6 Typemaps</a></H3> +<H3><a name="Perl5_nn53">30.11.6 Typemaps</a></H3> <p> diff --git a/Doc/Manual/Php.html b/Doc/Manual/Php.html index 52bedf87f..d0ec0df7f 100644 --- a/Doc/Manual/Php.html +++ b/Doc/Manual/Php.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Php">34 SWIG and PHP</a></H1> +<H1><a name="Php">31 SWIG and PHP</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -50,20 +50,13 @@ <p> -In this chapter, we discuss SWIG's support of PHP. The PHP module -was extensively rewritten in release 1.3.26, and support for generating -OO wrappers for PHP5 was added in 1.3.30. The PHP module now supports most -of the features available in some of the other languages. +In this chapter, we discuss SWIG's support of PHP. SWIG currently supports +generating wrappers for PHP7. Support for PHP5 was removed in SWIG 4.0.0 +and support for PHP4 was removed in SWIG 1.3.37. </p> <p> -SWIG supports generating wrappers for PHP5 and PHP7. Support for PHP4 was removed -in SWIG 1.3.37. -</p> - -<p> -Currently any PHP5 or PHP7 release should work, but we don't regularly test with -PHP < 5.3. +Currently any PHP7 release should work. </p> <p> @@ -77,13 +70,13 @@ your extension into php directly, you will need the complete PHP source tree available. </p> -<H2><a name="Php_nn1">34.1 Generating PHP Extensions</a></H2> +<H2><a name="Php_nn1">31.1 Generating PHP Extensions</a></H2> <p> -To build a PHP extension, run swig using the <tt>-php5</tt> or -<tt>-php7</tt> option as follows (<tt>-php</tt> is also supported -and currently is an alias for <tt>-php5</tt>): +To build a PHP extension, run swig using the <tt>-php7</tt> option as follows +(<tt>-php</tt> is also supported and currently is an alias for <tt>-php7</tt> +but prior to SWIG 4.0.0 it was an alias for <tt>-php5</tt>): </p> <div class="code"><pre> @@ -107,9 +100,7 @@ also contain PHP class wrappers. SWIG can generate PHP extensions from C++ libraries as well when given the <tt>-c++</tt> option. The support for C++ is discussed in more detail in <a href="#Php_nn2_6">section 27.2.6</a>. The generated -C++ wrapper will be called example_wrap.cpp (for PHP5) or -example_wrap.cxx (for PHP7 where the default has been changed to align -with SWIG's default for every other language). You can specify a +C++ wrapper will be called example_wrap.cxx. You can specify a different extension for the C++ wrapper using <tt>-cppext</tt> - e.g. if you want example_wrap.cc use <tt>-cppext cc</tt>. </p> @@ -128,7 +119,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">34.1.1 Building a loadable extension</a></H3> +<H3><a name="Php_nn1_1">31.1.1 Building a loadable extension</a></H3> <p> @@ -143,7 +134,7 @@ least work for Linux though): gcc -shared example_wrap.o example.o -o example.so </pre></div> -<H3><a name="Php_nn1_3">34.1.2 Using PHP Extensions</a></H3> +<H3><a name="Php_nn1_3">31.1.2 Using PHP Extensions</a></H3> <p> @@ -162,8 +153,8 @@ If the module is in PHP's default extension directory, you can omit the path. <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 +<a href="https://www.php.net/manual/en/function.dl.php">dl() function</a> to load +an extension at run time, by adding a line like this to the start of each PHP script which uses your extension: </p> @@ -172,8 +163,8 @@ PHP script which uses your extension: </pre></div> <p> -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 +But note that <tt>dl()</tt> isn't supported when running PHP through a +webserver - you'll need to use <tt>extension</tt> in <tt>php.ini</tt> as described above. </p> @@ -191,7 +182,7 @@ 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">34.2 Basic PHP interface</a></H2> +<H2><a name="Php_nn2">31.2 Basic PHP interface</a></H2> <p> @@ -199,10 +190,11 @@ It is important to understand that PHP uses a single global namespace into which all symbols from extension modules are loaded. It is quite possible for names of symbols in one extension module to clash with 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. +SWIG doesn't have support for generating wrappers which make use of PHP's +namespace feature. </p> -<H3><a name="Php_nn2_1">34.2.1 Constants</a></H3> +<H3><a name="Php_nn2_1">31.2.1 Constants</a></H3> <p> @@ -239,10 +231,12 @@ 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 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. +constant, PHP will emit a warning (or a notice in PHP 7.1 and earlier) and then +expand the constant to a string version of the constant's name. Unfortunately +it is easy to miss the warning message if you're using PHP in a webserver as +it will probably end up in error.log or similar. Apparently this will throw +an Error in a future version of PHP, but until then it's something to be +aware of. </p> <p> @@ -276,11 +270,10 @@ if(EASY_TO_MISPEL) { <p> The mis-spelled constant will become the string 'EASY_TO_MISPEL', which is treated as true by the if test, when the value of the intended constant -would be treated as false! Modern versions of PHP will at least issue -a PHP notice by default when this happens. +would be treated as false! </p> -<H3><a name="Php_nn2_2">34.2.2 Global Variables</a></H3> +<H3><a name="Php_nn2_2">31.2.2 Global Variables</a></H3> <p> @@ -329,7 +322,7 @@ undefined. At this time SWIG does not support custom accessor methods. </p> -<H3><a name="Php_nn2_3">34.2.3 Functions</a></H3> +<H3><a name="Php_nn2_3">31.2.3 Functions</a></H3> <p> @@ -382,7 +375,7 @@ print $s; # The value of $s was not changed. --> -<H3><a name="Php_nn2_4">34.2.4 Overloading</a></H3> +<H3><a name="Php_nn2_4">31.2.4 Overloading</a></H3> <p> @@ -390,8 +383,7 @@ Although PHP does not support overloading functions natively, swig will generate dispatch functions which will use <tt>%typecheck</tt> typemaps to allow overloading. This dispatch function's operation and precedence is described in <a -href="SWIGPlus.html#SWIGPlus_overloaded_methods">Wrapping -Overloaded Functions and Methods</a>. +href="SWIGPlus.html#SWIGPlus_overloaded_methods">Overloaded functions and methods</a>. </p> <!-- This isn't correct for 1.3.30 and needs rewriting to reflect reality @@ -438,7 +430,7 @@ taking the integer argument. </p> --> -<H3><a name="Php_nn2_5">34.2.5 Pointers and References</a></H3> +<H3><a name="Php_nn2_5">31.2.5 Pointers and References</a></H3> <p> @@ -527,13 +519,6 @@ named typemap REF. </p> <p> -Prior to SWIG 3.0, the REF typemaps relied on PHP's call-time -pass-by-reference, which was deprecated in PHP 5.3 and removed in PHP 5.4. -So if you use these REF typemaps, you should ensure that SWIG≥3.0 is -used to generate wrappers from your interface file. -</p> - -<p> In case you write your own typemaps, SWIG supports an attribute called <tt>byref</tt>: if you set that, then SWIG will make sure that the generated wrapper function will want the input parameter as a reference. @@ -583,7 +568,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">34.2.6 Structures and C++ classes</a></H3> +<H3><a name="Php_nn2_6">31.2.6 Structures and C++ classes</a></H3> <p> @@ -644,7 +629,7 @@ Would be used in the following way from PHP: Member variables and methods are accessed using the <tt>-></tt> operator. </p> -<H4><a name="Php_nn2_6_1">34.2.6.1 Using -noproxy</a></H4> +<H4><a name="Php_nn2_6_1">31.2.6.1 Using -noproxy</a></H4> <p> @@ -670,7 +655,7 @@ Complex_im_set($obj, $d); Complex_im_get($obj); </pre></div> -<H4><a name="Php_nn2_6_2">34.2.6.2 Constructors and Destructors</a></H4> +<H4><a name="Php_nn2_6_2">31.2.6.2 Constructors and Destructors</a></H4> <p> @@ -711,7 +696,7 @@ the programmer can either reassign the variable or call <tt>unset($v)</tt> </p> -<H4><a name="Php_nn2_6_3">34.2.6.3 Static Member Variables</a></H4> +<H4><a name="Php_nn2_6_3">31.2.6.3 Static Member Variables</a></H4> <p> @@ -754,7 +739,7 @@ Ko::threats(10); echo "There have now been " . Ko::threats() . " threats\n"; </pre></div> -<H4><a name="Php_nn2_6_4">34.2.6.4 Static Member Functions</a></H4> +<H4><a name="Php_nn2_6_4">31.2.6.4 Static Member Functions</a></H4> <p> @@ -776,7 +761,7 @@ Ko::threats(); </pre></div> -<H4><a name="Php_nn2_6_5">34.2.6.5 Specifying Implemented Interfaces</a></H4> +<H4><a name="Php_nn2_6_5">31.2.6.5 Specifying Implemented Interfaces</a></H4> <p> @@ -794,7 +779,7 @@ so: If there are multiple interfaces, just list them separated by commas. </p> -<H3><a name="Php_nn2_7">34.2.7 PHP Pragmas, Startup and Shutdown code</a></H3> +<H3><a name="Php_nn2_7">31.2.7 PHP Pragmas, Startup and Shutdown code</a></H3> <p> @@ -821,6 +806,15 @@ echo "example.php execution\n"; </pre></div> <p> +The <b>version</b> pragma can be used to add version to generated PHP extension module. The version is inserted in the zend_module_entry block. +</p> + +<div class="code"><pre> +%module example +%pragma(php) version="1.5" +</pre></div> + +<p> The <b>include</b> pragma is a short cut to add include statements to the example.php file. </p> @@ -882,7 +876,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">34.3 Cross language polymorphism</a></H2> +<H2><a name="Php_nn3">31.3 Cross language polymorphism</a></H2> <p> @@ -917,7 +911,7 @@ wrapper functions takes care of all the cross-language method routing transparently. </p> -<H3><a name="Php_nn3_1">34.3.1 Enabling directors</a></H3> +<H3><a name="Php_nn3_1">31.3.1 Enabling directors</a></H3> <p> @@ -944,7 +938,7 @@ globally, to specific classes, and to specific methods, like this: // generate directors for all classes that have virtual methods %feature("director"); -// generate directors for all virtual methods in class Foo +// generate directors for the virtual methods in class Foo %feature("director") Foo; </pre> </div> @@ -962,7 +956,7 @@ directors for specific classes or methods. So for example, </div> <p> -will generate directors for all virtual methods of class Foo except +will generate directors for the virtual methods of class Foo except bar(). </p> @@ -977,14 +971,14 @@ the methods one() and two() (but not three()): %feature("director") Foo; class Foo { public: - Foo(int foo); - virtual void one(); - virtual void two(); + Foo(int foo); + virtual void one(); + virtual void two(); }; class Bar: public Foo { public: - virtual void three(); + virtual void three(); }; </pre> </div> @@ -1006,7 +1000,7 @@ class MyFoo extends Foo { </div> -<H3><a name="Php_nn3_2">34.3.2 Director classes</a></H3> +<H3><a name="Php_nn3_2">31.3.2 Director classes</a></H3> @@ -1027,7 +1021,8 @@ For simplicity let's ignore the <tt>Swig::Director</tt> class and refer to the original C++ class as the director's base class. By default, a director class extends all virtual methods in the inheritance chain of its base class (see the preceding section for how to modify this behavior). -Thus all virtual method calls, whether they originate in C++ or in +Virtual methods that have a final specifier are unsurprisingly excluded. +Thus the virtual method calls, whether they originate in C++ or in PHP via proxy classes, eventually end up in at the implementation in the director class. The job of the director methods is to route these method calls to the appropriate place in the inheritance chain. By "appropriate @@ -1086,7 +1081,7 @@ so there is no need for the extra overhead involved with routing the calls through PHP. </p> -<H3><a name="Php_nn3_3">34.3.3 Ownership and object destruction</a></H3> +<H3><a name="Php_nn3_3">31.3.3 Ownership and object destruction</a></H3> <p> @@ -1116,12 +1111,12 @@ Here is an example: <pre> class Foo { public: - ... + ... }; class FooContainer { public: - void addFoo(Foo *); - ... + void addFoo(Foo *); + ... }; </pre> </div> @@ -1142,7 +1137,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">34.3.4 Exception unrolling</a></H3> +<H3><a name="Php_nn3_4">31.3.4 Exception unrolling</a></H3> <p> @@ -1166,9 +1161,9 @@ should suffice in most cases: <div class="code"> <pre> %feature("director:except") { - if ($error == FAILURE) { - throw Swig::DirectorMethodException(); - } + if ($error == FAILURE) { + throw Swig::DirectorMethodException(); + } } </pre> </div> @@ -1195,8 +1190,8 @@ suitable exception handler: <div class="code"> <pre> %exception { - try { $action } - catch (Swig::DirectorException &e) { SWIG_fail; } + try { $action } + catch (Swig::DirectorException &e) { SWIG_fail; } } </pre> </div> @@ -1209,7 +1204,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">34.3.5 Overhead and code bloat</a></H3> +<H3><a name="Php_nn3_5">31.3.5 Overhead and code bloat</a></H3> <p> @@ -1242,7 +1237,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">34.3.6 Typemaps</a></H3> +<H3><a name="Php_nn3_6">31.3.6 Typemaps</a></H3> <p> @@ -1256,7 +1251,7 @@ need to be supported. </p> -<H3><a name="Php_nn3_7">34.3.7 Miscellaneous</a></H3> +<H3><a name="Php_nn3_7">31.3.7 Miscellaneous</a></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 22ab4e2a2..2b8432399 100644 --- a/Doc/Manual/Pike.html +++ b/Doc/Manual/Pike.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Pike">35 SWIG and Pike</a></H1> +<H1><a name="Pike">37 SWIG and Pike</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -47,10 +47,10 @@ least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>" chapter.<br> </p> -<H2><a name="Pike_nn2">35.1 Preliminaries</a></H2> +<H2><a name="Pike_nn2">37.1 Preliminaries</a></H2> -<H3><a name="Pike_nn3">35.1.1 Running SWIG</a></H3> +<H3><a name="Pike_nn3">37.1.1 Running SWIG</a></H3> <p> @@ -95,7 +95,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">35.1.2 Getting the right header files</a></H3> +<H3><a name="Pike_nn4">37.1.2 Getting the right header files</a></H3> <p> @@ -115,7 +115,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">35.1.3 Using your module</a></H3> +<H3><a name="Pike_nn5">37.1.3 Using your module</a></H3> <p> @@ -130,10 +130,10 @@ Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend) (1) Result: 24 </pre></div> -<H2><a name="Pike_nn6">35.2 Basic C/C++ Mapping</a></H2> +<H2><a name="Pike_nn6">37.2 Basic C/C++ Mapping</a></H2> -<H3><a name="Pike_nn7">35.2.1 Modules</a></H3> +<H3><a name="Pike_nn7">37.2.1 Modules</a></H3> <p> @@ -144,7 +144,7 @@ concerned), SWIG's <tt>%module</tt> directive doesn't really have any significance. </p> -<H3><a name="Pike_nn8">35.2.2 Functions</a></H3> +<H3><a name="Pike_nn8">37.2.2 Functions</a></H3> <p> @@ -169,7 +169,7 @@ exactly as you'd expect it to: (1) Result: 24 </pre></div> -<H3><a name="Pike_nn9">35.2.3 Global variables</a></H3> +<H3><a name="Pike_nn9">37.2.3 Global variables</a></H3> <p> @@ -198,7 +198,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">35.2.4 Constants and enumerated types</a></H3> +<H3><a name="Pike_nn10">37.2.4 Constants and enumerated types</a></H3> <p> @@ -206,7 +206,7 @@ Enumerated types in C/C++ declarations are wrapped as Pike constants, not as Pike enums. </p> -<H3><a name="Pike_nn11">35.2.5 Constructors and Destructors</a></H3> +<H3><a name="Pike_nn11">37.2.5 Constructors and Destructors</a></H3> <p> @@ -214,7 +214,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">35.2.6 Static Members</a></H3> +<H3><a name="Pike_nn12">37.2.6 Static Members</a></H3> <p> @@ -230,8 +230,8 @@ For example, given this C++ class declaration: class Shape { public: - static void print(); - static int nshapes; + static void print(); + static int nshapes; }; </pre></div> diff --git a/Doc/Manual/Preface.html b/Doc/Manual/Preface.html index 3b654a6d2..36a99bd1f 100644 --- a/Doc/Manual/Preface.html +++ b/Doc/Manual/Preface.html @@ -69,6 +69,9 @@ over a period of 10 years starting from the year 2000. The final version in the series was 1.3.40, but in truth the 1.3.x series had been stable for many years. An official stable version was released along with the decision to make SWIG license changes and this gave rise to version 2.0.0 in 2010. +Version 3.0.0 was released in 2014 focusing on adding C++11 support and C++ nested classes. +Version 4.0.0 was released in 2019 to add in Doxygen support. +Some target languages were disabled as part of a clean up and others were given a new status of either 'Supported' or 'Experimental'. </p> <H2><a name="Preface_license">1.3 SWIG License</a></H2> @@ -364,7 +367,7 @@ a number of packages to be installed. Full instructions at <p> SWIG is known to work on various flavors of OS X. Follow the Unix installation instructions above. However, as of this writing, there is still great deal of -inconsistency with how shared libaries are handled by various scripting languages +inconsistency with how shared libraries are handled by various scripting languages on OS X. </p> @@ -435,7 +438,7 @@ don't intend to use these features in your own programs. </p> <p> -Note: The test-suite currently contains over 500 tests. If you +Note: The test-suite currently contains over 600 tests. If you have many different target languages installed and a slow machine, it might take more than an hour to run the test-suite. </p> diff --git a/Doc/Manual/Preprocessor.html b/Doc/Manual/Preprocessor.html index efa0c0f8e..3d1bb453e 100644 --- a/Doc/Manual/Preprocessor.html +++ b/Doc/Manual/Preprocessor.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Preprocessor">8 Preprocessing</a></H1> +<H1><a name="Preprocessor">10 Preprocessing</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -38,7 +38,7 @@ However, a number of modifications and enhancements have been made. This chapter describes some of these modifications. </p> -<H2><a name="Preprocessor_nn2">8.1 File inclusion</a></H2> +<H2><a name="Preprocessor_nn2">10.1 File inclusion</a></H2> <p> @@ -64,7 +64,7 @@ By default, the <tt>#include</tt> is ignored unless you run SWIG with the is that you often don't want SWIG to try and wrap everything included in standard header system headers and auxiliary files. -<H2><a name="Preprocessor_nn3">8.2 File imports</a></H2> +<H2><a name="Preprocessor_nn3">10.2 File imports</a></H2> <p> @@ -93,7 +93,7 @@ The <tt>-importall</tt> directive tells SWIG to follow all <tt>#include</tt> sta as imports. This might be useful if you want to extract type definitions from system header files without generating any wrappers. -<H2><a name="Preprocessor_condition_compilation">8.3 Conditional Compilation</a></H2> +<H2><a name="Preprocessor_condition_compilation">10.3 Conditional Compilation</a></H2> <p> @@ -109,10 +109,6 @@ SWIGIMPORTED Defined when SWIG is importing a file with <tt>% SWIG_VERSION Hexadecimal (binary-coded decimal) number containing SWIG version, such as 0x010311 (corresponding to SWIG-1.3.11). -SWIGALLEGROCL Defined when using Allegro CL -SWIGCFFI Defined when using CFFI -SWIGCHICKEN Defined when using CHICKEN -SWIGCLISP Defined when using CLISP SWIGCSHARP Defined when using C# SWIGGUILE Defined when using Guile SWIGJAVA Defined when using Java @@ -120,20 +116,16 @@ SWIGJAVASCRIPT Defined when using Javascript SWIG_JAVASCRIPT_JSC Defined when using Javascript for JavascriptCore SWIG_JAVASCRIPT_V8 Defined when using Javascript for v8 or node.js SWIGLUA Defined when using Lua -SWIGMODULA3 Defined when using Modula-3 SWIGMZSCHEME Defined when using Mzscheme -SWIGOCAML Defined when using Ocaml +SWIGOCAML Defined when using OCaml SWIGOCTAVE Defined when using Octave SWIGPERL Defined when using Perl -SWIGPHP Defined when using PHP5 or PHP7 -SWIGPHP5 Defined when using PHP5 +SWIGPHP Defined when using PHP (any version) SWIGPHP7 Defined when using PHP7 -SWIGPIKE Defined when using Pike SWIGPYTHON Defined when using Python SWIGR Defined when using R SWIGRUBY Defined when using Ruby SWIGSCILAB Defined when using Scilab -SWIGSEXP Defined when using S-expressions SWIGTCL Defined when using Tcl SWIGXML Defined when using XML </pre></div> @@ -146,7 +138,7 @@ In addition, SWIG defines the following set of standard C/C++ macros: <pre> __LINE__ Current line number __FILE__ Current file name -__STDC__ Defined to indicate ANSI C +__STDC__ Defined to indicate ISO C __cplusplus Defined when -c++ option used </pre> </div> @@ -159,7 +151,7 @@ SWIG (except for the symbol `<tt>SWIG</tt>' which is only defined within the SWIG compiler). </p> -<H2><a name="Preprocessor_nn5">8.4 Macro Expansion</a></H2> +<H2><a name="Preprocessor_nn5">10.4 Macro Expansion</a></H2> <p> @@ -188,9 +180,9 @@ More complex macros can be defined in the standard way. For example: <pre> #define EXTERN extern #ifdef __STDC__ -#define _ANSI(args) (args) +#define ISOC_(args) (args) #else -#define _ANSI(args) () +#define ISOC_(args) () #endif </pre> </div> @@ -214,7 +206,7 @@ like <tt>#x</tt>. This is a non-standard SWIG extension. </li> </ul> -<H2><a name="Preprocessor_nn6">8.5 SWIG Macros</a></H2> +<H2><a name="Preprocessor_nn6">10.5 SWIG Macros</a></H2> <p> @@ -260,7 +252,7 @@ many of SWIG's advanced features and libraries are built using this mechanism (s support). </p> -<H2><a name="Preprocessor_nn7">8.6 C99 and GNU Extensions</a></H2> +<H2><a name="Preprocessor_nn7">10.6 C99 and GNU Extensions</a></H2> <p> @@ -316,14 +308,14 @@ interface building. However, they are used internally to implement a number of SWIG directives and are provided to make SWIG more compatible with C99 code. </p> -<H2><a name="Preprocessor_delimiters">8.7 Preprocessing and delimiters</a></H2> +<H2><a name="Preprocessor_delimiters">10.7 Preprocessing and delimiters</a></H2> <p> The preprocessor handles { }, " " and %{ %} delimiters differently. </p> -<H3><a name="Preprocessor_nn8">8.7.1 Preprocessing and %{ ... %} & " ... " delimiters</a></H3> +<H3><a name="Preprocessor_nn8">10.7.1 Preprocessing and %{ ... %} & " ... " delimiters</a></H3> <p> @@ -348,7 +340,7 @@ the contents of the <tt>%{ ... %}</tt> block are copied without modification to the output (including all preprocessor directives). </p> -<H3><a name="Preprocessor_nn9">8.7.2 Preprocessing and { ... } delimiters</a></H3> +<H3><a name="Preprocessor_nn9">10.7.2 Preprocessing and { ... } delimiters</a></H3> <p> @@ -390,7 +382,7 @@ to actually go into the wrapper file, prefix the preprocessor directives with <t SWIG will strip the extra <tt>%</tt> and leave the preprocessor directive in the code. </p> -<H2><a name="Preprocessor_typemap_delimiters">8.8 Preprocessor and Typemaps</a></H2> +<H2><a name="Preprocessor_typemap_delimiters">10.8 Preprocessor and Typemaps</a></H2> <p> @@ -461,17 +453,17 @@ would generate </div> -<H2><a name="Preprocessor_nn10">8.9 Viewing preprocessor output</a></H2> +<H2><a name="Preprocessor_nn10">10.9 Viewing preprocessor output</a></H2> <p> Like many compilers, SWIG supports a <tt>-E</tt> command line option to display the output from the preprocessor. -When the <tt>-E</tt> switch is used, SWIG will not generate any wrappers. +When the <tt>-E</tt> option is used, SWIG will not generate any wrappers. Instead the results after the preprocessor has run are displayed. This might be useful as an aid to debugging and viewing the results of macro expansions. </p> -<H2><a name="Preprocessor_warning_error">8.10 The #error and #warning directives</a></H2> +<H2><a name="Preprocessor_warning_error">10.10 The #error and #warning directives</a></H2> <p> diff --git a/Doc/Manual/Python.html b/Doc/Manual/Python.html index a5b2100ce..ee443be53 100644 --- a/Doc/Manual/Python.html +++ b/Doc/Manual/Python.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Python">36 SWIG and Python</a></H1> +<H1><a name="Python">32 SWIG and Python</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -21,7 +21,8 @@ <li><a href="#Python_nn9">Using your module</a> <li><a href="#Python_nn10">Compilation of C++ extensions</a> <li><a href="#Python_nn11">Compiling for 64-bit platforms</a> -<li><a href="#Python_nn12">Building Python Extensions under Windows</a> +<li><a href="#Python_nn12">Building Python extensions under Windows</a> +<li><a href="#Python_commandline">Additional Python commandline options</a> </ul> <li><a href="#Python_nn13">A tour of basic C/C++ wrapping</a> <ul> @@ -54,7 +55,6 @@ <li><a href="#Python_builtin_overloads">Operator overloads and slots -- use them!</a> </ul> <li><a href="#Python_nn30">Memory management</a> -<li><a href="#Python_nn31">Python 2.2 and classic classes</a> </ul> <li><a href="#Python_directors">Cross language polymorphism</a> <ul> @@ -72,6 +72,10 @@ <li><a href="#Python_nn42">Adding additional Python code</a> <li><a href="#Python_nn43">Class extension with %extend</a> <li><a href="#Python_nn44">Exception handling with %exception</a> +<li><a href="#Python_optimization">Optimization options</a> +<ul> +<li><a href="#Python_fastproxy">-fastproxy</a> +</ul> </ul> <li><a href="#Python_nn45">Tips and techniques</a> <ul> @@ -96,6 +100,7 @@ <li><a href="#Python_nn62">Mapping Python tuples into small arrays</a> <li><a href="#Python_nn63">Mapping sequences to C arrays</a> <li><a href="#Python_nn64">Pointer handling</a> +<li><a href="#Python_memory_management_member_variables">Memory management when returning references to member variables</a> </ul> <li><a href="#Python_nn65">Docstring Features</a> <ul> @@ -116,12 +121,13 @@ <li><a href="#Python_absrelimports">Absolute and relative imports</a> <li><a href="#Python_absimport">Enforcing absolute import semantics</a> <li><a href="#Python_importfrominit">Importing from __init__.py</a> -<li><a href="#Python_implicit_namespace_packages">Implicit Namespace Packages</a> -<li><a href="#Python_package_search">Searching for the wrapper module</a> +<li><a href="#Python_implicit_namespace_packages">Implicit namespace packages</a> +<li><a href="#Python_package_search">Location of modules</a> <ul> <li><a href="#Python_package_search_both_package_modules">Both modules in the same package</a> -<li><a href="#Python_package_search_wrapper_split">Split modules</a> <li><a href="#Python_package_search_both_global_modules">Both modules are global</a> +<li><a href="#Python_package_search_wrapper_split">Split modules custom configuration</a> +<li><a href="#Python_custom_module_import">More on customizing the module import code</a> <li><a href="#Python_package_search_static">Statically linked C modules</a> </ul> </ul> @@ -133,6 +139,11 @@ <li><a href="#Python_nn77">Byte string output conversion</a> <li><a href="#Python_2_unicode">Python 2 Unicode</a> </ul> +<li><a href="#Python_multithreaded">Support for Multithreaded Applications</a> +<ul> +<li><a href="#Python_thread_UI">UI for Enabling Multithreading Support</a> +<li><a href="#Python_thread_performance">Multithread Performance</a> +</ul> </ul> </div> <!-- INDEX --> @@ -145,9 +156,9 @@ <p> This chapter describes SWIG's support of Python. SWIG is compatible -with most recent Python versions including Python 3.0 and Python 2.6, -as well as older versions dating back to Python 2.0. For the best results, -consider using Python 2.3 or newer. +with all recent Python versions (Python 2.7 and Python >= 3.2). If you +still need to generate bindings which work with older versions of Python, +you'll have to use SWIG 3.0.x. </p> <p> @@ -157,12 +168,12 @@ very least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>" chapter. </p> -<H2><a name="Python_nn2">36.1 Overview</a></H2> +<H2><a name="Python_nn2">32.1 Overview</a></H2> <p> To build Python extension modules, SWIG uses a layered approach in which -parts of the extension module are defined in C and other parts are +parts of the extension module are defined in C and other parts are defined in Python. The C layer contains low-level wrappers whereas Python code is used to define high-level features. </p> @@ -184,10 +195,10 @@ described followed by a discussion of low-level implementation details. </p> -<H2><a name="Python_nn3">36.2 Preliminaries</a></H2> +<H2><a name="Python_nn3">32.2 Preliminaries</a></H2> -<H3><a name="Python_nn4">36.2.1 Running SWIG</a></H3> +<H3><a name="Python_nn4">32.2.1 Running SWIG</a></H3> <p> @@ -210,7 +221,7 @@ int fact(int n); <p> 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 +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> @@ -221,16 +232,15 @@ resulting C file should be built as a python extension, inserting the module #include "example.h" int fact(int n) { - if (n < 0){ /* This should probably return an error, but this is simpler */ - return 0; - } - if (n == 0) { - return 1; - } - else { - /* testing for overflow would be a good idea here */ - return n * fact(n-1); - } + if (n < 0) { /* This should probably return an error, but this is simpler */ + return 0; + } + if (n == 0) { + return 1; + } else { + /* testing for overflow would be a good idea here */ + return n * fact(n-1); + } } </pre> @@ -285,13 +295,13 @@ 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">36.2.2 Using distutils</a></H3> +<H3><a name="Python_nn6">32.2.2 Using distutils</a></H3> <p> -The preferred approach to building an extension module for python is to compile it with -distutils, which comes with all recent versions of python -(<a href="https://docs.python.org/library/distutils.html">Distutils Docs</a>). +The preferred approach to building an extension module for Python is to compile it with +distutils, which comes with all recent versions of Python +(<a href="https://docs.python.org/3/library/distutils.html">Distutils Docs</a>). </p> <p> @@ -300,7 +310,7 @@ flags, headers, etc. for the version of Python it is run with. Distutils will co extension into a shared object file or DLL (<tt>.so</tt> on Linux, <tt>.pyd</tt> on Windows, etc). In addition, distutils can handle installing your package into site-packages, if that is desired. A configuration file (conventionally called: <tt>setup.py</tt>) -describes the extension (and related python modules). The distutils will +describes the extension (and related Python modules). The distutils will then generate all the right compiler directives to build it for you. </p> @@ -337,9 +347,9 @@ setup (name = 'example', In this example, the line: <tt>example_module = Extension(....)</tt> creates an Extension module object, defining the name as <tt>_example</tt>, and using the source code files: <tt>example_wrap.c</tt>, generated by swig, and <tt>example.c</tt>, your original c -source. The swig (and other python extension modules) tradition is for the compiled -extension to have the name of the python portion, prefixed by an underscore. If the name -of your python module is "<tt>example.py</tt>", then the name of the corresponding object file +source. The swig (and other Python extension modules) tradition is for the compiled +extension to have the name of the Python portion, prefixed by an underscore. If the name +of your Python module is "<tt>example.py</tt>", then the name of the corresponding object file will be"<tt>_example.so</tt>" </p> @@ -356,11 +366,11 @@ $ python setup.py build_ext --inplace <p> And a .so, or .pyd or... will be created for you. It will build a version that matches the -python that you run the command with. Taking apart the command line: +Python that you run the command with. Taking apart the command line: </p> <ul> -<li> <tt>python</tt> -- the version of python you want to build for +<li> <tt>python</tt> -- the version of Python you want to build for <li> <tt>setup.py</tt> -- the name of your setup script (it can be called anything, but setup.py is the tradition) <li> <tt>build_ext</tt> -- telling distutils to build extensions @@ -369,7 +379,7 @@ python that you run the command with. Taking apart the command line: </ul> <p> -The distutils have many other features, consult the python distutils docs for details. +The distutils have many other features, consult the Python distutils docs for details. </p> <p> @@ -377,7 +387,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">36.2.3 Hand compiling a dynamic module</a></H3> +<H3><a name="Python_nn7">32.2.3 Hand compiling a dynamic module</a></H3> <p> @@ -395,9 +405,9 @@ $ gcc -shared example.o example_wrap.o -o _example.so </pre></div> <p> -The exact commands for doing this vary from platform to platform. -However, SWIG tries to guess the right options when it is installed. Therefore, -you may want to start with one of the examples in the <tt>SWIG/Examples/python</tt> +The exact commands for doing this vary from platform to platform. +However, SWIG tries to guess the right options when it is installed. Therefore, +you may want to start with one of the examples in the <tt>SWIG/Examples/python</tt> directory. If that doesn't work, you will need to read the man-pages for your compiler and linker to get the right set of options. You might also check the <a href="https://github.com/swig/swig/wiki">SWIG Wiki</a> for @@ -409,7 +419,7 @@ When linking the module, <b>the name of the output file has to match the name of the module prefixed by an underscore</b>. If the name of your module is "<tt>example</tt>", then the 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 +The name of the module is specified using the <tt>%module</tt> directive or the <tt>-module</tt> command line option. </p> @@ -425,7 +435,7 @@ module actually consists of two files; <tt>socket.py</tt> and </p> -<H3><a name="Python_nn8">36.2.4 Static linking</a></H3> +<H3><a name="Python_nn8">32.2.4 Static linking</a></H3> <p> @@ -433,7 +443,7 @@ An alternative approach to dynamic linking is to rebuild the Python interpreter with your extension module added to it. In the past, this approach was sometimes necessary due to limitations in dynamic loading support on certain machines. However, the situation has improved greatly -over the last few years and you should not consider this approach +over the last few years and you should not consider this approach unless there is really no other option. </p> @@ -493,7 +503,7 @@ linking if possible. Some programmers may be inclined to use static linking in the interest of getting better performance. However, the performance gained by static linking tends to be rather minimal in most situations (and quite frankly not worth the extra -hassle in the opinion of this author). +hassle in the opinion of this author). </p> <p> @@ -504,7 +514,7 @@ If using static linking, you might want to rely on a different approach (perhaps using distutils). </p> -<H3><a name="Python_nn9">36.2.5 Using your module</a></H3> +<H3><a name="Python_nn9">32.2.5 Using your module</a></H3> <p> @@ -552,13 +562,13 @@ Another possible error is the following: Traceback (most recent call last): File "<stdin>", line 1, in ? ImportError: dynamic module does not define init function (init_example) ->>> +>>> </pre> </div> <p> -This error is almost always caused when a bad name is given to the shared object file. -For example, if you created a file <tt>example.so</tt> instead of <tt>_example.so</tt> you would +This error is almost always caused when a bad name is given to the shared object file. +For example, if you created a file <tt>example.so</tt> instead of <tt>_example.so</tt> you would get this error. Alternatively, this error could arise if the name of the module is inconsistent with the module name supplied with the <tt>%module</tt> directive. Double-check the interface to make sure the module name and the shared object @@ -584,7 +594,7 @@ This error usually indicates that you forgot to include some object files or libraries in the linking of the shared library file. Make sure you compile both the SWIG wrapper file and your original program into a shared library file. Make sure you pass all of the required libraries -to the linker. +to the linker. </p> <p> @@ -619,7 +629,7 @@ problem when you try to use your module: Traceback (most recent call last): File "<stdin>", line 1, in ? ImportError: libfoo.so: cannot open shared object file: No such file or directory ->>> +>>> </pre> </div> @@ -642,7 +652,7 @@ $ gcc -shared example.o example_wrap.o -L/home/beazley/projects/lib -lfoo \ <p> Alternatively, you can set the <tt>LD_LIBRARY_PATH</tt> environment variable to -include the directory with your shared libraries. +include the directory with your shared libraries. If setting <tt>LD_LIBRARY_PATH</tt>, be aware that setting this variable can introduce a noticeable performance impact on all other applications that you run. To set it only for Python, you might want to do this instead: @@ -661,7 +671,7 @@ system configuration (this requires root access and you will need to read the man pages). </p> -<H3><a name="Python_nn10">36.2.6 Compilation of C++ extensions</a></H3> +<H3><a name="Python_nn10">32.2.6 Compilation of C++ extensions</a></H3> <p> @@ -707,7 +717,7 @@ $ CC -G example.o example_wrap.o -L/opt/SUNWspro/lib -o _example.so -lCrun </pre></div> <p> -Of course, the extra libraries to use are completely non-portable---you will +Of course, the extra libraries to use are completely non-portable---you will probably need to do some experimentation. </p> @@ -715,8 +725,8 @@ probably need to do some experimentation. Sometimes people have suggested that it is necessary to relink the Python interpreter using the C++ compiler to make C++ extension modules work. In the experience of this author, this has never actually appeared to be -necessary. Relinking the interpreter with C++ really only includes the -special run-time libraries described above---as long as you link your extension +necessary. Relinking the interpreter with C++ really only includes the +special run-time libraries described above---as long as you link your extension modules with these libraries, it should not be necessary to rebuild Python. </p> @@ -753,14 +763,14 @@ 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">36.2.7 Compiling for 64-bit platforms</a></H3> +<H3><a name="Python_nn11">32.2.7 Compiling for 64-bit platforms</a></H3> <p> On platforms that support 64-bit applications (Solaris, Irix, etc.), special care is required when building extension modules. On these machines, 64-bit applications are compiled and linked using a different -set of compiler/linker options. In addition, it is not generally possible to mix +set of compiler/linker options. In addition, it is not generally possible to mix 32-bit and 64-bit code together in the same application. </p> @@ -786,11 +796,11 @@ careful about the libraries you link with or the library path you use. In general, a Linux distribution will have two set of libraries, one for native x86_64 programs (under /usr/lib64), and another for 32 bits compatibility (under /usr/lib). Also, the compiler options -m32 -and -m64 allow you to choose the desired binary format for your python +and -m64 allow you to choose the desired binary format for your Python extension. </p> -<H3><a name="Python_nn12">36.2.8 Building Python Extensions under Windows</a></H3> +<H3><a name="Python_nn12">32.2.8 Building Python extensions under Windows</a></H3> <p> @@ -802,6 +812,7 @@ are built with Visual Studio 2003), the standard <tt>python setup.py build</tt> should just work. </p> + <p> As of python2.5, the distutils support building extensions with MingGW out of the box. Following the instruction here: @@ -814,10 +825,10 @@ If you need to build it on your own, the following notes are provided: </p> <p> -You will need to create a DLL that can be loaded into the interpreter. +You will need to create a DLL that can be loaded into the interpreter. This section briefly describes the use of SWIG with Microsoft Visual C++. As a starting point, many of SWIG's examples include project -files (.dsp files) for Visual C++ 6. These can be opened by more +files (.dsp files) for Visual C++ 6. These can be opened by more recent versions of Visual Studio. You might want to take a quick look at these examples in addition to reading this section. @@ -852,12 +863,12 @@ settings, select the "Custom Build" option. "C++:Preprocessor". Add the include directories for your Python installation under "Additional include directories". -<li>Define the symbol __WIN32__ under preprocessor options. +<li>Define the symbol __WIN32__ under preprocessor options. <li>Finally, select the settings for the entire project and go to "Link Options". Add the Python library file to your link libraries. -For example "python21.lib". Also, set the name of the output file to -match the name of your Python module, ie. _example.pyd - Note that _example.dll also worked with Python-2.4 and earlier. +For example "python27.lib". Also, set the name of the output file to +match the name of your Python module, i.e. <tt>_example.pyd</tt> <li>Build your project. </ul> @@ -866,7 +877,7 @@ match the name of your Python module, ie. _example.pyd - Note that _example.dll If all went well, SWIG will be automatically invoked whenever you build your project. Any changes made to the interface file will result in SWIG being automatically executed to produce a new version of -the wrapper file. +the wrapper file. </p> <p> @@ -885,9 +896,9 @@ $ python <p> If you get an <tt>ImportError</tt> exception when importing the module, you may have forgotten to include additional library files when you built your module. -If you get an access violation or some kind of general protection fault -immediately upon import, you have a more serious problem. This -is often caused by linking your extension module against the wrong +If you get an access violation or some kind of general protection fault +immediately upon import, you have a more serious problem. This +is often caused by linking your extension module against the wrong set of Win32 debug or thread libraries. You will have to fiddle around with the build options of project to try and track this down. </p> @@ -919,7 +930,51 @@ SWIG Wiki</a>. </p> -<H2><a name="Python_nn13">36.3 A tour of basic C/C++ wrapping</a></H2> +<H3><a name="Python_commandline">32.2.9 Additional Python commandline options</a></H3> + + +<p> +The following table lists the additional commandline options available for the Python module. They can also be seen by using: +</p> + +<div class="code"><pre> +swig -python -help +</pre></div> + +<table summary="Python specific options"> +<tr> +<th>Python specific options</th> +</tr> + +<tr><td>-builtin </td><td>Create Python built-in types rather than proxy classes, for better performance</td></tr> +<tr><td>-castmode </td><td>Enable the casting mode, which allows implicit cast between types in Python</td></tr> +<tr><td>-debug-doxygen-parser </td><td>Display doxygen parser module debugging information</td></tr> +<tr><td>-debug-doxygen-translator </td><td>Display doxygen translator module debugging information</td></tr> +<tr><td>-dirvtable </td><td>Generate a pseudo virtual table for directors for faster dispatch</td></tr> +<tr><td>-doxygen </td><td>Convert C++ doxygen comments to pydoc comments in proxy classes</td></tr> +<tr><td>-extranative </td><td>Return extra native wrappers for C++ std containers wherever possible</td></tr> +<tr><td>-fastproxy </td><td>Use fast proxy mechanism for member methods</td></tr> +<tr><td>-globals <name> </td><td>Set <name> used to access C global variable (default: 'cvar')</td></tr> +<tr><td>-interface <mod></td><td>Set low-level C/C++ module name to <mod> (default: module name prefixed by '_')</td></tr> +<tr><td>-keyword </td><td>Use keyword arguments</td></tr> +<tr><td>-nofastunpack </td><td>Use traditional UnpackTuple method to parse the argument functions</td></tr> +<tr><td>-noh </td><td>Don't generate the output header file</td></tr> +<tr><td>-noproxy </td><td>Don't generate proxy classes</td></tr> +<tr><td>-nortti </td><td>Disable the use of the native C++ RTTI with directors</td></tr> +<tr><td>-nothreads </td><td>Disable thread support for the entire interface</td></tr> +<tr><td>-olddefs </td><td>Keep the old method definitions when using -fastproxy</td></tr> +<tr><td>-py3 </td><td>Generate code with Python 3 specific features and syntax</td></tr> +<tr><td>-relativeimport </td><td>Use relative Python imports</td></tr> +<tr><td>-threads </td><td>Add thread support for all the interface</td></tr> +<tr><td>-O </td><td>Enable the following optimization options: -fastdispatch -fastproxy -fvirtual</td></tr> + +</table> + +<p> +Many of these options are covered later on and their use should become clearer by the time you have finished reading this section on SWIG and Python. +</p> + +<H2><a name="Python_nn13">32.3 A tour of basic C/C++ wrapping</a></H2> <p> @@ -928,7 +983,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">36.3.1 Modules</a></H3> +<H3><a name="Python_nn14">32.3.1 Modules</a></H3> <p> @@ -938,10 +993,10 @@ wrapped into a Python '<tt>example</tt>' module. Underneath the covers, this module consists of a Python source file <tt>example.py</tt> and a low-level extension module <tt>_example.so</tt>. When choosing a module name, make sure you don't use the same name as a built-in -Python command or standard module name. +Python command or standard module name. </p> -<H3><a name="Python_nn15">36.3.2 Functions</a></H3> +<H3><a name="Python_nn15">32.3.2 Functions</a></H3> <p> @@ -965,7 +1020,7 @@ like you think it does: >>> </pre></div> -<H3><a name="Python_nn16">36.3.3 Global variables</a></H3> +<H3><a name="Python_nn16">32.3.3 Global variables</a></H3> <p> @@ -991,8 +1046,8 @@ then "a" and "b" are both names for the object containing the value 3.4. Thus, there is only one object containing 3.4 and "a" and "b" are both names that refer to it. This is quite different than C where a variable name refers to a memory location in which -a value is stored (and assignment copies data into that location). -Because of this, there is no direct way to map variable +a value is stored (and assignment copies data into that location). +Because of this, there is no direct way to map variable assignment in C to variable assignment in Python. </p> @@ -1038,7 +1093,7 @@ error message. For example: Traceback (most recent call last): File "<stdin>", line 1, in ? TypeError: C variable 'density (double )' ->>> +>>> </pre></div> <p> @@ -1103,7 +1158,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">36.3.4 Constants and enums</a></H3> +<H3><a name="Python_nn17">32.3.4 Constants and enums</a></H3> <p> @@ -1143,7 +1198,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">36.3.5 Pointers</a></H3> +<H3><a name="Python_nn18">32.3.5 Pointers</a></H3> <p> @@ -1178,7 +1233,7 @@ When wrapped, you will be able to use the functions in a natural way from Python <p> If this makes you uneasy, rest assured that there is no deep magic involved. Underneath the covers, pointers to C/C++ objects are -simply represented as opaque values using an especial python container object: +simply represented as opaque values using an especial Python container object: </p> <div class="targetlang"><pre> @@ -1188,7 +1243,7 @@ simply represented as opaque values using an especial python container object: <p> This pointer value can be freely passed around to different C functions that -expect to receive an object of type <tt>FILE *</tt>. The only thing you can't do is +expect to receive an object of type <tt>FILE *</tt>. The only thing you can't do is dereference the pointer from Python. Of course, that isn't much of a concern in this example. </p> @@ -1206,7 +1261,7 @@ _c0671108_p_FILE <p> Also, if you need to pass the raw pointer value to some external -python library, you can do it by casting the pointer object to an +Python library, you can do it by casting the pointer object to an integer: </p> @@ -1271,7 +1326,7 @@ Foo *BarToFoo(Bar *b) { } Foo *IncrFoo(Foo *f, int i) { - return f+i; + return f+i; } %} </pre> @@ -1284,7 +1339,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">36.3.6 Structures</a></H3> +<H3><a name="Python_nn19">32.3.6 Structures</a></H3> <p> @@ -1308,8 +1363,8 @@ is used as follows: >>> v.x = 3.5 >>> v.y = 7.2 >>> print v.x, v.y, v.z -7.8 -4.5 0.0 ->>> +3.5 7.2 0.0 +>>> </pre></div> <p> @@ -1368,7 +1423,7 @@ struct Foo { <p> When <tt>char *</tt> members of a structure are wrapped, the contents are assumed to be dynamically allocated using <tt>malloc</tt> or <tt>new</tt> (depending on whether or not -SWIG is run with the -c++ option). When the structure member is set, the old contents will be +SWIG is run with the -c++ option). When the structure member is set, the old contents will be released and a new value created. If this is not the behavior you want, you will have to use a typemap (described later). </p> @@ -1381,7 +1436,7 @@ example, consider this: <div class="code"> <pre> struct Bar { - int x[16]; + int x[16]; }; </pre> </div> @@ -1395,7 +1450,7 @@ If accessed in Python, you will see behavior like this: >>> b = example.Bar() >>> print b.x _801861a4_p_int ->>> +>>> </pre> </div> @@ -1460,7 +1515,7 @@ Foo *x = &b->f; /* Points inside b */ </div> <p> -Because the pointer points inside the structure, you can modify the contents and +Because the pointer points inside the structure, you can modify the contents and everything works just like you would expect. For example: </p> @@ -1468,12 +1523,33 @@ everything works just like you would expect. For example: <pre> >>> b = Bar() >>> b.f.a = 3 # Modify attribute of structure member ->>> x = b.f +>>> x = b.f >>> x.a = 3 # Modifies the same structure </pre> </div> -<H3><a name="Python_nn20">36.3.7 C++ classes</a></H3> +<p> +Note that there is a limitation with structs within structs that will cause a problem +if the outer struct is not a named variable in Python. The following will cause a segfault: +</p> + +<div class="targetlang"> +<pre> +Bar().f.a = 3 +</pre> +</div> + +<p> +because the unnamed Python proxy class for <tt>Bar()</tt> has its reference count +decremented by the Python interpreter after <tt>f</tt> has been obtained from it and +before <tt>f</tt> is used to obtain <tt>a</tt>. +This results in the underlying <tt>Bar</tt> instance being deleted, which of course also deletes +<tt>f</tt> inside it. Hence the pointer to <tt>f</tt> points to deleted +memory and use of it results in a segfault or some sort of other undefined behaviour. +</p> + + +<H3><a name="Python_nn20">32.3.7 C++ classes</a></H3> <p> @@ -1510,13 +1586,13 @@ you can use it in Python like this: </pre></div> <p> -Class data members are accessed in the same manner as C structures. +Class data members are accessed in the same manner as C structures. </p> <p> -Static class members present a special problem for Python. Prior to Python-2.2, +Static class members present a special problem for Python. Prior to Python-2.2, Python classes had no support for static methods and no version of Python -supports static member variables in a manner that SWIG can utilize. Therefore, +supports static member variables in a manner that SWIG can utilize. Therefore, SWIG generates wrappers that try to work around some of these issues. To illustrate, suppose you have a class like this: </p> @@ -1561,7 +1637,7 @@ they are accessed through <tt>cvar</tt> like this: </pre> </div> -<H3><a name="Python_nn21">36.3.8 C++ inheritance</a></H3> +<H3><a name="Python_nn21">32.3.8 C++ inheritance</a></H3> <p> @@ -1616,7 +1692,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">36.3.9 Pointers, references, values, and arrays</a></H3> +<H3><a name="Python_nn22">32.3.9 Pointers, references, values, and arrays</a></H3> <p> @@ -1669,15 +1745,15 @@ const Foo &spam9(); <p> then all three functions will return a pointer to some <tt>Foo</tt> object. -Since the third function (spam8) returns a value, newly allocated memory is used -to hold the result and a pointer is returned (Python will release this memory +Since the third function (spam8) returns a value, newly allocated memory is used +to hold the result and a pointer is returned (Python will release this memory when the return value is garbage collected). The fourth case (spam9) -which returns a const reference, in most of the cases will be +which returns a const reference, in most of the cases will be treated as a returning value, and it will follow the same allocation/deallocation process. </p> -<H3><a name="Python_nn23">36.3.10 C++ overloaded functions</a></H3> +<H3><a name="Python_nn23">32.3.10 C++ overloaded functions</a></H3> <p> @@ -1711,9 +1787,9 @@ Similarly, if you have a class like this, <pre> class Foo { public: - Foo(); - Foo(const Foo &); - ... + Foo(); + Foo(const Foo &); + ... }; </pre> </div> @@ -1771,7 +1847,7 @@ To fix this, you either need to ignore or rename one of the methods. For exampl <pre> %rename(spam_short) spam(short); ... -void spam(int); +void spam(int); void spam(short); // Accessed as spam_short </pre> </div> @@ -1784,7 +1860,7 @@ or <pre> %ignore spam(short); ... -void spam(int); +void spam(int); void spam(short); // Ignored </pre> </div> @@ -1797,10 +1873,10 @@ first declaration takes precedence. </p> <p> -Please refer to the "SWIG and C++" chapter for more information about overloading. +Please refer to the "SWIG and C++" chapter for more information about overloading. </p> -<H3><a name="Python_nn24">36.3.11 C++ operators</a></H3> +<H3><a name="Python_nn24">32.3.11 C++ operators</a></H3> <p> @@ -1823,7 +1899,7 @@ public: Complex operator-(const Complex &c) const; Complex operator*(const Complex &c) const; Complex operator-() const; - + double re() const { return rpart; } double im() const { return ipart; } }; @@ -1889,7 +1965,15 @@ 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">36.3.12 C++ namespaces</a></H3> +<p> +Operator overloading is implemented in the <tt>pyopers.swg</tt> library file. +In particular overloaded operators are marked with the <tt>python:maybecall</tt> feature, also known as <tt>%pythonmaybecall</tt>. +This feature forces SWIG to generate code that return an instance of Python's <tt>NotImplemented</tt> +instead of raising an exception when the comparison fails, that is, on any kind of error. +This follows the guidelines in <a href="https://www.python.org/dev/peps/pep-0207/">PEP 207 - Rich Comparisons</a> and <a href="https://docs.python.org/3/library/constants.html#NotImplemented">NotImplemented Python constant</a>. +</p> + +<H3><a name="Python_nn25">32.3.12 C++ namespaces</a></H3> <p> @@ -1938,11 +2022,11 @@ For example: %rename(Bar_spam) Bar::spam; namespace Foo { - int spam(); + int spam(); } namespace Bar { - int spam(); + int spam(); } </pre> </div> @@ -1956,7 +2040,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">36.3.13 C++ templates</a></H3> +<H3><a name="Python_nn26">32.3.13 C++ templates</a></H3> <p> @@ -2005,15 +2089,15 @@ In Python: <p> Obviously, there is more to template wrapping than shown in this example. -More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a> chapter. +More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a> chapter. Some more complicated examples will appear later. </p> -<H3><a name="Python_nn27">36.3.14 C++ Smart Pointers</a></H3> +<H3><a name="Python_nn27">32.3.14 C++ Smart Pointers</a></H3> -<H4><a name="Python_smart_pointers_shared_ptr">36.3.14.1 The shared_ptr Smart Pointer</a></H4> +<H4><a name="Python_smart_pointers_shared_ptr">32.3.14.1 The shared_ptr Smart Pointer</a></H4> <p> @@ -2024,7 +2108,7 @@ in the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a </p> -<H4><a name="Python_smart_pointers_generic">36.3.14.2 Generic Smart Pointers</a></H4> +<H4><a name="Python_smart_pointers_generic">32.3.14.2 Generic Smart Pointers</a></H4> <p> @@ -2108,7 +2192,7 @@ simply use the <tt>__deref__()</tt> method. For example: </pre> </div> -<H3><a name="Python_nn27a">36.3.15 C++ reference counted objects</a></H3> +<H3><a name="Python_nn27a">32.3.15 C++ reference counted objects</a></H3> <p> @@ -2117,7 +2201,7 @@ Python examples of memory management using referencing counting. </p> -<H2><a name="Python_nn28">36.4 Further details on the Python class interface</a></H2> +<H2><a name="Python_nn28">32.4 Further details on the Python class interface</a></H2> <p> @@ -2140,7 +2224,7 @@ the <tt>-builtin</tt> option are in the <a href="#Python_builtin_types">Built-in section. </p> -<H3><a name="Python_nn29">36.4.1 Proxy classes</a></H3> +<H3><a name="Python_nn29">32.4.1 Proxy classes</a></H3> <p> @@ -2153,9 +2237,9 @@ have a class like this <pre> class Foo { public: - int x; - int spam(int); - ... + int x; + int spam(int); + ... </pre> </div> @@ -2166,19 +2250,19 @@ then SWIG transforms it into a set of low-level procedural wrappers. For example <div class="code"> <pre> Foo *new_Foo() { - return new Foo(); + return new Foo(); } void delete_Foo(Foo *f) { - delete f; + delete f; } int Foo_x_get(Foo *f) { - return f->x; + return f->x; } void Foo_x_set(Foo *f, int value) { - f->x = value; + f->x = value; } int Foo_spam(Foo *f, int arg1) { - return f->spam(arg1); + return f->spam(arg1); } </pre> </div> @@ -2188,7 +2272,7 @@ These wrappers can be found in the low-level extension module (e.g., <tt>_exampl </p> <p> -Using these wrappers, SWIG generates a high-level Python proxy class (also known as a shadow class) like this (shown +Using these wrappers, SWIG generates a high-level Python proxy class (also known as a shadow class) like this (shown for Python 2.2): </p> @@ -2210,7 +2294,7 @@ class Foo(object): </div> <p> -This class merely holds a pointer to the underlying C++ object (<tt>.this</tt>) and dispatches methods and +This class merely holds a pointer to the underlying C++ object (<tt>.this</tt>) and dispatches methods and member variable access to that object using the low-level accessor functions. From a user's point of view, it makes the class work normally: </p> @@ -2229,7 +2313,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">36.4.2 Built-in Types</a></H3> +<H3><a name="Python_builtin_types">32.4.2 Built-in Types</a></H3> <p> @@ -2239,8 +2323,8 @@ and built-in types, let's take a look at what a wrapped object looks like under both circumstances. </p> -<p>When proxy classes are used, each wrapped object in python is an instance -of a pure python class. As a reminder, here is what the <tt>__init__</tt> method looks +<p>When proxy classes are used, each wrapped object in Python is an instance +of a pure Python class. As a reminder, here is what the <tt>__init__</tt> method looks like in a proxy class: </p> @@ -2254,37 +2338,30 @@ class Foo(object): </div> <p>When a <tt>Foo</tt> instance is created, the call to <tt>_example.new_Foo()</tt> -creates a new C++ <tt>Foo</tt> instance; wraps that C++ instance inside an instance of -a python built-in type called <tt>SwigPyObject</tt>; and stores the <tt>SwigPyObject</tt> -instance in the 'this' field of the python Foo object. Did you get all that? So, the -python <tt>Foo</tt> object is composed of three parts:</p> +creates a new C++ <tt>Foo</tt> instance; wraps that C++ instance inside an instance of +a Python built-in type called <tt>SwigPyObject</tt>; and stores the <tt>SwigPyObject</tt> +instance in the 'this' field of the Python Foo object. Did you get all that? So, the +Python <tt>Foo</tt> object is composed of three parts:</p> <ul> -<li> The python <tt>Foo</tt> instance, which contains...</li> +<li> The Python <tt>Foo</tt> instance, which contains...</li> <li> ... an instance of <tt>struct SwigPyObject</tt>, which contains...</li> <li> ... a C++ <tt>Foo</tt> instance</li> </ul> -<p>When <tt>-builtin</tt> is used, the pure python layer is stripped off. Each -wrapped class is turned into a new python built-in type which inherits from +<p>When <tt>-builtin</tt> is used, the pure Python layer is stripped off. Each +wrapped class is turned into a new Python built-in type which inherits from <tt>SwigPyObject</tt>, and <tt>SwigPyObject</tt> instances are returned directly -from the wrapped methods. For more information about python built-in extensions, -please refer to the python documentation:</p> +from the wrapped methods. For more information about Python built-in extensions, +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> +<p><a href="https://docs.python.org/3/extending/newtypes.html">https://docs.python.org/3/extending/newtypes.html</a></p> -<H4><a name="Python_builtin_limitations">36.4.2.1 Limitations</a></H4> +<H4><a name="Python_builtin_limitations">32.4.2.1 Limitations</a></H4> <p>Use of the <tt>-builtin</tt> option implies a couple of limitations: <ul> - <li><p>python version support:</p> - <ul> - <li>Versions 2.5 and up are fully supported</li> - <li>Versions 2.3 and 2.4 are mostly supported; there are problems with director classes and/or sub-classing a wrapped type in python.</li> - <li>Versions older than 2.3 are not supported.</li> - </ul> - </li> <li><p>Some legacy syntax is no longer supported; in particular:</p> <ul> <li>The functional interface is no longer exposed. For example, you may no longer call <tt>Whizzo.new_CrunchyFrog()</tt>. Instead, you must use <tt>Whizzo.CrunchyFrog()</tt>.</li> @@ -2292,15 +2369,15 @@ please refer to the python documentation:</p> They are instead accessed in the idiomatic way (<tt>Dances.FishSlap</tt>).</li> </ul> </li> - <li><p>Wrapped types may not be raised as python exceptions. Here's why: the python internals expect that all sub-classes of Exception will have this struct layout:</p> + <li><p>Wrapped types may not be raised as Python exceptions. Here's why: the Python internals expect that all sub-classes of Exception will have this struct layout:</p> <div class="code"> <pre> typedef struct { - PyObject_HEAD - PyObject *dict; - PyObject *args; - PyObject *message; + PyObject_HEAD + PyObject *dict; + PyObject *args; + PyObject *message; } PyBaseExceptionObject; </pre> </div> @@ -2310,12 +2387,12 @@ typedef struct { <div class="code"> <pre> typedef struct { - PyObject_HEAD - void *ptr; - swig_type_info *ty; - int own; - PyObject *next; - PyObject *dict; + PyObject_HEAD + void *ptr; + swig_type_info *ty; + int own; + PyObject *next; + PyObject *dict; } SwigPyObject; </pre> </div> @@ -2326,18 +2403,18 @@ typedef struct { <pre> class MyException { public: - MyException (const char *msg_); - ~MyException (); + MyException (const char *msg_); + ~MyException (); - const char *what () const; + const char *what () const; private: - char *msg; + char *msg; }; </pre> </div> -<p>... you can define this python class, which may be raised as an exception:</p> +<p>... you can define this Python class, which may be raised as an exception:</p> <div class="targetlang"> <pre> @@ -2352,22 +2429,22 @@ class MyPyException(Exception): </li> <li><p>Reverse binary operators (e.g., <tt>__radd__</tt>) are not supported.</p> <p>To illustrate this point, if you have a wrapped class called <tt>MyString</tt>, -and you want to use instances of <tt>MyString</tt> interchangeably with native python +and you want to use instances of <tt>MyString</tt> interchangeably with native Python strings, you can define an <tt>'operator+ (const char*)'</tt> method :</p> <div class="code"> <pre> class MyString { public: - MyString (const char *init); - MyString operator+ (const char *other) const; - ... + MyString (const char *init); + MyString operator+ (const char *other) const; + ... }; </pre> </div> <p> -SWIG will automatically create an operator overload in python that will allow this: +SWIG will automatically create an operator overload in Python that will allow this: </p> <div class="targetlang"> @@ -2394,7 +2471,7 @@ episode = "Dead " + mystr </div> <p> -The above code fails, because the first operand -- a native python string -- +The above code fails, because the first operand -- a native Python string -- doesn't know how to add an instance of <tt>MyString</tt> to itself. </p> </li> @@ -2430,7 +2507,7 @@ class Derived : public Base { <p>The <tt>import "A.i"</tt> statement is required, because module <tt>B</tt> depends on module <tt>A</tt>.</p> -<p>As long as you obey these requirements, your python code may import the modules in any order :</p> +<p>As long as you obey these requirements, your Python code may import the modules in any order :</p> <div class="targetlang"><pre> import B @@ -2441,35 +2518,36 @@ assert(issubclass(B.Derived, A.Base)) </li> </ul> -<H4><a name="Python_builtin_overloads">36.4.2.2 Operator overloads and slots -- use them!</a></H4> +<H4><a name="Python_builtin_overloads">32.4.2.2 Operator overloads and slots -- use them!</a></H4> <p>The entire justification for the <tt>-builtin</tt> option is improved performance. To that end, the best way to squeeze maximum performance out of your wrappers is to <b>use operator overloads.</b> -Named method dispatch is slow in python, even when compared to other scripting languages. -However, python built-in types have a large number of "slots", +Named method dispatch is slow in Python, even when compared to other scripting languages. +However, Python built-in types have a large number of "slots", analogous to C++ operator overloads, which allow you to short-circuit named method dispatch for certain common operations. </p> -<p>By default, SWIG will translate most C++ arithmetic operator overloads into python +<p>By default, SWIG will translate most C++ arithmetic operator overloads into Python slot entries. For example, suppose you have this class: <div class="code"> <pre> class Twit { public: - Twit operator+ (const Twit& twit) const; + Twit operator+ (const Twit& twit) const; - // Forward to operator+ - Twit add (const Twit& twit) const - { return *this + twit; } + // Forward to operator+ + Twit add (const Twit& twit) const { + return *this + twit; + } }; </pre> </div> -<p>SWIG will automatically register <tt>operator+</tt> as a python slot operator for addition. You may write python code like this:</p> +<p>SWIG will automatically register <tt>operator+</tt> as a Python slot operator for addition. You may write Python code like this:</p> <div class="targetlang"> <pre> @@ -2482,24 +2560,24 @@ percival = nigel.add(emily) </pre> </div> -<p>The last two lines of the python code are equivalent, +<p>The last two lines of the Python code are equivalent, but <b>the line that uses the '+' operator is much faster</b>. </p> <p>In-place operators (e.g., <tt>operator+=</tt>) and comparison operators -(<tt>operator==, operator<</tt>, etc.) are also converted to python +(<tt>operator==, operator<</tt>, etc.) are also converted to Python slot operators. For a complete list of C++ operators that are -automatically converted to python slot operators, refer to the file +automatically converted to Python slot operators, refer to the file <tt>python/pyopers.swig</tt> in the SWIG library. </p> <p> -Read about all of the available python slots here: -<a href="http://docs.python.org/c-api/typeobj.html">http://docs.python.org/c-api/typeobj.html</a></p> +Read about all of the available Python slots here: +<a href="https://docs.python.org/3/c-api/typeobj.html">https://docs.python.org/3/c-api/typeobj.html</a></p> <p> -There are two ways to define a python slot function: dispatch to a +There are two ways to define a Python slot function: dispatch to a statically defined function; or dispatch to a method defined on the operand. </p> @@ -2545,16 +2623,16 @@ public: </div> <p> -If you examine the generated code, the supplied hash function will now be +If you examine the generated code, the supplied hash function will now be the function callback in the tp_hash slot for the builtin type for <tt>MyClass</tt>: </p> <div class="code"> <pre> static PyHeapTypeObject SwigPyBuiltin__MyClass_type = { - ... - (hashfunc) myHashFunc, /* tp_hash */ - ... + ... + (hashfunc) myHashFunc, /* tp_hash */ + ... </pre> </div> @@ -2586,7 +2664,7 @@ class MyClass { </div> <p> -NOTE: Some python slots use a method signature which does not +NOTE: Some Python slots use a method signature which does not match the signature of SWIG-wrapped methods. For those slots, SWIG will automatically generate a "closure" function to re-marshal the arguments before dispatching to the wrapped method. Setting @@ -2600,7 +2678,7 @@ in the file <tt>python/pyopers.swig</tt> in the SWIG library. </p> -<H3><a name="Python_nn30">36.4.3 Memory management</a></H3> +<H3><a name="Python_nn30">32.4.3 Memory management</a></H3> <p>NOTE: Although this section refers to proxy objects, everything here also applies @@ -2609,7 +2687,7 @@ when the <tt>-builtin</tt> option is used.</p> <p> Associated with proxy object, is an ownership flag <tt>.thisown</tt> The value of this flag determines who is responsible for deleting the underlying C++ object. If set to 1, -the Python interpreter will destroy the C++ object when the proxy class is +the Python interpreter will destroy the C++ object when the proxy class is garbage collected. If set to 0 (or if the attribute is missing), then the destruction of the proxy class has no effect on the C++ object. </p> @@ -2623,8 +2701,8 @@ ownership of the result. For example: <pre> class Foo { public: - Foo(); - Foo bar(); + Foo(); + Foo bar(); }; </pre> </div> @@ -2653,9 +2731,9 @@ they came from. Therefore, the ownership is set to zero. For example: <pre> class Foo { public: - ... - Foo *spam(); - ... + ... + Foo *spam(); + ... }; </pre> </div> @@ -2694,8 +2772,8 @@ or global variable. For example, consider this interface: %module example struct Foo { - int value; - Foo *next; + int value; + Foo *next; }; Foo *head = 0; @@ -2712,7 +2790,7 @@ is assigned to a global variable. For example: >>> f = example.Foo() >>> f.thisown 1 ->>> example.cvar.head = f +>>> example.cvar.head = f >>> f.thisown 0 >>> @@ -2795,44 +2873,7 @@ It is also possible to deal with situations like this using typemaps--an advanced topic discussed later. </p> -<H3><a name="Python_nn31">36.4.4 Python 2.2 and classic classes</a></H3> - - -<p> -SWIG makes every attempt to preserve backwards compatibility with -older versions of Python to the extent that it is possible. However, -in Python-2.2, an entirely new type of class system was introduced. -This new-style class system offers many enhancements including static -member functions, properties (managed attributes), and class methods. -Details about all of these changes can be found on <a -href="https://www.python.org">www.python.org</a> and is not repeated here. -</p> - -<p> -To address differences between Python versions, SWIG currently emits -dual-mode proxy class wrappers. In Python-2.2 and newer releases, -these wrappers encapsulate C++ objects in new-style classes that take -advantage of new features (static methods and properties). However, -if these very same wrappers are imported into an older version of Python, -old-style classes are used instead. -</p> - -<p> -This dual-nature of the wrapper code means that you can create extension -modules with SWIG and those modules will work with all versions of Python -ranging from Python-2.0 to the very latest release. Moreover, the wrappers take -advantage of Python-2.2 features when available. -</p> - -<p> -For the most part, the interface presented to users is the same regardless -of what version of Python is used. The only incompatibility lies in the handling -of static member functions. In Python-2.2, they can be accessed via the -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">36.5 Cross language polymorphism</a></H2> +<H2><a name="Python_directors">32.5 Cross language polymorphism</a></H2> <p> @@ -2866,7 +2907,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">36.5.1 Enabling directors</a></H3> +<H3><a name="Python_nn33">32.5.1 Enabling directors</a></H3> <p> @@ -2883,18 +2924,18 @@ option to the %module directive, like this: <p> Without this option no director code will be generated. Second, you -must use the %feature("director") directive to tell SWIG which classes -and methods should get directors. The %feature directive can be applied +must use the %feature("director") directive to tell SWIG which classes +and methods should get directors. The %feature directive can be applied globally, to specific classes, and to specific methods, like this: </p> <div class="code"> <pre> // generate directors for all classes that have virtual methods -%feature("director"); +%feature("director"); -// generate directors for all virtual methods in class Foo -%feature("director") Foo; +// generate directors for the virtual methods in class Foo +%feature("director") Foo; </pre> </div> @@ -2911,12 +2952,12 @@ directors for specific classes or methods. So for example, </div> <p> -will generate directors for all virtual methods of class Foo except -bar(). +will generate directors for the virtual methods of class Foo except +bar(). </p> <p> -Directors can also be generated implicitly through inheritance. +Directors can also be generated implicitly through inheritance. In the following, class Bar will get a director class that handles the methods one() and two() (but not three()): </p> @@ -2926,21 +2967,21 @@ the methods one() and two() (but not three()): %feature("director") Foo; class Foo { public: - Foo(int foo); - virtual ~Foo(); - virtual void one(); - virtual void two(); + Foo(int foo); + virtual ~Foo(); + virtual void one(); + virtual void two(); }; class Bar: public Foo { public: - virtual void three(); + virtual void three(); }; </pre> </div> <p> -then at the python side you can define +then at the Python side you can define </p> <div class="targetlang"> @@ -2953,15 +2994,12 @@ class MyFoo(mymodule.Foo): # super().__init__(foo) # Alternative construction for Python3 def one(self): - print "one from python" + print "one from Python" </pre> </div> -<H3><a name="Python_nn34">36.5.2 Director classes</a></H3> - - - +<H3><a name="Python_nn34">32.5.2 Director classes</a></H3> <p> @@ -2980,7 +3018,8 @@ For simplicity let's ignore the <tt>Swig::Director</tt> class and refer to the original C++ class as the director's base class. By default, a director class extends all virtual methods in the inheritance chain of its base class (see the preceding section for how to modify this behavior). -Thus all virtual method calls, whether they originate in C++ or in +Virtual methods that have a final specifier are unsurprisingly excluded. +Thus the virtual method calls, whether they originate in C++ or in Python via proxy classes, eventually end up in at the implementation in the director class. The job of the director methods is to route these method calls to the appropriate place in the inheritance chain. By @@ -3040,7 +3079,7 @@ so there is no need for the extra overhead involved with routing the calls through Python. </p> -<H3><a name="Python_nn35">36.5.3 Ownership and object destruction</a></H3> +<H3><a name="Python_nn35">32.5.3 Ownership and object destruction</a></H3> <p> @@ -3077,12 +3116,12 @@ references. Here is an example: <pre> class Foo { public: - ... + ... }; class FooContainer { public: - void addFoo(Foo *); - ... + void addFoo(Foo *); + ... }; </pre> </div> @@ -3107,7 +3146,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">36.5.4 Exception unrolling</a></H3> +<H3><a name="Python_nn36">32.5.4 Exception unrolling</a></H3> <p> @@ -3123,9 +3162,9 @@ suffice in most cases: <div class="code"> <pre> %feature("director:except") { - if ($error != NULL) { - throw Swig::DirectorMethodException(); - } + if ($error != NULL) { + throw Swig::DirectorMethodException(); + } } </pre> </div> @@ -3152,8 +3191,8 @@ suitable exception handler: <div class="code"> <pre> %exception { - try { $action } - catch (Swig::DirectorException &e) { SWIG_fail; } + try { $action } + catch (Swig::DirectorException &e) { SWIG_fail; } } </pre> </div> @@ -3166,7 +3205,7 @@ Swig::DirectorMethodException is thrown, Python will register the exception as soon as the C wrapper function returns. </p> -<H3><a name="Python_nn37">36.5.5 Overhead and code bloat</a></H3> +<H3><a name="Python_nn37">32.5.5 Overhead and code bloat</a></H3> <p> @@ -3200,7 +3239,7 @@ directive) for only those methods that are likely to be extended in Python. </p> -<H3><a name="Python_nn38">36.5.6 Typemaps</a></H3> +<H3><a name="Python_nn38">32.5.6 Typemaps</a></H3> <p> @@ -3214,7 +3253,7 @@ need to be supported. </p> -<H3><a name="Python_nn39">36.5.7 Miscellaneous</a></H3> +<H3><a name="Python_nn39">32.5.7 Miscellaneous</a></H3> <p> @@ -3224,13 +3263,13 @@ be able to use std::vector, std::string, etc., as you would any other type. <p> <b>Note:</b> The director typemaps for return types based in const -references, such as +references, such as <div class="code"> <pre> class Foo { … - virtual const int& bar(); + virtual const int& bar(); … }; </pre> @@ -3248,7 +3287,7 @@ types, wherever possible, for example <pre> class Foo { … - virtual int bar(); + virtual int bar(); … }; </pre> @@ -3261,7 +3300,7 @@ methods that return const references. </p> -<H2><a name="Python_nn40">36.6 Common customization features</a></H2> +<H2><a name="Python_nn40">32.6 Common customization features</a></H2> <p> @@ -3274,7 +3313,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">36.6.1 C/C++ helper functions</a></H3> +<H3><a name="Python_nn41">32.6.1 C/C++ helper functions</a></H3> <p> @@ -3355,7 +3394,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">36.6.2 Adding additional Python code</a></H3> +<H3><a name="Python_nn42">32.6.2 Adding additional Python code</a></H3> <p> @@ -3420,7 +3459,9 @@ statements. </p> <p> -The following shows example usage for Python 2.6 to use <tt>print</tt> as it can in Python 3, that is, as a function instead of a statement: +The following example for Python 2.x shows how to insert code into the +generated wrapper to enable <tt>print</tt> to be used as a Python3-compatible +function instead of a statement: </p> <div class="code"> @@ -3437,13 +3478,13 @@ print("Loading", "Whizz", "Bang", sep=' ... ') </div> <p> -which can be seen when viewing the first few lines of the generated <tt>.py</tt> file: +The insert code can be seen at the start of the generated <tt>.py</tt> file: </p> <div class="code"> <pre> # This file was automatically generated by SWIG (http://www.swig.org). -# Version 2.0.11 +# Version 4.0.0 # # Do not make changes to this file unless you know what you are doing--modify # the SWIG interface file instead. @@ -3469,7 +3510,7 @@ an error for invalid preprocessor directives, so you may have to update existing interface files to delimit blocks of Python code correctly.</p> <p>As an alternative to providing a block containing Python code, you can -include python code from a file. The code is inserted exactly as in the +include Python code from a file. The code is inserted exactly as in the file, so this avoids any issues with the SWIG preprocessor. It's a good approach if you have a non-trivial chunk of Python code to insert. To use this feature you specify a filename in double quotes, for example:</p> @@ -3490,7 +3531,7 @@ entirely replace a proxy function you can use <pre> %module example -// Rewrite bar() python code +// Rewrite bar() Python code %feature("shadow") Foo::bar(int) %{ def bar(*args): @@ -3498,16 +3539,16 @@ def bar(*args): $action #do something after %} - + class Foo { public: - int bar(int x); + int bar(int x); }; </pre> </div> <p> where <tt>$action</tt> will be replaced by the call to -the C/C++ proper method. +the C/C++ proper method. </p> <p> @@ -3525,7 +3566,7 @@ proxy, just before the return statement. <pre> %module example -// Add python code to bar() +// Add Python code to bar() %feature("pythonprepend") Foo::bar(int) %{ #do something before C++ call @@ -3533,12 +3574,13 @@ proxy, just before the return statement. %feature("pythonappend") Foo::bar(int) %{ #do something after C++ call + #the 'val' variable holds the return value %} - + class Foo { public: - int bar(int x); + int bar(int x); }; </pre> </div> @@ -3554,7 +3596,7 @@ SWIG version 1.3.28 you can use the directive forms <pre> %module example -// Add python code to bar() +// Add Python code to bar() %pythonprepend Foo::bar(int) %{ #do something before C++ call @@ -3562,12 +3604,13 @@ SWIG version 1.3.28 you can use the directive forms %pythonappend Foo::bar(int) %{ #do something after C++ call + #the 'val' variable holds the return value %} - + class Foo { public: - int bar(int x); + int bar(int x); }; </pre> </div> @@ -3583,7 +3626,7 @@ as it will then get attached to all the overloaded C++ methods. For example: <pre> %module example -// Add python code to bar() +// Add Python code to bar() %pythonprepend Foo::bar %{ #do something before C++ call @@ -3596,8 +3639,8 @@ as it will then get attached to all the overloaded C++ methods. For example: class Foo { public: - int bar(int x); - int bar(); + int bar(int x); + int bar(); }; </pre> </div> @@ -3607,7 +3650,7 @@ The same applies for overloaded constructors. </p> -<H3><a name="Python_nn43">36.6.3 Class extension with %extend</a></H3> +<H3><a name="Python_nn43">32.6.3 Class extension with %extend</a></H3> <p> @@ -3658,7 +3701,7 @@ Vector(2, 3, 4) </div> <p> -<tt>%extend</tt> can be used for many more tasks than this. +<tt>%extend</tt> can be used for many more tasks than this. For example, if you wanted to overload a Python operator, you might do this: </p> @@ -3687,7 +3730,7 @@ Use it like this: >>> w = example.Vector(10, 11, 12) >>> print v+w Vector(12, 14, 16) ->>> +>>> </pre> </div> @@ -3696,7 +3739,7 @@ Vector(12, 14, 16) in any way---the extensions only show up in the Python interface. </p> -<H3><a name="Python_nn44">36.6.4 Exception handling with %exception</a></H3> +<H3><a name="Python_nn44">32.6.4 Exception handling with %exception</a></H3> <p> @@ -3830,7 +3873,143 @@ 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">36.7 Tips and techniques</a></H2> +<H3><a name="Python_optimization">32.6.5 Optimization options</a></H3> + + +<H4><a name="Python_fastproxy">32.6.5.1 -fastproxy</a></H4> + + +<p> +The <tt>-fastproxy</tt> command line option enables faster method calling as the call is made directly into the C/C++ layer rather than going through a method wrapper. +</p> + +<p> +Consider wrapping a C++ class: +</p> + +<div class="code"> +<pre> +struct Go { + void callme0() {} + void callme4(int a, int b, int c, int d) {} + void callme8(double a, double b, double c, double d, double e, double f, double g, double i) {} +}; +</pre> +</div> + +<p> +The default generated proxy class is: +</p> + +<div class="targetlang"> +<pre> +class Go(object): + def callme0(self): + return _example.Go_callme0(self) + + def callme4(self, a, b, c, d): + return _example.Go_callme4(self, a, b, c, d) + + def callme8(self, a, b, c, d, e, f, g, i): + return _example.Go_callme8(self, a, b, c, d, e, f, g, i) + ... +</pre> +</div> + +<p> +Each method in the Python class contains a Python proxy method which passes the arguments on to the underlying function in the low-level C/C++ module (_example in this case). +The generated proxy class when using <tt>-fastproxy</tt> is: +</p> + +<div class="targetlang"> +<pre> +%module example +class Go(object): + callme0 = _swig_new_instance_method(_example.Go_callme0) + callme4 = _swig_new_instance_method(_example.Go_callme4) + callme8 = _swig_new_instance_method(_example.Go_callme8) + ... +</pre> +</div> + +<p> +where <tt>_swig_new_instance_method</tt> adds the method to the proxy class via C API calls for direct access to the underlying function in the low-level C/C++ module. +Note that for some methods it is not possible to generate the direct access call and so <tt>-fastproxy</tt> is ignored. +This happens, for example, when adding <a href="#Python_nn42">additional code</a> to Python proxy methods, such as using <tt>%pythonprepend</tt>. +</p> + +<p> +The overhead calling into C/C++ from Python is reduced slightly using <tt>-fastproxy</tt>. +Below are some timings in microseconds calling the 3 functions in the example above. +Also included in the table for comparison is using the <tt>-builtin</tt> option covered in the +<a href="#Python_builtin_types">Built-in Types</a>. +</p> + +<table summary="Python fastproxy performance"> + <tr> + <th>Method name</th> + <th>Default</th> + <th>-fastproxy</th> + <th>-builtin</th> + </tr> + <tr> + <td>callme0</td> + <td>0.15</td> + <td>0.09</td> + <td>0.07</td> + </tr> + <tr> + <td>callme4</td> + <td>0.26</td> + <td>0.16</td> + <td>0.14</td> + </tr> + <tr> + <td>callme8</td> + <td>0.32</td> + <td>0.20</td> + <td>0.17</td> + </tr> +</table> + +<p> +Although the <tt>-fastproxy</tt> option results in faster code over the default, the generated proxy code is not as user-friendly +as docstring/doxygen comments and functions with default values are not visible in the generated Python proxy class. +The <tt>-olddefs</tt> option can rectify this. +</p> + +<p> +The generated proxy class for the example above when using <tt>-fastproxy -olddefs</tt> is: +</p> + +<div class="targetlang"> +<pre> +class Go(object): + def callme0(self): + return _example.Go_callme0(self) + callme0 = _swig_new_instance_method(_example.Go_callme0) + + def callme4(self, a, b, c, d): + return _example.Go_callme4(self, a, b, c, d) + callme4 = _swig_new_instance_method(_example.Go_callme4) + + def callme8(self, a, b, c, d, e, f, g, i): + return _example.Go_callme8(self, a, b, c, d, e, f, g, i) + callme8 = _swig_new_instance_method(_example.Go_callme8) + ... +</pre> +</div> + +<p> +The class defines each method in two different ways. The first definition is replaced by the second definition and so the second definition is the one used when the method is called. +While this possibly provides the best of both worlds, the time to import the module will be slightly slower when the class is defined due to the additional method definitions. +</p> + +<p> +The command line options mentioned above also apply to wrapped C/C++ global functions, not just class methods. +</p> + +<H2><a name="Python_nn45">32.7 Tips and techniques</a></H2> <p> @@ -3840,7 +4019,7 @@ strings, binary data, and arrays. This chapter discusses the common techniques solving these problems. </p> -<H3><a name="Python_nn46">36.7.1 Input and output parameters</a></H3> +<H3><a name="Python_nn46">32.7.1 Input and output parameters</a></H3> <p> @@ -3991,7 +4170,7 @@ int send_message(char *text, int *success); </div> <p> -When used in Python, the function will return multiple values. +When used in Python, the function will return multiple values. </p> <div class="targetlang"> @@ -4053,7 +4232,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">36.7.2 Simple pointers</a></H3> +<H3><a name="Python_nn47">32.7.2 Simple pointers</a></H3> <p> @@ -4122,7 +4301,7 @@ If you replace <tt>%pointer_functions()</tt> by <tt>%pointer_class(type, name)</ See the <a href="Library.html#Library">SWIG Library</a> chapter for further details. </p> -<H3><a name="Python_nn48">36.7.3 Unbounded C Arrays</a></H3> +<H3><a name="Python_nn48">32.7.3 Unbounded C Arrays</a></H3> <p> @@ -4132,17 +4311,17 @@ Sometimes a C function expects an array to be passed as a pointer. For example, <div class="code"> <pre> int sumitems(int *first, int nitems) { - int i, sum = 0; - for (i = 0; i < nitems; i++) { - sum += first[i]; - } - return sum; + int i, sum = 0; + for (i = 0; i < nitems; i++) { + sum += first[i]; + } + return sum; } </pre> </div> <p> -To wrap this into Python, you need to pass an array pointer as the first argument. +To wrap this into Python, you need to pass an array pointer as the first argument. A simple way to do this is to use the <tt>carrays.i</tt> library file. For example: </p> @@ -4184,7 +4363,7 @@ well suited for applications in which you need to create buffers, package binary data, etc. </p> -<H3><a name="Python_nn49">36.7.4 String handling</a></H3> +<H3><a name="Python_nn49">32.7.4 String handling</a></H3> <p> @@ -4219,13 +4398,13 @@ using the <tt>cstring.i</tt> library file described in the <a href="Library.html </p> <p> -When functions return a <tt>char *</tt>, it is assumed to be a NULL-terminated string. +When functions return a <tt>char *</tt>, it is assumed to be a NULL-terminated string. Data is copied into a new Python string and returned. </p> <p> If your program needs to work with binary data, you can use a typemap -to expand a Python string into a pointer/length argument pair. As luck would have it, +to expand a Python string into a pointer/length argument pair. As luck would have it, just such a typemap is already defined. Just do this: </p> @@ -4254,13 +4433,13 @@ also be used to extra binary data from arbitrary pointers. </p> -<H3><a name="Python_default_args">36.7.5 Default arguments</a></H3> +<H3><a name="Python_default_args">32.7.5 Default arguments</a></H3> <p> C++ default argument code generation is documented in the main <a href="SWIGPlus.html#SWIGPlus_default_args">Default arguments</a> section. -There is also an optional Python specific feature that can be used called the <tt>python:cdefaultargs</tt> +There is also an optional Python specific feature that can be used called the <tt>python:cdefaultargs</tt> <a href="Customization.html#Customization_feature_flags">feature flag</a>. By default, SWIG attempts to convert C++ default argument values into Python values and generates code into the Python layer containing these values. @@ -4303,7 +4482,7 @@ class CDA(object): <p> Adding the feature: </p> - + <div class="code"> <pre> %feature("python:cdefaultargs") CDA::fff; @@ -4353,7 +4532,7 @@ Versions of SWIG prior to this varied in their ability to convert C++ default va equivalent Python default argument values. </p> -<H2><a name="Python_nn53">36.8 Typemaps</a></H2> +<H2><a name="Python_nn53">32.8 Typemaps</a></H2> <p> @@ -4364,17 +4543,17 @@ as the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. </p> <p> -Before proceeding, it should be stressed that typemaps are not a required +Before proceeding, it should be stressed that typemaps are not 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-Python interface or if you want to elevate your guru status. </p> -<H3><a name="Python_nn54">36.8.1 What is a typemap?</a></H3> +<H3><a name="Python_nn54">32.8.1 What is a typemap?</a></H3> <p> -A typemap is nothing more than a code generation rule that is attached to +A typemap is nothing more than a code generation rule that is attached to a specific C datatype. For example, to convert integers from Python to C, you might define a typemap like this: </p> @@ -4486,7 +4665,7 @@ parameter is omitted): </pre> </div> -<H3><a name="Python_nn55">36.8.2 Python typemaps</a></H3> +<H3><a name="Python_nn55">32.8.2 Python typemaps</a></H3> <p> @@ -4506,7 +4685,7 @@ like this: <p> A detailed list of available methods can be found in the "<a -href="Typemaps.html#Typemaps">Typemaps</a>" chapter. +href="Typemaps.html#Typemaps">Typemaps</a>" chapter. </p> <p> @@ -4517,7 +4696,7 @@ looking at the files in the SWIG library. Just take into account that in the latest versions of swig (1.3.22+), the library files are not very pristine clear for the casual reader, as they used to be. The extensive use of macros and other ugly techniques in the latest -version produce a very powerful and consistent python typemap library, +version produce a very powerful and consistent Python typemap library, but at the cost of simplicity and pedagogic value. </p> @@ -4527,7 +4706,7 @@ a look at the SWIG library version 1.3.20 or so. </p> -<H3><a name="Python_nn56">36.8.3 Typemap variables</a></H3> +<H3><a name="Python_nn56">32.8.3 Typemap variables</a></H3> <p> @@ -4568,7 +4747,7 @@ A <tt>PyObject *</tt> that holds the result to be returned to Python. </p> <div class="indent"> -The parameter name that was matched. +The parameter name that was matched. </div> <p> @@ -4598,7 +4777,7 @@ properly assigned. The Python name of the wrapper function being created. </div> -<H3><a name="Python_nn57">36.8.4 Useful Python Functions</a></H3> +<H3><a name="Python_nn57">32.8.4 Useful Python Functions</a></H3> <p> @@ -4726,7 +4905,7 @@ write me </pre> </div> -<H2><a name="Python_nn58">36.9 Typemap Examples</a></H2> +<H2><a name="Python_nn58">32.9 Typemap Examples</a></H2> <p> @@ -4735,7 +4914,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">36.9.1 Converting Python list to a char ** </a></H3> +<H3><a name="Python_nn59">32.9.1 Converting Python list to a char ** </a></H3> <p> @@ -4812,10 +4991,10 @@ In the example, two different typemaps are used. The "in" typemap is used to receive an input argument and convert it to a C 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. +the C function. </p> -<H3><a name="Python_nn60">36.9.2 Expanding a Python object into multiple arguments</a></H3> +<H3><a name="Python_nn60">32.9.2 Expanding a Python object into multiple arguments</a></H3> <p> @@ -4878,7 +5057,7 @@ previous example: </div> <p> -When writing a multiple-argument typemap, each of the types is referenced by a variable such +When writing a multiple-argument typemap, each of the types is referenced by a variable such as <tt>$1</tt> or <tt>$2</tt>. The typemap code simply fills in the appropriate values from the supplied Python object. </p> @@ -4927,14 +5106,14 @@ If you don't you'll get an error message along the lines of: Traceback (most recent call last): File "runme.py", line 3, in >module< example.foo(["foo", "bar", "spam", "1"]) -NotImplementedError: Wrong number or type of arguments for overloaded function 'foo'. +TypeError: Wrong number or type of arguments for overloaded function 'foo'. Possible C/C++ prototypes are: foo(int, char **) foo() </pre> </div> -<H3><a name="Python_nn61">36.9.3 Using typemaps to return arguments</a></H3> +<H3><a name="Python_nn61">32.9.3 Using typemaps to return arguments</a></H3> <p> @@ -4960,7 +5139,7 @@ A typemap can be used to handle this case as follows : %module outarg // This tells SWIG to treat an double * argument with name 'OutValue' as -// an output value. We'll append the value to the current result which +// an output value. We'll append the value to the current result which // is guaranteed to be a List object by SWIG. %typemap(argout) double *OutValue { @@ -5022,7 +5201,7 @@ function can now be used as follows: >>> </pre></div> -<H3><a name="Python_nn62">36.9.4 Mapping Python tuples into small arrays</a></H3> +<H3><a name="Python_nn62">32.9.4 Mapping Python tuples into small arrays</a></H3> <p> @@ -5071,7 +5250,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">36.9.5 Mapping sequences to C arrays</a></H3> +<H3><a name="Python_nn63">32.9.5 Mapping sequences to C arrays</a></H3> <p> @@ -5160,7 +5339,7 @@ static int convert_darray(PyObject *input, double *ptr, int size) { </pre> </div> -<H3><a name="Python_nn64">36.9.6 Pointer handling</a></H3> +<H3><a name="Python_nn64">32.9.6 Pointer handling</a></H3> <p> @@ -5257,9 +5436,168 @@ that has a <tt>this</tt> attribute. In addition, class object (if applicable). </p> +<H3><a name="Python_memory_management_member_variables">32.9.7 Memory management when returning references to member variables</a></H3> + + +<p> +This example shows how to prevent premature garbage collection of objects when the underlying C++ class returns a pointer or reference to a member variable. +The example is a direct equivalent to this <a href="Java.html#Java_memory_management_objects">Java equivalent</a>. +</p> + +<p> +Consider the following C++ code: +</p> + +<div class="code"> +<pre> +#include <iostream> +struct Wheel { + int size; + Wheel(int sz = 0) : size(sz) {} + ~Wheel() { std::cout << "~Wheel" << std::endl; } +}; + +class Bike { + Wheel wheel; +public: + Bike(int val) : wheel(val) {} + Wheel& getWheel() { return wheel; } +}; +</pre> +</div> + +<p> +and the following usage from Python after running the code through SWIG: +</p> -<H2><a name="Python_nn65">36.10 Docstring Features</a></H2> +<div class="code"> +<pre> +bike = Bike(10) +wheel = bike.getWheel() +print("wheel size: {}".format(wheel.size)) + +del bike # Allow bike to be garbage collected +print("wheel size: {}".format(wheel.size)) +</pre> +</div> + +<p> +Don't be surprised that if the resulting output gives strange results such as... +</p> + +<div class="shell"> +<pre> +wheel size: 10 +~Wheel +wheel size: 135019664 +</pre> +</div> + +<p> +What has happened here is the garbage collector has collected the <tt>Bike</tt> instance as it doesn't think it is needed any more. +The proxy instance, <tt>wheel</tt>, contains a reference to memory that was deleted when the <tt>Bike</tt> instance was collected. +In order to prevent the garbage collector from collecting the <tt>Bike</tt> instance, a reference to the <tt>Bike</tt> must +be added to the <tt>wheel</tt> instance. +</p> + +<p> +You can do this by adding the reference when the <tt>getWheel()</tt> method +is called using one of three approaches: +</p> + +<p> +The easier, but less optimized, way is to use the <tt>%pythonappend</tt> directive +(see <a href="#Python_nn42">Adding additional Python code</a>): +</p> + +<div class="code"> +<pre> +%pythonappend getWheel %{ + # val is the Wheel proxy, self is the Bike instance + val.__bike_reference = self +%} +</pre> +</div> + +<p> +The code gets appended to the Python code generated for the +<tt>Bike::getWheel</tt> wrapper function, where we store the <tt>Bike</tt> proxy +instance onto the <tt>Wheel</tt> proxy instance before it is returned to the +caller as follows. +</p> + +<div class="targetlang"> +<pre> +class Bike(object): + ... + def getWheel(self): + val = _example.Bike_getWheel(self) + + # val is the Wheel proxy, self is the Bike instance + val.__bike_reference = self + + return val +</pre> +</div> + + +<p> +The second option, which performs better and is required if you use the +<tt>-builtin</tt> option, is to set the reference in the CPython implementation: + +<div class="code"> +<pre> +%extend Wheel { +// A reference to the parent class is added to ensure the underlying C++ +// object is not deleted while the item is in use +%typemap(ret) Wheel& getWheel { + PyObject *bike_reference_string = SWIG_Python_str_FromChar("__bike_reference"); + PyObject_SetAttr($result, bike_reference_string, $self); + Py_DecRef(bike_reference_string); +} +} +</pre> +</div> + +<p> +The third approach, shown below, is an optimization of the above approach and creates the "__bike_reference" Python string object just once. +While this looks more complex, it is just a small variation on the above typemap plus a support function +<tt>bike_reference()</tt> in a fragment called <tt>bike_reference_function</tt>. +The <tt>bike_reference_init</tt> typemap generates code into the "init" section for an initial call to <tt>bike_reference()</tt> when the module +is initialized and is done to create the "__bike_reference" Python string singleton in a thread-safe manner. +</p> + +<div class="code"> +<pre> +%fragment("bike_reference_init", "init") { + // Thread-safe initialization - initialize during Python module initialization + bike_reference(); +} + +%fragment("bike_reference_function", "header", fragment="bike_reference_init") { + +static PyObject *bike_reference() { + static PyObject *bike_reference_string = SWIG_Python_str_FromChar("__bike_reference"); + return bike_reference_string; +} + +} + +%extend Wheel { +// A reference to the parent class is added to ensure the underlying C++ +// object is not deleted while the item is in use +%typemap(ret, fragment="bike_reference_function") Wheel& getWheel %{ + PyObject_SetAttr($result, bike_reference(), $self); +%} +} +</pre> +</div> + + + + +<H2><a name="Python_nn65">32.10 Docstring Features</a></H2> <p> @@ -5287,7 +5625,7 @@ of your users much simpler. </p> -<H3><a name="Python_nn66">36.10.1 Module docstring</a></H3> +<H3><a name="Python_nn66">32.10.1 Module docstring</a></H3> <p> @@ -5312,7 +5650,7 @@ example: <div class="code"> <pre> %define DOCSTRING -"The `XmlResource` class allows program resources defining menus, +"The `XmlResource` class allows program resources defining menus, layout of controls on a panel, etc. to be loaded from an XML file." %enddef @@ -5321,7 +5659,7 @@ layout of controls on a panel, etc. to be loaded from an XML file." </div> -<H3><a name="Python_nn67">36.10.2 %feature("autodoc")</a></H3> +<H3><a name="Python_nn67">32.10.2 %feature("autodoc")</a></H3> <p> @@ -5349,7 +5687,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">36.10.2.1 %feature("autodoc", "0")</a></H4> +<H4><a name="Python_nn68">32.10.2.1 %feature("autodoc", "0")</a></H4> <p> @@ -5378,7 +5716,7 @@ def function_name(*args, **kwargs): </div> -<H4><a name="Python_nn69">36.10.2.2 %feature("autodoc", "1")</a></H4> +<H4><a name="Python_nn69">32.10.2.2 %feature("autodoc", "1")</a></H4> <p> @@ -5403,7 +5741,7 @@ def function_name(*args, **kwargs): </div> -<H4><a name="Python_autodoc2">36.10.2.3 %feature("autodoc", "2")</a></H4> +<H4><a name="Python_autodoc2">32.10.2.3 %feature("autodoc", "2")</a></H4> <p> @@ -5465,7 +5803,7 @@ def function_name(*args, **kwargs): </pre> </div> -<H4><a name="Python_autodoc3">36.10.2.4 %feature("autodoc", "3")</a></H4> +<H4><a name="Python_autodoc3">32.10.2.4 %feature("autodoc", "3")</a></H4> <p> @@ -5491,7 +5829,7 @@ def function_name(*args, **kwargs): </div> -<H4><a name="Python_nn70">36.10.2.5 %feature("autodoc", "docstring")</a></H4> +<H4><a name="Python_nn70">32.10.2.5 %feature("autodoc", "docstring")</a></H4> <p> @@ -5510,7 +5848,7 @@ void GetPosition(int* OUTPUT, int* OUTPUT); </div> -<H3><a name="Python_nn71">36.10.3 %feature("docstring")</a></H3> +<H3><a name="Python_nn71">32.10.3 %feature("docstring")</a></H3> <p> @@ -5542,7 +5880,7 @@ with more than one line. </pre> </div> -<H2><a name="Python_nn72">36.11 Python Packages</a></H2> +<H2><a name="Python_nn72">32.11 Python Packages</a></H2> <p>Python has concepts of modules and packages. Modules are separate units of @@ -5601,15 +5939,14 @@ Python3 adds another option for packages with namespace packages). Implicit namespace packages no longer use __init__.py files. SWIG generated Python modules support implicit namespace packages. See -<a href="#Python_implicit_namespace_packages">36.11.5 Implicit Namespace -Packages</a> for more information. +<a href="#Python_implicit_namespace_packages">Implicit namespace +packages</a> for more information. </p> <p> -If you place a SWIG generated module into a Python package then there -are details concerning the way SWIG -<a href="#Python_package_search">searches for the wrapper module</a> -that you may want to familiarize yourself with. +You can place a SWIG generated module into a Python package or keep as a global module, +details are covered a little later in +<a href="#Python_package_search">Location of modules</a>. </p> <p>The way Python defines its modules and packages impacts SWIG users. Some @@ -5617,7 +5954,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">36.11.1 Setting the Python package</a></H3> +<H3><a name="Python_modulepackage">32.11.1 Setting the Python package</a></H3> <p> @@ -5671,7 +6008,7 @@ pkg1/pkg2/_foo.so # (shared library built from C/C++ code generated by SWI </pre> </div> -<H3><a name="Python_absrelimports">36.11.2 Absolute and relative imports</a></H3> +<H3><a name="Python_absrelimports">32.11.2 Absolute and relative imports</a></H3> <p>Suppose, we have the following hierarchy of files:</p> @@ -5768,12 +6105,19 @@ class M2(pkg2.mod3.M3): pass </pre> </div> -<p>By default, SWIG would generate <tt>mod2.py</tt> proxy file with +<p>By default, SWIG will generate <tt>mod2.py</tt> proxy file with <tt>import</tt> directive as in point 1. This can be changed with the <tt>-relativeimport</tt> command line option. The <tt>-relativeimport</tt> instructs -SWIG to organize imports as in point 2 (for Python < 2.7.0) or as in point 4 -for Python 2.7.0 and newer. This is a check done at the time the module is -imported. In short, if you have +SWIG to organize imports as in point 4 for Python 2.7.0 and newer. +</p> + +<p> +<b>Compatibility Note:</b> Versions of SWIG prior to SWIG-4.0.0 supported Python < 2.7.0 +and would organize the imports as in point 2 if an older version of Python was detected at runtime. +</p> + +<p> +In short, if you have <tt>mod2.i</tt> and <tt>mod3.i</tt> as above, then without <tt>-relativeimport</tt> SWIG will write</p> @@ -5788,13 +6132,8 @@ write</p> <div class="targetlang"> <pre> -from sys import version_info -if version_info >= (2, 7, 0): - from . import pkg2 - import pkg1.pkg2.mod3 -else: - import pkg2.mod3 -del version_info +from . import pkg2 +from .pkg2 import mod3 </pre> </div> @@ -5806,7 +6145,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">36.11.3 Enforcing absolute import semantics</a></H3> +<H3><a name="Python_absimport">32.11.3 Enforcing absolute import semantics</a></H3> <p>As you may know, there is an incompatibility in import semantics (for the @@ -5832,7 +6171,7 @@ from __future__ import absolute_import </pre> </div> -<p>at the very beginning of his proxy <tt>*.py</tt> file. In SWIG, it may be +<p>at the very beginning of your proxy <tt>*.py</tt> file. In SWIG, it may be accomplished with <tt>%pythonbegin</tt> directive as follows:</p> <div class="code"> @@ -5843,7 +6182,7 @@ from __future__ import absolute_import </pre> </div> -<H3><a name="Python_importfrominit">36.11.4 Importing from __init__.py</a></H3> +<H3><a name="Python_importfrominit">32.11.4 Importing from __init__.py</a></H3> <p>Imports in <tt>__init__.py</tt> are handy when you want to populate a @@ -5953,7 +6292,7 @@ class Bar(pkg3.foo.Foo): pass effect (note, that the Python 2 case also needs the <tt>-relativeimport</tt> workaround).</p> -<H3><a name="Python_implicit_namespace_packages">36.11.5 Implicit Namespace Packages</a></H3> +<H3><a name="Python_implicit_namespace_packages">32.11.5 Implicit namespace packages</a></H3> <p> Python 3.3 introduced @@ -6000,7 +6339,7 @@ packages you can place these files in the following configurations: </pre> </div> -<p> Finally suppose that your pure python code is stored in a .zip file or +<p> Finally suppose that your pure Python code is stored in a .zip file or some other way (database, web service connection, etc). Python can load the robin.py module using a custom importer. But the _robin.so module will need to be located on a file system. Implicit namespace packages make this @@ -6031,145 +6370,280 @@ zipimporter requires python-3.5.1 or newer to work with subpackages. </p> -<H3><a name="Python_package_search">36.11.6 Searching for the wrapper module</a></H3> +<H3><a name="Python_package_search">32.11.6 Location of modules</a></H3> <p> When SWIG creates wrappers from an interface file, say foo.i, two Python modules are -created. There is a pure Python module module (foo.py) and C/C++ code which is -built and linked into a dynamically (or statically) loaded low-level module _foo -(see the <a href="Python.html#Python_nn3">Preliminaries section</a> for details). So, the interface +created. There is a pure Python module (foo.py) and C/C++ code which is +compiled and linked into a dynamically (or statically) loaded low-level module _foo +(see the <a href="#Python_nn3">Preliminaries section</a> for details). So, the interface file really defines two Python modules. How these two modules are loaded is covered next. </p> <p> -The pure Python module needs to load the C/C++ module in order to link -to the wrapped C/C++ methods. To do this it must make some assumptions -about what package the C/C++ module may be located in. The approach the -pure Python module uses to find the C/C++ module is as follows: +The pure Python module needs to load the C/C++ module in order to call +the wrapped C/C++ methods. To do this it must make some assumptions +about the location of the C/C++ module. +There are two configurations that are supported by default. </p> <ol> - <li><p>The pure Python module, foo.py, tries to load the C/C++ module, _foo, from the same package foo.py is - located in. The package name is determined from the <tt>__name__</tt> - attribute given to foo.py by the Python loader that imported - foo.py. If foo.py is not in a package then _foo is loaded - as a global module.</p> + <li><p>Both modules in the same package</p> </li> - <li><p>If the above import of _foo results in an ImportError - being thrown, then foo.py makes a final attempt to load _foo - as a global module.</p> + <li><p>Both modules are global</p> </li> </ol> <p> -The Python code implementing the loading logic described above is quite complex to handle multiple -versions of Python, but it can be replaced with custom code. -This is not recommended unless you understand the full intricacies of importing Python modules. -The custom code can be specified by setting the <tt>moduleimport</tt> option of the <tt>%module</tt> directive with the appropriate import code. For example: +Additional configurations are supported but require custom import code. +</p> + + +<p> +The following sub-sections look more closely at the two default configurations as well as some customized configurations. +An input interface file, foo.i, results in the two modules foo.py and _foo.so for each of the configurations. +</p> + +<H4><a name="Python_package_search_both_package_modules">32.11.6.1 Both modules in the same package</a></H4> + + +<p> +In this configuration, the pure Python module, foo.py, tries to load the C/C++ module, _foo, from the same package foo.py is +located in. The package name is determined from the <tt>__package__</tt> +attribute if available, see <a href="https://www.python.org/dev/peps/pep-0366/">PEP 366</a>. Otherwise it is derived from the <tt>__name__</tt> +attribute given to foo.py by the Python loader that imported foo.py. +The interface file for this configuration would contain: </p> <div class="code"> <pre> -%module(moduleimport="import _foo") foo +%module(package="mypackage") foo </pre> </div> +<p>The location of the files could be as follows:</p> +<div class="diagram"> +<pre> +/dir/mypackage/foo.py +/dir/mypackage/__init__.py +/dir/mypackage/_foo.so +</pre> +</div> + +<p>Assuming /dir/ is in PYTHONPATH, the module can be imported using</p> + +<div class="targetlang"> +<pre> +from mypackage import foo +</pre> +</div> + + +<H4><a name="Python_package_search_both_global_modules">32.11.6.2 Both modules are global</a></H4> + + <p> -The special variable <tt>$module</tt> will also be expanded into the low-level C/C++ module name, <tt>_foo</tt> in the case above. -When you have more than just a line or so then you can retain the easy -readability of the <tt>%module</tt> directive by using a macro. For -example: +In this configuration, there are no packages. +If foo.py is not in a package, that is, it is a global module, then _foo is loaded +as a global module. +The interface file for this configuration would contain: </p> <div class="code"> <pre> -%define MODULEIMPORT -" -print 'Loading low-level module $module' -import $module -print 'Module has loaded' -" -%enddef +%module foo +</pre> +</div> -%module(moduleimport=MODULEIMPORT) foo +<p>The location of the files could be as follows:</p> +<div class="diagram"> +<pre> +/dir/foo.py +/dir/_foo.so </pre> </div> +<p>Assuming /dir/ is in PYTHONPATH, the module can be imported using</p> -<p> -Now let's consider an example using the SWIG default loading logic. -Suppose foo.i is compiled into foo.py and _foo.so. Assuming -/dir is on PYTHONPATH, then the two modules can be installed and used in the -following ways: +<div class="targetlang"> +<pre> +import foo +</pre> +</div> + +<H4><a name="Python_package_search_wrapper_split">32.11.6.3 Split modules custom configuration</a></H4> + + +<p>In this non-standard 'split module' configuration, the pure Python module is in a package and the low level C/C++ module is global. +This configuration is not generally recommended and is not supported by default as it needs a custom configuration. +The module import code customization required is via the <tt>moduleimport</tt> attribute in the <tt>%module</tt> directive. +The next sub-section elaborates further on this. +The interface file for this split module configuration would contain: </p> +<div class="code"> +<pre> +%module(package="mypackage", moduleimport="import _foo") foo +</pre> +</div> -<H4><a name="Python_package_search_both_package_modules">36.11.6.1 Both modules in the same package</a></H4> +<p> +When using <tt>-builtin</tt>, use the following instead (the reasons are also covered shortly in the next sub-section): +</p> +<div class="code"> +<pre> +%module(package="mypackage", moduleimport="from _foo import *") foo +</pre> +</div> -<p>Both modules are in one package:</p> +<p>The location of the files could be as follows:</p> <div class="diagram"> <pre> -/dir/package/foo.py -/dir/package/__init__.py -/dir/package/_foo.so +/dir/mypackage/foo.py +/dir/mypackage/__init__.py +/dir/_foo.so </pre> </div> -<p>And imported with</p> -<div class="diagram"> + +<p>Assuming /dir/ is in PYTHONPATH, the module can be imported using</p> + +<div class="targetlang"> <pre> -from package import foo +from mypackage import foo </pre> </div> +<p> +<b>Compatibility Note:</b> Versions of SWIG prior to SWIG-4.0.0 supported split modules without the above customization. +However, this had to be removed as the default import code often led to confusion due to obfuscation of genuine Python <tt>ImportError</tt> problems. +Using one of the two default configurations is the recommended approach now. +</p> -<H4><a name="Python_package_search_wrapper_split">36.11.6.2 Split modules</a></H4> +<H4><a name="Python_custom_module_import">32.11.6.4 More on customizing the module import code</a></H4> -<p>The pure python module is in a package and the C/C++ module is global:</p> -<div class="diagram"> + +<p> +The Python code implementing the default import logic is shown below. It supports the two configurations described earlier, that is, +either both modules are in a package or loading both as global modules. +The code is generated into the pure Python module, foo.py, and merely imports the low-level _foo module. +</p> + +<div class="targetlang"> <pre> -/dir/package/foo.py -/dir/package/__init__.py -/dir/_foo.so +if __package__ or '.' in __name__: + from . import _foo +else: + import _foo </pre> </div> -<p>And imported with</p> -<div class="diagram"> + +<p> +This import code implementation is non-trivial but it can be replaced with custom code providing opportunities to make it simpler and/or more flexible. +This is not normally recommended though unless you have a good understanding of the intricacies of importing Python modules. +The custom code can be specified by setting the <tt>moduleimport</tt> option of the <tt>%module</tt> directive with the appropriate import code. For example: +</p> + +<div class="code"> <pre> -from package import foo +%module(moduleimport="import _foo") foo </pre> </div> +<p> +This will replace the default import logic above and generate the following into the pure Python module, foo.py: +</p> -<H4><a name="Python_package_search_both_global_modules">36.11.6.3 Both modules are global</a></H4> +<div class="targetlang"> +<pre> +import _foo +</pre> +</div> +<p> +In fact the above is a simplification customization for the configuration where both modules are global; +it removes the logic for also handling the modules being in a package. +</p> -<p>Both modules are global:</p> -<div class="diagram"> +<p> +There is a special variable, <tt>$module</tt>, which is expanded into the low-level C/C++ module name, <tt>_foo</tt> in the case above. +The identical output would be generated if instead the following had been used: +</p> + +<div class="code"> <pre> -/dir/foo.py -/dir/_foo.so +%module(moduleimport="import $module") foo </pre> </div> -<p>And imported with</p> -<div class="diagram"> + +<p> +When you have many lines you can retain the easy +readability of the <tt>%module</tt> directive by using a macro. For +example: +</p> + +<div class="code"> <pre> -import foo +%define MODULEIMPORT +" +print 'Loading low-level module $module' +import $module +print 'Module has loaded' +" +%enddef + +%module(moduleimport=MODULEIMPORT) foo +</pre> +</div> + +<p> +This will of course generate the following into the pure Python module: +</p> + +<div class="targetlang"> +<pre> +print 'Loading low-level module $module' +import _foo +print 'Module has loaded' +</pre> +</div> + +<p> +When using the <tt>-builtin</tt> option, the link between the pure Python module and the low-level C/C++ module is slightly different as +all the objects from the low-level module are imported directly into the pure Python module. +The default import loading code is thus different: +</p> + +<div class="targetlang"> +<pre> +if __package__ or '.' in __name__: + from ._foo import * +else: + from _foo import * </pre> </div> <p> -If _foo is statically linked into an embedded Python interpreter, then it may or -may not be in a Python package. This depends in the exact way the module was -loaded statically. The above search order will still be used for statically -loaded modules. So, one may place the module either globally or in a package -as desired. +Any customizations must import the code in a similar manner. +The best way to support both with and without <tt>-builtin</tt> is to make use of the <tt>SWIGPYTHON_BUILTIN</tt> macro which is defined when <tt>-builtin</tt> is specified. +The following will do this for the <a href="#Python_package_search_wrapper_split">split modules</a> case above. </p> -<H4><a name="Python_package_search_static">36.11.6.4 Statically linked C modules</a></H4> + +<div class="code"> +<pre> +#if defined(SWIGPYTHON_BUILTIN) /* defined when using -builtin */ +%module(package="mypackage", moduleimport="from $module import *") foo +#else +%module(package="mypackage", moduleimport="import $module") foo +#endif +</pre> +</div> + +<H4><a name="Python_package_search_static">32.11.6.5 Statically linked C modules</a></H4> <p>It is strongly recommended to use dynamically linked modules for the C @@ -6178,7 +6652,7 @@ If for some reason you still need to link the C module of the pair of Python modules generated by SWIG into your interpreter, then this section provides some details on how this impacts the pure Python modules ability to locate the other part of the pair. -Please also see the <a href="Python.html#Python_nn8">Static Linking</a> section. +Please also see the <a href="#Python_nn8">Static Linking</a> section. </p> <p>When Python is extended with C code the Python interpreter needs to be @@ -6195,7 +6669,7 @@ new SWIG C module exists. which would have normally been called when the shared object was dynamically loaded. The specific name of this method is not given here because statically linked modules are not encouraged with SWIG -(<a href="Python.html#Python_nn8">Static Linking</a>). However one can find this +(<a href="#Python_nn8">Static Linking</a>). However one can find this init function in the C file generated by SWIG. </p> @@ -6207,8 +6681,8 @@ they treat it affects how the pure Python module will be able to locate the C module. </p> -<p>The details concerning this are covered completly in the documentation -for Python itself. Links to the relavent sections follow: +<p>The details concerning this are covered completely in the documentation +for Python itself. Links to the relevant sections follow: </p> <ul> @@ -6218,21 +6692,21 @@ for Python itself. Links to the relavent sections follow: <p>There are two keys things to understand. The first is that in Python 2 the init() function returns void. In Python 3 the init() function -returns a PyObject * which points to the new module. Secondly, when +returns a <tt>PyObject *</tt> which points to the new module. Secondly, when you call the init() method manually, you are the Python importer. So, you determine which package the C module will be located in. </p> <p>So, if you are using Python 3 it is important that you follow what is described in the Python documentation linked above. In particular, you can't -simply call the init() function generated by SWIG and cast the PyObject +simply call the init() function generated by SWIG and cast the <tt>PyObject</tt> pointer it returns over the side. If you do then Python 3 will have no idea that your C module exists and the pure Python half of your wrapper will not be able to find it. You need to register your module with the Python interpreter as described in the Python docs. </p> -<p>With Python 2 things are somewhat more simple. In this case the init function +<p>With Python 2 things are somewhat more simple. In this case the init() function returns void. Calling it will register your new C module as a <b>global</b> module. The pure Python part of the SWIG wrapper will be able to find it because it tries both the pure Python module it is part of and the global @@ -6241,17 +6715,15 @@ module then you will either need to refer to the Python documentation on how to do this (remember you are now the Python importer) or use dynamic linking. </p> -<H2><a name="Python_python3support">36.12 Python 3 Support</a></H2> +<H2><a name="Python_python3support">32.12 Python 3 Support</a></H2> <p> -SWIG is able to support Python 3.0. The wrapper code generated by -SWIG can be compiled with both Python 2.x or 3.0. Further more, by +SWIG is able to support Python 3.x. The wrapper code generated by +SWIG can be compiled with both Python 2.x or 3.x. Further more, by passing the <tt>-py3</tt> command line option to SWIG, wrapper code with some Python 3 specific features can be generated (see below -subsections for details of these features). The <tt>-py3</tt> option also -disables some incompatible features for Python 3, such as -<tt>-classic</tt>. +subsections for details of these features). <p> There is a list of known-to-be-broken features in Python 3: @@ -6264,11 +6736,11 @@ There is a list of known-to-be-broken features in Python 3: </ul> <p> -The following are Python 3.0 new features that are currently supported by +The following are Python 3 new features that are currently supported by SWIG. </p> -<H3><a name="Python_nn74">36.12.1 Function annotation</a></H3> +<H3><a name="Python_nn74">32.12.1 Function annotation</a></H3> <p> @@ -6301,12 +6773,12 @@ For detailed usage of function annotation, see <a href="https://www.python.org/dev/peps/pep-3107/">PEP 3107</a>. </p> -<H3><a name="Python_nn75">36.12.2 Buffer interface</a></H3> +<H3><a name="Python_nn75">32.12.2 Buffer interface</a></H3> <p> -Buffer protocols were revised in Python 3. SWIG also gains a series of -new typemaps to support buffer interfaces. These typemap macros are +SWIG has a series of +typemaps to support buffer interfaces. These typemap macros are defined in <tt>pybuffer.i</tt>, which must be included in order to use them. By using these typemaps, your wrapped function will be able to accept any Python object that exposes a suitable buffer interface. @@ -6323,15 +6795,15 @@ void get_path(char *s); <p> Then you can write a typemap like this: (the following example is -applied to both Python 3.0 and 2.6, since the <tt>bytearray</tt> type -is backported to 2.6. +applied to both Python 2 and 3, since the <tt>bytearray</tt> type +was backported to 2.6. </p> <div class="code"><pre> %include <pybuffer.i> %pybuffer_mutable_string(char *str); -void get_path(char *s); +void get_path(char *str); </pre></div> <p> @@ -6378,7 +6850,7 @@ In Python: >>> snprintf(buf, "Hello world!") >>> print(buf) bytearray(b'Hello\x00') ->>> +>>> </pre></div> </div> @@ -6414,7 +6886,7 @@ bytearray(b'FOO\x00') <p> Both <tt>%pybuffer_mutable_binary</tt> and <tt>%pybuffer_mutable_string</tt> -require the provided buffer to be mutable, eg. they can accept a +require the provided buffer to be mutable, eg. they can accept a <tt>bytearray</tt> type but can't accept an immutable <tt>byte</tt> type. </p> @@ -6431,7 +6903,7 @@ type. This macro maps an object's buffer to a pointer <tt>parm</tt> and a size <tt>size_parm</tt>. It is similar to <tt>%pybuffer_mutable_binary</tt>, except the -<tt>%pybuffer_binary</tt> an accept both mutable and immutable +<tt>%pybuffer_binary</tt> can accept both mutable and immutable buffers. As a result, the wrapped function should not modify the buffer. </p> @@ -6453,13 +6925,14 @@ modify the buffer. </div> -<H3><a name="Python_nn76">36.12.3 Abstract base classes</a></H3> +<H3><a name="Python_nn76">32.12.3 Abstract base classes</a></H3> <p> By including <tt>pyabc.i</tt> and using the <tt>-py3</tt> command line option when calling SWIG, the proxy classes of the STL containers -will automatically gain an appropriate abstract base class. For +will automatically gain an appropriate abstract base class from the +<tt>collections.abc</tt> module. For example, the following SWIG interface: </p> @@ -6476,8 +6949,8 @@ namespace std { <p> will generate a Python proxy class <tt>Mapii</tt> inheriting from -<tt>collections.MutableMap</tt> and a proxy class <tt>IntList</tt> -inheriting from <tt>collections.MutableSequence</tt>. +<tt>collections.abc.MutableMap</tt> and a proxy class <tt>IntList</tt> +inheriting from <tt>collections.abc.MutableSequence</tt>. </p> <p> @@ -6486,7 +6959,7 @@ used to define an abstract base class for your own C++ class: </p> <div class="code"><pre> -%pythonabc(MySet, collections.MutableSet); +%pythonabc(MySet, collections.abc.MutableSet); </pre></div> <p> @@ -6494,7 +6967,15 @@ For details of abstract base class, please see <a href="https://www.python.org/dev/peps/pep-3119/">PEP 3119</a>. </p> -<H3><a name="Python_nn77">36.12.4 Byte string output conversion</a></H3> +<p> +<b>Compatibility Note:</b> SWIG-4.0.0 changed the base classes to use the +<tt>collections.abc</tt> module instead of <tt>collections</tt> due to the deprecation +of the classes in the <tt>collections</tt> module in Python 3.7. +The <tt>collections.abc</tt> module was introduced in Python 3.3 and hence this feature +requires Python 3.3 or later. +</p> + +<H3><a name="Python_nn77">32.12.4 Byte string output conversion</a></H3> <p> @@ -6511,18 +6992,21 @@ string that cannot be completely decoded as UTF-8: <div class="code"><pre> %module example -%include <std_string.i> - %inline %{ -const char* non_utf8_c_str(void) { - return "h\xe9llo w\xc3\xb6rld"; +const char * non_utf8_c_str(void) { + return "h\xe9llo w\xc3\xb6rld"; +} + +void instring(const char *s) { + ... } %} </pre></div> <p> +Note that "\xe9" is an invalid UTF-8 encoding, but "\xc3\xb6" is valid. When this method is called from Python 3, the return value is the following text string: </p> @@ -6581,6 +7065,20 @@ For more details about the <tt>surrogateescape</tt> error handler, please see </p> <p> +When Python 3 strings are passed to the C/C++ layer, they are expected to be valid UTF8 Unicode strings too. +For example, when the <tt>instring</tt> method above is wrapped and called, any invalid UTF8 Unicode code strings +will result in a TypeError because the attempted conversion fails: +</p> + +<div class="targetlang"><pre> +>>> example.instring('h\xe9llo') +>>> example.instring('h\udce9llo') +Traceback (most recent call last): + File "<stdin>", line 1, in <module> +TypeError: in method 'instring', argument 1 of type 'char const *' +</pre></div> + +<p> In some cases, users may wish to instead handle all byte strings as bytes objects in Python 3. This can be accomplished by adding <tt>SWIG_PYTHON_STRICT_BYTE_CHAR</tt> to the generated code: @@ -6658,7 +7156,7 @@ overloads taking both std::string (as Python bytes) and std::wstring (as Python unicode). </p> -<H3><a name="Python_2_unicode">36.12.5 Python 2 Unicode</a></H3> +<H3><a name="Python_2_unicode">32.12.5 Python 2 Unicode</a></H3> <p> @@ -6730,6 +7228,110 @@ the first is allowing unicode conversion and the second is explicitly prohibiting it. </p> +<H2><a name="Python_multithreaded">32.13 Support for Multithreaded Applications</a></H2> + + +<p>By default, SWIG does not enable support for multithreaded Python applications. More +specifically, the Python wrappers generated by SWIG will not release the + Python's interpreter's Global Interpreter Lock (GIL) when wrapped C/C++ code is +entered. Hence, while any of the wrapped C/C++ code is executing, the Python interpreter +will not be able to run any other threads, even if the wrapped C/C++ code is waiting + in a blocking call for something like network or disk IO. + + Fortunately, SWIG does have the ability to enable multithreaded support and automatic + release of the GIL either for all wrapped code in a module or on a more selective basis. The user + interface for this is described in the next section. +</p> + +<H3><a name="Python_thread_UI">32.13.1 UI for Enabling Multithreading Support</a></H3> + + +<p>The user interface is as follows:</p> +<ol> + <li><p>Module thread support can be enabled in two ways:</p> + <ul> + <li> + <p> + The <tt>-threads</tt> SWIG Python option at the command line (or in <tt>setup.py</tt>): + </p> + <div class="shell"><pre>$ swig -python -threads example.i</pre></div> + </li> + <li> + <p> + The <tt>threads</tt> module option in the *.i template file: + </p> + <div class="code"><pre>%module("threads"=1)</pre></div> + </li> + </ul> + </li> + <li><p>You can disable thread support for a given method:</p> + <div class="code"><pre>%feature("nothread") method;</pre></div> + or + <div class="code"><pre>%nothread method;</pre></div> + </li> + <li><p>You can partially disable thread support for a given method:</p> + <ul> + <li><p>To disable the C++/Python thread protection:</p> + <div class="code"><pre>%feature("nothreadblock") method;</pre></div> + or + <div class="code"><pre>%nothreadblock method;</pre></div> + </li> + <li> + <p>To disable the Python/C++ thread protection</p> + <div class="code"><pre>%feature("nothreadallow") method;</pre></div> + or + <div class="code"><pre>%nothreadallow method;</pre></div> + </li> + </ul> + </li> +</ol> + +<H3><a name="Python_thread_performance">32.13.2 Multithread Performance</a></H3> + + +<p> + For the curious about performance, here are some numbers for the profiletest.i test, + which is used to check the speed of the wrapped code: +</p> + +<table summary="Python multithread performance"> + <tr> + <th>Thread Mode</th> + <th>Execution Time (sec)</th> + <th>Comment</th> + </tr> + <tr> + <td>Single Threaded</td> + <td>9.6</td> + <td>no "-threads" option given</td> + </tr> + <tr> + <td>Fully Multithreaded</td> + <td>15.5</td> + <td>"-threads" option = 'allow' + 'block'</td> + </tr> + <tr> + <td>No Thread block</td> + <td>12.2</td> + <td>only 'allow'</td> + </tr> + <tr> + <td>No Thread Allow</td> + <td>13.6</td> + <td>only block'</td> + </tr> +</table> + +<p> + Fully threaded code decreases the wrapping performance by + around 60%. If that is important to your application, you + can tune each method using the different 'nothread', + 'nothreadblock' or 'nothreadallow' features as + needed. Note that for some methods deactivating the + 'thread block' or 'thread allow' code is not an option, + so, be careful. +</p> + </body> </html> diff --git a/Doc/Manual/R.html b/Doc/Manual/R.html index 40b96d6c9..373cd7ed9 100644 --- a/Doc/Manual/R.html +++ b/Doc/Manual/R.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="R">37 SWIG and R</a></H1> +<H1><a name="R">33 SWIG and R</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -28,13 +28,15 @@ R is a GPL'ed open source statistical and plotting environment. Information about R can be found at <a href="http://www.r-project.org/">www.r-project.org</a>. +</p> +<p> The R bindings are under active development. They have been used to 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">37.1 Bugs</a></H2> +<H2><a name="R_nn2">33.1 Bugs</a></H2> <p> @@ -46,7 +48,7 @@ Currently the following features are not implemented or broken: <li>C Array wrappings </ul> -<H2><a name="R_nn3">37.2 Using R and SWIG</a></H2> +<H2><a name="R_nn3">33.2 Using R and SWIG</a></H2> <p> @@ -113,11 +115,10 @@ cacheMetaData(1) </pre> </div> +<p> The cacheMetaData(1) will cause R to refresh its object tables. Without it, inheritance of wrapped objects may fail. - -<p> -These two files can be loaded in any order +These two files can be loaded in any order. </p> <p> @@ -129,7 +130,7 @@ These two files can be loaded in any order <li>If you do not set the output file name appropriately, you might see errors like <div class="shell"> <pre> -> fact(4) +> fact(4) Error in .Call("R_swig_fact", s_arg1, as.logical(.copy), PACKAGE = "example") : "R_swig_fact" not available for .Call() for package "example" </pre> @@ -137,25 +138,29 @@ Error in .Call("R_swig_fact", s_arg1, as.logical(.copy), PACKAGE = "example") : <li>Make sure the architecture of the shared library(x64 for instance), matches the architecture of the R program you want to load your shared library into </ul> -<H2><a name="R_nn4">37.3 Precompiling large R files</a></H2> +<H2><a name="R_nn4">33.3 Precompiling large R files</a></H2> +<p> In cases where the R file is large, one make save a lot of loading time by precompiling the R wrapper. This can be done by creating the file makeRData.R which contains the following +</p> -<pre> +<div class="code"><pre> source('BigFile.R') save(list=ls(all=TRUE), file="BigFile.RData", compress=TRUE) q(save="no") -</pre> +</pre></div> +<p> This will generate a compiled R file called BigFile.RData that will save a large amount of loading time. +</p> -<H2><a name="R_nn5">37.4 General policy</a></H2> +<H2><a name="R_nn5">33.4 General policy</a></H2> <p> @@ -164,7 +169,7 @@ wrapping over the underlying functions and rely on the R type system to provide R syntax. </p> -<H2><a name="R_language_conventions">37.5 Language conventions</a></H2> +<H2><a name="R_language_conventions">33.5 Language conventions</a></H2> <p> @@ -173,7 +178,7 @@ and [ are overloaded to allow for R syntax (one based indices and slices) </p> -<H2><a name="R_nn6">37.6 C++ classes</a></H2> +<H2><a name="R_nn6">33.6 C++ classes</a></H2> <p> @@ -185,13 +190,64 @@ 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">37.7 Enumerations</a></H2> +<H2><a name="R_nn7">33.7 Enumerations</a></H2> + +<p> +R doesn't have a native enumeration type. Enumerations are represented +as character strings in R, with calls to R functions that convert back +and forth between integers. +</p> + +<p> +The details of enumeration names and contents are stored in hidden R +environments, which are named according the the enumeration name - for +example, an enumeration colour: +</p> + +<div class="code"><pre> +enum colour { red=-1, blue, green = 10 }; +</pre></div> + +<p> +will be initialized by the following call in R: +</p> + +<div class="code"><pre> +defineEnumeration("_colour", + .values=c("red" = .Call('R_swig_colour_red_get',FALSE, PACKAGE='enum_thorough'), +"blue" = .Call('R_swig_colour_blue_get',FALSE, PACKAGE='enum_thorough'), +"green" = .Call('R_swig_colour_green_get',FALSE, PACKAGE='enum_thorough'))) +</pre></div> + +<p> +which will create an environment named <tt>.__E___colour</tt>. The enumeration +values are initialised via calls to C/C++ code, allowing complex +values for enumerations to be used. Calls to the C/C++ code require +the compiled library to be loaded, so a <tt>delayedAssign</tt> is employed +within <tt>defineEnumeration</tt> in order to allow the code to be easily used in R +packages. +</p> + +<p> +The user typically does not need to access the enumeration lookup +functions or know the name of the enumeration type used by +R. Attributes containing the type information are attached by swig to +functions requiring enumeration arguments or returning enumeration +values, and those attributes are used to identify and access the +appropriate environments and thus translate between characters +and integers. +</p> + +<p> +The relevant functions, for debugging purposes, are <tt>enumToInteger</tt> and +<tt>enumFromInteger</tt>. +</p> <p> -enumerations are characters which are then converted back and forth to -ints before calling the C routines. All of the enumeration code is -done in R. +Anonymous enumerations are ignored by the binding generation process, +leaving no way of accessing the value of anonymous enumerations from R +code. </p> </body> diff --git a/Doc/Manual/Ruby.html b/Doc/Manual/Ruby.html index 89de43010..3cfd1292c 100644 --- a/Doc/Manual/Ruby.html +++ b/Doc/Manual/Ruby.html @@ -8,7 +8,7 @@ <body bgcolor="#ffffff"> -<H1><a name="Ruby">38 SWIG and Ruby</a></H1> +<H1><a name="Ruby">34 SWIG and Ruby</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -149,10 +149,10 @@ <p>This chapter describes SWIG's support of Ruby.</p> -<H2><a name="Ruby_nn2">38.1 Preliminaries</a></H2> +<H2><a name="Ruby_nn2">34.1 Preliminaries</a></H2> -<p> SWIG 3.0 is known to work with Ruby versions 1.8 and later. +<p> SWIG 4.0 is known to work with Ruby versions 1.9 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 @@ -164,7 +164,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">38.1.1 Running SWIG</a></H3> +<H3><a name="Ruby_nn3">34.1.1 Running SWIG</a></H3> <p> To build a Ruby module, run SWIG using the <tt>-ruby</tt> @@ -188,7 +188,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">38.1.2 Getting the right header files</a></H3> +<H3><a name="Ruby_nn4">34.1.2 Getting the right header files</a></H3> <p> In order to compile the wrapper code, the compiler needs the <tt>ruby.h</tt> @@ -202,7 +202,7 @@ the compiler options needed to compile the code is to ask Ruby itself:</p> </pre> </div> -<H3><a name="Ruby_nn5">38.1.3 Compiling a dynamic module</a></H3> +<H3><a name="Ruby_nn5">34.1.3 Compiling a dynamic module</a></H3> <p> Ruby extension modules are typically compiled into shared @@ -275,7 +275,7 @@ manual pages for your compiler and linker to determine the correct set of options. You might also check the <a href="https://github.com/swig/swig/wiki">SWIG Wiki</a> for additional information. </p> -<H3><a name="Ruby_nn6">38.1.4 Using your module</a></H3> +<H3><a name="Ruby_nn6">34.1.4 Using your module</a></H3> <p> Ruby <i>module</i> names must be capitalized, @@ -305,7 +305,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">38.1.5 Static linking</a></H3> +<H3><a name="Ruby_nn7">34.1.5 Static linking</a></H3> <p> An alternative approach to dynamic linking is to rebuild the @@ -320,7 +320,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">38.1.6 Compilation of C++ extensions</a></H3> +<H3><a name="Ruby_nn8">34.1.6 Compilation of C++ extensions</a></H3> <p> On most machines, C++ extension modules should be linked @@ -352,7 +352,7 @@ $libs = append_library($libs, "supc++") create_makefile('example')</pre> </div> -<H2><a name="Ruby_nn9">38.2 Building Ruby Extensions under Windows 95/NT</a></H2> +<H2><a name="Ruby_nn9">34.2 Building Ruby Extensions under Windows 95/NT</a></H2> <p> Building a SWIG extension to Ruby under Windows 95/NT is @@ -377,7 +377,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">38.2.1 Running SWIG from Developer Studio</a></H3> +<H3><a name="Ruby_nn10">34.2.1 Running SWIG from Developer Studio</a></H3> <p> If you are developing your application within Microsoft @@ -441,13 +441,13 @@ Foo = 3.0 </pre> </div> -<H2><a name="Ruby_nn11">38.3 The Ruby-to-C/C++ Mapping</a></H2> +<H2><a name="Ruby_nn11">34.3 The Ruby-to-C/C++ Mapping</a></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">38.3.1 Modules</a></H3> +<H3><a name="Ruby_nn12">34.3.1 Modules</a></H3> <p> The SWIG <tt>%module</tt> directive specifies @@ -519,7 +519,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">38.3.2 Functions</a></H3> +<H3><a name="Ruby_nn13">34.3.2 Functions</a></H3> <p> Global functions are wrapped as Ruby module methods. For @@ -553,7 +553,7 @@ irb(main):002:0> <b>Example.fact(4)</b> 24</pre> </div> -<H3><a name="Ruby_nn14">38.3.3 Variable Linking</a></H3> +<H3><a name="Ruby_nn14">34.3.3 Variable Linking</a></H3> <p> C/C++ global variables are wrapped as a pair of singleton @@ -615,7 +615,7 @@ directive. For example: </p> effect until it is explicitly disabled using <tt>%mutable</tt>. </p> -<H3><a name="Ruby_nn15">38.3.4 Constants</a></H3> +<H3><a name="Ruby_nn15">34.3.4 Constants</a></H3> <p> C/C++ constants are wrapped as module constants initialized @@ -643,7 +643,7 @@ irb(main):002:0> <b>Example::PI</b> 3.14159</pre> </div> -<H3><a name="Ruby_nn16">38.3.5 Pointers</a></H3> +<H3><a name="Ruby_nn16">34.3.5 Pointers</a></H3> <p> "Opaque" pointers to arbitrary C/C++ types (i.e. types that @@ -667,7 +667,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">38.3.6 Structures</a></H3> +<H3><a name="Ruby_nn17">34.3.6 Structures</a></H3> <p> C/C++ structs are wrapped as Ruby classes, with accessor @@ -772,7 +772,7 @@ void Bar_f_set(Bar *b, Foo *val) { }</pre> </div> -<H3><a name="Ruby_nn18">38.3.7 C++ classes</a></H3> +<H3><a name="Ruby_nn18">34.3.7 C++ classes</a></H3> <p> Like structs, C++ classes are wrapped by creating a new Ruby @@ -827,7 +827,7 @@ Ale 3</pre> </div> -<H3><a name="Ruby_nn19">38.3.8 C++ Inheritance</a></H3> +<H3><a name="Ruby_nn19">34.3.8 C++ Inheritance</a></H3> <p> The SWIG type-checker is fully aware of C++ inheritance. @@ -980,7 +980,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">38.3.9 C++ Overloaded Functions</a></H3> +<H3><a name="Ruby_nn20">34.3.9 C++ Overloaded Functions</a></H3> <p> C++ overloaded functions, methods, and constructors are @@ -1070,7 +1070,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">38.3.10 C++ Operators</a></H3> +<H3><a name="Ruby_nn21">34.3.10 C++ Operators</a></H3> <p> For the most part, overloaded operators are handled @@ -1112,7 +1112,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">38.3.11 C++ namespaces</a></H3> +<H3><a name="Ruby_nn22">34.3.11 C++ namespaces</a></H3> <p> SWIG is aware of C++ namespaces, but namespace names do not @@ -1169,7 +1169,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">38.3.12 C++ templates</a></H3> +<H3><a name="Ruby_nn23">34.3.12 C++ templates</a></H3> <p> C++ templates don't present a huge problem for SWIG. However, @@ -1211,7 +1211,7 @@ irb(main):004:0> <b>p.second</b> 4</pre> </div> -<H3><a name="Ruby_nn23_1">38.3.13 C++ Standard Template Library (STL)</a></H3> +<H3><a name="Ruby_nn23_1">34.3.13 C++ Standard Template Library (STL)</a></H3> <p> On a related note, the standard SWIG library contains a @@ -1304,7 +1304,7 @@ 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">38.3.14 C++ STL Functors</a></H3> +<H3><a name="Ruby_C_STL_Functors">34.3.14 C++ STL Functors</a></H3> <p>Some containers in the STL allow you to modify their default @@ -1365,7 +1365,7 @@ b </pre> </div> -<H3><a name="Ruby_C_Iterators">38.3.15 C++ STL Iterators</a></H3> +<H3><a name="Ruby_C_Iterators">34.3.15 C++ STL Iterators</a></H3> <p>The STL is well known for the use of iterators. There @@ -1448,10 +1448,10 @@ i <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">38.3.16 C++ Smart Pointers</a></H3> +<H3><a name="Ruby_nn24">34.3.16 C++ Smart Pointers</a></H3> -<H4><a name="Ruby_smart_pointers_shared_ptr">38.3.16.1 The shared_ptr Smart Pointer</a></H4> +<H4><a name="Ruby_smart_pointers_shared_ptr">34.3.16.1 The shared_ptr Smart Pointer</a></H4> <p> @@ -1462,7 +1462,7 @@ in the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a </p> -<H4><a name="Ruby_smart_pointers_generic">38.3.16.2 Generic Smart Pointers</a></H4> +<H4><a name="Ruby_smart_pointers_generic">34.3.16.2 Generic Smart Pointers</a></H4> <p> In certain C++ programs, it is common to use classes that @@ -1527,7 +1527,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">38.3.17 Cross-Language Polymorphism</a></H3> +<H3><a name="Ruby_nn25">34.3.17 Cross-Language Polymorphism</a></H3> <p> SWIG's Ruby module supports cross-language polymorphism @@ -1536,7 +1536,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">38.3.17.1 Exception Unrolling</a></H4> +<H4><a name="Ruby_nn26">34.3.17.1 Exception Unrolling</a></H4> <p> Whenever a C++ director class routes one of its virtual @@ -1559,7 +1559,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">38.4 Naming</a></H2> +<H2><a name="Ruby_nn27">34.4 Naming</a></H2> <p>Ruby has several common naming conventions. Constants are @@ -1597,7 +1597,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">38.4.1 Defining Aliases</a></H3> +<H3><a name="Ruby_nn28">34.4.1 Defining Aliases</a></H3> <p> It's a fairly common practice in the Ruby built-ins and @@ -1667,7 +1667,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">38.4.2 Predicate Methods</a></H3> +<H3><a name="Ruby_nn29">34.4.2 Predicate Methods</a></H3> <p> Ruby methods that return a boolean value and end in a @@ -1716,7 +1716,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">38.4.3 Bang Methods</a></H3> +<H3><a name="Ruby_nn30">34.4.3 Bang Methods</a></H3> <p> Ruby methods that modify an object in-place and end in an @@ -1748,7 +1748,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">38.4.4 Getters and Setters</a></H3> +<H3><a name="Ruby_nn31">34.4.4 Getters and Setters</a></H3> <p> Often times a C++ library will expose properties through @@ -1783,7 +1783,7 @@ irb(main):003:0> <b>puts foo.value</b></pre> %rename("value=") Foo::setValue(int value);</pre> </div> -<H2><a name="Ruby_nn32">38.5 Input and output parameters</a></H2> +<H2><a name="Ruby_nn32">34.5 Input and output parameters</a></H2> <p> A common problem in some C programs is handling parameters @@ -1922,10 +1922,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">38.6 Exception handling </a></H2> +<H2><a name="Ruby_nn33">34.6 Exception handling </a></H2> -<H3><a name="Ruby_nn34">38.6.1 Using the %exception directive </a></H3> +<H3><a name="Ruby_nn34">34.6.1 Using the %exception directive </a></H3> <p>The SWIG <tt>%exception</tt> directive can be @@ -2034,7 +2034,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">38.6.2 Handling Ruby Blocks </a></H3> +<H3><a name="Ruby_nn34_2">34.6.2 Handling Ruby Blocks </a></H3> <p>One of the highlights of Ruby and most of its standard library @@ -2101,7 +2101,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">38.6.3 Raising exceptions </a></H3> +<H3><a name="Ruby_nn35">34.6.3 Raising exceptions </a></H3> <p>There are three ways to raise exceptions from C++ code to @@ -2258,7 +2258,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">38.6.4 Exception classes </a></H3> +<H3><a name="Ruby_nn36">34.6.4 Exception classes </a></H3> <p>Starting with SWIG 1.3.28, the Ruby module supports the <tt>%exceptionclass</tt> @@ -2295,7 +2295,7 @@ end </pre> <p>For another example look at swig/Examples/ruby/exception_class. </p> -<H2><a name="Ruby_nn37">38.7 Typemaps</a></H2> +<H2><a name="Ruby_nn37">34.7 Typemaps</a></H2> <p> This section describes how you can modify SWIG's default @@ -2310,7 +2310,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">38.7.1 What is a typemap?</a></H3> +<H3><a name="Ruby_nn38">34.7.1 What is a typemap?</a></H3> <p> A typemap is nothing more than a code generation rule that is @@ -2467,7 +2467,7 @@ to be used as follows (notice how the length parameter is omitted): </p> 2</pre> </div> -<H3><a name="Ruby_Typemap_scope">38.7.2 Typemap scope</a></H3> +<H3><a name="Ruby_Typemap_scope">34.7.2 Typemap scope</a></H3> <p> Once defined, a typemap remains in effect for all of the @@ -2513,7 +2513,7 @@ where the class itself is defined. For example:</p> };</pre> </div> -<H3><a name="Ruby_Copying_a_typemap">38.7.3 Copying a typemap</a></H3> +<H3><a name="Ruby_Copying_a_typemap">34.7.3 Copying a typemap</a></H3> <p> A typemap is copied by using assignment. For example:</p> @@ -2555,7 +2555,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">38.7.4 Deleting a typemap</a></H3> +<H3><a name="Ruby_Deleting_a_typemap">34.7.4 Deleting a typemap</a></H3> <p> A typemap can be deleted by simply defining no code. For @@ -2580,7 +2580,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">38.7.5 Placement of typemaps</a></H3> +<H3><a name="Ruby_Placement_of_typemaps">34.7.5 Placement of typemaps</a></H3> <p> Typemap declarations can be declared in the global scope, @@ -2651,13 +2651,13 @@ In this example, this is done using the class declaration <tt>class string</tt> .</p> -<H3><a name="Ruby_nn39">38.7.6 Ruby typemaps</a></H3> +<H3><a name="Ruby_nn39">34.7.6 Ruby typemaps</a></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">38.7.6.1 "in" typemap</a></H4> +<H4><a name="Ruby_in_typemap">34.7.6.1 "in" typemap</a></H4> <p>Converts Ruby objects to input @@ -2724,7 +2724,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">38.7.6.2 "typecheck" typemap</a></H4> +<H4><a name="Ruby_typecheck_typemap">34.7.6.2 "typecheck" typemap</a></H4> <p> The "typecheck" typemap is used to support overloaded @@ -2746,7 +2746,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">38.7.6.3 "out" typemap</a></H4> +<H4><a name="Ruby_out_typemap">34.7.6.3 "out" typemap</a></H4> <p>Converts return value of a C function @@ -2797,7 +2797,7 @@ version of the C datatype matched by the typemap.</td> </table> </div> -<H4><a name="Ruby_arginit_typemap">38.7.6.4 "arginit" typemap</a></H4> +<H4><a name="Ruby_arginit_typemap">34.7.6.4 "arginit" typemap</a></H4> <p> The "arginit" typemap is used to set the initial value of a @@ -2812,7 +2812,7 @@ applications. For example:</p> }</pre> </div> -<H4><a name="Ruby_default_typemap">38.7.6.5 "default" typemap</a></H4> +<H4><a name="Ruby_default_typemap">34.7.6.5 "default" typemap</a></H4> <p> The "default" typemap is used to turn an argument into a @@ -2837,7 +2837,7 @@ arguments that follow must have default values. See the <a href="SWIG.html#SWIG_ Default/optional arguments</a> section for further information on default argument wrapping.</p> -<H4><a name="Ruby_check_typemap">38.7.6.6 "check" typemap</a></H4> +<H4><a name="Ruby_check_typemap">34.7.6.6 "check" typemap</a></H4> <p> The "check" typemap is used to supply value checking code @@ -2852,7 +2852,7 @@ arguments have been converted. For example:</p> }</pre> </div> -<H4><a name="Ruby_argout_typemap_">38.7.6.7 "argout" typemap</a></H4> +<H4><a name="Ruby_argout_typemap_">34.7.6.7 "argout" typemap</a></H4> <p> The "argout" typemap is used to return values from arguments. @@ -2906,7 +2906,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_">38.7.6.8 "freearg" typemap</a></H4> +<H4><a name="Ruby_freearg_typemap_">34.7.6.8 "freearg" typemap</a></H4> <p> The "freearg" typemap is used to cleanup argument data. It is @@ -2933,7 +2933,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">38.7.6.9 "newfree" typemap</a></H4> +<H4><a name="Ruby_newfree_typemap">34.7.6.9 "newfree" typemap</a></H4> <p> The "newfree" typemap is used in conjunction with the <tt>%newobject</tt> @@ -2957,7 +2957,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">38.7.6.10 "memberin" typemap</a></H4> +<H4><a name="Ruby_memberin_typemap">34.7.6.10 "memberin" typemap</a></H4> <p> The "memberin" typemap is used to copy data from<em> an @@ -2975,21 +2975,21 @@ example:</p> already provides a default implementation for arrays, strings, and other objects.</p> -<H4><a name="Ruby_varin_typemap">38.7.6.11 "varin" typemap</a></H4> +<H4><a name="Ruby_varin_typemap">34.7.6.11 "varin" typemap</a></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_">38.7.6.12 "varout" typemap</a></H4> +<H4><a name="Ruby_varout_typemap_">34.7.6.12 "varout" typemap</a></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">38.7.6.13 "throws" typemap</a></H4> +<H4><a name="Ruby_throws_typemap">34.7.6.13 "throws" typemap</a></H4> <p> The "throws" typemap is only used when SWIG parses a C++ @@ -3030,7 +3030,7 @@ 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="Customization.html#Customization_exception">Exception handling with %exception</a> section.</p> -<H4><a name="Ruby_directorin_typemap">38.7.6.14 directorin typemap</a></H4> +<H4><a name="Ruby_directorin_typemap">34.7.6.14 directorin typemap</a></H4> <p>Converts C++ objects in director @@ -3089,7 +3089,7 @@ referring to the class itself.</td> </table> </div> -<H4><a name="Ruby_directorout_typemap">38.7.6.15 directorout typemap</a></H4> +<H4><a name="Ruby_directorout_typemap">34.7.6.15 directorout typemap</a></H4> <p>Converts Ruby objects in director @@ -3162,7 +3162,7 @@ exception. </p> -<H4><a name="Ruby_directorargout_typemap">38.7.6.16 directorargout typemap</a></H4> +<H4><a name="Ruby_directorargout_typemap">34.7.6.16 directorargout typemap</a></H4> <p>Output argument processing in director @@ -3220,19 +3220,19 @@ referring to the instance of the class itself</td> </table> </div> -<H4><a name="Ruby_ret_typemap">38.7.6.17 ret typemap</a></H4> +<H4><a name="Ruby_ret_typemap">34.7.6.17 ret typemap</a></H4> <p>Cleanup of function return values </p> -<H4><a name="Ruby_globalin_typemap">38.7.6.18 globalin typemap</a></H4> +<H4><a name="Ruby_globalin_typemap">34.7.6.18 globalin typemap</a></H4> <p>Setting of C global variables </p> -<H3><a name="Ruby_nn40">38.7.7 Typemap variables</a></H3> +<H3><a name="Ruby_nn40">34.7.7 Typemap variables</a></H3> <p> @@ -3282,7 +3282,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">38.7.8 Useful Functions</a></H3> +<H3><a name="Ruby_nn41">34.7.8 Useful Functions</a></H3> <p> When you write a typemap, you usually have to work directly @@ -3297,7 +3297,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">38.7.8.1 C Datatypes to Ruby Objects</a></H4> +<H4><a name="Ruby_nn42">34.7.8.1 C Datatypes to Ruby Objects</a></H4> <div class="diagram"> @@ -3339,11 +3339,11 @@ SWIG_From_float(float)</td> </table> </div> -<H4><a name="Ruby_nn43">38.7.8.2 Ruby Objects to C Datatypes</a></H4> +<H4><a name="Ruby_nn43">34.7.8.2 Ruby Objects to C Datatypes</a></H4> <p>Here, while the Ruby versions return the value directly, the SWIG -versions do not, but return a status value to indicate success (<tt>SWIG_OK</tt>). While more akward to use, this allows you to write typemaps that report more helpful error messages, like:</p> +versions do not, but return a status value to indicate success (<tt>SWIG_OK</tt>). While more awkward to use, this allows you to write typemaps that report more helpful error messages, like:</p> <div class="code"> <pre> @@ -3407,7 +3407,7 @@ versions do not, but return a status value to indicate success (<tt>SWIG_OK</tt> </table> </div> -<H4><a name="Ruby_nn44">38.7.8.3 Macros for VALUE</a></H4> +<H4><a name="Ruby_nn44">34.7.8.3 Macros for VALUE</a></H4> <p> <tt>RSTRING_LEN(str)</tt> </p> @@ -3430,7 +3430,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">38.7.8.4 Exceptions</a></H4> +<H4><a name="Ruby_nn45">34.7.8.4 Exceptions</a></H4> <p> <tt>void rb_raise(VALUE exception, const char *fmt, @@ -3509,7 +3509,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">38.7.8.5 Iterators</a></H4> +<H4><a name="Ruby_nn46">34.7.8.5 Iterators</a></H4> <p> <tt>void rb_iter_break()</tt> </p> @@ -3555,14 +3555,14 @@ VALUE), VALUE value)</tt></p> <div class="indent"> Equivalent to Ruby's <tt>throw</tt>. </div> -<H3><a name="Ruby_nn47">38.7.9 Typemap Examples</a></H3> +<H3><a name="Ruby_nn47">34.7.9 Typemap Examples</a></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">38.7.10 Converting a Ruby array to a char **</a></H3> +<H3><a name="Ruby_nn48">34.7.10 Converting a Ruby array to a char **</a></H3> <p> A common problem in many C programs is the processing of @@ -3627,7 +3627,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">38.7.11 Collecting arguments in a hash</a></H3> +<H3><a name="Ruby_nn49">34.7.11 Collecting arguments in a hash</a></H3> <p> Ruby's solution to the "keyword arguments" capability of some @@ -3704,7 +3704,7 @@ value: </p> <pre>%typemap(in) (int nattributes, const char **names, const int *values) (VALUE keys_arr, int i, VALUE key, VALUE val) { Check_Type($input, T_HASH); - <b>$1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));</b> + <b>$1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, Qnil));</b> }</pre> </div> @@ -3717,7 +3717,7 @@ the keys and values from the hash: </p> <pre>%typemap(in) (int nattributes, const char **names, const int *values) (VALUE keys_arr, int i, VALUE key, VALUE val) { Check_Type($input, T_HASH); - $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL)); + $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, Qnil)); <b>$2 = NULL; $3 = NULL; if ($1 > 0) { @@ -3736,13 +3736,13 @@ of the keys) and then start looping over the elements in that array: </p> <pre>%typemap(in) (int nattributes, const char **names, const int *values) (VALUE keys_arr, int i, VALUE key, VALUE val) { Check_Type($input, T_HASH); - $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL)); + $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, Qnil)); $2 = NULL; $3 = NULL; if ($1 > 0) { $2 = (char **) malloc($1*sizeof(char *)); $3 = (int *) malloc($1*sizeof(int)); - <b>keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL); + <b>keys_arr = rb_funcall($input, rb_intern("keys"), 0, Qnil); for (i = 0; i < $1; i++) { }</b> } @@ -3758,13 +3758,13 @@ corresponding to that key in the hash: </p> <pre>%typemap(in) (int nattributes, const char **names, const int *values) (VALUE keys_arr, int i, VALUE key, VALUE val) { Check_Type($input, T_HASH); - $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL)); + $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, Qnil)); $2 = NULL; $3 = NULL; if ($1 > 0) { $2 = (char **) malloc($1*sizeof(char *)); $3 = (int *) malloc($1*sizeof(int)); - keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL); + keys_arr = rb_funcall($input, rb_intern("keys"), 0, Qnil); for (i = 0; i < $1; i++) { <b>key = rb_ary_entry(keys_arr, i); val = rb_hash_aref($input, key);</b> @@ -3781,13 +3781,13 @@ value is a <tt>Fixnum</tt>: </p> <pre>%typemap(in) (int nattributes, const char **names, const int *values) (VALUE keys_arr, int i, VALUE key, VALUE val) { Check_Type($input, T_HASH); - $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL)); + $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, Qnil)); $2 = NULL; $3 = NULL; if ($1 > 0) { $2 = (char **) malloc($1*sizeof(char *)); $3 = (int *) malloc($1*sizeof(int)); - keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL); + keys_arr = rb_funcall($input, rb_intern("keys"), 0, Qnil); for (i = 0; i < $1; i++) { key = rb_ary_entry(keys_arr, i); val = rb_hash_aref($input, key); @@ -3805,13 +3805,13 @@ equivalents and store them in our local C arrays: </p> <pre>%typemap(in) (int nattributes, const char **names, const int *values) (VALUE keys_arr, int i, VALUE key, VALUE val) { Check_Type($input, T_HASH); - $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL)); + $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, Qnil)); $2 = NULL; $3 = NULL; if ($1 > 0) { $2 = (char **) malloc($1*sizeof(char *)); $3 = (int *) malloc($1*sizeof(int)); - keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL); + keys_arr = rb_funcall($input, rb_intern("keys"), 0, Qnil); for (i = 0; i < $1; i++) { key = rb_ary_entry(keys_arr, i); val = rb_hash_aref($input, key); @@ -3841,7 +3841,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">38.7.12 Pointer handling</a></H3> +<H3><a name="Ruby_nn50">34.7.12 Pointer handling</a></H3> <p> Occasionally, it might be necessary to convert pointer values @@ -3900,7 +3900,7 @@ For example: </p> }</pre> </div> -<H4><a name="Ruby_nn51">38.7.12.1 Ruby Datatype Wrapping</a></H4> +<H4><a name="Ruby_nn51">34.7.12.1 Ruby Datatype Wrapping</a></H4> <p> <tt>VALUE Data_Wrap_Struct(VALUE class, void @@ -3927,7 +3927,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">38.7.13 Example: STL Vector to Ruby Array</a></H3> +<H3><a name="Ruby_nn52">34.7.13 Example: STL Vector to Ruby Array</a></H3> <p>Another use for macros and type maps is to create a Ruby array @@ -4019,7 +4019,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">38.8 Docstring Features</a></H2> +<H2><a name="Ruby_nn65">34.8 Docstring Features</a></H2> <p> @@ -4053,7 +4053,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">38.8.1 Module docstring</a></H3> +<H3><a name="Ruby_nn66">34.8.1 Module docstring</a></H3> <p> @@ -4083,7 +4083,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">38.8.2 %feature("autodoc")</a></H3> +<H3><a name="Ruby_nn67">34.8.2 %feature("autodoc")</a></H3> <p>Since SWIG does know everything about the function it wraps, @@ -4104,7 +4104,7 @@ several options for autodoc controlled by the value given to the feature, described below. </p> -<H4><a name="Ruby_nn68">38.8.2.1 %feature("autodoc", "0")</a></H4> +<H4><a name="Ruby_nn68">34.8.2.1 %feature("autodoc", "0")</a></H4> <p> @@ -4128,7 +4128,7 @@ Then Ruby code like this will be generated: ...</pre> </div> -<H4><a name="Ruby_autodoc1">38.8.2.2 %feature("autodoc", "1")</a></H4> +<H4><a name="Ruby_autodoc1">34.8.2.2 %feature("autodoc", "1")</a></H4> <p> @@ -4148,7 +4148,7 @@ this: ...</pre> </div> -<H4><a name="Ruby_autodoc2">38.8.2.3 %feature("autodoc", "2")</a></H4> +<H4><a name="Ruby_autodoc2">34.8.2.3 %feature("autodoc", "2")</a></H4> <p> @@ -4160,7 +4160,7 @@ parameter types with the "2" option will result in Ruby code like this: </p> -<H4><a name="Ruby_feature_autodoc3">38.8.2.4 %feature("autodoc", "3")</a></H4> +<H4><a name="Ruby_feature_autodoc3">34.8.2.4 %feature("autodoc", "3")</a></H4> <p> @@ -4181,7 +4181,7 @@ Parameters: bar - Bar</pre> </div> -<H4><a name="Ruby_nn70">38.8.2.5 %feature("autodoc", "docstring")</a></H4> +<H4><a name="Ruby_nn70">34.8.2.5 %feature("autodoc", "docstring")</a></H4> <p> @@ -4197,7 +4197,7 @@ generated string. For example: void GetPosition(int* OUTPUT, int* OUTPUT);</pre> </div> -<H3><a name="Ruby_nn71">38.8.3 %feature("docstring")</a></H3> +<H3><a name="Ruby_nn71">34.8.3 %feature("docstring")</a></H3> <p> @@ -4208,10 +4208,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">38.9 Advanced Topics</a></H2> +<H2><a name="Ruby_nn53">34.9 Advanced Topics</a></H2> -<H3><a name="Ruby_operator_overloading">38.9.1 Operator overloading</a></H3> +<H3><a name="Ruby_operator_overloading">34.9.1 Operator overloading</a></H3> <p> SWIG allows operator overloading with, by using the <tt>%extend</tt> @@ -4392,7 +4392,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">38.9.2 Creating Multi-Module Packages</a></H3> +<H3><a name="Ruby_nn55">34.9.2 Creating Multi-Module Packages</a></H3> <p> The chapter on <a href="Modules.html#Modules">Working @@ -4518,7 +4518,7 @@ irb(main):005:0> <b>c.getX()</b> 5.0</pre> </div> -<H3><a name="Ruby_nn56">38.9.3 Specifying Mixin Modules</a></H3> +<H3><a name="Ruby_nn56">34.9.3 Specifying Mixin Modules</a></H3> <p> The Ruby language doesn't support multiple inheritance, but @@ -4585,7 +4585,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">38.10 Memory Management</a></H2> +<H2><a name="Ruby_nn57">34.10 Memory Management</a></H2> <p>One of the most common issues in generating SWIG bindings for @@ -4608,7 +4608,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">38.10.1 Mark and Sweep Garbage Collector </a></H3> +<H3><a name="Ruby_nn58">34.10.1 Mark and Sweep Garbage Collector </a></H3> <p>Ruby uses a mark and sweep garbage collector. When the garbage @@ -4639,7 +4639,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">38.10.2 Object Ownership</a></H3> +<H3><a name="Ruby_nn59">34.10.2 Object Ownership</a></H3> <p>As described above, memory management depends on clearly @@ -4784,7 +4784,7 @@ public: <p> This code can be seen in swig/examples/ruby/tracking.</p> -<H3><a name="Ruby_nn60">38.10.3 Object Tracking</a></H3> +<H3><a name="Ruby_nn60">34.10.3 Object Tracking</a></H3> <p>The remaining parts of this section will use the class library @@ -5010,7 +5010,7 @@ 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> methods.</p> -<H3><a name="Ruby_nn61">38.10.4 Mark Functions</a></H3> +<H3><a name="Ruby_nn61">34.10.4 Mark Functions</a></H3> <p>With a bit more testing, we see that our class library still @@ -5139,7 +5139,7 @@ irb(main):016:0></pre> <p>This code can be seen in swig/examples/ruby/mark_function.</p> -<H3><a name="Ruby_nn62">38.10.5 Free Functions</a></H3> +<H3><a name="Ruby_nn62">34.10.5 Free Functions</a></H3> <p>By default, SWIG creates a "free" function that is called when @@ -5307,7 +5307,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">38.10.6 Embedded Ruby and the C++ Stack</a></H3> +<H3><a name="Ruby_nn63">34.10.6 Embedded Ruby and the C++ Stack</a></H3> <p>As has been said, the Ruby GC runs and marks objects before diff --git a/Doc/Manual/SWIG.html b/Doc/Manual/SWIG.html index e5b441fbb..aec48ef03 100644 --- a/Doc/Manual/SWIG.html +++ b/Doc/Manual/SWIG.html @@ -88,7 +88,7 @@ <p> This chapter describes the basic operation of SWIG, the structure of its -input files, and how it handles standard ANSI C declarations. C++ support is +input files, and how it handles standard ISO C declarations. C++ support is described in the next chapter. However, C++ programmers should still read this chapter to understand the basics. Specific details about each target language are described in later @@ -103,71 +103,156 @@ To run SWIG, use the <tt>swig</tt> command with options and a filename like this </p> <div class="shell"><pre> -swig [ <em>options</em> ] filename +swig [ options ] filename </pre></div> <p> where <tt>filename</tt> is a SWIG interface file or a C/C++ header file. -Below is a subset of <em>options</em> that can be used. +Full help can be seen by running <tt>swig -help</tt>. +Below is the common set of options that can be used. Additional options are also defined for each target language. A full list -can be obtained by typing <tt>swig -help</tt> or <tt>swig -<em>-<lang></em> -help</tt> for language <em><lang></em> specific options. +can be obtained by running <tt>swig +<em>-<lang></em> -help</tt> for language <em><lang></em> specific options, +for example, <tt>swig -ruby -help</tt> for Ruby. </p> <div class="shell"><pre> --allegrocl Generate ALLEGROCL wrappers --chicken Generate CHICKEN wrappers --clisp Generate CLISP wrappers --cffi Generate CFFI wrappers --csharp Generate C# wrappers --d Generate D wrappers --go Generate Go wrappers --guile Generate Guile wrappers --java Generate Java wrappers --javascript Generate Javascript wrappers --lua Generate Lua wrappers --modula3 Generate Modula 3 wrappers --mzscheme Generate Mzscheme wrappers --ocaml Generate Ocaml wrappers --octave Generate Octave wrappers --perl Generate Perl wrappers --php5 Generate PHP5 wrappers --php7 Generate PHP7 wrappers --pike Generate Pike wrappers --python Generate Python wrappers --r Generate R (aka GNU S) wrappers --ruby Generate Ruby wrappers --scilab Generate Scilab wrappers --sexp Generate Lisp S-Expressions wrappers --tcl Generate Tcl wrappers --uffi Generate Common Lisp / UFFI wrappers --xml Generate XML wrappers - --c++ Enable C++ processing --cppext <em>ext</em> Change file extension of C++ generated files to <em>ext</em> - (default is cxx, except for PHP5 which uses cpp) --D<em>symbol</em> Define a preprocessor symbol --Fmicrosoft Display error/warning messages in Microsoft format --Fstandard Display error/warning messages in commonly used format --help Display all options --I<em>dir</em> Add a directory to the file include path --l<em>ifile</em> Include SWIG library file <ifile> --module <em>name</em> Set the name of the SWIG module --o <em>outfile</em> Set name of C/C++ output file to <outfile> --oh <em>headfile</em> Set name of C++ output header file for directors to <headfile> --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 Report location of SWIG library and exit --version Display SWIG version number +Supported Target Language Options + -csharp - Generate C# wrappers + -d - Generate D wrappers + -go - Generate Go wrappers + -guile - Generate Guile wrappers + -java - Generate Java wrappers + -javascript - Generate Javascript wrappers + -lua - Generate Lua wrappers + -octave - Generate Octave wrappers + -perl5 - Generate Perl 5 wrappers + -php7 - Generate PHP 7 wrappers + -python - Generate Python wrappers + -r - Generate R (aka GNU S) wrappers + -ruby - Generate Ruby wrappers + -scilab - Generate Scilab wrappers + -tcl8 - Generate Tcl 8 wrappers + -xml - Generate XML wrappers + +Experimental Target Language Options + -mzscheme - Generate MzScheme/Racket wrappers + -ocaml - Generate OCaml wrappers + +General Options + -addextern - Add extra extern declarations + -c++ - Enable C++ processing + -co <file> - Check <file> out of the SWIG library + -copyctor - Automatically generate copy constructors wherever possible + -cpperraswarn - Treat the preprocessor #error statement as #warning (default) + -cppext <ext> - Change file extension of generated C++ files to <ext> + (default is cxx) + -copyright - Display copyright notices + -debug-classes - Display information about the classes found in the interface + -debug-module <n>- Display module parse tree at stages 1-4, <n> is a csv list of stages + -debug-symtabs - Display symbol tables information + -debug-symbols - Display target language symbols in the symbol tables + -debug-csymbols - Display C symbols in the symbol tables + -debug-lsymbols - Display target language layer symbols + -debug-tags - Display information about the tags found in the interface + -debug-template - Display information for debugging templates + -debug-top <n> - Display entire parse tree at stages 1-4, <n> is a csv list of stages + -debug-typedef - Display information about the types and typedefs in the interface + -debug-typemap - Display typemap debugging information + -debug-tmsearch - Display typemap search debugging information + -debug-tmused - Display typemaps used debugging information + -directors - Turn on director mode for all the classes, mainly for testing + -dirprot - Turn on wrapping of protected members for director classes (default) + -D<symbol> - Define a symbol <symbol> (for conditional compilation) + -E - Preprocess only, does not generate wrapper code + -external-runtime [file] - Export the SWIG runtime stack + -fakeversion <v>- Make SWIG fake the program version number to <v> + -fcompact - Compile in compact mode + -features <list>- Set global features, where <list> is a comma separated list of + features, eg -features directors,autodoc=1 + If no explicit value is given to the feature, a default of 1 is used + -fastdispatch - Enable fast dispatch mode to produce faster overload dispatcher code + -Fmicrosoft - Display error/warning messages in Microsoft format + -Fstandard - Display error/warning messages in commonly used format + -fvirtual - Compile in virtual elimination mode + -help - Display help + -I- - Don't search the current directory + -I<dir> - Look for SWIG files in directory <dir> + -ignoremissing - Ignore missing include files + -importall - Follow all #include statements as imports + -includeall - Follow all #include statements + -l<ifile> - Include SWIG library file <ifile> + -macroerrors - Report errors inside macros + -makedefault - Create default constructors/destructors (the default) + -M - List all dependencies + -MD - Is equivalent to `-M -MF <file>', except `-E' is not implied + -MF <file> - Generate dependencies into <file> and continue generating wrappers + -MM - List dependencies, but omit files in SWIG library + -MMD - Like `-MD', but omit files in SWIG library + -module <name> - Set module name to <name> + -MP - Generate phony targets for all dependencies + -MT <target> - Set the target of the rule emitted by dependency generation + -nocontract - Turn off contract checking + -nocpperraswarn - Do not treat the preprocessor #error statement as #warning + -nodefault - Do not generate default constructors nor default destructors + -nodefaultctor - Do not generate implicit default constructors + -nodefaultdtor - Do not generate implicit default destructors + -nodirprot - Do not wrap director protected members + -noexcept - Do not wrap exception specifiers + -nofastdispatch - Disable fast dispatch mode (default) + -nopreprocess - Skip the preprocessor step + -notemplatereduce - Disable reduction of the typedefs in templates + -O - Enable the optimization options: + -fastdispatch -fvirtual + -o <outfile> - Set name of C/C++ output file to <outfile> + -oh <headfile> - Set name of C++ output header file for directors to <headfile> + -outcurrentdir - Set default output dir to current dir instead of input file's path + -outdir <dir> - Set language specific files output directory to <dir> + -pcreversion - Display PCRE version information + -small - Compile in virtual elimination and compact mode + -swiglib - Report location of SWIG library and exit + -templatereduce - Reduce all the typedefs in templates + -v - Run in verbose mode + -version - Display SWIG version number + -Wall - Remove all warning suppression, also implies -Wextra + -Wallkw - Enable keyword warnings for all the supported languages + -Werror - Treat warnings as errors + -Wextra - Adds the following additional warnings: 202,309,403,405,512,321,322 + -w<list> - Suppress/add warning messages, eg -w401,+321 - see Warnings.html + -xmlout <file> - Write XML version of the parse tree to <file> after normal processing +</pre></div> + +<p> +Arguments may also be passed in a command-line options file (also known as a +response file) which is useful if they exceed the system command line length +limit. To do this, put the arguments in a file, then provide the file name +prefixed with <tt>@</tt> like so: +</p> +<div class="shell"><pre> +swig @<em>file</em> </pre></div> +<p> +The options read from the file are inserted in place of the file option. If the +file does not exist, or cannot be read, then the option will be treated +literally and not removed. +</p> + +<p> +Options in the file are separated by whitespace. A whitespace character may be +included in an option by surrounding the entire option in either single or +double quotes. Any character (including a backslash) may be included by +prefixing the character to be included with a backslash. The file may itself +contain additional <tt>@file</tt> options; any such options will be processed +recursively. +</p> + <H3><a name="SWIG_nn3">5.1.1 Input format</a></H3> <p> -As input, SWIG expects a file containing ANSI C/C++ declarations and +As input, SWIG expects a file containing ISO C/C++ declarations and special SWIG directives. More often than not, this is a special SWIG interface file which is usually denoted with a special <tt>.i</tt> or <tt>.swg</tt> suffix. In certain cases, SWIG can be used directly on @@ -185,7 +270,7 @@ The most common format of a SWIG interface is as follows: %{ #include "myheader.h" %} -// Now list ANSI C/C++ declarations +// Now list ISO C/C++ declarations int foo; int bar(int x); ... @@ -389,7 +474,7 @@ For example /* bar not wrapped unless foo has been defined and the declaration of bar within foo has already been parsed */ int foo::bar(int) { - ... whatever ... + ... whatever ... } </pre> </div> @@ -1043,14 +1128,14 @@ expect :</p> <div class="targetlang"><pre> # Copy a file def filecopy(source, target): - f1 = fopen(source, "r") - f2 = fopen(target, "w") - buffer = malloc(8192) - nbytes = fread(buffer, 8192, 1, f1) - while (nbytes > 0): - fwrite(buffer, 8192, 1, f2) - nbytes = fread(buffer, 8192, 1, f1) - free(buffer) + f1 = fopen(source, "r") + f2 = fopen(target, "w") + buffer = malloc(8192) + nbytes = fread(buffer, 8192, 1, f1) + while (nbytes > 0): + fwrite(buffer, 8192, 1, f2) + nbytes = fread(buffer, 8192, 1, f1) + free(buffer) </pre></div> <p> @@ -1236,9 +1321,9 @@ creating a wrapper equivalent to the following: <div class="code"><pre> double wrap_dot_product(Vector *a, Vector *b) { - Vector x = *a; - Vector y = *b; - return dot_product(x, y); + Vector x = *a; + Vector y = *b; + return dot_product(x, y); } </pre></div> @@ -1266,12 +1351,12 @@ pointers. As a result, SWIG creates a wrapper like this: <div class="code"><pre> Vector *wrap_cross_product(Vector *v1, Vector *v2) { - Vector x = *v1; - Vector y = *v2; - Vector *result; - result = (Vector *) malloc(sizeof(Vector)); - *(result) = cross(x, y); - return result; + Vector x = *v1; + Vector y = *v2; + Vector *result; + result = (Vector *) malloc(sizeof(Vector)); + *(result) = cross(x, y); + return result; } </pre></div> @@ -1280,10 +1365,10 @@ or if SWIG was run with the <tt>-c++</tt> option:</p> <div class="code"><pre> Vector *wrap_cross(Vector *v1, Vector *v2) { - Vector x = *v1; - Vector y = *v2; - Vector *result = new Vector(cross(x, y)); // Uses default copy constructor - return result; + Vector x = *v1; + Vector y = *v2; + Vector *result = new Vector(cross(x, y)); // Uses default copy constructor + return result; } </pre></div> @@ -1737,6 +1822,16 @@ careful about namespaces and your use of modules, you can usually avoid these problems.</p> <p> +When wrapping C code, simple use of identifiers/symbols with <tt>%rename</tt> usually suffices. +When wrapping C++ code, simple use of simple identifiers/symbols with <tt>%rename</tt> might be too +limiting when using C++ features such as function overloading, default arguments, namespaces, template specialization etc. +If you are using the <tt>%rename</tt> directive and C++, make sure you read the +<a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a> chapter and in particular the section on +<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a> +for method overloading and default arguments. +</p> + +<p> Closely related to <tt>%rename</tt> is the <tt>%ignore</tt> directive. <tt>%ignore</tt> instructs SWIG to ignore declarations that match a given identifier. For example: </p> @@ -2078,7 +2173,7 @@ except those consisting of capital letters only: <p> Finally, variants of <tt>%rename</tt> and <tt>%ignore</tt> directives can be used to help wrap C++ overloaded functions and methods or C++ methods which use default arguments. This is described in the -<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> section in the C++ chapter. +<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a> section in the C++ chapter. </p> @@ -2147,7 +2242,7 @@ used in Tcl as follows :</p> </pre></div> <p> -Although the ANSI C standard does not allow default arguments, default +Although the ISO C standard does not allow default arguments, default arguments specified in a SWIG interface work with both C and C++. </p> @@ -2167,7 +2262,7 @@ in the C++ chapter for further details. <p> Occasionally, a C library may include functions that expect to receive pointers to functions--possibly to serve as callbacks. SWIG -provides full support for function pointers provided that the callback +provides full support for function pointers when the callback functions are defined in C and not in the target language. For example, consider a function like this: </p> @@ -2311,14 +2406,16 @@ And now, a final note about function pointer support. Although SWIG does not normally allow callback functions to be written in the target language, this can be accomplished with the use of typemaps and other advanced SWIG features. See the <a href="Typemaps.html#Typemaps">Typemaps chapter</a> for more about typemaps -and individual target language chapters for more on callbacks and the 'director' feature. +and individual target language chapters for more on callbacks. +The 'director' feature can be used to make callbacks from C/C++ into the target language, +see <a href="SWIGPlus.html#SWIGPlus_target_language_callbacks">Callbacks to the target language</a>. </p> <H2><a name="SWIG_nn31">5.5 Structures and unions</a></H2> <p> -This section describes the behavior of SWIG when processing ANSI C structures and union declarations. Extensions to +This section describes the behavior of SWIG when processing ISO C structures and union declarations. Extensions to handle C++ are described in the next section. </p> @@ -2368,10 +2465,10 @@ defined in the interface. For example: <div class="code"><pre> struct Vector *new_Vector() { - return (Vector *) calloc(1, sizeof(struct Vector)); + return (Vector *) calloc(1, sizeof(struct Vector)); } void delete_Vector(struct Vector *obj) { - free(obj); + free(obj); } </pre> </div> @@ -2602,10 +2699,10 @@ like this: <div class="code"> <pre> WORD Foo_w_get(Foo *f) { - return f->w; + return f->w; } void Foo_w_set(FOO *f, WORD value) { - f->w = value; + f->w = value; } </pre> </div> @@ -2896,7 +2993,7 @@ instead of a method. To do this, you might write some code like this: <pre> // Add a new attribute to Vector %extend Vector { - const double magnitude; + const double magnitude; } // Now supply the implementation of the Vector_magnitude_get function %{ @@ -3293,11 +3390,27 @@ Vector *new_Vector() { return (Vector *) malloc(sizeof(Vector)); } %} - </pre></div> <p> -The <tt>%inline</tt> directive inserts all of the code that follows +This is the same as writing: +</p> + +<div class="code"><pre> +%{ +/* Create a new vector */ +Vector *new_Vector() { + return (Vector *) malloc(sizeof(Vector)); +} +%} + +/* Create a new vector */ +Vector *new_Vector() { + return (Vector *) malloc(sizeof(Vector)); +} +</pre></div> +<p> +In other words, the <tt>%inline</tt> directive inserts all of the code that follows verbatim into the header portion of an interface file. The code is then parsed by both the SWIG preprocessor and parser. Thus, the above example creates a new command <tt>new_Vector</tt> using only one @@ -3305,6 +3418,11 @@ declaration. Since the code inside an <tt>%inline %{ ... %}</tt> block is given to both the C compiler and SWIG, it is illegal to include any SWIG directives inside a <tt>%{ ... %}</tt> block.</p> + +<p> +<b>Note:</b> The usual SWIG C preprocessor rules apply to code in <tt>%apply</tt> blocks when SWIG parses this code. For example, as mentioned earlier, <a href="SWIG.html#SWIG_nn6">SWIG's C Preprocessor</a> does not follow <tt>#include</tt> directives by default. +</p> + <H3><a name="SWIG_nn44">5.6.4 Initialization blocks</a></H3> @@ -3320,6 +3438,18 @@ initialization on module loading, you could write this: %} </pre></div> +<p> +Please note that some language backends (e.g. C# or Java) don't have any +initialization function, hence you should define a global object performing +the necessary initialization for them instead: +</p> + +<div class="code"><pre> +%init %{ + static struct MyInit { MyInit() { init_variables(); } } myInit; +%} +</pre></div> + <H2><a name="SWIG_nn45">5.7 An Interface Building Strategy</a></H2> @@ -3351,7 +3481,7 @@ interface to your program. SWIG's <tt>%include</tt> directive to process an entire C source/header file. -<li>Make sure everything in the interface file uses ANSI C/C++ syntax. +<li>Make sure everything in the interface file uses ISO C/C++ syntax. <li>Make sure all necessary `<tt>typedef</tt>' declarations and type-information is available in the interface file. diff --git a/Doc/Manual/SWIGPlus.html b/Doc/Manual/SWIGPlus.html index 3e7860b9b..dc9ae0f7e 100644 --- a/Doc/Manual/SWIGPlus.html +++ b/Doc/Manual/SWIGPlus.html @@ -31,7 +31,6 @@ <li><a href="#SWIGPlus_nn12">Static members</a> <li><a href="#SWIGPlus_member_data">Member data</a> </ul> -<li><a href="#SWIGPlus_default_args">Default arguments</a> <li><a href="#SWIGPlus_nn15">Protection</a> <li><a href="#SWIGPlus_nn16">Enums and constants</a> <li><a href="#SWIGPlus_nn17">Friends</a> @@ -39,16 +38,27 @@ <li><a href="#SWIGPlus_nn19">Pass and return by value</a> <li><a href="#SWIGPlus_nn20">Inheritance</a> <li><a href="#SWIGPlus_nn21">A brief discussion of multiple inheritance, pointers, and type checking</a> -<li><a href="#SWIGPlus_overloaded_methods">Wrapping Overloaded Functions and Methods</a> +<li><a href="#SWIGPlus_default_args">Default arguments</a> +<li><a href="#SWIGPlus_overloaded_methods">Overloaded functions and methods</a> <ul> <li><a href="#SWIGPlus_nn24">Dispatch function generation</a> -<li><a href="#SWIGPlus_nn25">Ambiguity in Overloading</a> -<li><a href="#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> +<li><a href="#SWIGPlus_nn25">Ambiguity in overloading</a> +<li><a href="#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a> <li><a href="#SWIGPlus_nn27">Comments on overloading</a> </ul> -<li><a href="#SWIGPlus_nn28">Wrapping overloaded operators</a> +<li><a href="#SWIGPlus_nn28">Overloaded operators</a> <li><a href="#SWIGPlus_class_extension">Class extension</a> <li><a href="#SWIGPlus_nn30">Templates</a> +<ul> +<li><a href="#SWIGPlus_template_directive">The %template directive</a> +<li><a href="#SWIGPlus_template_functions">Function templates</a> +<li><a href="#SWIGPlus_template_classes">Default template arguments</a> +<li><a href="#SWIGPlus_template_class_inheritance">Template base classes</a> +<li><a href="#SWIGPlus_template_specialization">Template specialization</a> +<li><a href="#SWIGPlus_template_member">Member templates</a> +<li><a href="#SWIGPlus_template_scoping">Scoping and templates</a> +<li><a href="#SWIGPlus_template_more">More on templates</a> +</ul> <li><a href="#SWIGPlus_namespaces">Namespaces</a> <ul> <li><a href="#SWIGPlus_nspace">The nspace feature for namespaces</a> @@ -62,6 +72,11 @@ <li><a href="#SWIGPlus_nn35">Using declarations and inheritance</a> <li><a href="#SWIGPlus_nested_classes">Nested classes</a> <li><a href="#SWIGPlus_const">A brief rant about const-correctness</a> +<li><a href="#SWIGPlus_target_language_callbacks">Callbacks to the target language</a> +<ul> +<li><a href="#SWIGPlus_director_classes_introduction">Introduction to director classes</a> +<li><a href="#SWIGPlus_directors_for_function_pointers">Using directors and target language callbacks</a> +</ul> <li><a href="#SWIGPlus_nn42">Where to go for more information</a> </ul> </div> @@ -70,9 +85,15 @@ <p> -This chapter describes SWIG's support for wrapping C++. As a prerequisite, +This chapter describes SWIG's support for wrapping C++. +It is mostly concerned about C++ as defined by the C++ 98 and 03 standards. +For additions to the original C++ standard, please read the +<a href="CPlusPlus11.html#CPlusPlus11">SWIG and C++11</a>, +<a href="CPlusPlus14.html#CPlusPlus14">SWIG and C++14</a> and +<a href="CPlusPlus17.html#CPlusPlus17">SWIG and C++17</a> chapters. +As a prerequisite, you should first read the chapter <a href="SWIG.html#SWIG">SWIG Basics</a> to see -how SWIG wraps ANSI C. Support for C++ builds upon ANSI C +how SWIG wraps ISO C. Support for C++ builds upon ISO C wrapping and that material will be useful in understanding this chapter. </p> @@ -123,7 +144,7 @@ yourself in the foot. You will just have to be careful. <p> To wrap C++, SWIG uses a layered approach to code generation. -At the lowest level, SWIG generates a collection of procedural ANSI-C style +At the lowest level, SWIG generates a collection of procedural ISO C style wrappers. These wrappers take care of basic type conversion, type checking, error handling, and other low-level details of the C++ binding. These wrappers are also sufficient to bind C++ into any target language @@ -346,8 +367,8 @@ public: class Spam { public: - Foo *value; - ... + Foo *value; + ... }; </pre> </div> @@ -706,7 +727,7 @@ class Foo { protected: Foo(); // Not wrapped. public: - ... + ... }; </pre> </div> @@ -726,7 +747,7 @@ public: class Grok : public Bar { public: - Grok(); // Not wrapped. No implementation of abstract spam(). + Grok(); // Not wrapped. No implementation of abstract spam(). }; </pre> </div> @@ -777,9 +798,9 @@ the normal constructor function. For example, if you have this: <pre> class List { public: - List(); - List(const List &); // Copy constructor - ... + List(); + List(const List &); // Copy constructor + ... }; </pre> </div> @@ -803,7 +824,7 @@ through a special function like this: <div class="code"> <pre> List *copy_List(List *f) { - return new List(*f); + return new List(*f); } </pre> </div> @@ -832,7 +853,7 @@ However, copy constructor wrappers can be generated if using the <tt>copyctor</t class List { public: - List(); + List(); }; </pre> </div> @@ -851,9 +872,9 @@ could be wrapped, but they had to be renamed. For example: <pre> class Foo { public: - Foo(); + Foo(); %name(CopyFoo) Foo(const Foo &); - ... + ... }; </pre> </div> @@ -969,8 +990,8 @@ not primitive types, such as classes. For instance, if you had another class lik <pre> class Foo { public: - List items; - ... + List items; + ... </pre> </div> @@ -982,10 +1003,10 @@ For example: <div class="code"> <pre> List *Foo_items_get(Foo *self) { - return &self->items; + return &self->items; } void Foo_items_set(Foo *self, List *value) { - self->items = *value; + self->items = *value; } </pre> </div> @@ -1007,10 +1028,10 @@ It is the naturalvar feature and can be used to effectively change the way acces <div class="code"> <pre> const List &Foo_items_get(Foo *self) { - return self->items; + return self->items; } void Foo_items_set(Foo *self, const List &value) { - self->items = value; + self->items = value; } </pre> </div> @@ -1094,113 +1115,7 @@ a few problems related to structure wrapping and some of SWIG's customization features. </p> -<H2><a name="SWIGPlus_default_args">6.7 Default arguments</a></H2> - - -<p> -SWIG will wrap all types of functions that have default arguments. For example member functions: -</p> - -<div class="code"> -<pre> -class Foo { -public: - void bar(int x, int y = 3, int z = 4); -}; -</pre> -</div> - -<p> -SWIG handles default arguments by generating an extra overloaded method for each defaulted argument. -SWIG is effectively handling methods with default arguments as if it was wrapping the equivalent overloaded methods. -Thus for the example above, it is as if we had instead given the following to SWIG: -</p> - -<div class="code"> -<pre> -class Foo { -public: - void bar(int x, int y, int z); - void bar(int x, int y); - void bar(int x); -}; -</pre> -</div> - -<p> -The wrappers produced are exactly the same as if the above code was instead fed into SWIG. -Details of this are covered later in the <a href="#SWIGPlus_overloaded_methods">Wrapping Overloaded Functions and Methods</a> section. -This approach allows SWIG to wrap all possible default arguments, but can be verbose. -For example if a method has ten default arguments, then eleven wrapper methods are generated. -</p> - -<p> -Please see the <a href="Customization.html#Customization_features_default_args">Features and default arguments</a> -section for more information on using <tt>%feature</tt> with functions with default arguments. -The <a href="#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> section -also deals with using <tt>%rename</tt> and <tt>%ignore</tt> on methods with default arguments. -If you are writing your own typemaps for types used in methods with default arguments, you may also need to write a <tt>typecheck</tt> typemap. -See the <a href="Typemaps.html#Typemaps_overloading">Typemaps and overloading</a> section for details or otherwise -use the <tt>compactdefaultargs</tt> feature flag as mentioned below. -</p> - -<p> -<b>Compatibility note:</b> Versions of SWIG prior to SWIG-1.3.23 wrapped default arguments slightly differently. -Instead a single wrapper method was generated and the default values were copied into the C++ wrappers -so that the method being wrapped was then called with all the arguments specified. -If the size of the wrappers are a concern then this approach to wrapping methods with default arguments -can be re-activated by using the <tt>compactdefaultargs</tt> -<a href="Customization.html#Customization_feature_flags">feature flag</a>. -</p> - -<div class="code"> -<pre> -%feature("compactdefaultargs") Foo::bar; -class Foo { -public: - void bar(int x, int y = 3, int z = 4); -}; -</pre> -</div> - - -<p> -This is great for reducing the size of the wrappers, but the caveat is it does not work for the statically typed languages, -such as C# and Java, -which don't have optional arguments in the language, -Another restriction of this feature is that it cannot handle default arguments that are not public. -The following example illustrates this: -</p> - -<div class="code"> -<pre> -class Foo { -private: - static const int spam; -public: - void bar(int x, int y = spam); // Won't work with %feature("compactdefaultargs") - - // private default value -}; -</pre> -</div> - -<p> -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> -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> - -<H2><a name="SWIGPlus_nn15">6.8 Protection</a></H2> +<H2><a name="SWIGPlus_nn15">6.7 Protection</a></H2> <p> @@ -1220,7 +1135,7 @@ until you explicitly give a `<tt>public:</tt>' declaration (This is the same convention used by C++). </p> -<H2><a name="SWIGPlus_nn16">6.9 Enums and constants</a></H2> +<H2><a name="SWIGPlus_nn16">6.8 Enums and constants</a></H2> <p> @@ -1250,7 +1165,7 @@ Swig_STOUT = Swig::STOUT Members declared as <tt>const</tt> are wrapped as read-only members and do not create constants. </p> -<H2><a name="SWIGPlus_nn17">6.10 Friends</a></H2> +<H2><a name="SWIGPlus_nn17">6.9 Friends</a></H2> <p> @@ -1278,7 +1193,7 @@ equivalent to one generated for the following declaration <pre> class Foo { public: - ... + ... }; void blah(Foo *f); @@ -1311,7 +1226,7 @@ namespace bar { and a wrapper for the method 'blah' will not be generated. </p> -<H2><a name="SWIGPlus_nn18">6.11 References and pointers</a></H2> +<H2><a name="SWIGPlus_nn18">6.10 References and pointers</a></H2> <p> @@ -1411,7 +1326,7 @@ templates and the STL. This was first added in SWIG-1.3.12. </p> -<H2><a name="SWIGPlus_nn19">6.12 Pass and return by value</a></H2> +<H2><a name="SWIGPlus_nn19">6.11 Pass and return by value</a></H2> <p> @@ -1485,8 +1400,8 @@ class A; %feature("valuewrapper") B; struct B { - B(); - // .... + B(); + // .... }; </pre></div> @@ -1515,7 +1430,7 @@ classes that don't define a default constructor. It is not used for C++ pointers or references. </p> -<H2><a name="SWIGPlus_nn20">6.13 Inheritance</a></H2> +<H2><a name="SWIGPlus_nn20">6.12 Inheritance</a></H2> <p> @@ -1701,7 +1616,7 @@ functions for virtual members that are already defined in a base class. </p> -<H2><a name="SWIGPlus_nn21">6.14 A brief discussion of multiple inheritance, pointers, and type checking</a></H2> +<H2><a name="SWIGPlus_nn21">6.13 A brief discussion of multiple inheritance, pointers, and type checking</a></H2> <p> @@ -1833,7 +1748,113 @@ int y = B_function((B *) pB); In practice, the pointer is held as an integral number in the target language proxy class. </p> -<H2><a name="SWIGPlus_overloaded_methods">6.15 Wrapping Overloaded Functions and Methods</a></H2> +<H2><a name="SWIGPlus_default_args">6.14 Default arguments</a></H2> + + +<p> +SWIG will wrap all types of functions that have default arguments. For example member functions: +</p> + +<div class="code"> +<pre> +class Foo { +public: + void bar(int x, int y = 3, int z = 4); +}; +</pre> +</div> + +<p> +SWIG handles default arguments by generating an extra overloaded method for each defaulted argument. +SWIG is effectively handling methods with default arguments as if it was wrapping the equivalent overloaded methods. +Thus for the example above, it is as if we had instead given the following to SWIG: +</p> + +<div class="code"> +<pre> +class Foo { +public: + void bar(int x, int y, int z); + void bar(int x, int y); + void bar(int x); +}; +</pre> +</div> + +<p> +The wrappers produced are exactly the same as if the above code was instead fed into SWIG. +Details of this are covered in the next section <a href="#SWIGPlus_overloaded_methods">Overloaded functions and methods</a>. +This approach allows SWIG to wrap all possible default arguments, but can be verbose. +For example if a method has ten default arguments, then eleven wrapper methods are generated. +</p> + +<p> +Please see the <a href="Customization.html#Customization_features_default_args">Features and default arguments</a> +section for more information on using <tt>%feature</tt> with functions with default arguments. +The <a href="#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a> section +also deals with using <tt>%rename</tt> and <tt>%ignore</tt> on methods with default arguments. +If you are writing your own typemaps for types used in methods with default arguments, you may also need to write a <tt>typecheck</tt> typemap. +See the <a href="Typemaps.html#Typemaps_overloading">Typemaps and overloading</a> section for details or otherwise +use the <tt>compactdefaultargs</tt> feature flag as mentioned below. +</p> + +<p> +<b>Compatibility note:</b> Versions of SWIG prior to SWIG-1.3.23 wrapped default arguments slightly differently. +Instead a single wrapper method was generated and the default values were copied into the C++ wrappers +so that the method being wrapped was then called with all the arguments specified. +If the size of the wrappers are a concern then this approach to wrapping methods with default arguments +can be re-activated by using the <tt>compactdefaultargs</tt> +<a href="Customization.html#Customization_feature_flags">feature flag</a>. +</p> + +<div class="code"> +<pre> +%feature("compactdefaultargs") Foo::bar; +class Foo { +public: + void bar(int x, int y = 3, int z = 4); +}; +</pre> +</div> + + +<p> +This is great for reducing the size of the wrappers, but the caveat is it does not work for the statically typed languages, +such as C# and Java, +which don't have optional arguments in the language, +Another restriction of this feature is that it cannot handle default arguments that are not public. +The following example illustrates this: +</p> + +<div class="code"> +<pre> +class Foo { +private: + static const int spam; +public: + void bar(int x, int y = spam); // Won't work with %feature("compactdefaultargs") - + // private default value +}; +</pre> +</div> + +<p> +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> +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> + +<H2><a name="SWIGPlus_overloaded_methods">6.15 Overloaded functions and methods</a></H2> <p> @@ -2021,7 +2042,7 @@ checked in the same order as they appear in this ranking. If you're still confused, don't worry about it---SWIG is probably doing the right thing. </p> -<H3><a name="SWIGPlus_nn25">6.15.2 Ambiguity in Overloading</a></H3> +<H3><a name="SWIGPlus_nn25">6.15.2 Ambiguity in overloading</a></H3> <p> @@ -2139,7 +2160,7 @@ it means that the target language module has not yet implemented support for ove functions and methods. The only way to fix the problem is to read the next section. </p> -<H3><a name="SWIGPlus_ambiguity_resolution_renaming">6.15.3 Ambiguity resolution and renaming</a></H3> +<H3><a name="SWIGPlus_ambiguity_resolution_renaming">6.15.3 Renaming and ambiguity resolution</a></H3> <p> @@ -2399,8 +2420,8 @@ the first renaming rule found on a depth-first traversal of the class hierarchy is used. </li> -<li><p>The name matching rules strictly follow member qualification rules. -For example, if you have a class like this:</p> +<li><p>The name matching rules strictly follow member qualifier rules. +For example, if you have a class and member with a member that is const qualified like this:</p> <div class="code"> <pre> @@ -2424,7 +2445,7 @@ the declaration </div> <p> -will not apply as there is no unqualified member <tt>bar()</tt>. The following will apply as +will not apply as there is no unqualified member <tt>bar()</tt>. The following will apply the rename as the qualifier matches correctly: </p> @@ -2435,6 +2456,26 @@ the qualifier matches correctly: </div> <p> +Similarly for combinations of cv-qualifiers and ref-qualifiers, all the qualifiers must be specified to match correctly: +</p> + +<div class="code"> +<pre> +%rename(name) Jam::bar(); // will not match +%rename(name) Jam::bar() &; // will not match +%rename(name) Jam::bar() const; // will not match +%rename(name) Jam::bar() const &; // ok, will match + +class Jam { +public: + ... + void bar() const &; + ... +}; +</pre> +</div> + +<p> An often overlooked C++ feature is that classes can define two different overloaded members that differ only in their qualifiers, like this: </p> @@ -2466,7 +2507,7 @@ For example we can give them separate names in the target language: <p> Similarly, if you merely wanted to ignore one of the declarations, use <tt>%ignore</tt> -with the full qualification. For example, the following directive +with the full qualifier. For example, the following directive would tell SWIG to ignore the <tt>const</tt> version of <tt>bar()</tt> above: </p> @@ -2532,8 +2573,7 @@ exactly matches the wrapped method: <p> The C++ method can then be called from the target language with the new name no matter how many arguments are specified, for example: <tt>newbar(2, 2.0)</tt>, <tt>newbar(2)</tt> or <tt>newbar()</tt>. -However, if the <tt>%rename</tt> does not contain the default arguments, it will only apply to the single equivalent target language overloaded method. -So if instead we have: +However, if the <tt>%rename</tt> does not contain the default arguments: </p> <div class="code"> @@ -2543,8 +2583,23 @@ So if instead we have: </div> <p> +then only one of the three equivalent overloaded methods will be renamed and wrapped as if SWIG parsed: +</p> + +<div class="code"> +<pre> +void Spam::newbar(int i, double d); +void Spam::bar(int i); +void Spam::bar(); +</pre> +</div> + +<p> The C++ method must then be called from the target language with the new name <tt>newbar(2, 2.0)</tt> when both arguments are supplied or with the original name as <tt>bar(2)</tt> (one argument) or <tt>bar()</tt> (no arguments). +</p> + +<p> In fact it is possible to use <tt>%rename</tt> on the equivalent overloaded methods, to rename all the equivalent overloaded methods: </p> @@ -2586,7 +2641,7 @@ As a general rule, statically typed languages like Java are able to provide more than dynamically typed languages like Perl, Python, Ruby, and Tcl. </p> -<H2><a name="SWIGPlus_nn28">6.16 Wrapping overloaded operators</a></H2> +<H2><a name="SWIGPlus_nn28">6.16 Overloaded operators</a></H2> <p> @@ -2779,7 +2834,7 @@ into two methods such that additional logic can be packed into the operations; C <tt>this[type key] { get { ... } set { ... }}</tt>, Python uses <tt>__getitem__</tt> and <tt>__setitem__</tt>, etc. In C++ if the return type of <tt>operator[]</tt> is a reference and the method is const, it is often indicative of the <i>setter</i>, -and and the <i>getter</i> is usually a const function return an object by value. +and the <i>getter</i> is usually a const function return an object by value. In the absence of any hard and fast rules and the fact that there may be multiple index operators, it is up to the user to choose the getter and setter to use by using %rename as shown earlier. </p> @@ -2936,63 +2991,76 @@ as <tt>vector<int></tt>. The wrapper for <tt>foo()</tt> will accept either variant. </p> +<H3><a name="SWIGPlus_template_directive">6.18.1 The %template directive</a></H3> + + <p> -Starting with SWIG-1.3.7, simple C++ template declarations can also be -wrapped. SWIG-1.3.12 greatly expands upon the earlier implementation. Before discussing this any further, there are a few things -you need to know about template wrapping. First, a bare C++ template +There are a couple of important points about template wrapping. +First, a bare C++ template does not define any sort of runnable object-code for which SWIG can normally create a wrapper. Therefore, in order to wrap a template, you need to give SWIG information about a particular template -instantiation (e.g., <tt>vector<int></tt>, +instantiation (e.g., <tt>vector<int></tt>, <tt>array<double></tt>, etc.). Second, an instantiation name such as <tt>vector<int></tt> is generally not a valid identifier name in most target languages. Thus, you will need to give the -template instantiation a more suitable name such as <tt>intvector</tt> -when creating a wrapper. +template instantiation a more suitable name such as <tt>intvector</tt>. </p> <p> -To illustrate, consider the following template definition: +To illustrate, consider the following class template definition: </p> <div class="code"><pre> template<class T> class List { private: - T *data; - int nitems; - int maxitems; + T *data; + int nitems; + int maxitems; public: - List(int max) { - data = new T [max]; - nitems = 0; - maxitems = max; - } - ~List() { - delete [] data; - }; - void append(T obj) { - if (nitems < maxitems) { - data[nitems++] = obj; - } - } - int length() { - return nitems; - } - T get(int n) { - return data[n]; + List(int max) { + data = new T [max]; + nitems = 0; + maxitems = max; + } + ~List() { + delete [] data; + }; + void append(T obj) { + if (nitems < maxitems) { + data[nitems++] = obj; } + } + int length() { + return nitems; + } + T get(int n) { + return data[n]; + } }; </pre></div> <p> -By itself, this template declaration is useless--SWIG simply ignores it -because it doesn't know how to generate any code until unless a definition of +By itself, this class template is useless--SWIG simply ignores it +because it doesn't know how to generate any code unless a definition of <tt>T</tt> is provided. +The <tt>%template</tt> directive is required to instantiate the template for use in a target language. +The directive requires an identifier name for use in the target language plus the template for instantiation. +The example below instantiates <tt>List<int></tt> for use as a class named <tt>intList</tt>: </p> +<div class="code"> +<pre> +%template(intList) List<int>; +</pre> +</div> + <p> -One way to create wrappers for a specific template instantiation is to simply -provide an expanded version of the class directly like this: +The instantiation expands the template code as a C++ compiler would do and then makes it available +under the given identifier name. +Essentially it is the same as wrapping the following concept code where +the class template definition has <tt>T</TT> expanded to <tt>int</tt> +(note that this is not entirely valid syntax): </p> <div class="code"> @@ -3000,60 +3068,112 @@ provide an expanded version of the class directly like this: %rename(intList) List<int>; // Rename to a suitable identifier class List<int> { private: - int *data; - int nitems; - int maxitems; + int *data; + int nitems; + int maxitems; public: - List(int max); - ~List(); - void append(int obj); - int length(); - int get(int n); + List(int max); + ~List(); + void append(int obj); + int length(); + int get(int n); }; </pre> </div> <p> -The <tt>%rename</tt> directive is needed to give the template class an appropriate identifier -name in the target language (most languages would not recognize C++ template syntax as a valid -class name). The rest of the code is the same as what would appear in a normal -class definition. +The argument to <tt>%template()</tt> is the name of the instantiation +in the target language. The name you choose should not conflict with +any other declarations in the interface file with one exception---it +is okay for the template name to match that of a typedef declaration. +For example: +</p> + +<div class="code"> +<pre> +%template(intList) List<int>; +... +typedef List<int> intList; // OK +</pre> +</div> + +<p> +The <tt>%template</tt> directive +must always appear <em>after</em> the definition of the template to be expanded, so the following will work: </p> +<div class="code"> +<pre> +template<class T> class List { ... }; +%template(intList) List<int>; +</pre> +</div> + <p> -Since manual expansion of templates gets old in a hurry, the <tt>%template</tt> directive can -be used to create instantiations of a template class. Semantically, <tt>%template</tt> is -simply a shortcut---it expands template code in exactly the same way as shown above. Here -are some examples: +but if %template is used before the template definition, such as: </p> <div class="code"> <pre> -/* Instantiate a few different versions of the template */ %template(intList) List<int>; -%template(doubleList) List<double>; +template<class T> class List { ... }; </pre> </div> <p> -The argument to <tt>%template()</tt> is the name of the instantiation -in the target language. The name you choose should not conflict with -any other declarations in the interface file with one exception---it -is okay for the template name to match that of a typedef declaration. -For example: +SWIG will generate an error: +</p> + +<div class="shell"> +<pre> +example.i:3: Error: Template 'List' undefined. +</pre> +</div> + +<p> +Since the type system knows how to handle <tt>typedef</tt>, it is +generally not necessary to instantiate different versions of a template +for typenames that are equivalent. For instance, consider this code: </p> <div class="code"> <pre> %template(intList) List<int>; +typedef int Integer; ... -typedef List<int> intList; // OK +void foo(List<Integer> *x); </pre> </div> <p> -SWIG can also generate wrappers for function templates using a similar technique. +In this case, <tt>List<Integer></tt> is exactly the same type as +<tt>List<int></tt>. Any use of <tt>List<Integer></tt> is mapped back to the +instantiation of <tt>List<int></tt> created earlier. Therefore, it is +not necessary to instantiate a new class for the type <tt>Integer</tt> (doing so is +redundant and will simply result in code bloat). +</p> + +<p> +The template provided to <tt>%template</tt> for instantiation must be the actual template and not a typedef to a template. +</p> + +<div class="code"> +<pre> +typedef List<int> ListOfInt; + +%template(intList) List<int>; // ok +%template(intList) ListOfInt; // illegal - Syntax error +</pre> +</div> + + +<H3><a name="SWIGPlus_template_functions">6.18.2 Function templates</a></H3> + + +<p> +SWIG can also generate wrappers for function templates using a similar technique +to that shown above for class templates. For example: </p> @@ -3074,6 +3194,28 @@ instantiations of the function. </p> <p> +SWIG even supports overloaded templated functions. As usual the <tt>%template</tt> directive +is used to wrap templated functions. For example: +</p> + +<div class="code"> +<pre> +template<class T> void foo(T x) { }; +template<class T> void foo(T x, T y) { }; + +%template(foo) foo<int>; +</pre> +</div> + +<p> +This will generate two overloaded wrapper methods, the first will take a single integer as an argument +and the second will take two integer arguments. +</p> + +<H3><a name="SWIGPlus_template_classes">6.18.3 Default template arguments</a></H3> + + +<p> The number of arguments supplied to <tt>%template</tt> should match that in the original template definition. Template default arguments are supported. For example: </p> @@ -3110,28 +3252,8 @@ instantiation only once in order to reduce the potential for code bloat. </p> -<p> -Since the type system knows how to handle <tt>typedef</tt>, it is -generally not necessary to instantiate different versions of a template -for typenames that are equivalent. For instance, consider this code: -</p> +<H3><a name="SWIGPlus_template_class_inheritance">6.18.4 Template base classes</a></H3> -<div class="code"> -<pre> -%template(intList) vector<int>; -typedef int Integer; -... -void foo(vector<Integer> *x); -</pre> -</div> - -<p> -In this case, <tt>vector<Integer></tt> is exactly the same type as -<tt>vector<int></tt>. Any use of <tt>Vector<Integer></tt> is mapped back to the -instantiation of <tt>vector<int></tt> created earlier. Therefore, it is -not necessary to instantiate a new class for the type <tt>Integer</tt> (doing so is -redundant and will simply result in code bloat). -</p> <p> When a template is instantiated using <tt>%template</tt>, information @@ -3158,13 +3280,13 @@ nothing is known about <tt>List<int></tt>, you will get a warning message <div class="shell"> <pre> -example.h:42: Warning 401. Nothing known about class 'List<int >'. Ignored. -example.h:42: Warning 401. Maybe you forgot to instantiate 'List<int >' using %template. +example.h:42: Warning 401. Nothing known about class 'List< int >'. Ignored. +example.h:42: Warning 401. Maybe you forgot to instantiate 'List< int >' using %template. </pre> </div> <p> -If a template class inherits from another template class, you need to +If a class template inherits from another class template, you need to make sure that base classes are instantiated before derived classes. For example: </p> @@ -3235,6 +3357,9 @@ TEMPLATE_WRAP(PairStringInt, std::pair<string, int>) Note the use of a vararg macro for the type T. If this wasn't used, the comma in the templated type in the last example would not be possible. </p> +<H3><a name="SWIGPlus_template_specialization">6.18.5 Template specialization</a></H3> + + <p> The SWIG template mechanism <em>does</em> support specialization. For instance, if you define a class like this, @@ -3244,15 +3369,15 @@ a class like this, <pre> template<> class List<int> { private: - int *data; - int nitems; - int maxitems; + int *data; + int nitems; + int maxitems; public: - List(int max); - ~List(); - void append(int obj); - int length(); - int get(int n); + List(int max); + ~List(); + void append(int obj); + int length(); + int get(int n); }; </pre> </div> @@ -3275,15 +3400,15 @@ code defines a template that is applied when the template argument is a pointer. <pre> template<class T> class List<T*> { private: - T *data; - int nitems; - int maxitems; + T *data; + int nitems; + int maxitems; public: - List(int max); - ~List(); - void append(int obj); - int length(); - T get(int n); + List(int max); + ~List(); + void append(T obj); + int length(); + T get(int n); }; </pre> </div> @@ -3322,10 +3447,13 @@ SWIG implements template argument deduction so that the following partial specia </pre> </div> +<H3><a name="SWIGPlus_template_member">6.18.6 Member templates</a></H3> + + <p> -Member function templates are supported. The underlying principle is the same +Member templates are supported. The underlying principle is the same as for normal templates--SWIG can't create a wrapper unless you provide -more information about types. For example, a class with a member template might +more information about types. For example, a class with a member function template might look like this: </p> @@ -3400,11 +3528,6 @@ methods to the Foo class. <p> -Note: because of the way that templates are handled, the <tt>%template</tt> directive -must always appear <em>after</em> the definition of the template to be expanded. -</p> - -<p> Now, if your target language supports overloading, you can even try </p> @@ -3424,7 +3547,7 @@ depending on the argument type. <p> When used with members, the <tt>%template</tt> directive may be placed in another -template class. Here is a slightly perverse example: +class template. Here is a slightly perverse example: </p> <div class="code"> @@ -3475,7 +3598,7 @@ template<class T1, class T2> struct pair { <p> This declaration is perfectly acceptable to SWIG, but the constructor template will be ignored unless you explicitly expand it. To do that, you could expand a few versions of the constructor -in the template class itself. For example: +in the class template itself. For example: </p> <div class="code"> @@ -3536,6 +3659,110 @@ constructor, that will dispatch the proper call depending on the argument type. </p> +<H3><a name="SWIGPlus_template_scoping">6.18.7 Scoping and templates</a></H3> + + +<p> +The <tt>%template</tt> directive for a class template is the equivalent to an explicit instantiation +of a C++ class template. The scope for a valid <tt>%template</tt> instantiation is the same +as the scope required for a valid explicit instantiation of a C++ template. +A definition of the template for the explicit instantiation must be in scope +where the instantiation is declared and must not be enclosed within a different namespace. +</p> + +<p> +For example, a few <tt>%template</tt> instantiations and C++ explicit instantiations are shown below: +</p> + +<div class="code"> +<pre> +namespace N { + template<typename T> class C {}; +} + +// valid +%template(cin) N::C<int>; +template class N::C<int>; + +// valid +namespace N { + %template(cin) C<int>; + template class C<int>; +} + +// valid +using namespace N; +%template(cin) C<int>; +template class C<int>; + +// valid +using N::C; +%template(cin) C<int>; +template class C<int>; + +// ill-formed +namespace unrelated { + using N::C; + %template(cin) C<int>; + template class C<int>; +} + +// ill-formed +namespace unrelated { + using namespace N; + %template(cin) C<int>; + template class C<int>; +} + +// ill-formed +namespace unrelated { + namespace N { + %template(cin) C<int>; + template class C<int>; + } +} + +// ill-formed +namespace unrelated { + %template(cin) N::C<int>; + template class N::C<int>; +} +</pre> +</div> + +<p> +When the scope is incorrect, such as for the ill-formed examples above, an error occurs: +</p> + +<div class="shell"> +<pre> +cpp_template_scope.i:34: Error: 'C' resolves to 'N::C' and was incorrectly instantiated +in scope 'unrelated' instead of within scope 'N'. +</pre> +</div> + +<p> +A note for the C++ standard geeks out there; a valid instantiation is one which conforms to +the C++03 standard as C++11 made a change to disallow using declarations and using directives to find a template. +</p> + +<div class="code"> +<pre> +// valid C++03, ill-formed C++11 +using N::C; +template class C<int>; +</pre> +</div> + +<p> +<b>Compatibility Note</b>: Versions prior to SWIG-4.0.0 did not error out with incorrectly scoped +<tt>%template</tt> declarations, but this led to numerous subtle template scope problems. +</p> + + +<H3><a name="SWIGPlus_template_more">6.18.8 More on templates</a></H3> + + <p> If all of this isn't quite enough and you really want to make someone's head explode, SWIG directives such as @@ -3568,7 +3795,7 @@ instantiation. </p> <p> -It is also possible to separate these declarations from the template class. For example: +It is also possible to separate these declarations from the class template. For example: </p> <div class="code"> @@ -3587,11 +3814,11 @@ It is also possible to separate these declarations from the template class. For ... template<class T> class List { - ... - public: - List() { } - T get(int index); - ... + ... + public: + List() { } + T get(int index); + ... }; </pre> </div> @@ -3609,33 +3836,14 @@ additional methods to a specific instantiation. For example: %template(intList) List<int>; %extend List<int> { - void blah() { - printf("Hey, I'm an List<int>!\n"); - } + void blah() { + printf("Hey, I'm an List<int>!\n"); + } }; </pre> </div> <p> -SWIG even supports overloaded templated functions. As usual the <tt>%template</tt> directive -is used to wrap templated functions. For example: -</p> - -<div class="code"> -<pre> -template<class T> void foo(T x) { }; -template<class T> void foo(T x, T y) { }; - -%template(foo) foo<int>; -</pre> -</div> - -<p> -This will generate two overloaded wrapper methods, the first will take a single integer as an argument -and the second will take two integer arguments. -</p> - -<p> It is even possible to extend a class via <tt>%extend</tt> with template methods, for example: </p> @@ -3694,20 +3902,20 @@ For example: <pre> template <class T> class OuterTemplateClass {}; -// The nested class OuterClass::InnerClass inherits from the template class +// The nested class OuterClass::InnerClass inherits from the class template // OuterTemplateClass<OuterClass::InnerStruct> and thus the template needs // to be expanded with %template before the OuterClass declaration. %template(OuterTemplateClass_OuterClass__InnerStruct) - OuterTemplateClass<OuterClass::InnerStruct> + OuterTemplateClass<OuterClass::InnerStruct> // Don't forget to use %feature("flatnested") for OuterClass::InnerStruct and // OuterClass::InnerClass if the target language doesn't support nested classes. class OuterClass { - public: - // Forward declarations: - struct InnerStruct; - class InnerClass; + public: + // Forward declarations: + struct InnerStruct; + class InnerClass; }; struct OuterClass::InnerStruct {}; @@ -3736,7 +3944,7 @@ introduced a new class name. This name could then be used with other directives <pre> %template(vectori) vector<int>; %extend vectori { - void somemethod() { } + void somemethod() { } }; </pre> </div> @@ -3750,7 +3958,7 @@ as the class name. For example: <pre> %template(vectori) vector<int>; %extend vector<int> { - void somemethod() { } + void somemethod() { } }; </pre> </div> @@ -3915,6 +4123,8 @@ then SWIG simply creates three wrapper functions <tt>bar()</tt>, <tt>spam()</tt>, and <tt>blah()</tt> in the target language. SWIG does not prepend the names with a namespace prefix nor are the functions packaged in any kind of nested scope. +Note that the default handling of flattening all the namespace scopes in the target language +can be changed via the <a href="#SWIGPlus_nspace">nspace feature</a>. </p> <p> @@ -4009,7 +4219,7 @@ in a different namespace. For example: <div class="code"> <pre> namespace foo { - template<typename T> T max(T a, T b) { return a > b ? a : b; } + template<typename T> T max(T a, T b) { return a > b ? a : b; } } using foo::max; @@ -4018,8 +4228,8 @@ using foo::max; %template(maxfloat) foo::max<float>; // Okay (qualified name). namespace bar { - using namespace foo; - %template(maxdouble) max<double>; // Okay. + using namespace foo; + %template(maxdouble) max<double>; // Okay. } </pre> </div> @@ -4040,7 +4250,7 @@ namespace foo { typedef int Integer; class bar { public: - ... + ... }; } @@ -4203,9 +4413,7 @@ namespace foo { <p> <b>Note:</b> The flattening of namespaces is only intended to serve as a basic namespace implementation. -None of the target language modules are currently programmed -with any namespace awareness. In the future, language modules may or may not provide -more advanced namespace support. +More advanced handling of namespaces is discussed next. </p> <H3><a name="SWIGPlus_nspace">6.19.1 The nspace feature for namespaces</a></H3> @@ -4301,9 +4509,9 @@ In the example below, the generic template type is used to rename to <tt>bbb</tt <div class="code"> <pre> -%rename(bbb) Space::ABC::aaa(T t); // will match but with lower precedence than ccc +%rename(bbb) Space::ABC::aaa(T t); // will match but with lower precedence than ccc %rename(ccc) Space::ABC<Space::XYZ>::aaa(Space::XYZ t);// will match but with higher precedence - // than bbb + // than bbb namespace Space { class XYZ {}; @@ -4381,9 +4589,9 @@ class Error { }; class Foo { public: - ... - void blah() throw(Error); - ... + ... + void blah() throw(Error); + ... }; </pre> </div> @@ -4408,7 +4616,7 @@ except Error, e: <p> Details of how to tailor code for handling the caught C++ exception and converting it into the target language's exception/error handling mechanism -is outlined in the <a href="Typemaps.html#throws_typemap">"throws" typemap</a> section. +is outlined in the <a href="Typemaps.html#Typemaps_throws_typemap">"throws" typemap</a> section. </p> <p> @@ -4425,7 +4633,7 @@ The next section details a way of simulating an exception specification or repla Exceptions are automatically handled for methods with an exception specification. Similar handling can be achieved for methods without exception specifications through the <tt>%catches</tt> feature. It is also possible to replace any declared exception specification using the <tt>%catches</tt> feature. -In fact, <tt>%catches</tt> uses the same <a href="Typemaps.html#throws_typemap">"throws" typemaps</a> that SWIG uses for exception specifications in handling exceptions. +In fact, <tt>%catches</tt> uses the same <a href="Typemaps.html#Typemaps_throws_typemap">"throws" typemaps</a> that SWIG uses for exception specifications in handling exceptions. The <tt>%catches</tt> feature must contain a list of possible types that can be thrown. For each type that is in the list, SWIG will generate a catch handler, in the same way that it would for types declared in the exception specification. Note that the list can also include the catch all specification "...". @@ -4445,10 +4653,10 @@ struct Error4 : EBase { }; class Foo { public: - ... - void bar(); - void blah() throw(Error1, Error2, Error3, Error4); - ... + ... + void bar(); + void blah() throw(Error1, Error2, Error3, Error4); + ... }; </pre> </div> @@ -4524,7 +4732,7 @@ for member pointers. <p> In some C++ programs, objects are often encapsulated by smart-pointers or proxy classes. This is sometimes done to implement automatic memory management (reference counting) or -persistence. Typically a smart-pointer is defined by a template class where +persistence. Typically a smart-pointer is defined by a class template where the <tt>-></tt> operator has been overloaded. This class is then wrapped around some other class. For example: </p> @@ -4533,21 +4741,21 @@ around some other class. For example: <pre> // Smart-pointer class template<class T> class SmartPtr { - T *pointee; + T *pointee; public: - SmartPtr(T *p) : pointee(p) { ... } - T *operator->() { - return pointee; - } - ... + SmartPtr(T *p) : pointee(p) { ... } + T *operator->() { + return pointee; + } + ... }; // Ordinary class class Foo_Impl { public: - int x; - virtual void bar(); - ... + int x; + virtual void bar(); + ... }; // Smart-pointer wrapper @@ -4555,13 +4763,13 @@ typedef SmartPtr<Foo_Impl> Foo; // Create smart pointer Foo Foo make_Foo() { - return SmartPtr<Foo_Impl>(new Foo_Impl()); + return SmartPtr<Foo_Impl>(new Foo_Impl()); } // Do something with smart pointer Foo void do_something(Foo f) { - printf("x = %d\n", f->x); - f->bar(); + printf("x = %d\n", f->x); + f->bar(); } // Call the wrapped smart pointer proxy class in the target language 'Foo' @@ -4660,13 +4868,13 @@ example, if you have this code</p> <pre> class Foo { public: - int x; + int x; }; class Bar { public: - int x; - Foo *operator->(); + int x; + Foo *operator->(); }; </pre> </div> @@ -4829,19 +5037,19 @@ For example: <p> where the code passed to the "ref" and "unref" features will be -executed as needed whenever a new object is passed to python, or when -python tries to release the proxy object instance, respectively. +executed as needed whenever a new object is passed to Python, or when +Python tries to release the proxy object instance, respectively. </p> <p> -On the python side, the use of a reference counted object is no +On the Python side, the use of a reference counted object is no different to any other regular instance: </p> <div class="targetlang"> <pre> def create_A(): - a = A() # SWIG ref 'a' - new object is passed to python (count: 1) + a = A() # SWIG ref 'a' - new object is passed to Python (count: 1) b1 = B(a) # C++ ref 'a (count: 2) if 1 + 1 == 2: b2 = B(a) # C++ ref 'a' (count: 3) @@ -4869,8 +5077,8 @@ features: <p> In other words, SWIG will not do anything special when a new object -is passed to python, and it will always 'delete' the underlying object when -python releases the proxy instance. +is passed to Python, and it will always 'delete' the underlying object when +Python releases the proxy instance. </p> <p> @@ -4915,19 +5123,19 @@ base classes. For example: <pre> class Foo { public: - int blah(int x); + int blah(int x); }; class Bar { public: - double blah(double x); + double blah(double x); }; class FooBar : public Foo, public Bar { public: - using Foo::blah; - using Bar::blah; - char *blah(const char *x); + using Foo::blah; + using Bar::blah; + char *blah(const char *x); }; </pre> </div> @@ -4970,14 +5178,14 @@ you wrap this code in Python, the module works just like you would expect: <pre> class Foo { protected: - int x; - int blah(int x); + int x; + int blah(int x); }; class Bar : public Foo { public: - using Foo::x; // Make x public - using Foo::blah; // Make blah public + using Foo::x; // Make x public + using Foo::blah; // Make blah public }; </pre> </div> @@ -5008,14 +5216,14 @@ correctly, you can always change the interface to the following: class FooBar : public Foo, public Bar { public: #ifndef SWIG - using Foo::blah; - using Bar::blah; + using Foo::blah; + using Bar::blah; #else - int blah(int x); // explicitly tell SWIG about other declarations - double blah(double x); + int blah(int x); // explicitly tell SWIG about other declarations + double blah(double x); #endif - char *blah(const char *x); + char *blah(const char *x); }; </pre> </div> @@ -5077,7 +5285,7 @@ normal classes. </p> <p> If the target language doesn't support nested classes directly, or the support is not implemented in the -language module (like for python currently), then the visible nested classes are moved to the same name +language module (like for Python currently), then the visible nested classes are moved to the same name space as the containing class (nesting hierarchy is "flattened"). The same behaviour may be turned on for C# and Java by the %feature ("flatnested"); If there is a class with the same name in the outer namespace the inner class (or the global one) may be renamed or ignored: @@ -5188,7 +5396,152 @@ using another tool if maintaining constness is the most important part of your project. </p> -<H2><a name="SWIGPlus_nn42">6.29 Where to go for more information</a></H2> +<H2><a name="SWIGPlus_target_language_callbacks">6.29 Callbacks to the target language</a></H2> + + +<p> +C/C++ function pointers are often used for callbacks and this is discussed in the +<a href="SWIG.html#SWIG_nn30">Pointers to functions and callbacks</a> section. +The callback techniques described therein provide a way to control callbacks to a C/C++ function but not callbacks into the target language. +The techniques described below show how the director feature can be used to support callbacks from C/C++ to the target language. +</p> + +<H3><a name="SWIGPlus_director_classes_introduction">6.29.1 Introduction to director classes</a></H3> + + +<p> +The director feature enables the ability for a target language class to derive from a wrapped C++ class. +The target language can override virtual methods of a wrapped C++ class, thereby supporting cross-language polymorphism. +Code can 'call up' from C++ into the target language by simply calling a virtual method overridden in a derived class in the target language. +The wrapped C++ classes that have this ability are termed 'director' classes. +The director feature is documented individually in each target language and the reader should locate and read this to obtain a full understanding of directors. +</p> + +<H3><a name="SWIGPlus_directors_for_function_pointers">6.29.2 Using directors and target language callbacks</a></H3> + + +<p> +SWIG's primary goal is to make it possible to call C/C++ code from a target language, however, the director feature enables the reverse. +While there isn't simple direct support for calling target language code from C, the director feature makes this possible. +It does require some work and additional wrapper code to be provided by the user. +The additional code required must be C++ and not C code and hence may introduce a small dependency on C++ if using a pure C project. +In a nutshell, the user must create a C++ base class and turn it into a director class. +A virtual method in the director base class is required. +SWIG generates the code to call up into the target language when wrapping the director virtual method. +</p> + +<p> +Let's look at some details next. +Consider the same function pointer for a callback called <tt>binary_op</tt> from the +<a href="SWIG.html#SWIG_nn30">Pointers to functions and callbacks</a> section. +For completeness, the code required for the module and director feature is also shown: +</p> + +<div class="code"><pre> +%module(directors="1") example + +%{ +int binary_op(int a, int b, int (*op)(int, int)) { + return op(a, b); +} +%} +</pre></div> + +<p> +The goal is to have a target language function that gets called by <tt>binary_op</tt>. +The target language function should have the equivalent signature as the C/C++ function pointer <tt>int (*op)(int, int)</tt>. +As we are using directors, we need a C++ virtual method with this signature, so let's +define the C++ class and pure virtual method first and make it a director class via the +director feature: +</p> + +<div class="code"><pre> +%feature("director") BinaryOp; + +%inline %{ +struct BinaryOp { + virtual int handle(int a, int b) = 0; + virtual ~BinaryOp() {} +}; +%} +</pre></div> + +<p> +The following <tt>handler_helper</tt> function and <tt>binary_op_wrapper</tt> function completes the code needed in the +C++/SWIG layer. The <tt>binary_op_wrapper</tt> function is wrapped by SWIG and is very similar to the <tt>binary_op</tt> function, +however, it takes a pointer to the director base class <tt>BinaryOp</tt> instead of a C/C++ function pointer. +</p> + +<div class="code"><pre> +%{ +static BinaryOp *handler_ptr = NULL; +static int handler_helper(int a, int b) { + // Make the call up to the target language when handler_ptr + // is an instance of a target language director class + return handler_ptr->handle(a, b); +} +// If desired, handler_ptr above could be changed to a thread-local variable in order to make thread-safe +%} + +%inline %{ +int binary_op_wrapper(int a, int b, BinaryOp *handler) { + handler_ptr = handler; + int result = binary_op(a, b, &handler_helper); + handler = NULL; + return result; +} +%} +</pre></div> + +<p> +On the target language side, we need to derive a class from <tt>BinaryOp</tt> and override the +<tt>handle</tt> method. In Python this could be as simple as: +</p> + +<div class="targetlang"> +<pre> +import example + +# PythonBinaryOp class is defined and derived from C++ class BinaryOp +class PythonBinaryOp(example.BinaryOp): + + # Define Python class 'constructor' + def __init__(self): + # Call C++ base class constructor + example.BinaryOp.__init__(self) + + # Override C++ method: virtual int handle(int a, int b) = 0; + def handle(self, a, b): + # Return the product + return a * b +</pre> +</div> + +<p> +For this to work from Python, an instance of the <tt>PythonBinaryOp</tt> class is created +and then passed to <tt>binary_op_wrapper</tt>. The net result is the <tt>binary_op</tt> +function will in turn be called which will call <tt>handler_helper</tt> which will call +the virtual <tt>handle</tt> method, that is, the Python method <tt>handle</tt> in the PythonBinaryOp class. The result will be the product of 10 and 20 and make its way back to Python and hence +200 will be printed with the following code: +</p> + +<div class="targetlang"> +<pre> +handler = PythonBinaryOp() +result = example.binary_op_wrapper(10, 20, handler) +print result +</pre> +</div> + +<p> +This has thus demonstrated a C/C++ function pointer calling back into a target language function. +The code could be made a little more user friendly by using <tt>%rename</tt> to provide the +original <tt>binary_op</tt> name from the target language instead of <tt>binary_op_wrapper</tt>. +A C++ functor base class and Python functor class +could also be used instead, but these are left as exercises for the reader. +</p> + +<H2><a name="SWIGPlus_nn42">6.30 Where to go for more information</a></H2> <p> diff --git a/Doc/Manual/Scilab.html b/Doc/Manual/Scilab.html index 90bd8bb9a..88ab8043e 100644 --- a/Doc/Manual/Scilab.html +++ b/Doc/Manual/Scilab.html @@ -9,7 +9,7 @@ <body bgcolor="#ffffff"> -<H1><a name="Scilab">39 SWIG and Scilab</a></H1> +<H1><a name="Scilab">35 SWIG and Scilab</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -39,7 +39,7 @@ </ul> <li><a href="#Scilab_wrapping_pointers">Pointers</a> <ul> -<li><a href="#Scilab_wrapping_pointers_pointer_adresses">Utility functions</a> +<li><a href="#Scilab_wrapping_pointers_utility_functions">Utility functions</a> <li><a href="#Scilab_wrapping_pointers_null_pointers">Null pointers:</a> </ul> <li><a href="#Scilab_wrapping_structs">Structures</a> @@ -88,11 +88,11 @@ This chapter explains how to use SWIG for Scilab. After this introduction, you s </p> -<H2><a name="Scilab_preliminaries">39.1 Preliminaries</a></H2> +<H2><a name="Scilab_preliminaries">35.1 Preliminaries</a></H2> <p> -SWIG for Scilab supports Linux. Other operating sytems haven't been tested. +SWIG for Scilab supports Linux. Other operating systems haven't been tested. </p> <p> @@ -105,7 +105,7 @@ SWIG for Scilab supports C language. C++ is partially supported. See <a href="#S </p> -<H2><a name="Scilab_running_swig">39.2 Running SWIG</a></H2> +<H2><a name="Scilab_running_swig">35.2 Running SWIG</a></H2> <p> @@ -121,15 +121,15 @@ In this example we bind from C a function and a global variable into Scilab. The double Foo = 3.0; int fact(int n) { - if (n < 0) { - return 0; - } - else if (n == 0) { - return 1; - } - else { - return n * fact(n-1); - } + if (n < 0) { + return 0; + } + else if (n == 0) { + return 1; + } + else { + return n * fact(n-1); + } } %} </pre></div> @@ -139,7 +139,7 @@ Note: a code in an <tt>%inline</tt> section is both parsed and wrapped by SWIG, </p> -<H3><a name="Scilab_running_swig_generating_module">39.2.1 Generating the module</a></H3> +<H3><a name="Scilab_running_swig_generating_module">35.2.1 Generating the module</a></H3> <p> @@ -182,7 +182,7 @@ The <tt>swig</tt> executable has several other command line options you can use. </p> -<H3><a name="Scilab_running_swig_building_module">39.2.2 Building the module</a></H3> +<H3><a name="Scilab_running_swig_building_module">35.2.2 Building the module</a></H3> <p> @@ -202,7 +202,7 @@ $ gcc -shared example_wrap.o -o libexample.so Note: we supposed in this example that the path to the Scilab include directory is <tt>/usr/local/include/scilab</tt> (which is the case in a Debian environment), this should be changed for another environment. </p> -<H3><a name="Scilab_running_swig_loading_module">39.2.3 Loading the module</a></H3> +<H3><a name="Scilab_running_swig_loading_module">35.2.3 Loading the module</a></H3> <p> @@ -226,7 +226,7 @@ Link done. which means that Scilab has successfully loaded the shared library. The module functions and other symbols are now available in Scilab. </p> -<H3><a name="Scilab_running_swig_using_module">39.2.4 Using the module</a></H3> +<H3><a name="Scilab_running_swig_using_module">35.2.4 Using the module</a></H3> <p> @@ -260,7 +260,7 @@ ans = Note: for conciseness, we assume in the subsequent Scilab code examples that the modules have been beforehand built and loaded in Scilab. </p> -<H3><a name="Scilab_running_swig_options">39.2.5 Scilab command line options</a></H3> +<H3><a name="Scilab_running_swig_options">35.2.5 Scilab command line options</a></H3> <p> @@ -304,6 +304,11 @@ The following table lists the Scilab specific command line options in addition t <td>Generate the gateway XML with the given <gateway_id></td> </tr> +<tr> +<td><tt>-targetversion</tt></td> +<td>Generate for Scilab target (major) version</td> +</tr> + </table> <p> @@ -315,10 +320,10 @@ $ swig -scilab -help </pre></div> -<H2><a name="Scilab_wrapping">39.3 A basic tour of C/C++ wrapping</a></H2> +<H2><a name="Scilab_wrapping">35.3 A basic tour of C/C++ wrapping</a></H2> -<H3><a name="Scilab_wrapping_overview">39.3.1 Overview</a></H3> +<H3><a name="Scilab_wrapping_overview">35.3.1 Overview</a></H3> <p> @@ -327,18 +332,22 @@ This means that functions, structs, classes, variables, etc... are interfaced th There are a few exceptions, such as constants and enumerations, which can be wrapped directly as Scilab variables. </p> -<H3><a name="Scilab_wrapping_identifiers">39.3.2 Identifiers</a></H3> +<H3><a name="Scilab_wrapping_identifiers">35.3.2 Identifiers</a></H3> <p> -In Scilab 5.x, identifier names are composed of 24 characters maximum (this limitation should disappear from Scilab 6.0 onwards). -<br>Thus long function or variable names may be truncated and this can cause ambiguities. +In Scilab 5.x, identifier names are composed of 24 characters maximum (this limitation disappears from Scilab 6.0 onwards). +<br>By default, variable, member, and function names longer than 24 characters are truncated, and a warning is produced for each truncation. </p> -<p>This happens especially when wrapping structs/classes, for which the wrapped function name is composed of the struct/class name and field names. +<p>This can cause ambiguities, especially when wrapping structs/classes, for which the wrapped function name is composed of the struct/class name and field names. In these cases, the <a href="SWIG.html#SWIG_rename_ignore">%rename directive</a> can be used to choose a different Scilab name. </p> -<H3><a name="Scilab_wrapping_functions">39.3.3 Functions</a></H3> +<p> +Note: truncations can be disabled by specifying the target version 6 of Scilab in the <tt>targetversion</tt> argument (i.e. <tt>-targetversion 6</tt>). +</p> + +<H3><a name="Scilab_wrapping_functions">35.3.3 Functions</a></H3> <p> @@ -369,7 +378,7 @@ ans = 24. </pre></div> -<H4><a name="Scilab_nn13">39.3.3.1 Argument passing</a></H4> +<H4><a name="Scilab_nn13">35.3.3.1 Argument passing</a></H4> <p> @@ -422,7 +431,7 @@ In Scilab, parameters are passed by value. The output (and inout) parameters are 7. </pre></div> -<H4><a name="Scilab_nn14">39.3.3.2 Multiple output arguments</a></H4> +<H4><a name="Scilab_nn14">35.3.3.2 Multiple output arguments</a></H4> <p> @@ -471,7 +480,7 @@ int divide(int n, int d, int *OUTPUT, int *OUTPUT); </pre></div> -<H3><a name="Scilab_wrapping_global_variables">39.3.4 Global variables</a></H3> +<H3><a name="Scilab_wrapping_global_variables">35.3.4 Global variables</a></H3> <p> @@ -540,10 +549,10 @@ It works the same:</p> </pre></div> -<H3><a name="Scilab_wrapping_constants_and_enums">39.3.5 Constants and enumerations</a></H3> +<H3><a name="Scilab_wrapping_constants_and_enums">35.3.5 Constants and enumerations</a></H3> -<H4><a name="Scilab_wrapping_constants">39.3.5.1 Constants</a></H4> +<H4><a name="Scilab_wrapping_constants">35.3.5.1 Constants</a></H4> <p> @@ -684,7 +693,7 @@ are mapped to Scilab variables, with the same name: 3.14 </pre></div> -<H4><a name="Scilab_wrapping_enums">39.3.5.2 Enumerations</a></H4> +<H4><a name="Scilab_wrapping_enums">35.3.5.2 Enumerations</a></H4> <p> @@ -749,14 +758,14 @@ typedef enum { RED, BLUE, GREEN } color; </pre></div> -<H3><a name="Scilab_wrapping_pointers">39.3.6 Pointers</a></H3> +<H3><a name="Scilab_wrapping_pointers">35.3.6 Pointers</a></H3> <p> Pointers are supported by SWIG. A pointer can be returned from a wrapped C/C++ function, stored in a Scilab variable, and used in input argument of another C/C++ function. </p> <p> -Also, thanks to the SWIG runtime which stores informations about types, pointer types are tracked between exchanges Scilab and the native code. Indeed pointer types are stored alongside the pointer adress. +Also, thanks to the SWIG runtime which stores information about types, pointer types are tracked between exchanges Scilab and the native code. Indeed pointer types are stored alongside the pointer address. A pointer is mapped to a Scilab structure (<a href="https://help.scilab.org/docs/5.5.2/en_US/tlist.html">tlist</a>), which contains as fields the pointer address and the pointer type (in fact a pointer to the type information structure in the SWIG runtime). <br> Why a native pointer is not mapped to a Scilab pointer (type name: "pointer", type ID: 128) ? The big advantage of mapping to a <tt>tlist</tt> is that it exposes a new type for the pointer in Scilab, type which can be acessed in Scilab with the <a href="https://help.scilab.org/docs/5.5.2/en_US/typeof.html">typeof</a> function, and manipulated using the <a href="https://help.scilab.org/docs/5.5.2/en_US/overloading.html">overloading</a> mechanism. @@ -811,7 +820,7 @@ Note: the type name <tt>_p_FILE</tt> which means "pointer to FILE". The user of a pointer is responsible for freeing it or, like in the example, closing any resources associated with it (just as is required in a C program). </p> -<H4><a name="Scilab_wrapping_pointers_pointer_adresses">39.3.6.1 Utility functions</a></H4> +<H4><a name="Scilab_wrapping_pointers_utility_functions">35.3.6.1 Utility functions</a></H4> <p> @@ -852,7 +861,7 @@ ans = </pre></div> -<H4><a name="Scilab_wrapping_pointers_null_pointers">39.3.6.2 Null pointers:</a></H4> +<H4><a name="Scilab_wrapping_pointers_null_pointers">35.3.6.2 Null pointers:</a></H4> <p> @@ -868,7 +877,7 @@ Using the previous <tt>SWIG_this()</tt> and <tt>SWIG_ptr()</tt>, it is possible </pre></div> -<H3><a name="Scilab_wrapping_structs">39.3.7 Structures</a></H3> +<H3><a name="Scilab_wrapping_structs">35.3.7 Structures</a></H3> <p> @@ -887,8 +896,8 @@ Let's see it on an example of a struct with two members: %inline %{ typedef struct { - int x; - int arr[4]; + int x; + int arr[4]; } Foo; %} @@ -964,7 +973,7 @@ ans = </pre></div> <p> -Note: the pointer to the struct works as described in <a href="Scilab_wrapping_pointers">Pointers</a>. For example, the type of the struct pointer can be get with <tt>typeof</tt>, as following: +Note: the pointer to the struct works as described in <a href="#Scilab_wrapping_pointers">Pointers</a>. For example, the type of the struct pointer can be get with <tt>typeof</tt>, as following: </p> <div class="targetlang"><pre> @@ -977,7 +986,7 @@ Note: the pointer to the struct works as described in <a href="Scilab_wrapping_p --> delete_Bar(b); </pre></div> -<H3><a name="Scilab_wrapping_cpp_classes">39.3.8 C++ classes</a></H3> +<H3><a name="Scilab_wrapping_cpp_classes">35.3.8 C++ classes</a></H3> <p> @@ -1028,7 +1037,7 @@ ans = </pre></div> <p> -Note: like structs, class pointers are mapped as described in <a href="Scilab_wrapping_pointers">Pointers</a>. Let's give an example which shows that each class pointer type is a new type in Scilab that can be used for example (through <a href="https://help.scilab.org/docs/5.5.2/en_US/overloading.html">overloading</a>) to implement a custom print for the <tt>Point</tt> class: +Note: like structs, class pointers are mapped as described in <a href="#Scilab_wrapping_pointers">Pointers</a>. Let's give an example which shows that each class pointer type is a new type in Scilab that can be used for example (through <a href="https://help.scilab.org/docs/5.5.2/en_US/overloading.html">overloading</a>) to implement a custom print for the <tt>Point</tt> class: </p> <div class="targetlang"><pre> @@ -1045,7 +1054,7 @@ Note: like structs, class pointers are mapped as described in <a href="Scilab_wr --> delete_Point(p); </pre></div> -<H3><a name="Scilab_wrapping_cpp_inheritance">39.3.9 C++ inheritance</a></H3> +<H3><a name="Scilab_wrapping_cpp_inheritance">35.3.9 C++ inheritance</a></H3> <p> @@ -1120,25 +1129,25 @@ But we can use either use the <tt>get_perimeter()</tt> function of the parent cl 18.84 </pre></div> -<H3><a name="Scilab_wrapping_cpp_overloading">39.3.10 C++ overloading</a></H3> +<H3><a name="Scilab_wrapping_cpp_overloading">35.3.10 C++ overloading</a></H3> <p> -As explained in <a href="SWIGPlus.html#SWIGPlus_overloaded_methods">6.15</a> SWIG provides support for overloaded functions and constructors. +As explained in <a href="SWIGPlus.html#SWIGPlus_overloaded_methods">Overloaded functions and methods</a> SWIG provides support for overloaded functions and constructors. </p> -<p>As SWIG knows pointer types, the overloading works also with pointer types, here is is an example with a function <tt>magnify</tt> overloaded for the previous classes <tt>Shape</tt> and <tt>Circle</tt>: +<p>As SWIG knows pointer types, the overloading works also with pointer types, here is an example with a function <tt>magnify</tt> overloaded for the previous classes <tt>Shape</tt> and <tt>Circle</tt>: </p> <div class="code"><pre> %module example void magnify(Square *square, double factor) { - square->size *= factor; + square->size *= factor; }; void magnify(Circle *circle, double factor) { - square->radius *= factor; + square->radius *= factor; }; </pre></div> @@ -1160,7 +1169,7 @@ void magnify(Circle *circle, double factor) { </pre></div> -<H3><a name="Scilab_wrapping_pointers_references_values_arrays">39.3.11 Pointers, references, values, and arrays</a></H3> +<H3><a name="Scilab_wrapping_pointers_references_values_arrays">35.3.11 Pointers, references, values, and arrays</a></H3> <p> @@ -1218,7 +1227,7 @@ All these functions will return a pointer to an instance of <tt>Foo</tt>. As the function <tt>spam7</tt> returns a value, new instance of <tt>Foo</tt> has to be allocated, and a pointer on this instance is returned. </p> -<H3><a name="Scilab_wrapping_cpp_templates">39.3.12 C++ templates</a></H3> +<H3><a name="Scilab_wrapping_cpp_templates">35.3.12 C++ templates</a></H3> <p> @@ -1277,7 +1286,7 @@ Then in Scilab: More details on template support can be found in the <a href="SWIGPlus.html#SWIGPlus_nn30">templates</a> documentation. </p> -<H3><a name="Scilab_wrapping_cpp_operators">39.3.13 C++ operators</a></H3> +<H3><a name="Scilab_wrapping_cpp_operators">35.3.13 C++ operators</a></H3> <p> @@ -1330,7 +1339,7 @@ private: </pre></div> -<H3><a name="Scilab_wrapping_cpp_namespaces">39.3.14 C++ namespaces</a></H3> +<H3><a name="Scilab_wrapping_cpp_namespaces">35.3.14 C++ namespaces</a></H3> <p> @@ -1408,7 +1417,7 @@ Note: the <a href="SWIGPlus.html#SWIGPlus_nspace">nspace</a> feature is not supp </p> -<H3><a name="Scilab_wrapping_cpp_exceptions">39.3.15 C++ exceptions</a></H3> +<H3><a name="Scilab_wrapping_cpp_exceptions">35.3.15 C++ exceptions</a></H3> <p> @@ -1432,7 +1441,7 @@ void throw_exception() throw(char const *) { <div class="targetlang"><pre> -->throw_exception() !--error 999 -SWIG/Scilab: Exception (char const *) occured: Bye world ! +SWIG/Scilab: Exception (char const *) occurred: Bye world ! </pre></div> <p> @@ -1449,7 +1458,7 @@ It can be used with the <tt>lasterror()</tt> function as following: --> lasterror() ans = - SWIG/Scilab: Exception (char const *) occured: Bye world ! + SWIG/Scilab: Exception (char const *) occurred: Bye world ! </pre></div> <p> @@ -1479,7 +1488,7 @@ void throw_stl_invalid_arg(int i) throw(std::invalid_argument) { <div class="targetlang"><pre> --> throw_int(); !--error 999 -SWIG/Scilab: Exception (int) occured: 12 +SWIG/Scilab: Exception (int) occurred: 12 -->throw_stl_invalid_arg(-1); !--error 999 @@ -1491,17 +1500,17 @@ More complex or custom exception types require specific exception typemaps to be See the <a href="SWIGPlus.html#SWIGPlus">SWIG C++ documentation</a> for more details. </p> -<H3><a name="Scilab_wrapping_cpp_stl">39.3.16 C++ STL</a></H3> +<H3><a name="Scilab_wrapping_cpp_stl">35.3.16 C++ STL</a></H3> <p> The Standard Template Library (STL) is partially supported. See <a href="#Scilab_typemaps_stl">STL</a> for more details. </p> -<H2><a name="Scilab_typemaps">39.4 Type mappings and libraries</a></H2> +<H2><a name="Scilab_typemaps">35.4 Type mappings and libraries</a></H2> -<H3><a name="Scilab_typemaps_primitive_types">39.4.1 Default primitive type mappings</a></H3> +<H3><a name="Scilab_typemaps_primitive_types">35.4.1 Default primitive type mappings</a></H3> <p> @@ -1552,7 +1561,7 @@ The default behaviour is for SWIG to generate code that will give a runtime erro -<H3><a name="Scilab_typemaps_arrays">39.4.2 Arrays</a></H3> +<H3><a name="Scilab_typemaps_arrays">35.4.2 Arrays</a></H3> <p> @@ -1607,15 +1616,15 @@ void printArray(int values[], int len) { [ 0 1 2 3 ] </pre></div> -<H3><a name="Scilab_typemaps_pointer-to-pointers">39.4.3 Pointer-to-pointers</a></H3> +<H3><a name="Scilab_typemaps_pointer-to-pointers">35.4.3 Pointer-to-pointers</a></H3> <p> -There are no specific typemaps for pointer-to-pointers, they are are mapped as pointers in Scilab. +There are no specific typemaps for pointer-to-pointers, they are mapped as pointers in Scilab. </p> <p> -Pointer-to-pointers are sometimes used to implement matrices in C. The following is a an example of this: +Pointer-to-pointers are sometimes used to implement matrices in C. The following is an example of this: </p> @@ -1680,7 +1689,7 @@ void print_matrix(double **M, int nbRows, int nbCols) { </pre></div> -<H3><a name="Scilab_typemaps_matrices">39.4.4 Matrices</a></H3> +<H3><a name="Scilab_typemaps_matrices">35.4.4 Matrices</a></H3> <p> @@ -1773,7 +1782,7 @@ The remarks made earlier for arrays also apply here: <li>There is no control while converting <tt>double</tt> values to integers, <tt>double</tt> values are truncated without any checking or warning.</li> </ul> -<H3><a name="Scilab_typemaps_stl">39.4.5 STL</a></H3> +<H3><a name="Scilab_typemaps_stl">35.4.5 STL</a></H3> <p> @@ -1973,7 +1982,7 @@ ans = --> delete_PersonPtrSet(p); </pre></div> -<H2><a name="Scilab_module_initialization">39.5 Module initialization</a></H2> +<H2><a name="Scilab_module_initialization">35.5 Module initialization</a></H2> <p> @@ -1997,7 +2006,7 @@ For example, to initialize the module <tt>example</tt>: --> example_Init(); </pre></div> -<H2><a name="Scilab_building_modes">39.6 Building modes</a></H2> +<H2><a name="Scilab_building_modes">35.6 Building modes</a></H2> <p> @@ -2012,7 +2021,7 @@ To produce a dynamic module, when generating the wrapper, there are two possibil <li>the <tt>builder</tt> mode. In this mode, Scilab is responsible of building. </ul> -<H3><a name="Scilab_building_modes_nobuilder_mode">39.6.1 No-builder mode</a></H3> +<H3><a name="Scilab_building_modes_nobuilder_mode">35.6.1 No-builder mode</a></H3> <p> @@ -2025,7 +2034,7 @@ This mode is the best option to use when you have to integrate the module build </p> -<H3><a name="Scilab_building_modes_builder_mode">39.6.2 Builder mode</a></H3> +<H3><a name="Scilab_building_modes_builder_mode">35.6.2 Builder mode</a></H3> <p> @@ -2053,7 +2062,7 @@ In this mode, the following SWIG options may be used to setup the build: Let's give an example how to build a module <tt>example</tt>, composed of two sources, and using a library dependency: </p> <ul> -<li>the sources are <tt>baa1.c</tt> and <tt>baa2.c</tt> (and are stored in in the current directory)</li> +<li>the sources are <tt>baa1.c</tt> and <tt>baa2.c</tt> (and are stored in the current directory)</li> <li>the library is <tt>libfoo</tt> in <tt>/opt/foo</tt> (headers stored in <tt>/opt/foo/include</tt>, and shared library in <tt>/opt/foo/lib</tt>)</li> </ul> @@ -2065,14 +2074,14 @@ The command is: $ swig -scilab -builder -buildercflags -I/opt/foo/include -builderldflags "-L/opt/foo/lib -lfoo" -buildersources baa1.cxx, baa2.cxx example.i </pre></div> -<H2><a name="Scilab_generated_scripts">39.7 Generated scripts</a></H2> +<H2><a name="Scilab_generated_scripts">35.7 Generated scripts</a></H2> <p> In this part we give some details about the generated Scilab scripts. </p> -<H3><a name="Scilab_generated_scripts_builder_script">39.7.1 Builder script</a></H3> +<H3><a name="Scilab_generated_scripts_builder_script">35.7.1 Builder script</a></H3> <p> @@ -2097,7 +2106,7 @@ ilib_build(ilib_name, table, files, libs); <li><tt><b>table</b></tt>: two column string matrix containing a table of pairs of 'scilab function name', 'C function name'.</li> </ul> -<H3><a name="Scilab_generated_scripts_loader_script">39.7.2 Loader script</a></H3> +<H3><a name="Scilab_generated_scripts_loader_script">35.7.2 Loader script</a></H3> <p> @@ -2136,7 +2145,7 @@ clear get_file_path; </ul> -<H2><a name="Scilab_other_resources">39.8 Other resources</a></H2> +<H2><a name="Scilab_other_resources">35.8 Other resources</a></H2> <ul> diff --git a/Doc/Manual/Sections.html b/Doc/Manual/Sections.html index 368f306b5..cc5f05e82 100644 --- a/Doc/Manual/Sections.html +++ b/Doc/Manual/Sections.html @@ -1,14 +1,14 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> -<title>SWIG-3.0 Documentation</title> +<title>SWIG-4.0 Documentation</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head> <body bgcolor="#ffffff"> -<H1><a name="Sections">SWIG-3.0 Documentation</a></H1> +<H1><a name="Sections">SWIG-4.0 Documentation</a></H1> <p> -Last update : SWIG-3.0.12 (27 Jan 2017) +Last update : SWIG-4.0.1 (21 Aug 2019) </p> <H2><a name="Sections_Sections">Sections</a></H2> @@ -22,6 +22,8 @@ Last update : SWIG-3.0.12 (27 Jan 2017) <li><a href="SWIG.html#SWIG">SWIG Basics</a> (Read this!)</li> <li><a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a></li> <li><a href="CPlusPlus11.html#CPlusPlus11">SWIG and C++11</a></li> +<li><a href="CPlusPlus14.html#CPlusPlus14">SWIG and C++14</a></li> +<li><a href="CPlusPlus17.html#CPlusPlus17">SWIG and C++17</a></li> <li><a href="Preprocessor.html#Preprocessor">The SWIG preprocessor</a></li> <li><a href="Library.html#Library">The SWIG library</a></li> <li><a href="Arguments.html#Arguments">Argument handling</a></li> @@ -29,32 +31,26 @@ Last update : SWIG-3.0.12 (27 Jan 2017) <li><a href="Customization.html#Customization">Customization features</a></li> <li><a href="Contract.html#Contract">Contracts</a></li> <li><a href="Varargs.html#Varargs">Variable length arguments</a></li> +<li><a href="Doxygen.html#Doxygen">Doxygen documentation comments</a></li> <li><a href="Warnings.html#Warnings">Warning messages</a></li> <li><a href="Modules.html#Modules">Working with Modules</a></li> <li><a href="CCache.html#CCache">Using SWIG with ccache</a></li> </ul> -<H3><a name="Sections_language_modules">Language Module Documentation</a></H3> +<H3><a name="Sections_language_modules">Supported Language Modules Documentation</a></H3> <ul> -<li><a href="Allegrocl.html#Allegrocl">Allegro Common Lisp support</a></li> <li><a href="Android.html#Android">Android support</a></li> <li><a href="CSharp.html#CSharp">C# support</a></li> -<li><a href="Chicken.html#Chicken">Chicken support</a></li> <li><a href="D.html#D">D support</a></li> <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#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> -<li><a href="Mzscheme.html#Mzscheme">MzScheme/Racket support</a></li> -<li><a href="Ocaml.html#Ocaml">Ocaml support</a></li> <li><a href="Octave.html#Octave">Octave support</a></li> <li><a href="Perl5.html#Perl5">Perl5 support</a></li> <li><a href="Php.html#Php">PHP support</a></li> -<li><a href="Pike.html#Pike">Pike support</a></li> <li><a href="Python.html#Python">Python support</a></li> <li><a href="R.html#R">R support</a></li> <li><a href="Ruby.html#Ruby">Ruby support</a></li> @@ -62,6 +58,13 @@ Last update : SWIG-3.0.12 (27 Jan 2017) <li><a href="Tcl.html#Tcl">Tcl support</a></li> </ul> +<H3><a name="Sections_experimental_language_modules">Experimental Language Modules Documentation</a></H3> + +<ul> +<li><a href="Mzscheme.html#Mzscheme">MzScheme/Racket support</a></li> +<li><a href="Ocaml.html#Ocaml">OCaml support</a></li> +</ul> + <H3><a name="Sections_developers_docs">Developer Documentation</a></H3> <ul> diff --git a/Doc/Manual/Tcl.html b/Doc/Manual/Tcl.html index 38d4103e0..ba5ca3852 100644 --- a/Doc/Manual/Tcl.html +++ b/Doc/Manual/Tcl.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Tcl">40 SWIG and Tcl</a></H1> +<H1><a name="Tcl">36 SWIG and Tcl</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -84,11 +84,11 @@ 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">40.1 Preliminaries</a></H2> +<H2><a name="Tcl_nn2">36.1 Preliminaries</a></H2> <p> -To build a Tcl module, run SWIG using the <tt>-tcl</tt> option : +To build a Tcl module, run SWIG using the <tt>-tcl</tt> or <tt>-tcl8</tt> option : </p> <div class="code"><pre> @@ -110,7 +110,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">40.1.1 Getting the right header files</a></H3> +<H3><a name="Tcl_nn3">36.1.1 Getting the right header files</a></H3> <p> @@ -128,7 +128,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">40.1.2 Compiling a dynamic module</a></H3> +<H3><a name="Tcl_nn4">36.1.2 Compiling a dynamic module</a></H3> <p> @@ -164,7 +164,7 @@ The name of the module is specified using the <tt>%module</tt> directive or the <tt>-module</tt> command line option. </p> -<H3><a name="Tcl_nn5">40.1.3 Static linking</a></H3> +<H3><a name="Tcl_nn5">36.1.3 Static linking</a></H3> <p> @@ -230,7 +230,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">40.1.4 Using your module</a></H3> +<H3><a name="Tcl_nn6">36.1.4 Using your module</a></H3> <p> @@ -358,7 +358,7 @@ to the default system configuration (this requires root access and you will need the man pages). </p> -<H3><a name="Tcl_nn7">40.1.5 Compilation of C++ extensions</a></H3> +<H3><a name="Tcl_nn7">36.1.5 Compilation of C++ extensions</a></H3> <p> @@ -441,7 +441,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">40.1.6 Compiling for 64-bit platforms</a></H3> +<H3><a name="Tcl_nn8">36.1.6 Compiling for 64-bit platforms</a></H3> <p> @@ -468,7 +468,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">40.1.7 Setting a package prefix</a></H3> +<H3><a name="Tcl_nn9">36.1.7 Setting a package prefix</a></H3> <p> @@ -487,7 +487,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">40.1.8 Using namespaces</a></H3> +<H3><a name="Tcl_nn10">36.1.8 Using namespaces</a></H3> <p> @@ -509,7 +509,7 @@ 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">40.2 Building Tcl/Tk Extensions under Windows 95/NT</a></H2> +<H2><a name="Tcl_nn11">36.2 Building Tcl/Tk Extensions under Windows 95/NT</a></H2> <p> @@ -520,7 +520,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">40.2.1 Running SWIG from Developer Studio</a></H3> +<H3><a name="Tcl_nn12">36.2.1 Running SWIG from Developer Studio</a></H3> <p> @@ -578,7 +578,7 @@ MSDOS > tclsh80 % </pre></div> -<H3><a name="Tcl_nn13">40.2.2 Using NMAKE</a></H3> +<H3><a name="Tcl_nn13">36.2.2 Using NMAKE</a></H3> <p> @@ -641,7 +641,7 @@ to get you started. With a little practice, you'll be making lots of Tcl extensions. </p> -<H2><a name="Tcl_nn14">40.3 A tour of basic C/C++ wrapping</a></H2> +<H2><a name="Tcl_nn14">36.3 A tour of basic C/C++ wrapping</a></H2> <p> @@ -652,7 +652,7 @@ classes. This section briefly covers the essential aspects of this wrapping. </p> -<H3><a name="Tcl_nn15">40.3.1 Modules</a></H3> +<H3><a name="Tcl_nn15">36.3.1 Modules</a></H3> <p> @@ -686,7 +686,7 @@ To fix this, supply an extra argument to <tt>load</tt> like this: </pre> </div> -<H3><a name="Tcl_nn16">40.3.2 Functions</a></H3> +<H3><a name="Tcl_nn16">36.3.2 Functions</a></H3> <p> @@ -711,7 +711,7 @@ like you think it does: % </pre></div> -<H3><a name="Tcl_nn17">40.3.3 Global variables</a></H3> +<H3><a name="Tcl_nn17">36.3.3 Global variables</a></H3> <p> @@ -791,7 +791,7 @@ extern char *path; // Read-only (due to %immutable) </pre> </div> -<H3><a name="Tcl_nn18">40.3.4 Constants and enums</a></H3> +<H3><a name="Tcl_nn18">36.3.4 Constants and enums</a></H3> <p> @@ -875,7 +875,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">40.3.5 Pointers</a></H3> +<H3><a name="Tcl_nn19">36.3.5 Pointers</a></H3> <p> @@ -958,7 +958,7 @@ Foo *BarToFoo(Bar *b) { } Foo *IncrFoo(Foo *f, int i) { - return f+i; + return f+i; } %} </pre> @@ -971,7 +971,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">40.3.6 Structures</a></H3> +<H3><a name="Tcl_nn20">36.3.6 Structures</a></H3> <p> @@ -1054,7 +1054,7 @@ example, consider this: <div class="code"> <pre> struct Bar { - int x[16]; + int x[16]; }; </pre> </div> @@ -1253,7 +1253,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">40.3.7 C++ classes</a></H3> +<H3><a name="Tcl_nn21">36.3.7 C++ classes</a></H3> <p> @@ -1319,7 +1319,7 @@ In Tcl, the static member is accessed as follows: </pre> </div> -<H3><a name="Tcl_nn22">40.3.8 C++ inheritance</a></H3> +<H3><a name="Tcl_nn22">36.3.8 C++ inheritance</a></H3> <p> @@ -1368,7 +1368,7 @@ For instance: It is safe to use multiple inheritance with SWIG. </p> -<H3><a name="Tcl_nn23">40.3.9 Pointers, references, values, and arrays</a></H3> +<H3><a name="Tcl_nn23">36.3.9 Pointers, references, values, and arrays</a></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">40.3.10 C++ overloaded functions</a></H3> +<H3><a name="Tcl_nn24">36.3.10 C++ overloaded functions</a></H3> <p> @@ -1456,9 +1456,9 @@ Similarly, if you have a class like this, <pre> class Foo { public: - Foo(); - Foo(const Foo &); - ... + Foo(); + Foo(const Foo &); + ... }; </pre> </div> @@ -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">40.3.11 C++ operators</a></H3> +<H3><a name="Tcl_nn25">36.3.11 C++ operators</a></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">40.3.12 C++ namespaces</a></H3> +<H3><a name="Tcl_nn26">36.3.12 C++ namespaces</a></H3> <p> @@ -1693,11 +1693,11 @@ For example: %rename(Bar_spam) Bar::spam; namespace Foo { - int spam(); + int spam(); } namespace Bar { - int spam(); + int spam(); } </pre> </div> @@ -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">40.3.13 C++ templates</a></H3> +<H3><a name="Tcl_nn27">36.3.13 C++ templates</a></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">40.3.14 C++ Smart Pointers</a></H3> +<H3><a name="Tcl_nn28">36.3.14 C++ Smart Pointers</a></H3> <p> @@ -1847,7 +1847,7 @@ simply use the <tt>__deref__()</tt> method. For example: </pre> </div> -<H2><a name="Tcl_nn29">40.4 Further details on the Tcl class interface</a></H2> +<H2><a name="Tcl_nn29">36.4 Further details on the Tcl class interface</a></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">40.4.1 Proxy classes</a></H3> +<H3><a name="Tcl_nn30">36.4.1 Proxy classes</a></H3> <p> @@ -1886,19 +1886,19 @@ then SWIG transforms it into a set of low-level procedural wrappers. For example <div class="code"> <pre> Foo *new_Foo() { - return new Foo(); + return new Foo(); } void delete_Foo(Foo *f) { - delete f; + delete f; } int Foo_x_get(Foo *f) { - return f->x; + return f->x; } void Foo_x_set(Foo *f, int value) { - f->x = value; + f->x = value; } int Foo_spam(Foo *f, int arg1) { - return f->spam(arg1); + return f->spam(arg1); } </pre> </div> @@ -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">40.4.2 Memory management</a></H3> +<H3><a name="Tcl_nn31">36.4.2 Memory management</a></H3> <p> @@ -1945,8 +1945,8 @@ ownership of the result. For example: <pre> class Foo { public: - Foo(); - Foo bar(); + Foo(); + Foo bar(); }; </pre> </div> @@ -1975,9 +1975,9 @@ they came from. Therefore, the ownership is set to zero. For example: <pre> class Foo { public: - ... - Foo *spam(); - ... + ... + Foo *spam(); + ... }; </pre> </div> @@ -2011,8 +2011,8 @@ or global variable. For example, consider this interface: %module example struct Foo { - int value; - Foo *next; + int value; + Foo *next; }; Foo *head = 0; @@ -2113,7 +2113,7 @@ typemaps--an advanced topic discussed later. </p> -<H2><a name="Tcl_nn32">40.5 Input and output parameters</a></H2> +<H2><a name="Tcl_nn32">36.5 Input and output parameters</a></H2> <p> @@ -2301,7 +2301,7 @@ set c [lindex $dim 1] </pre> </div> -<H2><a name="Tcl_nn33">40.6 Exception handling </a></H2> +<H2><a name="Tcl_nn33">36.6 Exception handling </a></H2> <p> @@ -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">40.7 Typemaps</a></H2> +<H2><a name="Tcl_nn34">36.7 Typemaps</a></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">40.7.1 What is a typemap?</a></H3> +<H3><a name="Tcl_nn35">36.7.1 What is a typemap?</a></H3> <p> @@ -2465,9 +2465,9 @@ you might define a typemap like this: %module example %typemap(in) int { - if (Tcl_GetIntFromObj(interp, $input, &$1) == TCL_ERROR) - return TCL_ERROR; - printf("Received an integer : %d\n", $1); + if (Tcl_GetIntFromObj(interp, $input, &$1) == TCL_ERROR) + return TCL_ERROR; + printf("Received an integer : %d\n", $1); } %inline %{ extern int fact(int n); @@ -2572,7 +2572,7 @@ parameter is omitted): </pre> </div> -<H3><a name="Tcl_nn36">40.7.2 Tcl typemaps</a></H3> +<H3><a name="Tcl_nn36">36.7.2 Tcl typemaps</a></H3> <p> @@ -2585,7 +2585,7 @@ like this: <div class="code"> <pre> %typemap(out) int { - Tcl_SetObjResult(interp, Tcl_NewIntObj($1)); + Tcl_SetObjResult(interp, Tcl_NewIntObj($1)); } </pre> </div> @@ -2710,7 +2710,7 @@ Initialize an argument to a value before any conversions occur. Examples of these methods will appear shortly. </p> -<H3><a name="Tcl_nn37">40.7.3 Typemap variables</a></H3> +<H3><a name="Tcl_nn37">36.7.3 Typemap variables</a></H3> <p> @@ -2781,7 +2781,7 @@ properly assigned. The Tcl name of the wrapper function being created. </div> -<H3><a name="Tcl_nn38">40.7.4 Converting a Tcl list to a char ** </a></H3> +<H3><a name="Tcl_nn38">36.7.4 Converting a Tcl list to a char ** </a></H3> <p> @@ -2843,7 +2843,7 @@ argv[2] = Larry 3 </pre></div> -<H3><a name="Tcl_nn39">40.7.5 Returning values in arguments</a></H3> +<H3><a name="Tcl_nn39">36.7.5 Returning values in arguments</a></H3> <p> @@ -2885,7 +2885,7 @@ result, a Tcl function using these typemaps will work like this : % </pre></div> -<H3><a name="Tcl_nn40">40.7.6 Useful functions</a></H3> +<H3><a name="Tcl_nn40">36.7.6 Useful functions</a></H3> <p> @@ -2961,7 +2961,7 @@ int Tcl_IsShared(Tcl_Obj *obj); </pre> </div> -<H3><a name="Tcl_nn41">40.7.7 Standard typemaps</a></H3> +<H3><a name="Tcl_nn41">36.7.7 Standard typemaps</a></H3> <p> @@ -3045,7 +3045,7 @@ work) </pre> </div> -<H3><a name="Tcl_nn42">40.7.8 Pointer handling</a></H3> +<H3><a name="Tcl_nn42">36.7.8 Pointer handling</a></H3> <p> @@ -3127,7 +3127,7 @@ For example: </pre> </div> -<H2><a name="Tcl_nn43">40.8 Turning a SWIG module into a Tcl Package.</a></H2> +<H2><a name="Tcl_nn43">36.8 Turning a SWIG module into a Tcl Package.</a></H2> <p> @@ -3199,7 +3199,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">40.9 Building new kinds of Tcl interfaces (in Tcl)</a></H2> +<H2><a name="Tcl_nn44">36.9 Building new kinds of Tcl interfaces (in Tcl)</a></H2> <p> @@ -3215,28 +3215,28 @@ helper functions to access arrays : %inline %{ double *new_double(int size) { - return (double *) malloc(size*sizeof(double)); + return (double *) malloc(size*sizeof(double)); } void delete_double(double *a) { - free(a); + free(a); } double get_double(double *a, int index) { - return a[index]; + return a[index]; } void set_double(double *a, int index, double val) { - a[index] = val; + a[index] = val; } int *new_int(int size) { - return (int *) malloc(size*sizeof(int)); + return (int *) malloc(size*sizeof(int)); } void delete_int(int *a) { - free(a); + free(a); } int get_int(int *a, int index) { - return a[index]; + return a[index]; } int set_int(int *a, int index, int val) { - a[index] = val; + a[index] = val; } %} @@ -3298,7 +3298,7 @@ danger of blowing something up (although it is easily accomplished with an out of bounds array access). </p> -<H3><a name="Tcl_nn45">40.9.1 Proxy classes</a></H3> +<H3><a name="Tcl_nn45">36.9.1 Proxy classes</a></H3> <p> @@ -3419,7 +3419,7 @@ short, but clever Tcl script can be combined with SWIG to do many interesting things. </p> -<H2><a name="Tcl_nn46">40.10 Tcl/Tk Stubs</a></H2> +<H2><a name="Tcl_nn46">36.10 Tcl/Tk Stubs</a></H2> <p> diff --git a/Doc/Manual/Typemaps.html b/Doc/Manual/Typemaps.html index a3a3e09cb..0bacd39f5 100644 --- a/Doc/Manual/Typemaps.html +++ b/Doc/Manual/Typemaps.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Typemaps">11 Typemaps</a></H1> +<H1><a name="Typemaps">13 Typemaps</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -67,7 +67,7 @@ <li><a href="#Typemaps_nn35">"memberin" typemap</a> <li><a href="#Typemaps_nn36">"varin" typemap</a> <li><a href="#Typemaps_nn37">"varout" typemap</a> -<li><a href="#throws_typemap">"throws" typemap</a> +<li><a href="#Typemaps_throws_typemap">"throws" typemap</a> </ul> <li><a href="#Typemaps_nn39">Some typemap examples</a> <ul> @@ -89,6 +89,9 @@ <li><a href="#Typemaps_runtime_type_checker_usage">Usage</a> </ul> <li><a href="#Typemaps_overloading">Typemaps and overloading</a> +<ul> +<li><a href="#Typemaps_typecheck_pointer">SWIG_TYPECHECK_POINTER precedence level and the typecheck typemap</a> +</ul> <li><a href="#Typemaps_nn48">More about %apply and %clear</a> <li><a href="#Typemaps_nn47">Passing data between typemaps</a> <li><a href="#Typemaps_nn52">C++ "this" pointer</a> @@ -99,7 +102,7 @@ -<H2><a name="Typemaps_nn2">11.1 Introduction</a></H2> +<H2><a name="Typemaps_nn2">13.1 Introduction</a></H2> <p> @@ -116,7 +119,7 @@ to re-read the earlier chapters if you have found your way to this chapter with only a vague idea of what SWIG already does by default. </p> -<H3><a name="Typemaps_nn3">11.1.1 Type conversion</a></H3> +<H3><a name="Typemaps_nn3">13.1.1 Type conversion</a></H3> <p> @@ -209,7 +212,7 @@ to read the extension documentation for your favorite language to know how it works (an exercise left to the reader). </p> -<H3><a name="Typemaps_nn4">11.1.2 Typemaps</a></H3> +<H3><a name="Typemaps_nn4">13.1.2 Typemaps</a></H3> <p> @@ -310,7 +313,7 @@ parts of the generated wrapper functions. Because arbitrary code can be insert possible to completely change the way in which values are converted. </p> -<H3><a name="Typemaps_nn5">11.1.3 Pattern matching</a></H3> +<H3><a name="Typemaps_nn5">13.1.3 Pattern matching</a></H3> <p> @@ -361,7 +364,7 @@ int spam(<b>foo::Number</b> a, <b>foo::Number</b> b); <p> In this case, the typemap is still applied to the proper arguments even though typenames don't always match the text "int". This ability to track types is a critical part of SWIG--in fact, all -of the target language modules work merely define a set of typemaps for the basic types. Yet, it +of the target language modules work merely define a family of typemaps for the basic types. Yet, it is never necessary to write new typemaps for typenames introduced by <tt>typedef</tt>. </p> @@ -412,7 +415,7 @@ In this case, a single input object is expanded into a pair of C arguments. Thi provides a hint to the unusual variable naming scheme involving <tt>$1</tt>, <tt>$2</tt>, and so forth. </p> -<H3><a name="Typemaps_nn6">11.1.4 Reusing typemaps</a></H3> +<H3><a name="Typemaps_nn6">13.1.4 Reusing typemaps</a></H3> <p> @@ -428,7 +431,8 @@ be copied and reused. One way to do this is to use assignment like this: </div> <p> -A more general form of copying is found in the <tt>%apply</tt> directive like this: +There is a more powerful way to copy a family of typemaps though. +Consider the following family of two typemap methods, "in" and "out" for type <tt>int</tt>: </p> <div class="code"> @@ -441,8 +445,29 @@ A more general form of copying is found in the <tt>%apply</tt> directive like th /* Return an integer value */ ... } +</pre> +</div> + +<p> +Each of the two typemap methods could be copied individually for type <tt>size_t</tt> as follows: +</p> + +<div class="code"> +<pre> +/* Apply all of the int typemaps to size_t */ +%typemap(in) size_t = int; +%typemap(out) size_t = int; +</pre> +</div> -/* Apply all of the integer typemaps to size_t */ +<p> +A more powerful form of copying is available from the <tt>%apply</tt> directive. +The code below is identical to the above: +</p> + +<div class="code"> +<pre> +/* Apply all of the int typemaps to size_t */ %apply int { size_t }; </pre> </div> @@ -468,7 +493,7 @@ typedef int size_t; then SWIG already knows that the <tt>int</tt> typemaps apply. You don't have to do anything. </p> -<H3><a name="Typemaps_nn7">11.1.5 What can be done with typemaps?</a></H3> +<H3><a name="Typemaps_nn7">13.1.5 What can be done with typemaps?</a></H3> <p> @@ -580,7 +605,7 @@ typemaps that expand upon this list. For example, the Java module defines a var aspects of the Java bindings. Consult language specific documentation for further details. </p> -<H3><a name="Typemaps_nn8">11.1.6 What can't be done with typemaps?</a></H3> +<H3><a name="Typemaps_nn8">13.1.6 What can't be done with typemaps?</a></H3> <p> @@ -643,12 +668,12 @@ void wrap_foo(char *s, int x) { </pre> </div> -<H3><a name="Typemaps_aspects">11.1.7 Similarities to Aspect Oriented Programming</a></H3> +<H3><a name="Typemaps_aspects">13.1.7 Similarities to Aspect Oriented Programming</a></H3> <p> -SWIG has parallels to <a href="http://en.wikipedia.org/wiki/Aspect-oriented_programming">Aspect Oriented Software Development (AOP)</a>. -The <a href="http://en.wikipedia.org/wiki/Aspect-oriented_programming#Terminology">AOP terminology</a> with respect to SWIG typemaps can be viewed as follows: +SWIG has parallels to <a href="https://en.wikipedia.org/wiki/Aspect-oriented_programming">Aspect Oriented Software Development (AOP)</a>. +The <a href="https://en.wikipedia.org/wiki/Aspect-oriented_programming#Terminology">AOP terminology</a> with respect to SWIG typemaps can be viewed as follows: </p> <ul> <li> <b>Cross-cutting concerns</b>: The cross-cutting concerns are the modularization of the functionality that the typemaps implement, which is primarily marshalling of types from/to the target language and C/C++. @@ -661,7 +686,7 @@ SWIG can also be viewed as has having a second set of aspects based around <a hr Features such as <tt>%exception</tt> are also cross-cutting concerns as they encapsulate code that can be used to add logging or exception handling to any function. </p> -<H3><a name="Typemaps_nn9">11.1.8 The rest of this chapter</a></H3> +<H3><a name="Typemaps_nn9">13.1.8 The rest of this chapter</a></H3> <p> @@ -681,14 +706,14 @@ of "The C Programming Language" by Kernighan and Ritchie or "The C++ Programming Language" by Stroustrup before going any further. </p> -<H2><a name="Typemaps_nn10">11.2 Typemap specifications</a></H2> +<H2><a name="Typemaps_nn10">13.2 Typemap specifications</a></H2> <p> This section describes the behavior of the <tt>%typemap</tt> directive itself. </p> -<H3><a name="Typemaps_defining">11.2.1 Defining a typemap</a></H3> +<H3><a name="Typemaps_defining">13.2.1 Defining a typemap</a></H3> <p> @@ -801,7 +826,7 @@ Admittedly, it's not the most readable syntax at first glance. However, the pur individual pieces will become clear. </p> -<H3><a name="Typemaps_nn12">11.2.2 Typemap scope</a></H3> +<H3><a name="Typemaps_nn12">13.2.2 Typemap scope</a></H3> <p> @@ -851,7 +876,7 @@ class Foo { </pre> </div> -<H3><a name="Typemaps_nn13">11.2.3 Copying a typemap</a></H3> +<H3><a name="Typemaps_nn13">13.2.3 Copying a typemap</a></H3> <p> @@ -909,40 +934,41 @@ The patterns for <tt>%apply</tt> follow the same rules as for <tt>%typemap</tt>. </pre> </div> -<H3><a name="Typemaps_nn14">11.2.4 Deleting a typemap</a></H3> +<H3><a name="Typemaps_nn14">13.2.4 Deleting a typemap</a></H3> <p> -A typemap can be deleted by simply defining no code. For example: +A particular typemap can be deleted / cleared by simply defining no code. For example: </p> <div class="code"> <pre> -%typemap(in) int; // Clears typemap for int -%typemap(in) int, long, short; // Clears typemap for int, long, short +%typemap(in) int; // Clears the "in" typemap for int +%typemap(in) int, long, short; // Clears the "in" typemap for int, long, short %typemap(in) int *output; </pre> </div> <p> -The <tt>%clear</tt> directive clears all typemaps for a given type. +The above syntax deletes a typemap for just one typemap method - the "in" method in each of the examples above. +The <tt>%clear</tt> directive is more powerful and will delete / clear a family of typemaps, that is, all the typemap methods for a given type. For example: </p> <div class="code"> <pre> -%clear int; // Removes all types for int +%clear int; // Delete all typemaps ("in", "out", "varin", ...) for int %clear int *output, long *output; </pre> </div> <p> <b>Note:</b> Since SWIG's default behavior is 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 +<tt>int</tt> will make that type unusable unless you also define a new family of typemaps immediately after the clear operation. </p> -<H3><a name="Typemaps_nn15">11.2.5 Placement of typemaps</a></H3> +<H3><a name="Typemaps_nn15">13.2.5 Placement of typemaps</a></H3> <p> @@ -1022,7 +1048,7 @@ It should be noted that for scoping to work, SWIG has to know that <tt>string</t within a particular namespace. In this example, this is done using the forward class declaration <tt>class string</tt>. </p> -<H2><a name="Typemaps_pattern_matching">11.3 Pattern matching rules</a></H2> +<H2><a name="Typemaps_pattern_matching">13.3 Pattern matching rules</a></H2> <p> @@ -1030,7 +1056,7 @@ The section describes the pattern matching rules by which C/C++ datatypes are as The matching rules can be observed in practice by using the debugging options also described. </p> -<H3><a name="Typemaps_nn17">11.3.1 Basic matching rules</a></H3> +<H3><a name="Typemaps_nn17">13.3.1 Basic matching rules</a></H3> <p> @@ -1129,7 +1155,7 @@ void F(int x[1000]); // int [ANY] rule (typemap 5) stripped all qualifiers in one step. </p> -<H3><a name="Typemaps_typedef_reductions">11.3.2 Typedef reductions matching</a></H3> +<H3><a name="Typemaps_typedef_reductions">13.3.2 Typedef reductions matching</a></H3> <p> @@ -1304,7 +1330,7 @@ void go(Struct aStruct); </pre> </div> -<H3><a name="Typemaps_nn19">11.3.3 Default typemap matching rules</a></H3> +<H3><a name="Typemaps_nn19">13.3.3 Default typemap matching rules</a></H3> <p> @@ -1357,7 +1383,7 @@ Below is a list of the typical default types supplied by language modules, showi %typemap(in) SWIGTYPE * { ... default pointer handling ... }; %typemap(in) SWIGTYPE *const { ... default pointer const handling ... }; %typemap(in) SWIGTYPE *const& { ... default pointer const reference handling ... }; -%typemap(in) SWIGTYPE[ANY] { ... 1D fixed size arrays handlling ... }; +%typemap(in) SWIGTYPE[ANY] { ... 1D fixed size arrays handling ... }; %typemap(in) SWIGTYPE [] { ... unknown sized array handling ... }; %typemap(in) enum SWIGTYPE { ... default handling for enum values ... }; %typemap(in) const enum SWIGTYPE & { ... default handling for const enum reference values ... }; @@ -1442,7 +1468,7 @@ Finally the best way to view the typemap matching rules in action is via the <a simpler scheme to match the current C++ class template partial specialization matching rules. </p> -<H3><a name="Typemaps_multi_argument_typemaps_patterns">11.3.4 Multi-arguments typemaps</a></H3> +<H3><a name="Typemaps_multi_argument_typemaps_patterns">13.3.4 Multi-arguments typemaps</a></H3> <p> @@ -1472,7 +1498,7 @@ but all subsequent arguments must match exactly. </p> -<H3><a name="Typemaps_matching_template_comparison">11.3.5 Matching rules compared to C++ templates</a></H3> +<H3><a name="Typemaps_matching_template_comparison">13.3.5 Matching rules compared to C++ templates</a></H3> <p> @@ -1631,7 +1657,7 @@ are similar to those for specialized template handling. </p> -<H3><a name="Typemaps_debugging_search">11.3.6 Debugging typemap pattern matching</a></H3> +<H3><a name="Typemaps_debugging_search">13.3.6 Debugging typemap pattern matching</a></H3> <p> @@ -1844,7 +1870,7 @@ Also the types may be displayed slightly differently - <tt>char const *</tt> and </li> </ul> -<H2><a name="Typemaps_nn21">11.4 Code generation rules</a></H2> +<H2><a name="Typemaps_nn21">13.4 Code generation rules</a></H2> <p> @@ -1852,7 +1878,7 @@ This section describes rules by which typemap code is inserted into the generated wrapper code. </p> -<H3><a name="Typemaps_nn22">11.4.1 Scope</a></H3> +<H3><a name="Typemaps_nn22">13.4.1 Scope</a></H3> <p> @@ -1930,7 +1956,7 @@ a block scope when it is emitted. This sometimes results in a less complicated Note that only the third of the three typemaps have the typemap code passed through the SWIG preprocessor. </p> -<H3><a name="Typemaps_nn23">11.4.2 Declaring new local variables</a></H3> +<H3><a name="Typemaps_nn23">13.4.2 Declaring new local variables</a></H3> <p> @@ -2097,7 +2123,7 @@ each type must have its own local variable declaration. </div> -<H3><a name="Typemaps_special_variables">11.4.3 Special variables</a></H3> +<H3><a name="Typemaps_special_variables">13.4.3 Special variables</a></H3> <p> @@ -2349,7 +2375,7 @@ Another approach, which only works for arrays is to use the <tt>$1_basetype</tt> </pre> </div> -<H3><a name="Typemaps_special_variable_macros">11.4.4 Special variable macros</a></H3> +<H3><a name="Typemaps_special_variable_macros">13.4.4 Special variable macros</a></H3> <p> @@ -2361,7 +2387,7 @@ it is done during the SWIG parsing/compilation stages. The following special variable macros are available across all language modules. </p> -<H4><a name="Typemaps_special_macro_descriptor">11.4.4.1 $descriptor(type)</a></H4> +<H4><a name="Typemaps_special_macro_descriptor">13.4.4.1 $descriptor(type)</a></H4> <p> @@ -2372,7 +2398,7 @@ For example, <tt>$descriptor(std::vector<int> *)</tt> will expand into <tt This macro is mostly used in the scripting target languages and is demonstrated later in the <a href="#Typemaps_runtime_type_checker_usage">Run-time type checker usage</a> section. </p> -<H4><a name="Typemaps_special_macro_typemap">11.4.4.2 $typemap(method, typepattern)</a></H4> +<H4><a name="Typemaps_special_macro_typemap">13.4.4.2 $typemap(method, typepattern)</a></H4> <p> @@ -2430,7 +2456,7 @@ The result is the following expansion </div> -<H3><a name="Typemaps_special_variable_attributes">11.4.5 Special variables and typemap attributes</a></H3> +<H3><a name="Typemaps_special_variable_attributes">13.4.5 Special variables and typemap attributes</a></H3> <p> @@ -2457,7 +2483,7 @@ is equivalent to the following as <tt>$*1_ltype</tt> expands to <tt>unsigned int </pre> </div> -<H3><a name="Typemaps_special_variables_and_macros">11.4.6 Special variables combined with special variable macros</a></H3> +<H3><a name="Typemaps_special_variables_and_macros">13.4.6 Special variables combined with special variable macros</a></H3> <p> @@ -2499,15 +2525,15 @@ which then expands to: </div> -<H2><a name="Typemaps_nn25">11.5 Common typemap methods</a></H2> +<H2><a name="Typemaps_nn25">13.5 Common typemap methods</a></H2> <p> -The set of typemaps recognized by a language module may vary. However, +The family of typemaps recognized by a language module may vary. However, the following typemap methods are nearly universal: </p> -<H3><a name="Typemaps_nn26">11.5.1 "in" typemap</a></H3> +<H3><a name="Typemaps_nn26">13.5.1 "in" typemap</a></H3> <p> @@ -2567,7 +2593,7 @@ Usually <tt>numinputs</tt> is not specified, whereupon the default value is 1, t is the same as the old "ignore" typemap. </p> -<H3><a name="Typemaps_nn27">11.5.2 "typecheck" typemap</a></H3> +<H3><a name="Typemaps_nn27">13.5.2 "typecheck" typemap</a></H3> <p> @@ -2594,7 +2620,7 @@ If you define new "in" typemaps <em>and</em> your program uses overloaded method "typecheck" typemaps. More details about this follow in the <a href="#Typemaps_overloading">Typemaps and overloading</a> section. </p> -<H3><a name="Typemaps_nn28">11.5.3 "out" typemap</a></H3> +<H3><a name="Typemaps_nn28">13.5.3 "out" typemap</a></H3> <p> @@ -2625,7 +2651,7 @@ $symname - Name of function/method being wrapped The "out" typemap supports an optional attribute flag called "optimal". This is for code optimisation and is detailed in the <a href="#Typemaps_optimal">Optimal code generation when returning by value</a> section. </p> -<H3><a name="Typemaps_nn29">11.5.4 "arginit" typemap</a></H3> +<H3><a name="Typemaps_nn29">13.5.4 "arginit" typemap</a></H3> <p> @@ -2644,7 +2670,7 @@ For example: </pre> </div> -<H3><a name="Typemaps_nn30">11.5.5 "default" typemap</a></H3> +<H3><a name="Typemaps_nn30">13.5.5 "default" typemap</a></H3> <p> @@ -2677,7 +2703,7 @@ See the <a href="SWIG.html#SWIG_default_args">Default/optional arguments</a> sec for further information on default argument wrapping. </p> -<H3><a name="Typemaps_nn31">11.5.6 "check" typemap</a></H3> +<H3><a name="Typemaps_nn31">13.5.6 "check" typemap</a></H3> <p> @@ -2696,7 +2722,7 @@ converted. For example: </pre> </div> -<H3><a name="Typemaps_nn32">11.5.7 "argout" typemap</a></H3> +<H3><a name="Typemaps_nn32">13.5.7 "argout" typemap</a></H3> <p> @@ -2742,7 +2768,7 @@ return values are often appended to return value of the function. See the <tt>typemaps.i</tt> library file for examples. </p> -<H3><a name="Typemaps_nn33">11.5.8 "freearg" typemap</a></H3> +<H3><a name="Typemaps_nn33">13.5.8 "freearg" typemap</a></H3> <p> @@ -2775,7 +2801,7 @@ be used in other typemaps whenever a wrapper function needs to abort prematurely. </p> -<H3><a name="Typemaps_nn34">11.5.9 "newfree" typemap</a></H3> +<H3><a name="Typemaps_nn34">13.5.9 "newfree" typemap</a></H3> <p> @@ -2804,7 +2830,7 @@ string *foo(); See <a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for further details. </p> -<H3><a name="Typemaps_ret">11.5.10 "ret" typemap</a></H3> +<H3><a name="Typemaps_ret">13.5.10 "ret" typemap</a></H3> <p> @@ -2843,7 +2869,7 @@ This approach is an alternative to using the "newfree" typemap and <tt>%newobjec is no need to list all the functions that require the memory cleanup, it is purely done on types. </p> -<H3><a name="Typemaps_nn35">11.5.11 "memberin" typemap</a></H3> +<H3><a name="Typemaps_nn35">13.5.11 "memberin" typemap</a></H3> <p> @@ -2865,7 +2891,7 @@ It is rarely necessary to write "memberin" typemaps---SWIG already provides a default implementation for arrays, strings, and other objects. </p> -<H3><a name="Typemaps_nn36">11.5.12 "varin" typemap</a></H3> +<H3><a name="Typemaps_nn36">13.5.12 "varin" typemap</a></H3> <p> @@ -2873,7 +2899,7 @@ The "varin" typemap is used to convert objects in the target language to C for t purposes of assigning to a C/C++ global variable. This is implementation specific. </p> -<H3><a name="Typemaps_nn37">11.5.13 "varout" typemap</a></H3> +<H3><a name="Typemaps_nn37">13.5.13 "varout" typemap</a></H3> <p> @@ -2881,11 +2907,11 @@ The "varout" typemap is used to convert a C/C++ object to an object in the targe language when reading a C/C++ global variable. This is implementation specific. </p> -<H3><a name="throws_typemap">11.5.14 "throws" typemap</a></H3> +<H3><a name="Typemaps_throws_typemap">13.5.14 "throws" typemap</a></H3> <p> -The "throws" typemap is only used when SWIG parses a C++ method with an exception specification or has the <tt>%catches</tt> feature attached to the method. +The "throws" typemap is only used when SWIG parses a C++ method with an exception specification or has the <tt>%catches</tt> feature attached to the method (see <a href="SWIGPlus.html#SWIGPlus_catches">Exception handling with %catches</a>). It provides a default mechanism for handling C++ methods that have declared the exceptions they will throw. The purpose of this typemap is to convert a C++ exception into an error or exception in the target language. It is slightly different to the other typemaps as it is based around the exception type rather than the type of a parameter or variable. @@ -2898,13 +2924,19 @@ For example: PyErr_SetString(PyExc_RuntimeError, $1); SWIG_fail; %} -void bar() throw (const char *); + +// Either an exception specification on the method + void bar() throw (const char *); + +// Or a %catches feature attached to the method + %catches(const char *) bar(); + void bar(); </pre> </div> <p> -As can be seen from the generated code below, SWIG generates an exception handler -with the catch block comprising the "throws" typemap content. +As can be seen from the resulting generated code below, SWIG generates an exception handler +when wrapping the <tt>bar</tt> function with the catch block comprising the "throws" typemap content. </p> <div class="code"> @@ -2912,8 +2944,7 @@ with the catch block comprising the "throws" typemap content. ... try { bar(); -} -catch(char const *_e) { +} catch(char const *_e) { PyErr_SetString(PyExc_RuntimeError, _e); SWIG_fail; } @@ -2922,11 +2953,11 @@ catch(char const *_e) { </div> <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="Customization.html#Customization_exception">Exception handling with %exception</a> section. +Note that if your methods do not have an exception specification but they do throw exceptions and you are not using <tt>%catches</tt>, SWIG cannot know how to deal with them. +Please also see the <a href="Customization.html#Customization_exception">Exception handling with %exception</a> section for another way to handle exceptions. </p> -<H2><a name="Typemaps_nn39">11.6 Some typemap examples</a></H2> +<H2><a name="Typemaps_nn39">13.6 Some typemap examples</a></H2> <p> @@ -2934,7 +2965,7 @@ This section contains a few examples. Consult language module documentation for more examples. </p> -<H3><a name="Typemaps_nn40">11.6.1 Typemaps for arrays</a></H3> +<H3><a name="Typemaps_nn40">13.6.1 Typemaps for arrays</a></H3> <p> @@ -3193,7 +3224,7 @@ Now, you will find that member access is quite nice: useless and has since been eliminated. To return structure members, simply use the "out" typemap. </p> -<H3><a name="Typemaps_nn41">11.6.2 Implementing constraints with typemaps</a></H3> +<H3><a name="Typemaps_nn41">13.6.2 Implementing constraints with typemaps</a></H3> <p> @@ -3241,7 +3272,7 @@ a NULL pointer. As a result, SWIG can often prevent a potential segmentation faults or other run-time problems by raising an exception rather than blindly passing values to the underlying C/C++ program.</p> -<H2><a name="Typemaps_nn43">11.7 Typemaps for multiple target languages</a></H2> +<H2><a name="Typemaps_nn43">13.7 Typemaps for multiple target languages</a></H2> <p> @@ -3271,12 +3302,12 @@ The example above also shows a common approach of issuing a warning for an as ye <tt>%typemap(ruby, in) int "$1 = NUM2INT($input);"</tt>. </p> -<H2><a name="Typemaps_optimal">11.8 Optimal code generation when returning by value</a></H2> +<H2><a name="Typemaps_optimal">13.8 Optimal code generation when returning by value</a></H2> <p> The "out" typemap is the main typemap for return types. -This typemap supports an optional attribute flag called "optimal", which is for reducing +This typemap supports an optional attribute flag called "optimal", which is for reducing the number of temporary variables and the amount of generated code, thereby giving the compiler the opportunity to use <i>return value optimization</i> for generating faster executing code. It only really makes a difference when returning objects by value and has some limitations on usage, @@ -3460,7 +3491,7 @@ example.i:7: Warning 475: optimal attribute usage in the out typemap. However, it doesn't always get it right, for example when <tt>$1</tt> is within some commented out code. </p> -<H2><a name="Typemaps_multi_argument_typemaps">11.9 Multi-argument typemaps</a></H2> +<H2><a name="Typemaps_multi_argument_typemaps">13.9 Multi-argument typemaps</a></H2> <p> @@ -3737,7 +3768,7 @@ with non-consecutive C/C++ arguments; a workaround such as a helper function re- the arguments to make them consecutive will need to be written. </p> -<H2><a name="Typemaps_warnings">11.10 Typemap warnings</a></H2> +<H2><a name="Typemaps_warnings">13.10 Typemap warnings</a></H2> <p> @@ -3746,7 +3777,7 @@ See the information in the <a href="Warnings.html#Warnings_nn5">issuing warnings </p> -<H2><a name="Typemaps_fragments">11.11 Typemap fragments</a></H2> +<H2><a name="Typemaps_fragments">13.11 Typemap fragments</a></H2> <p> @@ -3904,9 +3935,9 @@ A fragment can use one or more additional fragments, for example: <div class="code"> <pre> -%fragment("<limits.h>", "header") { - %#include <limits.h> -} +%fragment("<limits.h>", "header") %{ + #include <limits.h> +%} %fragment("AsMyClass", "header", fragment="<limits.h>") { @@ -3989,8 +4020,91 @@ Finally, you can force the inclusion of a fragment at any point in the generated </div> <p> -which is very useful inside a template class, for example. +which, for example, is very useful inside a template class. +Another useful case is when using <tt>%extend</tt> inside a class +where the additional code in the <tt>%extend</tt> block depends on the contents of the fragment. +</p> + +<div class="code"> +<pre> +%fragment("<limits.h>", "header") %{ + #include <limits.h> +%} + +struct X { + ... + %extend { + %fragment("<limits.h>"); + bool check(short val) { + if (val < SHRT_MIN /*defined in <limits.h>*/) { + return true; + } else { + return false; + } + } + } +}; +</pre> +</div> + + +<p> +Forced inclusion of fragments can be used as a replacement for <a href="SWIG.html#SWIG_nn42">code insertion block</a>, ensuring the +code block is only generated once. +Consider the contents of FileA.i below which first uses a code insertion block and then a forced fragment inclusion to generate code: +</p> +<div class="code"> +<pre> +// FileA.i +%{ + #include <stdio.h> +%} +%fragment("<limits.h>"); +</pre> +</div> + +<p> +and another file including the above: +</p> + +<div class="code"> +<pre> +// FileB.i +%include "FileA.i" +</pre> +</div> + +<p> +The resulting code in the wrappers for FileB.i is: +</p> + +<div class="code"> +<pre> + #include <stdio.h> + + #include <limits.h> +</pre> +</div> + +<p> +A note of caution must be mentioned when using <tt>%fragment</tt> forced inclusion or code insertion blocks with <tt>%import</tt>. +If <tt>%import</tt> is used instead: +</p> + +<div class="code"> +<pre> +// FileC.i +%import "FileA.i" +</pre> +</div> + +<p> +then nothing is generated in the resulting code in the wrappers for FileC.i. +This is because <tt>%import</tt> is for collecting type information and does not result in any code +being generated, see <a href="Preprocessor.html#Preprocessor_nn3">File Imports</a>. </p> + + </ol> <p> @@ -3999,7 +4113,7 @@ fragment usage unless a desire to really get to grips with some powerful but tricky macro and fragment usage that is used in parts of the SWIG typemap library. </p> -<H3><a name="Typemaps_fragment_type_specialization">11.11.1 Fragment type specialization</a></H3> +<H3><a name="Typemaps_fragment_type_specialization">13.11.1 Fragment type specialization</a></H3> <p> @@ -4032,7 +4146,7 @@ struct A { </pre> </div> -<H3><a name="Typemaps_automatic_specialization">11.11.2 Fragments and automatic typemap specialization</a></H3> +<H3><a name="Typemaps_automatic_specialization">13.11.2 Fragments and automatic typemap specialization</a></H3> <p> @@ -4078,7 +4192,7 @@ The interested (or very brave) reader can take a look at the fragments.swg file </p> -<H2><a name="Typemaps_runtime_type_checker">11.12 The run-time type checker</a></H2> +<H2><a name="Typemaps_runtime_type_checker">13.12 The run-time type checker</a></H2> <p> @@ -4104,7 +4218,7 @@ language modules.</li> <li>Modules can be unloaded from the type system.</li> </ul> -<H3><a name="Typemaps_nn45">11.12.1 Implementation</a></H3> +<H3><a name="Typemaps_nn45">13.12.1 Implementation</a></H3> <p> @@ -4298,7 +4412,7 @@ structures rather than creating new ones. These <tt>swig_module_info</tt> structures are chained together in a circularly linked list. </p> -<H3><a name="Typemaps_runtime_type_checker_usage">11.12.2 Usage</a></H3> +<H3><a name="Typemaps_runtime_type_checker_usage">13.12.2 Usage</a></H3> <p>This section covers how to use these functions from typemaps. To learn how to @@ -4394,7 +4508,7 @@ probably just look at the output of SWIG to get a better sense for how types are managed. </p> -<H2><a name="Typemaps_overloading">11.13 Typemaps and overloading</a></H2> +<H2><a name="Typemaps_overloading">13.13 Typemaps and overloading</a></H2> <p> @@ -4516,37 +4630,69 @@ To support dynamic dispatch, SWIG first defines a general purpose type hierarchy <pre> Symbolic Name Precedence Value ------------------------------ ------------------ -SWIG_TYPECHECK_POINTER 0 -SWIG_TYPECHECK_VOIDPTR 10 -SWIG_TYPECHECK_BOOL 15 -SWIG_TYPECHECK_UINT8 20 -SWIG_TYPECHECK_INT8 25 -SWIG_TYPECHECK_UINT16 30 -SWIG_TYPECHECK_INT16 35 -SWIG_TYPECHECK_UINT32 40 -SWIG_TYPECHECK_INT32 45 -SWIG_TYPECHECK_UINT64 50 -SWIG_TYPECHECK_INT64 55 -SWIG_TYPECHECK_UINT128 60 -SWIG_TYPECHECK_INT128 65 -SWIG_TYPECHECK_INTEGER 70 -SWIG_TYPECHECK_FLOAT 80 -SWIG_TYPECHECK_DOUBLE 90 -SWIG_TYPECHECK_COMPLEX 100 -SWIG_TYPECHECK_UNICHAR 110 -SWIG_TYPECHECK_UNISTRING 120 -SWIG_TYPECHECK_CHAR 130 -SWIG_TYPECHECK_STRING 140 -SWIG_TYPECHECK_BOOL_ARRAY 1015 -SWIG_TYPECHECK_INT8_ARRAY 1025 -SWIG_TYPECHECK_INT16_ARRAY 1035 -SWIG_TYPECHECK_INT32_ARRAY 1045 -SWIG_TYPECHECK_INT64_ARRAY 1055 -SWIG_TYPECHECK_INT128_ARRAY 1065 -SWIG_TYPECHECK_FLOAT_ARRAY 1080 -SWIG_TYPECHECK_DOUBLE_ARRAY 1090 -SWIG_TYPECHECK_CHAR_ARRAY 1130 -SWIG_TYPECHECK_STRING_ARRAY 1140 +SWIG_TYPECHECK_POINTER 0 +SWIG_TYPECHECK_ITERATOR 5 +SWIG_TYPECHECK_VOIDPTR 10 +SWIG_TYPECHECK_BOOL 15 +SWIG_TYPECHECK_UINT8 20 +SWIG_TYPECHECK_INT8 25 +SWIG_TYPECHECK_UINT16 30 +SWIG_TYPECHECK_INT16 35 +SWIG_TYPECHECK_UINT32 40 +SWIG_TYPECHECK_INT32 45 +SWIG_TYPECHECK_SIZE 47 +SWIG_TYPECHECK_PTRDIFF 48 +SWIG_TYPECHECK_UINT64 50 +SWIG_TYPECHECK_INT64 55 +SWIG_TYPECHECK_UINT128 60 +SWIG_TYPECHECK_INT128 65 +SWIG_TYPECHECK_INTEGER 70 +SWIG_TYPECHECK_FLOAT 80 +SWIG_TYPECHECK_DOUBLE 90 +SWIG_TYPECHECK_CPLXFLT 95 +SWIG_TYPECHECK_CPLXDBL 100 +SWIG_TYPECHECK_COMPLEX 105 +SWIG_TYPECHECK_UNICHAR 110 +SWIG_TYPECHECK_STDUNISTRING 115 +SWIG_TYPECHECK_UNISTRING 120 +SWIG_TYPECHECK_CHAR 130 +SWIG_TYPECHECK_STDSTRING 135 +SWIG_TYPECHECK_STRING 140 +SWIG_TYPECHECK_PAIR 150 +SWIG_TYPECHECK_STDARRAY 155 +SWIG_TYPECHECK_VECTOR 160 +SWIG_TYPECHECK_DEQUE 170 +SWIG_TYPECHECK_LIST 180 +SWIG_TYPECHECK_SET 190 +SWIG_TYPECHECK_MULTISET 200 +SWIG_TYPECHECK_MAP 210 +SWIG_TYPECHECK_MULTIMAP 220 +SWIG_TYPECHECK_STACK 230 +SWIG_TYPECHECK_QUEUE 240 +SWIG_TYPECHECK_BOOL_ARRAY 1015 +SWIG_TYPECHECK_INT8_ARRAY 1025 +SWIG_TYPECHECK_INT16_ARRAY 1035 +SWIG_TYPECHECK_INT32_ARRAY 1045 +SWIG_TYPECHECK_INT64_ARRAY 1055 +SWIG_TYPECHECK_INT128_ARRAY 1065 +SWIG_TYPECHECK_FLOAT_ARRAY 1080 +SWIG_TYPECHECK_DOUBLE_ARRAY 1090 +SWIG_TYPECHECK_CHAR_ARRAY 1130 +SWIG_TYPECHECK_STRING_ARRAY 1140 +SWIG_TYPECHECK_OBJECT_ARRAY 1150 +SWIG_TYPECHECK_BOOL_PTR 2015 +SWIG_TYPECHECK_UINT8_PTR 2020 +SWIG_TYPECHECK_INT8_PTR 2025 +SWIG_TYPECHECK_UINT16_PTR 2030 +SWIG_TYPECHECK_INT16_PTR 2035 +SWIG_TYPECHECK_UINT32_PTR 2040 +SWIG_TYPECHECK_INT32_PTR 2045 +SWIG_TYPECHECK_UINT64_PTR 2050 +SWIG_TYPECHECK_INT64_PTR 2055 +SWIG_TYPECHECK_FLOAT_PTR 2080 +SWIG_TYPECHECK_DOUBLE_PTR 2090 +SWIG_TYPECHECK_CHAR_PTR 2130 +SWIG_TYPECHECK_SWIGOBJECT 5000 </pre> </div> @@ -4671,7 +4817,8 @@ then the type is given a precedence higher than any other known precedence level <div class="shell"> <pre> -example.i:18: Warning 467: Overloaded method foo(int) not supported (incomplete type checking rule - no precedence level in typecheck typemap for 'int'). +example.i:18: Warning 467: Overloaded method foo(int) not supported (incomplete type +checking rule - no precedence level in typecheck typemap for 'int'). </pre> </div> @@ -4696,17 +4843,119 @@ simply check the type of the first array element and use that to dispatch to the Subsequent "in" typemaps would then perform more extensive type-checking. </li> -<li>Make sure you read the section on overloading in the "<a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a>" chapter. +<li>Make sure you read the section on <a href="SWIGPlus.html#SWIGPlus_overloaded_methods">overloading</a> in the SWIG and C++ chapter. </li> </ul> -<H2><a name="Typemaps_nn48">11.14 More about %apply and %clear</a></H2> +<H3><a name="Typemaps_typecheck_pointer">13.13.1 SWIG_TYPECHECK_POINTER precedence level and the typecheck typemap</a></H3> + + +<p> +When it comes to overloading of a particular type passed by value, pointer or reference (const and non-const), +a C++ compiler can disambiguate which overloaded function to call. +However, SWIG effectively treats these as pointers in the target language and thus as equivalent types. +For example, consider: +</p> + +<div class="code"> +<pre> +class X { ... }; +void m(X const &c); // equivalent: void m(X *c); +void m(X &r); // equivalent: void m(X *r); +void m(X *p); // equivalent: void m(X *p); +</pre> +</div> + +<p> +These cannot be disambiguated in the target languages and so SWIG will choose the first method and ignore the subsequent two methods. +The scripting languages do this by using the overload dispatch mechanism described earlier and warnings indicate this: +</p> + +<div class="shell"> +<pre> +example.i:6: Warning 509: Overloaded method m(X &) effectively ignored, +example.i:5: Warning 509: as it is shadowed by m(X const &). +example.i:7: Warning 509: Overloaded method m(X *) effectively ignored, +example.i:5: Warning 509: as it is shadowed by m(X const &). +</pre> +</div> + +<p> +The statically typed languages like Java and C# automatically ignore all but the first equivalent overloaded methods with warnings: +</p> + +<div class="shell"> +<pre> +example.i:6: Warning 516: Overloaded method m(X &) ignored, +example.i:5: Warning 516: using m(X const &) instead. +example.i:7: Warning 516: Overloaded method m(X *) ignored, +example.i:5: Warning 516: using m(X const &) instead. +</pre> +</div> + +<p> +You can select the overloaded method you would like to wrap by ignoring the other two with <tt>%ignore</tt> or rename two of them with <tt>%rename</tt> +and this will of course remove the warnings too. +The problem of ambiguity is also discussed in the C++ chapter on <a href="SWIGPlus.html#SWIGPlus_overloaded_methods">overloading</a>. +</p> + +<p> +So how does this work with respect to typemaps? +The typemaps SWIG provides to handle overloading for these three methods are from the SWIGTYPE family. +As discussed earlier, in <a href="Typemaps.html#Typemaps_nn19">Default typemap matching rules</a>, +the <tt>SWIGTYPE &</tt> typemaps are used for references and <tt>SWIGTYPE *</tt> typemaps are used for pointers. +SWIG uses the special <tt>SWIG_TYPECHECK_POINTER</tt> (0) precedence level to handle these types in the "typecheck" typemap: +</p> + +<div class="code"> +<pre> +%typemap(typecheck, precedence=SWIG_TYPECHECK_POINTER) SWIGTYPE & "..." +%typemap(typecheck, precedence=SWIG_TYPECHECK_POINTER) SWIGTYPE * "..." +</pre> +</div> + +<p> +When the SWIGTYPE "typecheck" typemaps use the <tt>SWIG_TYPECHECK_POINTER</tt> precedence level, +SWIG converts the type to a pointer equivalent type and then uses the equivalent type to detect if it can be disambiguated in an overloaded method in the target language. +In our example above, the equivalent types for <tt>X const &</tt>, <tt>X &</tt> and <tt>X *</tt> are all <tt>X *</tt>. +As they are the same, they cannot be disambiguated and so just the first overloaded method is chosen. +</p> + +<p> +The automatic conversion to equivalent types and subsequent type comparison is triggered via the use of the special <tt>SWIG_TYPECHECK_POINTER</tt> precedence level +and works for types passed by value, pointer and reference. +Alas, there are more ways to overload a method that also need handling. +C++ smart pointers are such a type which can be disambiguated by a C++ compiler but not automatically by SWIG. +SWIG does not automatically know that a smart pointer has an equivalent type, but it can be told manually. +Just specify the 'equivalent' attribute in the "typecheck" typemap with a pointer to the underlying type. +</p> + +<div class="code"> +<pre> +%typemap(typecheck, precedence=SWIG_TYPECHECK_POINTER, equivalent="X *") MySmartPtr<X> " ... " + +void m(X &r); // equivalent: void m(X *r); +void m(MySmartPtr<X> s); // equivalent: void m(X *s); +</pre> +</div> + +<p> +Now SWIG will detect the two types are equivalent and generate valid code by wrapping just the first overloaded method. +You can of course choose which method to wrap by ignoring one of them with <tt>%ignore</tt>. +Otherwise both can be wrapped by removing the overloading name ambiguity by renaming one of them with <tt>%rename</tt>. +</p> + +<p> +The 'equivalent' attribute is used in the implementation for the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a> library. +</p> + +<H2><a name="Typemaps_nn48">13.14 More about %apply and %clear</a></H2> <p> In order to implement certain kinds of program behavior, it is sometimes necessary to -write sets of typemaps. For example, to support output arguments, one often writes -a set of typemaps like this: +write a family of typemap methods. For example, to support output arguments, one often writes +a family of typemaps like this: </p> <div class="code"> @@ -4722,7 +4971,7 @@ a set of typemaps like this: <p> To make it easier to apply the typemap to different argument types and names, the <tt>%apply</tt> directive -performs a copy of all typemaps from one type to another. For example, if you specify this, +performs a copy of all typemaps from a source type to one or more set of target types. For example, if you specify this, </p> <div class="code"> @@ -4732,12 +4981,14 @@ performs a copy of all typemaps from one type to another. For example, if you s </div> <p> -then all of the <tt>int *OUTPUT</tt> typemaps are copied to <tt>int *retvalue</tt> and <tt>int32 *output</tt>. +then all of the <tt>int *OUTPUT</tt> (source) typemap methods are copied to <tt>int *retvalue</tt> and <tt>int32 *output</tt> (the targets). </p> <p> -However, there is a subtle aspect of <tt>%apply</tt> that needs more description. Namely, <tt>%apply</tt> does not -overwrite a typemap rule if it is already defined for the target datatype. This behavior allows you to do two things: +However, there is a subtle aspect of <tt>%apply</tt> that needs clarification. +Namely, if a target contains a typemap method that the source does not, +the target typemap method remains in place and unchanged. +This behavior allows you to do two things: </p> <ul> @@ -4745,7 +4996,7 @@ overwrite a typemap rule if it is already defined for the target datatype. Thi <tt>%apply</tt> to incorporate the remaining pieces. </li> -<li>Sets of different typemaps can be applied to the same datatype using repeated <tt>%apply</tt> directives. +<li>Different typemaps can be applied to the same datatype using repeated <tt>%apply</tt> directives. </li> </ul> @@ -4767,6 +5018,10 @@ For example: } } +%typemap(arginit) int *invalue %{ + $1 = NULL; +%} + ... %apply int *INPUT { int *invalue }; %apply int *POSITIVE { int *invalue }; @@ -4774,9 +5029,11 @@ For example: </div> <p> -Since <tt>%apply</tt> does not overwrite or replace any existing rules, the only way to reset behavior is to -use the <tt>%clear</tt> directive. <tt>%clear</tt> removes all typemap rules defined for a specific datatype. For -example: +In this example, neither of the two <tt>%apply</tt> directives will overwrite / delete the "arginit" typemap as neither has an "arginit" typemap. +The result is a family of three relevant typemaps for <tt>int *invalue</tt>. +Since <tt>%apply</tt> does not overwrite / delete any existing rules, the only way to reset behavior is to +delete them, such as with the <tt>%clear</tt> directive. +For example: </p> <div class="code"> @@ -4785,8 +5042,19 @@ example: </pre> </div> +<p> +will delete the typemaps for all the typemap methods; namely "in", "check" and "arginit". Alternatively delete each one individually: +</p> + +<div class="code"> +<pre> +%typemap(in) int *invalue; +%typemap(check) int *invalue; +%typemap(arginit) int *invalue; +</pre> +</div> -<H2><a name="Typemaps_nn47">11.15 Passing data between typemaps</a></H2> +<H2><a name="Typemaps_nn47">13.15 Passing data between typemaps</a></H2> <p> @@ -4823,7 +5091,7 @@ sure that the typemaps sharing information have exactly the same types and names </p> -<H2><a name="Typemaps_nn52">11.16 C++ "this" pointer</a></H2> +<H2><a name="Typemaps_nn52">13.16 C++ "this" pointer</a></H2> <p> @@ -4883,7 +5151,7 @@ will also match the typemap. One work around is to create an interface file tha the method, but gives the argument a name other than <tt>self</tt>. </p> -<H2><a name="Typemaps_nn51">11.17 Where to go for more information?</a></H2> +<H2><a name="Typemaps_nn51">13.17 Where to go for more information?</a></H2> <p> diff --git a/Doc/Manual/Varargs.html b/Doc/Manual/Varargs.html index fb58ee39a..9f20469d2 100644 --- a/Doc/Manual/Varargs.html +++ b/Doc/Manual/Varargs.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Varargs">14 Variable Length Arguments</a></H1> +<H1><a name="Varargs">16 Variable Length Arguments</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -43,7 +43,7 @@ added in SWIG-1.3.12. Most other wrapper generation tools have wisely chosen to avoid this issue. </p> -<H2><a name="Varargs_nn2">14.1 Introduction</a></H2> +<H2><a name="Varargs_nn2">16.1 Introduction</a></H2> <p> @@ -140,7 +140,7 @@ List make_list(const char *s, ...) { </pre> </div> -<H2><a name="Varargs_nn3">14.2 The Problem</a></H2> +<H2><a name="Varargs_nn3">16.2 The Problem</a></H2> <p> @@ -233,7 +233,7 @@ can also support real varargs wrapping (with stack-frame manipulation) if you are willing to get hands dirty. Keep reading. </p> -<H2><a name="Varargs_nn4">14.3 Default varargs support</a></H2> +<H2><a name="Varargs_nn4">16.3 Default varargs support</a></H2> <p> @@ -302,7 +302,7 @@ Read on for further solutions. </p> -<H2><a name="Varargs_nn5">14.4 Argument replacement using %varargs</a></H2> +<H2><a name="Varargs_nn5">16.4 Argument replacement using %varargs</a></H2> <p> @@ -413,7 +413,7 @@ mixed argument types such as <tt>printf()</tt>. Providing general purpose wrappers to such functions presents special problems (covered shortly). </p> -<H2><a name="Varargs_nn6">14.5 Varargs and typemaps</a></H2> +<H2><a name="Varargs_nn6">16.5 Varargs and typemaps</a></H2> <p> @@ -423,8 +423,8 @@ Variable length arguments may be used in typemap specifications. For example: <div class="code"> <pre> %typemap(in) (...) { - // Get variable length arguments (somehow) - ... + // Get variable length arguments (somehow) + ... } %typemap(in) (const char *fmt, ...) { @@ -529,8 +529,11 @@ like this: SWIG_fail; } pystr = PyUnicode_AsUTF8String(pyobj); + if (!pystr) { + SWIG_fail; + } str = strdup(PyBytes_AsString(pystr)); - Py_XDECREF(pystr); + Py_DECREF(pystr); %#else if (!PyString_Check(pyobj)) { PyErr_SetString(PyExc_ValueError, "Expected a string"); @@ -590,7 +593,7 @@ really want to elevate your guru status and increase your job security, continue to the next section. </p> -<H2><a name="Varargs_nn7">14.6 Varargs wrapping with libffi</a></H2> +<H2><a name="Varargs_nn7">16.6 Varargs wrapping with libffi</a></H2> <p> @@ -842,7 +845,7 @@ provide an argument number for the first extra argument. This can be used to in values. Please consult the chapter on each language module for more details. </p> -<H2><a name="Varargs_nn8">14.7 Wrapping of va_list</a></H2> +<H2><a name="Varargs_nn8">16.7 Wrapping of va_list</a></H2> <p> @@ -896,7 +899,7 @@ int my_vprintf(const char *fmt, ...) { </pre> </div> -<H2><a name="Varargs_nn9">14.8 C++ Issues</a></H2> +<H2><a name="Varargs_nn9">16.8 C++ Issues</a></H2> <p> @@ -965,7 +968,7 @@ design or to provide an alternative interface using a helper function than it is fully general wrapper to a varargs C++ member function. </p> -<H2><a name="Varargs_nn10">14.9 Discussion</a></H2> +<H2><a name="Varargs_nn10">16.9 Discussion</a></H2> <p> diff --git a/Doc/Manual/Warnings.html b/Doc/Manual/Warnings.html index e7b291f21..c63d7de0c 100644 --- a/Doc/Manual/Warnings.html +++ b/Doc/Manual/Warnings.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Warnings">15 Warning Messages</a></H1> +<H1><a name="Warnings">18 Warning Messages</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -25,7 +25,8 @@ <li><a href="#Warnings_nn11">Preprocessor (200-299)</a> <li><a href="#Warnings_nn12">C/C++ Parser (300-399)</a> <li><a href="#Warnings_nn13">Types and typemaps (400-499) </a> -<li><a href="#Warnings_nn14">Code generation (500-599)</a> +<li><a href="#Warnings_nn14">Code generation (500-559)</a> +<li><a href="#Warnings_doxygen">Doxygen comments (560-599)</a> <li><a href="#Warnings_nn15">Language module specific (700-899) </a> <li><a href="#Warnings_nn16">User defined (900-999)</a> </ul> @@ -36,7 +37,7 @@ -<H2><a name="Warnings_nn2">15.1 Introduction</a></H2> +<H2><a name="Warnings_nn2">18.1 Introduction</a></H2> <p> @@ -56,7 +57,7 @@ where the generated wrapper code will probably compile, but it may not work like you expect. </p> -<H2><a name="Warnings_suppression">15.2 Warning message suppression</a></H2> +<H2><a name="Warnings_suppression">18.2 Warning message suppression</a></H2> <p> @@ -148,7 +149,7 @@ your interface. Ignore the warning messages at your own peril. </p> -<H2><a name="Warnings_nn4">15.3 Enabling extra warnings</a></H2> +<H2><a name="Warnings_nn4">18.3 Enabling extra warnings</a></H2> <p> @@ -221,7 +222,7 @@ that is, any warnings suppressed or added in <tt>%warnfilter</tt>, <tt>#pragma S or the <tt>-w</tt> option. </p> -<H2><a name="Warnings_nn5">15.4 Issuing a warning message</a></H2> +<H2><a name="Warnings_nn5">18.4 Issuing a warning message</a></H2> <p> @@ -275,7 +276,7 @@ example.i:24: Warning 901: You are really going to regret this usage of blah * s </pre> </div> -<H2><a name="Warnings_symbolic_symbols">15.5 Symbolic symbols</a></H2> +<H2><a name="Warnings_symbolic_symbols">18.5 Symbolic symbols</a></H2> <p> @@ -310,7 +311,7 @@ or </pre> </div> -<H2><a name="Warnings_nn6">15.6 Commentary</a></H2> +<H2><a name="Warnings_nn6">18.6 Commentary</a></H2> <p> @@ -327,7 +328,7 @@ no obvious recovery. There is no mechanism for suppressing error messages. </p> -<H2><a name="Warnings_nn7">15.7 Warnings as errors</a></H2> +<H2><a name="Warnings_nn7">18.7 Warnings as errors</a></H2> <p> @@ -336,7 +337,7 @@ option. This will cause SWIG to exit with a non successful exit code if a warning is encountered. </p> -<H2><a name="Warnings_nn8">15.8 Message output format</a></H2> +<H2><a name="Warnings_nn8">18.8 Message output format</a></H2> <p> @@ -355,10 +356,10 @@ $ swig -python -Fmicrosoft example.i example.i(4) : Syntax error in input(1). </pre></div> -<H2><a name="Warnings_nn9">15.9 Warning number reference</a></H2> +<H2><a name="Warnings_nn9">18.9 Warning number reference</a></H2> -<H3><a name="Warnings_nn10">15.9.1 Deprecated features (100-199)</a></H3> +<H3><a name="Warnings_nn10">18.9.1 Deprecated features (100-199)</a></H3> <ul> @@ -386,7 +387,7 @@ example.i(4) : Syntax error in input(1). <li>126. The 'nestedworkaround' feature is deprecated. </ul> -<H3><a name="Warnings_nn11">15.9.2 Preprocessor (200-299)</a></H3> +<H3><a name="Warnings_nn11">18.9.2 Preprocessor (200-299)</a></H3> <ul> @@ -398,7 +399,7 @@ example.i(4) : Syntax error in input(1). <li>206. Unexpected tokens after #<em>directive</em> directive. </ul> -<H3><a name="Warnings_nn12">15.9.3 C/C++ Parser (300-399)</a></H3> +<H3><a name="Warnings_nn12">18.9.3 C/C++ Parser (300-399)</a></H3> <ul> @@ -475,7 +476,7 @@ example.i(4) : Syntax error in input(1). <li>395. operator delete[] ignored. </ul> -<H3><a name="Warnings_nn13">15.9.4 Types and typemaps (400-499) </a></H3> +<H3><a name="Warnings_nn13">18.9.4 Types and typemaps (400-499) </a></H3> <ul> @@ -506,7 +507,7 @@ example.i(4) : Syntax error in input(1). -<H3><a name="Warnings_nn14">15.9.5 Code generation (500-599)</a></H3> +<H3><a name="Warnings_nn14">18.9.5 Code generation (500-559)</a></H3> <ul> @@ -533,9 +534,22 @@ example.i(4) : Syntax error in input(1). <li>521. Illegal destructor name <em>name</em>. Ignored. <li>522. Use of an illegal constructor name '<em>name</em>' in %extend is deprecated, the constructor name should be '<em>name</em>'. <li>523. Use of an illegal destructor name '<em>name</em>' in %extend is deprecated, the destructor name should be '<em>name</em>'. +<li>524. Experimental target language. Target language <em>language</em> specified by <em>lang</em> is an experimental language. Please read about SWIG experimental languages, <em>htmllink</em>. +<li>525. Destructor <em>declaration</em> is final, <em>name</em> cannot be a director class. </ul> -<H3><a name="Warnings_nn15">15.9.6 Language module specific (700-899) </a></H3> +<H3><a name="Warnings_doxygen">18.9.6 Doxygen comments (560-599)</a></H3> + + +<ul> + <li>560: Unknown Doxygen command: <em>command</em>.</li> + <li>561: Unexpected end of Doxygen comment encountered.</li> + <li>562: Expected Doxygen command: <em>command</em></li> + <li>563: Doxygen HTML error for tag <em>tag</em>: <em>error text</em>.</li> + <li>564: Error parsing Doxygen command <em>command</em>: <em>error text</em>. Command ignored."</li> +</ul> + +<H3><a name="Warnings_nn15">18.9.7 Language module specific (700-899) </a></H3> <ul> @@ -586,14 +600,14 @@ example.i(4) : Syntax error in input(1). <li>871. Unrecognized pragma <em>pragma</em>. (Php). </ul> -<H3><a name="Warnings_nn16">15.9.7 User defined (900-999)</a></H3> +<H3><a name="Warnings_nn16">18.9.8 User defined (900-999)</a></H3> <p> These numbers can be used by your own application. </p> -<H2><a name="Warnings_nn17">15.10 History</a></H2> +<H2><a name="Warnings_nn17">18.10 History</a></H2> <p> diff --git a/Doc/Manual/Windows.html b/Doc/Manual/Windows.html index b95105bdd..800e2e420 100644 --- a/Doc/Manual/Windows.html +++ b/Doc/Manual/Windows.html @@ -68,7 +68,7 @@ SWIG does not come with the usual Windows type installation program, however it <p> -The swigwin distribution contains the SWIG Windows executable, swig.exe, which will run on 32 bit versions of Windows, ie Windows 95 and later. +The swigwin distribution contains the SWIG Windows 32-bit executable, swig.exe, which will run on both 32-bit and 64-bit versions of Windows. If you want to build your own swig.exe have a look at <a href="#Windows_swig_exe">Building swig.exe on Windows</a>. </p> @@ -149,7 +149,7 @@ PERL5_LIB: D:\nsPerl5.004_04\lib\CORE\perl.lib<br> <p> <b><tt>PYTHON_INCLUDE</tt></b> : Set this to the directory that contains Python.h<br> -<b><tt>PYTHON_LIB</tt></b> : Set this to the python library including path for linking<p> +<b><tt>PYTHON_LIB</tt></b> : Set this to the Python library including path for linking<p> Example using Python 2.1.1:<br> <tt> PYTHON_INCLUDE: D:\python21\include<br> @@ -211,7 +211,7 @@ If you do not have access to Visual C++ you will have to set up project files / <p> -SWIG can also be compiled and run using <a href="http://www.cygwin.com">Cygwin</a> or <a href="http://www.mingw.org">MinGW</a> which provides a Unix like front end to Windows and comes free with gcc, an ANSI C/C++ compiler. However, this is not a recommended approach as the prebuilt executable is supplied. +SWIG can also be compiled and run using <a href="http://www.cygwin.com">Cygwin</a> or <a href="http://www.mingw.org">MinGW</a> which provides a Unix like front end to Windows and comes free with gcc, an ISO C/C++ compiler. However, this is not a recommended approach as the prebuilt executable is supplied. </p> <H3><a name="Windows_swig_exe">3.3.1 Building swig.exe on Windows</a></H3> @@ -249,7 +249,7 @@ Execute the steps in the order shown and don't use spaces in path names. In fact <ol> <li> Download the following packages from the <a href="http://www.mingw.org/download.shtml">MinGW download page</a> - or <a href="http://sourceforge.net/projects/mingw/files/">MinGW SourceForge download page</a>. + or <a href="https://sourceforge.net/projects/mingw/files/">MinGW SourceForge download page</a>. Note that at the time of writing, the majority of these are in the Current release list and some are in the Snapshot or Previous release list. <ul> diff --git a/Doc/Manual/chapters b/Doc/Manual/chapters index d94a8a396..2cb2b18a3 100644 --- a/Doc/Manual/chapters +++ b/Doc/Manual/chapters @@ -5,6 +5,8 @@ Scripting.html SWIG.html SWIGPlus.html CPlusPlus11.html +CPlusPlus14.html +CPlusPlus17.html Preprocessor.html Library.html Arguments.html @@ -12,30 +14,26 @@ Typemaps.html Customization.html Contract.html Varargs.html +Doxygen.html Warnings.html Modules.html CCache.html -Allegrocl.html Android.html CSharp.html -Chicken.html D.html Go.html Guile.html Java.html Javascript.html -Lisp.html Lua.html -Modula3.html -Mzscheme.html -Ocaml.html Octave.html Perl5.html Php.html -Pike.html Python.html R.html Ruby.html Scilab.html Tcl.html +Mzscheme.html +Ocaml.html Extending.html diff --git a/Doc/Manual/index.html b/Doc/Manual/index.html index 26cc81ea1..e720e70d0 100644 --- a/Doc/Manual/index.html +++ b/Doc/Manual/index.html @@ -1,11 +1,11 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> -<title>SWIG-3.0 Documentation</title> +<title>SWIG-4.0 Documentation</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head> <body bgcolor="#ffffff"> -<H1><a name="index">SWIG-3.0 Documentation</a></H1> +<H1><a name="index">SWIG-4.0 Documentation</a></H1> The SWIG documentation is available in one of the following formats. <ul> diff --git a/Doc/Manual/makechap.py b/Doc/Manual/makechap.py index 61994e2a0..e30d14e0f 100644 --- a/Doc/Manual/makechap.py +++ b/Doc/Manual/makechap.py @@ -44,6 +44,8 @@ def getheadingname(m): def getheadingtext(m, s): prevheadingtext_newstyle = m.group(2) prevheadingtext_oldstyle = m.group(3) + if prevheadingtext_oldstyle is None or prevheadingtext_newstyle is None: + raise RuntimeError("Ill-formed heading in line:\n%s" % s) if len(prevheadingtext_oldstyle) == 0 and len(prevheadingtext_newstyle) == 0: raise RuntimeError("No heading text in line:\n%s" % s) if len(prevheadingtext_oldstyle) > 0 and len(prevheadingtext_newstyle) > 0: @@ -72,7 +74,7 @@ name = "" # Regexs for <h1>,... <h5> sections -h1 = re.compile(r".*?<H1>(<a.*?>\s*[\d\s]*(.*?)</a>)*[\d\s]*(.*?)</H1>", re.IGNORECASE) +h1 = re.compile(r".*?<H1>(<a.*?>\s*[\d\.\s]*(.*?)</a>)*[\d\.\s]*(.*?)</H1>", re.IGNORECASE) h2 = re.compile(r".*?<H2>(<a.*?>\s*[\d\.\s]*(.*?)</a>)*[\d\.\s]*(.*?)</H2>", re.IGNORECASE) h3 = re.compile(r".*?<H3>(<a.*?>\s*[\d\.\s]*(.*?)</a>)*[\d\.\s]*(.*?)</H3>", re.IGNORECASE) h4 = re.compile(r".*?<H4>(<a.*?>\s*[\d\.\s]*(.*?)</a>)*[\d\.\s]*(.*?)</H4>", re.IGNORECASE) |