jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

merge revisions 11877-12162 from trunk to gsoc2009-matevz

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2009-matevz@12164 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
William S Fulton 2010-07-20 23:35:40 +00:00
commit 25ff4e4927
563 changed files with 22912 additions and 17189 deletions
Download patch file Download diff file Expand all files Collapse all files

19
ANNOUNCE
View file

@ -1,14 +1,11 @@
*** ANNOUNCE: SWIG 2.0.0 (in progress) ***
*** ANNOUNCE: SWIG 2.0.1 (in progress) ***
http://www.swig.org
We're pleased to announce SWIG-2.0.0, the latest installment in the
SWIG development effort. SWIG-2.0.0 includes a number of bug fixes
and enhancements.
We're pleased to announce SWIG-2.0.1, the latest SWIG release.
What is SWIG?
-------------
=============
SWIG is a software development tool that reads C/C++ header files and
generates the wrapper code needed to make C and C++ code accessible
@ -20,17 +17,17 @@ SWIG include generation of scripting language extension modules, rapid
prototyping, testing, and user interface development for large C/C++
systems.
Availability:
-------------
Availability
============
The release is available for download on Sourceforge at
http://prdownloads.sourceforge.net/swig/swig-2.0.0.tar.gz
http://prdownloads.sourceforge.net/swig/swig-2.0.1.tar.gz
A Windows version is also available at
http://prdownloads.sourceforge.net/swig/swigwin-2.0.0.zip
http://prdownloads.sourceforge.net/swig/swigwin-2.0.1.zip
Please report problems with this release to the swig-dev mailing list,
Please report problems with this release to the swig-devel mailing list,
details at http://www.swig.org/mail.html.
--- The SWIG Developers

14
CCache/Makefile.in
View file

@ -40,8 +40,11 @@ web/ccache-man.html: ccache.yo
yodl2html -o web/ccache-man.html ccache.yo
install: $(PACKAGE_NAME)$(EXEEXT) $(PACKAGE_NAME).1
@echo "Installing $(PACKAGE_NAME)"
@echo "Installing $(DESTDIR)${bindir}/`echo $(PACKAGE_NAME) | sed '$(transform)'`$(EXEEXT)"
${INSTALLCMD} -d $(DESTDIR)${bindir}
${INSTALLCMD} -m 755 $(PACKAGE_NAME)$(EXEEXT) $(DESTDIR)${bindir}/`echo $(PACKAGE_NAME) | sed '$(transform)'`$(EXEEXT)
@echo "Installing $(DESTDIR)${mandir}/man1/`echo $(PACKAGE_NAME) | sed '$(transform)'`.1"
${INSTALLCMD} -d $(DESTDIR)${mandir}/man1
${INSTALLCMD} -m 644 ${srcdir}/$(PACKAGE_NAME).1 $(DESTDIR)${mandir}/man1/`echo $(PACKAGE_NAME) | sed '$(transform)'`.1
@ -52,9 +55,6 @@ uninstall: $(PACKAGE_NAME)$(EXEEXT) $(PACKAGE_NAME).1
clean:
/bin/rm -f $(OBJS) *~ $(PACKAGE_NAME)$(EXEEXT)
distclean-docs:
rm -f $(PACKAGE_NAME).1 web/ccache-man.html
check : test
test: test.sh
@ -62,11 +62,13 @@ test: test.sh
check: test
distclean: clean distclean-docs
/bin/rm -f Makefile config.h config.sub config.log build-stamp config.status config.h.in ccache_swig_config.h
distclean: clean
/bin/rm -f Makefile config.h config.sub config.log build-stamp config.status ccache_swig_config.h
/bin/rm -rf autom4te.cache
maintainer-clean: distclean
/bin/rm -f configure
/bin/rm -f $(PACKAGE_NAME).1 web/ccache-man.html
# FIXME: To fix this, test.sh needs to be able to take ccache from the
# installed prefix, not from the source dir.

668
CHANGES
View file

@ -1,6 +1,668 @@
SWIG (Simplified Wrapper and Interface Generator)
See CHANGES.current for current version.
See the CHANGES.current file for changes in the current version.
See the RELEASENOTES file for a summary of changes in each release.
Version 2.0.0 (2 June 2010)
===========================
2010-06-02: wsfulton
[C#] Fix SWIG_STD_VECTOR_ENHANCED macro used in std::vector to work with
types containing commas, for example:
SWIG_STD_VECTOR_ENHANCED(std::pair< double, std::string >)
2010-06-01: wsfulton
Add in std_shared_ptr.i for wrapping std::shared_ptr. Requires the %shared_ptr
macro like in the boost_shared_ptr.i library. std::tr1::shared_ptr can also be
wrapped if the following macro is defined:
#define SWIG_SHARED_PTR_SUBNAMESPACE tr1
%include <std_shared_ptr.i>
shared_ptr is also documented in Library.html now.
2010-05-27: wsfulton
Add the ability for $typemap special variable macros to call other $typemap
special variable macros, for example:
%typemap(cstype) CC "CC"
%typemap(cstype) BB "$typemap(cstype, CC)"
%typemap(cstype) AA "$typemap(cstype, BB)"
void hah(AA aa);
This also fixes C# std::vector containers of shared_ptr and %shared_ptr.
Also added diagnostics for $typemap with -debug-tmsearch, for example, the
above displays additional diagnostic lines starting "Containing: ":
example.i:34: Searching for a suitable 'cstype' typemap for: AA aa
Looking for: AA aa
Looking for: AA
Using: %typemap(cstype) AA
Containing: $typemap(cstype, BB)
example.i:31: Searching for a suitable 'cstype' typemap for: BB
Looking for: BB
Using: %typemap(cstype) BB
Containing: $typemap(cstype, CC)
example.i:29: Searching for a suitable 'cstype' typemap for: CC
Looking for: CC
Using: %typemap(cstype) CC
2010-05-26: olly
Fix %attribute2ref not to produce a syntax error if the last
argument (AccessorMethod) is omitted. Patch from David Piepgras
in SF#2235756.
2010-05-26: olly
[PHP] When using %throws or %catches, SWIG-generated PHP5 wrappers
now throw PHP Exception objects instead of giving a PHP error of
type E_ERROR.
This change shouldn't cause incompatibility issues, since you can't
set an error handler for E_ERROR, so previously PHP would just exit
which also happens for unhandled exceptions. The benefit is you can
now catch them if you want to.
Fixes SF#2545578 and SF#2955522.
2010-05-25: olly
[PHP] Add missing directorin typemap for const std::string &.
Fixes SF#3006404 reported by t-Legiaw.
2010-05-23: wsfulton
[C#] Fix #2957375 - SWIGStringHelper and SWIGExceptionHelper not always being
initialized before use in .NET 4 as the classes were not marked beforefieldinit.
A static constructor has been added to the intermediary class like this:
%pragma(csharp) imclasscode=%{
static $imclassname() {
}
%}
If you had added your own custom static constructor to the intermediary class in
the same way as above, you will have to modify your approach to use static variable
initialization or define SWIG_CSHARP_NO_IMCLASS_STATIC_CONSTRUCTOR - See csharphead.swg.
*** POTENTIAL INCOMPATIBILITY ***
2010-05-23: wsfulton
Fix #2408232. Improve shared_ptr and intrusive_ptr wrappers for classes in an
inheritance hierarchy. No special treatment is needed for derived classes.
The proxy class also no longer needs to be specified, it is automatically
deduced. The following macros are deprecated:
SWIG_SHARED_PTR(PROXYCLASS, TYPE)
SWIG_SHARED_PTR_DERIVED(PROXYCLASS, BASECLASSTYPE, TYPE)
and have been replaced by
%shared_ptr(TYPE)
Similarly for intrusive_ptr wrappers, the following macro is deprecated:
SWIG_INTRUSIVE_PTR(PROXYCLASS, TYPE)
SWIG_INTRUSIVE_PTR_DERIVED(PROXYCLASS, BASECLASSTYPE, TYPE)
and have been replaced by
%intrusive_ptr(TYPE)
2010-05-21: olly
[PHP] Stop generating a bogus line of code in certain constructors.
This was mostly harmless, but caused a PHP notice to be issued, if
enabled (SF#2985684).
2010-05-18: wsfulton
[Java] Fix member pointers on 64 bit platforms.
2010-05-14: wsfulton
Fix wrapping of C++ enum boolean values reported by Torsten Landschoff:
typedef enum { PLAY = true, STOP = false } play_state;
2010-05-14: olly
[PHP] Fix wrapping of global variables which was producing
uncompilable code in some cases.
2010-05-12: drjoe
[R] Add two more changes from Wil Nolan. Get garbage
collection to work. Implement newfree
2010-05-09: drjoe
Fix bug reported by Wil Nolan change creation of string so
that R 2.7.0+ can use char hashes
2010-05-07: wsfulton
Apply patch #2955146 from Sergey Satskiy to fix expressions containing divide by
operator in constructor initialization lists.
2010-05-05: wsfulton
[R] Memory leak fix handling const std::string & inputs, reported by Will Nolan.
2010-05-01: wsfulton
Typemap matching enhancement for non-default typemaps. Previously all
qualifiers were stripped in one step, now they are stripped one at a time
starting with the left most qualifier. For example, int const*const
is first stripped to int *const then int *.
*** POTENTIAL INCOMPATIBILITY ***
2010-04-25: bhy
[Python] Fix #2985655 - broken constructor renaming.
2010-04-14: wsfulton
Typemap fragments are now official and documented in Typemaps.html.
2010-04-09: wsfulton
[Ruby] Fix #2048064 and #2408020.
Apply Ubuntu patch to fix Ruby and std::vector wrappers with -minherit.
https://bugs.launchpad.net/ubuntu/+source/swig1.3/+bug/522874
2010-04-09: wsfulton
[Mzscheme] Apply Ubuntu patch to fix std::map wrappers:
https://bugs.launchpad.net/ubuntu/+source/swig1.3/+bug/203876
2010-04-09: wsfulton
[Python] Apply patch #2952374 - fix directors and the -nortti option.
2010-04-09: wsfulton
[Lua] Fix #2887254 and #2946032 - SWIG_Lua_typename using wrong stack index.
2010-04-03: wsfulton
[Python] Fix exceptions being thrown with the -threads option based on patch from Arto Vuori.
Fixes bug #2818499.
2010-04-03: wsfulton
Fix Makefile targets: distclean and maintainer-clean
2010-04-02: wsfulton
[Lua] Fix char pointers, wchar_t pointers and char arrays so that nil can be passed as a
valid value. Bug reported by Gedalia Pasternak.
2010-04-01: wsfulton
Numerous subtle typemap matching rule fixes when using the default type. The typemap
matching rules are to take a type and find the best default typemap (SWIGTYPE, SWIGTYPE* etc),
then look for the next best match by reducing the chosen default type. The type deduction
now follows C++ class template partial specialization matching rules.
Below are the set of changes made showing the default type deduction
along with the old reduced type and the new version of the reduced type:
SWIGTYPE const &[ANY]
new: SWIGTYPE const &[]
old: SWIGTYPE (&)[ANY]
SWIGTYPE *const [ANY]
new: SWIGTYPE const [ANY]
old: SWIGTYPE *[ANY]
SWIGTYPE const *const [ANY]
new: SWIGTYPE *const [ANY]
old: SWIGTYPE const *[ANY]
SWIGTYPE const *const &
new: SWIGTYPE *const &
old: SWIGTYPE const *&
SWIGTYPE *const *
new: SWIGTYPE const *
old: SWIGTYPE **
SWIGTYPE *const &
new: SWIGTYPE const &
old: SWIGTYPE *&
Additionally, a const SWIGTYPE lookup is used now for any constant type. Some examples, where
T is some reduced type, eg int, struct Foo:
T const
new: SWIGTYPE const
old: SWIGTYPE
T *const
new: SWIGTYPE *const
old: SWIGTYPE *
T const[]
new: SWIGTYPE const[]
old: SWIGTYPE[]
enum T const
new: enum SWIGTYPE const
old: enum SWIGTYPE
T (*const )[]
new: SWIGTYPE (*const )[]
old: SWIGTYPE (*)[]
Reminder: the typemap matching rules can now be seen for any types being wrapped by using
either the -debug-tmsearch or -debug-tmused options.
In practice this leads to some subtle matching rule changes and the majority of users
won't notice any changes, except in the prime area of motivation for this change: Improve
STL containers of const pointers and passing const pointers by reference. This is fixed
because many of the STL containers use a type 'T const&' as parameters and when T is
a const pointer, for example, 'K const*', then the full type is 'K const*const&'. This
means that the 'SWIGTYPE *const&' typemaps now match when T is either a non-const or
const pointer. Furthermore, some target languages incorrectly had 'SWIGTYPE *&' typemaps
when these should have been 'SWIGTYPE *const&'. These have been corrected (Java, C#, Lua, PHP).
*** POTENTIAL INCOMPATIBILITY ***
2010-03-13: wsfulton
[Java] Some very old deprecated pragma warnings are now errors.
2010-03-13: wsfulton
Improve handling of file names and directories containing double/multiple path separators.
2010-03-10: mutandiz (Mikel Bancroft)
[allegrocl] Use fully qualified symbol name of cl::identity in emit_defun().
2010-03-06: wsfulton
[Java] The intermediary JNI class modifiers are now public by default meaning these
intermediary low level functions are now accessible by default from outside any package
used. The proxy class pointer constructor and getCPtr() methods are also now public.
These are needed in order for the nspace option to work without any other mods.
The previous default of protected access can be restored using:
SWIG_JAVABODY_METHODS(protected, protected, SWIGTYPE)
%pragma(java) jniclassclassmodifiers = "class"
2010-03-06: wsfulton
[C#] Added the nspace feature for C#. Documentation for the nspace feature is now available.
2010-03-04: wsfulton
Added the nspace feature. This adds some improved namespace support. Currently only Java
is supported for target languages, where C++ namespaces are automatically translated into
Java packages. The feature only applies to classes,struct,unions and enums declared within
a namespace. Methods and variables declared in namespaces still effectively have their
namespaces flattened. Example usage:
%feature(nspace) Outer::Inner1::Color;
%feature(nspace) Outer::Inner2::Color;
namespace Outer {
namespace Inner1 {
struct Color {
...
};
}
namespace Inner2 {
struct Color {
...
};
}
}
For Java, the -package option is also required when using the nspace feature. Say
we use -package com.myco, the two classes can then be accessed as follows from Java:
com.myco.Outer.Inner1.Color and com.myco.Outer.Inner2.Color.
2010-02-27: wsfulton
[Python] Remove -dirvtable from the optimizations included by -O as it this option
currently leads to memory leaks as reported by Johan Blake.
2010-02-27: wsfulton
License code changes: SWIG Source is GPL-v3 and library code license is now clearer
and is provided under a very permissive license. See http://www.swig.org/legal.html.
2010-02-13: wsfulton
[Ruby] A few fixes for compiling under ruby-1.9.x including patch from 'Nibble'.
2010-02-13: wsfulton
[Ruby] Apply patch from Patrick Bennett to fix RARRAY_LEN and RARRAY_PTR usage for Ruby 1.9.x
used in various STL wrappers.
2010-02-13: wsfulton
[C#, Java] Fix incorrect multiply defined symbol name error when an enum item
and class name have the same name, as reported by Nathan Krieger. Example:
class Vector {};
namespace Text {
enum Preference { Vector };
}
This also fixes other incorrect corner case target language symbol name clashes.
2010-02-11: wsfulton
Add the -debug-lsymbols option for displaying the target language layer symbols.
2010-02-09: wsfulton
Fix -MM and -MMD options on Windows. They were not omitting files in the SWIG library as
they should be.
2010-02-08: wsfulton
Fix #1807329 - When Makefile dependencies are being generated using the -M family of options
on Windows, the file paths have been corrected to use single backslashes rather than double
backslashes as path separators.
2010-02-06: wsfulton
Fix #2918902 - language specific files not being generated in correct directory on
Windows when using forward slashes for -o, for example:
swig -python -c++ -o subdirectory/theinterface_wrap.cpp subdirectory/theinterface.i
2010-02-05: wsfulton
Fix #2894405 - assertion when using -xmlout.
2010-01-28: wsfulton
Fix typemap matching bug when a templated type has a typemap both specialized and not
specialized. For example:
template<typename T> struct XX { ... };
%typemap(in) const XX & "..."
%typemap(in) const XX< int > & "..."
resulted in the 2nd typemap being applied for all T in XX< T >.
2010-01-22: wsfulton
Fix #2933129 - typemaps not being found when the unary scope operator (::) is used to denote
global scope, the typemap is now used in situations like this:
struct X {};
%typemap(in) const X & "..."
void m(const ::X &);
and this:
struct X {};
%typemap(in) const ::X & "..."
void m(const X &);
2010-01-20: wsfulton
Fix some unary scope operator (::) denoting global scope problems in the types generated
into the C++ layer. Previously the unary scope operator was dropped in the generated code
if the type had any sort of qualifier, for example when using pointers, references, like
::foo*, ::foo&, bar< ::foo* >.
2010-01-13: olly
[PHP] Add datetime to the list of PHP predefined classes (patch
from David Fletcher in SF#2931042).
2010-01-11: wsfulton
Slight change to warning, error and diagnostic reporting. The warning number is no
longer shown within brackets. This is to help default parsing of warning messages by
other tools, vim on Unix in particular.
Example original display using -Fstandard:
example.i:20: Warning(401): Nothing known about base class 'B'. Ignored.
New display:
example.i:20: Warning 401: Nothing known about base class 'B'. Ignored.
Also subtle fix to -Fmicrosoft format adding in missing space. Example original display:
example.i(20): Warning(401): Nothing known about base class 'Base'. Ignored.
New display:
example.i(20) : Warning 401: Nothing known about base class 'Base'. Ignored.
2010-01-10: wsfulton
Fix a few inconsistencies in reporting of file/line numberings including modifying
the overload warnings 509, 512, 516, 474, 475 to now be two line warnings.
2010-01-10: wsfulton
Modify -debug-tags output to use standard file name/line reporting so that editors
can easily navigate to the appropriate lines.
Was typically:
. top . include . include (/usr/share/swig/temp/trunk/Lib/swig.swg:312)
. top . include . include . include (/usr/share/swig/temp/trunk/Lib/swigwarnings.swg:39)
now:
/usr/share/swig/temp/trunk/Lib/swig.swg:312: . top . include . include
/usr/share/swig/temp/trunk/Lib/swigwarnings.swg:39: . top . include . include . include
2010-01-03: wsfulton
Fix missing file/line numbers for typemap warnings and in output from the
-debug-tmsearch/-debug-tmused options.
2010-01-03: wsfulton
Add typemaps used debugging option (-debug-tmused). When used each line displays
the typemap used for each type for which code is being generated including the file
and line number related to the type. This is effectively a condensed form of the
-debug-tmsearch option. Documented in Typemaps.html.
2009-12-23: wsfulton
Fix for %javaexception and directors so that all the appropriate throws clauses
are generated. Problem reported by Peter Greenwood.
2009-12-20: wsfulton
Add -debug-tmsearch option for debugging the typemap pattern matching rules.
Documented in Typemaps.html.
2009-12-12: wsfulton
[Octave] Remove the -api option and use the new OCTAVE_API_VERSION_NUMBER
macro provided in the octave headers for determining the api version instead.
2009-12-04: olly
[Ruby] Improve support for Ruby 1.9 under GCC. Addresses part of
SF#2859614.
2009-12-04: olly
Fix handling of modulo operator (%) in constant expressions
(SF#2818562).
2009-12-04: olly
[PHP] "empty" is a reserved word in PHP, so rename empty() method
on STL classes to "is_empty()" (previously this was automatically
renamed to "c_empty()").
*** POTENTIAL INCOMPATIBILITY ***
2009-12-03: olly
[PHP] Add typemaps for long long and unsigned long long, and for
pointer to method.
2009-12-02: olly
[PHP] Fix warning and rename of reserved class name to be case
insensitive.
2009-12-01: wsfulton
Revert support for %extend and memberin typemaps added in swig-1.3.39. The
memberin typemaps are ignored again for member variables within a %extend block.
Documentation inconsistency reported by Torsten Landschoff.
2009-11-29: wsfulton
[Java, C#] Fix generated quoting when using %javaconst(1)/%csconst(1) for
static const char member variables.
%javaconst(1) A;
%csconst(1) A;
struct X {
static const char A = 'A';
};
2009-11-26: wsfulton
[Java, C#] Fix %javaconst(1)/%csconst(1) for static const member variables to
use the actual constant value if it is specified, rather than the C++ code to
access the member.
%javaconst(1) EN;
%csconst(1) EN;
struct X {
static const int EN = 2;
};
2009-11-23: wsfulton
C++ nested typedef classes can now be handled too, for example:
struct Outer {
typedef Foo { } FooTypedef1, FooTypedef2;
};
2009-11-18: wsfulton
The wrappers for C nested structs are now generated in the same order as declared
in the parsed code.
2009-11-18: wsfulton
Fix #491476 - multiple declarations of nested structs, for example:
struct Outer {
struct {
int val;
} inner1, inner2, *inner3, inner4[1];
} outer;
2009-11-17: wsfulton
Fix parsing of enum declaration and initialization, for example:
enum ABC {
a,
b,
c
} A = a, *pC = &C, array[3] = {a, b, c};
2009-11-17: wsfulton
Fix parsing of struct declaration and initialization, for example:
struct S {
int x;
} instance = { 10 };
2009-11-15: wsfulton
Fix #1960977 - Syntax error parsing derived nested class declaration and member
variable instance.
2009-11-14: wsfulton
Fix #2310483 - function pointer typedef within extern "C" block.
2009-11-13: wsfulton
Fix usage of nested template classes within templated classes so that compileable code
is generated.
2009-11-13: olly
[php] Fix place where class prefix (as specified with -prefix)
wasn't being used. Patch from gverbruggen in SF#2892647.
2009-11-12: wsfulton
Fix usage of nested template classes so that compileable code is generated - the nested
template class is now treated like a normal nested classes, that is, as an opaque type
unless the nestedworkaround feature is used.
2009-11-12: wsfulton
Replace SWIGWARN_PARSE_NESTED_CLASS with SWIGWARN_PARSE_NAMED_NESTED_CLASS and
SWIGWARN_PARSE_UNNAMED_NESTED_CLASS for named and unnamed nested classes respectively.
Named nested class ignored warnings can now be suppressed by name using %warnfilter, eg:
%warnfilter(SWIGWARN_PARSE_NAMED_NESTED_CLASS) Outer::Inner;
but clearly unnamed nested classes cannot and the global suppression is still required, eg:
#pragma SWIG nowarn=SWIGWARN_PARSE_UNNAMED_NESTED_CLASS
2009-11-11: wsfulton
Added the nestedworkaround feature as a way to use the full functionality of a nested class
(C++ mode only). It removes the nested class from SWIG's type information so it is as if SWIG
had never parsed the nested class. The documented nested class workarounds using a global
fake class stopped working when SWIG treated the nested class as an opaque pointer, and
this feature reverts this behaviour. The documentation has been updated with details of how
to use and implement it, see the "Nested classes" section in SWIGPlus.html.
2009-11-11: wsfulton
There were a number of C++ cases where nested classes/structs/unions were being handled
as if C code was being parsed which would oftentimes lead to uncompileable code as an
attempt was made to wrap the nested structs like it is documented for C code. Now all
nested structs/classes/unions are ignored in C++ mode, as was always documented. However,
there is an improvement as usage of nested structs/classes/unions is now always treated
as an opaque type by default, resulting in generated code that should always compile.
*** POTENTIAL INCOMPATIBILITY ***
2009-11-09: drjoe
Fix R for -fcompact and add std_map.i
2009-11-08: wsfulton
Fix inconsistency for nested structs/unions/classes. Uncompileable code was being
generated when inner struct and union declarations were used as types within the
inner struct. The inner struct/union is now treated as a forward declaration making the
behaviour the same as an inner class. (C++ code), eg:
struct Outer {
struct InnerStruct { int x; };
InnerStruct* getInnerStruct();
};
2009-11-08: wsfulton
Ignored nested class/struct warnings now display the name of the ignored class/struct.
2009-11-07: wsfulton
Bug #1514681 - Fix nested template classes within a namespace generated uncompileable
code and introduced strange side effects to other wrapper code especially code
after the nested template class. Note that nested template classes are still ignored.
2009-11-07: wsfulton
Add new debug options:
-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
2009-11-03: wsfulton
Fix some usage of unary scope operator (::) denoting global scope, for example:
namespace AA { /* ... */ }
using namespace ::AA;
and bug #1816802 - SwigValueWrapper should be used:
struct CC {
CC(int); // no default constructor
};
::CC x();
and in template parameter specializations:
struct S {};
template <typename T> struct X { void a() {}; };
template <> struct X<S> { void b() {}; };
%template(MyTConcrete) X< ::S >;
plus probably some other corner case usage of ::.
2009-11-02: olly
[Python] Fix potential memory leak in initialisation code for the
generated module.
2009-10-23: wsfulton
Fix seg fault when using a named nested template instantiation using %template(name)
within a class. A warning that these are not supported is now issued plus processing
continues as if no name was given.
2009-10-20: wsfulton
[Python] Fix std::vector<const T*>. This would previously compile, but not run correctly.
2009-10-20: wsfulton
Fixed previously fairly poor template partial specialization and explicit
specialization support. Numerous bugs in this area have been fixed including:
- Template argument deduction implemented for template type arguments, eg this now
works:
template<typename T> class X {};
template<typename T> class X<T *> {};
%template(X1) X<const int *>; // Chooses T * specialization
and more complex cases with multiple parameters and a mix of template argument
deduction and explicitly specialised parameters, eg:
template <typename T1, typename T2> struct TwoParm { void a() {} };
template <typename T1> struct TwoParm<T1 *, int *> { void e() {} };
%template(E) TwoParm<int **, int *>;
Note that the primary template must now be in scope, like in C++, when
an explicit or partial specialization is instantiated with %template.
*** POTENTIAL INCOMPATIBILITY ***
2009-09-14: wsfulton
[C#] Add %csattributes for adding C# attributes to enum values, see docs for example.
2009-09-11: wsfulton
Fix memmove regression in cdata.i as reported by Adriaan Renting.
2009-09-07: wsfulton
Fix constant expressions containing <= or >=.
2009-09-02: wsfulton
The following operators in constant expressions now result in type bool for C++
wrappers and remain as type int for C wrappers, as per each standard:
&& || == != < > <= >= (Actually the last 4 are still broken). For example:
#define A 10
#define B 10
#define A_EQ_B A == B // now wrapped as type bool for C++
#define A_AND_B A && B // now wrapped as type bool for C++
2009-09-02: wsfulton
Fix #2845746. true and false are now recognised keywords (only when wrapping C++).
Constants such as the following are now wrapped (as type bool):
#define FOO true
#define BAR FOO && false
Version 1.3.40 (18 August 2009)
===============================
@ -956,7 +1618,7 @@ Version 1.3.35 (7 April 2008)
03/17/2008: olly
Fix memory leak in SWIG's parser (based on patch from Russell
Bryant in SF#1914023).`
Bryant in SF#1914023).
03/12/2008: wsfulton
Fix bug #1878285 - unnecessary cast for C struct creation wrappers.
@ -8256,7 +8918,7 @@ Version 1.3.22 (September 4, 2004)
When needed, use
%inlcude std_string.i // 'char' strings
%inlcude std_wstring.i // 'wchar_t; strings
%inlcude std_wstring.i // 'wchar_t' strings
04/10/2004: mmatus (Marcelo Matus)

386
CHANGES.current
View file

@ -1,371 +1,27 @@
Version 1.3.41 (in progress)
============================
This file contains the changes for the current release.
See the CHANGES file for changes in older releases.
See the RELEASENOTES file for a summary of changes in each release.
2010-02-27: wsfulton
[Python] Remove -dirvtable from the optimizations included by -O as it this option
currently leads to memory leaks as reported by Johan Blake.
Version 2.0.1 (in progress)
===========================
2010-02-13: wsfulton
[Ruby] A few fixes for compiling under ruby-1.9.x including patch from 'Nibble'.
2010-07-16: wsfulton
Fix wrapping of function pointers and member function pointers when the function
returns by reference.
2010-02-13: wsfulton
[Ruby] Apply patch from Patrick Bennett to fix RARRAY_LEN and RARRAY_PTR usage for Ruby 1.9.x
used in various STL wrappers.
2010-07-08: wsfulton
Fix #3024875 - shared_ptr of classes with non-public destructors. This also fixes
the "unref" feature when used on classes with non-public destructors.
2010-02-13: wsfulton
[C#, Java] Fix incorrect multiply defined symbol name error when an enum item
and class name have the same name, as reported by Nathan Krieger. Example:
2010-06-10: wsfulton
[Lua] Fix SWIG_lua_isnilstring multiply defined when using multiple
modules and wrapping strings. Patch from 'Number Cruncher'.
class Vector {};
namespace Text {
enum Preference { Vector };
}
This also fixes other incorrect corner case target language symbol name clashes.
2010-02-11: wsfulton
Add the -debug-lsymbols option for displaying the target language layer symbols.
2010-02-09: wsfulton
Fix -MM and -MMD options on Windows. They were not omitting files in the SWIG library as
they should be.
2010-02-08: wsfulton
Fix #1807329 - When Makefile dependencies are being generated using the -M family of options
on Windows, the file paths have been corrected to use single backslashes rather than double
backslashes as path separators.
2010-02-06: wsfulton
Fix #2918902 - language specific files not being generated in correct directory on
Windows when using forward slashes for -o, for example:
swig -python -c++ -o subdirectory/theinterface_wrap.cpp subdirectory/theinterface.i
2010-02-05: wsfulton
Fix #2894405 - assertion when using -xmlout.
2010-01-28: wsfulton
Fix typemap matching bug when a templated type has a typemap both specialized and not
specialized. For example:
template<typename T> struct XX { ... };
%typemap(in) const XX & "..."
%typemap(in) const XX< int > & "..."
resulted in the 2nd typemap being applied for all T in XX< T >.
2010-01-22: wsfulton
Fix #2933129 - typemaps not being found when the unary scope operator (::) is used to denote
global scope, the typemap is now used in situations like this:
struct X {};
%typemap(in) const X & "..."
void m(const ::X &);
and this:
struct X {};
%typemap(in) const ::X & "..."
void m(const X &);
2010-01-20: wsfulton
Fix some unary scope operator (::) denoting global scope problems in the types generated
into the C++ layer. Previously the unary scope operator was dropped in the generated code
if the type had any sort of qualifier, for example when using pointers, references, like
::foo*, ::foo&, bar< ::foo* >.
2010-01-13: olly
[PHP] Add datetime to the list of PHP predefined classes (patch
from David Fletcher in SF#2931042).
2010-01-11: wsfulton
Slight change to warning, error and diagnostic reporting. The warning number is no
longer shown within brackets. This is to help default parsing of warning messages by
other tools, vim on Unix in particular.
Example original display using -Fstandard:
example.i:20: Warning(401): Nothing known about base class 'B'. Ignored.
New display:
example.i:20: Warning 401: Nothing known about base class 'B'. Ignored.
Also subtle fix to -Fmicrosoft format adding in missing space. Example original display:
example.i(20): Warning(401): Nothing known about base class 'Base'. Ignored.
New display:
example.i(20) : Warning 401: Nothing known about base class 'Base'. Ignored.
2010-01-10: wsfulton
Fix a few inconsistencies in reporting of file/line numberings including modifying
the overload warnings 509, 512, 516, 474, 475 to now be two line warnings.
2010-01-10: wsfulton
Modify -debug-tags output to use standard file name/line reporting so that editors
can easily navigate to the appropriate lines.
Was typically:
. top . include . include (/usr/share/swig/temp/trunk/Lib/swig.swg:312)
. top . include . include . include (/usr/share/swig/temp/trunk/Lib/swigwarnings.swg:39)
now:
/usr/share/swig/temp/trunk/Lib/swig.swg:312: . top . include . include
/usr/share/swig/temp/trunk/Lib/swigwarnings.swg:39: . top . include . include . include
2010-01-03: wsfulton
Fix missing file/line numbers for typemap warnings and in output from the
-debug-tmsearch/-debug-tmused options.
2010-01-03: wsfulton
Add typemaps used debugging option (-debug-tmused). When used each line displays
the typemap used for each type for which code is being generated including the file
and line number related to the type. This is effectively a condensed form of the
-debug-tmsearch option. Documented in Typemaps.html.
2009-12-23: wsfulton
Fix for %javaexception and directors so that all the appropriate throws clauses
are generated. Problem reported by Peter Greenwood.
2009-12-20: wsfulton
Add -debug-tmsearch option for debugging the typemap pattern matching rules.
Documented in Typemaps.html.
2009-12-12: wsfulton
[Octave] Remove the -api option and use the new OCTAVE_API_VERSION_NUMBER
macro provided in the octave headers for determining the api version instead.
2009-12-04: olly
[Ruby] Improve support for Ruby 1.9 under GCC. Addresses part of
SF#2859614.
2009-12-04: olly
Fix handling of modulo operator (%) in constant expressions
(SF#2818562).
2009-12-04: olly
[PHP] "empty" is a reserved word in PHP, so rename empty() method
on STL classes to "is_empty()" (previously this was automatically
renamed to "c_empty()").
*** POTENTIAL INCOMPATIBILITY ***
2009-12-03: olly
[PHP] Add typemaps for long long and unsigned long long, and for
pointer to method.
2009-12-02: olly
[PHP] Fix warning and rename of reserved class name to be case
insensitive.
2009-12-01: wsfulton
Revert support for %extend and memberin typemaps added in swig-1.3.39. The
memberin typemaps are ignored again for member variables within a %extend block.
Documentation inconsistency reported by Torsten Landschoff.
2009-11-29: wsfulton
[Java, C#] Fix generated quoting when using %javaconst(1)/%csconst(1) for
static const char member variables.
%javaconst(1) A;
%csconst(1) A;
struct X {
static const char A = 'A';
};
2009-11-26: wsfulton
[Java, C#] Fix %javaconst(1)/%csconst(1) for static const member variables to
use the actual constant value if it is specified, rather than the C++ code to
access the member.
%javaconst(1) EN;
%csconst(1) EN;
struct X {
static const int EN = 2;
};
2009-11-23: wsfulton
C++ nested typedef classes can now be handled too, for example:
struct Outer {
typedef Foo { } FooTypedef1, FooTypedef2;
};
2009-11-18: wsfulton
The wrappers for C nested structs are now generated in the same order as declared
in the parsed code.
2009-11-18: wsfulton
Fix #491476 - multiple declarations of nested structs, for example:
struct Outer {
struct {
int val;
} inner1, inner2, *inner3, inner4[1];
} outer;
2009-11-17: wsfulton
Fix parsing of enum declaration and initialization, for example:
enum ABC {
a,
b,
c
} A = a, *pC = &C, array[3] = {a, b, c};
2009-11-17: wsfulton
Fix parsing of struct declaration and initialization, for example:
struct S {
int x;
} instance = { 10 };
2009-11-15: wsfulton
Fix #1960977 - Syntax error parsing derived nested class declaration and member
variable instance.
2009-11-14: wsfulton
Fix #2310483 - function pointer typedef within extern "C" block.
2009-11-13: wsfulton
Fix usage of nested template classes within templated classes so that compileable code
is generated.
2009-11-13: olly
[php] Fix place where class prefix (as specified with -prefix)
wasn't being used. Patch from gverbruggen in SF#2892647.
2009-11-12: wsfulton
Fix usage of nested template classes so that compileable code is generated - the nested
template class is now treated like a normal nested classes, that is, as an opaque type
unless the nestedworkaround feature is used.
2009-11-12: wsfulton
Replace SWIGWARN_PARSE_NESTED_CLASS with SWIGWARN_PARSE_NAMED_NESTED_CLASS and
SWIGWARN_PARSE_UNNAMED_NESTED_CLASS for named and unnamed nested classes respectively.
Named nested class ignored warnings can now be suppressed by name using %warnfilter, eg:
%warnfilter(SWIGWARN_PARSE_NAMED_NESTED_CLASS) Outer::Inner;
but clearly unnamed nested classes cannot and the global suppression is still required, eg:
#pragma SWIG nowarn=SWIGWARN_PARSE_UNNAMED_NESTED_CLASS
2009-11-11: wsfulton
Added the nestedworkaround feature as a way to use the full functionality of a nested class
(C++ mode only). It removes the nested class from SWIG's type information so it is as if SWIG
had never parsed the nested class. The documented nested class workarounds using a global
fake class stopped working when SWIG treated the nested class as an opaque pointer, and
this feature reverts this behaviour. The documentation has been updated with details of how
to use and implement it, see the "Nested classes" section in SWIGPlus.html.
2009-11-11: wsfulton
There were a number of C++ cases where nested classes/structs/unions were being handled
as if C code was being parsed which would oftentimes lead to uncompileable code as an
attempt was made to wrap the nested structs like it is documented for C code. Now all
nested structs/classes/unions are ignored in C++ mode, as was always documented. However,
there is an improvement as usage of nested structs/classes/unions is now always treated
as an opaque type by default, resulting in generated code that should always compile.
*** POTENTIAL INCOMPATIBILITY ***
2009-11-09: drjoe
Fix R for -fcompact and add std_map.i
2009-11-08: wsfulton
Fix inconsistency for nested structs/unions/classes. Uncompileable code was being
generated when inner struct and union declarations were used as types within the
inner struct. The inner struct/union is now treated as a forward declaration making the
behaviour the same as an inner class. (C++ code), eg:
struct Outer {
struct InnerStruct { int x; };
InnerStruct* getInnerStruct();
};
2009-11-08: wsfulton
Ignored nested class/struct warnings now display the name of the ignored class/struct.
2009-11-07: wsfulton
Bug #1514681 - Fix nested template classes within a namespace generated uncompileable
code and introduced strange side effects to other wrapper code especially code
after the nested template class. Note that nested template classes are still ignored.
2009-11-07: wsfulton
Add new debug options:
-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
2009-11-03: wsfulton
Fix some usage of unary scope operator (::) denoting global scope, for example:
namespace AA { /* ... */ }
using namespace ::AA;
and bug #1816802 - SwigValueWrapper should be used:
struct CC {
CC(int); // no default constructor
};
::CC x();
and in template parameter specializations:
struct S {};
template <typename T> struct X { void a() {}; };
template <> struct X<S> { void b() {}; };
%template(MyTConcrete) X< ::S >;
plus probably some other corner case usage of ::.
2009-11-02: olly
[Python] Fix potential memory leak in initialisation code for the
generated module.
2009-10-23: wsfulton
Fix seg fault when using a named nested template instantiation using %template(name)
within a class. A warning that these are not supported is now issued plus processing
continues as if no name was given.
2009-10-20: wsfulton
[Python] Fix std::vector<const T*>. This would previously compile, but not run correctly.
2009-10-20: wsfulton
Fixed previously fairly poor template partial specialization and explicit
specialization support. Numerous bugs in this area have been fixed including:
- Template argument deduction implemented for template type arguments, eg this now
works:
template<typename T> class X {};
template<typename T> class X<T *> {};
%template(X1) X<const int *>; // Chooses T * specialization
and more complex cases with multiple parameters and a mix of template argument
deduction and explicitly specialised parameters, eg:
template <typename T1, typename T2> struct TwoParm { void a() {} };
template <typename T1> struct TwoParm<T1 *, int *> { void e() {} };
%template(E) TwoParm<int **, int *>;
Note that the primary template must now be in scope, like in C++, when
an explicit or partial specialization is instantiated with %template.
*** POTENTIAL INCOMPATIBILITY ***
2009-09-14: wsfulton
[C#] Add %csattributes for adding C# attributes to enum values, see docs for example.
2009-09-11: wsfulton
Fix memmove regression in cdata.i as reported by Adriaan Renting.
2009-09-07: wsfulton
Fix constant expressions containing <= or >=.
2009-09-02: wsfulton
The following operators in constant expressions now result in type bool for C++
wrappers and remain as type int for C wrappers, as per each standard:
&& || == != < > <= >= (Actually the last 4 are still broken). For example:
#define A 10
#define B 10
#define A_EQ_B A == B // now wrapped as type bool for C++
#define A_AND_B A && B // now wrapped as type bool for C++
2009-09-02: wsfulton
Fix #2845746. true and false are now recognised keywords (only when wrapping C++).
Constants such as the following are now wrapped (as type bool):
#define FOO true
#define BAR FOO && false
2010-06-10: olly
[PHP] Fix directors to correctly call a method with has a
different name in PHP to C++ (we were always using the C++ name
in this case).
2010-06-03: wsfulton
Fix uncompileable code when %rename results in two enum items
with the same name. Reported by Vadim Zeitlin.

42
COPYRIGHT
View file

@ -29,7 +29,7 @@ Past SWIG developers and major contributors include:
Charlie Savage (cfis@interserv.com) (Ruby)
Thien-Thi Nguyen (ttn@glug.org) (build/test/misc)
Richard Palmer (richard@magicality.org) (PHP)
Sam Liddicott - Anonova Ltd (saml@liddicott.com) (PHP)
Sam Liddicott - Ananova Ltd (saml@liddicott.com) (PHP)
Tim Hockin - Sun Microsystems (thockin@sun.com) (PHP)
Kevin Ruland (PHP)
Shibukawa Yoshiki (Japanese Translation)
@ -58,6 +58,42 @@ Past SWIG developers and major contributors include:
Past contributors include:
James Michael DuPont, Clark McGrew, Dustin Mitchell, Ian Cooke, Catalin Dumitrescu, Baran
Kovuk, Oleg Tolmatcev, Tal Shalif, Lluis Padro, Chris Seatory, Igor Bely, Robin Dunn
(See CHANGES and CHANGES.current for a more complete list).
Kovuk, Oleg Tolmatcev, Tal Shalif, Lluis Padro, Chris Seatory, Igor Bely, Robin Dunn,
Edward Zimmermann, David Ascher, Dominique Dumont, Pier Giorgio Esposito, Hasan Baran Kovuk,
Klaus Wiederänders
(See CHANGES and CHANGES.current and the bug tracker for a more complete list).
Past students:
Songyan Feng (Chicago).
Xinghua Shi (Chicago).
Jing Cao (Chicago).
Aquinas Hobor (Chicago).
Historically, the following people contributed to early versions of SWIG.
Peter Lomdahl, Brad Holian, Shujia Zhou, Niels Jensen, and Tim Germann
at Los Alamos National Laboratory were the first users. Patrick
Tullmann at the University of Utah suggested the idea of automatic
documentation generation. John Schmidt and Kurtis Bleeker at the
University of Utah tested out the early versions. Chris Johnson
supported SWIG's developed at the University of Utah. John Buckman,
Larry Virden, and Tom Schwaller provided valuable input on the first
releases and improving the portability of SWIG. David Fletcher and
Gary Holt have provided a great deal of input on improving SWIG's
Perl5 implementation. Kevin Butler contributed the first Windows NT
port.
Early bug reports and patches:
Adam Hupp, Arthur Smyles, Brad Clements, Brett Williams, Buck Hodges,
Burkhard Kloss, Chia-Liang Kao, Craig Files, Dennis Marsa, Dieter Baron,
Drake Diedrich, Fleur Diana Dragan, Gary Pennington, Geoffrey Hort, Gerald Williams,
Greg Anderson, Greg Kochanski, Greg Troxel, Henry Rowley, Irina Kotlova,
Israel Taller, James Bailey, Jim Fulton, Joel Reed, Jon Travis,
Junio Hamano, Justin Heyes-Jones, Karl Forner, Keith Davidson,
Krzysztof Kozminski, Larry Virden, Luke J Crook, Magnus Ljung, Marc Zonzon,
Mark Howson, Micahel Scharf, Michel Sanner, Mike Romberg, Mike Simons,
Mike Weiblen, Paul Brannan, Ram Bhamidipaty, Reinhard Fobbe, Rich Wales,
Richard Salz, Roy Lecates, Rudy Albachten, Scott Drummonds
Scott Michel, Shaun Lowry, Steve Galser, Tarn Weisner Burton,
Thomas Weidner, Tony Seward, Uwe Steinmann, Vadim Chugunov, Wyss Clemens,
Zhong Ren.

2
Doc/Devel/cmdopt.html
View file

@ -36,7 +36,7 @@ functions to mark whether or not a particular command line option was used. Thi
<h2>Argument Marking</h2>
As command line options are are processed by language modules, the following functions are used
As command line options are processed by language modules, the following functions are used
to mark the arguments as used:
<p>

17
Doc/Devel/engineering.html
View file

@ -119,22 +119,25 @@ are case-insensitive on Windows so this convention will prevent you from inadver
creating two files that differ in case-only.
<p>
Each file should include a short abstract, author information, copyright information, and
Each file should include a short abstract, license information and
a SVN revision tag like this:
<blockquote>
<pre>
/* -----------------------------------------------------------------------------
* See the LICENSE file for information on copyright, usage and redistribution
* of SWIG, and the README file for authors - http://www.swig.org/release.html.
* This file is part of SWIG, which is licensed as a whole under version 3
* (or any later version) of the GNU General Public License. Some additional
* terms also apply to certain portions of SWIG. The full details of the SWIG
* license and copyrights can be found in the LICENSE and COPYRIGHT files
* included with the SWIG source code as distributed by the SWIG developers
* and at http://www.swig.org/legal.html.
*
* cwrap.c
* xxx.c
*
* This file defines a variety of wrapping rules for C/C++ handling including
* the naming of local variables, calling conventions, and so forth.
* This file defines ...
* ----------------------------------------------------------------------------- */
char cvsroot_cwrap_c[] = "$Id$";
static char cvs[] = "&#36Id&#36 xxx.c";
#include "swig.h"

92
Doc/Devel/internals.html
View file

@ -42,11 +42,9 @@ David M. Beazley <br>
</ul>
<li><a name="i3" href="#3">3. Types and Typemaps</a>
<li><a name="i4" href="#4">4. Parsing</a>
<li><a name="i5" href="#5">5. Difference Between SWIG 1.1 and SWIG 1.3</a>
<li><a name="i6" href="#6">6. Plans for SWIG 2.0</a>
<li><a name="i7" href="#7">7. C/C++ Wrapper Support Functions</a>
<li><a name="i8" href="#8">8. Symbol Naming Guidelines for Generated C/C++ Code</a>
<li><a name="i9" href="#9">9. Debugging SWIG</a>
<li><a name="i5" href="#5">5. C/C++ Wrapper Support Functions</a>
<li><a name="i6" href="#6">6. Symbol Naming Guidelines for Generated C/C++ Code</a>
<li><a name="i7" href="#7">7. Debugging SWIG</a>
</ul>
<a name="1" href="#i1">
@ -76,9 +74,8 @@ to code).
<tr><td>Examples</td>
<td>This subdir tree contains examples of using SWIG w/ different
scripting languages, including makefiles. Typically, there are the
"simple" and "matrix" examples, w/ some languages offering additional
examples. The GIFPlot example has its own set of per-language
subdirectories. See the README more index.html file in each directory
"simple" and "class" examples, w/ some languages offering additional
examples. See the README more index.html file in each directory
for more info. [FIXME: Ref SWIG user manual.]</td>
</tr>
@ -97,55 +94,35 @@ info.</td>
</tr>
<tr><td>Source</td>
<td>SWIG source code is in this subdir tree. Directories marked w/ "(*)"
are used in building the <tt>swig</tt> executable.
<td>The C and C++ source code for the <tt>swig</tt> executable is in this
subdir tree.</td>
<table border=1>
<tr><td>DOH (*)</td>
<tr><td>DOH</td>
<td>C library providing memory allocation, file access and generic
containers. Result: libdoh.a</td>
containers.</td>
</tr>
<tr><td>Experiment</td>
<td>[TODO]</td>
</tr>
<tr><td>Include (*)</td>
<tr><td>Include</td>
<td>Configuration .h files</td>
</tr>
<tr><td>LParse</td>
<td>Parser (lex / yacc) files and support [why not (*)?!]</td>
<tr><td>CParse</td>
<td>Parser (lex / yacc) files and support</td>
</tr>
<tr><td>Modules</td>
<td>[TODO]</td>
</tr>
<tr><td>Modules1.1 (*)</td>
<td>Language-specific callbacks that does actual code generation (each
language has a .cxx and a .h file). Result: libmodules11.a</td>
language has a .cxx and a .h file).</td>
</tr>
<tr><td>Preprocessor (*)</td>
<td>SWIG-specialized C/C++ preprocessor. Result: libcpp.a</td>
<tr><td>Preprocessor</td>
<td>SWIG-specialized C/C++ preprocessor.</td>
</tr>
<tr><td>SWIG1.1 (*)</td>
<td>Parts of SWIG that are not language-specific, including option
processing and the type-mapping system. Result: libswig11.a.
Note: This directory is currently being phased out. </td>
</tr>
<tr><td>SWIG1.3</td>
<td>[TODO] [funny, nothing here is presently used for swig-1.3].
This directory might turn into a compatibility interface between
SWIG1.3 and the SWIG1.1 modules.</td>
</tr>
<tr><td>Swig (*)</td>
<td>This directory contains the new ANSI C core of the system
<tr><td>Swig</td>
<td>This directory contains the ANSI C core of the system
and contains generic functions related to types, file handling,
scanning, and so forth.</td>
</tr>
@ -154,7 +131,7 @@ are used in building the <tt>swig</tt> executable.
</tr>
<tr><td>Tools</td>
<td>Libtool support and the mkdist.py script.</td>
<td>The mkdist.py script and other tools.</td>
</tr>
<tr><td>Win</td>
@ -173,14 +150,14 @@ to look for code:
<ul>
<li> <tt>Modules1.1/swigmain.cxx:main()</tt> is the program entry
<li> <tt>Modules/swigmain.cxx:main()</tt> is the program entry
point. It parses the language-specifying command-line option (for
example, <tt>-java</tt>), creating a new language-specific wrapping
object (each language is a C++ class derived from base class
<tt>Language</tt>). This object and the command-line is passed to
<tt>SWIG_main()</tt>, whose return value is the program exit value.
<li> <tt>SWIG1.1/main.cxx:SWIG_main()</tt> is the "real" main. It
<li> <tt>Modules/main.cxx:SWIG_main()</tt> is the "real" main. It
initializes the preprocessor and typemap machinery, defines some
preprocessor symbols, locates the SWIG library, processes common
command-line options, and then calls the language-specific command-line
@ -203,7 +180,7 @@ included <tt>-freeze</tt>, go into an infinite loop; otherwise return the
error count.
<li> The language-specific <tt>parse()</tt> (and all other
language-specific code) lives in <tt>Modules1.1/foo.{h,cxx}</tt> for
language-specific code) lives in <tt>Modules/foo.{h,cxx}</tt> for
language Foo. Typically, <tt>FOO::parse()</tt> calls
<tt>FOO::headers()</tt> and then the global function <tt>yyparse()</tt>,
which uses the callbacks registered by <tt>SWIG_main()</tt> above.
@ -553,8 +530,7 @@ list item: listval5
The representation and manipulation of types is currently in the
process of being reorganized and (hopefully) simplified. The
following list describes the current set of functions that are used to
manipulate datatypes. These functions are different than in
SWIG1.1 and may change names in the final SWIG1.3 release.
manipulate datatypes.
<ul>
<li><tt>SwigType_str(SwigType *t, char *name)</tt>.<br>
@ -710,19 +686,7 @@ repeated calls without making any copies.
[TODO]
<a name="5" href="#i5">
<h2>5. Difference Between SWIG 1.1 and SWIG 1.3</h2>
</a>
[TODO]
<a name="6" href="#i6">
<h2>6. Plans for SWIG 2.0</h2>
</a>
[TODO]
<a name="7" href="#i7">
<h2>7. The C/C++ Wrapping Layer</h2>
<h2>5. The C/C++ Wrapping Layer</h2>
</a>
Added: Dave Beazley (July 22, 2000)
@ -1001,8 +965,8 @@ for specifying local variable declarations and argument conversions.
<a name="8" href="#i8">
<h2>8. Symbol Naming Guidelines for Generated C/C++ Code</h2>
<a name="6" href="#i6">
<h2>6. Symbol Naming Guidelines for Generated C/C++ Code</h2>
</a>
The C++ standard (ISO/IEC 14882:1998(E)) states:
<blockquote>
@ -1048,8 +1012,8 @@ For code compiled as C or C++ that attempts to mangle a wrapped symbol:
In the past SWIG has generated many symbols which flout the standard especially double underscores. In fact they may not all be rooted out yet, so please fix them when you see them.
<a name="9" href="#i9">
<h2>9. Debugging SWIG</h2>
<a name="7" href="#i7">
<h2>7. Debugging SWIG</h2>
</a>
Warning. Debugging SWIG is for the very patient.
<p>
@ -1100,7 +1064,7 @@ Please also read the Debugging Functions section in <a href="tree.html">SWIG Par
</p>
<hr>
Copyright (C) 1999-2004 SWIG Development Team.
Copyright (C) 1999-2010 SWIG Development Team.
</body>
</html>

9
Doc/Devel/scanner.html
View file

@ -77,7 +77,7 @@ string prior to using this function.
Pushes a token into the scanner. This exact token will be returned by the next call to <tt>Scanner_token()</tt>.
<tt>tokvalue</tt> is the integer token value to return and <tt>val</tt> is the token text to return. This
function is only used to handle very special parsing cases. For instance, if you need the scanner to
return a ficticious token into order to enter a special parsing case.
return a fictitious token into order to enter a special parsing case.
</blockquote>
<p>
@ -238,7 +238,7 @@ SWIG_TOKEN_PERIOD .
SWIG_TOKEN_AT @
SWIG_TOKEN_DOLLAR $
SWIG_TOKEN_ENDLINE Literal newline
SWIG_TOKEN_ID identifer
SWIG_TOKEN_ID identifier
SWIG_TOKEN_FLOAT Floating point with F suffix (e.g., 3.1415F)
SWIG_TOKEN_DOUBLE Floating point (e.g., 3.1415 )
SWIG_TOKEN_INT Integer (e.g., 314)
@ -281,8 +281,3 @@ using these functions to write a yacc-compatible lexer.
</body>
</html>

4
Doc/Manual/Allegrocl.html
View file

@ -8,7 +8,7 @@
<body bgcolor="#ffffff">
<H1><a name="Allegrocl_nn1"></a>17 SWIG and Allegro Common Lisp</H1>
<H1><a name="Allegrocl"></a>17 SWIG and Allegro Common Lisp</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -1777,7 +1777,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
</div>
<p>
These three typemaps are specifically employed by the the
These three typemaps are specifically employed by the
Allegro CL interface generator. SWIG also implements a number of
other typemaps that can be used for generating code in the C/C++
wrappers. You can read about

2
Doc/Manual/Arguments.html
View file

@ -81,7 +81,7 @@ One way to deal with this is to use the
%include "typemaps.i"
%apply double *OUTPUT { double *result };
%inlne %{
%inline %{
extern void add(double a, double b, double *result);
%}
</pre></div>

143
Doc/Manual/CSharp.html
View file

@ -9,35 +9,36 @@
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#csharp_introduction">Introduction</a>
<li><a href="#csharp_differences_java">Differences to the Java module</a>
<li><a href="#CSharp_introduction">Introduction</a>
<li><a href="#CSharp_differences_java">Differences to the Java module</a>
<li><a href="#CSharp_arrays">C# Arrays</a>
<ul>
<li><a href="#CSharp_arrays_swig_library">The SWIG C arrays library</a>
<li><a href="#CSharp_arrays_pinvoke_default_array_marshalling">Managed arrays using P/Invoke default array marshalling</a>
<li><a href="#CSharp_arrays_pinning">Managed arrays using pinning</a>
</ul>
<li><a href="#csharp_exceptions">C# Exceptions</a>
<li><a href="#CSharp_exceptions">C# Exceptions</a>
<ul>
<li><a href="#csharp_exception_example_check_typemap">C# exception example using "check" typemap</a>
<li><a href="#csharp_exception_example_percent_exception">C# exception example using %exception</a>
<li><a href="#csharp_exception_example_exception_specifications">C# exception example using exception specifications</a>
<li><a href="#csharp_custom_application_exception">Custom C# ApplicationException example</a>
<li><a href="#CSharp_exception_example_check_typemap">C# exception example using "check" typemap</a>
<li><a href="#CSharp_exception_example_percent_exception">C# exception example using %exception</a>
<li><a href="#CSharp_exception_example_exception_specifications">C# exception example using exception specifications</a>
<li><a href="#CSharp_custom_application_exception">Custom C# ApplicationException example</a>
</ul>
<li><a href="#csharp_directors">C# Directors</a>
<li><a href="#CSharp_directors">C# Directors</a>
<ul>
<li><a href="#csharp_directors_example">Directors example</a>
<li><a href="#csharp_directors_implementation">Directors implementation</a>
<li><a href="#csharp_director_caveats">Director caveats</a>
<li><a href="#CSharp_directors_example">Directors example</a>
<li><a href="#CSharp_directors_implementation">Directors implementation</a>
<li><a href="#CSharp_director_caveats">Director caveats</a>
</ul>
<li><a href="#csharp_typemap_examples">C# Typemap examples</a>
<li><a href="#CSharp_typemap_examples">C# Typemap examples</a>
<ul>
<li><a href="#csharp_memory_management_member_variables">Memory management when returning references to member variables</a>
<li><a href="#csharp_memory_management_objects">Memory management for objects passed to the C++ layer</a>
<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_partial_classes">Turning wrapped classes into partial classes</a>
<li><a href="#csharp_extending_proxy_class">Extending proxy classes with additional C# code</a>
<li><a href="#CSharp_memory_management_member_variables">Memory management when returning references to member variables</a>
<li><a href="#CSharp_memory_management_objects">Memory management for objects passed to the C++ layer</a>
<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_partial_classes">Turning wrapped classes into partial 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>
</ul>
</div>
@ -45,7 +46,7 @@
<H2><a name="csharp_introduction"></a>18.1 Introduction</H2>
<H2><a name="CSharp_introduction"></a>18.1 Introduction</H2>
<p>
@ -54,7 +55,7 @@ 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/library/default.asp?url=/library/en-us/dv_vstechart/html/vcconMixedDLLLoadingProblem.asp">Mixed DLL Loading Problem</a>.
<a href="http://msdn.microsoft.com/en-us/library/aa290048(VS.71).aspx">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/">Mono</a> and <a href="http://www.dotgnu.org/pnet.html">Portable.NET</a>.
</p>
@ -65,7 +66,7 @@ The <a href="http://msdn.microsoft.com">Microsoft Developer Network (MSDN)</a> h
Monodoc, available from the Mono project, has a very useful section titled <a href="http://www.mono-project.com/Interop_with_Native_Libraries">Interop with native libraries</a>.
</p>
<H2><a name="csharp_differences_java"></a>18.2 Differences to the Java module</H2>
<H2><a name="CSharp_differences_java"></a>18.2 Differences to the Java module</H2>
<p>
@ -102,6 +103,11 @@ namespace com.bloggs.widget {
Note that by default, the generated C# classes have no namespace and the module name is unrelated to namespaces. The module name is just like in Java and is merely used to name some of the generated classes.
</li>
<li>
The <a href="SWIGPlus.html#SWIGPlus_nspace">nspace feature</a> is also supported as described in this general section with a C# example.
Unlike Java which requires the use of the -package option when using the <tt>nspace</tt> feature, the -namespace option is not mandatory for C#.
</li>
<li>
The <tt>-dllimport &lt;name&gt;</tt> commandline option specifies the name of the DLL for the <tt>DllImport</tt> attribute for every PInvoke method. If this commandline option is not given, the <tt>DllImport</tt> DLL name is the same as the module name. This option is useful for when one wants to invoke SWIG multiple times on different modules, yet compile all the resulting code into a single DLL.
</li>
@ -132,7 +138,7 @@ If it was used, it would generate an illegal runtime initialisation via a PInvok
C# doesn't support the notion of throws clauses.
Therefore there is no 'throws' typemap attribute support for adding exception classes to a throws clause.
Likewise there is no need for an equivalent to <tt>%javaexception</tt>.
In fact, throwing C# exceptions works quite differently, see <a href="CSharp.html#csharp_exceptions">C# Exceptions</a> below.
In fact, throwing C# exceptions works quite differently, see <a href="CSharp.html#CSharp_exceptions">C# Exceptions</a> below.
</li>
<li>
@ -201,6 +207,7 @@ jniclassinterfaces -&gt; imclassinterfaces
$javaclassname -&gt; $csclassname
$&amp;javaclassname -&gt; $&amp;csclassname
$*javaclassname -&gt; $*csclassname
$javaclazzname -&gt; $csclazzname
$javainput -&gt; $csinput
$jnicall -&gt; $imcall
</pre></div>
@ -210,10 +217,10 @@ $jnicall -&gt; $imcall
<p>
Unlike the "javain" typemap, the "csin" typemap does not support the 'pgcpp' attribute as the C# module does not have a premature garbage collection prevention parameter.
The "csin" typemap supports additional optional attributes called 'cshin' and 'terminator'.
The 'cshin' attribute should contain the parameter type and name whenever a <a href="Java.html#java_constructor_helper_function">constructor helper function</a> is generated due to the 'pre' or 'post' attributes.
The 'cshin' attribute should contain the parameter type and name whenever a <a href="Java.html#Java_constructor_helper_function">constructor helper function</a> is generated due to the 'pre' or 'post' attributes.
The 'terminator' attribute normally just contains a closing brace for when the 'pre' attribute contains an opening brace, such as when a C# <tt>using</tt> or <tt>fixed</tt> block is started.
Note that 'pre', 'post', 'terminator' and 'cshin' attributes are not used for marshalling the property set.
Please see the <a href="#csharp_date_marshalling">Date marshalling example</a> and <a href="#csharp_date_properties">Date marshalling of properties example</a> for further understanding of these "csin" applicable attributes.
Please see the <a href="#CSharp_date_marshalling">Date marshalling example</a> and <a href="#CSharp_date_properties">Date marshalling of properties example</a> for further understanding of these "csin" applicable attributes.
</p>
</li>
@ -250,7 +257,7 @@ public static extern IntPtr function(string jarg1);
Support for type attributes.
The 'imtype' and 'cstype' typemaps can have an optional <tt>inattributes</tt> and <tt>outattributes</tt> typemap attribute.
The 'imtype' typemap can also have an optional <tt>directorinattributes</tt> and <tt>directoroutattributes</tt>
typemap attribute which attaches to director delegates, an implementation detail of directors, see <a href="#csharp_directors_implementation">directors implementation</a>.
typemap attribute which attaches to director delegates, an implementation detail of directors, see <a href="#CSharp_directors_implementation">directors implementation</a>.
Note that there are C# attributes and typemap attributes, don't get confused between the two!!
The C# attributes specified in these typemap attributes are generated wherever the type is used in the C# wrappers.
These can be used to specify any C# attribute associated with a C/C++ type, but are more typically used for the C# <tt>MarshalAs</tt> attribute.
@ -305,7 +312,7 @@ The <tt>directorinattributes</tt> and <tt>directoroutattributes</tt> typemap att
<li>
<p>
Support for attaching C# attributes to wrapped methods, variables and enum values.
This is done using the <tt>%csattributes</tt> feature, see <a href="Customization.html#features">%feature directives</a>.
This is done using the <tt>%csattributes</tt> feature, see <a href="Customization.html#Customization_features">%feature directives</a>.
Note that C# attributes are attached to proxy classes and enums using the <tt>csattributes</tt> typemap.
For example, imagine we have a custom attribute class, <tt>ThreadSafeAttribute</tt>, for labelling thread safety.
The following SWIG code shows how to attach this C# attribute to some methods and the class declaration itself:
@ -401,7 +408,7 @@ This feature is useful for some obscure cases where SWIG might get the <tt>virtu
</li>
<li>
<a name="csharp_module_directive"></a>
<a name="CSharp_module_directive"></a>
<p>
The name of the intermediary class can be changed from its default, that is, the module name with PINVOKE appended after it.
The module directive attribute <tt>imclassname</tt> is used to achieve this:
@ -436,7 +443,7 @@ if specified, otherwise it is equivalent to the <b>$module</b> special variable.
<p>
<b><tt>$imclassname</tt></b><br>
This special variable expands to the intermediary class name. For C# this is usually the same as '$modulePINVOKE' ('$moduleJNI' for Java),
unless the imclassname attribute is specified in the <a href="CSharp.html#csharp_module_directive">%module directive</a>.
unless the imclassname attribute is specified in the <a href="CSharp.html#CSharp_module_directive">%module directive</a>.
</p>
<p>
@ -505,7 +512,7 @@ In the P/Invoke default marshalling scheme, one needs to designate whether the i
array parameter as input, output, or both. When the function is invoked, the CLR allocates a separate chunk of memory as big as the given managed array,
which is automatically released at the end of the function call. If the array parameter is marked as being input, the content of the managed array is copied
into this buffer when the call is made. Correspondingly, if the array parameter is marked as being output, the contents of the reserved buffer are copied
back into the managed array after the call returns. A pointer to to this buffer
back into the managed array after the call returns. A pointer to this buffer
is passed to the native function.
</p>
@ -716,7 +723,7 @@ public static extern void myArrayCopy(IntPtr jarg1, IntPtr jarg2, int jarg3);
<H2><a name="csharp_exceptions"></a>18.4 C# Exceptions</H2>
<H2><a name="CSharp_exceptions"></a>18.4 C# Exceptions</H2>
<p>
@ -724,7 +731,7 @@ It is possible to throw a C# Exception from C/C++ code.
SWIG already provides the framework for throwing C# exceptions if it is able to detect that a C++ exception could be thrown.
Automatically detecting that a C++ exception could be thrown is only possible when a C++ exception specification is used,
see <a href="SWIGPlus.html#SWIGPlus_exception_specifications">Exception specifications</a>.
The <a href="Customization.html#exception">Exception handling with %exception</a> section details the <tt>%exception</tt> feature.
The <a href="Customization.html#Customization_exception">Exception handling with %exception</a> section details the <tt>%exception</tt> feature.
Customised code for handling exceptions with or without a C++ exception specification is possible and the details follow.
However anyone wishing to do this should be familiar with the contents of the sections referred to above.
</p>
@ -813,7 +820,7 @@ set so should only be used when a C# exception is not created.
</p>
<H3><a name="csharp_exception_example_check_typemap"></a>18.4.1 C# exception example using "check" typemap</H3>
<H3><a name="CSharp_exception_example_check_typemap"></a>18.4.1 C# exception example using "check" typemap</H3>
<p>
@ -995,12 +1002,12 @@ 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"></a>18.4.2 C# exception example using %exception</H3>
<H3><a name="CSharp_exception_example_percent_exception"></a>18.4.2 C# exception example using %exception</H3>
<p>
Let's consider a similar, but more common example that throws a C++ exception from within a wrapped function.
We can use <tt>%exception</tt> as mentioned in <a href="Customization.html#exception">Exception handling with %exception</a>.
We can use <tt>%exception</tt> as mentioned in <a href="Customization.html#Customization_exception">Exception handling with %exception</a>.
</p>
<div class="code">
@ -1060,7 +1067,7 @@ The managed code generated does check for the pending exception as mentioned ear
</pre>
</div>
<H3><a name="csharp_exception_example_exception_specifications"></a>18.4.3 C# exception example using exception specifications</H3>
<H3><a name="CSharp_exception_example_exception_specifications"></a>18.4.3 C# exception example using exception specifications</H3>
<p>
@ -1117,7 +1124,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"></a>18.4.4 Custom C# ApplicationException example</H3>
<H3><a name="CSharp_custom_application_exception"></a>18.4.4 Custom C# ApplicationException example</H3>
<p>
@ -1251,7 +1258,7 @@ try {
</pre>
</div>
<H2><a name="csharp_directors"></a>18.5 C# Directors</H2>
<H2><a name="CSharp_directors"></a>18.5 C# Directors</H2>
<p>
@ -1261,10 +1268,10 @@ Essentially, it enables unmanaged C++ code to call back into managed code for vi
<p>
The following sections provide information on the C# director implementation and contain most of the information required to use the C# directors.
However, the <a href="Java.html#java_directors">Java directors</a> section should also be read in order to gain more insight into directors.
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"></a>18.5.1 Directors example</H3>
<H3><a name="CSharp_directors_example"></a>18.5.1 Directors example</H3>
<p>
@ -1385,7 +1392,7 @@ CSharpDerived - UIntMethod(123)
</pre>
</div>
<H3><a name="csharp_directors_implementation"></a>18.5.2 Directors implementation</H3>
<H3><a name="CSharp_directors_implementation"></a>18.5.2 Directors implementation</H3>
<p>
@ -1571,7 +1578,7 @@ void SwigDirector_Base::BaseBoolMethod(Base const &amp;b, bool flag) {
</pre>
</div>
<H3><a name="csharp_director_caveats"></a>18.5.3 Director caveats</H3>
<H3><a name="CSharp_director_caveats"></a>18.5.3 Director caveats</H3>
<p>
@ -1619,7 +1626,7 @@ 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_typemap_examples"></a>18.6 C# Typemap examples</H2>
<H2><a name="CSharp_typemap_examples"></a>18.6 C# Typemap examples</H2>
This section includes a few examples of typemaps. For more examples, you
@ -1627,12 +1634,12 @@ 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"></a>18.6.1 Memory management when returning references to member variables</H3>
<H3><a name="CSharp_memory_management_member_variables"></a>18.6.1 Memory management when returning references to member variables</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>.
The example is a direct equivalent to this <a href="Java.html#Java_memory_management_objects">Java equivalent</a>.
</p>
<p>
@ -1751,11 +1758,11 @@ public class Bike : IDisposable {
Note the <tt>addReference</tt> call.
</p>
<H3><a name="csharp_memory_management_objects"></a>18.6.2 Memory management for objects passed to the C++ layer</H3>
<H3><a name="CSharp_memory_management_objects"></a>18.6.2 Memory management for objects passed to the C++ layer</H3>
<p>
The example is a direct equivalent to this <a href="Java.html#java_memory_management_objects">Java equivalent</a>.
The example is a direct equivalent to this <a href="Java.html#Java_memory_management_objects">Java equivalent</a>.
Managing memory can be tricky when using C++ and C# proxy classes.
The previous example shows one such case and this example looks at memory management for a class passed to a C++ method which expects the object to remain in scope
after the function has returned. Consider the following two C++ classes:
@ -1870,14 +1877,14 @@ The 'cscode' typemap simply adds in the specified code into the C# proxy class.
</div>
<H3><a name="csharp_date_marshalling"></a>18.6.3 Date marshalling using the csin typemap and associated attributes</H3>
<H3><a name="CSharp_date_marshalling"></a>18.6.3 Date marshalling using the csin typemap and associated attributes</H3>
<p>
The <a href="Java.html#nan_exception_typemap">NaN Exception example</a> is a simple example of the "javain" typemap and its 'pre' attribute.
The <a href="Java.html#Java_nan_exception_typemap">NaN Exception example</a> is a simple example of the "javain" typemap and its 'pre' attribute.
This example demonstrates how a C++ date class, say <tt>CDate</tt>, can be mapped onto the standard .NET date class,
<tt>System.DateTime</tt> by using the 'pre', 'post' and 'pgcppname' attributes of the "csin" typemap (the C# equivalent to the "javain" typemap).
The example is an equivalent to the <a href="Java.html#java_date_marshalling">Java Date marshalling example</a>.
The example is an equivalent to the <a href="Java.html#Java_date_marshalling">Java Date marshalling example</a>.
The idea is that the <tt>System.DateTime</tt> is used wherever the C++ API uses a <tt>CDate</tt>.
Let's assume the code being wrapped is as follows:
</p>
@ -2154,7 +2161,7 @@ public class example {
</pre>
</div>
<H3><a name="csharp_date_properties"></a>18.6.4 A date example demonstrating marshalling of C# properties</H3>
<H3><a name="CSharp_date_properties"></a>18.6.4 A date example demonstrating marshalling of C# properties</H3>
<p>
@ -2255,7 +2262,7 @@ Some points to note:
</ul>
<H3><a name="csharp_partial_classes"></a>18.6.5 Turning wrapped classes into partial classes</H3>
<H3><a name="CSharp_partial_classes"></a>18.6.5 Turning wrapped classes into partial classes</H3>
<p>
@ -2355,7 +2362,7 @@ 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"></a>18.6.6 Extending proxy classes with additional C# code</H3>
<H3><a name="CSharp_extending_proxy_class"></a>18.6.6 Extending proxy classes with additional C# code</H3>
<p>
@ -2394,6 +2401,38 @@ public class ExtendMe : IDisposable {
</pre>
</div>
<H3><a name="CSharp_enum_underlying_type"></a>18.6.7 Underlying type for enums</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.
Here is an example:
</p>
<div class="code">
<pre>
%typemap(csbase) BigNumbers "uint"
%inline %{
enum BigNumbers { big=0x80000000, bigger };
%}
</pre>
</div>
<p>
The generated enum will then use the given underlying type and compile correctly:
</p>
<div class="code">
<pre>
public enum BigNumbers : uint {
big = 0x80000000,
bigger
}
</pre>
</div>
</body>
</html>

23
Doc/Manual/Chicken.html
View file

@ -35,7 +35,7 @@
<li><a href="#Chicken_nn16">Typemaps</a>
<li><a href="#Chicken_nn17">Pointers</a>
<ul>
<li><a href="#collection">Garbage collection</a>
<li><a href="#Chicken_collection">Garbage collection</a>
</ul>
<li><a href="#Chicken_nn18">Unsupported features and known problems</a>
<ul>
@ -80,14 +80,13 @@
relies on some recent additions to CHICKEN, which are only
present in releases of CHICKEN with version number
<strong>greater than or equal to 1.89</strong>.
To use a chicken version between 1.40 and 1.89, see the <a href="#collection">Garbage collection</a>
To use a chicken version between 1.40 and 1.89, see the <a href="#Chicken_collection">Garbage collection</a>
section below.
</p>
<p>
You may want to look at any of the examples in Examples/chicken/
or Examples/GIFPlot/Chicken for the basic steps to run SWIG
CHICKEN.
directory for the basic steps to run SWIG CHICKEN.
</p>
<H3><a name="Chicken_nn3"></a>19.1.1 Running SWIG in C mode</H3>
@ -226,7 +225,7 @@
a function that must be called, the constant will appear as a
scheme variable. This causes the generated .scm file to just contain the code
<tt>(set! MYCONSTANT1 (MYCONSTANT1))</tt>. See
<a href="Customization.html#features">Features and the %feature directive</a>
<a href="Customization.html#Customization_features">Features and the %feature directive</a>
for info on how to apply the %feature.
</p>
@ -254,7 +253,7 @@
<p>The SWIG chicken module has support for exceptions thrown from
C or C++ code to be caught in scheme.
See <a href="Customization.html#exception">Exception handling with %exception</a>
See <a href="Customization.html#Customization_exception">Exception handling with %exception</a>
for more information about declaring exceptions in the interface file.
</p>
@ -263,7 +262,7 @@
inside the %exception blocks. <code>SWIG_exception</code> will throw a list consisting of the code
(as an integer) and the message. Both of these will throw an exception using <code>(abort)</code>,
which can be handled by <code>(handle-exceptions)</code>. See
<a href="http://www.call-with-current-continuation.org/manual/Exceptions.html#Exceptions">Chicken manual on Exceptions</a>
the Chicken manual on Exceptions
and <a href="http://srfi.schemers.org/srfi-12/srfi-12.html">SFRI-12</a>. Since the exception values are thrown
directly, if <code>(condition-case)</code> is used to catch an exception the exception will come through in the <code>val ()</code> case.
</p>
@ -417,8 +416,8 @@ $ csc -sv modname.scm modname_wrap.c modname_impl.c -o modname.so
</div>
<p>This library can then be loaded by scheme code with the <code>(require 'modname)</code> function.
See <a href="http://www.call-with-current-continuation.org/manual/Loading-extension-libraries.html">
Loading-extension-libraries</a> in the eval unit inside the CHICKEN manual for more information.</p>
See the
Loading-extension-libraries in the eval unit inside the CHICKEN manual for more information.</p>
<p>Another alternative is to run SWIG normally and create a scheme file that contains <code>(declare (uses <i>modname</i>))</code>
and then compile that file into the shared library as well. For example, inside the <tt>mod_load.scm</tt> file,</p>
@ -520,7 +519,7 @@ all the modules.</p>
type. flags is either zero or SWIG_POINTER_DISOWN (see below).
</p>
<H3><a name="collection"></a>19.6.1 Garbage collection</H3>
<H3><a name="Chicken_collection"></a>19.6.1 Garbage collection</H3>
<p>If the owner flag passed to <code>SWIG_NewPointerObj</code> is 1, <code>NewPointerObj</code> will add a
@ -531,12 +530,12 @@ all the modules.</p>
be garbage collected, SWIG will automatically set the owner flag to 1. For other functions,
the <code>%newobject</code> directive must be specified for functions whose return values
should be garbage collected. See
<a href="Customization.html#ownership">Object ownership and %newobject</a> for more information.
<a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for more information.
</p>
<p>In situations where a C or C++ function will assume ownership of a pointer, and thus
chicken should no longer garbage collect it, SWIG provides the <code>DISOWN</code> input typemap.
After applying this typemap (see the <a href="Typemaps.html">Typemaps chapter</a> for more information on how to apply typemaps),
After applying this typemap (see the <a href="Typemaps.html#Typemaps">Typemaps chapter</a> for more information on how to apply typemaps),
any pointer that gets passed in will no longer be garbage collected.
An object is disowned by passing the <code>SWIG_POINTER_DISOWN</code> flag to <code>SWIG_ConvertPtr</code>.
<b>Warning:</b> Since the lifetime of the object is now controlled by the underlying code, the object might

395
Doc/Manual/Contents.html
View file

@ -15,13 +15,12 @@
<div class="sectiontoc">
<ul>
<li><a href="Preface.html#Preface_nn2">Introduction</a>
<li><a href="Preface.html#Preface_nn3">Special Introduction for Version 1.3</a>
<li><a href="Preface.html#Preface_nn4">SWIG Versions</a>
<li><a href="Preface.html#Preface_nn5">SWIG resources</a>
<li><a href="Preface.html#Preface_nn6">Prerequisites</a>
<li><a href="Preface.html#Preface_nn7">Organization of this manual</a>
<li><a href="Preface.html#Preface_nn8">How to avoid reading the manual</a>
<li><a href="Preface.html#Preface_nn9">Backwards Compatibility</a>
<li><a href="Preface.html#Preface_nn9">Backwards compatibility</a>
<li><a href="Preface.html#Preface_nn10">Credits</a>
<li><a href="Preface.html#Preface_nn11">Bug reports</a>
</ul>
@ -122,7 +121,7 @@
<li><a href="SWIG.html#SWIG_nn2">Running SWIG</a>
<ul>
<li><a href="SWIG.html#SWIG_nn3">Input format</a>
<li><a href="SWIG.html#output">SWIG Output</a>
<li><a href="SWIG.html#SWIG_output">SWIG Output</a>
<li><a href="SWIG.html#SWIG_nn5">Comments</a>
<li><a href="SWIG.html#SWIG_nn6">C Preprocessor</a>
<li><a href="SWIG.html#SWIG_nn7">SWIG Directives</a>
@ -223,21 +222,24 @@
<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#ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
<li><a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</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_class_extension">Class extension</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn30">Templates</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn31">Namespaces</a>
<li><a href="SWIGPlus.html#SWIGPlus_namespaces">Namespaces</a>
<ul>
<li><a href="SWIGPlus.html#SWIGPlus_nspace">The nspace feature for namespaces</a>
</ul>
<li><a href="SWIGPlus.html#SWIGPlus_renaming_templated_types_namespaces">Renaming templated types in namespaces</a>
<li><a href="SWIGPlus.html#SWIGPlus_exception_specifications">Exception specifications</a>
<li><a href="SWIGPlus.html#SWIGPlus_catches">Exception handling with %catches</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn33">Pointers to Members</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn34">Smart pointers and operator-&gt;()</a>
<li><a href="SWIGPlus.html#SWIGPlus_smart_pointers">Smart pointers and operator-&gt;()</a>
<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_nn37">A brief rant about const-correctness</a>
<li><a href="SWIGPlus.html#SWIGPlus_const">A brief rant about const-correctness</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn42">Where to go for more information</a>
</ul>
</div>
@ -285,9 +287,10 @@
</ul>
<li><a href="Library.html#Library_stl_cpp_library">STL/C++ Library</a>
<ul>
<li><a href="Library.html#Library_nn14">std_string.i</a>
<li><a href="Library.html#Library_nn15">std_vector.i</a>
<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_nn16">Utility Libraries</a>
<ul>
@ -333,6 +336,7 @@
<li><a href="Typemaps.html#Typemaps_nn6">Reusing typemaps</a>
<li><a href="Typemaps.html#Typemaps_nn7">What can be done with typemaps?</a>
<li><a href="Typemaps.html#Typemaps_nn8">What can't be done with typemaps?</a>
<li><a href="Typemaps.html#Typemaps_aspects">Similarities to Aspect Oriented Programming</a>
<li><a href="Typemaps.html#Typemaps_nn9">The rest of this chapter</a>
</ul>
<li><a href="Typemaps.html#Typemaps_nn10">Typemap specifications</a>
@ -346,10 +350,10 @@
<li><a href="Typemaps.html#Typemaps_pattern_matching">Pattern matching rules</a>
<ul>
<li><a href="Typemaps.html#Typemaps_nn17">Basic matching rules</a>
<li><a href="Typemaps.html#Typemaps_typedef_reductions">Typedef reductions</a>
<li><a href="Typemaps.html#Typemaps_nn19">Default typemaps</a>
<li><a href="Typemaps.html#Typemaps_mixed_default">Mixed default typemaps</a>
<li><a href="Typemaps.html#Typemaps_nn20">Multi-arguments typemaps</a>
<li><a href="Typemaps.html#Typemaps_typedef_reductions">Typedef reductions matching</a>
<li><a href="Typemaps.html#Typemaps_nn19">Default typemap matching rules</a>
<li><a href="Typemaps.html#Typemaps_multi_argument_typemaps_patterns">Multi-arguments typemaps</a>
<li><a href="Typemaps.html#Typemaps_matching_template_comparison">Matching rules compared to C++ templates</a>
<li><a href="Typemaps.html#Typemaps_debugging_search">Debugging typemap pattern matching</a>
</ul>
<li><a href="Typemaps.html#Typemaps_nn21">Code generation rules</a>
@ -387,14 +391,18 @@
<li><a href="Typemaps.html#Typemaps_nn43">Typemaps for multiple target languages</a>
<li><a href="Typemaps.html#Typemaps_optimal">Optimal code generation when returning by value</a>
<li><a href="Typemaps.html#Typemaps_multi_argument_typemaps">Multi-argument typemaps</a>
<li><a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>
<li><a href="Typemaps.html#Typemaps_fragments">Typemap fragments</a>
<ul>
<li><a href="Typemaps.html#Typemaps_fragment_type_specialization">Fragment type specialization</a>
<li><a href="Typemaps.html#Typemaps_automatic_specialization">Fragments and automatic typemap specialization</a>
</ul>
<li><a href="Typemaps.html#Typemaps_runtime_type_checker">The run-time type checker</a>
<ul>
<li><a href="Typemaps.html#Typemaps_nn45">Implementation</a>
<li><a href="Typemaps.html#Typemaps_runtime_type_checker_usage">Usage</a>
</ul>
<li><a href="Typemaps.html#Typemaps_overloading">Typemaps and overloading</a>
<li><a href="Typemaps.html#Typemaps_nn48">More about <tt>%apply</tt> and <tt>%clear</tt></a>
<li><a href="Typemaps.html#Typemaps_nn49">Reducing wrapper code size</a>
<li><a href="Typemaps.html#Typemaps_nn47">Passing data between typemaps</a>
<li><a href="Typemaps.html#Typemaps_nn52">C++ "this" pointer</a>
<li><a href="Typemaps.html#Typemaps_nn51">Where to go for more information?</a>
@ -407,7 +415,7 @@
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Customization.html#exception">Exception handling with %exception</a>
<li><a href="Customization.html#Customization_exception">Exception handling with %exception</a>
<ul>
<li><a href="Customization.html#Customization_nn3">Handling exceptions in C code</a>
<li><a href="Customization.html#Customization_nn4">Exception handling with longjmp()</a>
@ -417,14 +425,14 @@
<li><a href="Customization.html#Customization_exception_special_variables">Special variables for %exception</a>
<li><a href="Customization.html#Customization_nn7">Using The SWIG exception library</a>
</ul>
<li><a href="Customization.html#ownership">Object ownership and %newobject</a>
<li><a href="Customization.html#features">Features and the %feature directive</a>
<li><a href="Customization.html#Customization_ownership">Object ownership and %newobject</a>
<li><a href="Customization.html#Customization_features">Features and the %feature directive</a>
<ul>
<li><a href="Customization.html#Customization_feature_attributes">Feature attributes</a>
<li><a href="Customization.html#Customization_feature_flags">Feature flags</a>
<li><a href="Customization.html#Customization_clearing_features">Clearing features</a>
<li><a href="Customization.html#Customization_features_default_args">Features and default arguments</a>
<li><a href="Customization.html#features_example">Feature example</a>
<li><a href="Customization.html#Customization_features_example">Feature example</a>
</ul>
</ul>
</div>
@ -497,7 +505,7 @@
<li><a href="Modules.html#Modules_introduction">Modules Introduction</a>
<li><a href="Modules.html#Modules_nn1">Basics</a>
<li><a href="Modules.html#Modules_nn2">The SWIG runtime code</a>
<li><a href="Modules.html#external_run_time">External access to the runtime</a>
<li><a href="Modules.html#Modules_external_run_time">External access to the runtime</a>
<li><a href="Modules.html#Modules_nn4">A word of caution about static libraries</a>
<li><a href="Modules.html#Modules_nn5">References</a>
<li><a href="Modules.html#Modules_nn6">Reducing the wrapper file size</a>
@ -620,35 +628,36 @@
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="CSharp.html#csharp_introduction">Introduction</a>
<li><a href="CSharp.html#csharp_differences_java">Differences to the Java module</a>
<li><a href="CSharp.html#CSharp_introduction">Introduction</a>
<li><a href="CSharp.html#CSharp_differences_java">Differences to the Java module</a>
<li><a href="CSharp.html#CSharp_arrays">C# Arrays</a>
<ul>
<li><a href="CSharp.html#CSharp_arrays_swig_library">The SWIG C arrays library</a>
<li><a href="CSharp.html#CSharp_arrays_pinvoke_default_array_marshalling">Managed arrays using P/Invoke default array marshalling</a>
<li><a href="CSharp.html#CSharp_arrays_pinning">Managed arrays using pinning</a>
</ul>
<li><a href="CSharp.html#csharp_exceptions">C# Exceptions</a>
<li><a href="CSharp.html#CSharp_exceptions">C# Exceptions</a>
<ul>
<li><a href="CSharp.html#csharp_exception_example_check_typemap">C# exception example using "check" typemap</a>
<li><a href="CSharp.html#csharp_exception_example_percent_exception">C# exception example using %exception</a>
<li><a href="CSharp.html#csharp_exception_example_exception_specifications">C# exception example using exception specifications</a>
<li><a href="CSharp.html#csharp_custom_application_exception">Custom C# ApplicationException example</a>
<li><a href="CSharp.html#CSharp_exception_example_check_typemap">C# exception example using "check" typemap</a>
<li><a href="CSharp.html#CSharp_exception_example_percent_exception">C# exception example using %exception</a>
<li><a href="CSharp.html#CSharp_exception_example_exception_specifications">C# exception example using exception specifications</a>
<li><a href="CSharp.html#CSharp_custom_application_exception">Custom C# ApplicationException example</a>
</ul>
<li><a href="CSharp.html#csharp_directors">C# Directors</a>
<li><a href="CSharp.html#CSharp_directors">C# Directors</a>
<ul>
<li><a href="CSharp.html#csharp_directors_example">Directors example</a>
<li><a href="CSharp.html#csharp_directors_implementation">Directors implementation</a>
<li><a href="CSharp.html#csharp_director_caveats">Director caveats</a>
<li><a href="CSharp.html#CSharp_directors_example">Directors example</a>
<li><a href="CSharp.html#CSharp_directors_implementation">Directors implementation</a>
<li><a href="CSharp.html#CSharp_director_caveats">Director caveats</a>
</ul>
<li><a href="CSharp.html#csharp_typemap_examples">C# Typemap examples</a>
<li><a href="CSharp.html#CSharp_typemap_examples">C# Typemap examples</a>
<ul>
<li><a href="CSharp.html#csharp_memory_management_member_variables">Memory management when returning references to member variables</a>
<li><a href="CSharp.html#csharp_memory_management_objects">Memory management for objects passed to the C++ layer</a>
<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_partial_classes">Turning wrapped classes into partial 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_memory_management_member_variables">Memory management when returning references to member variables</a>
<li><a href="CSharp.html#CSharp_memory_management_objects">Memory management for objects passed to the C++ layer</a>
<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_partial_classes">Turning wrapped classes into partial 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>
</ul>
</div>
@ -682,7 +691,7 @@
<li><a href="Chicken.html#Chicken_nn16">Typemaps</a>
<li><a href="Chicken.html#Chicken_nn17">Pointers</a>
<ul>
<li><a href="Chicken.html#collection">Garbage collection</a>
<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>
@ -692,7 +701,36 @@
</div>
<!-- INDEX -->
<h3><a href="Guile.html#Guile">20 SWIG and Guile</a></h3>
<h3><a href="Go.html#Go">20 SWIG and Go</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Go.html#Go_overview">Overview</a>
<li><a href="Go.html#Go_running_swig">Running SWIG with Go</a>
<ul>
<li><a href="Go.html#Go_commandline">Additional Commandline Options</a>
<li><a href="Go.html#Go_outputs">Go Output Files</a>
</ul>
<li><a href="Go.html#Go_basic_tour">A tour of basic C/C++ wrapping</a>
<ul>
<li><a href="Go.html#Go_package">Go Package Name</a>
<li><a href="Go.html#Go_names">Go Names</a>
<li><a href="Go.html#Go_constants">Go Constants</a>
<li><a href="Go.html#Go_enumerations">Go Enumerations</a>
<li><a href="Go.html#Go_classes">Go Classes</a>
<ul>
<li><a href="Go.html#Go_class_inheritance">Go Class Inheritance</a>
</ul>
<li><a href="Go.html#Go_templates">Go Templates</a>
<li><a href="Go.html#Go_director_classes">Go Director Classes</a>
<li><a href="Go.html#Go_primitive_type_mappings">Default Go primitive type mappings</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Guile.html#Guile">21 SWIG and Guile</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -727,149 +765,149 @@
</div>
<!-- INDEX -->
<h3><a href="Java.html#Java">21 SWIG and Java</a></h3>
<h3><a href="Java.html#Java">22 SWIG and Java</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Java.html#java_overview">Overview</a>
<li><a href="Java.html#java_preliminaries">Preliminaries</a>
<li><a href="Java.html#Java_overview">Overview</a>
<li><a href="Java.html#Java_preliminaries">Preliminaries</a>
<ul>
<li><a href="Java.html#running_swig">Running SWIG</a>
<li><a href="Java.html#java_commandline">Additional Commandline Options</a>
<li><a href="Java.html#getting_right_headers">Getting the right header files</a>
<li><a href="Java.html#compiling_dynamic">Compiling a dynamic module</a>
<li><a href="Java.html#using_module">Using your module</a>
<li><a href="Java.html#dynamic_linking_problems">Dynamic linking problems</a>
<li><a href="Java.html#compilation_problems_cpp">Compilation problems and compiling with C++</a>
<li><a href="Java.html#building_windows">Building on Windows</a>
<li><a href="Java.html#Java_running_swig">Running SWIG</a>
<li><a href="Java.html#Java_commandline">Additional Commandline Options</a>
<li><a href="Java.html#Java_getting_right_headers">Getting the right header files</a>
<li><a href="Java.html#Java_compiling_dynamic">Compiling a dynamic module</a>
<li><a href="Java.html#Java_using_module">Using your module</a>
<li><a href="Java.html#Java_dynamic_linking_problems">Dynamic linking problems</a>
<li><a href="Java.html#Java_compilation_problems_cpp">Compilation problems and compiling with C++</a>
<li><a href="Java.html#Java_building_windows">Building on Windows</a>
<ul>
<li><a href="Java.html#visual_studio">Running SWIG from Visual Studio</a>
<li><a href="Java.html#nmake">Using NMAKE</a>
<li><a href="Java.html#Java_visual_studio">Running SWIG from Visual Studio</a>
<li><a href="Java.html#Java_nmake">Using NMAKE</a>
</ul>
</ul>
<li><a href="Java.html#java_basic_tour">A tour of basic C/C++ wrapping</a>
<li><a href="Java.html#Java_basic_tour">A tour of basic C/C++ wrapping</a>
<ul>
<li><a href="Java.html#module_packages_classes">Modules, packages and generated Java classes</a>
<li><a href="Java.html#functions">Functions</a>
<li><a href="Java.html#global_variables">Global variables</a>
<li><a href="Java.html#constants">Constants</a>
<li><a href="Java.html#enumerations">Enumerations</a>
<li><a href="Java.html#Java_module_packages_classes">Modules, packages and generated Java classes</a>
<li><a href="Java.html#Java_functions">Functions</a>
<li><a href="Java.html#Java_global_variables">Global variables</a>
<li><a href="Java.html#Java_constants">Constants</a>
<li><a href="Java.html#Java_enumerations">Enumerations</a>
<ul>
<li><a href="Java.html#anonymous_enums">Anonymous enums</a>
<li><a href="Java.html#typesafe_enums">Typesafe enums</a>
<li><a href="Java.html#proper_enums">Proper Java enums</a>
<li><a href="Java.html#typeunsafe_enums">Type unsafe enums</a>
<li><a href="Java.html#simple_enums">Simple enums</a>
<li><a href="Java.html#Java_anonymous_enums">Anonymous enums</a>
<li><a href="Java.html#Java_typesafe_enums">Typesafe enums</a>
<li><a href="Java.html#Java_proper_enums">Proper Java enums</a>
<li><a href="Java.html#Java_typeunsafe_enums">Type unsafe enums</a>
<li><a href="Java.html#Java_simple_enums">Simple enums</a>
</ul>
<li><a href="Java.html#pointers">Pointers</a>
<li><a href="Java.html#structures">Structures</a>
<li><a href="Java.html#classes">C++ classes</a>
<li><a href="Java.html#inheritance">C++ inheritance</a>
<li><a href="Java.html#pointers_refs_arrays">Pointers, references, arrays and pass by value</a>
<li><a href="Java.html#Java_pointers">Pointers</a>
<li><a href="Java.html#Java_structures">Structures</a>
<li><a href="Java.html#Java_classes">C++ classes</a>
<li><a href="Java.html#Java_inheritance">C++ inheritance</a>
<li><a href="Java.html#Java_pointers_refs_arrays">Pointers, references, arrays and pass by value</a>
<ul>
<li><a href="Java.html#null_pointers">Null pointers</a>
<li><a href="Java.html#Java_null_pointers">Null pointers</a>
</ul>
<li><a href="Java.html#overloaded_functions">C++ overloaded functions</a>
<li><a href="Java.html#java_default_arguments">C++ default arguments</a>
<li><a href="Java.html#namespaces">C++ namespaces</a>
<li><a href="Java.html#templates">C++ templates</a>
<li><a href="Java.html#smart_pointers">C++ Smart Pointers</a>
<li><a href="Java.html#Java_overloaded_functions">C++ overloaded functions</a>
<li><a href="Java.html#Java_default_arguments">C++ default arguments</a>
<li><a href="Java.html#Java_namespaces">C++ namespaces</a>
<li><a href="Java.html#Java_templates">C++ templates</a>
<li><a href="Java.html#Java_smart_pointers">C++ Smart Pointers</a>
</ul>
<li><a href="Java.html#further_details">Further details on the generated Java classes</a>
<li><a href="Java.html#Java_further_details">Further details on the generated Java classes</a>
<ul>
<li><a href="Java.html#imclass">The intermediary JNI class</a>
<li><a href="Java.html#Java_imclass">The intermediary JNI class</a>
<ul>
<li><a href="Java.html#imclass_pragmas">The intermediary JNI class pragmas</a>
<li><a href="Java.html#Java_imclass_pragmas">The intermediary JNI class pragmas</a>
</ul>
<li><a href="Java.html#java_module_class">The Java module class</a>
<li><a href="Java.html#Java_module_class">The Java module class</a>
<ul>
<li><a href="Java.html#module_class_pragmas">The Java module class pragmas</a>
<li><a href="Java.html#Java_module_class_pragmas">The Java module class pragmas</a>
</ul>
<li><a href="Java.html#java_proxy_classes">Java proxy classes</a>
<li><a href="Java.html#Java_proxy_classes">Java proxy classes</a>
<ul>
<li><a href="Java.html#memory_management">Memory management</a>
<li><a href="Java.html#inheritance_mirroring">Inheritance</a>
<li><a href="Java.html#proxy_classes_gc">Proxy classes and garbage collection</a>
<li><a href="Java.html#java_pgcpp">The premature garbage collection prevention parameter for proxy class marshalling</a>
<li><a href="Java.html#java_multithread_libraries">Single threaded applications and thread safety</a>
<li><a href="Java.html#Java_memory_management">Memory management</a>
<li><a href="Java.html#Java_inheritance_mirroring">Inheritance</a>
<li><a href="Java.html#Java_proxy_classes_gc">Proxy classes and garbage collection</a>
<li><a href="Java.html#Java_pgcpp">The premature garbage collection prevention parameter for proxy class marshalling</a>
<li><a href="Java.html#Java_multithread_libraries">Single threaded applications and thread safety</a>
</ul>
<li><a href="Java.html#type_wrapper_classes">Type wrapper classes</a>
<li><a href="Java.html#enum_classes">Enum classes</a>
<li><a href="Java.html#Java_type_wrapper_classes">Type wrapper classes</a>
<li><a href="Java.html#Java_enum_classes">Enum classes</a>
<ul>
<li><a href="Java.html#typesafe_enums_classes">Typesafe enum classes</a>
<li><a href="Java.html#proper_enums_classes">Proper Java enum classes</a>
<li><a href="Java.html#typeunsafe_enums_classes">Type unsafe enum classes</a>
<li><a href="Java.html#Java_typesafe_enums_classes">Typesafe enum classes</a>
<li><a href="Java.html#Java_proper_enums_classes">Proper Java enum classes</a>
<li><a href="Java.html#Java_typeunsafe_enums_classes">Type unsafe enum classes</a>
</ul>
</ul>
<li><a href="Java.html#java_directors">Cross language polymorphism using directors</a>
<li><a href="Java.html#Java_directors">Cross language polymorphism using directors</a>
<ul>
<li><a href="Java.html#java_enabling_directors">Enabling directors</a>
<li><a href="Java.html#java_directors_classes">Director classes</a>
<li><a href="Java.html#java_directors_overhead">Overhead and code bloat</a>
<li><a href="Java.html#java_directors_example">Simple directors example</a>
<li><a href="Java.html#java_directors_threading">Director threading issues</a>
<li><a href="Java.html#Java_enabling_directors">Enabling directors</a>
<li><a href="Java.html#Java_directors_classes">Director classes</a>
<li><a href="Java.html#Java_directors_overhead">Overhead and code bloat</a>
<li><a href="Java.html#Java_directors_example">Simple directors example</a>
<li><a href="Java.html#Java_directors_threading">Director threading issues</a>
</ul>
<li><a href="Java.html#java_allprotected">Accessing protected members</a>
<li><a href="Java.html#common_customization">Common customization features</a>
<li><a href="Java.html#Java_allprotected">Accessing protected members</a>
<li><a href="Java.html#Java_common_customization">Common customization features</a>
<ul>
<li><a href="Java.html#helper_functions">C/C++ helper functions</a>
<li><a href="Java.html#class_extension">Class extension with %extend</a>
<li><a href="Java.html#exception_handling">Exception handling with %exception and %javaexception</a>
<li><a href="Java.html#method_access">Method access with %javamethodmodifiers</a>
<li><a href="Java.html#Java_helper_functions">C/C++ helper functions</a>
<li><a href="Java.html#Java_class_extension">Class extension with %extend</a>
<li><a href="Java.html#Java_exception_handling">Exception handling with %exception and %javaexception</a>
<li><a href="Java.html#Java_method_access">Method access with %javamethodmodifiers</a>
</ul>
<li><a href="Java.html#tips_techniques">Tips and techniques</a>
<li><a href="Java.html#Java_tips_techniques">Tips and techniques</a>
<ul>
<li><a href="Java.html#input_output_parameters">Input and output parameters using primitive pointers and references</a>
<li><a href="Java.html#simple_pointers">Simple pointers</a>
<li><a href="Java.html#c_arrays">Wrapping C arrays with Java arrays</a>
<li><a href="Java.html#unbounded_c_arrays">Unbounded C Arrays</a>
<li><a href="Java.html#java_heap_allocations">Overriding new and delete to allocate from Java heap</a>
<li><a href="Java.html#Java_input_output_parameters">Input and output parameters using primitive pointers and references</a>
<li><a href="Java.html#Java_simple_pointers">Simple pointers</a>
<li><a href="Java.html#Java_c_arrays">Wrapping C arrays with Java arrays</a>
<li><a href="Java.html#Java_unbounded_c_arrays">Unbounded C Arrays</a>
<li><a href="Java.html#Java_heap_allocations">Overriding new and delete to allocate from Java heap</a>
</ul>
<li><a href="Java.html#java_typemaps">Java typemaps</a>
<li><a href="Java.html#Java_typemaps">Java typemaps</a>
<ul>
<li><a href="Java.html#default_primitive_type_mappings">Default primitive type mappings</a>
<li><a href="Java.html#Java_default_primitive_type_mappings">Default primitive type mappings</a>
<li><a href="Java.html#Java_default_non_primitive_typemaps">Default typemaps for non-primitive types</a>
<li><a href="Java.html#jvm64">Sixty four bit JVMs</a>
<li><a href="Java.html#what_is_typemap">What is a typemap?</a>
<li><a href="Java.html#typemaps_c_to_java_types">Typemaps for mapping C/C++ types to Java types</a>
<li><a href="Java.html#typemap_attributes">Java typemap attributes</a>
<li><a href="Java.html#special_variables">Java special variables</a>
<li><a href="Java.html#typemaps_for_c_and_cpp">Typemaps for both C and C++ compilation</a>
<li><a href="Java.html#java_code_typemaps">Java code typemaps</a>
<li><a href="Java.html#java_directors_typemaps">Director specific typemaps</a>
<li><a href="Java.html#Java_jvm64">Sixty four bit JVMs</a>
<li><a href="Java.html#Java_what_is_typemap">What is a typemap?</a>
<li><a href="Java.html#Java_typemaps_c_to_java_types">Typemaps for mapping C/C++ types to Java types</a>
<li><a href="Java.html#Java_typemap_attributes">Java typemap attributes</a>
<li><a href="Java.html#Java_special_variables">Java special variables</a>
<li><a href="Java.html#Java_typemaps_for_c_and_cpp">Typemaps for both C and C++ compilation</a>
<li><a href="Java.html#Java_code_typemaps">Java code typemaps</a>
<li><a href="Java.html#Java_directors_typemaps">Director specific typemaps</a>
</ul>
<li><a href="Java.html#typemap_examples">Typemap Examples</a>
<li><a href="Java.html#Java_typemap_examples">Typemap Examples</a>
<ul>
<li><a href="Java.html#simpler_enum_classes">Simpler Java enums for enums without initializers</a>
<li><a href="Java.html#exception_typemap">Handling C++ exception specifications as Java exceptions</a>
<li><a href="Java.html#nan_exception_typemap">NaN Exception - exception handling for a particular type</a>
<li><a href="Java.html#converting_java_string_arrays">Converting Java String arrays to char ** </a>
<li><a href="Java.html#expanding_java_object">Expanding a Java object to multiple arguments</a>
<li><a href="Java.html#using_typemaps_return_arguments">Using typemaps to return arguments</a>
<li><a href="Java.html#adding_downcasts">Adding Java downcasts to polymorphic return types</a>
<li><a href="Java.html#adding_equals_method">Adding an equals method to the Java classes</a>
<li><a href="Java.html#void_pointers">Void pointers and a common Java base class</a>
<li><a href="Java.html#struct_pointer_pointer">Struct pointer to pointer</a>
<li><a href="Java.html#java_memory_management_member_variables">Memory management when returning references to member variables</a>
<li><a href="Java.html#java_memory_management_objects">Memory management for objects passed to the C++ layer</a>
<li><a href="Java.html#java_date_marshalling">Date marshalling using the javain typemap and associated attributes</a>
<li><a href="Java.html#Java_simpler_enum_classes">Simpler Java enums for enums without initializers</a>
<li><a href="Java.html#Java_exception_typemap">Handling C++ exception specifications as Java exceptions</a>
<li><a href="Java.html#Java_nan_exception_typemap">NaN Exception - exception handling for a particular type</a>
<li><a href="Java.html#Java_converting_java_string_arrays">Converting Java String arrays to char ** </a>
<li><a href="Java.html#Java_expanding_java_object">Expanding a Java object to multiple arguments</a>
<li><a href="Java.html#Java_using_typemaps_return_arguments">Using typemaps to return arguments</a>
<li><a href="Java.html#Java_adding_downcasts">Adding Java downcasts to polymorphic return types</a>
<li><a href="Java.html#Java_adding_equals_method">Adding an equals method to the Java classes</a>
<li><a href="Java.html#Java_void_pointers">Void pointers and a common Java base class</a>
<li><a href="Java.html#Java_struct_pointer_pointer">Struct pointer to pointer</a>
<li><a href="Java.html#Java_memory_management_member_variables">Memory management when returning references to member variables</a>
<li><a href="Java.html#Java_memory_management_objects">Memory management for objects passed to the C++ layer</a>
<li><a href="Java.html#Java_date_marshalling">Date marshalling using the javain typemap and associated attributes</a>
</ul>
<li><a href="Java.html#java_directors_faq">Living with Java Directors</a>
<li><a href="Java.html#odds_ends">Odds and ends</a>
<li><a href="Java.html#Java_directors_faq">Living with Java Directors</a>
<li><a href="Java.html#Java_odds_ends">Odds and ends</a>
<ul>
<li><a href="Java.html#javadoc_comments">JavaDoc comments</a>
<li><a href="Java.html#functional_interface">Functional interface without proxy classes</a>
<li><a href="Java.html#using_own_jni_functions">Using your own JNI functions</a>
<li><a href="Java.html#performance">Performance concerns and hints</a>
<li><a href="Java.html#java_debugging">Debugging</a>
<li><a href="Java.html#Java_javadoc_comments">JavaDoc comments</a>
<li><a href="Java.html#Java_functional_interface">Functional interface without proxy classes</a>
<li><a href="Java.html#Java_using_own_jni_functions">Using your own JNI functions</a>
<li><a href="Java.html#Java_performance">Performance concerns and hints</a>
<li><a href="Java.html#Java_debugging">Debugging</a>
</ul>
<li><a href="Java.html#java_examples">Examples</a>
<li><a href="Java.html#Java_examples">Examples</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Lisp.html#Lisp">22 SWIG and Common Lisp</a></h3>
<h3><a href="Lisp.html#Lisp">23 SWIG and Common Lisp</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -892,7 +930,7 @@
</div>
<!-- INDEX -->
<h3><a href="Lua.html#Lua">23 SWIG and Lua</a></h3>
<h3><a href="Lua.html#Lua">24 SWIG and Lua</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -949,48 +987,45 @@
</div>
<!-- INDEX -->
<h3><a href="Modula3.html#Modula3">24 SWIG and Modula-3</a></h3>
<h3><a href="Modula3.html#Modula3">25 SWIG and Modula-3</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Modula3.html#modula3_overview">Overview</a>
<li><a href="Modula3.html#Modula3_modula3_overview">Overview</a>
<ul>
<li><a href="Modula3.html#whyscripting">Why not scripting ?</a>
<li><a href="Modula3.html#whymodula3">Why Modula-3 ?</a>
<li><a href="Modula3.html#whycpp">Why C / C++ ?</a>
<li><a href="Modula3.html#whyswig">Why SWIG ?</a>
<li><a href="Modula3.html#Modula3_motivation">Motivation</a>
</ul>
<li><a href="Modula3.html#conception">Conception</a>
<li><a href="Modula3.html#Modula3_conception">Conception</a>
<ul>
<li><a href="Modula3.html#cinterface">Interfaces to C libraries</a>
<li><a href="Modula3.html#cppinterface">Interfaces to C++ libraries</a>
<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#preliminaries">Preliminaries</a>
<li><a href="Modula3.html#Modula3_preliminaries">Preliminaries</a>
<ul>
<li><a href="Modula3.html#compilers">Compilers</a>
<li><a href="Modula3.html#commandline">Additional Commandline Options</a>
<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>
<li><a href="Modula3.html#Modula3_typemaps">Modula-3 typemaps</a>
<ul>
<li><a href="Modula3.html#inoutparam">Inputs and outputs</a>
<li><a href="Modula3.html#ordinals">Subranges, Enumerations, Sets</a>
<li><a href="Modula3.html#class">Objects</a>
<li><a href="Modula3.html#imports">Imports</a>
<li><a href="Modula3.html#exceptions">Exceptions</a>
<li><a href="Modula3.html#typemap_example">Example</a>
<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#hints">More hints to the generator</a>
<li><a href="Modula3.html#Modula3_hints">More hints to the generator</a>
<ul>
<li><a href="Modula3.html#features">Features</a>
<li><a href="Modula3.html#pragmas">Pragmas</a>
<li><a href="Modula3.html#Modula3_features">Features</a>
<li><a href="Modula3.html#Modula3_pragmas">Pragmas</a>
</ul>
<li><a href="Modula3.html#remarks">Remarks</a>
<li><a href="Modula3.html#Modula3_remarks">Remarks</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Mzscheme.html#Mzscheme">25 SWIG and MzScheme</a></h3>
<h3><a href="Mzscheme.html#Mzscheme">26 SWIG and MzScheme</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1000,7 +1035,7 @@
</div>
<!-- INDEX -->
<h3><a href="Ocaml.html#Ocaml">26 SWIG and Ocaml</a></h3>
<h3><a href="Ocaml.html#Ocaml">27 SWIG and Ocaml</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1051,7 +1086,7 @@
</div>
<!-- INDEX -->
<h3><a href="Octave.html#Octave">27 SWIG and Octave</a></h3>
<h3><a href="Octave.html#Octave">28 SWIG and Octave</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1086,7 +1121,7 @@
</div>
<!-- INDEX -->
<h3><a href="Perl5.html#Perl5">28 SWIG and Perl5</a></h3>
<h3><a href="Perl5.html#Perl5">29 SWIG and Perl5</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1153,7 +1188,7 @@
</div>
<!-- INDEX -->
<h3><a href="Php.html#Php">29 SWIG and PHP</a></h3>
<h3><a href="Php.html#Php">30 SWIG and PHP</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1193,7 +1228,7 @@
</div>
<!-- INDEX -->
<h3><a href="Pike.html#Pike">30 SWIG and Pike</a></h3>
<h3><a href="Pike.html#Pike">31 SWIG and Pike</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1217,7 +1252,7 @@
</div>
<!-- INDEX -->
<h3><a href="Python.html#Python">31 SWIG and Python</a></h3>
<h3><a href="Python.html#Python">32 SWIG and Python</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1320,7 +1355,7 @@
</div>
<!-- INDEX -->
<h3><a href="Ruby.html#Ruby">32 SWIG and Ruby</a></h3>
<h3><a href="Ruby.html#Ruby">33 SWIG and Ruby</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1353,7 +1388,7 @@
<li><a href="Ruby.html#Ruby_nn22">C++ namespaces</a>
<li><a href="Ruby.html#Ruby_nn23">C++ templates</a>
<li><a href="Ruby.html#Ruby_nn23_1">C++ Standard Template Library (STL)</a>
<li><a href="Ruby.html#C_STL_Functors">C++ STL Functors</a>
<li><a href="Ruby.html#Ruby_C_STL_Functors">C++ STL Functors</a>
<li><a href="Ruby.html#Ruby_C_Iterators">C++ STL Iterators</a>
<li><a href="Ruby.html#Ruby_nn24">C++ Smart Pointers</a>
<li><a href="Ruby.html#Ruby_nn25">Cross-Language Polymorphism</a>
@ -1437,7 +1472,7 @@
</ul>
<li><a href="Ruby.html#Ruby_nn53">Advanced Topics</a>
<ul>
<li><a href="Ruby.html#Ruby_nn54">Operator overloading</a>
<li><a href="Ruby.html#Ruby_operator_overloading">Operator overloading</a>
<li><a href="Ruby.html#Ruby_nn55">Creating Multi-Module Packages</a>
<li><a href="Ruby.html#Ruby_nn56">Specifying Mixin Modules</a>
</ul>
@ -1454,7 +1489,7 @@
</div>
<!-- INDEX -->
<h3><a href="Tcl.html#Tcl">33 SWIG and Tcl</a></h3>
<h3><a href="Tcl.html#Tcl">34 SWIG and Tcl</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1520,7 +1555,7 @@
</div>
<!-- INDEX -->
<h3><a href="R.html#R">34 SWIG and R</a></h3>
<h3><a href="R.html#R">35 SWIG and R</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1536,7 +1571,7 @@
</div>
<!-- INDEX -->
<h3><a href="Extending.html#Extending">35 Extending SWIG to support new languages</a></h3>
<h3><a href="Extending.html#Extending">36 Extending SWIG to support new languages</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1585,7 +1620,7 @@
<li><a href="Extending.html#Extending_nn36">Entry point to code generation</a>
<li><a href="Extending.html#Extending_nn37">Module I/O and wrapper skeleton</a>
<li><a href="Extending.html#Extending_nn38">Low-level code generators</a>
<li><a href="Extending.html#Extending_nn39">Configuration files</a>
<li><a href="Extending.html#Extending_configuration_files">Configuration files</a>
<li><a href="Extending.html#Extending_nn40">Runtime support</a>
<li><a href="Extending.html#Extending_nn41">Standard library files</a>
<li><a href="Extending.html#Extending_nn42">User examples</a>

26
Doc/Manual/Customization.html
View file

@ -10,7 +10,7 @@
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#exception">Exception handling with %exception</a>
<li><a href="#Customization_exception">Exception handling with %exception</a>
<ul>
<li><a href="#Customization_nn3">Handling exceptions in C code</a>
<li><a href="#Customization_nn4">Exception handling with longjmp()</a>
@ -20,14 +20,14 @@
<li><a href="#Customization_exception_special_variables">Special variables for %exception</a>
<li><a href="#Customization_nn7">Using The SWIG exception library</a>
</ul>
<li><a href="#ownership">Object ownership and %newobject</a>
<li><a href="#features">Features and the %feature directive</a>
<li><a href="#Customization_ownership">Object ownership and %newobject</a>
<li><a href="#Customization_features">Features and the %feature directive</a>
<ul>
<li><a href="#Customization_feature_attributes">Feature attributes</a>
<li><a href="#Customization_feature_flags">Feature flags</a>
<li><a href="#Customization_clearing_features">Clearing features</a>
<li><a href="#Customization_features_default_args">Features and default arguments</a>
<li><a href="#features_example">Feature example</a>
<li><a href="#Customization_features_example">Feature example</a>
</ul>
</ul>
</div>
@ -45,7 +45,7 @@ of exception handling is presented. Then, a more general-purpose
customization mechanism known as "features" is described.
</p>
<H2><a name="exception"></a>11.1 Exception handling with %exception</H2>
<H2><a name="Customization_exception"></a>11.1 Exception handling with %exception</H2>
<p>
@ -83,7 +83,7 @@ How the exception is handled depends on the target language, for example, Python
<p>
When defined, the code enclosed in braces is inserted directly into the low-level wrapper
functions. The special variable <tt>$action</tt> is one of a few
<a href="Customization.html#Customization_exception_special_variables">%exception special variable</a>
<a href="Customization.html#Customization_exception_special_variables">%exception special variables</a>
supported and gets replaced with the actual operation
to be performed (a function call, method invocation, attribute access, etc.). An exception handler
remains in effect until it is explicitly deleted. This is done by using either <tt>%exception</tt>
@ -351,7 +351,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#ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>.
<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>.
For example, if you wanted to define
an exception handler for a specific class, you might write this:
</p>
@ -582,7 +582,7 @@ it can be used elsewhere in SWIG. This includes typemaps and helper
functions.
</p>
<H2><a name="ownership"></a>11.2 Object ownership and %newobject</H2>
<H2><a name="Customization_ownership"></a>11.2 Object ownership and %newobject</H2>
<p>
@ -734,7 +734,7 @@ char *strdup(const char *s);
The results might not be what you expect.
</p>
<H2><a name="features"></a>11.3 Features and the %feature directive</H2>
<H2><a name="Customization_features"></a>11.3 Features and the %feature directive</H2>
<p>
@ -773,9 +773,9 @@ involving <tt>%feature</tt>:
</div>
<p>
The name matching rules outlined in the <a href="SWIGPlus.html#ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
The name matching rules outlined in the <a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
section applies to all <tt>%feature</tt> directives.
In fact the the <tt>%rename</tt> directive is just a special form of <tt>%feature</tt>.
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
pinpoint accuracy to specific declarations if needed.
Additionally, if no declaration name is given, a global feature is said to be defined.
@ -854,7 +854,7 @@ In the following example, <tt>MyExceptionClass</tt> is the name of the Java clas
</div>
<p>
Further details can be obtained from the <a href="Java.html#exception_handling">Java exception handling</a> section.
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"></a>11.3.2 Feature flags</H3>
@ -1123,7 +1123,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="features_example"></a>11.3.5 Feature example</H3>
<H3><a name="Customization_features_example"></a>11.3.5 Feature example</H3>
<p>

122
Doc/Manual/Extending.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Extending"></a>35 Extending SWIG to support new languages</H1>
<H1><a name="Extending"></a>36 Extending SWIG to support new languages</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -54,7 +54,7 @@
<li><a href="#Extending_nn36">Entry point to code generation</a>
<li><a href="#Extending_nn37">Module I/O and wrapper skeleton</a>
<li><a href="#Extending_nn38">Low-level code generators</a>
<li><a href="#Extending_nn39">Configuration files</a>
<li><a href="#Extending_configuration_files">Configuration files</a>
<li><a href="#Extending_nn40">Runtime support</a>
<li><a href="#Extending_nn41">Standard library files</a>
<li><a href="#Extending_nn42">User examples</a>
@ -75,7 +75,7 @@
<H2><a name="Extending_nn2"></a>35.1 Introduction</H2>
<H2><a name="Extending_nn2"></a>36.1 Introduction</H2>
<p>
@ -91,7 +91,7 @@ Also, this chapter is not meant to be a hand-holding tutorial. As a starting po
you should probably look at one of SWIG's existing modules.
</p>
<H2><a name="Extending_nn3"></a>35.2 Prerequisites</H2>
<H2><a name="Extending_nn3"></a>36.2 Prerequisites</H2>
<p>
@ -121,7 +121,7 @@ obvious, but almost all SWIG directives as well as the low-level generation of
wrapper code are driven by C++ datatypes.
</p>
<H2><a name="Extending_nn4"></a>35.3 The Big Picture</H2>
<H2><a name="Extending_nn4"></a>36.3 The Big Picture</H2>
<p>
@ -158,7 +158,7 @@ role in making the system work. For example, both typemaps and declaration anno
based on pattern matching and interact heavily with the underlying type system.
</p>
<H2><a name="Extending_nn5"></a>35.4 Execution Model</H2>
<H2><a name="Extending_nn5"></a>36.4 Execution Model</H2>
<p>
@ -203,7 +203,7 @@ latter stage of compilation.
The next few sections briefly describe some of these stages.
</p>
<H3><a name="Extending_nn6"></a>35.4.1 Preprocessing</H3>
<H3><a name="Extending_nn6"></a>36.4.1 Preprocessing</H3>
<p>
@ -284,7 +284,7 @@ been expanded as well as everything else that goes into the low-level
construction of the wrapper code.
</p>
<H3><a name="Extending_nn7"></a>35.4.2 Parsing</H3>
<H3><a name="Extending_nn7"></a>36.4.2 Parsing</H3>
<p>
@ -385,7 +385,7 @@ returning a <tt>foo</tt> and taking types <tt>a</tt> and <tt>b</tt> as
arguments).
</p>
<H3><a name="Extending_nn8"></a>35.4.3 Parse Trees</H3>
<H3><a name="Extending_nn8"></a>36.4.3 Parse Trees</H3>
<p>
@ -640,7 +640,7 @@ $ swig -c++ -python -debug-module 4 example.i
</pre>
</div>
<H3><a name="Extending_nn9"></a>35.4.4 Attribute namespaces</H3>
<H3><a name="Extending_nn9"></a>36.4.4 Attribute namespaces</H3>
<p>
@ -659,7 +659,7 @@ that matches the name of the target language. For example, <tt>python:foo</tt>
<tt>perl:foo</tt>.
</p>
<H3><a name="Extending_nn10"></a>35.4.5 Symbol Tables</H3>
<H3><a name="Extending_nn10"></a>36.4.5 Symbol Tables</H3>
<p>
@ -750,7 +750,7 @@ example.i:5. Previous declaration is foo_i(int )
</pre>
</div>
<H3><a name="Extending_nn11"></a>35.4.6 The %feature directive</H3>
<H3><a name="Extending_nn11"></a>36.4.6 The %feature directive</H3>
<p>
@ -806,7 +806,7 @@ For example, the exception code above is simply
stored without any modifications.
</p>
<H3><a name="Extending_nn12"></a>35.4.7 Code Generation</H3>
<H3><a name="Extending_nn12"></a>36.4.7 Code Generation</H3>
<p>
@ -928,7 +928,7 @@ public :
The role of these functions is described shortly.
</p>
<H3><a name="Extending_nn13"></a>35.4.8 SWIG and XML</H3>
<H3><a name="Extending_nn13"></a>36.4.8 SWIG and XML</H3>
<p>
@ -941,7 +941,7 @@ internal data structures, it may be useful to keep XML in the back of
your mind as a model.
</p>
<H2><a name="Extending_nn14"></a>35.5 Primitive Data Structures</H2>
<H2><a name="Extending_nn14"></a>36.5 Primitive Data Structures</H2>
<p>
@ -987,7 +987,7 @@ typedef Hash Typetab;
</pre>
</div>
<H3><a name="Extending_nn15"></a>35.5.1 Strings</H3>
<H3><a name="Extending_nn15"></a>36.5.1 Strings</H3>
<p>
@ -1128,7 +1128,7 @@ Returns the number of replacements made (if any).
</div>
<H3><a name="Extending_nn16"></a>35.5.2 Hashes</H3>
<H3><a name="Extending_nn16"></a>36.5.2 Hashes</H3>
<p>
@ -1205,7 +1205,7 @@ Returns the list of hash table keys.
</div>
<H3><a name="Extending_nn17"></a>35.5.3 Lists</H3>
<H3><a name="Extending_nn17"></a>36.5.3 Lists</H3>
<p>
@ -1294,7 +1294,7 @@ If <tt>t</tt> is not a standard object, it is assumed to be a <tt>char *</tt>
and is used to create a String object.
</div>
<H3><a name="Extending_nn18"></a>35.5.4 Common operations</H3>
<H3><a name="Extending_nn18"></a>36.5.4 Common operations</H3>
The following operations are applicable to all datatypes.
@ -1349,7 +1349,7 @@ objects and report errors.
Gets the line number associated with <tt>x</tt>.
</div>
<H3><a name="Extending_nn19"></a>35.5.5 Iterating over Lists and Hashes</H3>
<H3><a name="Extending_nn19"></a>36.5.5 Iterating over Lists and Hashes</H3>
To iterate over the elements of a list or a hash table, the following functions are used:
@ -1394,7 +1394,7 @@ for (j = First(j); j.item; j= Next(j)) {
</div>
<H3><a name="Extending_nn20"></a>35.5.6 I/O</H3>
<H3><a name="Extending_nn20"></a>36.5.6 I/O</H3>
Special I/O functions are used for all internal I/O. These operations
@ -1531,7 +1531,7 @@ Similarly, the preprocessor and parser all operate on string-files.
</div>
<H2><a name="Extending_nn21"></a>35.6 Navigating and manipulating parse trees</H2>
<H2><a name="Extending_nn21"></a>36.6 Navigating and manipulating parse trees</H2>
Parse trees are built as collections of hash tables. Each node is a hash table in which
@ -1665,7 +1665,7 @@ Deletes a node from the parse tree. Deletion reconnects siblings and properly u
the parent so that sibling nodes are unaffected.
</div>
<H2><a name="Extending_nn22"></a>35.7 Working with attributes</H2>
<H2><a name="Extending_nn22"></a>36.7 Working with attributes</H2>
<p>
@ -1782,7 +1782,7 @@ the attribute is optional. <tt>Swig_restore()</tt> must always be called after
function.
</div>
<H2><a name="Extending_nn23"></a>35.8 Type system</H2>
<H2><a name="Extending_nn23"></a>36.8 Type system</H2>
<p>
@ -1791,7 +1791,7 @@ pointers, references, and pointers to members. A detailed discussion of
type theory is impossible here. However, let's cover the highlights.
</p>
<H3><a name="Extending_nn24"></a>35.8.1 String encoding of types</H3>
<H3><a name="Extending_nn24"></a>36.8.1 String encoding of types</H3>
<p>
@ -1892,7 +1892,7 @@ make the final type, the two parts are just joined together using
string concatenation.
</p>
<H3><a name="Extending_nn25"></a>35.8.2 Type construction</H3>
<H3><a name="Extending_nn25"></a>36.8.2 Type construction</H3>
<p>
@ -2061,7 +2061,7 @@ Returns the prefix of a type. For example, if <tt>ty</tt> is
<tt>ty</tt> is unmodified.
</div>
<H3><a name="Extending_nn26"></a>35.8.3 Type tests</H3>
<H3><a name="Extending_nn26"></a>36.8.3 Type tests</H3>
<p>
@ -2148,7 +2148,7 @@ Checks if <tt>ty</tt> is a varargs type.
Checks if <tt>ty</tt> is a templatized type.
</div>
<H3><a name="Extending_nn27"></a>35.8.4 Typedef and inheritance</H3>
<H3><a name="Extending_nn27"></a>36.8.4 Typedef and inheritance</H3>
<p>
@ -2250,7 +2250,7 @@ Fully reduces <tt>ty</tt> according to typedef rules. Resulting datatype
will consist only of primitive typenames.
</div>
<H3><a name="Extending_nn28"></a>35.8.5 Lvalues</H3>
<H3><a name="Extending_nn28"></a>36.8.5 Lvalues</H3>
<p>
@ -2287,7 +2287,7 @@ Literal y; // type = 'Literal', ltype='p.char'
</pre>
</div>
<H3><a name="Extending_nn29"></a>35.8.6 Output functions</H3>
<H3><a name="Extending_nn29"></a>36.8.6 Output functions</H3>
<p>
@ -2349,7 +2349,7 @@ SWIG, but is most commonly associated with type-descriptor objects
that appear in wrappers (e.g., <tt>SWIGTYPE_p_double</tt>).
</div>
<H2><a name="Extending_nn30"></a>35.9 Parameters</H2>
<H2><a name="Extending_nn30"></a>36.9 Parameters</H2>
<p>
@ -2448,7 +2448,7 @@ included. Used to emit prototypes.
Returns the number of required (non-optional) arguments in <tt>p</tt>.
</div>
<H2><a name="Extending_nn31"></a>35.10 Writing a Language Module</H2>
<H2><a name="Extending_nn31"></a>36.10 Writing a Language Module</H2>
<p>
@ -2463,7 +2463,7 @@ describes the creation of a minimal Python module. You should be able to extra
this to other languages.
</p>
<H3><a name="Extending_nn32"></a>35.10.1 Execution model</H3>
<H3><a name="Extending_nn32"></a>36.10.1 Execution model</H3>
<p>
@ -2473,7 +2473,7 @@ the parsing of command line options, all aspects of code generation are controll
different methods of the <tt>Language</tt> that must be defined by your module.
</p>
<H3><a name="Extending_starting_out"></a>35.10.2 Starting out</H3>
<H3><a name="Extending_starting_out"></a>36.10.2 Starting out</H3>
<p>
@ -2581,7 +2581,7 @@ that activates your module. For example, <tt>swig -python foo.i</tt>. The
messages from your new module should appear.
</p>
<H3><a name="Extending_nn34"></a>35.10.3 Command line options</H3>
<H3><a name="Extending_nn34"></a>36.10.3 Command line options</H3>
<p>
@ -2640,7 +2640,7 @@ to mark the option as valid. If you forget to do this, SWIG will terminate wit
unrecognized command line option error.
</p>
<H3><a name="Extending_nn35"></a>35.10.4 Configuration and preprocessing</H3>
<H3><a name="Extending_nn35"></a>36.10.4 Configuration and preprocessing</H3>
<p>
@ -2689,7 +2689,7 @@ an implementation file <tt>python.cxx</tt> and a configuration file
<tt>python.swg</tt>.
</p>
<H3><a name="Extending_nn36"></a>35.10.5 Entry point to code generation</H3>
<H3><a name="Extending_nn36"></a>36.10.5 Entry point to code generation</H3>
<p>
@ -2747,7 +2747,7 @@ int Python::top(Node *n) {
</pre>
</div>
<H3><a name="Extending_nn37"></a>35.10.6 Module I/O and wrapper skeleton</H3>
<H3><a name="Extending_nn37"></a>36.10.6 Module I/O and wrapper skeleton</H3>
<!-- please report bugs in this section to mgossage -->
@ -2895,7 +2895,7 @@ functionWrapper : void Shape_y_set(Shape *self,double y)
</pre>
</div>
<H3><a name="Extending_nn38"></a>35.10.7 Low-level code generators</H3>
<H3><a name="Extending_nn38"></a>36.10.7 Low-level code generators</H3>
<!-- please report bugs in this section to mgossage -->
@ -3049,7 +3049,7 @@ but without the typemaps, there is still work to do.
</p>
<H3><a name="Extending_nn39"></a>35.10.8 Configuration files</H3>
<H3><a name="Extending_configuration_files"></a>36.10.8 Configuration files</H3>
<!-- please report bugs in this section to ttn -->
@ -3090,8 +3090,6 @@ The nickname is used in four places:
<TR><TD><B>usage</B></TD><TD><B>transform</B></TD></TR>
<TR><TD>"skip" tag</TD><TD>(none)</TD></TR>
<TR><TD>Examples/ subdir name</TD><TD>(none)</TD></TR>
<TR><TD>Examples/GIFPlot/ subdir name</TD>
<TD>capitalize (upcase first letter)</TD></TR>
<TR><TD>Examples/test-suite/ subdir name</TD><TD>(none)</TD></TR>
<!-- add more uses here (remember to adjust header) -->
</TABLE>
@ -3159,8 +3157,8 @@ skip-qux = $(skip-qux99)
<p>
Lastly, you need to modify each of <TT>check-aliveness</TT>,
<TT>check-examples</TT>, <TT>check-test-suite</TT>,
<TT>check-gifplot</TT> (all targets) and <TT>lib-languages</TT> (var).
<TT>check-examples</TT>, <TT>check-test-suite</TT>
and <TT>lib-languages</TT> (var).
Use the nickname for these, not the alias.
Note that you can do this even before you have any tests or examples
set up; the Makefile rules do some sanity checking and skip around
@ -3175,10 +3173,6 @@ and look to the existing languages for examples.
<dd> Do <TT>cp ../python/check.list .</TT> and modify to taste.
One subdir per line.
<dt> <b>Examples/GIFPlot/Qux99/check.list</b>
<dd> Do <TT>cp ../Python/check.list .</TT> and modify to taste.
One subdir per line.
<dt> <b>Lib/qux99/extra-install.list</b>
<dd> If you add your language to the top-level Makefile.in var
<TT>lib-languages</TT>, then <TT>make install</TT> will install
@ -3199,7 +3193,7 @@ politely displays the ignoring language message.
</dl>
<H3><a name="Extending_nn40"></a>35.10.9 Runtime support</H3>
<H3><a name="Extending_nn40"></a>36.10.9 Runtime support</H3>
<p>
@ -3208,7 +3202,7 @@ Discuss the kinds of functions typically needed for SWIG runtime support (e.g.
the SWIG files that implement those functions.
</p>
<H3><a name="Extending_nn41"></a>35.10.10 Standard library files</H3>
<H3><a name="Extending_nn41"></a>36.10.10 Standard library files</H3>
<p>
@ -3227,7 +3221,7 @@ The following are the minimum that are usually supported:
Please copy these and modify for any new language.
</p>
<H3><a name="Extending_nn42"></a>35.10.11 User examples</H3>
<H3><a name="Extending_nn42"></a>36.10.11 User examples</H3>
<p>
@ -3252,11 +3246,11 @@ These can be found, for example for Python, in
<p>
By default, all of the examples are built and run when the user types
<tt>make check</tt>. To ensure that your examples are automatically run
during this process, see the section on <a href="#n37a">configuration
during this process, see the section on <a href="#Extending_configuration_files">configuration
files</a>.
</p>
<H3><a name="Extending_test_suite"></a>35.10.12 Test driven development and the test-suite</H3>
<H3><a name="Extending_test_suite"></a>36.10.12 Test driven development and the test-suite</H3>
<p>
@ -3315,7 +3309,7 @@ It is therefore essential that the runtime tests are written in a manner that di
but error/exception out with an error message on stderr on failure.
</p>
<H4><a name="Extending_running_test_suite"></a>35.10.12.1 Running the test-suite</H4>
<H4><a name="Extending_running_test_suite"></a>36.10.12.1 Running the test-suite</H4>
<p>
@ -3475,7 +3469,15 @@ SWIG can be analyzed for bad memory accesses using:
make ret_by_value.ctest SWIGTOOL="valgrind --tool=memcheck --trace-children=yes"
</pre></div>
<H3><a name="Extending_nn43"></a>35.10.13 Documentation</H3>
<p>
A debugger can also be invoked easily on an individual test, for example gdb:
</p>
<div class="shell"><pre>
make ret_by_value.ctest RUNTOOL="gdb --args"
</pre></div>
<H3><a name="Extending_nn43"></a>36.10.13 Documentation</H3>
<p>
@ -3507,7 +3509,7 @@ Some topics that you'll want to be sure to address include:
if available.
</ul>
<H3><a name="Extending_prerequisites"></a>35.10.14 Prerequisites for adding a new language module to the SWIG distribution</H3>
<H3><a name="Extending_prerequisites"></a>36.10.14 Prerequisites for adding a new language module to the SWIG distribution</H3>
<p>
@ -3564,7 +3566,7 @@ should be added should there be an area not already covered by
the existing tests.
</p>
<H3><a name="Extending_coding_style_guidelines"></a>35.10.15 Coding style guidelines</H3>
<H3><a name="Extending_coding_style_guidelines"></a>36.10.15 Coding style guidelines</H3>
<p>
@ -3588,7 +3590,7 @@ The generated C/C++ code should also follow this style as close as possible. How
should be avoided as unlike the SWIG developers, users will never have consistent tab settings.
</p>
<H2><a name="Extending_debugging_options"></a>35.11 Debugging Options</H2>
<H2><a name="Extending_debugging_options"></a>36.11 Debugging Options</H2>
<p>
@ -3613,7 +3615,7 @@ There are various command line options which can aid debugging a SWIG interface
The complete list of command line options for SWIG are available by running <tt>swig -help</tt>.
</p>
<H2><a name="Extending_nn46"></a>35.12 Guide to parse tree nodes</H2>
<H2><a name="Extending_nn46"></a>36.12 Guide to parse tree nodes</H2>
<p>
@ -4021,7 +4023,7 @@ extern "X" { ... } declaration.
</pre>
</div>
<H2><a name="Extending_further_info"></a>35.13 Further Development Information</H2>
<H2><a name="Extending_further_info"></a>36.13 Further Development Information</H2>
<p>

454
Doc/Manual/Go.html Normal file
View file

@ -0,0 +1,454 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>SWIG and Go</title>
<link rel="stylesheet" type="text/css" href="style.css">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="Go"></a>20 SWIG and Go</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Go_overview">Overview</a>
<li><a href="#Go_running_swig">Running SWIG with Go</a>
<ul>
<li><a href="#Go_commandline">Additional Commandline Options</a>
<li><a href="#Go_outputs">Go Output Files</a>
</ul>
<li><a href="#Go_basic_tour">A tour of basic C/C++ wrapping</a>
<ul>
<li><a href="#Go_package">Go Package Name</a>
<li><a href="#Go_names">Go Names</a>
<li><a href="#Go_constants">Go Constants</a>
<li><a href="#Go_enumerations">Go Enumerations</a>
<li><a href="#Go_classes">Go Classes</a>
<ul>
<li><a href="#Go_class_inheritance">Go Class Inheritance</a>
</ul>
<li><a href="#Go_templates">Go Templates</a>
<li><a href="#Go_director_classes">Go Director Classes</a>
<li><a href="#Go_primitive_type_mappings">Default Go primitive type mappings</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<p>
This chapter describes SWIG's support of Go. For more information on
the Go programming language
see <a href="http://golang.org/">golang.org</a>.
</p>
<H2><a name="Go_overview"></a>20.1 Overview</H2>
<p>
Go is a compiled language, not a scripting language. However, it does
not support direct calling of functions written in C/C++. The cgo
program may be used to generate wrappers to call C code from Go, but
there is no convenient way to call C++ code. SWIG fills this gap.
</p>
<p>
There are (at least) two different Go compilers. One is the gc
compiler, normally invoked under the names 6g, 8g, or 5g. The other
is the gccgo compiler, which is a frontend to the gcc compiler suite.
The interface to C/C++ code is completely different for the two Go
compilers. SWIG supports both, selected by a command line option.
</p>
<p>
Because Go is a type-safe compiled language, SWIG's runtime type
checking and runtime library are not used with Go. This should be
borne in mind when reading the rest of the SWIG documentation.
</p>
<H2><a name="Go_running_swig"></a>20.2 Running SWIG with Go</H2>
<p>
To generate Go code, use the <tt>-go</tt> option with SWIG. By
default SWIG will generate code for the gc compilers. To generate
code for gccgo, you should also use the <tt>-gccgo</tt> option.
</p>
<H3><a name="Go_commandline"></a>20.2.1 Additional Commandline Options</H3>
<p>
These are the command line options for SWIG's GO module. They can
also be seen by using:
</p>
<div class="code"><pre>
swig -go -help
</pre></div>
<table summary="Go specific options">
<tr>
<th>Go specific options</th>
</tr>
<tr>
<td>-gccgo</td>
<td>Generate code for gccgo. The default is to generate code for
6g/8g/6g.</td>
</tr>
<tr>
<td>-package &lt;name&gt;</td>
<td>Set the name of the Go package to &lt;name&gt;. The default
package name is the SWIG module name.</td>
</tr>
<tr>
<td>-go-prefix &lt;prefix&gt;</td>
<td>When generating code for gccgo, set the prefix to use. This
corresponds to the <tt>-fgo-prefix</tt> option to gccgo.</td>
</tr>
<tr>
<td>-long-type-size &lt;s&gt;</td>
<td>Set the size for the C/C++ type <tt>long</tt>. This controls
whether <tt>long</tt> is converted to the Go type <tt>int32</tt>
or <tt>int64</tt>. The &lt;s&gt; argument should be 32 or 64.</td>
</tr>
</table>
<H3><a name="Go_outputs"></a>20.2.2 Go Output Files</H3>
<p> When generating Go code, SWIG will generate the following
files:</p>
<ul>
<li>
MODULE.go will contain the Go functions that your Go code will call.
These functions will be wrappers for the C++ functions defined by your
module. This file should, of course, be compiled with the Go
compiler.
<li>
MODULE_wrap.c or MODULE_wrap.cxx will contain C/C++ functions will be
invoked by the Go wrapper code. This file should be compiled with the
usual C or C++ compiler and linked into a shared library.
<li>
MODULE_wrap.h will be generated if you use the directors feature. It
provides a definition of the generated C++ director classes. It is
generally not necessary to use this file, but in some special cases it
may be helpful to include it in your code, compiled with the usual C
or C++ compiler.
<li>
If using the gc compiler, MODULE_gc.c will contain C code which should
be compiled with the C compiler distributed as part of the gc compiler: 6c, 8c,
or 5c. It should then be combined with the compiled MODULE.go using
gopack. This file will not be generated when using gccgo.
</ul>
<p>
A typical command sequence would look like this:
</p>
<div class="code"><pre>
% swig -go example.i
% gcc -c -fpic example.c
% gcc -c -fpic example_wrap.c
% gcc -shared example.o example_wrap.o -o example.so
% 6g example.go
% 6c example_gc.c
% gopack grc example.a example.6 example_gc.6
% 6g main.go # your code, not generated by SWIG
% 6l main.6
</pre></div>
<H2><a name="Go_basic_tour"></a>20.3 A tour of basic C/C++ wrapping</H2>
<p>
By default, SWIG attempts to build a natural Go interface to your
C/C++ code. However, the languages are somewhat different, so some
modifications have to occur. This section briefly covers the
essential aspects of this wrapping.
</p>
<H3><a name="Go_package"></a>20.3.1 Go Package Name</H3>
<p>
All Go source code lives in a package. The name of this package will
default to the name of the module from SWIG's <tt>%module</tt>
directive. You may override this by using SWIG's <tt>-package</tt>
command line option.
</p>
<H3><a name="Go_names"></a>20.3.2 Go Names</H3>
<p>
In Go, a function is only visible outside the current package if the
first letter of the name is uppercase. This is quite different from
C/C++. Because of this, C/C++ names are modified when generating the
Go interface: the first letter is forced to be uppercase if it is not
already. This affects the names of functions, methods, variables,
constants, enums, and classes.
</p>
<p>
C/C++ variables are wrapped with setter and getter functions in Go.
First the first letter of the variable name will be forced to
uppercase, and then <tt>Get</tt> or <tt>Set</tt> will be prepended.
For example, if the C/C++ variable is called <tt>var</tt>, then SWIG
will define the functions <tt>GetVar</tt> and <tt>SetVar</tt>. If a
variable is declared as <tt>const</tt>, or if
SWIG's <a href="SWIG.html#SWIG_readonly_variables">
<tt>%immutable</tt> directive</a> is used for the variable, then only
the getter will be defined.
</p>
<p>
C++ classes will be discussed further below. Here we'll note that the
first letter of the class name will be forced to uppercase to give the
name of a type in Go. A constructor will be named <tt>New</tt>
followed by that name, and the destructor will be
named <tt>Delete</tt> followed by that name.
</p>
<H3><a name="Go_constants"></a>20.3.3 Go Constants</H3>
<p>
C/C++ constants created via <tt>#define</tt> or the <tt>%constant</tt>
directive become Go constants, declared with a <tt>const</tt>
declaration.
<H3><a name="Go_enumerations"></a>20.3.4 Go Enumerations</H3>
<p>
C/C++ enumeration types will cause SWIG to define an integer type with
the name of the enumeration (with first letter forced to uppercase as
usual). The values of the enumeration will become variables in Go;
code should avoid modifying those variables.
</p>
<H3><a name="Go_classes"></a>20.3.5 Go Classes</H3>
<p>
Go has interfaces, methods and inheritance, but it does not have
classes in the same sense as C++. This sections describes how SWIG
represents C++ classes represented in Go.
</p>
<p>
For a C++ class <tt>ClassName</tt>, SWIG will define two types in Go:
an underlying type, which will just hold a pointer to the C++ type,
and an interface type. The interface type will be
named <tt>ClassName</tt>. SWIG will define a
function <tt>NewClassName</tt> which will take any constructor
arguments and return a value of the interface
type <tt>ClassName</tt>. SWIG will also define a
destructor <tt>DeleteClassName</tt>.
</p>
<p>
SWIG will represent any methods of the C++ class as methods on the
underlying type, and also as methods of the interface type. Thus C++
methods may be invoked directly using the
usual <tt>val.MethodName</tt> syntax. Public members of the C++ class
will be given getter and setter functions defined as methods of the
class.
</p>
<p>
SWIG will represent static methods of C++ classes as ordinary Go
functions. SWIG will use names like <tt>ClassName_MethodName</tt>.
SWIG will give static members getter and setter functions with names
like <tt>GetClassName_VarName</tt>.
</p>
<p>
Given a value of the interface type, Go code can retrieve the pointer
to the C++ type by calling the <tt>Swigcptr</tt> method. This will
return a value of type <tt>SwigcptrClassName</tt>, which is just a
name for <tt>uintptr</tt>. A Go type conversion can be used to
convert this value to a different C++ type, but note that this
conversion will not be type checked and is essentially equivalent
to <tt>reinterpret_cast</tt>. This should only be used for very
special cases, such as where C++ would use a <tt>dynamic_cast</tt>.
</p>
<H4><a name="Go_class_inheritance"></a>20.3.5.1 Go Class Inheritance</H4>
<p>
C++ class inheritance is automatically represented in Go due to its
use of interfaces. The interface for a child class will be a superset
of the interface of its parent class. Thus a value of the child class
type in Go may be passed to a function which expects the parent class.
Doing the reverse will require an explicit type assertion, which will
be checked dynamically.
</p>
<H3><a name="Go_templates"></a>20.3.6 Go Templates</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
the <tt>%template</tt> directive.
<H3><a name="Go_director_classes"></a>20.3.7 Go Director Classes</H3>
<p>
SWIG's director feature permits a Go type to act as the subclass of a
C++ class with virtual methods. This is complicated by the fact that
C++ and Go define inheritance differently. In Go, structs can inherit
methods via anonymous field embedding. However, when a method is
called for an embedded struct, if that method calls any other methods,
they are called for the embedded struct, not for the original type.
Therefore, SWIG must use Go interfaces to represent C++ inheritance.
</p>
<p>
In order to use the director feature in Go, you must define a type in
your Go code. You must then add methods for the type. Define a
method in Go for each C++ virtual function that you want to override.
You must then create a value of your new type, and pass a pointer to
it to the function <tt>NewDirectorClassName</tt>,
where <tt>ClassName</tt> is the name of the C++ class. That will
return a value of type <tt>ClassName</tt>.
</p>
<p>
For example:
</p>
<div class="code">
<pre>
type GoClass struct { }
func (p *GoClass) VirtualFunction() { }
func MakeClass() ClassName {
return NewDirectorClassName(&amp;GoClass{})
}
</pre>
</div>
<p>
Any call in C++ code to the virtual function will wind up calling the
method defined in Go. The Go code may of course call other methods on
itself, and those methods may be defined either in Go or in C++.
</p>
<H3><a name="Go_primitive_type_mappings"></a>20.3.8 Default Go primitive type mappings</H3>
<p>
The following table lists the default type mapping from C/C++ to Go.
This table will tell you which Go type to expect for a function which
uses a given C/C++ type.
</p>
<table BORDER summary="Go primitive type mappings">
<tr>
<td><b>C/C++ type</b></td>
<td><b>Go type</b></td>
</tr>
<tr>
<td>bool</td>
<td>bool</td>
</tr>
<tr>
<td>char</td>
<td>byte</td>
</tr>
<tr>
<td>signed char</td>
<td>int8</td>
</tr>
<tr>
<td>unsigned char</td>
<td>byte</td>
</tr>
<tr>
<td>short</td>
<td>int16</td>
</tr>
<tr>
<td>unsigned short</td>
<td>uint16</td>
</tr>
<tr>
<td>int</td>
<td>int</td>
</tr>
<tr>
<td>unsigned int</td>
<td>uint</td>
</tr>
<tr>
<td>long</td>
<td>int32 or int64, depending on <tt>-long-type-size</tt></td>
</tr>
<tr>
<td>unsigned long</td>
<td>uint32 or uint64, depending on <tt>-long-type-size</tt></td>
</tr>
<tr>
<td>long long</td>
<td>int64</td>
</tr>
<tr>
<td>unsigned long long</td>
<td>uint64</td>
</tr>
<tr>
<td>float</td>
<td>float32</td>
</tr>
<tr>
<td>double</td>
<td>float64</td>
</tr>
<tr>
<td>char *<br>char []</td>
<td>string</td>
</tr>
</table>
<p>
Note that SWIG wraps the C <tt>char</tt> type as a character. Pointers
and arrays of this type are wrapped as strings. The <tt>signed
char</tt> type can be used if you want to treat <tt>char</tt> as a
signed number rather than a character. Also note that all const
references to primitive types are treated as if they are passed by
value.
</p>
<p>
These type mappings are defined by the "gotype" typemap. You may change
that typemap, or add new values, to control how C/C++ types are mapped
into Go types.
</p>
</body>
</html>

50
Doc/Manual/Guile.html
View file

@ -8,7 +8,7 @@
<body bgcolor="#ffffff">
<H1><a name="Guile"></a>20 SWIG and Guile</H1>
<H1><a name="Guile"></a>21 SWIG and Guile</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -47,7 +47,7 @@
<p>
This section details guile-specific support in SWIG.
<H2><a name="Guile_nn2"></a>20.1 Meaning of "Module"</H2>
<H2><a name="Guile_nn2"></a>21.1 Meaning of "Module"</H2>
<p>
@ -55,7 +55,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"></a>20.2 Using the SCM or GH Guile API</H2>
<H2><a name="Guile_nn3"></a>21.2 Using the SCM or GH Guile API</H2>
<p>The guile module can currently export wrapper files that use the guile GH interface or the
@ -69,7 +69,7 @@ SCM interface is the default. The SCM and GH interface differ greatly in how th
pointers and have completely different run-time code. See below for more info.
<p>The GH interface to guile is deprecated. Read more about why in the
<a href="http://www.gnu.org/software/guile/docs/guile-ref/GH-deprecation.html">Guile manual</a>.
<a href="http://www.gnu.org/software/guile/docs/docs-1.6/guile-ref/GH.html#GH">Guile manual</a>.
The idea of the GH interface was to provide a high level API that other languages and projects
could adopt. This was a good idea, but didn't pan out well for general development. But for the
specific, minimal uses that the SWIG typemaps put the GH interface to use is ideal for
@ -103,7 +103,7 @@ for the specific API. Currently only the guile language module has created a ma
but there is no reason other languages (like mzscheme or chicken) couldn't also use this.
If that happens, there is A LOT less code duplication in the standard typemaps.</p>
<H2><a name="Guile_nn4"></a>20.3 Linkage</H2>
<H2><a name="Guile_nn4"></a>21.3 Linkage</H2>
<p>
@ -111,7 +111,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"></a>20.3.1 Simple Linkage</H3>
<H3><a name="Guile_nn5"></a>21.3.1 Simple Linkage</H3>
<p>
@ -206,7 +206,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"></a>20.3.2 Passive Linkage</H3>
<H3><a name="Guile_nn6"></a>21.3.2 Passive Linkage</H3>
<p>Passive linkage is just like simple linkage, but it generates an
@ -216,7 +216,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"></a>20.3.3 Native Guile Module Linkage</H3>
<H3><a name="Guile_nn7"></a>21.3.3 Native Guile Module Linkage</H3>
<p>SWIG can also generate wrapper code that does all the Guile module
@ -257,7 +257,7 @@ Newer Guile versions have a shorthand procedure for this:
</div>
</ul>
<H3><a name="Guile_nn8"></a>20.3.4 Old Auto-Loading Guile Module Linkage</H3>
<H3><a name="Guile_nn8"></a>21.3.4 Old Auto-Loading Guile Module Linkage</H3>
<p>Guile used to support an autoloading facility for object-code
@ -283,7 +283,7 @@ option, SWIG generates an exported module initialization function with
an appropriate name.
<H3><a name="Guile_nn9"></a>20.3.5 Hobbit4D Linkage</H3>
<H3><a name="Guile_nn9"></a>21.3.5 Hobbit4D Linkage</H3>
<p>
@ -308,7 +308,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"></a>20.4 Underscore Folding</H2>
<H2><a name="Guile_nn10"></a>21.4 Underscore Folding</H2>
<p>
@ -320,7 +320,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"></a>20.5 Typemaps</H2>
<H2><a name="Guile_nn11"></a>21.5 Typemaps</H2>
<p>
@ -409,10 +409,10 @@ See also the "multivalue" example.
%feature("constasvar") can be applied to any constant, immutable variable, or enum.
Instead of exporting the constant as a function that must be called, the
constant will appear as a scheme variable. See
<a href="Customization.html#features">Features and the %feature directive</a>
<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"></a>20.6 Representation of pointers as smobs</H2>
<H2><a name="Guile_nn12"></a>21.6 Representation of pointers as smobs</H2>
<p>
@ -433,7 +433,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_nn13"></a>20.6.1 GH Smobs</H3>
<H3><a name="Guile_nn13"></a>21.6.1 GH Smobs</H3>
<p>
@ -462,7 +462,7 @@ that created them, so the first module we check will most likely be correct.
Once we have a swig_type_info structure, we loop through the linked list of
casts, using pointer comparisons.</p>
<H3><a name="Guile_nn14"></a>20.6.2 SCM Smobs</H3>
<H3><a name="Guile_nn14"></a>21.6.2 SCM Smobs</H3>
<p>The SCM interface (using the "-scm" argument to swig) uses swigrun.swg.
@ -477,7 +477,7 @@ in the smob tag. If a generated GOOPS module has been loaded, smobs will be wra
GOOPS class.</p>
<H3><a name="Guile_nn15"></a>20.6.3 Garbage Collection</H3>
<H3><a name="Guile_nn15"></a>21.6.3 Garbage Collection</H3>
<p>Garbage collection is a feature of the new SCM interface, and it is automatically included
@ -487,11 +487,11 @@ to the destructor for this type. The destructor is the generated wrapper around
So swig still exports a wrapper for the destructor, it just does not call scm_c_define_gsubr() for
the wrapped delete function. So the only way to delete an object is from the garbage collector, since the
delete function is not available to scripts. How swig determines if a type should be garbage collected
is exactly like described in <a href="Customization.html#ownership">
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"></a>20.7 Exception Handling</H2>
<H2><a name="Guile_nn16"></a>21.7 Exception Handling</H2>
<p>
@ -517,7 +517,7 @@ mapping:
The default when not specified here is to use "swig-error".
See Lib/exception.i for details.
<H2><a name="Guile_nn17"></a>20.8 Procedure documentation</H2>
<H2><a name="Guile_nn17"></a>21.8 Procedure documentation</H2>
<p>If invoked with the command-line option <code>-procdoc
@ -553,7 +553,7 @@ like this:
typemap argument <code>doc</code>. See <code>Lib/guile/typemaps.i</code> for
details.
<H2><a name="Guile_nn18"></a>20.9 Procedures with setters</H2>
<H2><a name="Guile_nn18"></a>21.9 Procedures with setters</H2>
<p>For global variables, SWIG creates a single wrapper procedure
@ -581,7 +581,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_nn19"></a>20.10 GOOPS Proxy Classes</H2>
<H2><a name="Guile_nn19"></a>21.10 GOOPS Proxy Classes</H2>
<p>SWIG can also generate classes and generic functions for use with
@ -730,7 +730,7 @@ Notice that &lt;Foo&gt; 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_nn20"></a>20.10.1 Naming Issues</H3>
<H3><a name="Guile_nn20"></a>21.10.1 Naming Issues</H3>
<p>As you can see in the example above, there are potential naming conflicts. The default exported
@ -767,9 +767,7 @@ guile-modules. For example,</p>
(use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:)))
</pre></div>
<p>TODO: Renaming class name prefixes?</p>
<H3><a name="Guile_nn21"></a>20.10.2 Linking</H3>
<H3><a name="Guile_nn21"></a>21.10.2 Linking</H3>
<p>The guile-modules generated above all need to be linked together. GOOPS support requires

15
Doc/Manual/Introduction.html
View file

@ -37,7 +37,7 @@
<p>
SWIG is a software development tool that simplifies the task of
interfacing different languages to C and C++ programs. In a
nutshell, SWIG is a compiler that takes C declarations and creates
nutshell, SWIG is a compiler that takes C/C++ declarations and creates
the wrappers needed to access those declarations from other languages including
including Perl, Python, Tcl, Ruby, Guile, and Java. SWIG normally
requires no modifications to existing code and can often be used to
@ -68,7 +68,8 @@ a dedicated IDL compiler). Although
this style of development isn't appropriate for every
project, it is particularly well suited to software development in the
small; especially the research and development work that is commonly found
in scientific and engineering projects.
in scientific and engineering projects. However, nowadays SWIG is known to be used in many
large open source and commercial projects.
<H2><a name="Introduction_nn3"></a>2.2 Why use SWIG?</H2>
@ -365,7 +366,7 @@ possible to support different types of interfaces depending on the application.
<p>
SWIG is a command line tool and as such can be incorporated into any build system that supports invoking external tools/compilers.
SWIG is most commonly invoked from within a Makefile, but is also known to be invoked from from popular IDEs such as
SWIG is most commonly invoked from within a Makefile, but is also known to be invoked from popular IDEs such as
Microsoft Visual Studio.
</p>
@ -375,10 +376,10 @@ If you are using the GNU Autotools
<a href="http://www.gnu.org/software/automake">Automake</a>/
<a href="http://www.gnu.org/software/libtool">Libtool</a>)
to configure SWIG use in your project, the SWIG Autoconf macros can be used.
The primary macro is <tt>ac_pkg_swig</tt>, see
<a href="http://www.gnu.org/software/ac-archive/htmldoc/ac_pkg_swig.html">http://www.gnu.org/software/ac-archive/htmldoc/ac_pkg_swig.html</a>.
The <tt>ac_python_devel</tt> macro is also helpful for generating Python extensions. See the
<a href="http://www.gnu.org/software/ac-archive/htmldoc/index.html">Autoconf Macro Archive</a>
The primary macro is <tt>ax_pkg_swig</tt>, see
<a href="http://www.gnu.org/software/autoconf-archive/ax_pkg_swig.html#ax_pkg_swig">http://www.gnu.org/software/autoconf-archive/ax_pkg_swig.html#ax_pkg_swig</a>.
The <tt>ax_python_devel</tt> macro is also helpful for generating Python extensions. See the
<a href="http://www.gnu.org/software/autoconf-archive/">Autoconf Archive</a>
for further information on this and other Autoconf macros.
</p>

582
Doc/Manual/Java.html
View file

File diff suppressed because it is too large Load diff

142
Doc/Manual/Library.html
View file

@ -27,9 +27,10 @@
</ul>
<li><a href="#Library_stl_cpp_library">STL/C++ Library</a>
<ul>
<li><a href="#Library_nn14">std_string.i</a>
<li><a href="#Library_nn15">std_vector.i</a>
<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_nn16">Utility Libraries</a>
<ul>
@ -893,7 +894,7 @@ char *foo();
This will release the result if the appropriate target language support is available.
SWIG provides the appropriate "newfree" typemap for <tt>char *</tt> so that the memory is released,
however, you may need to provide your own "newfree" typemap for other types.
See <a href="Customization.html#ownership">Object ownership and %newobject</a> for more details.
See <a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for more details.
</p>
<H3><a name="Library_nn12"></a>8.3.4 cstring.i</H3>
@ -1383,6 +1384,7 @@ The following table shows which C++ classes are supported and the equivalent SWI
<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::vector</td> <td>vector</td> <td>std_vector.i</td> </tr>
<tr> <td>std::shared_ptr</td> <td>shared_ptr</td> <td>std_shared_ptr.i</td> </tr>
</table>
@ -1392,7 +1394,7 @@ Please look for the library files in the appropriate language library directory.
</p>
<H3><a name="Library_nn14"></a>8.4.1 std_string.i</H3>
<H3><a name="Library_std_string"></a>8.4.1 std::string</H3>
<p>
@ -1476,16 +1478,11 @@ void foo(string s, const String &amp;t); // std_string typemaps still applie
</pre>
</div>
<p>
<b>Note:</b> The <tt>std_string</tt> library is incompatible with Perl on some platforms.
We're looking into it.
</p>
<H3><a name="Library_nn15"></a>8.4.2 std_vector.i</H3>
<H3><a name="Library_std_vector"></a>8.4.2 std::vector</H3>
<p>
The <tt>std_vector.i</tt> library provides support for the C++ <tt>vector</tt> class in the STL.
The <tt>std_vector.i</tt> library provides support for the C++ <tt>std::vector</tt> class in the STL.
Using this library involves the use of the <tt>%template</tt> directive. All you need to do is to
instantiate different versions of <tt>vector</tt> for the types that you want to use. For example:
</p>
@ -1660,11 +1657,6 @@ if you want to make their head explode.
details and the public API exposed to the interpreter vary.
</p>
<p>
<b>Note:</b> <tt>std_vector.i</tt> was written by Luigi "The Amazing" Ballabio.
</p>
<H3><a name="Library_stl_exceptions"></a>8.4.3 STL exceptions</H3>
@ -1715,6 +1707,124 @@ 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"></a>8.4.4 shared_ptr smart pointer</H3>
<p>
Some target languages have support for handling the widely used <tt>boost::shared_ptr</tt> smart pointer.
This smart pointer is also available as <tt>std::tr1::shared_ptr</tt> before it becomes fully standardized as <tt>std::shared_ptr</tt>.
The <tt>boost_shared_ptr.i</tt> library provides support for <tt>boost::shared_ptr</tt> and <tt>std_shared_ptr.i</tt> provides support for <tt>std::shared_ptr</tt>, but if the following macro is defined as shown, it can be used for <tt>std::tr1::shared_ptr</tt>:
</p>
<div class="code">
<pre>
#define SWIG_SHARED_PTR_SUBNAMESPACE tr1
%include &lt;std_shared_ptr.i&gt;
</pre>
</div>
<p>
You can only use one of these variants of shared_ptr in your interface file at a time.
and all three variants must be used in conjunction with the <tt>%shared_ptr(T)</tt> macro,
where <tt>T</tt> is the underlying pointer type equating to usage <tt>shared_ptr&lt;T&gt;</tt>.
The type <tt>T</tt> must be non-primitive.
A simple example demonstrates usage:
</p>
<div class="code">
<pre>
%module example
%include &lt;boost_shared_ptr.i&gt;
%shared_ptr(IntValue)
%inline %{
#include &lt;boost/shared_ptr.hpp&gt;
struct IntValue {
int value;
IntValue(int v) : value(v) {}
};
static int extractValue(const IntValue &amp;t) {
return t.value;
}
static int extractValueSmart(boost::shared_ptr&lt;IntValue&gt; t) {
return t-&gt;value;
}
%}
</pre>
</div>
<p>
Note that the <tt>%shared_ptr(IntValue)</tt> declaration occurs after the inclusion of the <tt>boost_shared_ptr.i</tt>
library which provides the macro and, very importantly, before any usage or declaration of the type, <tt>IntValue</tt>.
The <tt>%shared_ptr</tt> macro provides, a few things for handling this smart pointer, but mostly a number of
typemaps. These typemaps override the default typemaps so that the underlying proxy class is stored and passed around
as a pointer to a <tt>shared_ptr</tt> instead of a plain pointer to the underlying type.
This approach means that any instantiation of the type can be passed to methods taking the type by value, reference, pointer
or as a smart pointer.
The interested reader might want to look at the generated code, however, usage is simple and no different
handling is required from the target language.
For example, a simple use case of the above code from Java would be:
</p>
<div class="targetlang">
<pre>
IntValue iv = new IntValue(1234);
int val1 = example.extractValue(iv);
int val2 = example.extractValueSmart(iv);
System.out.println(val1 + " " + val2);
</pre>
</div>
<p>
This 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.
The only real change introduced by the <tt>%shared_ptr</tt> macro is that the proxy class stores a pointer to the shared_ptr instance instead of a raw pointer to the instance.
A proxy class derived from a base which is being wrapped with shared_ptr can and <b>must</b> be wrapped as a shared_ptr too.
In other words all classes in an inheritance hierarchy must all be used with the <tt>%shared_ptr</tt> macro.
For example the following code can be used with the base class shown earlier:
</p>
<div class="code">
<pre>
%shared_ptr(DerivedIntValue)
%inline %{
struct DerivedIntValue : IntValue {
DerivedIntValue(int value) : IntValue(value) {}
...
};
%}
</pre>
</div>
<p>
Note that if the <tt>%shared_ptr</tt> macro is omitted for any class in the inheritance hierarchy, it will
result in a C++ compiler error.
For example if the above <tt>%shared_ptr(DerivedIntValue)</tt> is omitted, the following is typical of the compiler error that will result:
</p>
<div class="shell">
<pre>
example_wrap.cxx: In function 'void Java_exampleJNI_delete_1DerivedIntValue(JNIEnv*, _jclass*, jlong)':
example_wrap.cxx:3169: error: 'smartarg1' was not declared in this scope
</pre>
</div>
<p>
A shared_ptr of the derived class can now be passed to a method where the base is expected in the target language, just as it can in C++:
</p>
<div class="targetlang">
<pre>
DerivedIntValue div = new DerivedIntValue(5678);
int val3 = example.extractValue(div);
int val4 = example.extractValueSmart(div);
</pre>
</div>
<H2><a name="Library_nn16"></a>8.5 Utility Libraries</H2>

30
Doc/Manual/Lisp.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Lisp_nn1"></a>22 SWIG and Common Lisp</H1>
<H1><a name="Lisp"></a>23 SWIG and Common Lisp</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -41,16 +41,16 @@
Lisp, Common Foreign Function Interface(CFFI), CLisp and UFFI
foreign function interfaces.
</p>
<H2><a name="Lisp_nn2"></a>22.1 Allegro Common Lisp</H2>
<H2><a name="Lisp_nn2"></a>23.1 Allegro Common Lisp</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_nn1">here</a>
<a href="Allegrocl.html#Allegrocl">here</a>
</p>
<H2><a name="Lisp_nn3"></a>22.2 Common Foreign Function Interface(CFFI)</H2>
<H2><a name="Lisp_nn3"></a>23.2 Common Foreign Function Interface(CFFI)</H2>
<p>
@ -77,7 +77,7 @@ swig -cffi -module <i>module-name</i> <i>file-name</i>
files and the various things which you can do with them.
</p>
<H3><a name="Lisp_nn4"></a>22.2.1 Additional Commandline Options </H3>
<H3><a name="Lisp_nn4"></a>23.2.1 Additional Commandline Options </H3>
<p>
@ -96,14 +96,14 @@ swig -cffi -help
<tr>
<td>-generate-typedef</td>
<td>If this option is given then defctype will be used to generate<br\>
<td>If this option is given then defctype will be used to generate<br/>
shortcuts according to the typedefs in the input.
</td>
</tr>
<tr>
<td>-[no]cwrap</td>
<td>Turn on or turn off generation of an intermediate C file when<br\>
<td>Turn on or turn off generation of an intermediate C file when<br/>
creating a C interface. By default this is only done for C++ code.
</td>
</tr>
@ -118,7 +118,7 @@ swig -cffi -help
</table>
<H3><a name="Lisp_nn5"></a>22.2.2 Generating CFFI bindings</H3>
<H3><a name="Lisp_nn5"></a>23.2.2 Generating CFFI bindings</H3>
As we mentioned earlier the ideal way to use SWIG is to use interface
@ -269,7 +269,7 @@ The generated SWIG Code will be:
want to lispify the names, also, before we forget you want to
export the generated lisp names. To do this, we will use the
SWIG <a
href="Customization.html#features">feature directive</a>.
href="Customization.html#Customization_features">feature directive</a>.
Let's edit the interface file such that the C type "div_t*" is changed
to Lisp type ":my-pointer", we lispify all names,
export everything, and do some more stuff.
@ -392,7 +392,7 @@ The feature <i>intern_function</i> ensures that all C names are
</pre></div>
<H3><a name="Lisp_nn6"></a>22.2.3 Generating CFFI bindings for C++ code</H3>
<H3><a name="Lisp_nn6"></a>23.2.3 Generating CFFI bindings for C++ code</H3>
<p>This feature to SWIG (for CFFI) is very new and still far from
@ -568,7 +568,7 @@ If you have any questions, suggestions, patches, etc., related to CFFI
module feel free to contact us on the SWIG mailing list, and
also please add a "[CFFI]" tag in the subject line.
<H3><a name="Lisp_nn7"></a>22.2.4 Inserting user code into generated files</H3>
<H3><a name="Lisp_nn7"></a>23.2.4 Inserting user code into generated files</H3>
<p>
@ -608,7 +608,7 @@ Note that the block <tt>%{ ... %}</tt> is effectively a shortcut for
</p>
<H2><a name="Lisp_nn8"></a>22.3 CLISP</H2>
<H2><a name="Lisp_nn8"></a>23.3 CLISP</H2>
<p>
@ -638,7 +638,7 @@ swig -clisp -module <i>module-name</i> <i>file-name</i>
interface file for the CLISP module. The CLISP module tries to
produce code which is both human readable and easily modifyable.
</p>
<H3><a name="Lisp_nn9"></a>22.3.1 Additional Commandline Options </H3>
<H3><a name="Lisp_nn9"></a>23.3.1 Additional Commandline Options </H3>
<p>
@ -671,7 +671,7 @@ and global variables will be created otherwise only definitions for<br/>
</table>
<H3><a name="Lisp_nn10"></a>22.3.2 Details on CLISP bindings</H3>
<H3><a name="Lisp_nn10"></a>23.3.2 Details on CLISP bindings</H3>
<p>
@ -795,7 +795,7 @@ struct bar {
</pre></div>
<H2><a name="Lisp_nn11"></a>22.4 UFFI </H2>
<H2><a name="Lisp_nn11"></a>23.4 UFFI </H2>
</body>

82
Doc/Manual/Lua.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Lua_nn1"></a>23 SWIG and Lua</H1>
<H1><a name="Lua"></a>24 SWIG and Lua</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -67,13 +67,13 @@
<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++). Its also a <em>really</em> tiny language, less than 6000 lines of code, which compiles to &lt;100 kilobytes of binary code. It can be found at <a href="http://www.lua.org">http://www.lua.org</a>
</p>
<H2><a name="Lua_nn2"></a>23.1 Preliminaries</H2>
<H2><a name="Lua_nn2"></a>24.1 Preliminaries</H2>
<p>
The current SWIG implementation is designed to work with Lua 5.0.x and Lua 5.1.x. It should work with later versions of Lua, but certainly not with Lua 4.0 due to substantial API changes. ((Currently SWIG generated code has only been tested on Windows with MingW, though given the nature of Lua, is should not have problems on other OS's)). It is possible to either static link or dynamic link a Lua module into the interpreter (normally Lua static links its libraries, as dynamic linking is not available on all platforms).
</p>
<H2><a name="Lua_nn3"></a>23.2 Running SWIG</H2>
<H2><a name="Lua_nn3"></a>24.2 Running SWIG</H2>
<p>
@ -105,7 +105,7 @@ This creates a C/C++ source file <tt>example_wrap.c</tt> or <tt>example_wrap.cxx
<p>
The name of the wrapper file is derived from the name of the input file. For example, if the input file is <tt>example.i</tt>, the name of the wrapper file is <tt>example_wrap.c</tt>. To change this, you can use the -o option. The wrappered module will export one function <tt>"int luaopen_example(lua_State* L)"</tt> which must be called to register the module with the Lua interpreter. The name "luaopen_example" depends upon the name of the module.
</p>
<H3><a name="Lua_nn4"></a>23.2.1 Compiling and Linking and Interpreter</H3>
<H3><a name="Lua_nn4"></a>24.2.1 Compiling and Linking and Interpreter</H3>
<p>
@ -152,7 +152,7 @@ $ gcc -c example.c -o example.o
$ gcc -I/usr/include/lua -L/usr/lib/lua min.o example_wrap.o example.o -o my_lua
</pre></div>
<H3><a name="Lua_nn5"></a>23.2.2 Compiling a dynamic module</H3>
<H3><a name="Lua_nn5"></a>24.2.2 Compiling a dynamic module</H3>
<p>
@ -220,7 +220,7 @@ Is quite obvious (Go back and consult the Lua documents on how to enable loadlib
<H3><a name="Lua_nn6"></a>23.2.3 Using your module</H3>
<H3><a name="Lua_nn6"></a>24.2.3 Using your module</H3>
<p>
@ -238,19 +238,19 @@ $ ./my_lua
&gt;
</pre></div>
<H2><a name="Lua_nn7"></a>23.3 A tour of basic C/C++ wrapping</H2>
<H2><a name="Lua_nn7"></a>24.3 A tour of basic C/C++ wrapping</H2>
<p>
By default, SWIG tries to build a very natural Lua interface to your C/C++ code. This section briefly covers the essential aspects of this wrapping.
</p>
<H3><a name="Lua_nn8"></a>23.3.1 Modules</H3>
<H3><a name="Lua_nn8"></a>24.3.1 Modules</H3>
<p>
The SWIG module directive specifies the name of the Lua module. If you specify `module example', then everything is wrapped into a Lua table 'example' containing all the functions and variables. When choosing a module name, make sure you don't use the same name as a built-in Lua command or standard module name.
</p>
<H3><a name="Lua_nn9"></a>23.3.2 Functions</H3>
<H3><a name="Lua_nn9"></a>24.3.2 Functions</H3>
<p>
@ -288,7 +288,7 @@ It is also possible to rename the module with an assignment.
24
</pre></div>
<H3><a name="Lua_nn10"></a>23.3.3 Global variables</H3>
<H3><a name="Lua_nn10"></a>24.3.3 Global variables</H3>
<p>
@ -334,7 +334,7 @@ extern double Foo;
%mutable;
</pre></div>
<p>
SWIG will allow the the reading of <tt>Foo</tt> but when a set attempt is made, an error function will be called.
SWIG will allow the reading of <tt>Foo</tt> but when a set attempt is made, an error function will be called.
</p>
<div class="targetlang"><pre>
&gt; print(e.Foo) -- reading works ok
@ -362,7 +362,7 @@ nil
3.142
</pre></div>
<H3><a name="Lua_nn11"></a>23.3.4 Constants and enums</H3>
<H3><a name="Lua_nn11"></a>24.3.4 Constants and enums</H3>
<p>
@ -385,7 +385,7 @@ example.SUNDAY=0
<p>
Constants are not guaranteed to remain constant in Lua. The name of the constant could be accidentally reassigned to refer to some 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="Lua_nn12"></a>23.3.5 Pointers</H3>
<H3><a name="Lua_nn12"></a>24.3.5 Pointers</H3>
<p>
@ -423,7 +423,7 @@ Lua enforces the integrity of its userdata, so it is virtually impossible to cor
nil
</pre></div>
<H3><a name="Lua_nn13"></a>23.3.6 Structures</H3>
<H3><a name="Lua_nn13"></a>24.3.6 Structures</H3>
<p>
@ -509,7 +509,7 @@ Because the pointer points inside the structure, you can modify the contents and
&gt; x.a = 3 -- Modifies the same structure
</pre></div>
<H3><a name="Lua_nn14"></a>23.3.7 C++ classes</H3>
<H3><a name="Lua_nn14"></a>24.3.7 C++ classes</H3>
<p>
@ -570,7 +570,7 @@ It is not (currently) possible to access static members of an instance:
-- does NOT work
</pre></div>
<H3><a name="Lua_nn15"></a>23.3.8 C++ inheritance</H3>
<H3><a name="Lua_nn15"></a>24.3.8 C++ inheritance</H3>
<p>
@ -595,7 +595,7 @@ then the function <tt>spam()</tt> accepts a Foo pointer or a pointer to any clas
<p>
It is safe to use multiple inheritance with SWIG.
</p>
<H3><a name="Lua_nn16"></a>23.3.9 Pointers, references, values, and arrays</H3>
<H3><a name="Lua_nn16"></a>24.3.9 Pointers, references, values, and arrays</H3>
<p>
@ -626,7 +626,7 @@ Foo spam7();
<p>
then all three functions will return a pointer to some Foo object. Since the third function (spam7) returns a value, newly allocated memory is used to hold the result and a pointer is returned (Lua will release this memory when the return value is garbage collected). The other two are pointers which are assumed to be managed by the C code and so will not be garbage collected.
</p>
<H3><a name="Lua_nn17"></a>23.3.10 C++ overloaded functions</H3>
<H3><a name="Lua_nn17"></a>24.3.10 C++ overloaded functions</H3>
<p>
@ -712,7 +712,7 @@ Please refer to the "SWIG and C++" chapter for more information about overloadin
<p>
Dealing with the Lua coercion mechanism, the priority is roughly (integers, floats, strings, userdata). But it is better to rename the functions rather than rely upon the ordering.
</p>
<H3><a name="Lua_nn18"></a>23.3.11 C++ operators</H3>
<H3><a name="Lua_nn18"></a>24.3.11 C++ operators</H3>
<p>
@ -824,7 +824,7 @@ It is also possible to overload the operator<tt>[]</tt>, but currently this cann
};
</pre></div>
<H3><a name="Lua_nn19"></a>23.3.12 Class extension with %extend</H3>
<H3><a name="Lua_nn19"></a>24.3.12 Class extension with %extend</H3>
<p>
@ -879,7 +879,7 @@ true
<p>
Extend works with both C and C++ code, on classes and structs. It does not modify the underlying object in any way---the extensions only show up in the Lua interface. The only item to take note of is the code has to use the '$self' instead of 'this', and that you cannot access protected/private members of the code (as you are not officially part of the class).
</p>
<H3><a name="Lua_nn20"></a>23.3.13 C++ templates</H3>
<H3><a name="Lua_nn20"></a>24.3.13 C++ templates</H3>
<p>
@ -914,7 +914,7 @@ In Lua:
<p>
Obviously, there is more to template wrapping than shown in this example. More details can be found in the SWIG and C++ chapter. Some more complicated examples will appear later.
</p>
<H3><a name="Lua_nn21"></a>23.3.14 C++ Smart Pointers</H3>
<H3><a name="Lua_nn21"></a>24.3.14 C++ Smart Pointers</H3>
<p>
@ -966,7 +966,7 @@ If you ever need to access the underlying pointer returned by <tt>operator-&gt;(
&gt; f = p:__deref__() -- Returns underlying Foo *
</pre></div>
<H3><a name="Lua_nn22"></a>23.3.15 C++ Exceptions</H3>
<H3><a name="Lua_nn22"></a>24.3.15 C++ Exceptions</H3>
<p>
@ -1099,23 +1099,23 @@ userdata: 0003D880
</pre></div>
<p>
Note: is is also possible (though tedious) to have a function throw several different kinds of exceptions. To process this
Note: it is also possible (though tedious) to have a function throw several different kinds of exceptions. To process this
will require a pcall, followed by a set of if statements checking the type of the error.
</p>
<p>
All of this code assumes that your C++ code uses exception specification (which a lot doesn't).
If it doesn't consult the "<a href="SWIGPlus.html#SWIGPlus_catches">Exception handling with %catches</a>" section
and the "<a href="Customization.html#exception">Exception handling with %exception</a>" section, for more details on how to
and the "<a href="Customization.html#Customization_exception">Exception handling with %exception</a>" section, for more details on how to
add exception specification to functions or globally (respectively).
</p>
<H2><a name="Lua_nn23"></a>23.4 Typemaps</H2>
<H2><a name="Lua_nn23"></a>24.4 Typemaps</H2>
<p>This section explains what typemaps are and the usage of them. The default wrappering behaviour of SWIG is enough in most cases. However sometimes SWIG may need a little additional assistance to know which typemap to apply to provide the best wrappering. This section will be explaining how to use typemaps to best effect</p>
<H3><a name="Lua_nn24"></a>23.4.1 What is a typemap?</H3>
<H3><a name="Lua_nn24"></a>24.4.1 What is a typemap?</H3>
<p>A typemap is nothing more than a code generation rule that is attached to a specific C datatype. For example, to convert integers from Lua to C, you might define a typemap like this:</p>
@ -1143,7 +1143,7 @@ Received an integer : 6
720
</pre></div>
<H3><a name="Lua_nn25"></a>23.4.2 Using typemaps</H3>
<H3><a name="Lua_nn25"></a>24.4.2 Using typemaps</H3>
<p>There are many ready written typemaps built into SWIG for all common types (int, float, short, long, char*, enum and more), which SWIG uses automatically, with no effort required on your part.</p>
@ -1196,7 +1196,7 @@ void swap(int *sx, int *sy);
<p>Note: C++ references must be handled exactly the same way. However SWIG will automatically wrap a <tt>const int&amp;</tt> as an input parameter (since that it obviously input).</p>
<H3><a name="Lua_nn26"></a>23.4.3 Typemaps and arrays</H3>
<H3><a name="Lua_nn26"></a>24.4.3 Typemaps and arrays</H3>
<p>Arrays present a challenge for SWIG, because like pointers SWIG does not know whether these are input or output values, nor
@ -1210,7 +1210,7 @@ extern void sort_double(double* arr, int len);
<p>There are basically two ways that SWIG can deal with this. The first way, uses the <tt>&lt;carrays.i&gt;</tt> library
to create an array in C/C++ then this can be filled within Lua and passed into the function. It works, but its a bit tedious.
More details can be found in the <a href="Library.html#Library_nn5">carrays.i</a> documention.</p>
More details can be found in the <a href="Library.html#Library_carrays">carrays.i</a> documention.</p>
<p>The second and more intuitive way, would be to pass a Lua table directly into the function, and have SWIG automatically convert between Lua-table and C-array. Within the <tt>&lt;typemaps.i&gt;</tt> file there are typemaps ready written to perform this task. To use them is again a matter of using %appy in the correct manner.</p>
@ -1260,7 +1260,7 @@ and Lua tables to be 1..N, (the indexing follows the norm for the language). In
<p>Note: SWIG also can support arrays of pointers in a similar manner.</p>
<H3><a name="Lua_nn27"></a>23.4.4 Typemaps and pointer-pointer functions</H3>
<H3><a name="Lua_nn27"></a>24.4.4 Typemaps and pointer-pointer functions</H3>
<p>Several C++ libraries use a pointer-pointer functions to create its objects. These functions require a pointer to a pointer which is then filled with the pointer to the new object. Microsoft's COM and DirectX as well as many other libraries have this kind of function. An example is given below:</p>
@ -1294,7 +1294,7 @@ int Create_Math(iMath** pptr); // its creator (assume it mallocs)
ptr=nil -- the iMath* will be GC'ed as normal
</pre></div>
<H2><a name="Lua_nn28"></a>23.5 Writing typemaps</H2>
<H2><a name="Lua_nn28"></a>24.5 Writing typemaps</H2>
<p>This section describes how you can modify SWIG's default wrapping behavior for various C/C++ datatypes using the <tt>%typemap</tt> directive. This is an advanced topic that assumes familiarity with the Lua C API as well as the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter.</p>
@ -1303,7 +1303,7 @@ ptr=nil -- the iMath* will be GC'ed as normal
<p>Before proceeding, you should read the previous section on using typemaps, as well as read the ready written typemaps found in luatypemaps.swg and typemaps.i. These are both well documented and fairly easy to read. You should not attempt to write your own typemaps until you have read and can understand both of these files (they may well also give you a idea to base your worn on).</p>
<H3><a name="Lua_nn29"></a>23.5.1 Typemaps you can write</H3>
<H3><a name="Lua_nn29"></a>24.5.1 Typemaps you can write</H3>
<p>There are many different types of typemap that can be written, the full list can be found in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. However the following are the most commonly used ones.</p>
@ -1316,7 +1316,7 @@ ptr=nil -- the iMath* will be GC'ed as normal
(the syntax for the typecheck is different from the typemap, see typemaps for details).</li>
</ul>
<H3><a name="Lua_nn30"></a>23.5.2 SWIG's Lua-C API</H3>
<H3><a name="Lua_nn30"></a>24.5.2 SWIG's Lua-C API</H3>
<p>This section explains the SWIG specific Lua-C API. It does not cover the main Lua-C api, as this is well documented and not worth covering.</p>
@ -1365,7 +1365,7 @@ This macro, when called within the context of a SWIG wrappered function, will di
<div class="indent">
Similar to SWIG_fail_arg, except that it will display the swig_type_info information instead.</div>
<H2><a name="Lua_nn31"></a>23.6 Customization of your Bindings</H2>
<H2><a name="Lua_nn31"></a>24.6 Customization of your Bindings</H2>
<p>
@ -1374,7 +1374,7 @@ This section covers adding of some small extra bits to your module to add the la
<H3><a name="Lua_nn32"></a>23.6.1 Writing your own custom wrappers</H3>
<H3><a name="Lua_nn32"></a>24.6.1 Writing your own custom wrappers</H3>
<p>
@ -1393,7 +1393,7 @@ int native_function(lua_State*L) // my native code
The <tt>%native</tt> directive in the above example, tells SWIG that there is a function <tt>int native_function(lua_State*L);</tt> which is to be added into the module under the name '<tt>my_func</tt>'. SWIG will not add any wrappering for this function, beyond adding it into the function table. How you write your code is entirely up to you.
</p>
<H3><a name="Lua_nn33"></a>23.6.2 Adding additional Lua code</H3>
<H3><a name="Lua_nn33"></a>24.6.2 Adding additional Lua code</H3>
<p>
@ -1431,7 +1431,7 @@ Good uses for this feature is adding of new code, or writing helper functions to
See Examples/lua/arrays for an example of this code.
</p>
<H2><a name="Lua_nn34"></a>23.7 Details on the Lua binding</H2>
<H2><a name="Lua_nn34"></a>24.7 Details on the Lua binding</H2>
<p>
@ -1442,7 +1442,7 @@ See Examples/lua/arrays for an example of this code.
</i>
</p>
<H3><a name="Lua_nn35"></a>23.7.1 Binding global data into the module.</H3>
<H3><a name="Lua_nn35"></a>24.7.1 Binding global data into the module.</H3>
<p>
@ -1502,7 +1502,7 @@ end
<p>
That way when you call '<tt>a=example.Foo</tt>', the interpreter looks at the table 'example' sees that there is no field 'Foo' and calls __index. This will in turn check in '.get' table and find the existence of 'Foo' and then return the value of the C function call 'Foo_get()'. Similarly for the code '<tt>example.Foo=10</tt>', the interpreter will check the table, then call the __newindex which will then check the '.set' table and call the C function 'Foo_set(10)'.
</p>
<H3><a name="Lua_nn36"></a>23.7.2 Userdata and Metatables</H3>
<H3><a name="Lua_nn36"></a>24.7.2 Userdata and Metatables</H3>
<p>
@ -1582,7 +1582,7 @@ Note: Both the opaque structures (like the FILE*) and normal wrappered classes/s
<p>
Note: Operator overloads are basically done in the same way, by adding functions such as '__add' &amp; '__call' to the classes metatable. The current implementation is a bit rough as it will add any member function beginning with '__' into the metatable too, assuming its an operator overload.
</p>
<H3><a name="Lua_nn37"></a>23.7.3 Memory management</H3>
<H3><a name="Lua_nn37"></a>24.7.3 Memory management</H3>
<p>

21
Doc/Manual/Makefile
View file

@ -9,6 +9,7 @@
# validation.
#
# Additional html validation can be done using the validate target.
# Additional link checking can be done using the linkchecker target.
#
# Note the # and " are escaped
@ -28,9 +29,9 @@ CCache.html: ../../CCache/ccache.yo
# it is just used as a primitive HTML checker.
# CCache.html is generated by yodl2html and has a few insignificant problems, so we don't put it through tidy
check:
tidy -errors --gnu-emacs yes -quiet index.html
tidy -errors --gnu-emacs yes -quiet Sections.html
all=`sed '/^#/d' chapters | grep -v CCache.html`; for a in $$all; do tidy -errors --gnu-emacs yes -quiet $$a; done;
tidy -errors --gnu-emacs yes -quiet index.html
tidy -errors --gnu-emacs yes -quiet Sections.html
all=`sed '/^#/d' chapters | grep -v CCache.html`; for a in $$all; do tidy -errors --gnu-emacs yes -quiet $$a; done;
generate: swightml.book swigpdf.book
htmldoc --batch swightml.book || true
@ -49,7 +50,7 @@ swightml.book:
echo "Sections.html" >> swightml.book
cat chapters >> swightml.book
clean: clean-baks
maintainer-clean: clean-baks
rm -f swightml.book
rm -f swigpdf.book
rm -f CCache.html
@ -60,11 +61,15 @@ clean-baks:
rm -f *.bak
test:
grep "href=\".*\.html\"" index.html
grep "href=\".*\.html\"" Sections.html
all=`sed '/^#/d' chapters`; for a in $$all; do grep -l "href=\".*\.html\"" $$a; done;
grep "href=\".*\.html\"" index.html
grep "href=\".*\.html\"" Sections.html
all=`sed '/^#/d' chapters`; for a in $$all; do grep -l "href=\".*\.html\"" $$a; done;
# Validating using the WDG offline validator - http://www.htmlhelp.com/tools/validator/offline/
validate:
all=`sed '/^#/d' chapters`; for a in $$all; do validate --emacs $$a; done;
all=`sed '/^#/d' chapters`; for a in $$all; do validate --emacs $$a; done;
# Link checking using linkchecker (can take a while - 30 mins)
linkchecker:
linkchecker --anchors Contents.html

279
Doc/Manual/Modula3.html
View file

@ -5,42 +5,39 @@
<link rel="stylesheet" type="text/css" href="style.css">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="Modula3"></a>24 SWIG and Modula-3</H1>
<H1><a name="Modula3"></a>25 SWIG and Modula-3</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#modula3_overview">Overview</a>
<li><a href="#Modula3_modula3_overview">Overview</a>
<ul>
<li><a href="#whyscripting">Why not scripting ?</a>
<li><a href="#whymodula3">Why Modula-3 ?</a>
<li><a href="#whycpp">Why C / C++ ?</a>
<li><a href="#whyswig">Why SWIG ?</a>
<li><a href="#Modula3_motivation">Motivation</a>
</ul>
<li><a href="#conception">Conception</a>
<li><a href="#Modula3_conception">Conception</a>
<ul>
<li><a href="#cinterface">Interfaces to C libraries</a>
<li><a href="#cppinterface">Interfaces to C++ libraries</a>
<li><a href="#Modula3_cinterface">Interfaces to C libraries</a>
<li><a href="#Modula3_cppinterface">Interfaces to C++ libraries</a>
</ul>
<li><a href="#preliminaries">Preliminaries</a>
<li><a href="#Modula3_preliminaries">Preliminaries</a>
<ul>
<li><a href="#compilers">Compilers</a>
<li><a href="#commandline">Additional Commandline Options</a>
<li><a href="#Modula3_compilers">Compilers</a>
<li><a href="#Modula3_commandline">Additional Commandline Options</a>
</ul>
<li><a href="#modula3_typemaps">Modula-3 typemaps</a>
<li><a href="#Modula3_typemaps">Modula-3 typemaps</a>
<ul>
<li><a href="#inoutparam">Inputs and outputs</a>
<li><a href="#ordinals">Subranges, Enumerations, Sets</a>
<li><a href="#class">Objects</a>
<li><a href="#imports">Imports</a>
<li><a href="#exceptions">Exceptions</a>
<li><a href="#typemap_example">Example</a>
<li><a href="#Modula3_inoutparam">Inputs and outputs</a>
<li><a href="#Modula3_ordinals">Subranges, Enumerations, Sets</a>
<li><a href="#Modula3_class">Objects</a>
<li><a href="#Modula3_imports">Imports</a>
<li><a href="#Modula3_exceptions">Exceptions</a>
<li><a href="#Modula3_typemap_example">Example</a>
</ul>
<li><a href="#hints">More hints to the generator</a>
<li><a href="#Modula3_hints">More hints to the generator</a>
<ul>
<li><a href="#features">Features</a>
<li><a href="#pragmas">Pragmas</a>
<li><a href="#Modula3_features">Features</a>
<li><a href="#Modula3_pragmas">Pragmas</a>
</ul>
<li><a href="#remarks">Remarks</a>
<li><a href="#Modula3_remarks">Remarks</a>
</ul>
</div>
<!-- INDEX -->
@ -49,24 +46,29 @@
<p>
This chapter describes SWIG's support of
<a href="http://www.m3.org/">Modula-3</a>.
<a href="http://modula3.org/">Modula-3</a>.
You should be familiar with the
<a href="SWIG.html#SWIG">basics</a>
of SWIG,
especially
<a href="Typemaps.html">typemaps</a>.
<a href="Typemaps.html#Typemaps">typemaps</a>.
</p>
<H2><a name="modula3_overview"></a>24.1 Overview</H2>
<H2><a name="Modula3_modula3_overview"></a>25.1 Overview</H2>
<p>
The Modula-3 support is very basic and highly experimental!
Modula-3 is a compiled language in the tradition of Niklaus Wirth's Modula 2,
which is in turn a successor to Pascal.
</p>
<p>
SWIG's Modula-3 support is currently very basic and highly experimental!
Many features are still not designed satisfyingly
and I need more discussion about the odds and ends.
Don't rely on any feature, incompatible changes are likely in the future!
The Modula-3 generator was already useful for interfacing
to the libraries
However, the Modula-3 generator was already useful for interfacing
to the libraries:
</p>
<ol>
@ -78,130 +80,34 @@ PLPlot
<li>
<a href="http://www.elegosoft.com/cgi-bin/cvsweb.cgi/cm3/m3-libs/fftw/">
FFTW
</a> .
</a>
</li>
</ol>
<p>
I took some more time to explain
why I think it's right what I'm doing.
So the introduction got a bit longer than it should ... ;-)
</p>
<H3><a name="whyscripting"></a>24.1.1 Why not scripting ?</H3>
<H3><a name="Modula3_motivation"></a>25.1.1 Motivation</H3>
<p>
SWIG started as wrapper from the fast compiled languages C and C++
to high level scripting languages like Python.
Although scripting languages are designed
to make programming life easier
by hiding machine internals from the programmer
there are several aspects of today's scripting languages
that are unfavourable in my opinion.
Although it is possible to write Modula-3 code that performs as well as C/C++
most existing libraries are not written in Modula-3 but in C or C++, and
even libraries in other languages may provide C header files.
</p>
<p>
Besides C, C++, Cluster (a Modula derivate for Amiga computers)
I evaluated several scripting like languages in the past:
Different dialects of BASIC,
Perl, ARexx (a variant of Rexx for Amiga computers),
shell scripts.
I found them too inconsistent,
too weak in distinguishing types,
too weak in encapsulating pieces of code.
Eventually I have started several projects in Python
because of the fine syntax.
But when projects became larger
I lost the track.
I got convinced that one can not have
maintainable code in a language
that is not statically typed.
In fact the main advantages of scripting languages
e.g. matching regular expressions,
complex built-in datatypes like lists, dictionaries,
are not advantages of the language itself
but can be provided by function libraries.
</p>
<H3><a name="whymodula3"></a>24.1.2 Why Modula-3 ?</H3>
<p>
Modula-3 is a compiler language
in the tradition of Niklaus Wirth's Modula 2,
which is in turn a successor of the popular Pascal.
I have chosen Modula-3
because of its
logical syntax,
strong modularization,
the type system which is very detailed
for machine types compared to other languages.
Of course it supports all of the modern games
like exceptions, objects, garbage collection, threads.
While C++ programmers must
control three languages,
namely the preprocessor, C and ++,
Modula-3 is made in one go
and the language definition is really compact.
Fortunately Modula-3 can call C functions, but you have to write Modula-3
interfaces to them, and to make things comfortable you will also need
wrappers that convert between high-level features of Modula-3 (garbage
collecting, exceptions) and the explicit tracking of allocated memory and
exception codes used by C APIs.
</p>
<p>
On the one hand Modula-3 can be safe
(but probably less efficient) in normal modules
while providing much static and dynamic safety.
On the other hand you can write efficient
but less safe code in the style of C
within <tt>UNSAFE</tt> modules.
SWIG converts C headers to Modula-3 interfaces for you, and using typemaps
you can pass <tt>TEXT</tt>s or open arrays, and convert error return codes
into exceptions.
</p>
<p>
Unfortunately Modula's safety and strength
requires more writing than scripting languages do.
Today if I want to safe characters
I prefer Haskell (similar to OCAML) -
it's statically typed, too.
</p>
<H3><a name="whycpp"></a>24.1.3 Why C / C++ ?</H3>
<p>
Although it is no problem to write Modula-3 programs
that performs as fast as C
most libraries are not written in Modula-3 but in C.
Fortunately the binary interface of most function libraries
can be addressed by Modula-3.
Even more fortunately even non-C libraries may provide C header files.
This is where SWIG becomes helpful.
</p>
<H3><a name="whyswig"></a>24.1.4 Why SWIG ?</H3>
<p>
The C headers and the possibility to interface to C libraries
still leaves the work for you
to write Modula-3 interfaces to them.
To make things comfortable you will also need
wrappers that convert between high-level features of Modula-3
(garbage collecting, exceptions)
and the low level of the C libraries.
</p>
<p>
SWIG converts C headers to Modula-3 interfaces for you.
You could call the C functions without loss
of efficiency but it won't be joy
because you could not pass <tt>TEXT</tt>s
or open arrays and
you would have to process error return codes
rather then exceptions.
But using some typemaps SWIG will also generate
wrappers that bring the whole Modula-3 comfort to you.
If the library API is ill designed
writing appropriate typemaps can be still time-consuming.
E.g. C programmers are very creative to work-around
@ -211,55 +117,28 @@ otherwise you lose static safety and consistency.
</p>
<p>
But you have still a problem:
C library interfaces are often ill.
They lack for certain information
because C compilers wouldn't care about.
You should integrate detailed type information
by adding <tt>typedef</tt>s and <tt>const</tt>s
and you should persuade the C library programmer
to add this information to his interface.
Only this way other language users can benefit from your work
and only this way you can easily update your interfaces
when a new library version is released.
You will realise that writing <b>good</b> SWIG interfaces
is very costly and it will only amortise
when considering evolving libraries.
</p>
<p>
Without SWIG you would probably never consider
to call C++ libraries from Modula-3.
But with SWIG this is worth a consideration.
SWIG can write C wrappers to C++ functions and object methods
that may throw exceptions.
In fact it breaks down C++ libraries to C interfaces
which can be in turn called from Modula-3.
To make it complete you can hide the C interface
with Modula-3 classes and exceptions.
Without SWIG you would probably never consider trying to call C++ libraries
from Modula-3, but with SWIG this is becomes feasible.
SWIG can generate C wrappers to C++ functions and object methods
that may throw exceptions, and then wrap these C wrappers for Module-3.
To make it complete you can then hide the C interface with Modula-3 classes and
exceptions.
</p>
<p>
Although SWIG does the best it can do
it can only serve as a one-way strategy.
That means you can use C++ libraries
with Modula-3 (even with call back functions),
but it's certainly not possible to smoothly
integrate Modula-3 code into a C / C++ project.
SWIG allows you to call C and C++ libraries from Modula-3 (even with call back
functions), but it doesn't allow you to easily integrate a Module-3 module into
a C/C++ project.
</p>
<H2><a name="conception"></a>24.2 Conception</H2>
<H2><a name="Modula3_conception"></a>25.2 Conception</H2>
<H3><a name="cinterface"></a>24.2.1 Interfaces to C libraries</H3>
<H3><a name="Modula3_cinterface"></a>25.2.1 Interfaces to C libraries</H3>
<p>
Modula-3 has an integrated support for calling C functions.
Modula-3 has integrated support for calling C functions.
This is also extensively used by the standard Modula-3 libraries
to call OS functions.
The Modula-3 part of SWIG and the corresponding SWIG library
@ -404,7 +283,7 @@ and the principal type must be renamed (<tt>%typemap</tt>).
</p>
<H3><a name="cppinterface"></a>24.2.2 Interfaces to C++ libraries</H3>
<H3><a name="Modula3_cppinterface"></a>25.2.2 Interfaces to C++ libraries</H3>
<p>
@ -417,7 +296,7 @@ with a C interface.
<p>
Here's a scheme of how the function calls to Modula-3 wrappers
a redirected to C library functions:
are redirected to C library functions:
</p>
<table summary="Modula-3 C++ library">
@ -477,13 +356,13 @@ Is it possible to sub-class C++ classes with Modula-3 code?
This issue is addressed by directors,
a feature that was experimentally added to some Language modules
like
<a href="Java.html#java_directors">Java</a> and
<a href="Python.html#directors">Python</a>.
<a href="Java.html#Java_directors">Java</a> and
<a href="Python.html#Python_directors">Python</a>.
</li>
<li>
How to manage storage with the garbage collector of Modula-3?
Support for
<a href="Customization.html#ownership">
<a href="Customization.html#Customization_ownership">
<tt>%newobject</tt> and <tt>%typemap(newfree)</tt></a>
isn't implemented, yet.
What's about resources that are managed by the garbage collector
@ -494,7 +373,7 @@ as far as I know.
<li>
How to turn C++ exceptions into Modula-3 exceptions?
There's also no support for
<a href="Customization.html#exception">
<a href="Customization.html#Customization_exception">
<tt>%exception</tt></a>, yet.
</li>
</ul>
@ -505,10 +384,10 @@ There is no C++ library I wrote a SWIG interface for,
so I'm not sure if this is possible or sensible, yet.
</p>
<H2><a name="preliminaries"></a>24.3 Preliminaries</H2>
<H2><a name="Modula3_preliminaries"></a>25.3 Preliminaries</H2>
<H3><a name="compilers"></a>24.3.1 Compilers</H3>
<H3><a name="Modula3_compilers"></a>25.3.1 Compilers</H3>
<p>
@ -522,7 +401,7 @@ For testing examples I use Critical Mass cm3.
</p>
<H3><a name="commandline"></a>24.3.2 Additional Commandline Options</H3>
<H3><a name="Modula3_commandline"></a>25.3.2 Additional Commandline Options</H3>
<p>
@ -599,10 +478,10 @@ Instead generate templates for some basic typemaps.
</tr>
</table>
<H2><a name="modula3_typemaps"></a>24.4 Modula-3 typemaps</H2>
<H2><a name="Modula3_typemaps"></a>25.4 Modula-3 typemaps</H2>
<H3><a name="inoutparam"></a>24.4.1 Inputs and outputs</H3>
<H3><a name="Modula3_inoutparam"></a>25.4.1 Inputs and outputs</H3>
<p>
@ -818,7 +697,7 @@ consist of the following parts:
</table>
<H3><a name="ordinals"></a>24.4.2 Subranges, Enumerations, Sets</H3>
<H3><a name="Modula3_ordinals"></a>25.4.2 Subranges, Enumerations, Sets</H3>
<p>
@ -870,7 +749,7 @@ that I'd like to automate.
</p>
<H3><a name="class"></a>24.4.3 Objects</H3>
<H3><a name="Modula3_class"></a>25.4.3 Objects</H3>
<p>
@ -883,7 +762,7 @@ is not really useful, yet.
</p>
<H3><a name="imports"></a>24.4.4 Imports</H3>
<H3><a name="Modula3_imports"></a>25.4.4 Imports</H3>
<p>
@ -918,7 +797,7 @@ IMPORT M3toC;
</pre></div>
<H3><a name="exceptions"></a>24.4.5 Exceptions</H3>
<H3><a name="Modula3_exceptions"></a>25.4.5 Exceptions</H3>
<p>
@ -942,7 +821,7 @@ you should declare
<tt>%typemap("m3wrapinconv:throws") blah * %{OSError.E%}</tt>.
</p>
<H3><a name="typemap_example"></a>24.4.6 Example</H3>
<H3><a name="Modula3_typemap_example"></a>25.4.6 Example</H3>
<p>
@ -989,10 +868,10 @@ where almost everything is generated by a typemap:
</pre></div>
<H2><a name="hints"></a>24.5 More hints to the generator</H2>
<H2><a name="Modula3_hints"></a>25.5 More hints to the generator</H2>
<H3><a name="features"></a>24.5.1 Features</H3>
<H3><a name="Modula3_features"></a>25.5.1 Features</H3>
<table border summary="Modula-3 features">
@ -1022,14 +901,14 @@ where almost everything is generated by a typemap:
This is necessary in the cases
where it was defined by a non-trivial C expression.
This feature is used by the
<tt>-generateconst</tt> <a href="#options">option</a>.
<tt>-generateconst</tt> <a href="#Modula3_commandline">option</a>.
In future it may be generalized to other kind of values
such as strings.
</td>
</tr>
</table>
<H3><a name="pragmas"></a>24.5.2 Pragmas</H3>
<H3><a name="Modula3_pragmas"></a>25.5.2 Pragmas</H3>
<table border summary="Modula-3 pragmas">
@ -1052,14 +931,14 @@ where almost everything is generated by a typemap:
</tr>
</table>
<H2><a name="remarks"></a>24.6 Remarks</H2>
<H2><a name="Modula3_remarks"></a>25.6 Remarks</H2>
<ul>
<li>
The Modula-3 part of SWIG doesn't try to generate nicely formatted code.
Use <tt>m3pp</tt> to postprocess the Modula files,
it does a very good job here.
If you need to read the generated code, use <tt>m3pp</tt> to postprocess the
Modula files.
</li>
</ul>

8
Doc/Manual/Modules.html
View file

@ -13,7 +13,7 @@
<li><a href="#Modules_introduction">Modules Introduction</a>
<li><a href="#Modules_nn1">Basics</a>
<li><a href="#Modules_nn2">The SWIG runtime code</a>
<li><a href="#external_run_time">External access to the runtime</a>
<li><a href="#Modules_external_run_time">External access to the runtime</a>
<li><a href="#Modules_nn4">A word of caution about static libraries</a>
<li><a href="#Modules_nn5">References</a>
<li><a href="#Modules_nn6">Reducing the wrapper file size</a>
@ -29,7 +29,7 @@
<p>
Each invocation of SWIG requires a module name to be specified.
The module name is used to name the resulting target language extension module.
Exactly what this means and and what the name is used for
Exactly what this means and what the name is used for
depends on the target language, for example the name can define
a target language namespace or merely be a useful name for naming files or helper classes.
Essentially, a module comprises target language wrappers for a chosen collection of global variables/functions, structs/classes and other C/C++ types.
@ -241,10 +241,10 @@ 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="external_run_time"></a>15.4 External access to the runtime</H2>
<H2><a name="Modules_external_run_time"></a>15.4 External access to the runtime</H2>
<p>As described in <a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>,
<p>As described in <a href="Typemaps.html#Typemaps_runtime_type_checker">The run-time type checker</a>,
the functions <tt>SWIG_TypeQuery</tt>, <tt>SWIG_NewPointerObj</tt>, and others sometimes need
to be called. Calling these functions from a typemap is supported, since the typemap code
is embedded into the <tt>_wrap.c</tt> file, which has those declarations available. If you need

4
Doc/Manual/Mzscheme.html
View file

@ -8,7 +8,7 @@
<body bgcolor="#ffffff">
<H1><a name="MzScheme"></a>25 SWIG and MzScheme</H1>
<H1><a name="Mzscheme"></a>26 SWIG and MzScheme</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -22,7 +22,7 @@
<p>
This section contains information on SWIG's support of MzScheme.
<H2><a name="MzScheme_nn2"></a>25.1 Creating native MzScheme structures</H2>
<H2><a name="MzScheme_nn2"></a>26.1 Creating native MzScheme structures</H2>
<p>

62
Doc/Manual/Ocaml.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<a name="n1"></a>
<H1><a name="Ocaml"></a>26 SWIG and Ocaml</H1>
<H1><a name="Ocaml"></a>27 SWIG and Ocaml</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -80,7 +80,7 @@ If you're not familiar with the Objective Caml language, you can visit
<a href="http://www.ocaml.org/">The Ocaml Website</a>.
</p>
<H2><a name="Ocaml_nn2"></a>26.1 Preliminaries</H2>
<H2><a name="Ocaml_nn2"></a>27.1 Preliminaries</H2>
<p>
@ -99,7 +99,7 @@ file Examples/Makefile illustrate how to compile and link SWIG modules that
will be loaded dynamically. This has only been tested on Linux so far.
</p>
<H3><a name="Ocaml_nn3"></a>26.1.1 Running SWIG</H3>
<H3><a name="Ocaml_nn3"></a>27.1.1 Running SWIG</H3>
<p>
@ -122,7 +122,7 @@ you will compile the file <tt>example_wrap.c</tt> with <tt>ocamlc</tt> or
the resulting .ml and .mli files as well, and do the final link with -custom
(not needed for native link). </p>
<H3><a name="Ocaml_nn4"></a>26.1.2 Compiling the code</H3>
<H3><a name="Ocaml_nn4"></a>27.1.2 Compiling the code</H3>
<p>
@ -158,7 +158,7 @@ the user more freedom with respect to custom typing.
</pre>
</div>
<H3><a name="Ocaml_nn5"></a>26.1.3 The camlp4 module</H3>
<H3><a name="Ocaml_nn5"></a>27.1.3 The camlp4 module</H3>
<p>
@ -234,7 +234,7 @@ let b = C_string (getenv "PATH")
</td></tr>
</table>
<H3><a name="Ocaml_nn6"></a>26.1.4 Using your module</H3>
<H3><a name="Ocaml_nn6"></a>27.1.4 Using your module</H3>
<p>
@ -248,7 +248,7 @@ When linking any ocaml bytecode with your module, use the -custom
option is not needed when you build native code.
</p>
<H3><a name="Ocaml_nn7"></a>26.1.5 Compilation problems and compiling with C++</H3>
<H3><a name="Ocaml_nn7"></a>27.1.5 Compilation problems and compiling with C++</H3>
<p>
@ -259,7 +259,7 @@ liberal with pointer types may not compile under the C++ compiler.
Most code meant to be compiled as C++ will not have problems.
</p>
<H2><a name="Ocaml_nn8"></a>26.2 The low-level Ocaml/C interface</H2>
<H2><a name="Ocaml_nn8"></a>27.2 The low-level Ocaml/C interface</H2>
<p>
@ -360,7 +360,7 @@ is that you must append them to the return list with swig_result = caml_list_a
signature for a function that uses value in this way.
</p>
<H3><a name="Ocaml_nn9"></a>26.2.1 The generated module</H3>
<H3><a name="Ocaml_nn9"></a>27.2.1 The generated module</H3>
<p>
@ -394,7 +394,7 @@ it describes the output SWIG will generate for class definitions.
</td></tr>
</table>
<H3><a name="Ocaml_nn10"></a>26.2.2 Enums</H3>
<H3><a name="Ocaml_nn10"></a>27.2.2 Enums</H3>
<p>
@ -457,7 +457,7 @@ val x : Enum_test.c_obj = C_enum `a
</pre>
</div>
<H4><a name="Ocaml_nn11"></a>26.2.2.1 Enum typing in Ocaml</H4>
<H4><a name="Ocaml_nn11"></a>27.2.2.1 Enum typing in Ocaml</H4>
<p>
@ -470,10 +470,10 @@ functions imported from different modules. You must convert values to master
values using the swig_val function before sharing them with another module.
</p>
<H3><a name="Ocaml_nn12"></a>26.2.3 Arrays</H3>
<H3><a name="Ocaml_nn12"></a>27.2.3 Arrays</H3>
<H4><a name="Ocaml_nn13"></a>26.2.3.1 Simple types of bounded arrays</H4>
<H4><a name="Ocaml_nn13"></a>27.2.3.1 Simple types of bounded arrays</H4>
<p>
@ -494,7 +494,7 @@ arrays of simple types with known bounds in your code, but this only works
for arrays whose bounds are completely specified.
</p>
<H4><a name="Ocaml_nn14"></a>26.2.3.2 Complex and unbounded arrays</H4>
<H4><a name="Ocaml_nn14"></a>27.2.3.2 Complex and unbounded arrays</H4>
<p>
@ -507,7 +507,7 @@ SWIG can't predict which of these methods will be used in the array,
so you have to specify it for yourself in the form of a typemap.
</p>
<H4><a name="Ocaml_nn15"></a>26.2.3.3 Using an object</H4>
<H4><a name="Ocaml_nn15"></a>27.2.3.3 Using an object</H4>
<p>
@ -521,7 +521,7 @@ Consider writing an object when the ending condition of your array is complex,
such as using a required sentinel, etc.
</p>
<H4><a name="Ocaml_nn16"></a>26.2.3.4 Example typemap for a function taking float * and int</H4>
<H4><a name="Ocaml_nn16"></a>27.2.3.4 Example typemap for a function taking float * and int</H4>
<p>
@ -572,7 +572,7 @@ void printfloats( float *tab, int len );
</pre></td></tr></table>
<H3><a name="Ocaml_nn17"></a>26.2.4 C++ Classes</H3>
<H3><a name="Ocaml_nn17"></a>27.2.4 C++ Classes</H3>
<p>
@ -615,7 +615,7 @@ the underlying pointer, so using create_[x]_from_ptr alters the
returned value for the same object.
</p>
<H4><a name="Ocaml_nn18"></a>26.2.4.1 STL vector and string Example</H4>
<H4><a name="Ocaml_nn18"></a>27.2.4.1 STL vector and string Example</H4>
<p>
@ -695,7 +695,7 @@ baz
#
</pre></div>
<H4><a name="Ocaml_nn19"></a>26.2.4.2 C++ Class Example</H4>
<H4><a name="Ocaml_nn19"></a>27.2.4.2 C++ Class Example</H4>
<p>
@ -725,7 +725,7 @@ public:
};
</pre></td></tr></table>
<H4><a name="Ocaml_nn20"></a>26.2.4.3 Compiling the example</H4>
<H4><a name="Ocaml_nn20"></a>27.2.4.3 Compiling the example</H4>
<div class="code"><pre>
@ -743,7 +743,7 @@ bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \
-L$QTPATH/lib -cclib -lqt
</pre></div>
<H4><a name="Ocaml_nn21"></a>26.2.4.4 Sample Session</H4>
<H4><a name="Ocaml_nn21"></a>27.2.4.4 Sample Session</H4>
<div class="code"><pre>
@ -770,10 +770,10 @@ Assuming you have a working installation of QT, you will see a window
containing the string "hi" in a button.
</p>
<H3><a name="Ocaml_nn22"></a>26.2.5 Director Classes</H3>
<H3><a name="Ocaml_nn22"></a>27.2.5 Director Classes</H3>
<H4><a name="Ocaml_nn23"></a>26.2.5.1 Director Introduction</H4>
<H4><a name="Ocaml_nn23"></a>27.2.5.1 Director Introduction</H4>
<p>
@ -800,7 +800,7 @@ class foo {
};
</pre></div>
<H4><a name="Ocaml_nn24"></a>26.2.5.2 Overriding Methods in Ocaml</H4>
<H4><a name="Ocaml_nn24"></a>27.2.5.2 Overriding Methods in Ocaml</H4>
<p>
@ -828,7 +828,7 @@ In this example, I'll examine the objective caml code involved in providing
an overloaded class. This example is contained in Examples/ocaml/shapes.
</p>
<H4><a name="Ocaml_nn25"></a>26.2.5.3 Director Usage Example</H4>
<H4><a name="Ocaml_nn25"></a>27.2.5.3 Director Usage Example</H4>
<table border="1" bgcolor="#dddddd" summary="Director usage example">
@ -887,7 +887,7 @@ in a more effortless style in ocaml, while leaving the "engine" part of the
program in C++.
</p>
<H4><a name="Ocaml_nn26"></a>26.2.5.4 Creating director objects</H4>
<H4><a name="Ocaml_nn26"></a>27.2.5.4 Creating director objects</H4>
<p>
@ -928,7 +928,7 @@ object from causing a core dump, as long as the object is destroyed
properly.
</p>
<H4><a name="Ocaml_nn27"></a>26.2.5.5 Typemaps for directors, <tt>directorin, directorout, directorargout</tt></H4>
<H4><a name="Ocaml_nn27"></a>27.2.5.5 Typemaps for directors, <tt>directorin, directorout, directorargout</tt></H4>
<p>
@ -939,7 +939,7 @@ well as a function return value in the same way you provide function arguments,
and to receive arguments the same way you normally receive function returns.
</p>
<H4><a name="Ocaml_nn28"></a>26.2.5.6 <tt>directorin</tt> typemap</H4>
<H4><a name="Ocaml_nn28"></a>27.2.5.6 <tt>directorin</tt> typemap</H4>
<p>
@ -950,7 +950,7 @@ code receives when you are called. In general, a simple <tt>directorin</tt> typ
can use the same body as a simple <tt>out</tt> typemap.
</p>
<H4><a name="Ocaml_nn29"></a>26.2.5.7 <tt>directorout</tt> typemap</H4>
<H4><a name="Ocaml_nn29"></a>27.2.5.7 <tt>directorout</tt> typemap</H4>
<p>
@ -961,7 +961,7 @@ for the same type, except when there are special requirements for object
ownership, etc.
</p>
<H4><a name="Ocaml_nn30"></a>26.2.5.8 <tt>directorargout</tt> typemap</H4>
<H4><a name="Ocaml_nn30"></a>27.2.5.8 <tt>directorargout</tt> typemap</H4>
<p>
@ -978,7 +978,7 @@ In the event that you don't specify all of the necessary values, integral
values will read zero, and struct or object returns have undefined results.
</p>
<H3><a name="Ocaml_nn31"></a>26.2.6 Exceptions</H3>
<H3><a name="Ocaml_nn31"></a>27.2.6 Exceptions</H3>
<p>

68
Doc/Manual/Octave.html
View file

@ -8,7 +8,7 @@
<body bgcolor="#ffffff">
<H1><a name="Octave"></a>27 SWIG and Octave</H1>
<H1><a name="Octave"></a>28 SWIG and Octave</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -54,21 +54,22 @@ More information can be found at <a href="http://www.octave.org">www.octave.org<
Also, there are a dozen or so examples in the Examples/octave directory, and hundreds in the test suite (Examples/test-suite and Examples/test-suite/octave).
</p>
<H2><a name="Octave_nn2"></a>27.1 Preliminaries</H2>
<H2><a name="Octave_nn2"></a>28.1 Preliminaries</H2>
<p>
The current SWIG implemention is based on Octave 2.9.12. Support for other versions (in particular the recent 3.0) has not been tested, nor has support for any OS other than Linux.
The SWIG implemention was first based on Octave 2.9.12, so this is the minimum version required. Testing has only been done on Linux.
</p>
<H2><a name="Octave_nn3"></a>27.2 Running SWIG</H2>
<H2><a name="Octave_nn3"></a>28.2 Running SWIG</H2>
<p>
Let's start with a very simple SWIG interface file:
Let's start with a very simple SWIG interface file, example.i:
</p>
<div class="code"><pre>%module example
<div class="code"><pre>
%module example
%{
#include "example.h"
%}
@ -76,20 +77,27 @@ int gcd(int x, int y);
extern double Foo; </pre></div>
<p>
To build an Octave module, run SWIG using the <tt>-octave</tt> option. The <tt>-c++</tt> option is required (for now) as Octave itself is written in C++ and thus the wrapper code must also be.
To build an Octave module when wrapping C code, run SWIG using the <tt>-octave</tt> option:
</p>
<div class="shell"><pre>$ swig -octave example.i </pre></div>
<p>
The <tt>-c++</tt> option is also required when wrapping C++ code:
</p>
<div class="shell"><pre>$ swig -octave -c++ example.i </pre></div>
<p>
This creates a C/C++ source file <tt>example_wrap.cxx</tt>. 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.
This creates a C++ source file <tt>example_wrap.cxx</tt>. 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>
<p>
The swig command line has a number of options you can use, like to redirect it's output. Use <tt>swig --help</tt> to learn about these.
</p>
<H3><a name="Octave_nn5"></a>27.2.1 Compiling a dynamic module</H3>
<H3><a name="Octave_nn5"></a>28.2.1 Compiling a dynamic module</H3>
<p>
@ -116,7 +124,7 @@ $ mkoctfile example_wrap.cxx example.c
<div class="targetlang"><pre>octave:1&gt; example</pre></div>
<H3><a name="Octave_nn6"></a>27.2.2 Using your module</H3>
<H3><a name="Octave_nn6"></a>28.2.2 Using your module</H3>
<p>
@ -134,10 +142,10 @@ octave:4&gt; example.cvar.Foo=4;
octave:5&gt; example.cvar.Foo
ans = 4 </pre></div>
<H2><a name="Octave_nn7"></a>27.3 A tour of basic C/C++ wrapping</H2>
<H2><a name="Octave_nn7"></a>28.3 A tour of basic C/C++ wrapping</H2>
<H3><a name="Octave_nn8"></a>27.3.1 Modules</H3>
<H3><a name="Octave_nn8"></a>28.3.1 Modules</H3>
<p>
@ -179,7 +187,7 @@ One can also rename it by simple assignment, e.g.,
octave:1&gt; some_vars = cvar;
</pre></div>
<H3><a name="Octave_nn9"></a>27.3.2 Functions</H3>
<H3><a name="Octave_nn9"></a>28.3.2 Functions</H3>
<p>
@ -196,7 +204,7 @@ int fact(int n); </pre></div>
<div class="targetlang"><pre>octave:1&gt; example.fact(4)
24 </pre></div>
<H3><a name="Octave_nn10"></a>27.3.3 Global variables</H3>
<H3><a name="Octave_nn10"></a>28.3.3 Global variables</H3>
<p>
@ -231,7 +239,7 @@ extern double Foo;
</pre></div>
<p>
SWIG will allow the the reading of <tt>Foo</tt> but when a set attempt is made, an error function will be called.
SWIG will allow the reading of <tt>Foo</tt> but when a set attempt is made, an error function will be called.
</p>
<div class="targetlang"><pre>octave:1&gt; example
@ -249,7 +257,7 @@ octave:2&gt; example.PI=3.142;
octave:3&gt; example.PI
ans = 3.1420 </pre></div>
<H3><a name="Octave_nn11"></a>27.3.4 Constants and enums</H3>
<H3><a name="Octave_nn11"></a>28.3.4 Constants and enums</H3>
<p>
@ -271,7 +279,7 @@ example.SCONST="Hello World"
example.SUNDAY=0
.... </pre></div>
<H3><a name="Octave_nn12"></a>27.3.5 Pointers</H3>
<H3><a name="Octave_nn12"></a>28.3.5 Pointers</H3>
<p>
@ -318,7 +326,7 @@ octave:2&gt; f=example.fopen("not there","r");
error: value on right hand side of assignment is undefined
error: evaluating assignment expression near line 2, column 2 </pre></div>
<H3><a name="Octave_nn13"></a>27.3.6 Structures and C++ classes</H3>
<H3><a name="Octave_nn13"></a>28.3.6 Structures and C++ classes</H3>
<p>
@ -453,7 +461,7 @@ ans = 1
Depending on the ownership setting of a <tt>swig_ref</tt>, it may call C++ destructors when its reference count goes to zero. See the section on memory management below for details.
</p>
<H3><a name="Octave_nn15"></a>27.3.7 C++ inheritance</H3>
<H3><a name="Octave_nn15"></a>28.3.7 C++ inheritance</H3>
<p>
@ -462,7 +470,7 @@ This information contains the full class hierarchy. When an indexing operation (
the tree is walked to find a match in the current class as well as any of its bases. The lookup is then cached in the <tt>swig_ref</tt>.
</p>
<H3><a name="Octave_nn17"></a>27.3.8 C++ overloaded functions</H3>
<H3><a name="Octave_nn17"></a>28.3.8 C++ overloaded functions</H3>
<p>
@ -472,7 +480,7 @@ The dispatch function selects which overload to call (if any) based on the passe
<tt>typecheck</tt> typemaps are used to analyze each argument, as well as assign precedence. See the chapter on typemaps for details.
</p>
<H3><a name="Octave_nn18"></a>27.3.9 C++ operators</H3>
<H3><a name="Octave_nn18"></a>28.3.9 C++ operators</H3>
<p>
@ -572,7 +580,7 @@ On the C++ side, the default mappings are as follows:
%rename(__brace) *::operator[];
</pre></div>
<H3><a name="Octave_nn19"></a>27.3.10 Class extension with %extend</H3>
<H3><a name="Octave_nn19"></a>28.3.10 Class extension with %extend</H3>
<p>
@ -602,7 +610,7 @@ octave:3&gt; printf("%s\n",a);
octave:4&gt; a.__str()
4
</pre></div>
<H3><a name="Octave_nn20"></a>27.3.11 C++ templates</H3>
<H3><a name="Octave_nn20"></a>28.3.11 C++ templates</H3>
<p>
@ -679,14 +687,14 @@ ans =
</pre></div>
<H3><a name="Octave_nn21"></a>27.3.12 C++ Smart Pointers</H3>
<H3><a name="Octave_nn21"></a>28.3.12 C++ Smart Pointers</H3>
<p>
C++ smart pointers are fully supported as in other modules.
</p>
<H3><a name="Octave_nn22"></a>27.3.13 Directors (calling Octave from C++ code)</H3>
<H3><a name="Octave_nn22"></a>28.3.13 Directors (calling Octave from C++ code)</H3>
<p>
@ -766,14 +774,14 @@ c-side routine called
octave-side routine called
</pre></div>
<H3><a name="Octave_nn23"></a>27.3.14 Threads</H3>
<H3><a name="Octave_nn23"></a>28.3.14 Threads</H3>
<p>
The use of threads in wrapped Director code is not supported; i.e., an Octave-side implementation of a C++ class must be called from the Octave interpreter's thread. Anything fancier (apartment/queue model, whatever) is left to the user. Without anything fancier, this amounts to the limitation that Octave must drive the module... like, for example, an optimization package that calls Octave to evaluate an objective function.
</p>
<H3><a name="Octave_nn24"></a>27.3.15 Memory management</H3>
<H3><a name="Octave_nn24"></a>28.3.15 Memory management</H3>
<p>
@ -807,14 +815,14 @@ The %newobject directive may be used to control this behavior for pointers retur
In the case where one wishes for the C++ side to own an object that was created in Octave (especially a Director object), one can use the __disown() method to invert this logic. Then letting the Octave reference count go to zero will not destroy the object, but destroying the object will invalidate the Octave-side object if it still exists (and call destructors of other C++ bases in the case of multiple inheritance/<tt>subclass()</tt>'ing).
</p>
<H3><a name="Octave_nn25"></a>27.3.16 STL support</H3>
<H3><a name="Octave_nn25"></a>28.3.16 STL support</H3>
<p>
This is some skeleton support for various STL containers.
Various STL library files are provided for wrapping STL containers.
</p>
<H3><a name="Octave_nn26"></a>27.3.17 Matrix typemaps</H3>
<H3><a name="Octave_nn26"></a>28.3.17 Matrix typemaps</H3>
<p>

96
Doc/Manual/Perl5.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Perl5"></a>28 SWIG and Perl5</H1>
<H1><a name="Perl5"></a>29 SWIG and Perl5</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -87,7 +87,7 @@ later. Earlier versions are problematic and SWIG generated extensions
may not compile or run correctly.
</p>
<H2><a name="Perl5_nn2"></a>28.1 Overview</H2>
<H2><a name="Perl5_nn2"></a>29.1 Overview</H2>
<p>
@ -108,7 +108,7 @@ described. Advanced customization features, typemaps, and other
options are found near the end of the chapter.
</p>
<H2><a name="Perl5_nn3"></a>28.2 Preliminaries</H2>
<H2><a name="Perl5_nn3"></a>29.2 Preliminaries</H2>
<p>
@ -133,7 +133,7 @@ To build the module, you will need to compile the file
<tt>example_wrap.c</tt> and link it with the rest of your program.
</p>
<H3><a name="Perl5_nn4"></a>28.2.1 Getting the right header files</H3>
<H3><a name="Perl5_nn4"></a>29.2.1 Getting the right header files</H3>
<p>
@ -165,7 +165,7 @@ loaded, an easy way to find out is to run Perl itself.
</pre>
</div>
<H3><a name="Perl5_nn5"></a>28.2.2 Compiling a dynamic module</H3>
<H3><a name="Perl5_nn5"></a>29.2.2 Compiling a dynamic module</H3>
<p>
@ -198,7 +198,7 @@ the target should be named `<tt>example.so</tt>',
`<tt>example.sl</tt>', or the appropriate dynamic module name on your system.
</p>
<H3><a name="Perl5_nn6"></a>28.2.3 Building a dynamic module with MakeMaker</H3>
<H3><a name="Perl5_nn6"></a>29.2.3 Building a dynamic module with MakeMaker</H3>
<p>
@ -232,7 +232,7 @@ the preferred approach to compilation. More information about MakeMaker can be
found in "Programming Perl, 2nd ed." by Larry Wall, Tom Christiansen,
and Randal Schwartz.</p>
<H3><a name="Perl5_nn7"></a>28.2.4 Building a static version of Perl</H3>
<H3><a name="Perl5_nn7"></a>29.2.4 Building a static version of Perl</H3>
<p>
@ -301,7 +301,7 @@ added to it. Depending on your machine, you may need to link with
additional libraries such as <tt>-lsocket, -lnsl, -ldl</tt>, etc.
</p>
<H3><a name="Perl5_nn8"></a>28.2.5 Using the module</H3>
<H3><a name="Perl5_nn8"></a>29.2.5 Using the module</H3>
<p>
@ -456,7 +456,7 @@ system configuration (this requires root access and you will need to
read the man pages).
</p>
<H3><a name="Perl5_nn9"></a>28.2.6 Compilation problems and compiling with C++</H3>
<H3><a name="Perl5_nn9"></a>29.2.6 Compilation problems and compiling with C++</H3>
<p>
@ -599,7 +599,7 @@ have to find the macro that conflicts and add an #undef into the .i file. Pleas
any conflicting macros you find to <a href="http://www.swig.org/mail.html">swig-user mailing list</a>.
</p>
<H3><a name="Perl5_nn10"></a>28.2.7 Compiling for 64-bit platforms</H3>
<H3><a name="Perl5_nn10"></a>29.2.7 Compiling for 64-bit platforms</H3>
<p>
@ -626,7 +626,7 @@ also introduce problems on platforms that support more than one
linking standard (e.g., -o32 and -n32 on Irix).
</p>
<H2><a name="Perl5_nn11"></a>28.3 Building Perl Extensions under Windows</H2>
<H2><a name="Perl5_nn11"></a>29.3 Building Perl Extensions under Windows</H2>
<p>
@ -637,7 +637,7 @@ section assumes you are using SWIG with Microsoft Visual C++
although the procedure may be similar with other compilers.
</p>
<H3><a name="Perl5_nn12"></a>28.3.1 Running SWIG from Developer Studio</H3>
<H3><a name="Perl5_nn12"></a>29.3.1 Running SWIG from Developer Studio</H3>
<p>
@ -700,7 +700,7 @@ print "$a\n";
</pre></div>
<H3><a name="Perl5_nn13"></a>28.3.2 Using other compilers</H3>
<H3><a name="Perl5_nn13"></a>29.3.2 Using other compilers</H3>
<p>
@ -708,7 +708,7 @@ SWIG is known to work with Cygwin and may work with other compilers on Windows.
For general hints and suggestions refer to the <a href="Windows.html#Windows">Windows</a> chapter.
</p>
<H2><a name="Perl5_nn14"></a>28.4 The low-level interface</H2>
<H2><a name="Perl5_nn14"></a>29.4 The low-level interface</H2>
<p>
@ -718,7 +718,7 @@ can be used to control your application. However, it is also used to
construct more user-friendly proxy classes as described in the next section.
</p>
<H3><a name="Perl5_nn15"></a>28.4.1 Functions</H3>
<H3><a name="Perl5_nn15"></a>29.4.1 Functions</H3>
<p>
@ -741,7 +741,7 @@ use example;
$a = &amp;example::fact(2);
</pre></div>
<H3><a name="Perl5_nn16"></a>28.4.2 Global variables</H3>
<H3><a name="Perl5_nn16"></a>29.4.2 Global variables</H3>
<p>
@ -811,7 +811,7 @@ extern char *path; // Declared later in the input
</pre>
</div>
<H3><a name="Perl5_nn17"></a>28.4.3 Constants</H3>
<H3><a name="Perl5_nn17"></a>29.4.3 Constants</H3>
<p>
@ -851,7 +851,7 @@ print example::FOO,"\n";
</pre>
</div>
<H3><a name="Perl5_nn18"></a>28.4.4 Pointers</H3>
<H3><a name="Perl5_nn18"></a>29.4.4 Pointers</H3>
<p>
@ -960,7 +960,7 @@ as XS and <tt>xsubpp</tt>. Given the advancement of the SWIG typesystem and the
SWIG and XS, this is no longer supported.
</p>
<H3><a name="Perl5_nn19"></a>28.4.5 Structures</H3>
<H3><a name="Perl5_nn19"></a>29.4.5 Structures</H3>
<p>
@ -1094,7 +1094,7 @@ void Bar_f_set(Bar *b, Foo *val) {
</div>
<H3><a name="Perl5_nn20"></a>28.4.6 C++ classes</H3>
<H3><a name="Perl5_nn20"></a>29.4.6 C++ classes</H3>
<p>
@ -1159,7 +1159,7 @@ provides direct access to C++ objects. A higher level interface using Perl prox
can be built using these low-level accessors. This is described shortly.
</p>
<H3><a name="Perl5_nn21"></a>28.4.7 C++ classes and type-checking</H3>
<H3><a name="Perl5_nn21"></a>29.4.7 C++ classes and type-checking</H3>
<p>
@ -1195,7 +1195,7 @@ If necessary, the type-checker also adjusts the value of the pointer (as is nece
multiple inheritance is used).
</p>
<H3><a name="Perl5_nn22"></a>28.4.8 C++ overloaded functions</H3>
<H3><a name="Perl5_nn22"></a>29.4.8 C++ overloaded functions</H3>
<p>
@ -1239,7 +1239,7 @@ example::Spam_foo_d($s,3.14);
Please refer to the "SWIG Basics" chapter for more information.
</p>
<H3><a name="Perl5_nn23"></a>28.4.9 Operators</H3>
<H3><a name="Perl5_nn23"></a>29.4.9 Operators</H3>
<p>
@ -1266,7 +1266,7 @@ The following C++ operators are currently supported by the Perl module:
<li>operator or </li>
</ul>
<H3><a name="Perl5_nn24"></a>28.4.10 Modules and packages</H3>
<H3><a name="Perl5_nn24"></a>29.4.10 Modules and packages</H3>
<p>
@ -1361,7 +1361,7 @@ print Foo::fact(4),"\n"; # Call a function in package FooBar
</pre></div>
-->
<H2><a name="Perl5_nn25"></a>28.5 Input and output parameters</H2>
<H2><a name="Perl5_nn25"></a>29.5 Input and output parameters</H2>
<p>
@ -1580,7 +1580,7 @@ print "$c\n";
<b>Note:</b> The <tt>REFERENCE</tt> feature is only currently supported for numeric types (integers and floating point).
</p>
<H2><a name="Perl5_nn26"></a>28.6 Exception handling</H2>
<H2><a name="Perl5_nn26"></a>29.6 Exception handling</H2>
<p>
@ -1745,7 +1745,7 @@ This is still supported, but it is deprecated. The newer <tt>%exception</tt> di
functionality, but it has additional capabilities that make it more powerful.
</p>
<H2><a name="Perl5_nn27"></a>28.7 Remapping datatypes with typemaps</H2>
<H2><a name="Perl5_nn27"></a>29.7 Remapping datatypes with typemaps</H2>
<p>
@ -1762,7 +1762,7 @@ Typemaps are only used if you want to change some aspect of the primitive
C-Perl interface.
</p>
<H3><a name="Perl5_nn28"></a>28.7.1 A simple typemap example</H3>
<H3><a name="Perl5_nn28"></a>29.7.1 A simple typemap example</H3>
<p>
@ -1866,7 +1866,7 @@ example::count("e","Hello World");
</div>
<H3><a name="Perl5_nn29"></a>28.7.2 Perl5 typemaps</H3>
<H3><a name="Perl5_nn29"></a>29.7.2 Perl5 typemaps</H3>
<p>
@ -1971,7 +1971,7 @@ Return of C++ member data (all languages).
Check value of input parameter.
</div>
<H3><a name="Perl5_nn30"></a>28.7.3 Typemap variables</H3>
<H3><a name="Perl5_nn30"></a>29.7.3 Typemap variables</H3>
<p>
@ -2042,7 +2042,7 @@ properly assigned.
The Perl name of the wrapper function being created.
</div>
<H3><a name="Perl5_nn31"></a>28.7.4 Useful functions</H3>
<H3><a name="Perl5_nn31"></a>29.7.4 Useful functions</H3>
<p>
@ -2111,7 +2111,7 @@ int sv_isa(SV *, char *0;
</div>
<H2><a name="Perl5_nn32"></a>28.8 Typemap Examples</H2>
<H2><a name="Perl5_nn32"></a>29.8 Typemap Examples</H2>
<p>
@ -2120,7 +2120,7 @@ might look at the files "<tt>perl5.swg</tt>" and "<tt>typemaps.i</tt>" in
the SWIG library.
</p>
<H3><a name="Perl5_nn33"></a>28.8.1 Converting a Perl5 array to a char **</H3>
<H3><a name="Perl5_nn33"></a>29.8.1 Converting a Perl5 array to a char **</H3>
<p>
@ -2212,7 +2212,7 @@ print @$b,"\n"; # Print it out
</pre></div>
<H3><a name="Perl5_nn34"></a>28.8.2 Return values</H3>
<H3><a name="Perl5_nn34"></a>29.8.2 Return values</H3>
<p>
@ -2241,7 +2241,7 @@ can be done using the <tt>EXTEND()</tt> macro as in :
}
</pre></div>
<H3><a name="Perl5_nn35"></a>28.8.3 Returning values from arguments</H3>
<H3><a name="Perl5_nn35"></a>29.8.3 Returning values from arguments</H3>
<p>
@ -2295,7 +2295,7 @@ print "multout(7,13) = @r\n";
($x,$y) = multout(7,13);
</pre></div>
<H3><a name="Perl5_nn36"></a>28.8.4 Accessing array structure members</H3>
<H3><a name="Perl5_nn36"></a>29.8.4 Accessing array structure members</H3>
<p>
@ -2358,7 +2358,7 @@ the "in" typemap in the previous section would be used to convert an
to copy the converted array into a C data structure.
</p>
<H3><a name="Perl5_nn37"></a>28.8.5 Turning Perl references into C pointers</H3>
<H3><a name="Perl5_nn37"></a>29.8.5 Turning Perl references into C pointers</H3>
<p>
@ -2423,7 +2423,7 @@ print "$c\n";
</pre></div>
<H3><a name="Perl5_nn38"></a>28.8.6 Pointer handling</H3>
<H3><a name="Perl5_nn38"></a>29.8.6 Pointer handling</H3>
<p>
@ -2502,7 +2502,7 @@ For example:
</pre>
</div>
<H2><a name="Perl5_nn39"></a>28.9 Proxy classes</H2>
<H2><a name="Perl5_nn39"></a>29.9 Proxy classes</H2>
<p>
@ -2518,7 +2518,7 @@ to the underlying code. This section describes the implementation
details of the proxy interface.
</p>
<H3><a name="Perl5_nn40"></a>28.9.1 Preliminaries</H3>
<H3><a name="Perl5_nn40"></a>29.9.1 Preliminaries</H3>
<p>
@ -2540,7 +2540,7 @@ SWIG creates a collection of high-level Perl wrappers. In your scripts, you wil
high level wrappers. The wrappers, in turn, interact with the low-level procedural module.
</p>
<H3><a name="Perl5_nn41"></a>28.9.2 Structure and class wrappers</H3>
<H3><a name="Perl5_nn41"></a>29.9.2 Structure and class wrappers</H3>
<p>
@ -2666,7 +2666,7 @@ $v-&gt;DESTROY();
</pre></div>
<H3><a name="Perl5_nn42"></a>28.9.3 Object Ownership</H3>
<H3><a name="Perl5_nn42"></a>29.9.3 Object Ownership</H3>
<p>
@ -2753,7 +2753,7 @@ counting, garbage collection, or advanced features one might find in
sophisticated languages.
</p>
<H3><a name="Perl5_nn43"></a>28.9.4 Nested Objects</H3>
<H3><a name="Perl5_nn43"></a>29.9.4 Nested Objects</H3>
<p>
@ -2806,7 +2806,7 @@ $p-&gt;{f}-&gt;{x} = 0.0;
%${$p-&gt;{v}} = ( x=&gt;0, y=&gt;0, z=&gt;0);
</pre></div>
<H3><a name="Perl5_nn44"></a>28.9.5 Proxy Functions</H3>
<H3><a name="Perl5_nn44"></a>29.9.5 Proxy Functions</H3>
<p>
@ -2840,7 +2840,7 @@ This function replaces the original function, but operates in an
identical manner.
</p>
<H3><a name="Perl5_nn45"></a>28.9.6 Inheritance</H3>
<H3><a name="Perl5_nn45"></a>29.9.6 Inheritance</H3>
<p>
@ -2916,12 +2916,12 @@ particular, inheritance of data members is extremely tricky (and I'm
not even sure if it really works).
</p>
<H3><a name="Perl5_nn46"></a>28.9.7 Modifying the proxy methods</H3>
<H3><a name="Perl5_nn46"></a>29.9.7 Modifying the proxy methods</H3>
<p>
It is possible to override the SWIG generated proxy/shadow methods, using <tt>%feature("shadow")</tt>.
It works like all the other <a href="Customization.html#features">%feature directives</a>.
It works like all the other <a href="Customization.html#Customization_features">%feature directives</a>.
Here is a simple example showing how to add some Perl debug code to the constructor:
</p>
@ -2944,7 +2944,7 @@ public:
};
</pre></div>
<H2><a name="Perl5_nn47"></a>28.10 Adding additional Perl code</H2>
<H2><a name="Perl5_nn47"></a>29.10 Adding additional Perl code</H2>
<p>

56
Doc/Manual/Php.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Php"></a>29 SWIG and PHP</H1>
<H1><a name="Php"></a>30 SWIG and PHP</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -75,7 +75,7 @@ your extension into php directly, you will need the complete PHP source tree
available.
</p>
<H2><a name="Php_nn1"></a>29.1 Generating PHP Extensions</H2>
<H2><a name="Php_nn1"></a>30.1 Generating PHP Extensions</H2>
<p>
@ -122,7 +122,7 @@ and it doesn't play nicely with package system. We don't recommend
this approach, or provide explicit support for it.
</p>
<H3><a name="Php_nn1_1"></a>29.1.1 Building a loadable extension</H3>
<H3><a name="Php_nn1_1"></a>30.1.1 Building a loadable extension</H3>
<p>
@ -137,7 +137,7 @@ least work for Linux though):
gcc -shared example_wrap.o -o example.so
</pre></div>
<H3><a name="Php_nn1_3"></a>29.1.2 Using PHP Extensions</H3>
<H3><a name="Php_nn1_3"></a>30.1.2 Using PHP Extensions</H3>
<p>
@ -168,7 +168,7 @@ attempts to do the <tt>dl()</tt> call for you:
include("example.php");
</pre></div>
<H2><a name="Php_nn2"></a>29.2 Basic PHP interface</H2>
<H2><a name="Php_nn2"></a>30.2 Basic PHP interface</H2>
<p>
@ -178,7 +178,7 @@ possible for names of symbols in one extension module to clash with
other symbols unless care is taken to <tt>%rename</tt> them.
</p>
<H3><a name="Php_nn2_1"></a>29.2.1 Constants</H3>
<H3><a name="Php_nn2_1"></a>30.2.1 Constants</H3>
<p>
@ -303,7 +303,7 @@ both point to the same value, without the case test taking place. (
Apologies, this paragraph needs rewriting to make some sense. )
</p>
<H3><a name="Php_nn2_2"></a>29.2.2 Global Variables</H3>
<H3><a name="Php_nn2_2"></a>30.2.2 Global Variables</H3>
<p>
@ -352,7 +352,7 @@ undefined.
At this time SWIG does not support custom accessor methods.
</p>
<H3><a name="Php_nn2_3"></a>29.2.3 Functions</H3>
<H3><a name="Php_nn2_3"></a>30.2.3 Functions</H3>
<p>
@ -405,7 +405,7 @@ print $s; # The value of $s was not changed.
-->
<H3><a name="Php_nn2_4"></a>29.2.4 Overloading</H3>
<H3><a name="Php_nn2_4"></a>30.2.4 Overloading</H3>
<p>
@ -413,7 +413,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="TypemapsSWIGPlus.html#SWIGPlus_overloaded_methods">Wrapping
href="SWIGPlus.html#SWIGPlus_overloaded_methods">Wrapping
Overloaded Functions and Methods</a>.
</p>
@ -461,7 +461,7 @@ taking the integer argument.
</p>
-->
<H3><a name="Php_nn2_5"></a>29.2.5 Pointers and References</H3>
<H3><a name="Php_nn2_5"></a>30.2.5 Pointers and References</H3>
<p>
@ -593,7 +593,7 @@ PHP in a number of ways: by using <tt>unset</tt> on an existing
variable, or assigning <tt>NULL</tt> to a variable.
</p>
<H3><a name="Php_nn2_6"></a>29.2.6 Structures and C++ classes</H3>
<H3><a name="Php_nn2_6"></a>30.2.6 Structures and C++ classes</H3>
<p>
@ -652,7 +652,7 @@ Would be used in the following way from PHP5:
Member variables and methods are accessed using the <tt>-&gt;</tt> operator.
</p>
<H4><a name="Php_nn2_6_1"></a>29.2.6.1 Using <tt>-noproxy</tt></H4>
<H4><a name="Php_nn2_6_1"></a>30.2.6.1 Using <tt>-noproxy</tt></H4>
<p>
@ -678,7 +678,7 @@ Complex_im_set($obj,$d);
Complex_im_get($obj);
</pre></div>
<H4><a name="Php_nn2_6_2"></a>29.2.6.2 Constructors and Destructors</H4>
<H4><a name="Php_nn2_6_2"></a>30.2.6.2 Constructors and Destructors</H4>
<p>
@ -719,7 +719,7 @@ the programmer can either reassign the variable or call
<tt>unset($v)</tt>
</p>
<H4><a name="Php_nn2_6_3"></a>29.2.6.3 Static Member Variables</H4>
<H4><a name="Php_nn2_6_3"></a>30.2.6.3 Static Member Variables</H4>
<p>
@ -762,7 +762,7 @@ Ko::threats(10);
echo "There has now been " . Ko::threats() . " threats\n";
</pre></div>
<H4><a name="Php_nn2_6_4"></a>29.2.6.4 Static Member Functions</H4>
<H4><a name="Php_nn2_6_4"></a>30.2.6.4 Static Member Functions</H4>
<p>
@ -784,7 +784,7 @@ Ko::threats();
</pre></div>
<H3><a name="Php_nn2_7"></a>29.2.7 PHP Pragmas, Startup and Shutdown code</H3>
<H3><a name="Php_nn2_7"></a>30.2.7 PHP Pragmas, Startup and Shutdown code</H3>
<p>
@ -857,7 +857,7 @@ either <tt>%init</tt> or <tt>%minit</tt>.
<p>
To insert code into the <tt>PHP_MSHUTDOWN_FUNCTION</tt>, one can use
either <tt>%init</tt> or <tt>%minit</tt>.
either <tt>%shutdown</tt> or <tt>%mshutdown</tt>.
</p>
<div class="code"><pre>
@ -868,11 +868,11 @@ either <tt>%init</tt> or <tt>%minit</tt>.
</pre></div>
<p>
The <tt>%rinit</tt> and <tt>%rshutdown</tt> statements insert code
into the request init and shutdown code respectively.
The <tt>%rinit</tt> and <tt>%rshutdown</tt> statements are very similar but insert code
into the request init (PHP_RINIT_FUNCTION) and request shutdown (PHP_RSHUTDOWN_FUNCTION) code respectively.
</p>
<H2><a name="Php_nn3"></a>29.3 Cross language polymorphism</H2>
<H2><a name="Php_nn3"></a>30.3 Cross language polymorphism</H2>
<p>
@ -907,7 +907,7 @@ wrapper functions takes care of all the cross-language method routing
transparently.
</p>
<H3><a name="Php_nn3_1"></a>29.3.1 Enabling directors</H3>
<H3><a name="Php_nn3_1"></a>30.3.1 Enabling directors</H3>
<p>
@ -999,7 +999,7 @@ class MyFoo extends Foo {
</div>
<H3><a name="Php_nn3_2"></a>29.3.2 Director classes</H3>
<H3><a name="Php_nn3_2"></a>30.3.2 Director classes</H3>
@ -1079,7 +1079,7 @@ so there is no need for the extra overhead involved with routing the
calls through PHP.
</p>
<H3><a name="Php_nn3_3"></a>29.3.3 Ownership and object destruction</H3>
<H3><a name="Php_nn3_3"></a>30.3.3 Ownership and object destruction</H3>
<p>
@ -1135,7 +1135,7 @@ In this example, we are assuming that FooContainer will take care of
deleting all the Foo pointers it contains at some point.
</p>
<H3><a name="Php_nn3_4"></a>29.3.4 Exception unrolling</H3>
<H3><a name="Php_nn3_4"></a>30.3.4 Exception unrolling</H3>
<p>
@ -1194,7 +1194,7 @@ Swig::DirectorMethodException is thrown, PHP will register the exception
as soon as the C wrapper function returns.
</p>
<H3><a name="Php_nn3_5"></a>29.3.5 Overhead and code bloat</H3>
<H3><a name="Php_nn3_5"></a>30.3.5 Overhead and code bloat</H3>
<p>
@ -1227,7 +1227,7 @@ optimized by selectively enabling director methods (using the %feature
directive) for only those methods that are likely to be extended in PHP.
</p>
<H3><a name="Php_nn3_6"></a>29.3.6 Typemaps</H3>
<H3><a name="Php_nn3_6"></a>30.3.6 Typemaps</H3>
<p>
@ -1241,7 +1241,7 @@ need to be supported.
</p>
<H3><a name="Php_nn3_7"></a>29.3.7 Miscellaneous</H3>
<H3><a name="Php_nn3_7"></a>30.3.7 Miscellaneous</H3>
<p> Director typemaps for STL classes are mostly in place, and hence you

26
Doc/Manual/Pike.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Pike"></a>30 SWIG and Pike</H1>
<H1><a name="Pike"></a>31 SWIG and Pike</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -46,10 +46,10 @@ least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>"
chapter.<br>
</p>
<H2><a name="Pike_nn2"></a>30.1 Preliminaries</H2>
<H2><a name="Pike_nn2"></a>31.1 Preliminaries</H2>
<H3><a name="Pike_nn3"></a>30.1.1 Running SWIG</H3>
<H3><a name="Pike_nn3"></a>31.1.1 Running SWIG</H3>
<p>
@ -94,7 +94,7 @@ can use the <tt>-o</tt> option:
<div class="code">
<pre>$ <b>swig -pike -o pseudonym.c example.i</b><br></pre>
</div>
<H3><a name="Pike_nn4"></a>30.1.2 Getting the right header files</H3>
<H3><a name="Pike_nn4"></a>31.1.2 Getting the right header files</H3>
<p>
@ -114,7 +114,7 @@ You're looking for files with the names <tt>global.h</tt>, <tt>program.h</tt>
and so on.
</p>
<H3><a name="Pike_nn5"></a>30.1.3 Using your module</H3>
<H3><a name="Pike_nn5"></a>31.1.3 Using your module</H3>
<p>
@ -129,10 +129,10 @@ Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend)
(1) Result: 24
</pre></div>
<H2><a name="Pike_nn6"></a>30.2 Basic C/C++ Mapping</H2>
<H2><a name="Pike_nn6"></a>31.2 Basic C/C++ Mapping</H2>
<H3><a name="Pike_nn7"></a>30.2.1 Modules</H3>
<H3><a name="Pike_nn7"></a>31.2.1 Modules</H3>
<p>
@ -143,7 +143,7 @@ concerned), SWIG's <tt>%module</tt> directive doesn't really have any
significance.
</p>
<H3><a name="Pike_nn8"></a>30.2.2 Functions</H3>
<H3><a name="Pike_nn8"></a>31.2.2 Functions</H3>
<p>
@ -168,11 +168,11 @@ exactly as you'd expect it to:
(1) Result: 24
</pre></div>
<H3><a name="Pike_nn9"></a>30.2.3 Global variables</H3>
<H3><a name="Pike_nn9"></a>31.2.3 Global variables</H3>
<p>
Global variables are currently wrapped as a pair of of functions, one to get
Global variables are currently wrapped as a pair of functions, one to get
the current value of the variable and another to set it. For example, the
declaration
</p>
@ -197,7 +197,7 @@ will result in two functions, <tt>Foo_get()</tt> and <tt>Foo_set()</tt>:
(3) Result: 3.141590
</pre></div>
<H3><a name="Pike_nn10"></a>30.2.4 Constants and enumerated types</H3>
<H3><a name="Pike_nn10"></a>31.2.4 Constants and enumerated types</H3>
<p>
@ -205,7 +205,7 @@ Enumerated types in C/C++ declarations are wrapped as Pike constants,
not as Pike enums.
</p>
<H3><a name="Pike_nn11"></a>30.2.5 Constructors and Destructors</H3>
<H3><a name="Pike_nn11"></a>31.2.5 Constructors and Destructors</H3>
<p>
@ -213,7 +213,7 @@ Constructors are wrapped as <tt>create()</tt> methods, and destructors are
wrapped as <tt>destroy()</tt> methods, for Pike classes.
</p>
<H3><a name="Pike_nn12"></a>30.2.6 Static Members</H3>
<H3><a name="Pike_nn12"></a>31.2.6 Static Members</H3>
<p>

100
Doc/Manual/Preface.html
View file

@ -11,13 +11,12 @@
<div class="sectiontoc">
<ul>
<li><a href="#Preface_nn2">Introduction</a>
<li><a href="#Preface_nn3">Special Introduction for Version 1.3</a>
<li><a href="#Preface_nn4">SWIG Versions</a>
<li><a href="#Preface_nn5">SWIG resources</a>
<li><a href="#Preface_nn6">Prerequisites</a>
<li><a href="#Preface_nn7">Organization of this manual</a>
<li><a href="#Preface_nn8">How to avoid reading the manual</a>
<li><a href="#Preface_nn9">Backwards Compatibility</a>
<li><a href="#Preface_nn9">Backwards compatibility</a>
<li><a href="#Preface_nn10">Credits</a>
<li><a href="#Preface_nn11">Bug reports</a>
</ul>
@ -49,34 +48,22 @@ has since evolved into a general purpose tool that is used in a wide
variety of applications--in fact almost anything where C/C++ programming
is involved.
<H2><a name="Preface_nn3"></a>1.2 Special Introduction for Version 1.3</H2>
<H2><a name="Preface_nn4"></a>1.2 SWIG Versions</H2>
<p>
Since SWIG was released in 1996, its user base and applicability has
continued to grow. Although its rate of development has varied, an
active development effort has continued to make improvements to the
system. Today, nearly a dozen developers are working to create
SWIG-2.0---a system that aims to provide wrapping support for nearly
all of the ANSI C++ standard and approximately ten target languages
including Guile, Java, Mzscheme, Ocaml, Perl, Pike, PHP, Python, Ruby,
and Tcl.
In the late 1990's, the most stable version of SWIG was release
1.1p5. Versions 1.3.x were officially development versions and these were released
over a period of 10 years starting from the year 2000. The final version in the 1.3.x
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. The license was clarified
so that the code that SWIG generated could be distributed
under license terms of the user's choice/requirements and at the same time the SWIG
source was placed under the GNU General Public License version 3.
</p>
<H2><a name="Preface_nn4"></a>1.3 SWIG Versions</H2>
<p>
For several years, the most stable version of SWIG has been release
1.1p5. Starting with version 1.3, a new version numbering scheme has
been adopted. Odd version numbers (1.3, 1.5, etc.) represent
development versions of SWIG. Even version numbers (1.4, 1.6, etc.)
represent stable releases. Currently, developers are working to
create a stable SWIG-2.0 release. Don't let the development status
of SWIG-1.3 scare you---it is much more stable (and capable) than SWIG-1.1p5.
</p>
<H2><a name="Preface_nn5"></a>1.4 SWIG resources</H2>
<H2><a name="Preface_nn5"></a>1.3 SWIG resources</H2>
<p>
@ -106,7 +93,7 @@ SWIG along with information about beta releases and future work.
</p>
<p>
SVN access to the latest version of SWIG is also available. More information
Subversion access to the latest version of SWIG is also available. More information
about this can be obtained at:
</p>
@ -115,7 +102,7 @@ about this can be obtained at:
</pre></div>
<H2><a name="Preface_nn6"></a>1.5 Prerequisites</H2>
<H2><a name="Preface_nn6"></a>1.4 Prerequisites</H2>
<p>
@ -132,7 +119,7 @@ writing a normal C program.
</p>
<p>
Recent SWIG releases have become significantly more capable in
Over time SWIG releases have become significantly more capable in
their C++ handling--especially support for advanced features like
namespaces, overloaded operators, and templates. Whenever possible,
this manual tries to cover the technicalities of this interface.
@ -140,7 +127,7 @@ However, this isn't meant to be a tutorial on C++ programming. For many
of the gory details, you will almost certainly want to consult a good C++ reference. If you don't program
in C++, you may just want to skip those parts of the manual.
<H2><a name="Preface_nn7"></a>1.6 Organization of this manual</H2>
<H2><a name="Preface_nn7"></a>1.5 Organization of this manual</H2>
<p>
@ -149,11 +136,10 @@ provide an overview of its capabilities. The remaining chapters are
devoted to specific SWIG language modules and are self
contained. Thus, if you are using SWIG to build Python interfaces, you
can probably skip to that chapter and find almost everything you need
to know. Caveat: we are currently working on a documentation rewrite and many
of the older language module chapters are still somewhat out of date.
to know.
</p>
<H2><a name="Preface_nn8"></a>1.7 How to avoid reading the manual</H2>
<H2><a name="Preface_nn8"></a>1.6 How to avoid reading the manual</H2>
<p>
@ -165,24 +151,19 @@ The SWIG distribution also comes with a large directory of
examples that illustrate different topics.
</p>
<H2><a name="Preface_nn9"></a>1.8 Backwards Compatibility</H2>
<H2><a name="Preface_nn9"></a>1.7 Backwards compatibility</H2>
<p>
If you are a previous user of SWIG, don't expect recent versions of
SWIG to provide backwards compatibility. In fact, backwards
compatibility issues may arise even between successive 1.3.x releases.
Although these incompatibilities are regrettable, SWIG-1.3 is an active
development project. The primary goal of this effort is to make SWIG
If you are a previous user of SWIG, don't expect
SWIG to provide complete backwards compatibility.
Although the developers strive to the utmost to keep backwards compatibility,
this isn't always possible as the
primary goal over time is to make SWIG
better---a process that would simply be impossible if the developers
are constantly bogged down with backwards compatibility issues.
</p>
<p>
On a positive note, a few incompatibilities are a small price to pay
for the large number of new features that have been
added---namespaces, templates, smart pointers, overloaded methods,
operators, and more.
Potential incompatibilities are clearly marked in the detailed release notes
(CHANGES files).
</p>
@ -206,33 +187,20 @@ Note: The version symbol is not defined in the generated SWIG
wrapper file. The SWIG preprocessor has defined SWIG_VERSION since SWIG-1.3.11.
</p>
<H2><a name="Preface_nn10"></a>1.9 Credits</H2>
<H2><a name="Preface_nn10"></a>1.8 Credits</H2>
<p>
SWIG is an unfunded project that would not be possible without the
contributions of many people. Most recent SWIG development has been
supported by Matthias K&ouml;ppe, William Fulton, Lyle Johnson,
Richard Palmer, Thien-Thi Nguyen, Jason Stewart, Loic Dachary, Masaki
Fukushima, Luigi Ballabio, Sam Liddicott, Art Yerkes, Marcelo Matus,
Harco de Hilster, John Lenz, and Surendra Singhi.
contributions of many people working in their spare time.
If you have benefitted from using SWIG, please consider
<a href="http://www.swig.org/donate.html">Donating to SWIG</a> to keep development going.
There have been a large varied number of people
who have made contributions at all levels over time. Contributors
are mentioned either in the COPYRIGHT file or CHANGES files shipped with SWIG or in submitted bugs.
</p>
<p>
Historically, the following people contributed to early versions of SWIG.
Peter Lomdahl, Brad Holian, Shujia Zhou, Niels Jensen, and Tim Germann
at Los Alamos National Laboratory were the first users. Patrick
Tullmann at the University of Utah suggested the idea of automatic
documentation generation. John Schmidt and Kurtis Bleeker at the
University of Utah tested out the early versions. Chris Johnson
supported SWIG's developed at the University of Utah. John Buckman,
Larry Virden, and Tom Schwaller provided valuable input on the first
releases and improving the portability of SWIG. David Fletcher and
Gary Holt have provided a great deal of input on improving SWIG's
Perl5 implementation. Kevin Butler contributed the first Windows NT
port.
<H2><a name="Preface_nn11"></a>1.10 Bug reports</H2>
<H2><a name="Preface_nn11"></a>1.9 Bug reports</H2>
<p>

6
Doc/Manual/Preprocessor.html
View file

@ -81,7 +81,7 @@ Such information generally includes type declarations (e.g., <tt>typedef</tt>) a
C++ classes that might be used as base-classes for class declarations in the interface.
The use of <tt>%import</tt> is also important when SWIG is used to generate
extensions as a collection of related modules. This is an advanced topic and is described
in later in the <a href="Modules.html">Working with Modules</a> chapter.
in later in the <a href="Modules.html#Modules">Working with Modules</a> chapter.
</p>
<P>
@ -102,7 +102,7 @@ by SWIG when it is parsing the interface:
<div class="code"><pre>
SWIG Always defined when SWIG is processing a file
SWIGIMPORTED Defined when SWIG is importing a file with <tt>%import</tt>
SWIG_VERSION Hexadecimal number containing SWIG version,
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
@ -377,7 +377,7 @@ SWIG will strip the extra <tt>%</tt> and leave the preprocessor directive in the
<p>
<a href="Typemaps.html">Typemaps</a> support a special attribute called <tt>noblock</tt> where the { ... } delimiters can be used,
<a href="Typemaps.html#Typemaps">Typemaps</a> support a special attribute called <tt>noblock</tt> where the { ... } delimiters can be used,
but the delimiters are not actually generated into the code.
The effect is then similar to using "" or %{ %} delimiters but the code <b>is</b> run through the preprocessor. For example:
</p>

181
Doc/Manual/Python.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Python"></a>31 SWIG and Python</H1>
<H1><a name="Python"></a>32 SWIG and Python</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -128,7 +128,7 @@ very least, make sure you read the "<a href="SWIG.html#SWIG">SWIG
Basics</a>" chapter.
</p>
<H2><a name="Python_nn2"></a>31.1 Overview</H2>
<H2><a name="Python_nn2"></a>32.1 Overview</H2>
<p>
@ -155,10 +155,10 @@ described followed by a discussion of low-level implementation
details.
</p>
<H2><a name="Python_nn3"></a>31.2 Preliminaries</H2>
<H2><a name="Python_nn3"></a>32.2 Preliminaries</H2>
<H3><a name="Python_nn4"></a>31.2.1 Running SWIG</H3>
<H3><a name="Python_nn4"></a>32.2.1 Running SWIG</H3>
<p>
@ -256,7 +256,7 @@ The following sections have further practical examples and details on
how you might go about compiling and using the generated files.
</p>
<H3><a name="Python_nn6"></a>31.2.2 Using distutils</H3>
<H3><a name="Python_nn6"></a>32.2.2 Using distutils</H3>
<p>
@ -348,7 +348,7 @@ This same approach works on all platforms if the appropriate compiler is install
can even build extensions to the standard Windows Python using MingGW)
</p>
<H3><a name="Python_nn7"></a>31.2.3 Hand compiling a dynamic module</H3>
<H3><a name="Python_nn7"></a>32.2.3 Hand compiling a dynamic module</H3>
<p>
@ -396,7 +396,7 @@ module actually consists of two files; <tt>socket.py</tt> and
</p>
<H3><a name="Python_nn8"></a>31.2.4 Static linking</H3>
<H3><a name="Python_nn8"></a>32.2.4 Static linking</H3>
<p>
@ -475,7 +475,7 @@ If using static linking, you might want to rely on a different approach
(perhaps using distutils).
</p>
<H3><a name="Python_nn9"></a>31.2.5 Using your module</H3>
<H3><a name="Python_nn9"></a>32.2.5 Using your module</H3>
<p>
@ -632,7 +632,7 @@ system configuration (this requires root access and you will need to
read the man pages).
</p>
<H3><a name="Python_nn10"></a>31.2.6 Compilation of C++ extensions</H3>
<H3><a name="Python_nn10"></a>32.2.6 Compilation of C++ extensions</H3>
<p>
@ -724,7 +724,7 @@ erratic program behavior. If working with lots of software components, you
might want to investigate using a more formal standard such as COM.
</p>
<H3><a name="Python_nn11"></a>31.2.7 Compiling for 64-bit platforms</H3>
<H3><a name="Python_nn11"></a>32.2.7 Compiling for 64-bit platforms</H3>
<p>
@ -761,7 +761,7 @@ and -m64 allow you to choose the desired binary format for your python
extension.
</p>
<H3><a name="Python_nn12"></a>31.2.8 Building Python Extensions under Windows</H3>
<H3><a name="Python_nn12"></a>32.2.8 Building Python Extensions under Windows</H3>
<p>
@ -870,7 +870,7 @@ SWIG Wiki</a>.
</p>
<H2><a name="Python_nn13"></a>31.3 A tour of basic C/C++ wrapping</H2>
<H2><a name="Python_nn13"></a>32.3 A tour of basic C/C++ wrapping</H2>
<p>
@ -879,7 +879,7 @@ to your C/C++ code. Functions are wrapped as functions, classes are wrapped as
This section briefly covers the essential aspects of this wrapping.
</p>
<H3><a name="Python_nn14"></a>31.3.1 Modules</H3>
<H3><a name="Python_nn14"></a>32.3.1 Modules</H3>
<p>
@ -892,7 +892,7 @@ module name, make sure you don't use the same name as a built-in
Python command or standard module name.
</p>
<H3><a name="Python_nn15"></a>31.3.2 Functions</H3>
<H3><a name="Python_nn15"></a>32.3.2 Functions</H3>
<p>
@ -916,7 +916,7 @@ like you think it does:
&gt;&gt;&gt;
</pre></div>
<H3><a name="Python_nn16"></a>31.3.3 Global variables</H3>
<H3><a name="Python_nn16"></a>32.3.3 Global variables</H3>
<p>
@ -1054,7 +1054,7 @@ that starts with a leading underscore. SWIG does not create <tt>cvar</tt>
if there are no global variables in a module.
</p>
<H3><a name="Python_nn17"></a>31.3.4 Constants and enums</H3>
<H3><a name="Python_nn17"></a>32.3.4 Constants and enums</H3>
<p>
@ -1094,7 +1094,7 @@ other object. Unfortunately, there is no easy way for SWIG to
generate code that prevents this. You will just have to be careful.
</p>
<H3><a name="Python_nn18"></a>31.3.5 Pointers</H3>
<H3><a name="Python_nn18"></a>32.3.5 Pointers</H3>
<p>
@ -1235,7 +1235,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return
<tt>None</tt> if the conversion can't be performed.
</p>
<H3><a name="Python_nn19"></a>31.3.6 Structures</H3>
<H3><a name="Python_nn19"></a>32.3.6 Structures</H3>
<p>
@ -1282,7 +1282,7 @@ something like this:
<p>
This object is actually a Python instance that has been wrapped around a pointer to the low-level
C structure. This instance doesn't actually do anything--it just serves as a proxy.
The pointer to the C object can be found in the the <tt>.this</tt>
The pointer to the C object can be found in the <tt>.this</tt>
attribute. For example:
</p>
@ -1424,7 +1424,7 @@ everything works just like you would expect. For example:
</pre>
</div>
<H3><a name="Python_nn20"></a>31.3.7 C++ classes</H3>
<H3><a name="Python_nn20"></a>32.3.7 C++ classes</H3>
<p>
@ -1513,7 +1513,7 @@ they are accessed through <tt>cvar</tt> like this:
</pre>
</div>
<H3><a name="Python_nn21"></a>31.3.8 C++ inheritance</H3>
<H3><a name="Python_nn21"></a>32.3.8 C++ inheritance</H3>
<p>
@ -1568,7 +1568,7 @@ then the function <tt>spam()</tt> accepts <tt>Foo *</tt> or a pointer to any cla
It is safe to use multiple inheritance with SWIG.
</p>
<H3><a name="Python_nn22"></a>31.3.9 Pointers, references, values, and arrays</H3>
<H3><a name="Python_nn22"></a>32.3.9 Pointers, references, values, and arrays</H3>
<p>
@ -1629,7 +1629,7 @@ treated as a returning value, and it will follow the same
allocation/deallocation process.
</p>
<H3><a name="Python_nn23"></a>31.3.10 C++ overloaded functions</H3>
<H3><a name="Python_nn23"></a>32.3.10 C++ overloaded functions</H3>
<p>
@ -1752,7 +1752,7 @@ first declaration takes precedence.
Please refer to the "SWIG and C++" chapter for more information about overloading.
</p>
<H3><a name="Python_nn24"></a>31.3.11 C++ operators</H3>
<H3><a name="Python_nn24"></a>32.3.11 C++ operators</H3>
<p>
@ -1841,7 +1841,7 @@ Also, be aware that certain operators don't map cleanly to Python. For instance
overloaded assignment operators don't map to Python semantics and will be ignored.
</p>
<H3><a name="Python_nn25"></a>31.3.12 C++ namespaces</H3>
<H3><a name="Python_nn25"></a>32.3.12 C++ namespaces</H3>
<p>
@ -1908,7 +1908,7 @@ utilizes thousands of small deeply nested namespaces each with
identical symbol names, well, then you get what you deserve.
</p>
<H3><a name="Python_nn26"></a>31.3.13 C++ templates</H3>
<H3><a name="Python_nn26"></a>32.3.13 C++ templates</H3>
<p>
@ -1962,7 +1962,7 @@ Some more complicated
examples will appear later.
</p>
<H3><a name="Python_nn27"></a>31.3.14 C++ Smart Pointers</H3>
<H3><a name="Python_nn27"></a>32.3.14 C++ Smart Pointers</H3>
<p>
@ -2047,7 +2047,7 @@ simply use the <tt>__deref__()</tt> method. For example:
</div>
<H3><a name="Python_nn27a"></a>31.3.15 C++ Reference Counted Objects (ref/unref)</H3>
<H3><a name="Python_nn27a"></a>32.3.15 C++ Reference Counted Objects (ref/unref)</H3>
<p>
@ -2124,8 +2124,8 @@ Object 'RCObj', which implements the ref/unref idiom.
<p>
To tell SWIG that 'RCObj' and all its derived classes are reference
counted objects, you use the "ref" and "unref" features, or
<tt>%ref</tt> and <tt>%unref</tt> directives (since 1.3.28). For example:
counted objects, you use the "ref" and "unref" features.
For example:
</p>
@ -2143,25 +2143,6 @@ counted objects, you use the "ref" and "unref" features, or
</pre>
</div>
or, using the directive form:
<div class="code">
<pre>
%module example
...
%ref RCObj "$this-&gt;ref();"
%unref RCObj "$this-&gt;unref();"
%include "rcobj.h"
%include "A.h"
...
</pre>
</div>
<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
@ -2209,7 +2190,7 @@ python releases the proxy instance.
</p>
<H2><a name="Python_nn28"></a>31.4 Further details on the Python class interface</H2>
<H2><a name="Python_nn28"></a>32.4 Further details on the Python class interface</H2>
<p>
@ -2222,7 +2203,7 @@ of low-level details were omitted. This section provides a brief overview
of how the proxy classes work.
</p>
<H3><a name="Python_nn29"></a>31.4.1 Proxy classes</H3>
<H3><a name="Python_nn29"></a>32.4.1 Proxy classes</H3>
<p>
@ -2311,7 +2292,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_nn30"></a>31.4.2 Memory management</H3>
<H3><a name="Python_nn30"></a>32.4.2 Memory management</H3>
<p>
@ -2503,7 +2484,7 @@ It is also possible to deal with situations like this using
typemaps--an advanced topic discussed later.
</p>
<H3><a name="Python_nn31"></a>31.4.3 Python 2.2 and classic classes</H3>
<H3><a name="Python_nn31"></a>32.4.3 Python 2.2 and classic classes</H3>
<p>
@ -2513,7 +2494,7 @@ 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="//www.python.org">www.python.org</a> and is not repeated here.
href="http://www.python.org">www.python.org</a> and is not repeated here.
</p>
<p>
@ -2540,7 +2521,7 @@ class itself. In Python-2.1 and earlier, they have to be accessed as a global
function or through an instance (see the earlier section).
</p>
<H2><a name="Python_directors"></a>31.5 Cross language polymorphism</H2>
<H2><a name="Python_directors"></a>32.5 Cross language polymorphism</H2>
<p>
@ -2574,7 +2555,7 @@ proxy classes, director classes, and C wrapper functions takes care of
all the cross-language method routing transparently.
</p>
<H3><a name="Python_nn33"></a>31.5.1 Enabling directors</H3>
<H3><a name="Python_nn33"></a>32.5.1 Enabling directors</H3>
<p>
@ -2667,7 +2648,7 @@ class MyFoo(mymodule.Foo):
</div>
<H3><a name="Python_nn34"></a>31.5.2 Director classes</H3>
<H3><a name="Python_nn34"></a>32.5.2 Director classes</H3>
@ -2749,7 +2730,7 @@ so there is no need for the extra overhead involved with routing the
calls through Python.
</p>
<H3><a name="Python_nn35"></a>31.5.3 Ownership and object destruction</H3>
<H3><a name="Python_nn35"></a>32.5.3 Ownership and object destruction</H3>
<p>
@ -2801,12 +2782,12 @@ public:
<div class="targetlang">
<pre>
&gt;&gt;&gt; c = FooContainer()
&gt;&gt;&gt; a = Foo().__disown()__
&gt;&gt;&gt; a = Foo().__disown__()
&gt;&gt;&gt; c.addFoo(a)
&gt;&gt;&gt; b = Foo()
&gt;&gt;&gt; b = b.__disown()__
&gt;&gt;&gt; b = b.__disown__()
&gt;&gt;&gt; c.addFoo(b)
&gt;&gt;&gt; c.addFoo(Foo().__disown()__)
&gt;&gt;&gt; c.addFoo(Foo().__disown__())
</pre>
</div>
@ -2816,7 +2797,7 @@ deleting all the Foo pointers it contains at some point. Note that no hard
references to the Foo objects remain in Python.
</p>
<H3><a name="Python_nn36"></a>31.5.4 Exception unrolling</H3>
<H3><a name="Python_nn36"></a>32.5.4 Exception unrolling</H3>
<p>
@ -2875,7 +2856,7 @@ Swig::DirectorMethodException is thrown, Python will register the
exception as soon as the C wrapper function returns.
</p>
<H3><a name="Python_nn37"></a>31.5.5 Overhead and code bloat</H3>
<H3><a name="Python_nn37"></a>32.5.5 Overhead and code bloat</H3>
<p>
@ -2909,7 +2890,7 @@ directive) for only those methods that are likely to be extended in
Python.
</p>
<H3><a name="Python_nn38"></a>31.5.6 Typemaps</H3>
<H3><a name="Python_nn38"></a>32.5.6 Typemaps</H3>
<p>
@ -2923,7 +2904,7 @@ need to be supported.
</p>
<H3><a name="Python_nn39"></a>31.5.7 Miscellaneous</H3>
<H3><a name="Python_nn39"></a>32.5.7 Miscellaneous</H3>
<p>
@ -2970,7 +2951,7 @@ methods that return const references.
</p>
<H2><a name="Python_nn40"></a>31.6 Common customization features</H2>
<H2><a name="Python_nn40"></a>32.6 Common customization features</H2>
<p>
@ -2983,7 +2964,7 @@ This section describes some common SWIG features that are used to
improve your the interface to an extension module.
</p>
<H3><a name="Python_nn41"></a>31.6.1 C/C++ helper functions</H3>
<H3><a name="Python_nn41"></a>32.6.1 C/C++ helper functions</H3>
<p>
@ -3064,7 +3045,7 @@ hard to implement. It is possible to clean this up using Python code, typemaps,
customization features as covered in later sections.
</p>
<H3><a name="Python_nn42"></a>31.6.2 Adding additional Python code</H3>
<H3><a name="Python_nn42"></a>32.6.2 Adding additional Python code</H3>
<p>
@ -3120,7 +3101,7 @@ customization features.
<p>Sometimes you may want to replace or modify the wrapper function
that SWIG creates in the proxy <tt>.py</tt> file. The Python module
in SWIG provides some features that enable you do do this. First, to
in SWIG provides some features that enable you to do this. First, to
entirely replace a proxy function you can use
<tt>%feature("shadow")</tt>. For example:</p>
@ -3213,7 +3194,7 @@ public:
<H3><a name="Python_nn43"></a>31.6.3 Class extension with %extend</H3>
<H3><a name="Python_nn43"></a>32.6.3 Class extension with %extend</H3>
<p>
@ -3302,7 +3283,7 @@ Vector(12,14,16)
in any way---the extensions only show up in the Python interface.
</p>
<H3><a name="Python_nn44"></a>31.6.4 Exception handling with %exception</H3>
<H3><a name="Python_nn44"></a>32.6.4 Exception handling with %exception</H3>
<p>
@ -3428,7 +3409,7 @@ The language-independent <tt>exception.i</tt> library file can also be used
to raise exceptions. See the <a href="Library.html#Library">SWIG Library</a> chapter.
</p>
<H2><a name="Python_nn45"></a>31.7 Tips and techniques</H2>
<H2><a name="Python_nn45"></a>32.7 Tips and techniques</H2>
<p>
@ -3438,7 +3419,7 @@ strings, binary data, and arrays. This chapter discusses the common techniques
solving these problems.
</p>
<H3><a name="Python_nn46"></a>31.7.1 Input and output parameters</H3>
<H3><a name="Python_nn46"></a>32.7.1 Input and output parameters</H3>
<p>
@ -3651,7 +3632,7 @@ void foo(Bar *OUTPUT);
may not have the intended effect since <tt>typemaps.i</tt> does not define an OUTPUT rule for <tt>Bar</tt>.
</p>
<H3><a name="Python_nn47"></a>31.7.2 Simple pointers</H3>
<H3><a name="Python_nn47"></a>32.7.2 Simple pointers</H3>
<p>
@ -3720,7 +3701,7 @@ If you replace <tt>%pointer_functions()</tt> by <tt>%pointer_class(type,name)</t
See the <a href="Library.html#Library">SWIG Library</a> chapter for further details.
</p>
<H3><a name="Python_nn48"></a>31.7.3 Unbounded C Arrays</H3>
<H3><a name="Python_nn48"></a>32.7.3 Unbounded C Arrays</H3>
<p>
@ -3782,7 +3763,7 @@ well suited for applications in which you need to create buffers,
package binary data, etc.
</p>
<H3><a name="Python_nn49"></a>31.7.4 String handling</H3>
<H3><a name="Python_nn49"></a>32.7.4 String handling</H3>
<p>
@ -3851,7 +3832,7 @@ If you need to return binary data, you might use the
also be used to extra binary data from arbitrary pointers.
</p>
<H2><a name="Python_nn53"></a>31.8 Typemaps</H2>
<H2><a name="Python_nn53"></a>32.8 Typemaps</H2>
<p>
@ -3868,7 +3849,7 @@ Typemaps are only used if you want to change some aspect of the primitive
C-Python interface or if you want to elevate your guru status.
</p>
<H3><a name="Python_nn54"></a>31.8.1 What is a typemap?</H3>
<H3><a name="Python_nn54"></a>32.8.1 What is a typemap?</H3>
<p>
@ -3984,7 +3965,7 @@ parameter is omitted):
</pre>
</div>
<H3><a name="Python_nn55"></a>31.8.2 Python typemaps</H3>
<H3><a name="Python_nn55"></a>32.8.2 Python typemaps</H3>
<p>
@ -4025,7 +4006,7 @@ a look at the SWIG library version 1.3.20 or so.
</p>
<H3><a name="Python_nn56"></a>31.8.3 Typemap variables</H3>
<H3><a name="Python_nn56"></a>32.8.3 Typemap variables</H3>
<p>
@ -4096,7 +4077,7 @@ properly assigned.
The Python name of the wrapper function being created.
</div>
<H3><a name="Python_nn57"></a>31.8.4 Useful Python Functions</H3>
<H3><a name="Python_nn57"></a>32.8.4 Useful Python Functions</H3>
<p>
@ -4224,7 +4205,7 @@ write me
</pre>
</div>
<H2><a name="Python_nn58"></a>31.9 Typemap Examples</H2>
<H2><a name="Python_nn58"></a>32.9 Typemap Examples</H2>
<p>
@ -4233,7 +4214,7 @@ might look at the files "<tt>python.swg</tt>" and "<tt>typemaps.i</tt>" in
the SWIG library.
</p>
<H3><a name="Python_nn59"></a>31.9.1 Converting Python list to a char ** </H3>
<H3><a name="Python_nn59"></a>32.9.1 Converting Python list to a char ** </H3>
<p>
@ -4313,7 +4294,7 @@ memory allocation is used to allocate memory for the array, the
the C function.
</p>
<H3><a name="Python_nn60"></a>31.9.2 Expanding a Python object into multiple arguments</H3>
<H3><a name="Python_nn60"></a>32.9.2 Expanding a Python object into multiple arguments</H3>
<p>
@ -4392,7 +4373,7 @@ to supply the argument count. This is automatically set by the typemap code. F
</pre>
</div>
<H3><a name="Python_nn61"></a>31.9.3 Using typemaps to return arguments</H3>
<H3><a name="Python_nn61"></a>32.9.3 Using typemaps to return arguments</H3>
<p>
@ -4481,7 +4462,7 @@ function can now be used as follows:
&gt;&gt;&gt;
</pre></div>
<H3><a name="Python_nn62"></a>31.9.4 Mapping Python tuples into small arrays</H3>
<H3><a name="Python_nn62"></a>32.9.4 Mapping Python tuples into small arrays</H3>
<p>
@ -4530,7 +4511,7 @@ array, such an approach would not be recommended for huge arrays, but
for small structures, this approach works fine.
</p>
<H3><a name="Python_nn63"></a>31.9.5 Mapping sequences to C arrays</H3>
<H3><a name="Python_nn63"></a>32.9.5 Mapping sequences to C arrays</H3>
<p>
@ -4619,7 +4600,7 @@ static int convert_darray(PyObject *input, double *ptr, int size) {
</pre>
</div>
<H3><a name="Python_nn64"></a>31.9.6 Pointer handling</H3>
<H3><a name="Python_nn64"></a>32.9.6 Pointer handling</H3>
<p>
@ -4716,7 +4697,7 @@ class object (if applicable).
<H2><a name="Python_nn65"></a>31.10 Docstring Features</H2>
<H2><a name="Python_nn65"></a>32.10 Docstring Features</H2>
<p>
@ -4744,7 +4725,7 @@ of your users much simpler.
</p>
<H3><a name="Python_nn66"></a>31.10.1 Module docstring</H3>
<H3><a name="Python_nn66"></a>32.10.1 Module docstring</H3>
<p>
@ -4778,7 +4759,7 @@ layout of controls on a panel, etc. to be loaded from an XML file."
</div>
<H3><a name="Python_nn67"></a>31.10.2 %feature("autodoc")</H3>
<H3><a name="Python_nn67"></a>32.10.2 %feature("autodoc")</H3>
<p>
@ -4805,7 +4786,7 @@ names, default values if any, and return type if any. There are also
three options for autodoc controlled by the value given to the
feature, described below.
<H4><a name="Python_nn68"></a>31.10.2.1 %feature("autodoc", "0")</H4>
<H4><a name="Python_nn68"></a>32.10.2.1 %feature("autodoc", "0")</H4>
<p>
@ -4834,7 +4815,7 @@ def function_name(*args, **kwargs):
</div>
<H4><a name="Python_nn69"></a>31.10.2.2 %feature("autodoc", "1")</H4>
<H4><a name="Python_nn69"></a>32.10.2.2 %feature("autodoc", "1")</H4>
<p>
@ -4859,7 +4840,7 @@ def function_name(*args, **kwargs):
<H4><a name="Python_nn70"></a>31.10.2.3 %feature("autodoc", "docstring")</H4>
<H4><a name="Python_nn70"></a>32.10.2.3 %feature("autodoc", "docstring")</H4>
<p>
@ -4878,7 +4859,7 @@ void GetPosition(int* OUTPUT, int* OUTPUT);
</div>
<H3><a name="Python_nn71"></a>31.10.3 %feature("docstring")</H3>
<H3><a name="Python_nn71"></a>32.10.3 %feature("docstring")</H3>
<p>
@ -4910,7 +4891,7 @@ with more than one line.
</pre>
</div>
<H2><a name="Python_nn72"></a>31.11 Python Packages</H2>
<H2><a name="Python_nn72"></a>32.11 Python Packages</H2>
<p>
@ -4937,7 +4918,7 @@ and also in base class declarations, etc. if the package name is
different than its own.
</p>
<H2><a name="Python_python3support"></a>31.12 Python 3 Support</H2>
<H2><a name="Python_python3support"></a>32.12 Python 3 Support</H2>
<p>
@ -4964,7 +4945,7 @@ The following are Python 3.0 new features that are currently supported by
SWIG.
</p>
<H3><a name="Python_nn74"></a>31.12.1 Function annotation</H3>
<H3><a name="Python_nn74"></a>32.12.1 Function annotation</H3>
<p>
@ -4996,7 +4977,7 @@ all overloaded functions share the same function in SWIG generated proxy class.
For detailed usage of function annotation, see PEP 3107.
</p>
<H3><a name="Python_nn75"></a>31.12.2 Buffer interface</H3>
<H3><a name="Python_nn75"></a>32.12.2 Buffer interface</H3>
<p>
@ -5148,7 +5129,7 @@ modify the buffer.
</div>
<H3><a name="Python_nn76"></a>31.12.3 Abstract base classes</H3>
<H3><a name="Python_nn76"></a>32.12.3 Abstract base classes</H3>
<p>

50
Doc/Manual/R.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="R"></a>34 SWIG and R</H1>
<H1><a name="R"></a>35 SWIG and R</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -33,7 +33,7 @@ compile and run an R interface to QuantLib running on Mandriva Linux
with gcc. The R bindings also work on Microsoft Windows using Visual C++.
</p>
<H2><a name="R_nn2"></a>34.1 Bugs</H2>
<H2><a name="R_nn2"></a>35.1 Bugs</H2>
<p>
@ -45,7 +45,7 @@ Currently the following features are not implemented or broken:
<li>C Array wrappings
</ul>
<H2><a name="R_nn3"></a>34.2 Using R and SWIG</H2>
<H2><a name="R_nn3"></a>35.2 Using R and SWIG</H2>
<p>
@ -56,28 +56,48 @@ example.c is the name of the file with the functions in them
<div class="shell">
<pre>
swig -r example.i
PKG_LIBS="example.c" R CMD SHLIB example_wrap.c
R CMD SHLIB example_wrap.c example.c
</pre>
</div>
<p>
The corresponding comments for C++ mode are
The corresponding options for C++ mode are
</p>
<div class="shell">
<pre>
swig -c++ -r -o example_wrap.cpp example.i
PKG_LIBS="example.cxx" R CMD SHLIB example_wrap.cpp
R CMD SHLIB example_wrap.cpp example.cpp
</pre>
</div>
<p>
Note that R is sensitive to the name of the file and to the file
extension in C and C++ mode. The name of the wrapper file must be the
name of the library. Also in C++ mode, the file extension must be .cpp
rather than .cxx for the R compile command to recognize it.
Note that R is sensitive to the names of the files.
The name of the wrapper file must be the
name of the library unless you use the -o option to R when building the library, for example:
</p>
<div class="shell">
<pre>
swig -c++ -r -o example_wrap.cpp example.i
R CMD SHLIB -o example.so example_wrap.cpp example.cpp
</pre>
</div>
<p>
R is also sensitive to the name of the file
extension in C and C++ mode. In C++ mode, the file extension must be .cpp
rather than .cxx for the R compile command to recognize it. If your C++ code is
in a file using something other than a .cpp extension, then it may still work using PKG_LIBS:
</p>
<div class="shell">
<pre>
swig -c++ -r -o example_wrap.cpp example.i
PKG_LIBS="example.cxx" R CMD SHLIB -o example example_wrap.cpp
</pre>
</div>
<p>
The commands produces two files. A dynamic shared object file called
example.so, or example.dll, and an R wrapper file called example.R. To load these
@ -99,7 +119,7 @@ Without it, inheritance of wrapped objects may fail.
These two files can be loaded in any order
</p>
<H2><a name="R_nn4"></a>34.3 Precompiling large R files</H2>
<H2><a name="R_nn4"></a>35.3 Precompiling large R files</H2>
In cases where the R file is large, one make save a lot of loading
@ -117,7 +137,7 @@ will save a large amount of loading time.
<H2><a name="R_nn5"></a>34.4 General policy</H2>
<H2><a name="R_nn5"></a>35.4 General policy</H2>
<p>
@ -126,7 +146,7 @@ wrapping over the underlying functions and rely on the R type system
to provide R syntax.
</p>
<H2><a name="R_language_conventions"></a>34.5 Language conventions</H2>
<H2><a name="R_language_conventions"></a>35.5 Language conventions</H2>
<p>
@ -135,7 +155,7 @@ and [ are overloaded to allow for R syntax (one based indices and
slices)
</p>
<H2><a name="R_nn6"></a>34.6 C++ classes</H2>
<H2><a name="R_nn6"></a>35.6 C++ classes</H2>
<p>
@ -147,7 +167,7 @@ keep track of the pointer object which removes the necessity for a lot
of the proxy class baggage you see in other languages.
</p>
<H2><a name="R_nn7"></a>34.7 Enumerations</H2>
<H2><a name="R_nn7"></a>35.7 Enumerations</H2>
<p>

220
Doc/Manual/Ruby.html
View file

@ -26,7 +26,7 @@
<H1><a name="Ruby"></a>32 SWIG and Ruby</H1>
<H1><a name="Ruby"></a>33 SWIG and Ruby</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -58,7 +58,7 @@
<li><a href="#Ruby_nn22">C++ namespaces</a>
<li><a href="#Ruby_nn23">C++ templates</a>
<li><a href="#Ruby_nn23_1">C++ Standard Template Library (STL)</a>
<li><a href="#C_STL_Functors">C++ STL Functors</a>
<li><a href="#Ruby_C_STL_Functors">C++ STL Functors</a>
<li><a href="#Ruby_C_Iterators">C++ STL Iterators</a>
<li><a href="#Ruby_nn24">C++ Smart Pointers</a>
<li><a href="#Ruby_nn25">Cross-Language Polymorphism</a>
@ -142,7 +142,7 @@
</ul>
<li><a href="#Ruby_nn53">Advanced Topics</a>
<ul>
<li><a href="#Ruby_nn54">Operator overloading</a>
<li><a href="#Ruby_operator_overloading">Operator overloading</a>
<li><a href="#Ruby_nn55">Creating Multi-Module Packages</a>
<li><a href="#Ruby_nn56">Specifying Mixin Modules</a>
</ul>
@ -167,7 +167,7 @@
<H2><a name="Ruby_nn2"></a>32.1 Preliminaries</H2>
<H2><a name="Ruby_nn2"></a>33.1 Preliminaries</H2>
<p> SWIG 1.3 is known to work with Ruby versions 1.6 and later.
@ -190,7 +190,7 @@ of Ruby. </p>
<H3><a name="Ruby_nn3"></a>32.1.1 Running SWIG</H3>
<H3><a name="Ruby_nn3"></a>33.1.1 Running SWIG</H3>
<p> To build a Ruby module, run SWIG using the <tt>-ruby</tt>
@ -244,7 +244,7 @@ to compile this file and link it with the rest of your program. </p>
<H3><a name="Ruby_nn4"></a>32.1.2 Getting the right header files</H3>
<H3><a name="Ruby_nn4"></a>33.1.2 Getting the right header files</H3>
<p> In order to compile the wrapper code, the compiler needs the <tt>ruby.h</tt>
@ -288,7 +288,7 @@ installed, you can run Ruby to find out. For example: </p>
<H3><a name="Ruby_nn5"></a>32.1.3 Compiling a dynamic module</H3>
<H3><a name="Ruby_nn5"></a>33.1.3 Compiling a dynamic module</H3>
<p> Ruby extension modules are typically compiled into shared
@ -443,7 +443,7 @@ manual pages for your compiler and linker to determine the correct set
of options. You might also check the <a href="http://www.dabeaz.com/cgi-bin/wiki.pl">SWIG Wiki</a>
for additional information. </p>
<H3><a name="Ruby_nn6"></a>32.1.4 Using your module</H3>
<H3><a name="Ruby_nn6"></a>33.1.4 Using your module</H3>
<p> Ruby <i>module</i> names must be capitalized,
@ -498,7 +498,7 @@ begins with: </p>
<H3><a name="Ruby_nn7"></a>32.1.5 Static linking</H3>
<H3><a name="Ruby_nn7"></a>33.1.5 Static linking</H3>
<p> An alternative approach to dynamic linking is to rebuild the
@ -519,7 +519,7 @@ finally rebuilding Ruby. </p>
<H3><a name="Ruby_nn8"></a>32.1.6 Compilation of C++ extensions</H3>
<H3><a name="Ruby_nn8"></a>33.1.6 Compilation of C++ extensions</H3>
<p> On most machines, C++ extension modules should be linked
@ -571,7 +571,7 @@ extension, e.g. </p>
<H2><a name="Ruby_nn9"></a>32.2 Building Ruby Extensions under Windows 95/NT</H2>
<H2><a name="Ruby_nn9"></a>33.2 Building Ruby Extensions under Windows 95/NT</H2>
<p> Building a SWIG extension to Ruby under Windows 95/NT is
@ -610,7 +610,7 @@ files. </p>
<H3><a name="Ruby_nn10"></a>32.2.1 Running SWIG from Developer Studio</H3>
<H3><a name="Ruby_nn10"></a>33.2.1 Running SWIG from Developer Studio</H3>
<p> If you are developing your application within Microsoft
@ -752,7 +752,7 @@ directory, then run the Ruby script from the DOS/Command prompt: </p>
<H2><a name="Ruby_nn11"></a>32.3 The Ruby-to-C/C++ Mapping</H2>
<H2><a name="Ruby_nn11"></a>33.3 The Ruby-to-C/C++ Mapping</H2>
<p> This section describes the basics of how SWIG maps C or C++
@ -762,7 +762,7 @@ declarations in your SWIG interface files to Ruby constructs. </p>
<H3><a name="Ruby_nn12"></a>32.3.1 Modules</H3>
<H3><a name="Ruby_nn12"></a>33.3.1 Modules</H3>
<p> The SWIG <tt>%module</tt> directive specifies
@ -931,7 +931,7 @@ Ruby's built-in names. </p>
<H3><a name="Ruby_nn13"></a>32.3.2 Functions</H3>
<H3><a name="Ruby_nn13"></a>33.3.2 Functions</H3>
<p> Global functions are wrapped as Ruby module methods. For
@ -994,7 +994,7 @@ module that can be used like so: </p>
<H3><a name="Ruby_nn14"></a>32.3.3 Variable Linking</H3>
<H3><a name="Ruby_nn14"></a>33.3.3 Variable Linking</H3>
<p> C/C++ global variables are wrapped as a pair of singleton
@ -1094,7 +1094,7 @@ effect until it is explicitly disabled using <tt>%mutable</tt>.
<H3><a name="Ruby_nn15"></a>32.3.4 Constants</H3>
<H3><a name="Ruby_nn15"></a>33.3.4 Constants</H3>
<p> C/C++ constants are wrapped as module constants initialized
@ -1138,7 +1138,7 @@ constant values, e.g. </p>
<H3><a name="Ruby_nn16"></a>32.3.5 Pointers</H3>
<H3><a name="Ruby_nn16"></a>33.3.5 Pointers</H3>
<p> "Opaque" pointers to arbitrary C/C++ types (i.e. types that
@ -1190,7 +1190,7 @@ the Ruby <tt>nil</tt> object. </p>
<H3><a name="Ruby_nn17"></a>32.3.6 Structures</H3>
<H3><a name="Ruby_nn17"></a>33.3.6 Structures</H3>
<p> C/C++ structs are wrapped as Ruby classes, with accessor
@ -1317,7 +1317,7 @@ this code: </p>
<p> If you want to set an array member, you will need to supply a
"memberin" typemap described in the <a href="#ruby_cpp_smart_pointers">section on typemaps</a>.
"memberin" typemap described in the <a href="#Ruby_memberin_typemap">section on typemaps</a>.
As a special case, SWIG does generate code to set array members of type
<tt>char</tt> (allowing you to store a Ruby string in the
structure). </p>
@ -1365,7 +1365,7 @@ pointers. For example, </p>
<H3><a name="Ruby_nn18"></a>32.3.7 C++ classes</H3>
<H3><a name="Ruby_nn18"></a>33.3.7 C++ classes</H3>
<p> Like structs, C++ classes are wrapped by creating a new Ruby
@ -1451,7 +1451,7 @@ class. </li>
<H3><a name="Ruby_nn19"></a>32.3.8 C++ Inheritance</H3>
<H3><a name="Ruby_nn19"></a>33.3.8 C++ Inheritance</H3>
<p> The SWIG type-checker is fully aware of C++ inheritance.
@ -1682,7 +1682,7 @@ Typing"</a>). </p>
<H3><a name="Ruby_nn20"></a>32.3.9 C++ Overloaded Functions</H3>
<H3><a name="Ruby_nn20"></a>33.3.9 C++ Overloaded Functions</H3>
<p> C++ overloaded functions, methods, and constructors are
@ -1882,7 +1882,7 @@ and C++"</a> chapter for more information about overloading. </p>
<H3><a name="Ruby_nn21"></a>32.3.10 C++ Operators</H3>
<H3><a name="Ruby_nn21"></a>33.3.10 C++ Operators</H3>
<p> For the most part, overloaded operators are handled
@ -1956,14 +1956,14 @@ example: </p>
<p> More details about wrapping C++ operators into Ruby operators
is discussed in the <a href="#ruby_operator_overloading">section
is discussed in the <a href="#Ruby_operator_overloading">section
on operator overloading</a>. </p>
<H3><a name="Ruby_nn22"></a>32.3.11 C++ namespaces</H3>
<H3><a name="Ruby_nn22"></a>33.3.11 C++ namespaces</H3>
<p> SWIG is aware of C++ namespaces, but namespace names do not
@ -2039,7 +2039,7 @@ identical symbol names, well, then you get what you deserve. </p>
<H3><a name="Ruby_nn23"></a>32.3.12 C++ templates</H3>
<H3><a name="Ruby_nn23"></a>33.3.12 C++ templates</H3>
<p> C++ templates don't present a huge problem for SWIG. However,
@ -2083,7 +2083,7 @@ directive. For example: </p>
<H3><a name="Ruby_nn23_1"></a>32.3.13 C++ Standard Template Library (STL)</H3>
<H3><a name="Ruby_nn23_1"></a>33.3.13 C++ Standard Template Library (STL)</H3>
<p> On a related note, the standard SWIG library contains a
@ -2336,7 +2336,7 @@ chapter.</p>
<H3><a name="C_STL_Functors"></a>32.3.14 C++ STL Functors</H3>
<H3><a name="Ruby_C_STL_Functors"></a>33.3.14 C++ STL Functors</H3>
<p>Some containers in the STL allow you to modify their default
@ -2536,7 +2536,7 @@ b<br style="font-weight: bold;">
<H3><a name="Ruby_C_Iterators"></a>32.3.15 C++ STL Iterators</H3>
<H3><a name="Ruby_C_Iterators"></a>33.3.15 C++ STL Iterators</H3>
<p>The STL is well known for the use of iterators. &nbsp;There
@ -2747,7 +2747,7 @@ i<br>
<H3><a name="Ruby_nn24"></a>32.3.16 C++ Smart Pointers</H3>
<H3><a name="Ruby_nn24"></a>33.3.16 C++ Smart Pointers</H3>
<p> In certain C++ programs, it is common to use classes that
@ -2872,12 +2872,12 @@ method. For example: </p>
<H3><a name="Ruby_nn25"></a>32.3.17 Cross-Language Polymorphism</H3>
<H3><a name="Ruby_nn25"></a>33.3.17 Cross-Language Polymorphism</H3>
<p> SWIG's Ruby module supports cross-language polymorphism
(a.k.a. the "directors" feature) similar to that for SWIG's Python
module. Rather than duplicate the information presented in the <a href="Ruby">Python</a> chapter, this
module. Rather than duplicate the information presented in the <a href="Python.html#Python">Python</a> chapter, this
section just notes the differences that you need to be aware of when
using this feature with Ruby. </p>
@ -2885,7 +2885,7 @@ using this feature with Ruby. </p>
<H4><a name="Ruby_nn26"></a>32.3.17.1 Exception Unrolling</H4>
<H4><a name="Ruby_nn26"></a>33.3.17.1 Exception Unrolling</H4>
<p> Whenever a C++ director class routes one of its virtual
@ -2923,7 +2923,7 @@ caught here and a C++ exception is raised in its place. </p>
<H2><a name="Ruby_nn27"></a>32.4 Naming</H2>
<H2><a name="Ruby_nn27"></a>33.4 Naming</H2>
<p>Ruby has several common naming conventions. Constants are
@ -3019,7 +3019,7 @@ planned to become the default option in future releases.</p>
<H3><a name="Ruby_nn28"></a>32.4.1 Defining Aliases</H3>
<H3><a name="Ruby_nn28"></a>33.4.1 Defining Aliases</H3>
<p> It's a fairly common practice in the Ruby built-ins and
@ -3111,7 +3111,7 @@ Features"</a>) for more details).</p>
<H3><a name="Ruby_nn29"></a>32.4.2 Predicate Methods</H3>
<H3><a name="Ruby_nn29"></a>33.4.2 Predicate Methods</H3>
<p> Ruby methods that return a boolean value and end in a
@ -3200,7 +3200,7 @@ Features"</a>) for more details). </p>
<H3><a name="Ruby_nn30"></a>32.4.3 Bang Methods</H3>
<H3><a name="Ruby_nn30"></a>33.4.3 Bang Methods</H3>
<p> Ruby methods that modify an object in-place and end in an
@ -3264,7 +3264,7 @@ Features"</a>) for more details). </p>
<H3><a name="Ruby_nn31"></a>32.4.4 Getters and Setters</H3>
<H3><a name="Ruby_nn31"></a>33.4.4 Getters and Setters</H3>
<p> Often times a C++ library will expose properties through
@ -3334,7 +3334,7 @@ methods to be exposed in Ruby as <tt>value</tt> and <tt>value=.
<H2><a name="Ruby_nn32"></a>32.5 Input and output parameters</H2>
<H2><a name="Ruby_nn32"></a>33.5 Input and output parameters</H2>
<p> A common problem in some C programs is handling parameters
@ -3585,10 +3585,10 @@ of <tt>%apply</tt> </p>
<H2><a name="Ruby_nn33"></a>32.6 Exception handling </H2>
<H2><a name="Ruby_nn33"></a>33.6 Exception handling </H2>
<H3><a name="Ruby_nn34"></a>32.6.1 Using the %exception directive </H3>
<H3><a name="Ruby_nn34"></a>33.6.1 Using the %exception directive </H3>
<p>The SWIG <tt>%exception</tt> directive can be
@ -3683,7 +3683,7 @@ Features</a> for more examples.</p>
<H3><a name="Ruby_nn34_2"></a>32.6.2 Handling Ruby Blocks </H3>
<H3><a name="Ruby_nn34_2"></a>33.6.2 Handling Ruby Blocks </H3>
<p>One of the highlights of Ruby and most of its standard library
@ -3864,7 +3864,7 @@ RUBY_YIELD_SELF );<br>
<p>For more information on typemaps, see <a href="#Ruby_nn37">Typemaps</a>.</p>
<H3><a name="Ruby_nn35"></a>32.6.3 Raising exceptions </H3>
<H3><a name="Ruby_nn35"></a>33.6.3 Raising exceptions </H3>
<p>There are three ways to raise exceptions from C++ code to
@ -4625,7 +4625,7 @@ the built-in Ruby exception types.</p>
<H3><a name="Ruby_nn36"></a>32.6.4 Exception classes </H3>
<H3><a name="Ruby_nn36"></a>33.6.4 Exception classes </H3>
<p>Starting with SWIG 1.3.28, the Ruby module supports the <tt>%exceptionclass</tt>
@ -4683,7 +4683,7 @@ providing for a more natural integration between C++ code and Ruby code.</p>
<H2><a name="Ruby_nn37"></a>32.7 Typemaps</H2>
<H2><a name="Ruby_nn37"></a>33.7 Typemaps</H2>
<p> This section describes how you can modify SWIG's default
@ -4706,7 +4706,7 @@ of the primitive C-Ruby interface.</p>
<H3><a name="Ruby_nn38"></a>32.7.1 What is a typemap?</H3>
<H3><a name="Ruby_nn38"></a>33.7.1 What is a typemap?</H3>
<p> A typemap is nothing more than a code generation rule that is
@ -4968,7 +4968,7 @@ to be used as follows (notice how the length parameter is omitted): </p>
<H3><a name="Ruby_Typemap_scope"></a>32.7.2 Typemap scope</H3>
<H3><a name="Ruby_Typemap_scope"></a>33.7.2 Typemap scope</H3>
<p> Once defined, a typemap remains in effect for all of the
@ -5016,7 +5016,7 @@ where the class itself is defined. For example:</p>
<H3><a name="Ruby_Copying_a_typemap"></a>32.7.3 Copying a typemap</H3>
<H3><a name="Ruby_Copying_a_typemap"></a>33.7.3 Copying a typemap</H3>
<p> A typemap is copied by using assignment. For example:</p>
@ -5118,7 +5118,7 @@ rules as for <tt>
<H3><a name="Ruby_Deleting_a_typemap"></a>32.7.4 Deleting a typemap</H3>
<H3><a name="Ruby_Deleting_a_typemap"></a>33.7.4 Deleting a typemap</H3>
<p> A typemap can be deleted by simply defining no code. For
@ -5170,7 +5170,7 @@ typemaps immediately after the clear operation.</p>
<H3><a name="Ruby_Placement_of_typemaps"></a>32.7.5 Placement of typemaps</H3>
<H3><a name="Ruby_Placement_of_typemaps"></a>33.7.5 Placement of typemaps</H3>
<p> Typemap declarations can be declared in the global scope,
@ -5254,7 +5254,7 @@ string</tt>
<H3><a name="Ruby_nn39"></a>32.7.6 Ruby typemaps</H3>
<H3><a name="Ruby_nn39"></a>33.7.6 Ruby typemaps</H3>
<p>The following list details all of the typemap methods that
@ -5264,7 +5264,7 @@ can be used by the Ruby module: </p>
<H4><a name="Ruby_in_typemap"></a>32.7.6.1 &nbsp;"in" typemap</H4>
<H4><a name="Ruby_in_typemap"></a>33.7.6.1 &nbsp;"in" typemap</H4>
<p>Converts Ruby objects to input
@ -5507,7 +5507,7 @@ arguments to be specified. For example:</p>
<H4><a name="Ruby_typecheck_typemap"></a>32.7.6.2 "typecheck" typemap</H4>
<H4><a name="Ruby_typecheck_typemap"></a>33.7.6.2 "typecheck" typemap</H4>
<p> The "typecheck" typemap is used to support overloaded
@ -5548,7 +5548,7 @@ on "Typemaps and Overloading."</p>
<H4><a name="Ruby_out_typemap"></a>32.7.6.3 &nbsp;"out" typemap</H4>
<H4><a name="Ruby_out_typemap"></a>33.7.6.3 &nbsp;"out" typemap</H4>
<p>Converts return value of a C function
@ -5780,7 +5780,7 @@ version of the C datatype matched by the typemap.</td>
<H4><a name="Ruby_arginit_typemap"></a>32.7.6.4 "arginit" typemap</H4>
<H4><a name="Ruby_arginit_typemap"></a>33.7.6.4 "arginit" typemap</H4>
<p> The "arginit" typemap is used to set the initial value of a
@ -5805,7 +5805,7 @@ applications. For example:</p>
<H4><a name="Ruby_default_typemap"></a>32.7.6.5 "default" typemap</H4>
<H4><a name="Ruby_default_typemap"></a>33.7.6.5 "default" typemap</H4>
<p> The "default" typemap is used to turn an argument into a
@ -5847,7 +5847,7 @@ default argument wrapping.</p>
<H4><a name="Ruby_check_typemap"></a>32.7.6.6 "check" typemap</H4>
<H4><a name="Ruby_check_typemap"></a>33.7.6.6 "check" typemap</H4>
<p> The "check" typemap is used to supply value checking code
@ -5871,7 +5871,7 @@ arguments have been converted. For example:</p>
<H4><a name="Ruby_argout_typemap_"></a>32.7.6.7 "argout" typemap</H4>
<H4><a name="Ruby_argout_typemap_"></a>33.7.6.7 "argout" typemap</H4>
<p> The "argout" typemap is used to return values from arguments.
@ -6029,7 +6029,7 @@ some function like SWIG_Ruby_AppendOutput.</p>
<H4><a name="Ruby_freearg_typemap_"></a>32.7.6.8 "freearg" typemap</H4>
<H4><a name="Ruby_freearg_typemap_"></a>33.7.6.8 "freearg" typemap</H4>
<p> The "freearg" typemap is used to cleanup argument data. It is
@ -6065,7 +6065,7 @@ abort prematurely.</p>
<H4><a name="Ruby_newfree_typemap"></a>32.7.6.9 "newfree" typemap</H4>
<H4><a name="Ruby_newfree_typemap"></a>33.7.6.9 "newfree" typemap</H4>
<p> The "newfree" typemap is used in conjunction with the <tt>%newobject</tt>
@ -6089,14 +6089,14 @@ a function. For example:</p>
<p> See <a href="http://www.swig.org/Doc1.3/SWIGDocumentation.html#ownership">Object
<p> See <a href="Customization.html#Customization_ownership">Object
ownership and %newobject</a> for further details.</p>
<H4><a name="Ruby_memberin_typemap"></a>32.7.6.10 "memberin" typemap</H4>
<H4><a name="Ruby_memberin_typemap"></a>33.7.6.10 "memberin" typemap</H4>
<p> The "memberin" typemap is used to copy data from<em> an
@ -6129,7 +6129,7 @@ other objects.</p>
<H4><a name="Ruby_varin_typemap"></a>32.7.6.11 "varin" typemap</H4>
<H4><a name="Ruby_varin_typemap"></a>33.7.6.11 "varin" typemap</H4>
<p> The "varin" typemap is used to convert objects in the target
@ -6140,7 +6140,7 @@ This is implementation specific.</p>
<H4><a name="Ruby_varout_typemap_"></a>32.7.6.12 "varout" typemap</H4>
<H4><a name="Ruby_varout_typemap_"></a>33.7.6.12 "varout" typemap</H4>
<p> The "varout" typemap is used to convert a C/C++ object to an
@ -6151,7 +6151,7 @@ This is implementation specific.</p>
<H4><a name="Ruby_throws_typemap"></a>32.7.6.13 "throws" typemap</H4>
<H4><a name="Ruby_throws_typemap"></a>33.7.6.13 "throws" typemap</H4>
<p> The "throws" typemap is only used when SWIG parses a C++
@ -6210,7 +6210,7 @@ handling with %exception</a> section.</p>
<H4><a name="Ruby_directorin_typemap"></a>32.7.6.14 directorin typemap</H4>
<H4><a name="Ruby_directorin_typemap"></a>33.7.6.14 directorin typemap</H4>
<p>Converts C++ objects in director
@ -6464,7 +6464,7 @@ referring to the class itself.</td>
<H4><a name="Ruby_directorout_typemap"></a>32.7.6.15 directorout typemap</H4>
<H4><a name="Ruby_directorout_typemap"></a>33.7.6.15 directorout typemap</H4>
<p>Converts Ruby objects in director
@ -6724,7 +6724,7 @@ exception.<br>
<H4><a name="Ruby_directorargout_typemap"></a>32.7.6.16 directorargout typemap</H4>
<H4><a name="Ruby_directorargout_typemap"></a>33.7.6.16 directorargout typemap</H4>
<p>Output argument processing in director
@ -6964,7 +6964,7 @@ referring to the instance of the class itself</td>
<H4><a name="Ruby_ret_typemap"></a>32.7.6.17 ret typemap</H4>
<H4><a name="Ruby_ret_typemap"></a>33.7.6.17 ret typemap</H4>
<p>Cleanup of function return values
@ -6974,7 +6974,7 @@ referring to the instance of the class itself</td>
<H4><a name="Ruby_globalin_typemap"></a>32.7.6.18 globalin typemap</H4>
<H4><a name="Ruby_globalin_typemap"></a>33.7.6.18 globalin typemap</H4>
<p>Setting of C global variables
@ -6984,7 +6984,7 @@ referring to the instance of the class itself</td>
<H3><a name="Ruby_nn40"></a>32.7.7 Typemap variables</H3>
<H3><a name="Ruby_nn40"></a>33.7.7 Typemap variables</H3>
<p>
@ -7094,13 +7094,13 @@ being created. </div>
<H3><a name="Ruby_nn41"></a>32.7.8 Useful Functions</H3>
<H3><a name="Ruby_nn41"></a>33.7.8 Useful Functions</H3>
<p> When you write a typemap, you usually have to work directly
with Ruby objects. The following functions may prove to be useful.
(These functions plus many more can be found in <a href="http://www.rubycentral.com/book"><em>Programming
Ruby</em></a>, by David Thomas and Andrew Hunt.)&nbsp;</p>
(These functions plus many more can be found in <em>Programming
Ruby</em> book, by David Thomas and Andrew Hunt.)&nbsp;</p>
<p>In addition, we list equivalent functions that SWIG defines, which
provide a language neutral conversion (these functions are defined for
each swig language supported). &nbsp;If you are trying to create a swig
@ -7118,7 +7118,7 @@ across multiple languages.</p>
<H4><a name="Ruby_nn42"></a>32.7.8.1 C Datatypes to Ruby Objects</H4>
<H4><a name="Ruby_nn42"></a>33.7.8.1 C Datatypes to Ruby Objects</H4>
<div class="diagram">
@ -7174,7 +7174,7 @@ SWIG_From_float(float)</td>
<H4><a name="Ruby_nn43"></a>32.7.8.2 Ruby Objects to C Datatypes</H4>
<H4><a name="Ruby_nn43"></a>33.7.8.2 Ruby Objects to C Datatypes</H4>
<p>Here, while the Ruby versions return the value directly, the SWIG
@ -7263,7 +7263,7 @@ Ruby_Format_TypeError( "$1_name", "$1_type","$symname", $argnum, $input
<H4><a name="Ruby_nn44"></a>32.7.8.3 Macros for VALUE</H4>
<H4><a name="Ruby_nn44"></a>33.7.8.3 Macros for VALUE</H4>
<p> <tt>RSTRING_LEN(str)</tt> </p>
@ -7326,7 +7326,7 @@ Ruby_Format_TypeError( "$1_name", "$1_type","$symname", $argnum, $input
<H4><a name="Ruby_nn45"></a>32.7.8.4 Exceptions</H4>
<H4><a name="Ruby_nn45"></a>33.7.8.4 Exceptions</H4>
<p> <tt>void rb_raise(VALUE exception, const char *fmt,
@ -7493,7 +7493,7 @@ arguments are interpreted as with <tt>printf()</tt>. </div>
<H4><a name="Ruby_nn46"></a>32.7.8.5 Iterators</H4>
<H4><a name="Ruby_nn46"></a>33.7.8.5 Iterators</H4>
<p> <tt>void rb_iter_break()</tt> </p>
@ -7595,7 +7595,7 @@ VALUE), VALUE value)</tt></p>
<H3><a name="Ruby_nn47"></a>32.7.9 Typemap Examples</H3>
<H3><a name="Ruby_nn47"></a>33.7.9 Typemap Examples</H3>
<p> This section includes a few examples of typemaps. For more
@ -7606,7 +7606,7 @@ directory. </p>
<H3><a name="Ruby_nn48"></a>32.7.10 Converting a Ruby array to a char **</H3>
<H3><a name="Ruby_nn48"></a>33.7.10 Converting a Ruby array to a char **</H3>
<p> A common problem in many C programs is the processing of
@ -7661,7 +7661,7 @@ after the execution of the C function. </p>
<H3><a name="Ruby_nn49"></a>32.7.11 Collecting arguments in a hash</H3>
<H3><a name="Ruby_nn49"></a>33.7.11 Collecting arguments in a hash</H3>
<p> Ruby's solution to the "keyword arguments" capability of some
@ -7940,7 +7940,7 @@ directory of the SWIG distribution. </p>
<H3><a name="Ruby_nn50"></a>32.7.12 Pointer handling</H3>
<H3><a name="Ruby_nn50"></a>33.7.12 Pointer handling</H3>
<p> Occasionally, it might be necessary to convert pointer values
@ -8039,7 +8039,7 @@ For example: </p>
<H4><a name="Ruby_nn51"></a>32.7.12.1 Ruby Datatype Wrapping</H4>
<H4><a name="Ruby_nn51"></a>33.7.12.1 Ruby Datatype Wrapping</H4>
<p> <tt>VALUE Data_Wrap_Struct(VALUE class, void
@ -8090,7 +8090,7 @@ and assigns that pointer to <i>ptr</i>. </div>
<H3><a name="Ruby_nn52"></a>32.7.13 Example: STL Vector to Ruby Array</H3>
<H3><a name="Ruby_nn52"></a>33.7.13 Example: STL Vector to Ruby Array</H3>
<p>Another use for macros and type maps is to create a Ruby array
@ -8199,7 +8199,7 @@ the<a href="#Ruby_nn23_1"> C++ Standard Template Library</a>.<br>
<H2><a name="Ruby_nn65"></a>32.8 Docstring Features</H2>
<H2><a name="Ruby_nn65"></a>33.8 Docstring Features</H2>
<p>
@ -8260,7 +8260,7 @@ generate ri documentation from a c wrap file, you could do:</p>
<H3><a name="Ruby_nn66"></a>32.8.1 Module docstring</H3>
<H3><a name="Ruby_nn66"></a>33.8.1 Module docstring</H3>
<p>
@ -8311,7 +8311,7 @@ macro. For example:
<H3><a name="Ruby_nn67"></a>32.8.2 %feature("autodoc")</H3>
<H3><a name="Ruby_nn67"></a>33.8.2 %feature("autodoc")</H3>
<p>Since SWIG does know everything about the function it wraps,
@ -8340,7 +8340,7 @@ feature, described below.
<H4><a name="Ruby_nn68"></a>32.8.2.1 %feature("autodoc", "0")</H4>
<H4><a name="Ruby_nn68"></a>33.8.2.1 %feature("autodoc", "0")</H4>
<p>
@ -8388,7 +8388,7 @@ Then Ruby code like this will be generated:
<H4><a name="Ruby_autodoc1"></a>32.8.2.2 %feature("autodoc", "1")</H4>
<H4><a name="Ruby_autodoc1"></a>33.8.2.2 %feature("autodoc", "1")</H4>
<p>
@ -8420,7 +8420,7 @@ this:
<H4><a name="Ruby_autodoc2"></a>32.8.2.3 %feature("autodoc", "2")</H4>
<H4><a name="Ruby_autodoc2"></a>33.8.2.3 %feature("autodoc", "2")</H4>
<p>
@ -8436,7 +8436,7 @@ this:
<H4><a name="Ruby_feature_autodoc3"></a>32.8.2.4 %feature("autodoc", "3")</H4>
<H4><a name="Ruby_feature_autodoc3"></a>33.8.2.4 %feature("autodoc", "3")</H4>
<p>
@ -8464,7 +8464,7 @@ this:
<H4><a name="Ruby_nn70"></a>32.8.2.5 %feature("autodoc", "docstring")</H4>
<H4><a name="Ruby_nn70"></a>33.8.2.5 %feature("autodoc", "docstring")</H4>
<p>
@ -8492,7 +8492,7 @@ generated string. For example:
<H3><a name="Ruby_nn71"></a>32.8.3 %feature("docstring")</H3>
<H3><a name="Ruby_nn71"></a>33.8.3 %feature("docstring")</H3>
<p>
@ -8507,10 +8507,10 @@ docstring and they are output together. </p>
<H2><a name="Ruby_nn53"></a>32.9 Advanced Topics</H2>
<H2><a name="Ruby_nn53"></a>33.9 Advanced Topics</H2>
<H3><a name="Ruby_nn54"></a>32.9.1 Operator overloading</H3>
<H3><a name="Ruby_operator_overloading"></a>33.9.1 Operator overloading</H3>
<p> SWIG allows operator overloading with, by using the <tt>%extend</tt>
@ -9527,10 +9527,10 @@ parses the expression <i>a != b</i> as <i>!(a == b)</i>.
<H3><a name="Ruby_nn55"></a>32.9.2 Creating Multi-Module Packages</H3>
<H3><a name="Ruby_nn55"></a>33.9.2 Creating Multi-Module Packages</H3>
<p> The chapter on <a href="Modules.html">Working
<p> The chapter on <a href="Modules.html#Modules">Working
with Modules</a> discusses the basics of creating multi-module
extensions with SWIG, and in particular the considerations for sharing
runtime type information among the different modules. </p>
@ -9708,7 +9708,7 @@ initialized: </p>
<H3><a name="Ruby_nn56"></a>32.9.3 Specifying Mixin Modules</H3>
<H3><a name="Ruby_nn56"></a>33.9.3 Specifying Mixin Modules</H3>
<p> The Ruby language doesn't support multiple inheritance, but
@ -9806,7 +9806,7 @@ Features"</a>) for more details). </p>
<H2><a name="Ruby_nn57"></a>32.10 Memory Management</H2>
<H2><a name="Ruby_nn57"></a>33.10 Memory Management</H2>
<p>One of the most common issues in generating SWIG bindings for
@ -9853,7 +9853,7 @@ understanding of how the underlying library manages memory.</p>
<H3><a name="Ruby_nn58"></a>32.10.1 Mark and Sweep Garbage Collector </H3>
<H3><a name="Ruby_nn58"></a>33.10.1 Mark and Sweep Garbage Collector </H3>
<p>Ruby uses a mark and sweep garbage collector. When the garbage
@ -9901,7 +9901,7 @@ this memory. </p>
<H3><a name="Ruby_nn59"></a>32.10.2 Object Ownership</H3>
<H3><a name="Ruby_nn59"></a>33.10.2 Object Ownership</H3>
<p>As described above, memory management depends on clearly
@ -10050,7 +10050,7 @@ above. For example:</p>
<p>In this case, the default SWIG behavior for calling member
functions is incorrect. The Ruby object should assume ownership of the
returned object. This can be done by using the %newobject directive.
See <a href="file:///d:/msys/1.0/src/SWIG/Doc/Manual/Customization.html#ownership">
See <a href="Customization.html#Customization_ownership">
Object ownership and %newobject</a> for more information. </p>
@ -10128,7 +10128,7 @@ classes is:</p>
<H3><a name="Ruby_nn60"></a>32.10.3 Object Tracking</H3>
<H3><a name="Ruby_nn60"></a>33.10.3 Object Tracking</H3>
<p>The remaining parts of this section will use the class library
@ -10204,7 +10204,7 @@ the same underlying C++ object. This can cause problems. For example:<br>
<p>After the the garbage collector runs, as a result of our call
<p>After the garbage collector runs, as a result of our call
to <tt>GC.start</tt>, calling<tt>tiger2.get_name()</tt>
causes a segmentation fault. The problem is that when <tt>tiger1</tt>
is garbage collected, it frees the underlying C++ object. Thus, when <tt>tiger2</tt>
@ -10342,7 +10342,7 @@ methods.</p>
<H3><a name="Ruby_nn61"></a>32.10.4 Mark Functions</H3>
<H3><a name="Ruby_nn61"></a>33.10.4 Mark Functions</H3>
<p>With a bit more testing, we see that our class library still
@ -10460,7 +10460,7 @@ test suite.</p>
<H3><a name="Ruby_nn62"></a>32.10.5 Free Functions</H3>
<H3><a name="Ruby_nn62"></a>33.10.5 Free Functions</H3>
<p>By default, SWIG creates a "free" function that is called when
@ -10615,7 +10615,7 @@ been freed, and thus raises a runtime exception.</p>
<H3><a name="Ruby_nn63"></a>32.10.6 Embedded Ruby and the C++ Stack</H3>
<H3><a name="Ruby_nn63"></a>33.10.6 Embedded Ruby and the C++ Stack</H3>
<p>As has been said, the Ruby GC runs and marks objects before
@ -10649,7 +10649,7 @@ initialization a normal Ruby interpreter will call the ruby_init()
function which in turn will call a function called Init_stack or
similar. &nbsp;This function will store a pointer to the location
where
the stack points at at that point in time.</p>
the stack points at that point in time.</p>

20
Doc/Manual/SWIG.html
View file

@ -13,7 +13,7 @@
<li><a href="#SWIG_nn2">Running SWIG</a>
<ul>
<li><a href="#SWIG_nn3">Input format</a>
<li><a href="#output">SWIG Output</a>
<li><a href="#SWIG_output">SWIG Output</a>
<li><a href="#SWIG_nn5">Comments</a>
<li><a href="#SWIG_nn6">C Preprocessor</a>
<li><a href="#SWIG_nn7">SWIG Directives</a>
@ -92,7 +92,7 @@ chapters.
<p>
To run SWIG, use the <tt>swig</tt> command with options options and a filename like this:
To run SWIG, use the <tt>swig</tt> command with options and a filename like this:
</p>
<div class="shell"><pre>
@ -113,6 +113,7 @@ can be obtained by typing <tt>swig -help</tt> or <tt>swig
-clisp Generate CLISP wrappers
-cffi Generate CFFI wrappers
-csharp Generate C# wrappers
-go Generate Go wrappers
-guile Generate Guile wrappers
-java Generate Java wrappers
-lua Generate Lua wrappers
@ -193,7 +194,7 @@ semantics in SWIG is analogous to that of the declarations section
used in input files to parser generation tools such as yacc or bison.
</p>
<H3><a name="output"></a>5.1.2 SWIG Output</H3>
<H3><a name="SWIG_output"></a>5.1.2 SWIG Output</H3>
<p>
@ -1618,7 +1619,7 @@ double y; // Read-write
<p>
The <tt>%mutable</tt> and <tt>%immutable</tt> directives are actually
<a href="Customization.html#features">%feature directives</a> defined like this:
<a href="Customization.html#Customization_features">%feature directives</a> defined like this:
</p>
<div class="code"><pre>
@ -1672,7 +1673,7 @@ directive as shown :</p>
// interface.i
%rename(my_print) print;
extern void print(char *);
extern void print(const char *);
%rename(foo) a_really_long_and_annoying_name;
extern int a_really_long_and_annoying_name;
@ -1725,9 +1726,10 @@ to ignore declarations that match a given identifier. For example:
<div class="code">
<pre>
%ignore print; // Ignore all declarations named print
%ignore _HAVE_FOO_H; // Ignore an include guard constant
%ignore MYMACRO; // Ignore a macro
...
%include "foo.h" // Grab a header file
#define MYMACRO 123
void print(const char *);
...
</pre>
</div>
@ -1742,7 +1744,7 @@ declarations. If you need to remove a whole section of problematic code, the SW
<p>
More powerful 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#ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> section in the C++ chapter.
<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> section in the C++ chapter.
</p>
<p>
@ -1752,7 +1754,7 @@ For example:
<div class="code">
<pre>
%name(output) extern void print(char *);
%name(output) extern void print(const char *);
</pre>
</div>

108
Doc/Manual/SWIGPlus.html
View file

@ -42,18 +42,21 @@
<ul>
<li><a href="#SWIGPlus_nn24">Dispatch function generation</a>
<li><a href="#SWIGPlus_nn25">Ambiguity in Overloading</a>
<li><a href="#ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
<li><a href="#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
<li><a href="#SWIGPlus_nn27">Comments on overloading</a>
</ul>
<li><a href="#SWIGPlus_nn28">Wrapping overloaded operators</a>
<li><a href="#SWIGPlus_class_extension">Class extension</a>
<li><a href="#SWIGPlus_nn30">Templates</a>
<li><a href="#SWIGPlus_nn31">Namespaces</a>
<li><a href="#SWIGPlus_namespaces">Namespaces</a>
<ul>
<li><a href="#SWIGPlus_nspace">The nspace feature for namespaces</a>
</ul>
<li><a href="#SWIGPlus_renaming_templated_types_namespaces">Renaming templated types in namespaces</a>
<li><a href="#SWIGPlus_exception_specifications">Exception specifications</a>
<li><a href="#SWIGPlus_catches">Exception handling with %catches</a>
<li><a href="#SWIGPlus_nn33">Pointers to Members</a>
<li><a href="#SWIGPlus_nn34">Smart pointers and operator-&gt;()</a>
<li><a href="#SWIGPlus_smart_pointers">Smart pointers and operator-&gt;()</a>
<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>
@ -1125,7 +1128,7 @@ For example if a method has ten default arguments, then eleven wrapper methods a
<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="#ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> section
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
@ -2124,7 +2127,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="ambiguity_resolution_renaming"></a>6.15.3 Ambiguity resolution and renaming</H3>
<H3><a name="SWIGPlus_ambiguity_resolution_renaming"></a>6.15.3 Ambiguity resolution and renaming</H3>
<p>
@ -3647,12 +3650,16 @@ as the class name. For example:
Similar changes apply to typemaps and other customization features.
</p>
<H2><a name="SWIGPlus_nn31"></a>6.19 Namespaces</H2>
<H2><a name="SWIGPlus_namespaces"></a>6.19 Namespaces</H2>
<p>
Support for C++ namespaces is a relatively late addition to SWIG,
first appearing in SWIG-1.3.12. Before describing the implementation,
Support for C++ namespaces is comprehensive, but by default simple, however,
some target languages can turn on more advanced namespace support via the
<a href="#SWIGPlus_nspace">nspace feature</a>, described later.
Code within unnamed namespaces is ignored as there is no external
access to symbols declared within the unnamed namespace.
Before detailing the default implementation for named namespaces,
it is worth noting that the semantics of C++ namespaces is extremely
non-trivial--especially with regard to the C++ type system and class
machinery. At a most basic level, namespaces are sometimes used to
@ -4092,6 +4099,87 @@ with any namespace awareness. In the future, language modules may or may not p
more advanced namespace support.
</p>
<H3><a name="SWIGPlus_nspace"></a>6.19.1 The nspace feature for namespaces</H3>
<p>
Some target languages provide support for the <tt>nspace</tt> <a href="Customization.html#Customization_features">feature</a>.
The feature can be applied to any class, struct, union or enum declared within a named namespace.
The feature wraps the type within the target language specific concept of a namespace,
for example, a Java package or C# namespace.
Please see the language specific sections to see if the target language you are interested in supports the nspace feature.
</p>
<p>
The feature is demonstrated below for C# using the following example:
</p>
<div class="code">
<pre>
%feature("nspace") MyWorld::Material::Color;
%nspace MyWorld::Wrapping::Color; // %nspace is a macro for %feature("nspace")
namespace MyWorld {
namespace Material {
class Color {
...
};
}
namespace Wrapping {
class Color {
...
};
}
}
</pre>
</div>
<p>
Without the <tt>nspace</tt> feature directives above or <tt>%rename</tt>, you would get the following warning resulting in just one of the <tt>Color</tt> classes being available for use from the target language:
</p>
<div class="shell">
<pre>
example.i:9: Error: 'Color' is multiply defined in the generated target language module.
example.i:5: Error: Previous declaration of 'Color'
</pre>
</div>
<p>
With the <tt>nspace</tt> feature the two <tt>Color</tt> classes are wrapped into the equivalent C# namespaces.
A fully qualified constructor call of each these two types in C# is then:
</p>
<div class="targetlang">
<pre>
MyWorld.Material.Color materialColor = new MyWorld.Material.Color();
MyWorld.Wrapping.Color wrappingColor = new MyWorld.Wrapping.Color();
</pre>
</div>
<p>
Note that the <tt>nspace</tt> feature does not apply to variables and functions simply declared in a namespace. For example, the following symbols cannot co-exist in the target language without renaming. This may change in a future version.
</p>
<div class="code">
<pre>
namespace MyWorld {
namespace Material {
int quantity;
void dispatch();
}
namespace Wrapping {
int quantity;
void dispatch();
}
}
</pre>
</div>
<p>
<b>Compatibility Note:</b> The nspace feature was first introduced in SWIG-2.0.0.
</p>
<H2><a name="SWIGPlus_renaming_templated_types_namespaces"></a>6.20 Renaming templated types in namespaces</H2>
@ -4216,7 +4304,7 @@ is outlined in the <a href="Typemaps.html#throws_typemap">"throws" typemap</a> s
<p>
Since exception specifications are sometimes only used sparingly, this alone may not be enough to
properly handle C++ exceptions. To do that, a different set of special SWIG directives are used.
Consult the "<a href="Customization.html#exception">Exception handling with %exception</a>" section for details.
Consult the "<a href="Customization.html#Customization_exception">Exception handling with %exception</a>" section for details.
The next section details a way of simulating an exception specification or replacing an existing one.
</p>
@ -4320,7 +4408,7 @@ when checking types. However, no such support is currently provided
for member pointers.
</p>
<H2><a name="SWIGPlus_nn34"></a>6.24 Smart pointers and operator-&gt;()</H2>
<H2><a name="SWIGPlus_smart_pointers"></a>6.24 Smart pointers and operator-&gt;()</H2>
<p>

36
Doc/Manual/Sections.html
View file

@ -1,23 +1,15 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>SWIG-1.3 Documentation</title>
<title>SWIG-2.0 Documentation</title>
</head>
<body bgcolor="#ffffff">
<H1><a name="Sections"></a>SWIG-1.3 Development Documentation</H1>
<H1><a name="Sections"></a>SWIG-2.0 Documentation</H1>
Last update : SWIG-2.0.0 (in progress)
Last update : SWIG-2.0.1 (in progress)
<H2>Sections</H2>
<p>
The SWIG documentation is being updated to reflect new SWIG
features and enhancements. However, this update process is not quite
finished--there is a lot of old SWIG-1.1 documentation and it is taking
some time to update all of it. Please pardon our dust (or volunteer
to help!).
</p>
<H3>SWIG Core Documentation</H3>
<ul>
<li><a href="Preface.html#Preface">Preface</a></li>
@ -41,13 +33,14 @@ to help!).
<H3>Language Module Documentation</H3>
<ul>
<li><a href="Allegrocl.html#Allegrocl_nn1">Allegro CL support</a></li>
<li><a href="Allegrocl.html#Allegrocl">Allegro CL 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="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="Lua.html#Lua_nn1">Lua support</a></li>
<li><a href="Lisp.html#Lisp_nn1">Common Lisp support</a></li>
<li><a href="Lua.html#Lua">Lua support</a></li>
<li><a href="Lisp.html#Lisp">Common Lisp support</a></li>
<li><a href="Modula3.html#Modula3">Modula3 support</a></li>
<li><a href="Mzscheme.html#MzScheme">MzScheme support</a></li>
<li><a href="Ocaml.html#Ocaml">Ocaml support</a></li>
@ -67,20 +60,5 @@ to help!).
<li><a href="Extending.html#Extending">Extending SWIG</a></li>
</ul>
<H3>Documentation that has not yet been updated</H3>
<p>
This documentation has not been completely updated from SWIG-1.1, but most of the topics
still apply to the current release. Make sure you read the
<a href="SWIG.html#SWIG">SWIG Basics</a> chapter before reading
any of these chapters. Also, SWIG-1.3.10 features extensive changes to the
implementation of typemaps. Make sure you read the <a href="Typemaps.html#Typemaps">Typemaps</a>
chapter above if you are using this feature.
</p>
<ul>
<li><a href="Advanced.html#Advanced">Advanced topics</a> (see <a href="Modules.html#Modules">Modules</a> for updated information).</li>
</ul>
</body>
</html>

92
Doc/Manual/Tcl.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Tcl"></a>33 SWIG and Tcl</H1>
<H1><a name="Tcl"></a>34 SWIG and Tcl</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -83,7 +83,7 @@ Tcl 8.0 or a later release. Earlier releases of SWIG supported Tcl 7.x, but
this is no longer supported.
</p>
<H2><a name="Tcl_nn2"></a>33.1 Preliminaries</H2>
<H2><a name="Tcl_nn2"></a>34.1 Preliminaries</H2>
<p>
@ -109,7 +109,7 @@ build a Tcl extension module. To finish building the module, you
need to compile this file and link it with the rest of your program.
</p>
<H3><a name="Tcl_nn3"></a>33.1.1 Getting the right header files</H3>
<H3><a name="Tcl_nn3"></a>34.1.1 Getting the right header files</H3>
<p>
@ -127,7 +127,7 @@ this is the case, you should probably make a symbolic link so that <tt>tcl.h</tt
header file.
</p>
<H3><a name="Tcl_nn4"></a>33.1.2 Compiling a dynamic module</H3>
<H3><a name="Tcl_nn4"></a>34.1.2 Compiling a dynamic module</H3>
<p>
@ -162,7 +162,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"></a>33.1.3 Static linking</H3>
<H3><a name="Tcl_nn5"></a>34.1.3 Static linking</H3>
<p>
@ -228,7 +228,7 @@ minimal in most situations (and quite frankly not worth the extra
hassle in the opinion of this author).
</p>
<H3><a name="Tcl_nn6"></a>33.1.4 Using your module</H3>
<H3><a name="Tcl_nn6"></a>34.1.4 Using your module</H3>
<p>
@ -356,7 +356,7 @@ to the default system configuration (this requires root access and you will need
the man pages).
</p>
<H3><a name="Tcl_nn7"></a>33.1.5 Compilation of C++ extensions</H3>
<H3><a name="Tcl_nn7"></a>34.1.5 Compilation of C++ extensions</H3>
<p>
@ -439,7 +439,7 @@ erratic program behavior. If working with lots of software components, you
might want to investigate using a more formal standard such as COM.
</p>
<H3><a name="Tcl_nn8"></a>33.1.6 Compiling for 64-bit platforms</H3>
<H3><a name="Tcl_nn8"></a>34.1.6 Compiling for 64-bit platforms</H3>
<p>
@ -466,7 +466,7 @@ also introduce problems on platforms that support more than one
linking standard (e.g., -o32 and -n32 on Irix).
</p>
<H3><a name="Tcl_nn9"></a>33.1.7 Setting a package prefix</H3>
<H3><a name="Tcl_nn9"></a>34.1.7 Setting a package prefix</H3>
<p>
@ -485,7 +485,7 @@ option will append the prefix to the name when creating a command and
call it "<tt>Foo_bar</tt>".
</p>
<H3><a name="Tcl_nn10"></a>33.1.8 Using namespaces</H3>
<H3><a name="Tcl_nn10"></a>34.1.8 Using namespaces</H3>
<p>
@ -507,7 +507,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"></a>33.2 Building Tcl/Tk Extensions under Windows 95/NT</H2>
<H2><a name="Tcl_nn11"></a>34.2 Building Tcl/Tk Extensions under Windows 95/NT</H2>
<p>
@ -518,7 +518,7 @@ covers the process of using SWIG with Microsoft Visual C++.
although the procedure may be similar with other compilers.
</p>
<H3><a name="Tcl_nn12"></a>33.2.1 Running SWIG from Developer Studio</H3>
<H3><a name="Tcl_nn12"></a>34.2.1 Running SWIG from Developer Studio</H3>
<p>
@ -576,7 +576,7 @@ MSDOS &gt; tclsh80
%
</pre></div>
<H3><a name="Tcl_nn13"></a>33.2.2 Using NMAKE</H3>
<H3><a name="Tcl_nn13"></a>34.2.2 Using NMAKE</H3>
<p>
@ -639,7 +639,7 @@ to get you started. With a little practice, you'll be making lots of
Tcl extensions.
</p>
<H2><a name="Tcl_nn14"></a>33.3 A tour of basic C/C++ wrapping</H2>
<H2><a name="Tcl_nn14"></a>34.3 A tour of basic C/C++ wrapping</H2>
<p>
@ -650,7 +650,7 @@ classes. This section briefly covers the essential aspects of this
wrapping.
</p>
<H3><a name="Tcl_nn15"></a>33.3.1 Modules</H3>
<H3><a name="Tcl_nn15"></a>34.3.1 Modules</H3>
<p>
@ -684,7 +684,7 @@ To fix this, supply an extra argument to <tt>load</tt> like this:
</pre>
</div>
<H3><a name="Tcl_nn16"></a>33.3.2 Functions</H3>
<H3><a name="Tcl_nn16"></a>34.3.2 Functions</H3>
<p>
@ -709,7 +709,7 @@ like you think it does:
%
</pre></div>
<H3><a name="Tcl_nn17"></a>33.3.3 Global variables</H3>
<H3><a name="Tcl_nn17"></a>34.3.3 Global variables</H3>
<p>
@ -789,7 +789,7 @@ extern char *path; // Read-only (due to %immutable)
</pre>
</div>
<H3><a name="Tcl_nn18"></a>33.3.4 Constants and enums</H3>
<H3><a name="Tcl_nn18"></a>34.3.4 Constants and enums</H3>
<p>
@ -873,7 +873,7 @@ When an identifier name is given, it is used to perform an implicit hash-table l
conversion. This allows the <tt>global</tt> statement to be omitted.
</p>
<H3><a name="Tcl_nn19"></a>33.3.5 Pointers</H3>
<H3><a name="Tcl_nn19"></a>34.3.5 Pointers</H3>
<p>
@ -969,7 +969,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return
<tt>None</tt> if the conversion can't be performed.
</p>
<H3><a name="Tcl_nn20"></a>33.3.6 Structures</H3>
<H3><a name="Tcl_nn20"></a>34.3.6 Structures</H3>
<p>
@ -1251,7 +1251,7 @@ Note: Tcl only destroys the underlying object if it has ownership. See the
memory management section that appears shortly.
</p>
<H3><a name="Tcl_nn21"></a>33.3.7 C++ classes</H3>
<H3><a name="Tcl_nn21"></a>34.3.7 C++ classes</H3>
<p>
@ -1318,7 +1318,7 @@ In Tcl, the static member is accessed as follows:
</pre>
</div>
<H3><a name="Tcl_nn22"></a>33.3.8 C++ inheritance</H3>
<H3><a name="Tcl_nn22"></a>34.3.8 C++ inheritance</H3>
<p>
@ -1367,7 +1367,7 @@ For instance:
It is safe to use multiple inheritance with SWIG.
</p>
<H3><a name="Tcl_nn23"></a>33.3.9 Pointers, references, values, and arrays</H3>
<H3><a name="Tcl_nn23"></a>34.3.9 Pointers, references, values, and arrays</H3>
<p>
@ -1421,7 +1421,7 @@ to hold the result and a pointer is returned (Tcl will release this memory
when the return value is garbage collected).
</p>
<H3><a name="Tcl_nn24"></a>33.3.10 C++ overloaded functions</H3>
<H3><a name="Tcl_nn24"></a>34.3.10 C++ overloaded functions</H3>
<p>
@ -1544,7 +1544,7 @@ first declaration takes precedence.
Please refer to the "SWIG and C++" chapter for more information about overloading.
</p>
<H3><a name="Tcl_nn25"></a>33.3.11 C++ operators</H3>
<H3><a name="Tcl_nn25"></a>34.3.11 C++ operators</H3>
<p>
@ -1646,7 +1646,7 @@ There are ways to make this operator appear as part of the class using the <tt>%
Keep reading.
</p>
<H3><a name="Tcl_nn26"></a>33.3.12 C++ namespaces</H3>
<H3><a name="Tcl_nn26"></a>34.3.12 C++ namespaces</H3>
<p>
@ -1710,7 +1710,7 @@ utilizes thousands of small deeply nested namespaces each with
identical symbol names, well, then you get what you deserve.
</p>
<H3><a name="Tcl_nn27"></a>33.3.13 C++ templates</H3>
<H3><a name="Tcl_nn27"></a>34.3.13 C++ templates</H3>
<p>
@ -1762,7 +1762,7 @@ More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</
examples will appear later.
</p>
<H3><a name="Tcl_nn28"></a>33.3.14 C++ Smart Pointers</H3>
<H3><a name="Tcl_nn28"></a>34.3.14 C++ Smart Pointers</H3>
<p>
@ -1846,7 +1846,7 @@ simply use the <tt>__deref__()</tt> method. For example:
</pre>
</div>
<H2><a name="Tcl_nn29"></a>33.4 Further details on the Tcl class interface</H2>
<H2><a name="Tcl_nn29"></a>34.4 Further details on the Tcl class interface</H2>
<p>
@ -1859,7 +1859,7 @@ of low-level details were omitted. This section provides a brief overview
of how the proxy classes work.
</p>
<H3><a name="Tcl_nn30"></a>33.4.1 Proxy classes</H3>
<H3><a name="Tcl_nn30"></a>34.4.1 Proxy classes</H3>
<p>
@ -1924,7 +1924,7 @@ function. This allows objects to be encapsulated objects that look a lot like
as shown in the last section.
</p>
<H3><a name="Tcl_nn31"></a>33.4.2 Memory management</H3>
<H3><a name="Tcl_nn31"></a>34.4.2 Memory management</H3>
<p>
@ -2112,7 +2112,7 @@ typemaps--an advanced topic discussed later.
</p>
<H2><a name="Tcl_nn32"></a>33.5 Input and output parameters</H2>
<H2><a name="Tcl_nn32"></a>34.5 Input and output parameters</H2>
<p>
@ -2300,7 +2300,7 @@ set c [lindex $dim 1]
</pre>
</div>
<H2><a name="Tcl_nn33"></a>33.6 Exception handling </H2>
<H2><a name="Tcl_nn33"></a>34.6 Exception handling </H2>
<p>
@ -2434,7 +2434,7 @@ Since SWIG's exception handling is user-definable, you are not limited to C++ ex
See the chapter on "<a href="Customization.html#Customization">Customization Features</a>" for more examples.
</p>
<H2><a name="Tcl_nn34"></a>33.7 Typemaps</H2>
<H2><a name="Tcl_nn34"></a>34.7 Typemaps</H2>
<p>
@ -2451,7 +2451,7 @@ Typemaps are only used if you want to change some aspect of the primitive
C-Tcl interface.
</p>
<H3><a name="Tcl_nn35"></a>33.7.1 What is a typemap?</H3>
<H3><a name="Tcl_nn35"></a>34.7.1 What is a typemap?</H3>
<p>
@ -2568,7 +2568,7 @@ parameter is omitted):
</pre>
</div>
<H3><a name="Tcl_nn36"></a>33.7.2 Tcl typemaps</H3>
<H3><a name="Tcl_nn36"></a>34.7.2 Tcl typemaps</H3>
<p>
@ -2706,7 +2706,7 @@ Initialize an argument to a value before any conversions occur.
Examples of these methods will appear shortly.
</p>
<H3><a name="Tcl_nn37"></a>33.7.3 Typemap variables</H3>
<H3><a name="Tcl_nn37"></a>34.7.3 Typemap variables</H3>
<p>
@ -2777,7 +2777,7 @@ properly assigned.
The Tcl name of the wrapper function being created.
</div>
<H3><a name="Tcl_nn38"></a>33.7.4 Converting a Tcl list to a char ** </H3>
<H3><a name="Tcl_nn38"></a>34.7.4 Converting a Tcl list to a char ** </H3>
<p>
@ -2839,7 +2839,7 @@ argv[2] = Larry
3
</pre></div>
<H3><a name="Tcl_nn39"></a>33.7.5 Returning values in arguments</H3>
<H3><a name="Tcl_nn39"></a>34.7.5 Returning values in arguments</H3>
<p>
@ -2881,7 +2881,7 @@ result, a Tcl function using these typemaps will work like this :
%
</pre></div>
<H3><a name="Tcl_nn40"></a>33.7.6 Useful functions</H3>
<H3><a name="Tcl_nn40"></a>34.7.6 Useful functions</H3>
<p>
@ -2958,7 +2958,7 @@ int Tcl_IsShared(Tcl_Obj *obj);
</pre>
</div>
<H3><a name="Tcl_nn41"></a>33.7.7 Standard typemaps</H3>
<H3><a name="Tcl_nn41"></a>34.7.7 Standard typemaps</H3>
<p>
@ -3042,7 +3042,7 @@ work)
</pre>
</div>
<H3><a name="Tcl_nn42"></a>33.7.8 Pointer handling</H3>
<H3><a name="Tcl_nn42"></a>34.7.8 Pointer handling</H3>
<p>
@ -3118,7 +3118,7 @@ For example:
</pre>
</div>
<H2><a name="Tcl_nn43"></a>33.8 Turning a SWIG module into a Tcl Package.</H2>
<H2><a name="Tcl_nn43"></a>34.8 Turning a SWIG module into a Tcl Package.</H2>
<p>
@ -3190,7 +3190,7 @@ As a final note, most SWIG examples do not yet use the
to use the <tt>load</tt> command instead.
</p>
<H2><a name="Tcl_nn44"></a>33.9 Building new kinds of Tcl interfaces (in Tcl)</H2>
<H2><a name="Tcl_nn44"></a>34.9 Building new kinds of Tcl interfaces (in Tcl)</H2>
<p>
@ -3289,7 +3289,7 @@ danger of blowing something up (although it is easily accomplished
with an out of bounds array access).
</p>
<H3><a name="Tcl_nn45"></a>33.9.1 Proxy classes</H3>
<H3><a name="Tcl_nn45"></a>34.9.1 Proxy classes</H3>
<p>
@ -3410,7 +3410,7 @@ short, but clever Tcl script can be combined with SWIG to do many
interesting things.
</p>
<H2><a name="Tcl_nn46"></a>33.10 Tcl/Tk Stubs</H2>
<H2><a name="Tcl_nn46"></a>34.10 Tcl/Tk Stubs</H2>
<p>

851
Doc/Manual/Typemaps.html
View file

File diff suppressed because it is too large Load diff

2
Doc/Manual/Warnings.html
View file

@ -102,7 +102,7 @@ int foo(double); // Silently ignored.
<p>
The <tt>%warnfilter</tt> directive has the same semantics as other declaration modifiers like
<tt>%rename</tt>, <tt>%ignore</tt> and <tt>%feature</tt>, see the
<a href="Customization.html#features">%feature directive</a> section. For example, if you wanted to
<a href="Customization.html#Customization_features">%feature directive</a> section. For example, if you wanted to
suppress a warning for a method in a class hierarchy, you could do this:
</p>

6
Doc/Manual/Windows.html
View file

@ -67,7 +67,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/98/ME/NT/2000/XP.
The swigwin distribution contains the SWIG Windows executable, swig.exe, which will run on 32 bit versions of Windows, ie Windows 95 and later.
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>
@ -78,7 +78,7 @@ If you want to build your own swig.exe have a look at <a href="#Windows_swig_exe
<p>
Using Microsoft Visual C++ is the most common approach to compiling and linking SWIG's output.
The Examples directory has a few Visual C++ project files (.dsp files).
These were produced by Visual C++ 6, although they should also work in Visual C++ 5.
These were produced by Visual C++ 6.
Later versions of Visual Studio should also be able to open and convert these project files.
The C# examples come with .NET 2003 solution (.sln) and project files instead of Visual C++ 6 project files.
The project files have been set up to execute SWIG in a custom build rule for the SWIG interface (.i) file.
@ -272,7 +272,7 @@ Execute the steps in the order shown and don't use spaces in path names. In fact
<ul>
<li>Answer y to the "do you wish to continue with the post install?"</li>
<li>Answer y to the "do you have MinGW installed?"</li>
<li>Type in the the folder in which you installed MinGW (C:/MinGW is default)</li>
<li>Type in the folder in which you installed MinGW (C:/MinGW is default)</li>
</ul>
</li>

1
Doc/Manual/chapters
View file

@ -18,6 +18,7 @@ CCache.html
Allegrocl.html
CSharp.html
Chicken.html
Go.html
Guile.html
Java.html
Lisp.html

4
Doc/Manual/index.html
View file

@ -1,10 +1,10 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>SWIG-1.3 Documentation</title>
<title>SWIG-2.0 Documentation</title>
</head>
<body bgcolor="#ffffff">
<H1><a name="index"></a>SWIG-1.3 Development Documentation</h1>
<H1><a name="index"></a>SWIG-2.0 Documentation</h1>
The SWIG documentation is available in one of the following formats.
<ul>

82
Examples/Makefile.in
View file

@ -85,6 +85,11 @@ CXXSHARED= @CXXSHARED@
OBJS = $(SRCS:.c=.@OBJEXT@) $(CXXSRCS:.cxx=.@OBJEXT@)
distclean:
rm -f Makefile
rm -f guile/Makefile
rm -f xml/Makefile
##################################################################
##### Tcl/Tk ######
##################################################################
@ -342,7 +347,7 @@ OCTAVE_SO = @OCTAVE_SO@
octave: $(SRCS)
$(SWIG) -octave $(SWIGOPT) $(INTERFACEPATH)
$(CXX) -g -c $(CCSHARED) $(CXXFLAGS) $(ICXXSRCS) $(CXXSRCS) $(INCLUDES) -I$(OCTAVE_INCLUDE)
$(CC) -g -c $(CCSHARED) $(CFLAGS) $(SRCS) $(INCLUDES)
$(CC) -g -c $(CCSHARED) $(CFLAGS) $(SRCS) $(CSRCS) $(INCLUDES)
$(LDSHARED) $(CFLAGS) $(OBJS) $(IOBJS) $(OCTAVE_DLNK) $(LIBS) -o $(LIBPREFIX)$(TARGET)$(OCTAVE_SO)
# -----------------------------------------------------------------
@ -1125,11 +1130,11 @@ RRSRC = $(INTERFACE:.i=.R)
r: $(SRCS)
$(SWIG) -r $(SWIGOPT) $(INTERFACEPATH)
+( PKG_LIBS="$(SRCS)" PKG_CPPFLAGS="$(INCLUDES)" $(COMPILETOOL) $(R) CMD SHLIB -fPIC -o $(LIBPREFIX)$(TARGET)$(SO) $(ISRCS) )
+( PKG_CPPFLAGS="$(INCLUDES)" $(COMPILETOOL) $(R) CMD SHLIB -o $(LIBPREFIX)$(TARGET)$(SO) $(ISRCS) $(SRCS) )
r_cpp: $(CXXSRCS)
$(SWIG) -c++ -r $(SWIGOPT) -o $(RCXXSRCS) $(INTERFACEPATH)
+( PKG_LIBS="$(CXXSRCS)" PKG_CPPFLAGS="$(INCLUDES)" $(COMPILETOOL) $(R) CMD SHLIB -fPIC -o $(LIBPREFIX)$(TARGET)$(SO) $(RCXXSRCS) )
+( PKG_CPPFLAGS="$(INCLUDES)" $(COMPILETOOL) $(R) CMD SHLIB -o $(LIBPREFIX)$(TARGET)$(SO) $(RCXXSRCS) $(SRCS) $(CXXSRCS))
r_clean:
rm -f *_wrap* *~ .~*
@ -1137,3 +1142,74 @@ r_clean:
rm -f *.@OBJEXT@ *@SO@ NAMESPACE
rm -f $(RRSRC) runme.Rout .RData
##################################################################
##### Go ######
##################################################################
GO = @GO@
GOGCC = @GOGCC@
GOSWIGARG = `if $(GOGCC) ; then echo -gccgo; fi`
GOCOMPILEARG = `if $(GOGCC) ; then echo -c -g; fi`
GOSRCS = $(INTERFACE:.i=.go)
GOCSRCS = $(INTERFACE:.i=_gc.c)
GOC = $(GO:g=c)
GOLD = $(GO:g=l)
GOPACKAGE = $(INTERFACE:.i=.a)
GOOBJEXT = $(GO:g=)
GOGCOBJS = $(GOSRCS:.go=.$(GOOBJEXT))
GOGCCOBJS = $(GOSRCS:.go=.@OBJEXT@)
# ----------------------------------------------------------------
# Build a Go dynamically loadable module (C)
# ----------------------------------------------------------------
go: $(SRCS)
$(SWIG) -go $(GOSWIGARG) $(SWIGOPT) $(INTERFACEPATH)
$(CC) -g -c $(CCSHARED) $(CFLAGS) $(SRCS) $(ISRCS) $(INCLUDES)
$(LDSHARED) $(CFLAGS) $(OBJS) $(IOBJS) $(LIBS) -o $(LIBPREFIX)$(TARGET)$(SO)
$(COMPILETOOL) $(GO) -I . $(GOCOMPILEARG) $(GOSRCS)
if ! $(GOGCC) ; then \
$(COMPILETOOL) $(GOC) -I $${GOROOT}/pkg/$${GOOS}_$${GOARCH} $(GOCSRCS) && \
$(COMPILETOOL) gopack grc $(GOPACKAGE) $(GOGCOBJS) $(GOCSRCS:.c=.$(GOOBJEXT)); \
fi
# ----------------------------------------------------------------
# Build a Go dynamically loadable module (C++)
# ----------------------------------------------------------------
go_cpp: $(SRCS)
$(SWIG) -go -c++ $(GOSWIGARG) $(SWIGOPT) $(INTERFACEPATH)
$(CXX) -g -c $(CCSHARED) $(CFLAGS) $(SRCS) $(CXXSRCS) $(ICXXSRCS) $(INCLUDES)
$(CXXSHARED) $(CFLAGS) $(OBJS) $(IOBJS) $(LIBS) $(CPP_DLLIBS) -o $(LIBPREFIX)$(TARGET)$(SO)
$(COMPILETOOL) $(GO) -I . $(GOCOMPILEARG) $(GOSRCS)
if ! $(GOGCC) ; then \
$(COMPILETOOL) $(GOC) -I $${GOROOT}/pkg/$${GOOS}_$${GOARCH} $(GOCSRCS) && \
$(COMPILETOOL) gopack grc $(GOPACKAGE) $(GOGCOBJS) $(GOCSRCS:.c=.$(GOOBJEXT)); \
fi
# -----------------------------------------------------------------
# Running a Go example
# -----------------------------------------------------------------
go_run: runme.go
$(GO) $(GOCOMPILEARG) runme.go
if $(GOGCC) ; then \
$(COMPILETOOL) $(GO) -o runme runme.@OBJEXT@ $(GOGCCOBJS) $(LIBPREFIX)$(TARGET)$(SO); \
else \
$(COMPILETOOL) $(GOLD) -r $${GOROOT}/pkg/$${GOOS}_$${GOARCH}:. -o runme runme.$(GOOBJEXT); \
fi
env LD_LIBRARY_PATH=.:$$LD_LIBRARY_PATH $(RUNTOOL) ./runme
# -----------------------------------------------------------------
# Cleaning the Go examples
# -----------------------------------------------------------------
go_clean:
rm -f *_wrap* *_gc* .~* runme
rm -f core @EXTRA_CLEAN@
rm -f *.@OBJEXT@ *.[568] *.a *@SO@

4
Examples/README
View file

@ -2,9 +2,7 @@ SWIG Examples
The "perl5", "python", "tcl", "guile", "java", "mzscheme", "ruby", and
"chicken" directories contain a number of simple examples that are
primarily used for testing. The "GIFPlot" directory contains a more
complicated example that illustrates some of SWIG's more advanced
capabilities.
primarily used for testing.
The file 'index.html' is the top of a hyperlinked document that
contains information about all of the examples along with various

18
Examples/go/callback/Makefile Normal file
View file

@ -0,0 +1,18 @@
TOP = ../..
SWIG = $(TOP)/../preinst-swig
CXXSRCS = example.cxx
TARGET = example
INTERFACE = example.i
SWIGOPT =
all:: go
go::
$(MAKE) -f $(TOP)/Makefile CXXSRCS='$(CXXSRCS)' SWIG='$(SWIG)' \
SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' go_cpp
clean::
$(MAKE) -f $(TOP)/Makefile go_clean
check: all
$(MAKE) -f $(TOP)/Makefile TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' go_run

4
Examples/go/callback/example.cxx Normal file
View file

@ -0,0 +1,4 @@
/* File : example.cxx */
#include "example.h"

188
Examples/go/callback/example.go Normal file
View file

@ -0,0 +1,188 @@
/* ----------------------------------------------------------------------------
* This file was automatically generated by SWIG (http://www.swig.org).
* Version 2.0.1
*
* This file is not intended to be easily readable and contains a number of
* coding conventions designed to improve portability and efficiency. Do not make
* changes to this file unless you know what you are doing--modify the SWIG
* interface file instead.
* ----------------------------------------------------------------------------- */
package example
type _swig_fnptr *byte
type _swig_memberptr *byte
func _swig_allocatememory(int) *byte
func _swig_internal_allocate(len int) *byte {
return _swig_allocatememory(len)
}
func _swig_allocatestring(*byte, int) string
func _swig_internal_makegostring(p *byte, l int) string {
return _swig_allocatestring(p, l)
}
func _swig_internal_gopanic(p *byte, l int) {
panic(_swig_allocatestring(p, l))
}
type _swig_DirectorCallback struct {
SwigcptrCallback
v interface{}
}
func (p *_swig_DirectorCallback) Swigcptr() uintptr {
return p.SwigcptrCallback.Swigcptr()
}
func (p *_swig_DirectorCallback) SwigIsCallback() {
}
func (p *_swig_DirectorCallback) DirectorInterface() interface{} {
return p.v
}
func _swig_NewDirectorCallbackCallback(*_swig_DirectorCallback) SwigcptrCallback
func NewDirectorCallback(v interface{}) Callback {
p := &_swig_DirectorCallback{0, v}
p.SwigcptrCallback = _swig_NewDirectorCallbackCallback(p)
return p
}
func _swig_wrap_DeleteDirectorCallback(uintptr)
func DeleteDirectorCallback(arg1 Callback) {
_swig_wrap_DeleteDirectorCallback(arg1.Swigcptr())
}
func Swiggo_DeleteDirector_Callback(p *_swig_DirectorCallback) {
p.SwigcptrCallback = 0
}
type _swig_DirectorInterfaceCallbackRun interface {
Run()
}
func _swig_wrap__swig_DirectorCallback_upcall_Run(SwigcptrCallback)
func (swig_p *_swig_DirectorCallback) Run() {
if swig_g, swig_ok := swig_p.v.(_swig_DirectorInterfaceCallbackRun); swig_ok {
swig_g.Run()
return
}
_swig_wrap__swig_DirectorCallback_upcall_Run(swig_p.SwigcptrCallback)
}
func DirectorCallbackRun(p Callback) {
_swig_wrap__swig_DirectorCallback_upcall_Run(p.(*_swig_DirectorCallback).SwigcptrCallback)
}
func Swig_DirectorCallback_callback_run(p *_swig_DirectorCallback) {
p.Run()
}
type SwigcptrCallback uintptr
func (p SwigcptrCallback) Swigcptr() uintptr {
return (uintptr)(p)
}
func (p SwigcptrCallback) SwigIsCallback() {
}
func (p SwigcptrCallback) DirectorInterface() interface{} {
return nil
}
func _swig_wrap_delete_Callback(uintptr)
func DeleteCallback(arg1 Callback) {
_swig_wrap_delete_Callback(arg1.Swigcptr())
}
func _swig_wrap_Callback_run(SwigcptrCallback)
func (arg1 SwigcptrCallback) Run() {
_swig_wrap_Callback_run(arg1)
}
func _swig_wrap_new_Callback() SwigcptrCallback
func NewCallback() Callback {
return _swig_wrap_new_Callback()
}
type Callback interface {
Swigcptr() uintptr
SwigIsCallback()
DirectorInterface() interface{}
Run()
}
type SwigcptrCaller uintptr
func (p SwigcptrCaller) Swigcptr() uintptr {
return (uintptr)(p)
}
func (p SwigcptrCaller) SwigIsCaller() {
}
func _swig_wrap_new_Caller() SwigcptrCaller
func NewCaller() Caller {
return _swig_wrap_new_Caller()
}
func _swig_wrap_delete_Caller(uintptr)
func DeleteCaller(arg1 Caller) {
_swig_wrap_delete_Caller(arg1.Swigcptr())
}
func _swig_wrap_Caller_delCallback(SwigcptrCaller)
func (arg1 SwigcptrCaller) DelCallback() {
_swig_wrap_Caller_delCallback(arg1)
}
func _swig_wrap_Caller_setCallback(SwigcptrCaller, uintptr)
func (arg1 SwigcptrCaller) SetCallback(arg2 Callback) {
_swig_wrap_Caller_setCallback(arg1, arg2.Swigcptr())
}
func _swig_wrap_Caller_call(SwigcptrCaller)
func (arg1 SwigcptrCaller) Call() {
_swig_wrap_Caller_call(arg1)
}
type Caller interface {
Swigcptr() uintptr
SwigIsCaller()
DelCallback()
SetCallback(arg2 Callback)
Call()
}
type SwigcptrSwigDirector_Callback uintptr
type SwigDirector_Callback interface {
Swigcptr() uintptr;
}
func (p SwigcptrSwigDirector_Callback) Swigcptr() uintptr {
return uintptr(p)
}
type SwigcptrVoid uintptr
type Void interface {
Swigcptr() uintptr;
}
func (p SwigcptrVoid) Swigcptr() uintptr {
return uintptr(p)
}

23
Examples/go/callback/example.h Normal file
View file

@ -0,0 +1,23 @@
/* File : example.h */
#include <cstdio>
#include <iostream>
class Callback {
public:
virtual ~Callback() { std::cout << "Callback::~Callback()" << std:: endl; }
virtual void run() { std::cout << "Callback::run()" << std::endl; }
};
class Caller {
private:
Callback *_callback;
public:
Caller(): _callback(0) {}
~Caller() { delCallback(); }
void delCallback() { delete _callback; _callback = 0; }
void setCallback(Callback *cb) { delCallback(); _callback = cb; }
void call() { if (_callback) _callback->run(); }
};

13
Examples/go/callback/example.i Normal file
View file

@ -0,0 +1,13 @@
/* File : example.i */
%module(directors="1") example
%{
#include "example.h"
%}
%include "std_string.i"
/* turn on director wrapping Callback */
%feature("director") Callback;
%include "example.h"

81
Examples/go/callback/index.html Normal file
View file

@ -0,0 +1,81 @@
<html>
<head>
<title>SWIG:Examples:go:callback</title>
</head>
<body bgcolor="#ffffff">
<tt>SWIG/Examples/go/callback/</tt>
<hr>
<H2>Implementing C++ callbacks in Go</H2>
<p>
This example illustrates how to use directors to implement C++
callbacks in Go.
</p>
<p>
Because Go and C++ use inheritance differently, you must call a
different function to create a class which uses callbacks. Instead of
calling the usual constructor function whose name is <tt>New</tt>
followed by the capitalized name of the class, you call a function
named <tt>NewDirector</tt> followed by the capitalized name of the
class.
</p>
<p>
The first argument to the <tt>NewDirector</tt> function is an instance
of a type. The <tt>NewDirector</tt> function will return an interface
value as usual. However, when calling any method on the returned
value, the program will first check whether the value passed
to <tt>NewDirector</tt> implements that method. If it does, the
method will be called in Go. This is true whether the method is
called from Go code or C++ code.
</p>
<p>
Note that the Go code will be called with just the Go value, not the
C++ value. If the Go code needs to call a C++ method on itself, you
need to get a copy of the C++ object. This is typically done as
follows:
<blockquote>
<pre>
type Child struct { abi Parent }
func (p *Child) ChildMethod() {
p.abi.ParentMethod()
}
func f() {
p := &Child{nil}
d := NewDirectorParent(p)
p.abi = d
...
}
</pre>
</blockquote>
In other words, we first create the Go value. We pass that to
the <tt>NewDirector</tt> function to create the C++ value; this C++
value will be created with an association to the Go value. We then
store the C++ value in the Go value, giving us the reverse
association. That permits us to call parent methods from the child.
</p>
<p>
To delete a director object, use the function <tt>DeleteDirector</tt>
followed by the capitalized name of the class.
</p>
<p>
<ul>
<li><a href="example.h">example.h</a>. Header file containing some enums.
<li><a href="example.i">example.i</a>. Interface file.
<li><a href="runme.go">runme.go</a>. Sample Go program.
</ul>
<hr>
</body>
</html>

41
Examples/go/callback/runme.go Normal file
View file

@ -0,0 +1,41 @@
package main
import (
"fmt"
. "./example"
)
func main() {
fmt.Println("Adding and calling a normal C++ callback")
fmt.Println("----------------------------------------")
caller := NewCaller()
callback := NewCallback()
caller.SetCallback(callback)
caller.Call()
caller.DelCallback()
callback = NewDirectorCallback(new(GoCallback))
fmt.Println()
fmt.Println("Adding and calling a Go callback")
fmt.Println("------------------------------------")
caller.SetCallback(callback)
caller.Call()
caller.DelCallback()
// Test that a double delete does not occur as the object has
// already been deleted from the C++ layer.
DeleteDirectorCallback(callback)
fmt.Println()
fmt.Println("Go exit")
}
type GoCallback struct{}
func (p *GoCallback) Run() {
fmt.Println("GoCallback.Run")
}

13
Examples/go/check.list Normal file
View file

@ -0,0 +1,13 @@
# see top-level Makefile.in
callback
class
constants
enum
extend
funcptr
multimap
pointer
reference
simple
template
variables

16
Examples/go/class/Makefile Normal file
View file

@ -0,0 +1,16 @@
TOP = ../..
SWIG = $(TOP)/../preinst-swig
CXXSRCS = example.cxx
TARGET = example
INTERFACE = example.i
LIBS = -lm
all::
$(MAKE) -f $(TOP)/Makefile CXXSRCS='$(CXXSRCS)' SWIG='$(SWIG)' \
TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' go_cpp
clean::
$(MAKE) -f $(TOP)/Makefile go_clean
check: all
$(MAKE) -f $(TOP)/Makefile TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' go_run

28
Examples/go/class/example.cxx Normal file
View file

@ -0,0 +1,28 @@
/* File : example.c */
#include "example.h"
#define M_PI 3.14159265358979323846
/* Move the shape to a new location */
void Shape::move(double dx, double dy) {
x += dx;
y += dy;
}
int Shape::nshapes = 0;
double Circle::area(void) {
return M_PI*radius*radius;
}
double Circle::perimeter(void) {
return 2*M_PI*radius;
}
double Square::area(void) {
return width*width;
}
double Square::perimeter(void) {
return 4*width;
}

284
Examples/go/class/example.go Normal file
View file

@ -0,0 +1,284 @@
/* ----------------------------------------------------------------------------
* This file was automatically generated by SWIG (http://www.swig.org).
* Version 2.0.1
*
* This file is not intended to be easily readable and contains a number of
* coding conventions designed to improve portability and efficiency. Do not make
* changes to this file unless you know what you are doing--modify the SWIG
* interface file instead.
* ----------------------------------------------------------------------------- */
package example
type _swig_fnptr *byte
type _swig_memberptr *byte
func _swig_allocatememory(int) *byte
func _swig_internal_allocate(len int) *byte {
return _swig_allocatememory(len)
}
func _swig_allocatestring(*byte, int) string
func _swig_internal_makegostring(p *byte, l int) string {
return _swig_allocatestring(p, l)
}
func _swig_internal_gopanic(p *byte, l int) {
panic(_swig_allocatestring(p, l))
}
type SwigcptrShape uintptr
func (p SwigcptrShape) Swigcptr() uintptr {
return (uintptr)(p)
}
func (p SwigcptrShape) SwigIsShape() {
}
func _swig_wrap_delete_Shape(uintptr)
func DeleteShape(arg1 Shape) {
_swig_wrap_delete_Shape(arg1.Swigcptr())
}
func _swig_wrap_Shape_x_set(SwigcptrShape, float64)
func (arg1 SwigcptrShape) SetX(arg2 float64) {
_swig_wrap_Shape_x_set(arg1, arg2)
}
func _swig_wrap_Shape_x_get(SwigcptrShape) float64
func (arg1 SwigcptrShape) GetX() float64 {
return _swig_wrap_Shape_x_get(arg1)
}
func _swig_wrap_Shape_y_set(SwigcptrShape, float64)
func (arg1 SwigcptrShape) SetY(arg2 float64) {
_swig_wrap_Shape_y_set(arg1, arg2)
}
func _swig_wrap_Shape_y_get(SwigcptrShape) float64
func (arg1 SwigcptrShape) GetY() float64 {
return _swig_wrap_Shape_y_get(arg1)
}
func _swig_wrap_Shape_move(SwigcptrShape, float64, float64)
func (arg1 SwigcptrShape) Move(arg2 float64, arg3 float64) {
_swig_wrap_Shape_move(arg1, arg2, arg3)
}
func _swig_wrap_Shape_area(SwigcptrShape) float64
func (arg1 SwigcptrShape) Area() float64 {
return _swig_wrap_Shape_area(arg1)
}
func _swig_wrap_Shape_perimeter(SwigcptrShape) float64
func (arg1 SwigcptrShape) Perimeter() float64 {
return _swig_wrap_Shape_perimeter(arg1)
}
func _swig_wrap_Shape_nshapes_set(int)
func SetShapeNshapes(arg1 int) {
_swig_wrap_Shape_nshapes_set(arg1)
}
func GetShapeNshapes() int
type Shape interface {
Swigcptr() uintptr
SwigIsShape()
SetX(arg2 float64)
GetX() float64
SetY(arg2 float64)
GetY() float64
Move(arg2 float64, arg3 float64)
Area() float64
Perimeter() float64
}
type SwigcptrCircle uintptr
func (p SwigcptrCircle) Swigcptr() uintptr {
return (uintptr)(p)
}
func (p SwigcptrCircle) SwigIsCircle() {
}
func _swig_wrap_new_Circle(float64) SwigcptrCircle
func NewCircle(arg1 float64) Circle {
return _swig_wrap_new_Circle(arg1)
}
func _swig_wrap_Circle_area(SwigcptrCircle) float64
func (arg1 SwigcptrCircle) Area() float64 {
return _swig_wrap_Circle_area(arg1)
}
func _swig_wrap_Circle_perimeter(SwigcptrCircle) float64
func (arg1 SwigcptrCircle) Perimeter() float64 {
return _swig_wrap_Circle_perimeter(arg1)
}
func _swig_wrap_delete_Circle(uintptr)
func DeleteCircle(arg1 Circle) {
_swig_wrap_delete_Circle(arg1.Swigcptr())
}
func _swig_wrap_SetCircle_X(SwigcptrCircle, float64)
func (_swig_base SwigcptrCircle) SetX(arg1 float64) {
_swig_wrap_SetCircle_X(_swig_base, arg1)
}
func _swig_wrap_GetCircle_X(SwigcptrCircle) float64
func (_swig_base SwigcptrCircle) GetX() float64 {
return _swig_wrap_GetCircle_X(_swig_base)
}
func _swig_wrap_SetCircle_Y(SwigcptrCircle, float64)
func (_swig_base SwigcptrCircle) SetY(arg1 float64) {
_swig_wrap_SetCircle_Y(_swig_base, arg1)
}
func _swig_wrap_GetCircle_Y(SwigcptrCircle) float64
func (_swig_base SwigcptrCircle) GetY() float64 {
return _swig_wrap_GetCircle_Y(_swig_base)
}
func _swig_wrap_Circle_move(SwigcptrCircle, float64, float64)
func (_swig_base SwigcptrCircle) Move(arg1 float64, arg2 float64) {
_swig_wrap_Circle_move(_swig_base, arg1, arg2)
}
func (p SwigcptrCircle) SwigIsShape() {
}
func (p SwigcptrCircle) SwigGetShape() Shape {
return SwigcptrShape(p.Swigcptr())
}
type Circle interface {
Swigcptr() uintptr
SwigIsCircle()
Area() float64
Perimeter() float64
SetX(arg1 float64)
GetX() float64
SetY(arg1 float64)
GetY() float64
Move(arg1 float64, arg2 float64)
SwigIsShape()
SwigGetShape() Shape
}
type SwigcptrSquare uintptr
func (p SwigcptrSquare) Swigcptr() uintptr {
return (uintptr)(p)
}
func (p SwigcptrSquare) SwigIsSquare() {
}
func _swig_wrap_new_Square(float64) SwigcptrSquare
func NewSquare(arg1 float64) Square {
return _swig_wrap_new_Square(arg1)
}
func _swig_wrap_Square_area(SwigcptrSquare) float64
func (arg1 SwigcptrSquare) Area() float64 {
return _swig_wrap_Square_area(arg1)
}
func _swig_wrap_Square_perimeter(SwigcptrSquare) float64
func (arg1 SwigcptrSquare) Perimeter() float64 {
return _swig_wrap_Square_perimeter(arg1)
}
func _swig_wrap_delete_Square(uintptr)
func DeleteSquare(arg1 Square) {
_swig_wrap_delete_Square(arg1.Swigcptr())
}
func _swig_wrap_SetSquare_X(SwigcptrSquare, float64)
func (_swig_base SwigcptrSquare) SetX(arg1 float64) {
_swig_wrap_SetSquare_X(_swig_base, arg1)
}
func _swig_wrap_GetSquare_X(SwigcptrSquare) float64
func (_swig_base SwigcptrSquare) GetX() float64 {
return _swig_wrap_GetSquare_X(_swig_base)
}
func _swig_wrap_SetSquare_Y(SwigcptrSquare, float64)
func (_swig_base SwigcptrSquare) SetY(arg1 float64) {
_swig_wrap_SetSquare_Y(_swig_base, arg1)
}
func _swig_wrap_GetSquare_Y(SwigcptrSquare) float64
func (_swig_base SwigcptrSquare) GetY() float64 {
return _swig_wrap_GetSquare_Y(_swig_base)
}
func _swig_wrap_Square_move(SwigcptrSquare, float64, float64)
func (_swig_base SwigcptrSquare) Move(arg1 float64, arg2 float64) {
_swig_wrap_Square_move(_swig_base, arg1, arg2)
}
func (p SwigcptrSquare) SwigIsShape() {
}
func (p SwigcptrSquare) SwigGetShape() Shape {
return SwigcptrShape(p.Swigcptr())
}
type Square interface {
Swigcptr() uintptr
SwigIsSquare()
Area() float64
Perimeter() float64
SetX(arg1 float64)
GetX() float64
SetY(arg1 float64)
GetY() float64
Move(arg1 float64, arg2 float64)
SwigIsShape()
SwigGetShape() Shape
}
type SwigcptrVoid uintptr
type Void interface {
Swigcptr() uintptr;
}
func (p SwigcptrVoid) Swigcptr() uintptr {
return uintptr(p)
}

39
Examples/go/class/example.h Normal file
View file

@ -0,0 +1,39 @@
/* File : example.h */
class Shape {
public:
Shape() {
nshapes++;
}
virtual ~Shape() {
nshapes--;
};
double x, y;
void move(double dx, double dy);
virtual double area(void) = 0;
virtual double perimeter(void) = 0;
static int nshapes;
};
class Circle : public Shape {
private:
double radius;
public:
Circle(double r) : radius(r) { };
virtual double area(void);
virtual double perimeter(void);
};
class Square : public Shape {
private:
double width;
public:
Square(double w) : width(w) { };
virtual double area(void);
virtual double perimeter(void);
};

10
Examples/go/class/example.i Normal file
View file

@ -0,0 +1,10 @@
/* File : example.i */
%module example
%{
#include "example.h"
%}
/* Let's just grab the original header file here */
%include "example.h"

203
Examples/go/class/index.html Normal file
View file

@ -0,0 +1,203 @@
<html>
<head>
<title>SWIG:Examples:go:class</title>
</head>
<body bgcolor="#ffffff">
<tt>SWIG/Examples/go/class/</tt>
<hr>
<H2>Wrapping a simple C++ class</H2>
<p>
This example illustrates the most primitive form of C++ class wrapping
performed by SWIG. In this case, C++ classes are simply transformed
into a collection of C-style functions that provide access to class
members.
<h2>The C++ Code</h2>
Suppose you have some C++ classes described by the following (and
admittedly lame) header file:
<blockquote>
<pre>
/* File : example.h */
class Shape {
public:
Shape() {
nshapes++;
}
virtual ~Shape() {
nshapes--;
};
double x, y;
void move(double dx, double dy);
virtual double area() = 0;
virtual double perimeter() = 0;
static int nshapes;
};
class Circle : public Shape {
private:
double radius;
public:
Circle(double r) : radius(r) { };
virtual double area();
virtual double perimeter();
};
class Square : public Shape {
private:
double width;
public:
Square(double w) : width(w) { };
virtual double area();
virtual double perimeter();
};
</pre>
</blockquote>
<h2>The SWIG interface</h2>
A simple SWIG interface for this can be built by simply grabbing the
header file like this:
<blockquote>
<pre>
/* File : example.i */
%module example
%{
#include "example.h"
%}
/* Let's just grab the original header file here */
%include "example.h"
</pre>
</blockquote>
Note: when creating a C++ extension, you must run SWIG with
the <tt>-c++</tt> option like this:
<blockquote>
<pre>
% swig -c++ -go example.i
</pre>
</blockquote>
<h2>A sample Go script</h2>
See <a href="example.go">example.go</a> for a program that calls the
C++ functions from Go.
<h2>Key points</h2>
<ul>
<li>To create a new object, you call a constructor like this:
<blockquote>
<pre>
c := example.NewCircle(10.0)
</pre>
</blockquote>
The name of the constructor is <tt>New</tt> followed by the name of
the class, capitalized.
<p>
<li>
The constructor returns a value of interface type. The methods of the
interface will be the methods of the C++ class, plus member accessor
functions.
<p>
<li>To access member data, a pair of accessor methods are used. For
example:
<blockquote>
<pre>
c.SetX(15) # Set member data
x := c.GetX() # Get member data.
</pre>
</blockquote>
These are methods on the type returned by the constructor. The getter
is named <tt>Get</tt> followed by the name of the member,
capitalized. The setter is similar but uses <tt>Set</tt>.
<p>
<li>To invoke a member function, you simply do this
<blockquote>
<pre>
fmt.Println("The area is", example.c.Area())
</pre>
</blockquote>
<li>To invoke a destructor, simply do this
<blockquote>
<pre>
example.DeleteShape(c) # Deletes a shape
</pre>
</blockquote>
The name of the destructor is <tt>Delete</tt> followed by the name of
the class, capitalized. (Note: destructors are currently not
inherited. This might change later).
<p>
<li>Static member variables are wrapped much like C global variables.
For example:
<blockquote>
<pre>
n := GetShapeNshapes() # Get a static data member
SetShapeNshapes(13) # Set a static data member
</pre>
</blockquote>
The name is <tt>Get</tt> or <tt>Set</tt>, followed by the name of the
class, capitalized, followed by the name of the member, capitalized.
</ul>
<h2>General Comments</h2>
<ul>
<li>This low-level interface is not the only way to handle C++ code.
Director classes provide a much higher-level interface.
<p>
<li>Because C++ and Go implement inheritance quite differently, you
can not simply upcast an object in Go code when using multiple
inheritance. When using only single inheritance, you can simply pass
a class to a function expecting a parent class. When using multiple
inheritance, you have to call an automatically generated getter
function named <tt>Get</tt> followed by the capitalized name of the
immediate parent. This will return the same object converted to the
parent class.
<p>
<li>
Overloaded methods should normally work. However, when calling an
overloaded method you must explicitly convert constants to the
expected type when it is not <tt>int</tt> or <tt>float</tt>. In
particular, a floating point constant will default to
type <tt>float</tt>, but C++ functions typically expect the C++
type <tt>double</tt> which is equivalent to the Go
type <tt>float64</tt> So calling an overloaded method with a floating
point constant typically requires an explicit conversion
to <tt>float64</tt>.
<p>
<li>Namespaces are not supported in any very coherent way.
</ul>
<hr>
</body>
</html>

63
Examples/go/class/runme.go Normal file
View file

@ -0,0 +1,63 @@
// This example illustrates how C++ classes can be used from Go using SWIG.
package main
import (
"fmt"
. "./example"
)
func main() {
// ----- Object creation -----
fmt.Println("Creating some objects:")
c := NewCircle(10)
fmt.Println(" Created circle", c)
s := NewSquare(10)
fmt.Println(" Created square", s)
// ----- Access a static member -----
fmt.Println("\nA total of", GetShapeNshapes(), "shapes were created")
// ----- Member data access -----
// Notice how we can do this using functions specific to
// the 'Circle' class.
c.SetX(20)
c.SetY(30)
// Now use the same functions in the base class
var shape Shape = s
shape.SetX(-10)
shape.SetY(5)
fmt.Println("\nHere is their current position:")
fmt.Println(" Circle = (", c.GetX(), " ", c.GetY(), ")")
fmt.Println(" Square = (", s.GetX(), " ", s.GetY(), ")")
// ----- Call some methods -----
fmt.Println("\nHere are some properties of the shapes:")
shapes := []Shape{c, s}
for i := 0; i < len(shapes); i++ {
fmt.Println(" ", shapes[i])
fmt.Println(" area = ", shapes[i].Area())
fmt.Println(" perimeter = ", shapes[i].Perimeter())
}
// Notice how the area() and perimeter() functions really
// invoke the appropriate virtual method on each object.
// ----- Delete everything -----
fmt.Println("\nGuess I'll clean up now")
// Note: this invokes the virtual destructor
// You could leave this to the garbage collector
DeleteCircle(c)
DeleteSquare(s)
fmt.Println(GetShapeNshapes(), " shapes remain")
fmt.Println("Goodbye")
}

16
Examples/go/constants/Makefile Normal file
View file

@ -0,0 +1,16 @@
TOP = ../..
SWIG = $(TOP)/../preinst-swig
CXXSRCS =
TARGET = example
INTERFACE = example.i
SWIGOPT =
all::
$(MAKE) -f $(TOP)/Makefile CXXSRCS='$(CXXSRCS)' SWIG='$(SWIG)' \
SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' go
clean::
$(MAKE) -f $(TOP)/Makefile go_clean
check: all
$(MAKE) -f $(TOP)/Makefile TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' go_run

44
Examples/go/constants/example.go Normal file
View file

@ -0,0 +1,44 @@
/* ----------------------------------------------------------------------------
* This file was automatically generated by SWIG (http://www.swig.org).
* Version 2.0.1
*
* This file is not intended to be easily readable and contains a number of
* coding conventions designed to improve portability and efficiency. Do not make
* changes to this file unless you know what you are doing--modify the SWIG
* interface file instead.
* ----------------------------------------------------------------------------- */
package example
type _swig_fnptr *byte
type _swig_memberptr *byte
func _swig_allocatememory(int) *byte
func _swig_internal_allocate(len int) *byte {
return _swig_allocatememory(len)
}
func _swig_allocatestring(*byte, int) string
func _swig_internal_makegostring(p *byte, l int) string {
return _swig_allocatestring(p, l)
}
func _swig_internal_gopanic(p *byte, l int) {
panic(_swig_allocatestring(p, l))
}
const ICONST int = 42
const FCONST float64 = 2.1828
const CCONST byte = 'x'
func _swig_getCCONST2() byte
var CCONST2 byte = _swig_getCCONST2()
const SCONST string = "Hello World"
func _swig_getSCONST2() string
var SCONST2 string = _swig_getSCONST2()
func _swig_getEXPR() float64
var EXPR float64 = _swig_getEXPR()
const Iconst int = 37
const Fconst float64 = 3.14

25
Examples/go/constants/example.i Normal file
View file

@ -0,0 +1,25 @@
/* File : example.i */
%module example
/* A few preprocessor macros */
#define ICONST 42
#define FCONST 2.1828
#define CCONST 'x'
#define CCONST2 '\n'
#define SCONST "Hello World"
#define SCONST2 "\"Hello World\""
/* This should work just fine */
#define EXPR ICONST + 3*(FCONST)
/* This shouldn't do anything */
#define EXTERN extern
/* Neither should this (BAR isn't defined) */
#define FOO (ICONST + BAR)
/* The following directives also produce constants */
%constant int iconst = 37;
%constant double fconst = 3.14;

55
Examples/go/constants/index.html Normal file
View file

@ -0,0 +1,55 @@
<html>
<head>
<title>SWIG:Examples:go:constants</title>
</head>
<body bgcolor="#ffffff">
<tt>SWIG/Examples/go/constants/</tt>
<hr>
<H2>Wrapping C Constants</H2>
<p>
When SWIG encounters C preprocessor macros and C declarations that
look like constants, it creates a Go constant with an identical value.
Click <a href="example.i">here</a> to see a SWIG interface with some
constant declarations in it.
<h2>Accessing Constants from Go</h2>
Click <a href="../../../Doc/Manual/Go.html#go_constants">here</a> for
the section on constants in the SWIG and Go documentation.
<p>
Click <a href="runme.go">here</a> to see a Go program that prints out
the values of the constants contained in the above file.</p>
<h2>Key points</h2>
<ul>
<li>All names are capitalized to make them visible.
<li>The values of preprocessor macros are converted into Go constants.
<li>C string literals such as "Hello World" are converted into Go strings.
<li>Macros that are not fully defined are simply ignored. For example:
<blockquote>
<pre>
#define EXTERN extern
</pre>
</blockquote>
is ignored because SWIG has no idea what type of variable this would be.
<p>
<li>Expressions are allowed provided that all of their components are
defined. Otherwise, the constant is ignored.
<li>Certain C declarations involving 'const' are also turned into Go
constants.
<li>The constants that appear in a SWIG interface file do not have to
appear in any sort of matching C source file since the creation of a
constant does not require linkage to a stored value (i.e., a value
held in a C global variable or memory location).
</ul>
<hr>
</body>
</html>

18
Examples/go/constants/runme.go Normal file
View file

@ -0,0 +1,18 @@
package main
import (
"fmt"
"./example"
)
func main() {
fmt.Println("ICONST = ", example.ICONST, " (should be 42)")
fmt.Println("FCONST = ", example.FCONST, " (should be 2.1828)")
fmt.Printf("CCONST = %c (should be 'x')\n", example.CCONST)
fmt.Printf("CCONST2 = %c(this should be on a new line)\n", example.CCONST2)
fmt.Println("SCONST = ", example.SCONST, " (should be 'Hello World')")
fmt.Println("SCONST2 = ", example.SCONST2, " (should be '\"Hello World\"')")
fmt.Println("EXPR = ", example.EXPR, " (should be 48.5484)")
fmt.Println("iconst = ", example.Iconst, " (should be 37)")
fmt.Println("fconst = ", example.Fconst, " (should be 3.14)")
}

18
Examples/go/enum/Makefile Normal file
View file

@ -0,0 +1,18 @@
TOP = ../..
SWIG = $(TOP)/../preinst-swig
CXXSRCS = example.cxx
TARGET = example
INTERFACE = example.i
SWIGOPT =
all:: go
go::
$(MAKE) -f $(TOP)/Makefile CXXSRCS='$(CXXSRCS)' SWIG='$(SWIG)' \
SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' go_cpp
clean::
$(MAKE) -f $(TOP)/Makefile go_clean
check: all
$(MAKE) -f $(TOP)/Makefile TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' go_run

37
Examples/go/enum/example.cxx Normal file
View file

@ -0,0 +1,37 @@
/* File : example.cxx */
#include "example.h"
#include <stdio.h>
void Foo::enum_test(speed s) {
if (s == IMPULSE) {
printf("IMPULSE speed\n");
} else if (s == WARP) {
printf("WARP speed\n");
} else if (s == LUDICROUS) {
printf("LUDICROUS speed\n");
} else {
printf("Unknown speed\n");
}
}
void enum_test(color c, Foo::speed s) {
if (c == RED) {
printf("color = RED, ");
} else if (c == BLUE) {
printf("color = BLUE, ");
} else if (c == GREEN) {
printf("color = GREEN, ");
} else {
printf("color = Unknown color!, ");
}
if (s == Foo::IMPULSE) {
printf("speed = IMPULSE speed\n");
} else if (s == Foo::WARP) {
printf("speed = WARP speed\n");
} else if (s == Foo::LUDICROUS) {
printf("speed = LUDICROUS speed\n");
} else {
printf("speed = Unknown speed!\n");
}
}

93
Examples/go/enum/example.go Normal file
View file

@ -0,0 +1,93 @@
/* ----------------------------------------------------------------------------
* This file was automatically generated by SWIG (http://www.swig.org).
* Version 2.0.1
*
* This file is not intended to be easily readable and contains a number of
* coding conventions designed to improve portability and efficiency. Do not make
* changes to this file unless you know what you are doing--modify the SWIG
* interface file instead.
* ----------------------------------------------------------------------------- */
package example
type _swig_fnptr *byte
type _swig_memberptr *byte
func _swig_allocatememory(int) *byte
func _swig_internal_allocate(len int) *byte {
return _swig_allocatememory(len)
}
func _swig_allocatestring(*byte, int) string
func _swig_internal_makegostring(p *byte, l int) string {
return _swig_allocatestring(p, l)
}
func _swig_internal_gopanic(p *byte, l int) {
panic(_swig_allocatestring(p, l))
}
type Color int
func _swig_getRED() Color
var RED Color = _swig_getRED()
func _swig_getBLUE() Color
var BLUE Color = _swig_getBLUE()
func _swig_getGREEN() Color
var GREEN Color = _swig_getGREEN()
type SwigcptrFoo uintptr
func (p SwigcptrFoo) Swigcptr() uintptr {
return (uintptr)(p)
}
func (p SwigcptrFoo) SwigIsFoo() {
}
func _swig_wrap_new_Foo() SwigcptrFoo
func NewFoo() Foo {
return _swig_wrap_new_Foo()
}
type FooSpeed int
func _swig_getFoo_IMPULSE_Foo() FooSpeed
var FooIMPULSE FooSpeed = _swig_getFoo_IMPULSE_Foo()
func _swig_getFoo_WARP_Foo() FooSpeed
var FooWARP FooSpeed = _swig_getFoo_WARP_Foo()
func _swig_getFoo_LUDICROUS_Foo() FooSpeed
var FooLUDICROUS FooSpeed = _swig_getFoo_LUDICROUS_Foo()
func _swig_wrap_Foo_enum_test(SwigcptrFoo, FooSpeed)
func (arg1 SwigcptrFoo) Enum_test(arg2 FooSpeed) {
_swig_wrap_Foo_enum_test(arg1, arg2)
}
func _swig_wrap_delete_Foo(uintptr)
func DeleteFoo(arg1 Foo) {
_swig_wrap_delete_Foo(arg1.Swigcptr())
}
type Foo interface {
Swigcptr() uintptr
SwigIsFoo()
Enum_test(arg2 FooSpeed)
}
func _swig_wrap_enum_test(Color, FooSpeed)
func Enum_test(arg1 Color, arg2 FooSpeed) {
_swig_wrap_enum_test(arg1, arg2)
}
type SwigcptrVoid uintptr
type Void interface {
Swigcptr() uintptr;
}
func (p SwigcptrVoid) Swigcptr() uintptr {
return uintptr(p)
}

13
Examples/go/enum/example.h Normal file
View file

@ -0,0 +1,13 @@
/* File : example.h */
enum color { RED, BLUE, GREEN };
class Foo {
public:
Foo() { }
enum speed { IMPULSE=10, WARP=20, LUDICROUS=30 };
void enum_test(speed s);
};
void enum_test(color c, Foo::speed s);

11
Examples/go/enum/example.i Normal file
View file

@ -0,0 +1,11 @@
/* File : example.i */
%module example
%{
#include "example.h"
%}
/* Let's just grab the original header file here */
%include "example.h"

42
Examples/go/enum/index.html Normal file
View file

@ -0,0 +1,42 @@
<html>
<head>
<title>SWIG:Examples:go:enum</title>
</head>
<body bgcolor="#ffffff">
<tt>SWIG/Examples/go/enum/</tt>
<hr>
<H2>Wrapping enumerations</H2>
<p>
This example tests SWIG's ability to wrap enumerations.
<ul>
<li>
Enum values are expressed as constants or variables in GO.
<li>
If the enum is named, then that name, capitalized, as defined as a new
type name for <tt>int</tt>. All the enum values will be defined to
have that type.
<li>
If the enum is declared at global level, then the name in Go is simply
the enum value, capitalized.
<li>
If the enum is declared within a C++ class or struct, then the name in
Go is the capitalized name of the class or struct followed by the
capitalized name of the enum value.
<li>
</ul>
<p>
<ul>
<li><a href="example.h">example.h</a>. Header file containing some enums.
<li><a href="example.i">example.i</a>. Interface file.
<li><a href="runme.go">runme.go</a>. Sample Go program.
</ul>
<hr>
</body>
</html>

32
Examples/go/enum/runme.go Normal file
View file

@ -0,0 +1,32 @@
package main
import (
"fmt"
. "./example"
)
func main() {
// Print out the value of some enums
fmt.Println("*** color ***")
fmt.Println(" RED = ", RED)
fmt.Println(" BLUE = ", BLUE)
fmt.Println(" GREEN = ", GREEN)
fmt.Println("\n*** Foo::speed ***")
fmt.Println(" Foo::IMPULSE = ", FooIMPULSE)
fmt.Println(" Foo::WARP = ", FooWARP)
fmt.Println(" Foo::LUDICROUS = ", FooLUDICROUS)
fmt.Println("\nTesting use of enums with functions\n")
Enum_test(RED, FooIMPULSE)
Enum_test(BLUE, FooWARP)
Enum_test(GREEN, FooLUDICROUS)
fmt.Println("\nTesting use of enum with class method")
f := NewFoo()
f.Enum_test(FooIMPULSE)
f.Enum_test(FooWARP)
f.Enum_test(FooLUDICROUS)
}

18
Examples/go/extend/Makefile Normal file
View file

@ -0,0 +1,18 @@
TOP = ../..
SWIG = $(TOP)/../preinst-swig
CXXSRCS = example.cxx
TARGET = example
INTERFACE = example.i
SWIGOPT =
all:: go
go::
$(MAKE) -f $(TOP)/Makefile CXXSRCS='$(CXXSRCS)' SWIG='$(SWIG)' \
SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' go_cpp
clean::
$(MAKE) -f $(TOP)/Makefile go_clean
check: all
$(MAKE) -f $(TOP)/Makefile TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' go_run

4
Examples/go/extend/example.cxx Normal file
View file

@ -0,0 +1,4 @@
/* File : example.cxx */
#include "example.h"

397
Examples/go/extend/example.go Normal file
View file

@ -0,0 +1,397 @@
/* ----------------------------------------------------------------------------
* This file was automatically generated by SWIG (http://www.swig.org).
* Version 2.0.1
*
* This file is not intended to be easily readable and contains a number of
* coding conventions designed to improve portability and efficiency. Do not make
* changes to this file unless you know what you are doing--modify the SWIG
* interface file instead.
* ----------------------------------------------------------------------------- */
package example
type _swig_fnptr *byte
type _swig_memberptr *byte
func _swig_allocatememory(int) *byte
func _swig_internal_allocate(len int) *byte {
return _swig_allocatememory(len)
}
func _swig_allocatestring(*byte, int) string
func _swig_internal_makegostring(p *byte, l int) string {
return _swig_allocatestring(p, l)
}
func _swig_internal_gopanic(p *byte, l int) {
panic(_swig_allocatestring(p, l))
}
type _swig_DirectorEmployee struct {
SwigcptrEmployee
v interface{}
}
func (p *_swig_DirectorEmployee) Swigcptr() uintptr {
return p.SwigcptrEmployee.Swigcptr()
}
func (p *_swig_DirectorEmployee) SwigIsEmployee() {
}
func (p *_swig_DirectorEmployee) DirectorInterface() interface{} {
return p.v
}
func _swig_NewDirectorEmployeeEmployee(*_swig_DirectorEmployee, string) SwigcptrEmployee
func NewDirectorEmployee(v interface{}, arg1 string) Employee {
p := &_swig_DirectorEmployee{0, v}
p.SwigcptrEmployee = _swig_NewDirectorEmployeeEmployee(p, arg1)
return p
}
type _swig_DirectorInterfaceEmployeeGetTitle interface {
GetTitle() string
}
func _swig_wrap__swig_DirectorEmployee_upcall_GetTitle(SwigcptrEmployee) string
func (swig_p *_swig_DirectorEmployee) GetTitle() string {
if swig_g, swig_ok := swig_p.v.(_swig_DirectorInterfaceEmployeeGetTitle); swig_ok {
return swig_g.GetTitle()
}
return _swig_wrap__swig_DirectorEmployee_upcall_GetTitle(swig_p.SwigcptrEmployee)
}
func DirectorEmployeeGetTitle(p Employee) string {
return _swig_wrap__swig_DirectorEmployee_upcall_GetTitle(p.(*_swig_DirectorEmployee).SwigcptrEmployee)
}
func Swig_DirectorEmployee_callback_getTitle(p *_swig_DirectorEmployee) (swig_result string) {
return p.GetTitle()
}
type _swig_DirectorInterfaceEmployeeGetName interface {
GetName() string
}
func _swig_wrap__swig_DirectorEmployee_upcall_GetName(SwigcptrEmployee) string
func (swig_p *_swig_DirectorEmployee) GetName() string {
if swig_g, swig_ok := swig_p.v.(_swig_DirectorInterfaceEmployeeGetName); swig_ok {
return swig_g.GetName()
}
return _swig_wrap__swig_DirectorEmployee_upcall_GetName(swig_p.SwigcptrEmployee)
}
func DirectorEmployeeGetName(p Employee) string {
return _swig_wrap__swig_DirectorEmployee_upcall_GetName(p.(*_swig_DirectorEmployee).SwigcptrEmployee)
}
func Swig_DirectorEmployee_callback_getName(p *_swig_DirectorEmployee) (swig_result string) {
return p.GetName()
}
type _swig_DirectorInterfaceEmployeeGetPosition interface {
GetPosition() string
}
func _swig_wrap__swig_DirectorEmployee_upcall_GetPosition(SwigcptrEmployee) string
func (swig_p *_swig_DirectorEmployee) GetPosition() string {
if swig_g, swig_ok := swig_p.v.(_swig_DirectorInterfaceEmployeeGetPosition); swig_ok {
return swig_g.GetPosition()
}
return _swig_wrap__swig_DirectorEmployee_upcall_GetPosition(swig_p.SwigcptrEmployee)
}
func DirectorEmployeeGetPosition(p Employee) string {
return _swig_wrap__swig_DirectorEmployee_upcall_GetPosition(p.(*_swig_DirectorEmployee).SwigcptrEmployee)
}
func Swig_DirectorEmployee_callback_getPosition(p *_swig_DirectorEmployee) (swig_result string) {
return p.GetPosition()
}
func _swig_wrap_DeleteDirectorEmployee(uintptr)
func DeleteDirectorEmployee(arg1 Employee) {
_swig_wrap_DeleteDirectorEmployee(arg1.Swigcptr())
}
func Swiggo_DeleteDirector_Employee(p *_swig_DirectorEmployee) {
p.SwigcptrEmployee = 0
}
type SwigcptrEmployee uintptr
func (p SwigcptrEmployee) Swigcptr() uintptr {
return (uintptr)(p)
}
func (p SwigcptrEmployee) SwigIsEmployee() {
}
func (p SwigcptrEmployee) DirectorInterface() interface{} {
return nil
}
func _swig_wrap_new_Employee(string) SwigcptrEmployee
func NewEmployee(arg1 string) Employee {
return _swig_wrap_new_Employee(arg1)
}
func _swig_wrap_Employee_getTitle(SwigcptrEmployee) string
func (arg1 SwigcptrEmployee) GetTitle() string {
return _swig_wrap_Employee_getTitle(arg1)
}
func _swig_wrap_Employee_getName(SwigcptrEmployee) string
func (arg1 SwigcptrEmployee) GetName() string {
return _swig_wrap_Employee_getName(arg1)
}
func _swig_wrap_Employee_getPosition(SwigcptrEmployee) string
func (arg1 SwigcptrEmployee) GetPosition() string {
return _swig_wrap_Employee_getPosition(arg1)
}
func _swig_wrap_delete_Employee(uintptr)
func DeleteEmployee(arg1 Employee) {
_swig_wrap_delete_Employee(arg1.Swigcptr())
}
type Employee interface {
Swigcptr() uintptr
SwigIsEmployee()
DirectorInterface() interface{}
GetTitle() string
GetName() string
GetPosition() string
}
type _swig_DirectorManager struct {
SwigcptrManager
v interface{}
}
func (p *_swig_DirectorManager) Swigcptr() uintptr {
return p.SwigcptrManager.Swigcptr()
}
func (p *_swig_DirectorManager) SwigIsManager() {
}
func (p *_swig_DirectorManager) DirectorInterface() interface{} {
return p.v
}
func _swig_NewDirectorManagerManager(*_swig_DirectorManager, string) SwigcptrManager
func NewDirectorManager(v interface{}, arg1 string) Manager {
p := &_swig_DirectorManager{0, v}
p.SwigcptrManager = _swig_NewDirectorManagerManager(p, arg1)
return p
}
type _swig_DirectorInterfaceManagerGetTitle interface {
GetTitle() string
}
func _swig_wrap__swig_DirectorManager_upcall_GetTitle(SwigcptrManager) string
func (swig_p *_swig_DirectorManager) GetTitle() string {
if swig_g, swig_ok := swig_p.v.(_swig_DirectorInterfaceManagerGetTitle); swig_ok {
return swig_g.GetTitle()
}
return _swig_wrap__swig_DirectorManager_upcall_GetTitle(swig_p.SwigcptrManager)
}
func DirectorManagerGetTitle(p Manager) string {
return _swig_wrap__swig_DirectorManager_upcall_GetTitle(p.(*_swig_DirectorManager).SwigcptrManager)
}
func Swig_DirectorManager_callback_getTitle(p *_swig_DirectorManager) (swig_result string) {
return p.GetTitle()
}
type _swig_DirectorInterfaceManagerGetName interface {
GetName() string
}
func _swig_wrap__swig_DirectorManager_upcall_GetName(SwigcptrManager) string
func (swig_p *_swig_DirectorManager) GetName() string {
if swig_g, swig_ok := swig_p.v.(_swig_DirectorInterfaceManagerGetName); swig_ok {
return swig_g.GetName()
}
return _swig_wrap__swig_DirectorManager_upcall_GetName(swig_p.SwigcptrManager)
}
func DirectorManagerGetName(p Manager) string {
return _swig_wrap__swig_DirectorManager_upcall_GetName(p.(*_swig_DirectorManager).SwigcptrManager)
}
func Swig_DirectorManager_callback_getName(p *_swig_DirectorManager) (swig_result string) {
return p.GetName()
}
type _swig_DirectorInterfaceManagerGetPosition interface {
GetPosition() string
}
func _swig_wrap__swig_DirectorManager_upcall_GetPosition(SwigcptrManager) string
func (swig_p *_swig_DirectorManager) GetPosition() string {
if swig_g, swig_ok := swig_p.v.(_swig_DirectorInterfaceManagerGetPosition); swig_ok {
return swig_g.GetPosition()
}
return _swig_wrap__swig_DirectorManager_upcall_GetPosition(swig_p.SwigcptrManager)
}
func DirectorManagerGetPosition(p Manager) string {
return _swig_wrap__swig_DirectorManager_upcall_GetPosition(p.(*_swig_DirectorManager).SwigcptrManager)
}
func Swig_DirectorManager_callback_getPosition(p *_swig_DirectorManager) (swig_result string) {
return p.GetPosition()
}
func _swig_wrap_DeleteDirectorManager(uintptr)
func DeleteDirectorManager(arg1 Manager) {
_swig_wrap_DeleteDirectorManager(arg1.Swigcptr())
}
func Swiggo_DeleteDirector_Manager(p *_swig_DirectorManager) {
p.SwigcptrManager = 0
}
type SwigcptrManager uintptr
func (p SwigcptrManager) Swigcptr() uintptr {
return (uintptr)(p)
}
func (p SwigcptrManager) SwigIsManager() {
}
func (p SwigcptrManager) DirectorInterface() interface{} {
return nil
}
func _swig_wrap_new_Manager(string) SwigcptrManager
func NewManager(arg1 string) Manager {
return _swig_wrap_new_Manager(arg1)
}
func _swig_wrap_Manager_getPosition(SwigcptrManager) string
func (arg1 SwigcptrManager) GetPosition() string {
return _swig_wrap_Manager_getPosition(arg1)
}
func _swig_wrap_delete_Manager(uintptr)
func DeleteManager(arg1 Manager) {
_swig_wrap_delete_Manager(arg1.Swigcptr())
}
func _swig_wrap_Manager_getTitle(SwigcptrManager) string
func (_swig_base SwigcptrManager) GetTitle() string {
return _swig_wrap_Manager_getTitle(_swig_base)
}
func _swig_wrap_Manager_getName(SwigcptrManager) string
func (_swig_base SwigcptrManager) GetName() string {
return _swig_wrap_Manager_getName(_swig_base)
}
func (p SwigcptrManager) SwigIsEmployee() {
}
func (p SwigcptrManager) SwigGetEmployee() Employee {
return SwigcptrEmployee(p.Swigcptr())
}
type Manager interface {
Swigcptr() uintptr
SwigIsManager()
DirectorInterface() interface{}
GetPosition() string
GetTitle() string
GetName() string
SwigIsEmployee()
SwigGetEmployee() Employee
}
type SwigcptrEmployeeList uintptr
func (p SwigcptrEmployeeList) Swigcptr() uintptr {
return (uintptr)(p)
}
func (p SwigcptrEmployeeList) SwigIsEmployeeList() {
}
func _swig_wrap_new_EmployeeList() SwigcptrEmployeeList
func NewEmployeeList() EmployeeList {
return _swig_wrap_new_EmployeeList()
}
func _swig_wrap_EmployeeList_addEmployee(SwigcptrEmployeeList, uintptr)
func (arg1 SwigcptrEmployeeList) AddEmployee(arg2 Employee) {
_swig_wrap_EmployeeList_addEmployee(arg1, arg2.Swigcptr())
}
func _swig_wrap_EmployeeList_get_item(SwigcptrEmployeeList, int) SwigcptrEmployee
func (arg1 SwigcptrEmployeeList) Get_item(arg2 int) Employee {
return _swig_wrap_EmployeeList_get_item(arg1, arg2)
}
func _swig_wrap_delete_EmployeeList(uintptr)
func DeleteEmployeeList(arg1 EmployeeList) {
_swig_wrap_delete_EmployeeList(arg1.Swigcptr())
}
type EmployeeList interface {
Swigcptr() uintptr
SwigIsEmployeeList()
AddEmployee(arg2 Employee)
Get_item(arg2 int) Employee
}
type SwigcptrSwigDirector_Manager uintptr
type SwigDirector_Manager interface {
Swigcptr() uintptr;
}
func (p SwigcptrSwigDirector_Manager) Swigcptr() uintptr {
return uintptr(p)
}
type SwigcptrSwigDirector_Employee uintptr
type SwigDirector_Employee interface {
Swigcptr() uintptr;
}
func (p SwigcptrSwigDirector_Employee) Swigcptr() uintptr {
return uintptr(p)
}
type SwigcptrVoid uintptr
type Void interface {
Swigcptr() uintptr;
}
func (p SwigcptrVoid) Swigcptr() uintptr {
return uintptr(p)
}

56
Examples/go/extend/example.h Normal file
View file

@ -0,0 +1,56 @@
/* File : example.h */
#include <cstdio>
#include <iostream>
#include <vector>
#include <string>
#include <cmath>
class Employee {
private:
std::string name;
public:
Employee(const char* n): name(n) {}
virtual std::string getTitle() { return getPosition() + " " + getName(); }
virtual std::string getName() { return name; }
virtual std::string getPosition() const { return "Employee"; }
virtual ~Employee() { printf("~Employee() @ %p\n", this); }
};
class Manager: public Employee {
public:
Manager(const char* n): Employee(n) {}
virtual std::string getPosition() const { return "Manager"; }
};
class EmployeeList {
std::vector<Employee*> list;
public:
EmployeeList() {
list.push_back(new Employee("Bob"));
list.push_back(new Employee("Jane"));
list.push_back(new Manager("Ted"));
}
void addEmployee(Employee *p) {
list.push_back(p);
std::cout << "New employee added. Current employees are:" << std::endl;
std::vector<Employee*>::iterator i;
for (i=list.begin(); i!=list.end(); i++) {
std::cout << " " << (*i)->getTitle() << std::endl;
}
}
const Employee *get_item(int i) {
return list[i];
}
~EmployeeList() {
std::vector<Employee*>::iterator i;
std::cout << "~EmployeeList, deleting " << list.size() << " employees." << std::endl;
for (i=list.begin(); i!=list.end(); i++) {
delete *i;
}
std::cout << "~EmployeeList empty." << std::endl;
}
};

15
Examples/go/extend/example.i Normal file
View file

@ -0,0 +1,15 @@
/* File : example.i */
%module(directors="1") example
%{
#include "example.h"
%}
%include "std_vector.i"
%include "std_string.i"
/* turn on director wrapping for Manager */
%feature("director") Employee;
%feature("director") Manager;
%include "example.h"

27
Examples/go/extend/index.html Normal file
View file

@ -0,0 +1,27 @@
<html>
<head>
<title>SWIG:Examples:go:extend</title>
</head>
<body bgcolor="#ffffff">
<tt>SWIG/Examples/go/extend/</tt>
<hr>
<H2>Extending a simple C++ class in Go</H2>
<p>
This example illustrates the extending of a C++ class with cross
language polymorphism.
<p>
<ul>
<li><a href="example.h">example.h</a>. Header file containing some enums.
<li><a href="example.i">example.i</a>. Interface file.
<li><a href="runme.go">runme.go</a>. Sample Go program.
</ul>
<hr>
</body>
</html>

77
Examples/go/extend/runme.go Normal file
View file

@ -0,0 +1,77 @@
// This file illustrates the cross language polymorphism using directors.
package main
import (
"fmt"
. "./example"
)
type CEO struct{}
func (p *CEO) GetPosition() string {
return "CEO"
}
func main() {
// Create an instance of CEO, a class derived from the Go
// proxy of the underlying C++ class. The calls to getName()
// and getPosition() are standard, the call to getTitle() uses
// the director wrappers to call CEO.getPosition().
e := NewDirectorManager(new(CEO), "Alice")
fmt.Println(e.GetName(), " is a ", e.GetPosition())
fmt.Println("Just call her \"", e.GetTitle(), "\"")
fmt.Println("----------------------")
// Create a new EmployeeList instance. This class does not
// have a C++ director wrapper, but can be used freely with
// other classes that do.
list := NewEmployeeList()
// EmployeeList owns its items, so we must surrender ownership
// of objects we add.
// e.DisownMemory()
list.AddEmployee(e)
fmt.Println("----------------------")
// Now we access the first four items in list (three are C++
// objects that EmployeeList's constructor adds, the last is
// our CEO). The virtual methods of all these instances are
// treated the same. For items 0, 1, and 2, all methods
// resolve in C++. For item 3, our CEO, GetTitle calls
// GetPosition which resolves in Go. The call to GetPosition
// is slightly different, however, because of the overidden
// GetPosition() call, since now the object reference has been
// "laundered" by passing through EmployeeList as an
// Employee*. Previously, Go resolved the call immediately in
// CEO, but now Go thinks the object is an instance of class
// Employee. So the call passes through the Employee proxy
// class and on to the C wrappers and C++ director, eventually
// ending up back at the Java CEO implementation of
// getPosition(). The call to GetTitle() for item 3 runs the
// C++ Employee::getTitle() method, which in turn calls
// GetPosition(). This virtual method call passes down
// through the C++ director class to the Java implementation
// in CEO. All this routing takes place transparently.
fmt.Println("(position, title) for items 0-3:")
fmt.Println(" ", list.Get_item(0).GetPosition(), ", \"", list.Get_item(0).GetTitle(), "\"")
fmt.Println(" ", list.Get_item(1).GetPosition(), ", \"", list.Get_item(1).GetTitle(), "\"")
fmt.Println(" ", list.Get_item(2).GetPosition(), ", \"", list.Get_item(2).GetTitle(), "\"")
fmt.Println(" ", list.Get_item(3).GetPosition(), ", \"", list.Get_item(3).GetTitle(), "\"")
fmt.Println("----------------------")
// Time to delete the EmployeeList, which will delete all the
// Employee* items it contains. The last item is our CEO,
// which gets destroyed as well.
DeleteEmployeeList(list)
fmt.Println("----------------------")
// All done.
fmt.Println("Go exit")
}

18
Examples/go/funcptr/Makefile Normal file
View file

@ -0,0 +1,18 @@
TOP = ../..
SWIG = $(TOP)/../preinst-swig
SRCS = example.c
TARGET = example
INTERFACE = example.i
SWIGOPT =
all:: go
go::
$(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \
SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' go
clean::
$(MAKE) -f $(TOP)/Makefile go_clean
check: all
$(MAKE) -f $(TOP)/Makefile TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' go_run

19
Examples/go/funcptr/example.c Normal file
View file

@ -0,0 +1,19 @@
/* File : example.c */
int do_op(int a, int b, int (*op)(int,int)) {
return (*op)(a,b);
}
int add(int a, int b) {
return a+b;
}
int sub(int a, int b) {
return a-b;
}
int mul(int a, int b) {
return a*b;
}
int (*funcvar)(int,int) = add;

54
Examples/go/funcptr/example.go Normal file
View file

@ -0,0 +1,54 @@
/* ----------------------------------------------------------------------------
* This file was automatically generated by SWIG (http://www.swig.org).
* Version 2.0.1
*
* This file is not intended to be easily readable and contains a number of
* coding conventions designed to improve portability and efficiency. Do not make
* changes to this file unless you know what you are doing--modify the SWIG
* interface file instead.
* ----------------------------------------------------------------------------- */
package example
type _swig_fnptr *byte
type _swig_memberptr *byte
func _swig_allocatememory(int) *byte
func _swig_internal_allocate(len int) *byte {
return _swig_allocatememory(len)
}
func _swig_allocatestring(*byte, int) string
func _swig_internal_makegostring(p *byte, l int) string {
return _swig_allocatestring(p, l)
}
func _swig_internal_gopanic(p *byte, l int) {
panic(_swig_allocatestring(p, l))
}
func Do_op(int, int, _swig_fnptr) int
func _swig_getADD() _swig_fnptr
var ADD _swig_fnptr = _swig_getADD()
func _swig_getSUB() _swig_fnptr
var SUB _swig_fnptr = _swig_getSUB()
func _swig_getMUL() _swig_fnptr
var MUL _swig_fnptr = _swig_getMUL()
func _swig_wrap_funcvar_set(_swig_fnptr)
func SetFuncvar(arg1 _swig_fnptr) {
_swig_wrap_funcvar_set(arg1)
}
func GetFuncvar() _swig_fnptr
type SwigcptrVoid uintptr
type Void interface {
Swigcptr() uintptr;
}
func (p SwigcptrVoid) Swigcptr() uintptr {
return uintptr(p)
}

9
Examples/go/funcptr/example.h Normal file
View file

@ -0,0 +1,9 @@
/* file: example.h */
extern int do_op(int,int, int (*op)(int,int));
extern int add(int,int);
extern int sub(int,int);
extern int mul(int,int);
extern int (*funcvar)(int,int);

16
Examples/go/funcptr/example.i Normal file
View file

@ -0,0 +1,16 @@
/* File : example.i */
%module example
%{
#include "example.h"
%}
/* Wrap a function taking a pointer to a function */
extern int do_op(int a, int b, int (*op)(int, int));
/* Now install a bunch of "ops" as constants */
%constant int (*ADD)(int,int) = add;
%constant int (*SUB)(int,int) = sub;
%constant int (*MUL)(int,int) = mul;
extern int (*funcvar)(int,int);

89
Examples/go/funcptr/index.html Normal file
View file

@ -0,0 +1,89 @@
<html>
<head>
<title>SWIG:Examples:go:funcptr</title>
</head>
<body bgcolor="#ffffff">
<tt>SWIG/Examples/go/funcptr/</tt>
<hr>
<H2>Pointers to Functions</H2>
<p>
Okay, just what in the heck does SWIG do with a declaration like this?
<blockquote>
<pre>
int do_op(int a, int b, int (*op)(int, int));
</pre>
</blockquote>
Well, it creates a wrapper as usual. Of course, that does raise some
questions about the third argument (the pointer to a function).
<p>
In this case, SWIG will wrap the function pointer as it does for all
other pointers. However, in order to actually call this function from
a Go program, you will need to pass some kind of C function pointer
object. In C, this is easy, you just supply a function name as an
argument like this:
<blockquote>
<pre>
/* Some callback function */
int add(int a, int b) {
return a+b;
}
...
int r = do_op(x,y,add);
</pre>
</blockquote>
To make this work with SWIG, you will need to do a little extra work.
Specifically, you need to create some function pointer objects using
the %constant directive like this:
<blockquote>
<pre>
%constant(int (*)(int,int)) ADD = add;
</pre>
</blockquote>
Now, in a Go program, you would do this:
<blockquote>
<pre>
int r = do_op(x,y, example.ADD)
</pre>
</blockquote>
where <tt>example</tt> is the module name.
<h2>An Example</h2>
Here are some files that illustrate this with a simple example:
<ul>
<li><a href="example.c">example.c</a>
<li><a href="example.h">example.h</a>
<li><a href="example.i">example.i</a> (SWIG interface)
<li><a href="runme.go">runme.go</a> (Sample program)
</ul>
<h2>Notes</h2>
<ul>
<li>The value of a function pointer must correspond to a function
written in C or C++. It is not possible to pass an arbitrary Go
function in as a substitute for a C function pointer.
</ul>
<hr>
</body>
</html>

25
Examples/go/funcptr/runme.go Normal file
View file

@ -0,0 +1,25 @@
package main
import (
"fmt"
. "./example"
)
func main() {
a := 37
b := 42
// Now call our C function with a bunch of callbacks
fmt.Println("Trying some C callback functions")
fmt.Println(" a = ", a)
fmt.Println(" b = ", b)
fmt.Println(" ADD(a,b) = ", Do_op(a, b, ADD))
fmt.Println(" SUB(a,b) = ", Do_op(a, b, SUB))
fmt.Println(" MUL(a,b) = ", Do_op(a, b, MUL))
fmt.Println("Here is what the C callback function classes are called in Go")
fmt.Println(" ADD = ", ADD)
fmt.Println(" SUB = ", SUB)
fmt.Println(" MUL = ", MUL)
}

89
Examples/go/index.html Normal file
View file

@ -0,0 +1,89 @@
<html>
<head>
<title>SWIG:Examples:Go</title>
</head>
<body bgcolor="#ffffff">
<H1>SWIG Go Examples</H1>
<p>
The following examples illustrate the use of SWIG with Go.
<ul>
<li><a href="simple/index.html">simple</a>. A minimal example showing how SWIG can
be used to wrap a C function, a global variable, and a constant.
<li><a href="constants/index.html">constants</a>. This shows how preprocessor macros and
certain C declarations are turned into constants.
<li><a href="variables/index.html">variables</a>. An example showing how to access C global variables from Go.
<li><a href="enum/index.html">enum</a>. Wrapping enumerations.
<li><a href="class/index.html">class</a>. Wrapping a simple C++ class.
<li><a href="reference/index.html">reference</a>. C++ references.
<li><a href="pointer/index.html">pointer</a>. Simple pointer handling.
<li><a href="funcptr/index.html">funcptr</a>. Pointers to functions.
<li><a href="template/index.html">template</a>. C++ templates.
<li><a href="callback/index.html">callback</a>. C++ callbacks using directors.
<li><a href="extend/index.html">extend</a>. Polymorphism using directors.
</ul>
<h2>Compilation Issues</h2>
<ul>
<li>To create a Go extension, SWIG is run with the following options:
<blockquote>
<pre>
% swig -go interface.i
</pre>
</blockquote>
<li>On Unix the compilation of examples is done using the
file <tt>Example/Makefile</tt>. This makefile performs a manual
module compilation which is platform specific. When using
the <tt>6g</tt> or <tt>8g</tt> compiler, the steps look like this
(GNU/Linux):
<blockquote>
<pre>
% swig -go interface.i
% gcc -fpic -c interface_wrap.c
% gcc -shared interface_wrap.o $(OBJS) -o interfacemodule.so
% 6g interface.go
% 6c interface_gc.c
% gopack grc interface.a interface.6 interface_gc.6
% 6l program.6
</pre>
</blockquote>
<li>When using the <tt>gccgo</tt> compiler, the steps look like this:
<blockquote>
<pre>
% swig -go interface.i
% gcc -c interface_wrap.c
% gccgo -c interface.go
% gccgo program.o interface.o interface_wrap.o
</pre>
</blockquote
</ul>
<h2>Compatibility</h2>
The examples have been extensively tested on the following platforms:
<ul>
<li>GNU/Linux
</ul>
All of the examples were last tested with the following configuration
(10 May 2010):
<ul>
<li>Ubuntu Hardy
<li>gcc-4.2.4
</ul>
Your mileage may vary. If you experience a problem, please let us know by
contacting us on the <a href="http://www.swig.org/mail.html">mailing lists</a>.
</body>
</html>

18
Examples/go/multimap/Makefile Normal file
View file

@ -0,0 +1,18 @@
TOP = ../..
SWIG = $(TOP)/../preinst-swig
SRCS = example.c
TARGET = example
INTERFACE = example.i
SWIGOPT =
all:: go
go::
$(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \
SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' go
clean::
$(MAKE) -f $(TOP)/Makefile go_clean
check: all
$(MAKE) -f $(TOP)/Makefile TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' go_run

53
Examples/go/multimap/example.c Normal file
View file

@ -0,0 +1,53 @@
/* File : example.c */
#include <stdio.h>
#include <stdlib.h>
#include <ctype.h>
/* Compute the greatest common divisor of positive integers */
int gcd(int x, int y) {
int g;
g = y;
while (x > 0) {
g = x;
x = y % x;
y = g;
}
return g;
}
int gcdmain(int argc, char *argv[]) {
int x,y;
if (argc != 3) {
printf("usage: gcd x y\n");
return -1;
}
x = atoi(argv[1]);
y = atoi(argv[2]);
printf("gcd(%d,%d) = %d\n", x,y,gcd(x,y));
return 0;
}
int count(char *bytes, int len, char c) {
int i;
int count = 0;
for (i = 0; i < len; i++) {
if (bytes[i] == c) count++;
}
return count;
}
void capitalize(char *str, int len) {
int i;
for (i = 0; i < len; i++) {
str[i] = (char)toupper(str[i]);
}
}
void circle(double x, double y) {
double a = x*x + y*y;
if (a > 1.0) {
printf("Bad points %g, %g\n", x,y);
} else {
printf("Good points %g, %g\n", x,y);
}
}

55
Examples/go/multimap/example.go Normal file
View file

@ -0,0 +1,55 @@
/* ----------------------------------------------------------------------------
* This file was automatically generated by SWIG (http://www.swig.org).
* Version 2.0.1
*
* This file is not intended to be easily readable and contains a number of
* coding conventions designed to improve portability and efficiency. Do not make
* changes to this file unless you know what you are doing--modify the SWIG
* interface file instead.
* ----------------------------------------------------------------------------- */
package example
type _swig_fnptr *byte
type _swig_memberptr *byte
func _swig_allocatememory(int) *byte
func _swig_internal_allocate(len int) *byte {
return _swig_allocatememory(len)
}
func _swig_allocatestring(*byte, int) string
func _swig_internal_makegostring(p *byte, l int) string {
return _swig_allocatestring(p, l)
}
func _swig_internal_gopanic(p *byte, l int) {
panic(_swig_allocatestring(p, l))
}
func Gcd(int, int) int
func Gcdmain([]string) int
func Count(string, byte) int
func _swig_wrap_capitalize([]string)
func Capitalize(arg1 []string) {
_swig_wrap_capitalize(arg1)
}
func _swig_wrap_circle(float64, float64)
func Circle(arg1 float64, arg2 float64) {
_swig_wrap_circle(arg1, arg2)
}
type SwigcptrVoid uintptr
type Void interface {
Swigcptr() uintptr;
}
func (p SwigcptrVoid) Swigcptr() uintptr {
return uintptr(p)
}

110
Examples/go/multimap/example.i Normal file
View file

@ -0,0 +1,110 @@
/* File : example.i */
%module example
%{
extern int gcd(int x, int y);
extern int gcdmain(int argc, char *argv[]);
extern int count(char *bytes, int len, char c);
extern void capitalize (char *str, int len);
extern void circle (double cx, double cy);
extern int squareCubed (int n, int *OUTPUT);
%}
extern int gcd(int x, int y);
%typemap(gotype) (int argc, char *argv[]) "[]string"
%typemap(in) (int argc, char *argv[])
%{
{
int i;
_gostring_* a;
$1 = $input.len;
a = (_gostring_*) $input.array;
$2 = (char **) malloc (($1 + 1) * sizeof (char *));
for (i = 0; i < $1; i++) {
_gostring_ *ps = &a[i];
$2[i] = (char *) ps->p;
}
$2[i] = NULL;
}
%}
%typemap(argout) (int argc, char *argv[]) "" /* override char *[] default */
%typemap(freearg) (int argc, char *argv[])
%{
free($2);
%}
extern int gcdmain(int argc, char *argv[]);
%typemap(gotype) (char *bytes, int len) "string"
%typemap(in) (char *bytes, int len)
%{
$1 = $input.p;
$2 = $input.n;
%}
extern int count(char *bytes, int len, char c);
/* This example shows how to wrap a function that mutates a c string. A one
* element Go string slice is used so that the string can be returned
* modified.
*/
%typemap(gotype) (char *str, int len) "[]string"
%typemap(in) (char *str, int len)
%{
{
_gostring_ *a;
char *p;
int n;
a = (_gostring_*) $input.array;
p = a[0].p;
n = a[0].n;
$1 = malloc(n + 1);
$2 = n;
memcpy($1, p, n);
}
%}
/* Return the mutated string as a modified element in the array. */
%typemap(argout) (char *str, int len)
%{
{
_gostring_ *a;
a = (_gostring_*) $input.array;
a[0] = _swig_makegostring($1, $2);
}
%}
%typemap(freearg) (char *str, int len)
%{
free($1);
%}
extern void capitalize(char *str, int len);
/* A multi-valued constraint. Force two arguments to lie
inside the unit circle */
%typemap(check) (double cx, double cy)
%{
{
double a = $1*$1 + $2*$2;
if (a > 1.0) {
_swig_gopanic("$1_name and $2_name must be in unit circle");
return;
}
}
%}
extern void circle(double cx, double cy);

26
Examples/go/multimap/runme.go Normal file
View file

@ -0,0 +1,26 @@
package main
import (
"fmt"
. "./example"
)
func main() {
// Call our gcd() function
x := 42
y := 105
g := Gcd(x, y)
fmt.Println("The gcd of ", x, " and ", y, " is ", g)
// Call the gcdmain() function
args := []string{"gcdmain", "42", "105"}
Gcdmain(args)
// Call the count function
fmt.Println(Count("Hello World", 'l'))
// Call the capitalize function
capitalizeMe := []string{"hello world"}
Capitalize(capitalizeMe)
fmt.Println(capitalizeMe[0])
}

18
Examples/go/pointer/Makefile Normal file
View file

@ -0,0 +1,18 @@
TOP = ../..
SWIG = $(TOP)/../preinst-swig
SRCS = example.c
TARGET = example
INTERFACE = example.i
SWIGOPT =
all:: go
go::
$(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \
SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' go
clean::
$(MAKE) -f $(TOP)/Makefile go_clean
check: all
$(MAKE) -f $(TOP)/Makefile TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' go_run

16
Examples/go/pointer/example.c Normal file
View file

@ -0,0 +1,16 @@
/* File : example.c */
void add(int *x, int *y, int *result) {
*result = *x + *y;
}
void sub(int *x, int *y, int *result) {
*result = *x - *y;
}
int divide(int n, int d, int *r) {
int q;
q = n/d;
*r = n - q*d;
return q;
}

68
Examples/go/pointer/example.go Normal file
View file

@ -0,0 +1,68 @@
/* ----------------------------------------------------------------------------
* This file was automatically generated by SWIG (http://www.swig.org).
* Version 2.0.1
*
* This file is not intended to be easily readable and contains a number of
* coding conventions designed to improve portability and efficiency. Do not make
* changes to this file unless you know what you are doing--modify the SWIG
* interface file instead.
* ----------------------------------------------------------------------------- */
package example
type _swig_fnptr *byte
type _swig_memberptr *byte
func _swig_allocatememory(int) *byte
func _swig_internal_allocate(len int) *byte {
return _swig_allocatememory(len)
}
func _swig_allocatestring(*byte, int) string
func _swig_internal_makegostring(p *byte, l int) string {
return _swig_allocatestring(p, l)
}
func _swig_internal_gopanic(p *byte, l int) {
panic(_swig_allocatestring(p, l))
}
func _swig_wrap_add(*int, *int, *int)
func Add(arg1 *int, arg2 *int, arg3 *int) {
_swig_wrap_add(arg1, arg2, arg3)
}
func New_intp() *int
func Copy_intp(int) *int
func _swig_wrap_delete_intp(*int)
func Delete_intp(arg1 *int) {
_swig_wrap_delete_intp(arg1)
}
func _swig_wrap_intp_assign(*int, int)
func Intp_assign(arg1 *int, arg2 int) {
_swig_wrap_intp_assign(arg1, arg2)
}
func Intp_value(*int) int
func _swig_wrap_sub(int, int, []int)
func Sub(arg1 int, arg2 int, arg3 []int) {
_swig_wrap_sub(arg1, arg2, arg3)
}
func Divide(int, int, []int) int
type SwigcptrVoid uintptr
type Void interface {
Swigcptr() uintptr;
}
func (p SwigcptrVoid) Swigcptr() uintptr {
return uintptr(p)
}

30
Examples/go/pointer/example.i Normal file
View file

@ -0,0 +1,30 @@
/* File : example.i */
%module example
%{
extern void add(int *, int *, int *);
extern void sub(int *, int *, int *);
extern int divide(int, int, int *);
%}
/* This example illustrates a couple of different techniques
for manipulating C pointers */
/* First we'll use the pointer library */
extern void add(int *x, int *y, int *result);
%include cpointer.i
%pointer_functions(int, intp);
/* Next we'll use some typemaps */
%include typemaps.i
extern void sub(int *INPUT, int *INPUT, int *OUTPUT);
/* Next we'll use typemaps and the %apply directive */
%apply int *OUTPUT { int *r };
extern int divide(int n, int d, int *r);

143
Examples/go/pointer/index.html Normal file
View file

@ -0,0 +1,143 @@
<html>
<head>
<title>SWIG:Examples:go:pointer</title>
</head>
<body bgcolor="#ffffff">
<tt>SWIG/Examples/go/pointer/</tt>
<hr>
<H2>Simple Pointer Handling</H2>
<p>
This example illustrates a couple of techniques for handling simple
pointers in SWIG. The prototypical example is a C function that
operates on pointers such as this:
<blockquote>
<pre>
void add(int *x, int *y, int *r) {
*r = *x + *y;
}
</pre>
</blockquote>
By default, SWIG wraps this function exactly as specified and creates
an interface that expects pointer objects for arguments. This only
works when there is a precise correspondence between the C type and
some Go type.
<p>
<h2>Other approaches</h2>
<p>
<li>The SWIG pointer library provides a different, safer, way to
handle pointers. For example, in the interface file you would do
this:
<blockquote>
<pre>
%include cpointer.i
%pointer_functions(int, intp);
</pre>
</blockquote>
and from Go you would use pointers like this:
<blockquote>
<pre>
a := example.New_intp()
b := example.New_intp()
c := example.New_intp()
Intp_Assign(a, 37)
Intp_Assign(b, 42)
fmt.Println(" a =", a)
fmt.Println(" b =", b)
fmt.Println(" c =", c)
// Call the add() function with some pointers
example.Add(a,b,c)
// Now get the result
res := example.Intp_value(c)
fmt.Println(" 37 + 42 =", res)
// Clean up the pointers
example.Delete_intp(a)
example.Delete_intp(b)
example.Delete_intp(c)
</pre>
</blockquote>
<p>
<li>Use the SWIG typemap library. This library allows you to
completely change the way arguments are processed by SWIG. For
example:
<blockquote>
<pre>
%include "typemaps.i"
void add(int *INPUT, int *INPUT, int *OUTPUT);
</pre>
</blockquote>
And in a Go program:
<blockquote>
<pre>
r := []int{0}
example.Sub(37,42,r)
fmt.Println("Result =", r[0])
</pre>
</blockquote>
Needless to say, this is substantially easier although a bit unusual.
<p>
<li>A final alternative is to use the typemaps library in combination
with the %apply directive. This allows you to change the names of parameters
that behave as input or output parameters. For example:
<blockquote>
<pre>
%include "typemaps.i"
%apply int *INPUT {int *x, int *y};
%apply int *OUTPUT {int *r};
void add(int *x, int *y, int *r);
void sub(int *x, int *y, int *r);
void mul(int *x, int *y, int *r);
... etc ...
</pre>
</blockquote>
</ul>
<h2>Example</h2>
The following example illustrates the use of these features for pointer
extraction.
<ul>
<li> <a href="example.c">example.c</a> (C Source)
<li> <a href="example.i">example.i</a> (SWIG interface)
<li> <a href="runme.go">runme.go</a> (Go program)
</ul>
<h2>Notes</h2>
<ul>
<li>Since pointers are used for so many different things (arrays, output values,
etc...) the complexity of pointer handling can be as complicated as you want to
make it.
<p>
<li>More documentation on the typemaps.i and cpointer.i library files can be
found in the SWIG user manual. The files also contain documentation.
</ul>
<hr>
</body>
</html>

Some files were not shown because too many files have changed in this diff Show more