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

Merge remote-tracking branch 'origin/master' into HEAD

Browse source
This commit is contained in:
Markus Friedrich 2022-01-16 09:57:22 +01:00
commit be0b975e6b
977 changed files with 15369 additions and 35050 deletions
Download patch file Download diff file Expand all files Collapse all files

457
.github/workflows/ci.yml vendored Normal file
View file

@ -0,0 +1,457 @@
name: CI
on:
push:
paths-ignore:
- 'CHANGES*'
- 'Doc/**'
- 'appveyor.yml'
pull_request:
branches: master
paths-ignore:
- 'CHANGES*'
- 'Doc/**'
- 'appveyor.yml'
jobs:
build:
# When continue-on-error is true for an individual build, that build can fail (it'll show red),
# but it won't fail the overall build
continue-on-error: ${{ matrix.continue-on-error || false }}
runs-on: ${{ matrix.os || 'ubuntu-20.04' }}
# By default, the name of the build is the language used and SWIG options, but matrix entries
# can define the additional "desc" field with any additional information to include in the name.
name: ${{ matrix.SWIGLANG || 'none' }}${{ matrix.PY3 }} ${{ matrix.ENGINE}} ${{ matrix.VER }} ${{ matrix.SWIG_FEATURES }} ${{ (matrix.compiler || 'gcc') }}${{ matrix.GCC }} ${{ matrix.CPPSTD }} ${{ matrix.CSTD }} ${{ matrix.desc }} ${{ matrix.continue-on-error && '(can fail)' }}
strategy:
matrix:
include:
- SWIGLANG: ""
- SWIGLANG: ""
GCC: 7
- SWIGLANG: ""
GCC: 8
- SWIGLANG: ""
GCC: 9
- SWIGLANG: ""
GCC: 10
- SWIGLANG: ""
GCC: 11
- SWIGLANG: ""
compiler: clang
- SWIGLANG: csharp
# D support can't be enabled because dmd 2.066 fails to build anything
# under Ubuntu 18.04 due to its standard library (libphobos2.a) not
# being compiled with -FPIC, but system gcc using -fpie by default,
# resulting in linking errors for any output. And later versions, such
# as 2.086.1, are not supported and result in errors in SWIG test suite.
#
# - SWIGLANG: d
# VER: '2.066.0'
# os: ubuntu-18.04 # This dlang version doesn't work under 20.04.
- SWIGLANG: go
VER: '1.6'
CSTD: gnu11
- SWIGLANG: go
VER: '1.8'
- SWIGLANG: go
VER: '1.12'
CSTD: gnu11
- SWIGLANG: go
VER: '1.17'
- SWIGLANG: guile
- SWIGLANG: java
- SWIGLANG: javascript
ENGINE: node
VER: '6'
CPPSTD: c++11
os: ubuntu-18.04
- SWIGLANG: javascript
ENGINE: node
VER: '8'
CPPSTD: c++11
os: ubuntu-18.04
- SWIGLANG: javascript
ENGINE: node
VER: '10'
CPPSTD: c++11
os: ubuntu-18.04
- SWIGLANG: javascript
ENGINE: node
VER: '12'
CPPSTD: c++11
- SWIGLANG: javascript
ENGINE: node
VER: '17'
CPPSTD: c++14
- SWIGLANG: javascript
ENGINE: jsc
- SWIGLANG: lua
- SWIGLANG: lua
VER: '5.3'
- SWIGLANG: octave
CPPSTD: c++11
- SWIGLANG: octave
VER: '6.4'
CPPSTD: c++11
- SWIGLANG: perl5
- SWIGLANG: php
VER: '7.0'
- SWIGLANG: php
VER: '7.1'
- SWIGLANG: php
VER: '7.2'
- SWIGLANG: php
VER: '7.3'
- SWIGLANG: php
VER: '7.4'
- SWIGLANG: php
- SWIGLANG: php
VER: '8.1'
- SWIGLANG: python
- SWIGLANG: python
PY3: 3
VER: '3.2'
os: ubuntu-18.04 # Python < 3.5 not available for 20.04.
- SWIGLANG: python
PY3: 3
VER: '3.3'
os: ubuntu-18.04 # Python < 3.5 not available for 20.04.
- SWIGLANG: python
PY3: 3
VER: '3.4'
os: ubuntu-18.04 # Python < 3.5 not available for 20.04.
- SWIGLANG: python
PY3: 3
VER: '3.5'
- SWIGLANG: python
PY3: 3
VER: '3.6'
- SWIGLANG: python
PY3: 3
VER: '3.7'
- SWIGLANG: python
PY3: 3
VER: '3.8'
- SWIGLANG: python
PY3: 3
VER: '3.9'
- SWIGLANG: python
PY3: 3
VER: '3.10'
- SWIGLANG: python
SWIG_FEATURES: -builtin
- SWIGLANG: python
SWIG_FEATURES: -builtin -O
- SWIGLANG: python
PY3: 3
SWIG_FEATURES: -builtin
- SWIGLANG: python
PY3: 3
SWIG_FEATURES: -builtin -O
- SWIGLANG: r
- SWIGLANG: ruby
VER: '1.9'
os: ubuntu-18.04
- SWIGLANG: ruby
VER: '2.0'
os: ubuntu-18.04
- SWIGLANG: ruby
VER: '2.1'
os: ubuntu-18.04
- SWIGLANG: ruby
VER: '2.2'
os: ubuntu-18.04
- SWIGLANG: ruby
VER: '2.3'
os: ubuntu-18.04
- SWIGLANG: ruby
VER: '2.4'
- SWIGLANG: ruby
VER: '2.5'
- SWIGLANG: ruby
VER: '2.6'
- SWIGLANG: ruby
VER: '2.7'
- SWIGLANG: ruby
VER: '3.0'
CPPSTD: c++11
- SWIGLANG: scilab
os: ubuntu-18.04 # scilab-6.1 in ubuntu-20.04 not yet working
- SWIGLANG: tcl
# c++11 testing
- SWIGLANG: csharp
CPPSTD: c++11
- SWIGLANG: go
VER: '1.17'
CPPSTD: c++11
CSTD: gnu11
- SWIGLANG: guile
CPPSTD: c++11
- SWIGLANG: java
CPPSTD: c++11
- SWIGLANG: javascript
ENGINE: node
VER: '14'
CPPSTD: c++11
- SWIGLANG: lua
CPPSTD: c++11
- SWIGLANG: perl5
CPPSTD: c++11
- SWIGLANG: php
CPPSTD: c++11
CSTD: gnu11
- SWIGLANG: python
CPPSTD: c++11
PY3: 3
- SWIGLANG: r
CPPSTD: c++11
- SWIGLANG: ruby
CPPSTD: c++11
- SWIGLANG: scilab
CPPSTD: c++11
os: ubuntu-18.04 # scilab-6.1 in ubuntu-20.04 not yet working
- SWIGLANG: tcl
CPPSTD: c++11
# c++14 testing
- SWIGLANG: csharp
CPPSTD: c++14
- SWIGLANG: go
VER: '1.17'
CPPSTD: c++14
CSTD: gnu11
- SWIGLANG: guile
CPPSTD: c++14
- SWIGLANG: java
CPPSTD: c++14
- SWIGLANG: javascript
ENGINE: node
VER: '16'
CPPSTD: c++14
- SWIGLANG: lua
CPPSTD: c++14
- SWIGLANG: octave
CPPSTD: c++14
- SWIGLANG: perl5
CPPSTD: c++14
- SWIGLANG: php
CPPSTD: c++14
CSTD: gnu11
- SWIGLANG: python
CPPSTD: c++14
PY3: 3
- SWIGLANG: r
CPPSTD: c++14
- SWIGLANG: ruby
CPPSTD: c++14
- SWIGLANG: scilab
CPPSTD: c++14
os: ubuntu-18.04 # scilab-6.1 in ubuntu-20.04 not yet working
- SWIGLANG: tcl
CPPSTD: c++14
# c++17 testing (using gcc11)
- SWIGLANG: csharp
CPPSTD: c++17
GCC: 11
- SWIGLANG: go
VER: '1.17'
CPPSTD: c++17
GCC: 11
CSTD: gnu17
- SWIGLANG: guile
CPPSTD: c++17
GCC: 11
- SWIGLANG: java
CPPSTD: c++17
GCC: 11
- SWIGLANG: javascript
ENGINE: node
VER: '17'
CPPSTD: c++17
GCC: 11
- SWIGLANG: lua
CPPSTD: c++17
GCC: 11
- SWIGLANG: octave
CPPSTD: c++17
GCC: 11
- SWIGLANG: perl5
CPPSTD: c++17
GCC: 11
- SWIGLANG: php
CPPSTD: c++17
CSTD: gnu17
GCC: 11
- SWIGLANG: python
CPPSTD: c++17
GCC: 11
PY3: 3
- SWIGLANG: r
CPPSTD: c++17
GCC: 11
- SWIGLANG: ruby
CPPSTD: c++17
GCC: 11
- SWIGLANG: scilab
CPPSTD: c++17
GCC: 11
os: ubuntu-18.04 # scilab-6.1 in ubuntu-20.04 not yet working
- SWIGLANG: tcl
CPPSTD: c++17
GCC: 11
# Experimental languages (these are allowed to fail)
- SWIGLANG: mzscheme
continue-on-error: true
- SWIGLANG: ocaml
continue-on-error: true
os: ubuntu-18.04 # ocaml-4.08 in ubuntu-20.04 not yet working
# Run all of them, as opposed to aborting when one fails
fail-fast: false
env:
SWIGLANG: ${{ matrix.SWIGLANG }}
PY3: ${{ matrix.PY3 }}
VER: ${{ matrix.VER }}
ENGINE: ${{ matrix.ENGINE }}
SWIG_FEATURES: ${{ matrix.SWIG_FEATURES }}
GCC: ${{ matrix.GCC }}
CSTD: ${{ matrix.CSTD }}
CPPSTD: ${{ matrix.CPPSTD }}
steps:
- name: Checkout
uses: actions/checkout@v2
with:
submodules: recursive
- name: Install CCache
uses: hendrikmuhs/ccache-action@v1
with:
key: ${{ matrix.os || 'ubuntu-20.04' }}-${{ matrix.compiler || 'gcc' }}${{ matrix.GCC }}
# Uncomment to debug via ssh, see https://github.com/mxschmitt/action-tmate
# - name: Setup tmate session
# uses: mxschmitt/action-tmate@v3
- name: Install Dependencies
run: |
set -x
export PATH="/usr/lib/ccache:/usr/local/opt/ccache/libexec:$PATH"
echo PATH="$PATH" >> $GITHUB_ENV
source $GITHUB_WORKSPACE/Tools/GHA-linux-install.sh
echo WITHLANG="$WITHLANG" >> $GITHUB_ENV
case $(uname) in
Linux)
cpu_count=$(nproc)
;;
Darwin)
cpu_count=$(sysctl -n hw.ncpu)
;;
*)
cpu_count=1
;;
esac
if [[ $cpu_count != 1 ]]; then
echo SWIGJOBS=-j$cpu_count >> $GITHUB_ENV
fi
if test '${{ matrix.compiler }}' = 'clang'; then
CC="clang"
CXX="clang++"
CFLAGS="$CFLAGS -fPIE"
CXXFLAGS="$CXXFLAGS -fPIE"
elif test -n "$GCC"; then
CC="gcc-$GCC"
CXX="g++-$GCC"
else
CC="gcc"
CXX="g++"
fi
export CC CXX
echo CC="$CC" >> $GITHUB_ENV
echo CXX="$CXX" >> $GITHUB_ENV
ls -la $(which $CC) $(which $CXX)
$CC --version
$CXX --version
- name: Configure
run: |
source $GITHUB_WORKSPACE/Tools/CI-linux-environment.sh
set -x
if [[ -z "$CSTD" ]]; then
case "$CPPSTD" in
c++11) export CSTD=c11 ;;
c++14) export CSTD=c11 ;;
c++17) export CSTD=c17 ;;
esac
echo CSTD="$CSTD" >> $GITHUB_ENV
fi
if test -n "$CPPSTD"; then CONFIGOPTS+=(--enable-cpp11-testing "CXXFLAGS=-std=$CPPSTD $CXXFLAGS"); fi
if test -n "$CSTD"; then CONFIGOPTS+=("CFLAGS=-std=$CSTD $CFLAGS"); fi
if test -n "$SWIGLANG"; then CONFIGOPTS+=(--without-alllang --with-$WITHLANG); fi
echo "${CONFIGOPTS[@]}"
./autogen.sh && mkdir -p build/build && cd build/build && ../../configure "${CONFIGOPTS[@]}"
- name: Build
working-directory: build/build
run: |
set -x
make -s $SWIGJOBS
./swig -version && ./swig -pcreversion
- name: Test
working-directory: build/build
run: |
source $GITHUB_WORKSPACE/Tools/CI-linux-environment.sh
set -x
if test -z "$SWIGLANG"; then
make $SWIGJOBS check-ccache
make $SWIGJOBS check-errors-test-suite
else
case "$SWIGLANG" in
javascript)
case "$ENGINE" in
v8 | jsc)
# Running tests using v8 or jsc involves creating a custom
# interpreter in Tools/javascript, which is currently broken
# for parallel builds (we attempt to update this interpreter
# while running, resulting in "Text file busy" error).
unset SWIGJOBS
esac
;;
esac
# Stricter compile flags for examples. Various headers and SWIG generated code prevents full use of -pedantic.
cflags=$($GITHUB_WORKSPACE/Tools/testflags.py --language $SWIGLANG --cflags --std=$CSTD --compiler=$CC) && echo $cflags
cxxflags=$($GITHUB_WORKSPACE/Tools/testflags.py --language $SWIGLANG --cxxflags --std=$CPPSTD --compiler=$CC) && echo $cxxflags
make check-$SWIGLANG-version
make check-$SWIGLANG-enabled
make $SWIGJOBS check-$SWIGLANG-examples CFLAGS="$cflags" CXXFLAGS="$cxxflags"
make $SWIGJOBS check-$SWIGLANG-test-suite CFLAGS="$cflags" CXXFLAGS="$cxxflags"
fi
- name: Install
working-directory: build/build
run: |
set -x
if test -z "$SWIGLANG"; then sudo make install && swig -version && ccache-swig -V; fi
- name: Clean
working-directory: build/build
run: |
set -x
make check-maintainer-clean && ../../configure

9
.gitignore vendored
View file

@ -150,6 +150,8 @@ Examples/guile/*/my-guile
# Java
Examples/test-suite/java/*/
Examples/test-suite/java/expected.txt
Examples/test-suite/java/got.txt
Examples/java/*/*.java
!Examples/java/*/runme.java
Examples/java/doxygen/javadocs
@ -173,6 +175,8 @@ Examples/ocaml/**/swigp4.ml
# Octave
swigexample*.oct
Examples/test-suite/octave/*.oct
Examples/test-suite/octave/octheaders.hpp
Examples/test-suite/octave/octheaders.hpp.gch
# Perl5
Examples/test-suite/perl5/*.pm
@ -180,11 +184,8 @@ Examples/perl5/*/*.pm
# PHP
Examples/test-suite/php/php_*.h
Examples/test-suite/php/*.php
!Examples/test-suite/php/*runme.php
!Examples/test-suite/php/skel.php
Examples/php/*/php_*.h
Examples/php/*/example.php
Examples/php/pragmas/example.php
# Python
# Based on https://github.com/github/gitignore/blob/master/Python.gitignore

504
.travis.yml
View file

@ -1,504 +0,0 @@
language: cpp
matrix:
include:
- compiler: clang
os: linux
env: SWIGLANG=
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=
sudo: required
dist: xenial
- os: linux
env: SWIGLANG= GCC=4.4
sudo: required
dist: xenial
- os: linux
env: SWIGLANG= GCC=4.6
sudo: required
dist: xenial
- os: linux
env: SWIGLANG= GCC=4.7
sudo: required
dist: xenial
- os: linux
env: SWIGLANG= GCC=4.8
sudo: required
dist: xenial
- os: linux
env: SWIGLANG= GCC=4.9
sudo: required
dist: xenial
- os: linux
env: SWIGLANG= GCC=6
sudo: required
dist: xenial
- os: linux
env: SWIGLANG= GCC=7
sudo: required
dist: xenial
- os: linux
env: SWIGLANG= GCC=8
sudo: required
dist: xenial
- os: linux
env: SWIGLANG= GCC=9
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=csharp
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=d
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=go VER=1.3
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=go VER=1.8
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=go VER=1.12
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=guile
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=java
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=javascript ENGINE=node VER=0.10
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=javascript ENGINE=node VER=4 CPP11=1
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=javascript ENGINE=node VER=6 CPP11=1
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=javascript ENGINE=node VER=8 CPP11=1
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=javascript ENGINE=node VER=10 CPP11=1
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=javascript ENGINE=jsc
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=javascript ENGINE=v8
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=lua
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=lua VER=5.3
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=mzscheme
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=ocaml
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=octave SWIGJOBS=-j2
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=perl5
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=php VER=7.0
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=php VER=7.1
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=php VER=7.2
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=php VER=7.3
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python # 2.7
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python PY3=3 VER=3.2
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python PY3=3 VER=3.3
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python PY3=3 VER=3.4
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python PY3=3 VER=3.5
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python PY3=3 VER=3.6
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python PY3=3 VER=3.7
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python SWIG_FEATURES=-builtin
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python SWIG_FEATURES="-builtin -O"
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=python SWIG_FEATURES=-builtin GCC=6 CPP11=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=python SWIG_FEATURES=-builtin GCC=6 CPP11=1 PY3=3 VER=3.7
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python SWIG_FEATURES=-builtin PY3=3 VER=3.4
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python SWIG_FEATURES=-builtin PY3=3 VER=3.5
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python SWIG_FEATURES=-builtin PY3=3 VER=3.7
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python SWIG_FEATURES="-builtin -O" PY3=3 VER=3.7
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python SWIG_FEATURES=-builtin PY3=3 VER=3.7 SWIGOPTPY3=
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python SWIG_FEATURES=-O
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=python SWIG_FEATURES=-O PY3=3 VER=3.7
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=r
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=ruby VER=1.9
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=ruby VER=2.0
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=ruby VER=2.1
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=ruby VER=2.2
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=ruby VER=2.3
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=ruby VER=2.4
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=ruby VER=2.5
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=ruby VER=2.6
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=scilab
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=tcl
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=csharp CPP11=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=go VER=1.6 CPP11=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=java CPP11=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=python CPP11=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=r CPP11=1 # Note: making 'R CMD SHLIB' use a different compiler is non-trivial
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=ruby CPP11=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=tcl CPP11=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=csharp GCC=6 CPP14=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=go VER=1.6 GCC=6 CPP14=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=java GCC=6 CPP14=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=python GCC=6 CPP14=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=ruby GCC=6 CPP14=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=tcl GCC=6 CPP14=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=java GCC=7 CPP14=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=python GCC=7 CPP14=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=csharp GCC=8 CPP17=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=java GCC=8 CPP17=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=python GCC=8 CPP17=1 PY3=3 VER=3.7
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=csharp GCC=9 CPP17=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=java GCC=9 CPP17=1
sudo: required
dist: xenial
- os: linux
env: SWIGLANG=python GCC=9 CPP17=1 PY3=3 VER=3.7
sudo: required
dist: xenial
- compiler: gcc
os: osx
env: SWIGLANG=
- compiler: clang
os: osx
env: SWIGLANG=
- compiler: clang
os: osx
env: SWIGLANG=csharp
- compiler: clang
os: osx
env: SWIGLANG=go
- compiler: clang
os: osx
env: SWIGLANG=guile
- compiler: clang
os: osx
env: SWIGLANG=java
- compiler: clang
os: osx
env: SWIGLANG=lua
- compiler: clang
os: osx
env: SWIGLANG=octave SWIGJOBS=-j2
- compiler: clang
os: osx
env: SWIGLANG=perl5
- compiler: clang
os: osx
env: SWIGLANG=python
- compiler: clang
os: osx
env: SWIGLANG=python PY3=3
- compiler: clang
os: osx
env: SWIGLANG=ruby
- compiler: clang
os: osx
env: SWIGLANG=tcl
- compiler: clang
os: osx
env: SWIGLANG=java CPP17=1
osx_image: xcode10.2
- compiler: clang
os: osx
env: SWIGLANG=python PY3=3 CPP17=1
osx_image: xcode10.2
allow_failures:
# seg fault in director_basic testcase
- compiler: gcc
os: linux
env: SWIGLANG=php VER=7.2
sudo: required
dist: xenial
# Sometimes hits the Travis 50 minute time limit
- compiler: clang
os: osx
env: SWIGLANG=octave SWIGJOBS=-j2
# Experimental languages
- compiler: gcc
os: linux
env: SWIGLANG=mzscheme
sudo: required
dist: xenial
- compiler: gcc
os: linux
env: SWIGLANG=ocaml
sudo: required
dist: xenial
before_install:
- date -u
- uname -a
- if test "$TRAVIS_OS_NAME" = "linux"; then lscpu && cat /proc/cpuinfo | grep "model name" && cat /proc/meminfo | grep MemTotal; fi
- if test "$TRAVIS_OS_NAME" = "osx"; then sysctl -a | grep brand_string; fi
# Travis overrides CC environment with compiler predefined values
- if test -n "$GCC"; then export CC="gcc-$GCC" && export CXX="g++-$GCC"; fi
install:
- if test "$TRAVIS_OS_NAME" = "linux"; then source Tools/travis-linux-install.sh; fi
- if test "$TRAVIS_OS_NAME" = "osx"; then source Tools/travis-osx-install.sh; fi
- ls -la $(which $CC) $(which $CXX) && $CC --version && $CXX --version
script:
- echo 'Configuring...' && echo -en 'travis_fold:start:script.1\\r'
- if test -n "$CPP11"; then CONFIGOPTS+=(--enable-cpp11-testing --without-maximum-compile-warnings "CXXFLAGS=-std=c++11 -Wall -Wextra" "CFLAGS=-std=c11 -Wall -Wextra") && export CSTD=c11 && export CPPSTD=c++11; fi
- if test -n "$CPP14"; then CONFIGOPTS+=(--enable-cpp11-testing --without-maximum-compile-warnings "CXXFLAGS=-std=c++14 -Wall -Wextra" "CFLAGS=-std=c11 -Wall -Wextra") && export CSTD=c11 && export CPPSTD=c++14; fi
- if test -n "$CPP17"; then CONFIGOPTS+=(--enable-cpp11-testing --without-maximum-compile-warnings "CXXFLAGS=-std=c++17 -Wall -Wextra" "CFLAGS=-std=c17 -Wall -Wextra") && export CSTD=c17 && export CPPSTD=c++17; fi
- if test -n "$SWIGLANG"; then CONFIGOPTS+=(--without-alllang --with-$WITHLANG); fi
- echo "${CONFIGOPTS[@]}"
- ./autogen.sh && mkdir -p build/build && cd build/build && ../../configure "${CONFIGOPTS[@]}"
- echo -en 'travis_fold:end:script.1\\r'
- make -s $SWIGJOBS
- ./swig -version && ./swig -pcreversion
- if test -z "$SWIGLANG"; then make -s $SWIGJOBS check-ccache; fi
- if test -z "$SWIGLANG"; then make -s $SWIGJOBS check-errors-test-suite; fi
- echo 'Installing...' && echo -en 'travis_fold:start:script.2\\r'
- if test -z "$SWIGLANG"; then sudo make -s install && swig -version && ccache-swig -V; fi
- echo -en 'travis_fold:end:script.2\\r'
# Stricter compile flags for examples. Various headers and SWIG generated code prevents full use of -pedantic.
- if test -n "$SWIGLANG"; then cflags=$($TRAVIS_BUILD_DIR/Tools/testflags.py --language $SWIGLANG --cflags --std=$CSTD --compiler=$CC) && echo $cflags; fi
- if test -n "$SWIGLANG"; then cxxflags=$($TRAVIS_BUILD_DIR/Tools/testflags.py --language $SWIGLANG --cxxflags --std=$CPPSTD --compiler=$CC) && echo $cxxflags; fi
- if test -n "$SWIGLANG"; then make -s check-$SWIGLANG-version; fi
- if test -n "$SWIGLANG"; then make check-$SWIGLANG-enabled; fi
- if test -n "$SWIGLANG"; then make $SWIGJOBS check-$SWIGLANG-examples CFLAGS="$cflags" CXXFLAGS="$cxxflags"; fi
- if test -n "$SWIGLANG"; then make $SWIGJOBS check-$SWIGLANG-test-suite CFLAGS="$cflags" CXXFLAGS="$cxxflags"; fi
- echo 'Cleaning...' && echo -en 'travis_fold:start:script.3\\r'
- make check-maintainer-clean && ../../configure $CONFIGOPTS
- echo -en 'travis_fold:end:script.3\\r'

8
ANNOUNCE
View file

@ -1,8 +1,8 @@
*** ANNOUNCE: SWIG 4.0.2 (in progress) ***
*** ANNOUNCE: SWIG 4.1.0 (in progress) ***
http://www.swig.org
We're pleased to announce SWIG-4.0.2, the latest SWIG release.
We're pleased to announce SWIG-4.1.0, the latest SWIG release.
What is SWIG?
=============
@ -25,11 +25,11 @@ Availability
============
The release is available for download on Sourceforge at
http://prdownloads.sourceforge.net/swig/swig-4.0.2.tar.gz
http://prdownloads.sourceforge.net/swig/swig-4.1.0.tar.gz
A Windows version is also available at
http://prdownloads.sourceforge.net/swig/swigwin-4.0.2.zip
http://prdownloads.sourceforge.net/swig/swigwin-4.1.0.zip
Please report problems with this release to the swig-devel mailing list,
details at http://www.swig.org/mail.html.

2
CCache/README.swig
View file

@ -2,7 +2,7 @@ This directory contains a version of ccache. The initial version was based on cc
debian patches 01-02, 04-14, see the debian/patches subdirectory. The ccache-win32-2.4 modifications
to ccache-2.4 have also been merged in.
Changes have been made to support cacheing the output from SWIG. The ability to cache c/c++ compiler
Changes have been made to support caching the output from SWIG. The ability to cache c/c++ compiler
output has been retained.
Additional features added are the CCACHE_VERBOSE and CCACHE_SWIG environment variables, see docs.

20
CCache/configure.ac
View file

@ -1,12 +1,12 @@
dnl Process this file with autoconf to produce a configure script.
AC_INIT([ccache-swig], [0.0]) # Get version from SWIG in ccache_swig_config.h.in
AC_PREREQ(2.52)
AC_INIT([ccache-swig],[0.0]) # Get version from SWIG in ccache_swig_config.h.in
AC_PREREQ([2.60])
AC_CONFIG_SRCDIR([ccache.h])
AC_MSG_NOTICE([Configuring ccache])
AC_CONFIG_HEADER(config.h)
AC_CONFIG_HEADERS([config.h])
AC_CONFIG_FILES([config_win32.h])
dnl Checks for programs.
@ -41,7 +41,7 @@ else
fi
AC_HEADER_DIRENT
AC_HEADER_TIME
AC_HEADER_SYS_WAIT
AC_CHECK_HEADERS(ctype.h strings.h stdlib.h string.h pwd.h sys/time.h)
@ -51,19 +51,16 @@ AC_CHECK_FUNCS(gethostname getpwuid)
AC_CHECK_FUNCS(utimes)
AC_CACHE_CHECK([for compar_fn_t in stdlib.h],ccache_cv_COMPAR_FN_T, [
AC_TRY_COMPILE(
[#include <stdlib.h>],
[
AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <stdlib.h>]], [[
void test_fn(void) { qsort(NULL, 0, 0, (__compar_fn_t)NULL); }
],
ccache_cv_COMPAR_FN_T=yes,ccache_cv_COMPAR_FN_T=no)])
]])],[ccache_cv_COMPAR_FN_T=yes],[ccache_cv_COMPAR_FN_T=no])])
if test x"$ccache_cv_COMPAR_FN_T" = x"yes"; then
AC_DEFINE(HAVE_COMPAR_FN_T, 1, [ ])
fi
dnl Note: This could be replaced by AC_FUNC_SNPRINTF() in the autoconf macro archive
AC_CACHE_CHECK([for C99 vsnprintf],ccache_cv_HAVE_C99_VSNPRINTF,[
AC_TRY_RUN([
AC_RUN_IFELSE([AC_LANG_SOURCE([[
#include <sys/types.h>
#include <stdarg.h>
void foo(const char *format, ...) {
@ -81,8 +78,7 @@ void foo(const char *format, ...) {
exit(0);
}
main() { foo("hello"); }
],
ccache_cv_HAVE_C99_VSNPRINTF=yes,ccache_cv_HAVE_C99_VSNPRINTF=no,ccache_cv_HAVE_C99_VSNPRINTF=cross)])
]])],[ccache_cv_HAVE_C99_VSNPRINTF=yes],[ccache_cv_HAVE_C99_VSNPRINTF=no],[ccache_cv_HAVE_C99_VSNPRINTF=cross])])
if test x"$ccache_cv_HAVE_C99_VSNPRINTF" = x"yes"; then
AC_DEFINE(HAVE_C99_VSNPRINTF, 1, [ ])
fi

2
CCache/execute.c
View file

@ -137,7 +137,7 @@ int execute(char **argv,
_dup2(fd, 2);
_close(fd);
/* Spawn process (_exec* familly doesn't return) */
/* Spawn process (_exec* family doesn't return) */
status = _spawnv(_P_WAIT, argv[0], (const char **)argv);
/* Restore descriptors */

4
CCache/snprintf.c
View file

@ -16,7 +16,7 @@
* for string length. This covers a nasty loophole.
*
* The other functions are there to prevent NULL pointers from
* causing nast effects.
* causing nasty effects.
*
* More Recently:
* Brandon Long <blong@fiction.net> 9/15/96 for mutt 0.43
@ -30,7 +30,7 @@
* probably requires libm on most operating systems. Don't yet
* support the exponent (e,E) and sigfig (g,G). Also, fmtint()
* was pretty badly broken, it just wasn't being exercised in ways
* which showed it, so that's been fixed. Also, formated the code
* which showed it, so that's been fixed. Also, formatted the code
* to mutt conventions, and removed dead code left over from the
* original. Also, there is now a builtin-test, just compile with:
* gcc -DTEST_SNPRINTF -o snprintf snprintf.c -lm

2
CCache/web/index.html
View file

@ -34,7 +34,7 @@ on the new options.<p>
You can get this release from the <a href="http://ccache.samba.org/ftp/ccache/">download directory</a>
<p>NOTE! This release changes the hash input slighly, so you will
<p>NOTE! This release changes the hash input slightly, so you will
probably find that you will not get any hits against your existing
cache when you upgrade.

145
CHANGES
View file

@ -5,6 +5,151 @@ See the RELEASENOTES file for a summary of changes in each release.
Issue # numbers mentioned below can be found on Github. For more details, add
the issue number to the end of the URL: https://github.com/swig/swig/issues/
Version 4.0.2 (8 Jun 2020)
==========================
2020-06-07 vigsterkr
[Ruby] #1717 Nil fix mangling strings
2020-06-07 vadz
#1748 Fix doxygen comments quoting issue
2020-06-07 munoah
#1800 Escape spaces in file paths for dependencies (-M -MM etc)
2020-06-06 andreas-schwab
[Ruby] #1801 Fix encoding on big endian systems when wrapping std::wstring.
2020-05-31 kwwette
[Octave] #1789 error handling improvements and return error code on exit for SWIG wrapped modules.
2020-05-30 msteinbeck
[D] #1593 Replace broken imports when using newer versions of D.
2020-05-29: ZackerySpytz
[Python] #1716 Performance improvements converting strings when using Python >= 3.3.
2020-05-28: ZackerySpytz
#1776 Quite dramatically decrease run times when generating very large interface files by changing
some internal memory pool sizes.
2020-05-28: mcfarljm
#1788 Fix handling of Doxygen \endlink command.
2020-05-24: vapier
[Javascript] #1796 Fix pkg-config invocation in configure.
2020-04-30: kwwette
[Octave] Fix exception raising for newer Octave versions
Since (at least) Octave 5.1.0, the Octave error() function now raises a C++ exception,
which if uncaught immediately exits a SWIG wrapper function, bypassing any cleanup code
that may appear after a "fail:" label. This patch adds a "try { ... } catch(...) { }"
block around the contents of SWIG wrapper functions to first execute the cleanup code
before rethrowing any exception raised. It is backward compatible with earlier versions
of Octave where error() does not raise an exception, which will still branch to the
"fail:" block to execute cleanup code if an error is encountered.
Note that the new "try { ... } catch(...) { }" block will localise any local variables
used in typemaps that were NOT declared through SWIG's %typemap(...) syntax, so it's
possible this could break existing SWIG wrappers which were implicitly sharing local
variables between typemaps. This can be fixed, however, by declaring local variables
which need to be shared between typemaps through SWIG's %typemap(...) syntax.
2020-02-18: ryannevell
[Lua] #1728 Add support for LUA lightuserdata to SWIG_Lua_ConvertPtr.
2020-02-18: dmach
[Ruby] #1725 Fix gcc -Wcatch-value warnings.
2020-02-14: treitmayr
#1724 Fix wrapping of abstract user-defined conversion operators.
2020-02-13: ddurham2
[Python] #1512 Fix memleak when using STL containers of shared_ptr objects.
2020-02-06: wsfulton
[Python] #1673 #1674 Fix setting 'this' when extending a proxy class with __slots__.
2020-01-31: vadz
[Ruby] #1651 Add std::auto_ptr<> typemaps.
2020-01-31: ZackerySpytz
[Python] #1700 More robust error checking for failures in calls to Python C API:
PyBytes_AsStringAndSize() and PyString_AsStringAndSize().
2020-01-31: vadz
[Python] #1710 Fix crash parsing empty docstrings.
2020-01-30: Alzathar
[R] #910 #914 Fix R memory leak on exception.
2020-01-30: richardbeare
[R] #1511 Fix bug wrapping functions. These were previously incorrectly wrapped as if
they were variables. This happened when 'get' or 'set' was in the name of the function
or method, but sometimes also in some other circumstances. If you were using R
attribute syntax to access these methods, you'll need to switch to calling them as R
methods.
*** POTENTIAL INCOMPATIBILITY ***
2020-01-24: etse-dignitas, wsfulton
[C#, D, Java] #1533 Fix upcasting for shared_ptr's of templated types.
2020-01-16: mcfarljm
#1643 #1654 When using -doxygen, fix segfault when nameless parameters or vararg parameters
are used.
2020-01-16: mcfarljm
#1632 #1659 Fix newline handling for doxygen "///" comments.
2020-01-14: mcfarljm
#1647 #1656 Fix crash handling empty doxygen comments.
2020-01-14: mcfarljm
#1608 Improve doxygen support.
- Add support for \param[] commands such as: \param[in].
- Optional arguments are marked as 'optional' in pydoc.
- Improve support for \code commands so that other languages are supported as code blocks.
Support added for java, c and py. For example Python: \code{.py} ... \endcode
- Fix doxygen handling of \em and \p tags for Python.
2020-01-13: wsfulton
[Python] #1595 Python -builtin constructors silently ignored keyword arguments.
Instead of silenty ignoring them, now a "TypeError: f() takes no keyword arguments"
exception is thrown if keyword arguments are used. Hence constructors and normal methods/
functions behave in the same way. Note, -keyword should be used with -builtin to obtain
keyword argument support.
2020-01-05: jschueller shadchin
[Python] #1670 #1696 Add missing field initializers introduced in python 3.8:
tp_vectorcall and tp_print.
2020-01-05: friedrichatgc
[Octave] #1688 Change swig_this() to use size_t instead of long for compatibility
with Windows 64 bit.
2020-01-05: treitmayr
[Ruby] #1692 #1689 Add support for Ruby 2.7
2019-12-30: treitmayr
[Ruby] #1653 #1668 Fix code generated when using -globalmodule option.
2019-12-29: ZackerySpytz
[OCaml] #1686 Fix compilation errors with OCaml 4.09.0.
2019-12-10: wsfulton
#1679 Fix parsing of C++11 identifiers with special meaning (final and override) when
they are used as part of the scope name of an identifier, such as a namespace name.
2019-11-26: wsfulton
[C#] #1628 'out' or 'ref' used in a cstype typemap was not always stripped out in parts
of director code generation.
2019-11-01: wsfulton
[Python] #1595 Fix bug in support for keyword arguments (kwargs feature or -keyword)
when using -builtin. The fix is in the argument error checking when wrapping zero
argument constructors only.
Version 4.0.1 (21 Aug 2019)
===========================

323
CHANGES.current
View file

@ -4,18 +4,319 @@ See the RELEASENOTES file for a summary of changes in each release.
Issue # numbers mentioned below can be found on Github. For more details, add
the issue number to the end of the URL: https://github.com/swig/swig/issues/
Version 4.0.2 (in progress)
Version 4.1.0 (in progress)
===========================
2019-12-10: wsfulton
#1679 Fix parsing of C++11 identifiers with special meaning (final and override) when
they are used as part of the scope name of an identifier, such as a namespace name.
2022-01-14: wsfulton
[Python] Fix %callback and specifying the callback function as a
static member function using Python staticmethod syntax, such as
Klass.memberfunction instead of Klass_memberfunction when using
-builtin and -fastproxy.
2019-11-26: wsfulton
[C#] #1628 'out' or 'ref' used in a cstype typemap was not always stripped out in parts
of director code generation.
2022-01-11: wsfulton
[Python] Accept keyword arguments accessing static member functions when
using -builtin and kwargs feature and Python class staticmethod syntax.
The missing keyword argument support was only when using the
class staticmethod syntax, such as Klass.memberfunction, and not when
using the flat static method syntax, such as Klass_memberfunction.
2019-11-01: wsfulton
[Python] #1595 Fix bug in support for keyword arguments (kwargs feature or -keyword)
when using -builtin. The fix is in the argument error checking when wrapping zero
argument constructors only.
2022-01-04: juierror
[Go] #2045 Add support for std::array in std_array.i.
2021-12-18: olly
[PHP] Add PHP keyword 'readonly' (added in 8.1) to the list SWIG
knows to automatically rename. This keyword is special in that PHP
allows it to be used as a function (or method) name.
2021-12-07: vstinner
[Python] #2116 Python 3.11 support: use Py_SET_TYPE()
2021-12-05: rwf1
[Octave] #2020 #1893 Add support for Octave 6 up to and including 6.4.
Also add support for compiling with -Bsymbolic which is used by default
by mkoctfile.
2021-12-02: jsenn
[Python] #2102 Fixed crashes when using embedded Python interpreters.
2021-11-12: wsfulton
[Javascript] v8 and node only. Fix mismatched new char[] and free()
when wrapping C code char arrays. Now calloc is now used instead of
new char[] in SWIG_AsCharPtrAndSize.
2021-10-03: ajrh1
[Perl] #2074: Avoid -Wmisleading-indentation in generated code
when using gcc11.
2021-10-03: jschueller
[CMake] #2065: Add option to enable or disable PCRE support.
2021-09-16: ianlancetaylor
[Go] Improved _cgo_panic implementation.
2021-09-16: ianlancetaylor
[Go] Don't use crosscall2 for panicking. Instead rely on documented
and exported interfaces.
2021-09-14: ianlancetaylor
[Go] Remove -no-cgo option (long unsupported in Go)
2021-05-04: olly
[PHP] #2014 Throw PHP exceptions instead of using PHP errors
PHP exceptions can be caught and handled if desired, but if they
aren't caught then PHP exits in much the same way as it does for a
PHP error.
In particular this means parameter type errors and some other cases
in SWIG-generated wrappers now throw a PHP exception, which matches
how PHP's native parameter handling deals with similar situations.
`SWIG_ErrorCode()`, `SWIG_ErrorMsg()`, `SWIG_FAIL()` and `goto thrown;`
are no longer supported (these are really all internal implementation
details and none are documented aside from brief mentions in CHANGES
for the first three). I wasn't able to find any uses in user interface
files at least in FOSS code via code search tools.
If you are using these:
Use `SWIG_PHP_Error(code,msg);` instead of `SWIG_ErrorCode(code);
SWIG_ErrorMsg(msg);` (which will throw a PHP exception in SWIG >= 4.1
and do the same as the individual calls in older SWIG).
`SWIG_FAIL();` and `goto thrown;` can typically be replaced with
`SWIG_fail;`. This will probably also work with older SWIG, but
please test with your wrappers if this is important to you.
*** POTENTIAL INCOMPATIBILITY ***
2021-05-17: adr26
[Python] #1985 Fix memory leaks:
1. Python object references were being incorrectly retained by
SwigPyClientData, causing swig_varlink_dealloc() never to run / free
memory. SwigPyClientData_New() / SwigPyClientData_Del() were updated
to fix the object reference counting, causing swig_varlink_dealloc()
to run and the memory swig_varlink owns to be freed.
2. SwigPyClientData itself was not freed by SwigPyClientData_Del(),
causing another heap leak. The required free() was added to
SwigPyClientData_Del()
3. Fix reference counting/leak of python cached type query
4. Fix reference counting/leak of SwigPyObject dict (-builtin)
5. Python object reference counting fixes for out-of-memory
scenarios were added to: SWIG_Python_RaiseOrModifyTypeError(),
SWIG_Python_AppendOutput(), SwigPyClientData_New(),
SwigPyObject_get___dict__() and SwigPyObject_format()
6. Add error handling for PyModule_AddObject() to
SWIG_Python_SetModule() (failure could be caused by OOM or a name
clash caused by malicious code)
2021-05-13: olly
[UFFI] #2009 Remove code for Common Lisp UFFI. We dropped support
for it in SWIG 4.0.0 and nobody has stepped forward to revive it in
over 2 years.
2021-05-13: olly
[S-EXP] #2009 Remove code for Common Lisp S-Exp. We dropped
support for it in SWIG 4.0.0 and nobody has stepped forward to
revive it in over 2 years.
2021-05-13: olly
[Pike] #2009 Remove code for Pike. We dropped support for it in
SWIG 4.0.0 and nobody has stepped forward to revive it in over 2
years.
2021-05-13: olly
[Modula3] #2009 Remove code for Modula3. We dropped support for it
in SWIG 4.0.0 and nobody has stepped forward to revive it in over 2
years.
2021-05-13: olly
[CLISP] #2009 Remove code for GNU Common Lisp. We dropped support
for it in SWIG 4.0.0 and nobody has stepped forward to revive it in
over 2 years.
2021-05-13: olly
[Chicken] #2009 Remove code for Chicken. We dropped support for it
in SWIG 4.0.0 and nobody has stepped forward to revive it in over 2
years.
2021-05-13: olly
[Allegrocl] #2009 Remove code for Allegro Common Lisp. We dropped
support for it in SWIG 4.0.0 and nobody has stepped forward to
revive it in over 2 years.
2021-05-04: olly
[PHP] #1982 #1457 https://sourceforge.net/p/swig/bugs/1339/
SWIG now only use PHP's C API to implement its wrappers, and no
longer generates PHP code to define classes. The wrappers should
be almost entirely compatible with those generated before, but
faster and without some previously hard-to-fix bugs.
The main notable difference is SWIG no longer generates a .php
wrapper at all by default (only if %pragma(php) code=... or
%pragma(php) include=... are specified in the interface file).
This also means you need to load the module via extension=...
in php.ini, rather than letting the dl() in the generated
.php wrapper load it (but dl() has only worked for command-line
PHP for some years now).
*** POTENTIAL INCOMPATIBILITY ***
2021-04-30: olly
#1984 Remove support for $source and $target.
These were officially deprecated in 2001, and attempts to use them have
resulted in a warning (including a pointer to what to update them to)
for most if not all of that time.
2021-04-27: wsfulton
#1987 [Java] Fix %interface family of macros for returning by const
pointer reference.
2021-04-19: olly
Fix use of uninitialised variable in the generated code for an
empty typecheck typemap, such as the dummy one we include for
std::initializer_list.
2021-04-12: olly
#1777 [Python] Specifying -py3 now generates a check for Python
version >= 3.0.
2021-03-26: olly
[PHP] Add PHP keywords 'fn' (added in 7.4) and 'match' (added in
8.0) to the list SWIG knows to automatically rename.
2021-03-23: wsfulton
#1942 [Python] Fix compilation error in wrappers when using -builtin
and wrapping varargs in constructors.
2021-03-22: goto40
#1977 Fix handling of template template parameters.
2021-03-21: olly
#1929, #1978 [PHP] Add support for PHP 8.
2021-03-19: wsfulton
#1610 Remove -ansi from default compilation flags.
2021-03-19: dot-asm
#1934 [Java] Clean up typemaps for long long arrays.
2021-03-19: olly
#1527 [PHP] Improve PHP object creation in directorin case.
Reportedly the code we were using in this case gave segfaults in
PHP 7.2 and later - we've been unable to reproduce these, but the
new approach is also simpler and should be bit faster too.
2021-03-18: olly
#1655 [PHP] Fix char* typecheck typemap to accept PHP Null like the
corresponding in typemap does.
2021-03-18: olly
#1900, #1905 [PHP] Fix wrapping of overloaded directed methods with
non-void return.
2021-03-11: murillo128
#1498 [Javascript] Support type conversion.
2021-03-06: nshmyrev
#872 [Javascript] Various typemap issues in arrays_javascript.i fixed.
2021-03-03: vaughamhong
#577 [Javascript] Implemented SetModule/GetModule for JSC to allow type sharing
across modules.
2021-03-01: xantares, Oliver Buchtala, geographika
#1040 Add support for building SWIG with CMake. See documentation in Windows.html.
2021-03-01: vadz
#1952 Fix incorrect warning "Unknown Doxygen command: ."
2021-02-28: p2k
#969 [Javascript] v8/node - prevent crash calling a constructor without new keyword.
2021-02-28: alecmev
#405 #1121 [Javascript] Fix OUTPUT typemaps on methods that don't return void.
The output value is appended to the return value.
2021-02-26: murillo128, wsfulton
#1269 [Javascript] Fix handling of large positive unsigned long and
unsigned long long values.
2021-02-24: tomleavy, yegorich, tungntpham
#1746 [Javascript] Add support for Node v12, v14 and v16.
SWIG support for Node is now for v6 and later only.
2020-02-09: ZackerySpytz
#1872 Fix typos in attribute2ref macros.
2020-10-10: wsfulton
[Javascript] Fix so that ccomplex.i interface to file can be used.
2020-10-10: wsfulton
#252 complex can now be used as a C identifier and doesn't give a syntax error.
2020-10-10: lpsinger
#1770 Correct C complex support.
_Complex is now parsed as a keyword rather than complex as per the C99 standard.
The complex macro is available in the ccomplex.i library file along with other
complex number handling provided by the complex.h header.
2020-10-07: ZackerySpytz
[Python] #1812 Fix the error handling for the PyObject_GetBuffer() calls in
pybuffer.i.
2020-10-07: treitmayr
#1824 Add missing space in director method declaration returning
const pointer.
2020-10-07: adelva1984
#1859 Remove all (two) exceptions from SWIG executable.
2020-09-25: wsfulton
[C#, Java] #1874 Add ability to change the modifiers for the interface
generated when using the %interface macros.
For C# use the 'csinterfacemodifiers' typemap.
For Java use the 'javainterfacemodifiers' typemap.
For example:
%typemap(csinterfacemodifiers) X "internal interface"
2020-09-24: geefr
[C#] #1868 Fix wchar_t* csvarout typemap for member variable wrappers.
2020-08-28: wsfulton
[Java] #1862 Fix crashes in swig_connect_director during director class construction
when using the director class from multiple threads - a race condition initialising
block scope static variables. The fix is guaranteed when using C++11, but most
compilers also fix it when using C++03/C++98.
2020-08-16: wsfulton
[Python] Add missing initializer for member ‘_heaptypeobject::ht_module’ when using
-builtin to complete Python 3.9 support.
2020-08-16: wsfulton
[Python] Remove PyEval_InitThreads() call for Python 3.7 and later as Python calls
it automatically now. This removes a deprecation warning when using Python 3.9.
2020-08-15: wsfulton
[Python] All Python examples and tests are written to be Python 2 and Python 3
compatible, removing the need for 2to3 to run the examples or test-suite.
2020-08-13: wsfulton
[C#] Add support for void *VOID_INT_PTR for member variables.
2020-07-29: chrisburr
#1843 [Python] Compilation error fix in SwigPyBuiltin_SetMetaType when using PyPy.
2020-06-14: ZackerySpytz
#1642 #1809 Fix virtual comparison operators in director classes - remove incorrect
space in the function name, for example, operator= = is now operator==.

166
CMakeLists.txt Normal file
View file

@ -0,0 +1,166 @@
cmake_minimum_required (VERSION 3.2)
if (NOT DEFINED CMAKE_BUILD_TYPE)
set (CMAKE_BUILD_TYPE Release CACHE STRING "Build type")
endif ()
project (swig)
if (POLICY CMP0074)
cmake_policy (SET CMP0074 NEW)
endif()
file (STRINGS configure.ac line LIMIT_COUNT 1 REGEX "AC_INIT\\(.*\\)" )
if (line MATCHES "AC_INIT\\(\\[(.*)\\],[ \t]*\\[(.*)\\],[ \t]*\\[(.*)\\]\\)" )
set (SWIG_VERSION ${CMAKE_MATCH_2})
set (PACKAGE_BUGREPORT ${CMAKE_MATCH_3})
else ()
message (SEND_ERROR "Could not parse version from configure.ac")
endif ()
set (SWIG_ROOT ${PROJECT_SOURCE_DIR})
set (SWIG_LIB share/swig/${SWIG_VERSION})
# Project wide configuration variables
# ------------------------------------
set (SWIG_SOURCE_DIR ${SWIG_ROOT}/Source CACHE INTERNAL "Path of swig sources" FORCE)
set (PACKAGE_NAME swig)
set (PACKAGE_VERSION ${SWIG_VERSION})
# Configure
# ---------
list (APPEND CMAKE_MODULE_PATH ${SWIG_ROOT}/Tools/cmake)
include (CheckIncludeFiles)
include (CheckIncludeFile)
include (CheckIncludeFileCXX)
include (CheckTypeSize)
include (CheckSymbolExists)
include (CheckFunctionExists)
include (CheckLibraryExists)
include (CheckCSourceCompiles)
# HACK: didn't get the bool check working for Visual Studio 2008
if (MSVC)
set(HAVE_BOOL 1)
else()
set (CMAKE_EXTRA_INCLUDE_FILES stdbool.h)
check_type_size ("bool" HAVE_BOOL)
set (CMAKE_EXTRA_INCLUDE_FILES)
endif()
check_include_file ("inttypes.h" HAVE_INTTYPES_H)
check_include_file ("stddef.h" HAVE_STDDEF_H)
check_include_file ("stdint.h" HAVE_STDINT_H)
check_include_file ("stdio.h" HAVE_STDIO_H)
check_include_file ("stdlib.h" HAVE_STDLIB_H)
check_include_file ("string.h" HAVE_STRING_H)
check_include_file ("strings.h" HAVE_STRINGS_H)
check_include_file ("sys/stat.h" HAVE_SYS_STAT_H)
check_include_file ("sys/types.h" HAVE_SYS_TYPES_H)
check_include_file ("unistd.h" HAVE_UNISTD_H)
check_include_files ("stdlib.h;stdarg.h;string.h;float.h" STDC_HEADERS)
check_include_file_cxx ("boost/shared_ptr.hpp" HAVE_BOOST)
check_library_exists (dl dlopen "" HAVE_LIBDL)
check_function_exists (popen HAVE_POPEN)
if (MSVC)
set (CMAKE_CXX_FLAGS "/EHsc ${CMAKE_CXX_FLAGS}")
endif ()
option (WITH_PCRE "Enable pcre" ON)
if (WITH_PCRE)
find_package (PCRE REQUIRED)
set (HAVE_PCRE 1)
include_directories (${PCRE_INCLUDE_DIRS})
endif()
if (WIN32)
file (TO_NATIVE_PATH ${CMAKE_INSTALL_PREFIX}/${SWIG_LIB} SWIG_LIB_WIN_UNIX)
string (REGEX REPLACE "\\\\" "\\\\\\\\" SWIG_LIB_WIN_UNIX "${SWIG_LIB_WIN_UNIX}")
endif ()
configure_file (${SWIG_ROOT}/Tools/cmake/swigconfig.h.in
${CMAKE_CURRENT_BINARY_DIR}/Source/Include/swigconfig.h)
find_package (BISON REQUIRED)
# Compiler flags
# --------------
include_directories (
${SWIG_SOURCE_DIR}/CParse
${SWIG_SOURCE_DIR}/Include
${SWIG_SOURCE_DIR}/DOH
${SWIG_SOURCE_DIR}/Swig
${SWIG_SOURCE_DIR}/Preprocessor
${SWIG_SOURCE_DIR}/Modules
${PROJECT_BINARY_DIR}/Source/Include
${PROJECT_BINARY_DIR}/Source/CParse
${PROJECT_SOURCE_DIR}/Source/Doxygen
)
# generate the parser source code (depends on bison)
file (MAKE_DIRECTORY ${PROJECT_BINARY_DIR}/Source/CParse)
BISON_TARGET (swig_parser
${SWIG_SOURCE_DIR}/CParse/parser.y
${PROJECT_BINARY_DIR}/Source/CParse/parser.c
)
# generate swigwarn.swg
file (READ ${SWIG_SOURCE_DIR}/Include/swigwarn.h SWIG_WARN_H)
string (REGEX REPLACE "#define WARN([^ \\t]*)[ \\t]*([0-9]+)" "%define SWIGWARN\\1 \\2 %enddef" SWIG_WARN_SWG ${SWIG_WARN_H})
file (WRITE ${CMAKE_CURRENT_BINARY_DIR}/swigwarn.swg ${SWIG_WARN_SWG})
set_property (SOURCE ${CMAKE_CURRENT_BINARY_DIR}/swigwarn.swg PROPERTY GENERATED 1)
# install lib
install (DIRECTORY ${SWIG_ROOT}/Lib/ DESTINATION ${SWIG_LIB})
install (FILES ${CMAKE_CURRENT_BINARY_DIR}/swigwarn.swg DESTINATION ${SWIG_LIB})
# sources
# ---------
file (GLOB DOH_SOURCES ${SWIG_SOURCE_DIR}/DOH/*.c)
file (GLOB CPARSE_SOURCES ${SWIG_SOURCE_DIR}/CParse/*.c)
list (APPEND CPARSE_SOURCES)
file (GLOB PREPROCESSOR_SOURCES ${SWIG_SOURCE_DIR}/Preprocessor/*.c)
file (GLOB CORE_SOURCES ${SWIG_SOURCE_DIR}/Swig/*.c)
file (GLOB DOXYGEN_SOURCES ${SWIG_SOURCE_DIR}/Doxygen/*.cxx)
file (GLOB MODULES_SOURCES ${SWIG_SOURCE_DIR}/Modules/*.cxx)
add_executable (swig
${CPARSE_SOURCES}
${DOH_SOURCES}
${DOXYGEN_SOURCES}
${MODULES_SOURCES}
${CORE_SOURCES}
${PREPROCESSOR_SOURCES}
${PROJECT_BINARY_DIR}/Source/Include/swigconfig.h
${SWIG_SOURCE_DIR}/Include/swigwarn.h
${PROJECT_BINARY_DIR}/Source/CParse/parser.c
${PROJECT_BINARY_DIR}/Source/CParse/parser.h
)
if (PCRE_FOUND)
target_link_libraries (swig ${PCRE_LIBRARIES})
endif ()
install (TARGETS swig DESTINATION bin)
# 'make package-source' creates tarballs
set (CPACK_PACKAGE_NAME ${PACKAGE_NAME})
set (CPACK_SOURCE_GENERATOR "TGZ;TBZ2")
set (CPACK_SOURCE_IGNORE_FILES "/.git;/build;.*~;${CPACK_SOURCE_IGNORE_FILES}")
set (CPACK_SOURCE_PACKAGE_FILE_NAME ${PACKAGE_NAME}-${PACKAGE_VERSION})
include (CPack)
# few tests
enable_testing ()
add_test (NAME cmd_version COMMAND swig -version)
add_test (NAME cmd_swiglib COMMAND swig -swiglib)
add_test (NAME cmd_external_runtime COMMAND swig -external-runtime ext_rt.h)
set_tests_properties(cmd_external_runtime PROPERTIES ENVIRONMENT "SWIG_LIB=${PROJECT_SOURCE_DIR}/Lib")

24
Doc/Devel/internals.html
View file

@ -441,12 +441,12 @@ Resulting output:
<blockquote>
<pre>
hash len: 5
get: hashval2
hash item: hashval5 [h5]
hash item: hashval1 [h1]
hash item: hashval2 [h2]
hash item: hashval3 [h3]
list len: 5
get: listval2
list item: newlistval1
list item: listval2
list item: listval3
list item: listval5
</pre>
</blockquote>
@ -494,12 +494,12 @@ Resulting output:
<blockquote>
<pre>
list len: 5
get: listval2
list item: newlistval1
list item: listval2
list item: listval3
list item: listval5
hash len: 5
get: hashval2
hash item: hashval5 [h5]
hash item: hashval1 [h1]
hash item: hashval2 [h2]
hash item: hashval3 [h3]
</pre>
</blockquote>

2150
Doc/Manual/Allegrocl.html
View file

File diff suppressed because it is too large Load diff

16
Doc/Manual/Android.html
View file

@ -6,7 +6,7 @@
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="Android">21 SWIG and Android</a></H1>
<H1><a name="Android">22 SWIG and Android</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -31,7 +31,7 @@ This chapter describes SWIG's support of Android.
<H2><a name="Android_overview">21.1 Overview</a></H2>
<H2><a name="Android_overview">22.1 Overview</a></H2>
<p>
@ -41,10 +41,10 @@ Everything in the <a href="Java.html#Java">Java chapter</a> applies to generatin
This chapter contains a few Android specific notes and examples.
</p>
<H2><a name="Android_examples">21.2 Android examples</a></H2>
<H2><a name="Android_examples">22.2 Android examples</a></H2>
<H3><a name="Android_examples_intro">21.2.1 Examples introduction</a></H3>
<H3><a name="Android_examples_intro">22.2.1 Examples introduction</a></H3>
<p>
@ -77,7 +77,7 @@ $ android list targets
The following examples are shipped with SWIG under the Examples/android directory and include a Makefile to build and install each example.
</p>
<H3><a name="Android_example_simple">21.2.2 Simple C example</a></H3>
<H3><a name="Android_example_simple">22.2.2 Simple C example</a></H3>
<p>
@ -399,7 +399,7 @@ Run the app again and this time you will see the output pictured below, showing
<center><img src="android-simple.png" alt="Android screenshot of SwigSimple example"></center>
<H3><a name="Android_example_class">21.2.3 C++ class example</a></H3>
<H3><a name="Android_example_class">22.2.3 C++ class example</a></H3>
<p>
@ -747,7 +747,7 @@ Run the app to see the result of calling the C++ code from Java:
<center><img src="android-class.png" alt="Android screenshot of SwigClass example"></center>
<H3><a name="Android_examples_other">21.2.4 Other examples</a></H3>
<H3><a name="Android_examples_other">22.2.4 Other examples</a></H3>
<p>
@ -759,7 +759,7 @@ Note that the 'extend' example is demonstrates the directors feature.
Normally C++ exception handling and the STL is not available by default in the version of g++ shipped with Android, but this example turns these features on as described in the next section.
</p>
<H2><a name="Android_stl">21.3 C++ STL</a></H2>
<H2><a name="Android_stl">22.3 C++ STL</a></H2>
<p>

22
Doc/Manual/Arguments.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Arguments">12 Argument Handling</a></H1>
<H1><a name="Arguments">13 Argument Handling</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -43,7 +43,7 @@ return multiple values through the arguments of a function. This chapter
describes some of the techniques for doing this.
</p>
<H2><a name="Arguments_nn2">12.1 The typemaps.i library</a></H2>
<H2><a name="Arguments_nn2">13.1 The typemaps.i library</a></H2>
<p>
@ -51,7 +51,7 @@ This section describes the <tt>typemaps.i</tt> library file--commonly used to
change certain properties of argument conversion.
</p>
<H3><a name="Arguments_nn3">12.1.1 Introduction</a></H3>
<H3><a name="Arguments_nn3">13.1.1 Introduction</a></H3>
<p>
@ -195,7 +195,7 @@ else. To clear a typemap, the <tt>%clear</tt> directive should be used. For e
</pre>
</div>
<H3><a name="Arguments_nn4">12.1.2 Input parameters</a></H3>
<H3><a name="Arguments_nn4">13.1.2 Input parameters</a></H3>
<p>
@ -248,7 +248,7 @@ When the function is used in the scripting language interpreter, it will work li
result = add(3, 4)
</pre></div>
<H3><a name="Arguments_nn5">12.1.3 Output parameters</a></H3>
<H3><a name="Arguments_nn5">13.1.3 Output parameters</a></H3>
<p>
@ -315,7 +315,7 @@ iresult, dresult = foo(3.5, 2)
</pre>
</div>
<H3><a name="Arguments_nn6">12.1.4 Input/Output parameters</a></H3>
<H3><a name="Arguments_nn6">13.1.4 Input/Output parameters</a></H3>
<p>
@ -380,7 +380,7 @@ rather than directly overwriting the value of the original input object.
SWIG. Backwards compatibility is preserved, but deprecated.
</p>
<H3><a name="Arguments_nn7">12.1.5 Using different names</a></H3>
<H3><a name="Arguments_nn7">13.1.5 Using different names</a></H3>
<p>
@ -414,7 +414,7 @@ Typemap declarations are lexically scoped so a typemap takes effect from the poi
file or a matching <tt>%clear</tt> declaration.
</p>
<H2><a name="Arguments_nn8">12.2 Applying constraints to input values</a></H2>
<H2><a name="Arguments_nn8">13.2 Applying constraints to input values</a></H2>
<p>
@ -424,7 +424,7 @@ insure that a value is positive, or that a pointer is non-NULL. This
can be accomplished including the <tt>constraints.i</tt> library file.
</p>
<H3><a name="Arguments_nn9">12.2.1 Simple constraint example</a></H3>
<H3><a name="Arguments_nn9">13.2.1 Simple constraint example</a></H3>
<p>
@ -450,7 +450,7 @@ the arguments violate the constraint condition, a scripting language
exception will be raised. As a result, it is possible to catch bad
values, prevent mysterious program crashes and so on.</p>
<H3><a name="Arguments_nn10">12.2.2 Constraint methods</a></H3>
<H3><a name="Arguments_nn10">13.2.2 Constraint methods</a></H3>
<p>
@ -466,7 +466,7 @@ NONNULL Non-NULL pointer (pointers only).
</pre></div>
<H3><a name="Arguments_nn11">12.2.3 Applying constraints to new datatypes</a></H3>
<H3><a name="Arguments_nn11">13.2.3 Applying constraints to new datatypes</a></H3>
<p>

36
Doc/Manual/CCache.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="CCache">20 Using SWIG with ccache - ccache-swig(1) manpage</a></H1>
<H1><a name="CCache">21 Using SWIG with ccache - ccache-swig(1) manpage</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -35,7 +35,7 @@
<p>
<H2><a name="CCache_nn2">20.1 NAME</a></H2>
<H2><a name="CCache_nn2">21.1 NAME</a></H2>
<p>
@ -43,7 +43,7 @@
ccache-swig - a fast compiler cache
<p>
<H2><a name="CCache_nn3">20.2 SYNOPSIS</a></H2>
<H2><a name="CCache_nn3">21.2 SYNOPSIS</a></H2>
<p>
@ -53,7 +53,7 @@ ccache-swig &lt;compiler&gt; [COMPILER OPTIONS]
<p>
&lt;compiler&gt; [COMPILER OPTIONS]
<p>
<H2><a name="CCache_nn4">20.3 DESCRIPTION</a></H2>
<H2><a name="CCache_nn4">21.3 DESCRIPTION</a></H2>
<p>
@ -62,7 +62,7 @@ by caching previous compiles and detecting when the same compile is
being done again. ccache-swig is ccache plus support for SWIG. ccache
and ccache-swig are used interchangeably in this document.
<p>
<H2><a name="CCache_nn5">20.4 OPTIONS SUMMARY</a></H2>
<H2><a name="CCache_nn5">21.4 OPTIONS SUMMARY</a></H2>
<p>
@ -82,7 +82,7 @@ Here is a summary of the options to ccache-swig.
</pre>
<p>
<H2><a name="CCache_nn6">20.5 OPTIONS</a></H2>
<H2><a name="CCache_nn6">21.5 OPTIONS</a></H2>
<p>
@ -124,7 +124,7 @@ rounded down to the nearest multiple of 16 kilobytes.
<p>
</dl>
<p>
<H2><a name="CCache_nn7">20.6 INSTALLATION</a></H2>
<H2><a name="CCache_nn7">21.6 INSTALLATION</a></H2>
<p>
@ -156,7 +156,7 @@ This will work as long as /usr/local/bin comes before the path to gcc
Note! Do not use a hard link, use a symbolic link. A hardlink will
cause "interesting" problems.
<p>
<H2><a name="CCache_nn8">20.7 EXTRA OPTIONS</a></H2>
<H2><a name="CCache_nn8">21.7 EXTRA OPTIONS</a></H2>
<p>
@ -176,7 +176,7 @@ file). By using --ccache-skip you can force an option to not be
treated as an input file name and instead be passed along to the
compiler as a command line option.
<p>
<H2><a name="CCache_nn9">20.8 ENVIRONMENT VARIABLES</a></H2>
<H2><a name="CCache_nn9">21.8 ENVIRONMENT VARIABLES</a></H2>
<p>
@ -315,7 +315,7 @@ the use of '#pragma SWIG'.
<p>
</dl>
<p>
<H2><a name="CCache_nn10">20.9 CACHE SIZE MANAGEMENT</a></H2>
<H2><a name="CCache_nn10">21.9 CACHE SIZE MANAGEMENT</a></H2>
<p>
@ -328,7 +328,7 @@ When these limits are reached ccache will reduce the cache to 20%
below the numbers you specified in order to avoid doing the cache
clean operation too often.
<p>
<H2><a name="CCache_nn11">20.10 CACHE COMPRESSION</a></H2>
<H2><a name="CCache_nn11">21.10 CACHE COMPRESSION</a></H2>
<p>
@ -339,7 +339,7 @@ performance slowdown, it significantly increases the number of files
that fit in the cache. You can turn off compression setting the
CCACHE_NOCOMPRESS environment variable.
<p>
<H2><a name="CCache_nn12">20.11 HOW IT WORKS</a></H2>
<H2><a name="CCache_nn12">21.11 HOW IT WORKS</a></H2>
<p>
@ -364,7 +364,7 @@ compiler output that you would get without the cache. If you ever
discover a case where ccache changes the output of your compiler then
please let me know.
<p>
<H2><a name="CCache_nn13">20.12 USING CCACHE WITH DISTCC</a></H2>
<H2><a name="CCache_nn13">21.12 USING CCACHE WITH DISTCC</a></H2>
<p>
@ -378,7 +378,7 @@ option. You just need to set the environment variable CCACHE_PREFIX to
'distcc' and ccache will prefix the command line used with the
compiler with the command 'distcc'.
<p>
<H2><a name="CCache_nn14">20.13 SHARING A CACHE</a></H2>
<H2><a name="CCache_nn14">21.13 SHARING A CACHE</a></H2>
<p>
@ -407,7 +407,7 @@ following conditions need to be met:
versions of ccache that do not support compression.
</ul>
<p>
<H2><a name="CCache_nn15">20.14 HISTORY</a></H2>
<H2><a name="CCache_nn15">21.14 HISTORY</a></H2>
<p>
@ -423,7 +423,7 @@ I wrote ccache because I wanted to get a bit more speed out of a
compiler cache and I wanted to remove some of the limitations of the
shell-script version.
<p>
<H2><a name="CCache_nn16">20.15 DIFFERENCES FROM COMPILERCACHE</a></H2>
<H2><a name="CCache_nn16">21.15 DIFFERENCES FROM COMPILERCACHE</a></H2>
<p>
@ -441,7 +441,7 @@ are:
<li> ccache avoids a double call to cpp on a cache miss
</ul>
<p>
<H2><a name="CCache_nn17">20.16 CREDITS</a></H2>
<H2><a name="CCache_nn17">21.16 CREDITS</a></H2>
<p>
@ -453,7 +453,7 @@ Thanks to the following people for their contributions to ccache
<li> Paul Russell for many suggestions and the debian packaging
</ul>
<p>
<H2><a name="CCache_nn18">20.17 AUTHOR</a></H2>
<H2><a name="CCache_nn18">21.17 AUTHOR</a></H2>
<p>

4
Doc/Manual/CPlusPlus11.html
View file

@ -336,6 +336,10 @@ int i; int j;
decltype(i+j) k; // syntax error
</pre></div>
<p>SWIG does not support <tt>auto</tt> as a type specifier for variables, only
for specifying the return type of <a href="#CPlusPlus11_lambda_functions_and_expressions">lambdas</a>
and <a href="#CPlusPlus11_alternate_function_syntax">functions</a>.</p>
<H3><a name="CPlusPlus11_range_based_for_loop">7.2.7 Range-based for-loop</a></H3>

42
Doc/Manual/CPlusPlus20.html Normal file
View file

@ -0,0 +1,42 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and C++20</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="CPlusPlus20">10 SWIG and C++20</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#CPlusPlus20_introduction">Introduction</a>
<li><a href="#CPlusPlus20_core_language_changes">Core language changes</a>
<li><a href="#CPlusPlus20_standard_library_changes">Standard library changes</a>
</ul>
</div>
<!-- INDEX -->
<H2><a name="CPlusPlus20_introduction">10.1 Introduction</a></H2>
<p>This chapter gives you a brief overview about the SWIG
implementation of the C++20 standard.
Work has only just begun on adding C++20 support.
</p>
<p>
<b>Compatibility note:</b> SWIG-4.1.0 is the first version to support any C++20 features.
</p>
<H2><a name="CPlusPlus20_core_language_changes">10.2 Core language changes</a></H2>
<H2><a name="CPlusPlus20_standard_library_changes">10.3 Standard library changes</a></H2>
</body>
</html>

64
Doc/Manual/CSharp.html
View file

@ -6,7 +6,7 @@
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="CSharp">22 SWIG and C#</a></H1>
<H1><a name="CSharp">23 SWIG and C#</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -55,7 +55,7 @@
<H2><a name="CSharp_introduction">22.1 Introduction</a></H2>
<H2><a name="CSharp_introduction">23.1 Introduction</a></H2>
<p>
@ -75,16 +75,13 @@ There are some minor exceptions, where the minimum required is .NET 4.0.
This is when using the <tt>std::complex</tt> and <tt>std::list</tt> STL containers.
</p>
<p>
</p>
<p>
To get the most out of this chapter an understanding of interop is required.
The <a href="https://msdn.microsoft.com">Microsoft Developer Network (MSDN)</a> has a good reference guide in a section titled "Interop Marshaling".
Monodoc, available from the Mono project, has a very useful section titled <a href="https://www.mono-project.com/docs/advanced/pinvoke/">Interop with native libraries</a>.
</p>
<H3><a name="CSharp_introduction_swig2_compatibility">22.1.1 SWIG 2 Compatibility</a></H3>
<H3><a name="CSharp_introduction_swig2_compatibility">23.1.1 SWIG 2 Compatibility</a></H3>
<p>
@ -92,7 +89,7 @@ In order to minimize name collisions between names generated based on input to S
</p>
<H3><a name="CSharp_commandline">22.1.2 Additional command line options</a></H3>
<H3><a name="CSharp_commandline">23.1.2 Additional command line options</a></H3>
<p>
@ -144,7 +141,7 @@ Note that the file extension (.cs) will not be automatically added and needs to
Due to possible compiler limits it is not advisable to use <tt>-outfile</tt> for large projects.
</p>
<H2><a name="CSharp_differences_java">22.2 Differences to the Java module</a></H2>
<H2><a name="CSharp_differences_java">23.2 Differences to the Java module</a></H2>
<p>
@ -243,6 +240,7 @@ javabody -&gt; csbody
javafinalize -&gt; csfinalize
javadestruct -&gt; csdisposing and csdispose
javadestruct_derived -&gt; csdisposing_derived and csdispose_derived
javainterfacemodifiers -&gt; csinterfacemodifiers
javainterfacecode -&gt; csinterfacecode
</pre></div>
@ -565,7 +563,7 @@ Windows users can also get the examples working using a
<a href="http://www.cygwin.com">Cygwin</a> or <a href="http://www.mingw.org">MinGW</a> environment for automatic configuration of the example makefiles.
Any one of the C# compilers (Mono or Microsoft) can be detected from within a Cygwin or Mingw environment if installed in your path.
<H2><a name="CSharp_void_pointers">22.3 Void pointers</a></H2>
<H2><a name="CSharp_void_pointers">23.3 Void pointers</a></H2>
<p>
@ -583,7 +581,7 @@ void * f(void *v);
</pre>
</div>
<H2><a name="CSharp_arrays">22.4 C# Arrays</a></H2>
<H2><a name="CSharp_arrays">23.4 C# Arrays</a></H2>
<p>
@ -595,7 +593,7 @@ with one of the following three approaches; namely the SWIG C arrays library, P/
pinned arrays.
</p>
<H3><a name="CSharp_arrays_swig_library">22.4.1 The SWIG C arrays library</a></H3>
<H3><a name="CSharp_arrays_swig_library">23.4.1 The SWIG C arrays library</a></H3>
<p>
@ -632,7 +630,7 @@ example.print_array(c.cast()); // Pass to C
</div>
<H3><a name="CSharp_arrays_pinvoke_default_array_marshalling">22.4.2 Managed arrays using P/Invoke default array marshalling</a></H3>
<H3><a name="CSharp_arrays_pinvoke_default_array_marshalling">23.4.2 Managed arrays using P/Invoke default array marshalling</a></H3>
<p>
@ -759,7 +757,7 @@ and intermediary class method
</div>
<H3><a name="CSharp_arrays_pinning">22.4.3 Managed arrays using pinning</a></H3>
<H3><a name="CSharp_arrays_pinning">23.4.3 Managed arrays using pinning</a></H3>
<p>
@ -854,7 +852,7 @@ public static extern void myArrayCopy(global::System.IntPtr jarg1, global::Syste
<H2><a name="CSharp_exceptions">22.5 C# Exceptions</a></H2>
<H2><a name="CSharp_exceptions">23.5 C# Exceptions</a></H2>
<p>
@ -951,7 +949,7 @@ set so should only be used when a C# exception is not created.
</p>
<H3><a name="CSharp_exception_example_check_typemap">22.5.1 C# exception example using "check" typemap</a></H3>
<H3><a name="CSharp_exception_example_check_typemap">23.5.1 C# exception example using "check" typemap</a></H3>
<p>
@ -1133,7 +1131,7 @@ method and C# code does not handle pending exceptions via the canthrow attribute
Actually it will issue this warning for any function beginning with <tt>SWIG_CSharpSetPendingException</tt>.
</P>
<H3><a name="CSharp_exception_example_percent_exception">22.5.2 C# exception example using %exception</a></H3>
<H3><a name="CSharp_exception_example_percent_exception">23.5.2 C# exception example using %exception</a></H3>
<p>
@ -1198,7 +1196,7 @@ The managed code generated does check for the pending exception as mentioned ear
</pre>
</div>
<H3><a name="CSharp_exception_example_exception_specifications">22.5.3 C# exception example using exception specifications</a></H3>
<H3><a name="CSharp_exception_example_exception_specifications">23.5.3 C# exception example using exception specifications</a></H3>
<p>
@ -1254,7 +1252,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">22.5.4 Custom C# ApplicationException example</a></H3>
<H3><a name="CSharp_custom_application_exception">23.5.4 Custom C# ApplicationException example</a></H3>
<p>
@ -1388,7 +1386,7 @@ try {
</pre>
</div>
<H2><a name="CSharp_directors">22.6 C# Directors</a></H2>
<H2><a name="CSharp_directors">23.6 C# Directors</a></H2>
<p>
@ -1401,7 +1399,7 @@ The following sections provide information on the C# director implementation and
However, the <a href="Java.html#Java_directors">Java directors</a> section should also be read in order to gain more insight into directors.
</p>
<H3><a name="CSharp_directors_example">22.6.1 Directors example</a></H3>
<H3><a name="CSharp_directors_example">23.6.1 Directors example</a></H3>
<p>
@ -1522,7 +1520,7 @@ CSharpDerived - UIntMethod(123)
</pre>
</div>
<H3><a name="CSharp_directors_implementation">22.6.2 Directors implementation</a></H3>
<H3><a name="CSharp_directors_implementation">23.6.2 Directors implementation</a></H3>
<p>
@ -1730,7 +1728,7 @@ before SWIG parses the Base class will change all the delegates to <tt>internal<
</pre>
</div>
<H3><a name="CSharp_director_caveats">22.6.3 Director caveats</a></H3>
<H3><a name="CSharp_director_caveats">23.6.3 Director caveats</a></H3>
<p>
@ -1778,7 +1776,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_multiple_modules">22.7 Multiple modules</a></H2>
<H2><a name="CSharp_multiple_modules">23.7 Multiple modules</a></H2>
<p>
@ -1813,7 +1811,7 @@ the <tt>[System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrows
if you don't want users to easily stumble upon these so called 'internal workings' of the wrappers.
</p>
<H2><a name="CSharp_typemap_examples">22.8 C# Typemap examples</a></H2>
<H2><a name="CSharp_typemap_examples">23.8 C# Typemap examples</a></H2>
This section includes a few examples of typemaps. For more examples, you
@ -1821,7 +1819,7 @@ might look at the files "<tt>csharp.swg</tt>" and "<tt>typemaps.i</tt>" in
the SWIG library.
<H3><a name="CSharp_memory_management_member_variables">22.8.1 Memory management when returning references to member variables</a></H3>
<H3><a name="CSharp_memory_management_member_variables">23.8.1 Memory management when returning references to member variables</a></H3>
<p>
@ -1945,7 +1943,7 @@ public class Bike : global::System.IDisposable {
Note the <tt>addReference</tt> call.
</p>
<H3><a name="CSharp_memory_management_objects">22.8.2 Memory management for objects passed to the C++ layer</a></H3>
<H3><a name="CSharp_memory_management_objects">23.8.2 Memory management for objects passed to the C++ layer</a></H3>
<p>
@ -2077,7 +2075,7 @@ as mentioned earlier, <tt>setElement</tt> is actually:
</div>
<H3><a name="CSharp_date_marshalling">22.8.3 Date marshalling using the csin typemap and associated attributes</a></H3>
<H3><a name="CSharp_date_marshalling">23.8.3 Date marshalling using the csin typemap and associated attributes</a></H3>
<p>
@ -2363,7 +2361,7 @@ public class example {
</pre>
</div>
<H3><a name="CSharp_date_properties">22.8.4 A date example demonstrating marshalling of C# properties</a></H3>
<H3><a name="CSharp_date_properties">23.8.4 A date example demonstrating marshalling of C# properties</a></H3>
<p>
@ -2463,7 +2461,7 @@ Some points to note:
<li>The 'csin' typemap has 'pre', 'post' and 'cshin' attributes, and these are all ignored in the property set. The code in these attributes must instead be replicated within the 'csvarin' typemap. The line creating the <tt>temp$csinput</tt> variable is such an example; it is identical to what is in the 'pre' attribute.
</ul>
<H3><a name="CSharp_date_pre_post_directors">22.8.5 Date example demonstrating the 'pre' and 'post' typemap attributes for directors</a></H3>
<H3><a name="CSharp_date_pre_post_directors">23.8.5 Date example demonstrating the 'pre' and 'post' typemap attributes for directors</a></H3>
<p>
@ -2525,7 +2523,7 @@ Pay special attention to the memory management issues, using these attributes.
</p>
<H3><a name="CSharp_partial_classes">22.8.6 Turning proxy classes into partial classes</a></H3>
<H3><a name="CSharp_partial_classes">23.8.6 Turning proxy classes into partial classes</a></H3>
<p>
@ -2625,7 +2623,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_sealed_proxy_class">22.8.7 Turning proxy classes into sealed classes</a></H3>
<H3><a name="CSharp_sealed_proxy_class">23.8.7 Turning proxy classes into sealed classes</a></H3>
<p>
@ -2715,7 +2713,7 @@ Either suppress the warning or modify the generated code by copying and tweaking
'csbody' typemap code in csharp.swg by modifying swigCMemOwn to not be protected.
</p>
<H3><a name="CSharp_extending_proxy_class">22.8.8 Extending proxy classes with additional C# code</a></H3>
<H3><a name="CSharp_extending_proxy_class">23.8.8 Extending proxy classes with additional C# code</a></H3>
<p>
@ -2754,7 +2752,7 @@ public class ExtendMe : global::System.IDisposable {
</pre>
</div>
<H3><a name="CSharp_enum_underlying_type">22.8.9 Underlying type for enums</a></H3>
<H3><a name="CSharp_enum_underlying_type">23.8.9 Underlying type for enums</a></H3>
<P>

597
Doc/Manual/Chicken.html
View file

@ -1,597 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and Chicken</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Chicken">23 SWIG and Chicken</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Chicken_nn2">Preliminaries</a>
<ul>
<li><a href="#Chicken_nn3">Running SWIG in C mode</a>
<li><a href="#Chicken_nn4">Running SWIG in C++ mode</a>
</ul>
<li><a href="#Chicken_nn5">Code Generation</a>
<ul>
<li><a href="#Chicken_nn6">Naming Conventions</a>
<li><a href="#Chicken_nn7">Modules</a>
<li><a href="#Chicken_nn8">Constants and Variables</a>
<li><a href="#Chicken_nn9">Functions</a>
<li><a href="#Chicken_nn10">Exceptions</a>
</ul>
<li><a href="#Chicken_nn11">TinyCLOS</a>
<li><a href="#Chicken_nn12">Linkage</a>
<ul>
<li><a href="#Chicken_nn13">Static binary or shared library linked at compile time</a>
<li><a href="#Chicken_nn14">Building chicken extension libraries</a>
<li><a href="#Chicken_nn15">Linking multiple SWIG modules with TinyCLOS</a>
</ul>
<li><a href="#Chicken_nn16">Typemaps</a>
<li><a href="#Chicken_nn17">Pointers</a>
<ul>
<li><a href="#Chicken_collection">Garbage collection</a>
</ul>
<li><a href="#Chicken_nn18">Unsupported features and known problems</a>
<ul>
<li><a href="#Chicken_nn19">TinyCLOS problems with Chicken version &lt;= 1.92</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<p>
This chapter describes SWIG's support of CHICKEN. CHICKEN is a
Scheme-to-C compiler supporting most of the language features as
defined in the <i>Revised^5 Report on Scheme</i>. Its main
attributes are that it
</p>
<ol>
<li>generates portable C code</li>
<li>includes a customizable interpreter</li>
<li>links to C libraries with a simple Foreign Function Interface</li>
<li>supports full tail-recursion and first-class continuations</li>
</ol>
<p>
When confronted with a large C library, CHICKEN users can use
SWIG to generate CHICKEN wrappers for the C library. However,
the real advantages of using SWIG with CHICKEN are its
<strong>support for C++</strong> -- object-oriented code is
difficult to wrap by hand in CHICKEN -- and its <strong>typed
pointer representation</strong>, essential for C and C++
libraries involving structures or classes.
</p>
<H2><a name="Chicken_nn2">23.1 Preliminaries</a></H2>
<p>
CHICKEN support was introduced to SWIG in version 1.3.18. SWIG
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="#Chicken_collection">Garbage collection</a>
section below.
</p>
<p>
You may want to look at any of the examples in Examples/chicken/
directory for the basic steps to run SWIG CHICKEN.
</p>
<H3><a name="Chicken_nn3">23.1.1 Running SWIG in C mode</a></H3>
<p>
To run SWIG CHICKEN in C mode, use
the -chicken option.
</p>
<div class="shell">
<pre>% swig -chicken example.i</pre>
</div>
<p>
To allow the wrapper to take advantage of future CHICKEN code
generation improvements, part of the wrapper is direct CHICKEN
function calls (<tt>example_wrap.c</tt>) and part is CHICKEN
Scheme (<tt>example.scm</tt>). The basic Scheme code must
be compiled to C using your system's CHICKEN compiler or
both files can be compiled directly using the much simpler <tt>csc</tt>.
</p>
<div class="shell">
<pre>
% chicken example.scm -output-file oexample.c
</pre>
</div>
<p>
So for the C mode of SWIG CHICKEN, <tt>example_wrap.c</tt> and
<tt>oexample.c</tt> are the files that must be compiled to
object files and linked into your project.
</p>
<H3><a name="Chicken_nn4">23.1.2 Running SWIG in C++ mode</a></H3>
<p>
To run SWIG CHICKEN in C++ mode, use
the -chicken -c++ option.
</p>
<div class="shell">
<pre>% swig -chicken -c++ example.i</pre>
</div>
<p>
This will generate <tt>example_wrap.cxx</tt> and
<tt>example.scm</tt>. The basic Scheme code must be
compiled to C using your system's CHICKEN compiler or
both files can be compiled directly using the much simpler <tt>csc</tt>.
</p>
<div class="shell">
<pre>% chicken example.scm -output-file oexample.c</pre>
</div>
<p>
So for the C++ mode of SWIG CHICKEN, <tt>example_wrap.cxx</tt>
and <tt>oexample.c</tt> are the files that must be compiled to
object files and linked into your project.
</p>
<H2><a name="Chicken_nn5">23.2 Code Generation</a></H2>
<H3><a name="Chicken_nn6">23.2.1 Naming Conventions</a></H3>
<p>
Given a C variable, function or constant declaration named
<tt>Foo_Bar</tt>, the declaration will be available
in CHICKEN as an identifier ending with
<tt>Foo-Bar</tt>. That is, an underscore is converted
to a dash.
</p>
<p>
You may control what the CHICKEN identifier will be by using the
<tt>%rename</tt> SWIG directive in the SWIG interface file.
</p>
<H3><a name="Chicken_nn7">23.2.2 Modules</a></H3>
<p>
The name of the module must be declared one of two ways:
<ul>
<li>Placing <tt>%module example</tt> in the SWIG interface
file.</li>
<li>Using <tt>-module example</tt> on the SWIG command
line.</li>
</ul>
<p>
The generated example.scm file then exports <code>(declare (unit modulename))</code>.
If you do not want SWIG to export the <code>(declare (unit modulename))</code>, pass
the -nounit option to SWIG.
<p>
CHICKEN will be able to access the module using the <code>(declare
(uses <i>modulename</i>))</code> CHICKEN Scheme form.
</p>
<H3><a name="Chicken_nn8">23.2.3 Constants and Variables</a></H3>
<p>
Constants may be created using any of the four constructs in
the interface file:
</p>
<ol>
<li><code>#define MYCONSTANT1 ...</code></li>
<li><code>%constant int MYCONSTANT2 = ...</code></li>
<li><code>const int MYCONSTANT3 = ...</code></li>
<li><code>enum { MYCONSTANT4 = ... };</code></li>
</ol>
<p>
In all cases, the constants may be accessed from within CHICKEN
using the form <tt>(MYCONSTANT1)</tt>; that is, the constants
may be accessed using the read-only parameter form.
</p>
<p>
Variables are accessed using the full parameter form.
For example, to set the C variable "int my_variable;", use the
Scheme form <tt>(my-variable 2345)</tt>. To get the C variable,
use <tt>(my-variable)</tt>.
</p>
<p>
The <tt>%feature("constasvar")</tt> can be applied to any constant
or immutable variable. Instead of exporting the constant as
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#Customization_features">Features and the %feature directive</a>
for info on how to apply the %feature.
</p>
<H3><a name="Chicken_nn9">23.2.4 Functions</a></H3>
<p>
C functions declared in the SWIG interface file will have
corresponding CHICKEN Scheme procedures. For example, the C
function "int sqrt(double x);" will be available using the
Scheme form <tt>(sqrt 2345.0)</tt>. A <code>void</code> return
value will give C_SCHEME_UNDEFINED as a result.
</p>
<p>
A function may return more than one value by using the
<code>OUTPUT</code> specifier (see Lib/chicken/typemaps.i).
They will be returned as multiple values using <code>(values)</code> if there is more than one
result (that is, a non-void return value and at least one argout
parameter, or a void return value and at least two argout
parameters). The return values can then be accessed with <code>(call-with-values)</code>.
</p>
<H3><a name="Chicken_nn10">23.2.5 Exceptions</a></H3>
<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#Customization_exception">Exception handling with %exception</a>
for more information about declaring exceptions in the interface file.
</p>
<p>Chicken supports both the <code>SWIG_exception(int code, const char *msg)</code> interface
as well as a <code>SWIG_ThrowException(C_word val)</code> function for throwing exceptions from
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
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>
<p>The following simple module</p>
<div class="code"><pre>
%module exception_test
%inline %{
void test_throw(int i) throws (int) {
if (i == 1) throw 15;
}
%}
</pre></div>
<p>could be run with</p>
<div class="targetlang"><pre>
(handle-exceptions exvar
(if (= exvar 15)
(print "Correct!")
(print "Threw something else " exvar))
(test-throw 1))
</pre></div>
<H2><a name="Chicken_nn11">23.3 TinyCLOS</a></H2>
<p>
The author of TinyCLOS, Gregor Kiczales, describes TinyCLOS as:
"Tiny CLOS is a Scheme implementation of a 'kernelized' CLOS, with a
metaobject protocol. The implementation is even simpler than
the simple CLOS found in 'The Art of the Metaobject Protocol',
weighing in at around 850 lines of code, including (some)
comments and documentation."
</p>
<p>
Almost all good Scheme books describe how to use metaobjects and
generic procedures to implement an object-oriented Scheme
system. Please consult a Scheme book if you are unfamiliar
with the concept.
</p>
<p>
CHICKEN has a modified version of TinyCLOS, which SWIG CHICKEN
uses if the -proxy argument is given. If -proxy is passed, then
the generated example.scm file will contain TinyCLOS class definitions.
A class named Foo is declared as &lt;Foo&gt;, and each member variable
is allocated a slot. Member functions are exported as generic functions.
<p>
Primitive symbols and functions (the interface that would be presented if
-proxy was not passed) are hidden and no longer accessible. If the -unhideprimitive
command line argument is passed to SWIG, then the primitive symbols will be
available, but each will be prefixed by the string "primitive:"
<p>
The exported symbol names can be controlled with the -closprefix and -useclassprefix arguments.
If -useclassprefix is passed to SWIG, every member function will be generated with the class name
as a prefix. If the -closprefix mymod: argument is passed to SWIG, then the exported functions will
be prefixed by the string "mymod:". If -useclassprefix is passed, -closprefix is ignored.
</p>
<H2><a name="Chicken_nn12">23.4 Linkage</a></H2>
<p>
Please refer to <em>CHICKEN - A practical and portable Scheme
system - User's manual</em> for detailed help on how to link
object files to create a CHICKEN Scheme program. Briefly, to
link object files, be sure to add <tt>`chicken-config
-extra-libs -libs`</tt> or <tt>`chicken-config -shared
-extra-libs -libs`</tt>to your linker options. Use the
<tt>-shared</tt> option if you want to create a dynamically
loadable module. You might also want to use the much simpler
<tt>csc</tt> or <tt>csc.bat</tt>.
</p>
<p>Each scheme file that is generated
by SWIG contains <code>(declare (uses <i>modname</i>))</code>. This means that to load the
module from scheme code, the code must include <code>(declare (uses <i>modname</i>))</code>.
</p>
<H3><a name="Chicken_nn13">23.4.1 Static binary or shared library linked at compile time</a></H3>
<p>We can easily use csc to build a static binary.</p>
<div class="shell">
<pre>
$ swig -chicken example.i
$ csc -v example.scm example_impl.c example_wrap.c test_script.scm -o example
$ ./example
</pre>
</div>
<p>Similar to the above, any number of <tt>module.scm</tt> files could be compiled
into a shared library, and then that shared library linked when compiling the
main application.</p>
<div class="shell">
<pre>
$ swig -chicken example.i
$ csc -sv example.scm example_wrap.c example_impl.c -o example.so
</pre>
</div>
<p>The <tt>example.so</tt> file can then linked with <tt>test_script.scm</tt> when it
is compiled, in which case <tt>test_script.scm</tt> must have <code>(declare (uses example))</code>.
Multiple SWIG modules could have been linked into <tt>example.so</tt> and each
one accessed with a <code>(declare (uses ... ))</code>.
</p>
<div class="shell">
<pre>
$ csc -v test_script.scm -lexample
</pre>
</div>
<p>An alternative is that the test_script.scm can have the code <code>(load-library 'example "example.so")</code>,
in which case the test script does not need to be linked with example.so. The test_script.scm file can then
be run with <tt>csi</tt>.
</p>
<H3><a name="Chicken_nn14">23.4.2 Building chicken extension libraries</a></H3>
<p>Building a shared library like in the above section only works if the library
is linked at compile time with a script containing <code>(declare (uses ...))</code> or is
loaded explicitly with <code>(load-library 'example "example.so")</code>. It is
not the format that CHICKEN expects for extension libraries and eggs. The problem is the
<code>(declare (unit <i>modname</i>))</code> inside the <tt>modname.scm</tt> file. There are
two possible solutions to this.</p>
<p>First, SWIG accepts a <tt>-nounit</tt> argument, in which case the <code>(declare (unit <i>modname</i>))</code>
is not generated. Then, the <tt>modname.scm</tt> and <tt>modname_wrap.c</tt> files <b>must</b> be compiled into
their own shared library.</p>
<div class="shell">
<pre>
$ csc -sv modname.scm modname_wrap.c modname_impl.c -o modname.so
</pre>
</div>
<p>This library can then be loaded by scheme code with the <code>(require 'modname)</code> function.
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>
<div class="targetlang">
<pre>
(declare (uses mod1))
(declare (uses mod2))
</pre>
</div>
<p>Which would then be compiled with</p>
<div class="shell">
<pre>
$ swig -chicken mod1.i
$ swig -chicken mod2.i
$ csc -sv mod_load.scm mod1.scm mod2.scm mod1_wrap.c mod2_wrap.c mod1_impl.c mod2_impl.c -o mod.so
</pre>
</div>
<p>Then the extension library can be loaded with <code>(require 'mod)</code>. As we can see here,
<tt>mod_load.scm</tt> contains the code that gets executed when the module is loaded. All this code
does is load both mod1 and mod2. As we can see, this technique is more useful when you want to
combine a few SWIG modules into one chicken extension library, especially if modules are related by
<code>%import</code></p>
<p>In either method, the files that are compiled into the shared library could also be
packaged into an egg. The <tt>mod1_wrap.c</tt> and <tt>mod2_wrap.c</tt> files that are created by SWIG
are stand alone and do not need SWIG to be installed to be compiled. Thus the egg could be
distributed and used by anyone, even if SWIG is not installed.</p>
<p>See the <tt>Examples/chicken/egg</tt> directory in the SWIG source for an example that builds
two eggs, one using the first method and one using the second method.</p>
<H3><a name="Chicken_nn15">23.4.3 Linking multiple SWIG modules with TinyCLOS</a></H3>
<p>Linking together multiple modules that share type information using the <code>%import</code>
directive while also using <tt>-proxy</tt> is more complicated. For example, if <tt>mod2.i</tt> imports <tt>mod1.i</tt>, then the
<tt>mod2.scm</tt> file contains references to symbols declared in <tt>mod1.scm</tt>,
and thus a <code>(declare (uses <i>mod1</i>))</code> or <code>(require '<i>mod1</i>)</code> must be exported
to the top of <tt>mod2.scm</tt>. By default, when SWIG encounters an <code>%import "modname.i"</code> directive,
it exports <code>(declare (uses <i>modname</i>))</code> into the scm file. This works fine unless mod1 was compiled with
the <tt>-nounit</tt> argument or was compiled into an extension library with other modules under a different name.</p>
<p>One option is to override the automatic generation of <code>(declare (uses mod1))</code>
by passing the <tt>-noclosuses</tt> option to SWIG when compiling <tt>mod2.i</tt>.
SWIG then provides the <code>%insert(closprefix) %{ %}</code> directive. Any scheme code inside that directive is inserted into the
generated .scm file, and if <tt>mod1</tt> was compiled with <tt>-nounit</tt>, the directive should contain <code>(require 'mod1)</code>.
This option allows for mixed loading as well, where some modules are imported with <code>(declare (uses <i>modname</i>))</code>
(which means they were compiled without -nounit) and some are imported with <code>(require 'modname)</code>.</p>
<p>The other option is to use the second idea in the above section. Compile all the modules normally, without any
<code>%insert(closprefix)</code>, <tt>-nounit</tt>, or <tt>-noclosuses</tt>. Then the modules will import each other correctly
with <code>(declare (uses ...))</code>.
To create an extension library or an egg, just create a <tt>module_load.scm</tt> file that <code>(declare (uses ...))</code>
all the modules.</p>
<H2><a name="Chicken_nn16">23.5 Typemaps</a></H2>
<p>
The Chicken module handles all types via typemaps. This information is
read from <code>Lib/chicken/typemaps.i</code> and
<code>Lib/chicken/chicken.swg</code>.
</p>
<H2><a name="Chicken_nn17">23.6 Pointers</a></H2>
<p>
For pointer types, SWIG uses CHICKEN tagged pointers.
A tagged pointer is an ordinary CHICKEN pointer with an
extra slot for a void *. With SWIG
CHICKEN, this void * is a pointer to a type-info
structure. So each pointer used as input or output from
the SWIG-generated CHICKEN wrappers will have type
information attached to it. This will let the wrappers
correctly determine which method should be called
according to the object type hierarchy exposed in the SWIG
interface files.
</p>
<p>
To construct a Scheme object from a C pointer, the wrapper code
calls the function
<code>SWIG_NewPointerObj(void *ptr, swig_type_info *type, int owner)</code>,
The function that calls <code>SWIG_NewPointerObj</code> must have a variable declared
<code>C_word *known_space = C_alloc(C_SIZEOF_SWIG_POINTER);</code>
It is ok to call <code>SWIG_NewPointerObj</code> more than once,
just make sure known_space has enough space for all the created pointers.
</p>
<p>
To get the pointer represented by a CHICKEN tagged pointer, the
wrapper code calls the function
<code>SWIG_ConvertPtr(C_word s, void **result, swig_type_info *type, int flags)</code>,
passing a pointer to a struct representing the expected pointer
type. flags is either zero or SWIG_POINTER_DISOWN (see below).
</p>
<H3><a name="Chicken_collection">23.6.1 Garbage collection</a></H3>
<p>If the owner flag passed to <code>SWIG_NewPointerObj</code> is 1, <code>NewPointerObj</code> will add a
finalizer to the type which will call the destructor or delete method of
that type. The destructor and delete functions are no longer exported for
use in scheme code, instead SWIG and chicken manage pointers.
In situations where SWIG knows that a function is returning a type that should
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#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">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
get deleted while the scheme code still holds a pointer to it. Further use of this pointer
can lead to a crash.
</p>
<p>Adding a finalizer function from C code was added to chicken in the 1.89 release, so garbage collection
does not work for chicken versions below 1.89. If you would like the SWIG generated code to work with
chicken 1.40 to 1.89, pass the <code>-nocollection</code> argument to SWIG. This will not export code
inside the _wrap.c file to register finalizers, and will then export destructor functions which
must be called manually.
</p>
<H2><a name="Chicken_nn18">23.7 Unsupported features and known problems</a></H2>
<ul>
<li>No director support.</li>
<li>No support for c++ standard types like std::vector.</li>
<li>The TinyCLOS wrappers for overloaded functions will not work correctly when using
<a href="SWIGPlus.html#SWIGPlus_default_args">%feature(compactdefaultargs)</a>.</li>
</ul>
<H3><a name="Chicken_nn19">23.7.1 TinyCLOS problems with Chicken version &lt;= 1.92</a></H3>
<p>In Chicken versions equal to or below 1.92, TinyCLOS has a limitation such that generic methods do not properly work on methods
with different number of specializers: TinyCLOS assumes that every method added to a generic function
will have the same number of specializers. SWIG generates functions with different lengths of specializers
when C/C++ functions are overloaded. For example, the code</p>
<div class="code">
<pre>
class Foo {};
int foo(int a, Foo *b);
int foo(int a);
</pre></div>
<p>will produce scheme code</p>
<div class="targetlang">
<pre>
(define-method (foo (arg0 &lt;top&gt;) (arg1 &lt;Foo&gt;)) (<i>call primitive function</i>))
(define-method (foo (arg0 &lt;top&gt;)) (<i>call primitive function</i>))
</pre></div>
<p>Using unpatched TinyCLOS, the second <code>(define-method)</code> will replace the first one,
so calling <code>(foo 3 f)</code> will produce an error.</p>
<p>There are three solutions to this. The easist is to upgrade to the latest Chicken version. Otherwise, the
file <tt>Lib/chicken/tinyclos-multi-generic.patch</tt> in the SWIG source contains a patch against
tinyclos.scm inside the 1.92 chicken source to add support into TinyCLOS for multi-argument generics. (This patch was accepted into Chicken)
This requires chicken to be rebuilt and custom install of chicken. An alternative is the <tt>Lib/chicken/multi-generic.scm</tt>
file in the SWIG source. This file can be loaded after TinyCLOS is loaded, and it will override some functions
inside TinyCLOS to correctly support multi-argument generics. Please see the comments at the top of both files for more information.</p>
</body>
</html>

78
Doc/Manual/Contents.html
View file

@ -95,9 +95,10 @@
<ul>
<li><a href="Windows.html#Windows_swig_exe">Building swig.exe on Windows</a>
<ul>
<li><a href="Windows.html#Windows_cmake">Building swig.exe using CMake</a>
<li><a href="Windows.html#Windows_msys2">Building swig.exe using MSYS2</a>
<li><a href="Windows.html#Windows_mingw_msys">Building swig.exe using MinGW and MSYS</a>
<li><a href="Windows.html#Windows_cygwin">Building swig.exe using Cygwin</a>
<li><a href="Windows.html#Windows_building_alternatives">Building swig.exe alternatives</a>
</ul>
<li><a href="Windows.html#Windows_examples_cygwin">Running the examples on Windows using Cygwin</a>
</ul>
@ -372,7 +373,19 @@
</div>
<!-- INDEX -->
<h3><a href="Preprocessor.html#Preprocessor">10 Preprocessing</a></h3>
<h3><a href="CPlusPlus20.html#CPlusPlus20">10 SWIG and C++20</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="CPlusPlus20.html#CPlusPlus20_introduction">Introduction</a>
<li><a href="CPlusPlus20.html#CPlusPlus20_core_language_changes">Core language changes</a>
<li><a href="CPlusPlus20.html#CPlusPlus20_standard_library_changes">Standard library changes</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Preprocessor.html#Preprocessor">11 Preprocessing</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -395,7 +408,7 @@
</div>
<!-- INDEX -->
<h3><a href="Library.html#Library">11 SWIG library</a></h3>
<h3><a href="Library.html#Library">12 SWIG library</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -438,7 +451,7 @@
</div>
<!-- INDEX -->
<h3><a href="Arguments.html#Arguments">12 Argument Handling</a></h3>
<h3><a href="Arguments.html#Arguments">13 Argument Handling</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -461,7 +474,7 @@
</div>
<!-- INDEX -->
<h3><a href="Typemaps.html#Typemaps">13 Typemaps</a></h3>
<h3><a href="Typemaps.html#Typemaps">14 Typemaps</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -555,7 +568,7 @@
</div>
<!-- INDEX -->
<h3><a href="Customization.html#Customization">14 Customization Features</a></h3>
<h3><a href="Customization.html#Customization">15 Customization Features</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -583,7 +596,7 @@
</div>
<!-- INDEX -->
<h3><a href="Contract.html#Contract">15 Contracts</a></h3>
<h3><a href="Contract.html#Contract">16 Contracts</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -596,7 +609,7 @@
</div>
<!-- INDEX -->
<h3><a href="Varargs.html#Varargs">16 Variable Length Arguments</a></h3>
<h3><a href="Varargs.html#Varargs">17 Variable Length Arguments</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -614,7 +627,7 @@
</div>
<!-- INDEX -->
<h3><a href="Doxygen.html#Doxygen">17 SWIG and Doxygen Translation</a></h3>
<h3><a href="Doxygen.html#Doxygen">18 SWIG and Doxygen Translation</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -662,7 +675,7 @@
</div>
<!-- INDEX -->
<h3><a href="Warnings.html#Warnings">18 Warning Messages</a></h3>
<h3><a href="Warnings.html#Warnings">19 Warning Messages</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -691,7 +704,7 @@
</div>
<!-- INDEX -->
<h3><a href="Modules.html#Modules">19 Working with Modules</a></h3>
<h3><a href="Modules.html#Modules">20 Working with Modules</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -707,7 +720,7 @@
</div>
<!-- INDEX -->
<h3><a href="CCache.html#CCache">20 Using SWIG with ccache - ccache-swig(1) manpage</a></h3>
<h3><a href="CCache.html#CCache">21 Using SWIG with ccache - ccache-swig(1) manpage</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -733,7 +746,7 @@
</div>
<!-- INDEX -->
<h3><a href="Android.html#Android">21 SWIG and Android</a></h3>
<h3><a href="Android.html#Android">22 SWIG and Android</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -751,7 +764,7 @@
</div>
<!-- INDEX -->
<h3><a href="CSharp.html#CSharp">22 SWIG and C#</a></h3>
<h3><a href="CSharp.html#CSharp">23 SWIG and C#</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -799,7 +812,7 @@
</div>
<!-- INDEX -->
<h3><a href="D.html#D">23 SWIG and D</a></h3>
<h3><a href="D.html#D">24 SWIG and D</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -833,7 +846,7 @@
</div>
<!-- INDEX -->
<h3><a href="Go.html#Go">24 SWIG and Go</a></h3>
<h3><a href="Go.html#Go">25 SWIG and Go</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -877,7 +890,7 @@
</div>
<!-- INDEX -->
<h3><a href="Guile.html#Guile">25 SWIG and Guile</a></h3>
<h3><a href="Guile.html#Guile">26 SWIG and Guile</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -913,7 +926,7 @@
</div>
<!-- INDEX -->
<h3><a href="Java.html#Java">26 SWIG and Java</a></h3>
<h3><a href="Java.html#Java">27 SWIG and Java</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1067,7 +1080,7 @@
</div>
<!-- INDEX -->
<h3><a href="Javascript.html#Javascript">27 SWIG and Javascript</a></h3>
<h3><a href="Javascript.html#Javascript">28 SWIG and Javascript</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1109,7 +1122,7 @@
</div>
<!-- INDEX -->
<h3><a href="Lua.html#Lua">28 SWIG and Lua</a></h3>
<h3><a href="Lua.html#Lua">29 SWIG and Lua</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1177,7 +1190,7 @@
</div>
<!-- INDEX -->
<h3><a href="Octave.html#Octave">29 SWIG and Octave</a></h3>
<h3><a href="Octave.html#Octave">30 SWIG and Octave</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1217,7 +1230,7 @@
</div>
<!-- INDEX -->
<h3><a href="Perl5.html#Perl5">30 SWIG and Perl5</a></h3>
<h3><a href="Perl5.html#Perl5">31 SWIG and Perl5</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1293,7 +1306,7 @@
</div>
<!-- INDEX -->
<h3><a href="Php.html#Php">31 SWIG and PHP</a></h3>
<h3><a href="Php.html#Php">32 SWIG and PHP</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1334,7 +1347,7 @@
</div>
<!-- INDEX -->
<h3><a href="Python.html#Python">32 SWIG and Python</a></h3>
<h3><a href="Python.html#Python">33 SWIG and Python</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1476,7 +1489,7 @@
</div>
<!-- INDEX -->
<h3><a href="R.html#R">33 SWIG and R</a></h3>
<h3><a href="R.html#R">34 SWIG and R</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1487,12 +1500,15 @@
<li><a href="R.html#R_nn5">General policy</a>
<li><a href="R.html#R_language_conventions">Language conventions</a>
<li><a href="R.html#R_nn6">C++ classes</a>
<ul>
<li><a href="R.html#R_class_examples">Examples</a>
</ul>
<li><a href="R.html#R_nn7">Enumerations</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Ruby.html#Ruby">34 SWIG and Ruby</a></h3>
<h3><a href="Ruby.html#Ruby">35 SWIG and Ruby</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1630,7 +1646,7 @@
</div>
<!-- INDEX -->
<h3><a href="Scilab.html#Scilab">35 SWIG and Scilab</a></h3>
<h3><a href="Scilab.html#Scilab">36 SWIG and Scilab</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1699,7 +1715,7 @@
</div>
<!-- INDEX -->
<h3><a href="Tcl.html#Tcl">36 SWIG and Tcl</a></h3>
<h3><a href="Tcl.html#Tcl">37 SWIG and Tcl</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1765,7 +1781,7 @@
</div>
<!-- INDEX -->
<h3><a href="Mzscheme.html#Mzscheme">37 SWIG and MzScheme/Racket</a></h3>
<h3><a href="Mzscheme.html#Mzscheme">38 SWIG and MzScheme/Racket</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1777,7 +1793,7 @@
</div>
<!-- INDEX -->
<h3><a href="Ocaml.html#Ocaml">38 SWIG and OCaml</a></h3>
<h3><a href="Ocaml.html#Ocaml">39 SWIG and OCaml</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1832,7 +1848,7 @@
</div>
<!-- INDEX -->
<h3><a href="Extending.html#Extending">39 Extending SWIG to support new languages</a></h3>
<h3><a href="Extending.html#Extending">40 Extending SWIG to support new languages</a></h3>
<!-- INDEX -->
<div class="sectiontoc">

10
Doc/Manual/Contract.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Contract">15 Contracts</a></H1>
<H1><a name="Contract">16 Contracts</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -39,7 +39,7 @@ When one of the rules is violated by a script, a runtime exception is
generated rather than having the program continue to execute.
</p>
<H2><a name="Contract_nn2">15.1 The %contract directive</a></H2>
<H2><a name="Contract_nn2">16.1 The %contract directive</a></H2>
<p>
@ -95,7 +95,7 @@ RuntimeError: Contract violation: require: (arg1&gt;=0)
</pre>
</div>
<H2><a name="Contract_nn3">15.2 %contract and classes</a></H2>
<H2><a name="Contract_nn3">16.2 %contract and classes</a></H2>
<p>
@ -174,7 +174,7 @@ specified for the derived class all must hold. In the above example,
this means that both the arguments to <tt>Spam::bar</tt> must be positive.
</p>
<H2><a name="Contract_nn4">15.3 Constant aggregation and %aggregate_check</a></H2>
<H2><a name="Contract_nn4">16.3 Constant aggregation and %aggregate_check</a></H2>
<p>
@ -263,7 +263,7 @@ Regrettably, there is no automatic way to perform similar checks with enums valu
release.
</p>
<H2><a name="Contract_nn5">15.4 Notes</a></H2>
<H2><a name="Contract_nn5">16.4 Notes</a></H2>
<p>

32
Doc/Manual/Customization.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Customization">14 Customization Features</a></H1>
<H1><a name="Customization">15 Customization Features</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -46,7 +46,7 @@ of exception handling is presented. Then, a more general-purpose
customization mechanism known as "features" is described.
</p>
<H2><a name="Customization_exception">14.1 Exception handling with %exception</a></H2>
<H2><a name="Customization_exception">15.1 Exception handling with %exception</a></H2>
<p>
@ -101,7 +101,7 @@ for exception handling. That directive is deprecated--<tt>%exception</tt>
provides the same functionality, but is substantially more flexible.
</p>
<H3><a name="Customization_nn3">14.1.1 Handling exceptions in C code</a></H3>
<H3><a name="Customization_nn3">15.1.1 Handling exceptions in C code</a></H3>
<p>
@ -169,7 +169,7 @@ Each target language has its own approach to creating a runtime error/exception
and for Perl it is the <tt>croak</tt> method shown above.
</p>
<H3><a name="Customization_nn4">14.1.2 Exception handling with longjmp()</a></H3>
<H3><a name="Customization_nn4">15.1.2 Exception handling with longjmp()</a></H3>
<p>
@ -245,7 +245,7 @@ Note: This implementation is only intended to illustrate the general idea. To m
modify it to handle nested <tt>try</tt> declarations.
</p>
<H3><a name="Customization_nn5">14.1.3 Handling C++ exceptions</a></H3>
<H3><a name="Customization_nn5">15.1.3 Handling C++ exceptions</a></H3>
<p>
@ -280,7 +280,7 @@ class OutOfMemory {};
</pre>
</div>
<H3><a name="Customization_allowexcept">14.1.4 Exception handlers for variables</a></H3>
<H3><a name="Customization_allowexcept">15.1.4 Exception handlers for variables</a></H3>
<p>
@ -305,7 +305,7 @@ The <tt>%allowexception</tt> feature works like any other feature and so can be
</pre>
</div>
<H3><a name="Customization_nn6">14.1.5 Defining different exception handlers</a></H3>
<H3><a name="Customization_nn6">15.1.5 Defining different exception handlers</a></H3>
<p>
@ -442,7 +442,7 @@ declarations. However, it never really worked that well and the new
%exception directive is much better.
</p>
<H3><a name="Customization_exception_special_variables">14.1.6 Special variables for %exception</a></H3>
<H3><a name="Customization_exception_special_variables">15.1.6 Special variables for %exception</a></H3>
<p>
@ -545,7 +545,7 @@ Below shows the expansions for the 1st of the overloaded <tt>something</tt> wrap
</pre></div>
<H3><a name="Customization_nn7">14.1.7 Using The SWIG exception library</a></H3>
<H3><a name="Customization_nn7">15.1.7 Using The SWIG exception library</a></H3>
<p>
@ -600,7 +600,7 @@ SWIG_NullReferenceError
The <tt>SWIG_exception()</tt> function can also be used in typemaps.
</p>
<H2><a name="Customization_ownership">14.2 Object ownership and %newobject</a></H2>
<H2><a name="Customization_ownership">15.2 Object ownership and %newobject</a></H2>
<p>
@ -757,7 +757,7 @@ char *strdup(const char *s);
The results might not be what you expect.
</p>
<H2><a name="Customization_features">14.3 Features and the %feature directive</a></H2>
<H2><a name="Customization_features">15.3 Features and the %feature directive</a></H2>
<p>
@ -839,7 +839,7 @@ The following are all equivalent:
The syntax in the first variation will generate the <tt>{ }</tt> delimiters used whereas the other variations will not.
</p>
<H3><a name="Customization_feature_attributes">14.3.1 Feature attributes</a></H3>
<H3><a name="Customization_feature_attributes">15.3.1 Feature attributes</a></H3>
<p>
@ -880,7 +880,7 @@ In the following example, <tt>MyExceptionClass</tt> is the name of the Java clas
Further details can be obtained from the <a href="Java.html#Java_exception_handling">Java exception handling</a> section.
</p>
<H3><a name="Customization_feature_flags">14.3.2 Feature flags</a></H3>
<H3><a name="Customization_feature_flags">15.3.2 Feature flags</a></H3>
<p>
@ -978,7 +978,7 @@ in the <tt>swig.swg</tt> Library file. The following shows the alternative synta
The concept of clearing features is discussed next.
</p>
<H3><a name="Customization_clearing_features">14.3.3 Clearing features</a></H3>
<H3><a name="Customization_clearing_features">15.3.3 Clearing features</a></H3>
<p>
@ -1071,7 +1071,7 @@ The three macros below show this for the "except" feature:
</pre>
</div>
<H3><a name="Customization_features_default_args">14.3.4 Features and default arguments</a></H3>
<H3><a name="Customization_features_default_args">15.3.4 Features and default arguments</a></H3>
<p>
@ -1146,7 +1146,7 @@ specifying or not specifying default arguments in a feature is not applicable as
in SWIG-1.3.23 when the approach to wrapping methods with default arguments was changed.
</p>
<H3><a name="Customization_features_example">14.3.5 Feature example</a></H3>
<H3><a name="Customization_features_example">15.3.5 Feature example</a></H3>
<p>

44
Doc/Manual/D.html
View file

@ -6,7 +6,7 @@
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="D">23 SWIG and D</a></H1>
<H1><a name="D">24 SWIG and D</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -41,7 +41,7 @@
<H2><a name="D_introduction">23.1 Introduction</a></H2>
<H2><a name="D_introduction">24.1 Introduction</a></H2>
<p>From the <a href="http://www.digitalmars.com/d/">D Programming Language</a> web site: <em>D is a systems programming language. Its focus is on combining the power and high performance of C and C++ with the programmer productivity of modern languages like Ruby and Python. [...] The D language is statically typed and compiles directly to machine code.</em> As such, it is not very surprising that D is able to directly <a href="http://www.digitalmars.com/d/1.0/interfaceToC.html">interface with C libraries</a>. Why would a SWIG module for D be needed then in the first place?</p>
@ -53,7 +53,7 @@
<p>To help addressing these issues, the SWIG C# module has been forked to support D. Is has evolved quite a lot since then, but there are still many similarities, so if you do not find what you are looking for on this page, it might be worth having a look at the chapter on <a href="CSharp.html#CSharp">C#</a> (and also on <a href="Java.html#Java">Java</a>, since the C# module was in turn forked from it).</p>
<H2><a name="D_command_line_invocation">23.2 Command line invocation</a></H2>
<H2><a name="D_command_line_invocation">24.2 Command line invocation</a></H2>
<p>To activate the D module, pass the <tt>-d</tt> option to SWIG at the command line. The same standard command line options as with any other language module are available, plus the following D specific ones:</p>
@ -83,10 +83,10 @@
</dl>
<H2><a name="D_typemaps">23.3 Typemaps</a></H2>
<H2><a name="D_typemaps">24.3 Typemaps</a></H2>
<H3><a name="D_typemap_name_comparison">23.3.1 C# &lt;-&gt; D name comparison</a></H3>
<H3><a name="D_typemap_name_comparison">24.3.1 C# &lt;-&gt; D name comparison</a></H3>
<p>If you already know the SWIG C# module, you might find the following name comparison table useful:</p>
@ -112,7 +112,7 @@
</pre></div>
<H3><a name="D_ctype_imtype_dtype">23.3.2 ctype, imtype, dtype</a></H3>
<H3><a name="D_ctype_imtype_dtype">24.3.2 ctype, imtype, dtype</a></H3>
<p>Mapping of types between the C/C++ library, the C/C++ library wrapper exposing the C functions, the D wrapper module importing these functions and the D proxy code.</p>
@ -120,7 +120,7 @@
<p>The <tt>ctype</tt> typemap is used to determine the types to use in the C wrapper functions. The types from the <tt>imtype</tt> typemap are used in the extern(C) declarations of these functions in the intermediary D module. The <tt>dtype</tt> typemap contains the D types used in the D proxy module/class.</p>
<H3><a name="D_in_out_directorin_direcetorout">23.3.3 in, out, directorin, directorout</a></H3>
<H3><a name="D_in_out_directorin_direcetorout">24.3.3 in, out, directorin, directorout</a></H3>
<p>Used for converting between the types for C/C++ and D when generating the code for the wrapper functions (on the C++ side).</p>
@ -130,7 +130,7 @@
<p>The <tt>directorin</tt> typemap is used to convert parameters to the type used in the D director callback function, its return value is processed by <tt>directorout</tt> (see below).</p>
<H3><a name="D_din_dout_ddirectorin_ddirectorout">23.3.4 din, dout, ddirectorin, ddirectorout</a></H3>
<H3><a name="D_din_dout_ddirectorin_ddirectorout">24.3.4 din, dout, ddirectorin, ddirectorout</a></H3>
<p>Typemaps for code generation in D proxy and type wrapper classes.</p>
@ -157,13 +157,13 @@
dtype DClass.method(dtype a)</pre></div>
<H3><a name="D_typecheck_typemaps">23.3.5 typecheck typemaps</a></H3>
<H3><a name="D_typecheck_typemaps">24.3.5 typecheck typemaps</a></H3>
<p>Because, unlike many scripting languages supported by SWIG, D does not need any dynamic dispatch helper to access an overloaded function, the purpose of these is merely to issue a warning for overloaded C++ functions that cannot be overloaded in D (as more than one C++ type maps to a single D type).</p>
<H3><a name="D_code_injection_typemaps">23.3.6 Code injection typemaps</a></H3>
<H3><a name="D_code_injection_typemaps">24.3.6 Code injection typemaps</a></H3>
<p>These typemaps are used for generating the skeleton of proxy classes for C++ types.</p>
@ -178,7 +178,7 @@
Code can also be injected into the D proxy class using <tt>%proxycode</tt>.
</p>
<H3><a name="D_special_variables">23.3.7 Special variable macros</a></H3>
<H3><a name="D_special_variables">24.3.7 Special variable macros</a></H3>
<p>The standard SWIG special variables are available for use within typemaps as described in the <a href="Typemaps.html#Typemaps">Typemaps documentation</a>, for example <tt>$1</tt>, <tt>$input</tt>, <tt>$result</tt> etc.</p>
@ -299,7 +299,7 @@ $importtype(AnotherInterface)
</dl>
<H2><a name="D_features">23.4 D and %feature</a></H2>
<H2><a name="D_features">24.4 D and %feature</a></H2>
<p>The D module defines a number of directives which modify the <a href="Customization.html#Customization_features">SWIG features</a> set globally or for a specific declaration:</p>
@ -329,7 +329,7 @@ struct A {
</dl>
<H2><a name="D_pragmas">23.5 Pragmas</a></H2>
<H2><a name="D_pragmas">24.5 Pragmas</a></H2>
<p>There are a few SWIG pragmas specific to the D module, which you can use to influence the D code SWIG generates:</p>
@ -368,7 +368,7 @@ struct A {
</dl>
<H2><a name="D_exceptions">23.6 D Exceptions</a></H2>
<H2><a name="D_exceptions">24.6 D Exceptions</a></H2>
<p>Out of the box, C++ exceptions are fundamentally incompatible to their equivalent in the D world and cannot simply be propagated to a calling D method. There is, however, an easy way to solve this problem: Just catch the exception in the C/C++ wrapper layer, pass the contents to D, and make the wrapper code rethrow the exception in the D world.</p>
@ -378,7 +378,7 @@ struct A {
<p>As this feature is implemented in exactly the same way it is for C#, please see the <a href="CSharp.html#CSharp_exceptions">C# documentation</a> for a more detailed explanation.</p>
<H2><a name="D_directors">23.7 D Directors</a></H2>
<H2><a name="D_directors">24.7 D Directors</a></H2>
<p>When the directors feature is activated, SWIG generates extra code on both the C++ and the D side to enable cross-language polymorphism. Essentially, this means that if you subclass a proxy class in D, C++ code can access any overridden virtual methods just as if you created a derived class in C++.</p>
@ -387,16 +387,16 @@ struct A {
</p>
<H2><a name="D_other_features">23.8 Other features</a></H2>
<H2><a name="D_other_features">24.8 Other features</a></H2>
<H3><a name="D_nspace">23.8.1 Extended namespace support (nspace)</a></H3>
<H3><a name="D_nspace">24.8.1 Extended namespace support (nspace)</a></H3>
<p>By default, SWIG flattens all C++ namespaces into a single target language namespace, but as for Java and C#, the <a href="SWIGPlus.html#SWIGPlus_nspace"><tt>nspace</tt></a> feature is supported for D. If it is active, C++ namespaces are mapped to D packages/modules. Note, however, that like for the other languages, <em>free</em> variables and functions are not supported yet; currently, they are all allows written to the main proxy D module.</p>
<H3><a name="D_native_pointer_support">23.8.2 Native pointer support</a></H3>
<H3><a name="D_native_pointer_support">24.8.2 Native pointer support</a></H3>
<p>Contrary to many of the scripting languages supported by SWIG, D fully supports C-style pointers. The D module thus includes a custom mechanism to wrap C pointers directly as D pointers where applicable, that is, if the type that is pointed to is represented the same in C and D (on the bit-level), dubbed a <em>primitive type</em> below.</p>
@ -408,7 +408,7 @@ struct A {
<p>To determine if a type should be considered primitive, the <tt>cprimitive</tt> attribute on its <tt>dtype</tt> attribute is used. For example, the <tt>dtype</tt> typemap for <tt>float</tt> has <tt>cprimitive="1"</tt>, so the code from the <tt>nativepointer</tt> attribute is taken into account e.g. for <tt>float **</tt> or the function pointer <tt>float (*)(float *)</tt>.</p>
<H3><a name="D_operator_overloading">23.8.3 Operator overloading</a></H3>
<H3><a name="D_operator_overloading">24.8.3 Operator overloading</a></H3>
<p>The D module comes with basic operator overloading support for both D1 and D2. There are, however, a few limitations arising from conceptual differences between C++ and D:</p>
@ -420,7 +420,7 @@ struct A {
<p>There are also some cases where the operators can be translated to D, but the differences in the implementation details are big enough that a rather involved scheme would be required for automatic wrapping them, which has not been implemented yet. This affects, for example, the array subscript operator, <tt>[]</tt>, in combination with assignments - while <tt>operator []</tt> in C++ simply returns a reference which is then written to, D resorts to a separate <tt>opIndexAssign</tt> method -, or implicit casting (which was introduced in D2 via <tt>alias this</tt>). Despite the lack of automatic support, manually handling these cases should be perfectly possible.</p>
<H3><a name="D_test_suite">23.8.4 Running the test-suite</a></H3>
<H3><a name="D_test_suite">24.8.4 Running the test-suite</a></H3>
<p>As with any other language, the SWIG test-suite can be built for D using the <tt>*-d-test-suite</tt> targets of the top-level Makefile. By default, D1 is targeted, to build it with D2, use the optional <tt>D_VERSION</tt> variable, e.g. <tt>make check-d-test-suite D_VERSION=2</tt>.</p>
@ -428,14 +428,14 @@ struct A {
<p>Note: If you want to use GDC on Linux or another platform which requires you to link <tt>libdl</tt> for dynamically loading the shared library, you might have to add <tt>-ldl</tt> manually to the <tt>d_compile</tt> target in <tt>Examples/Makefile</tt>, because GDC does not currently honor the <tt>pragma(lib, ...)</tt> statement.</p>
<H2><a name="D_typemap_examples">23.9 D Typemap examples</a></H2>
<H2><a name="D_typemap_examples">24.9 D Typemap examples</a></H2>
<p>There are no D-specific typemap examples yet. However, with the above <a href="D.html#D_typemap_name_comparison">name comparison table</a>, you should be able to get an idea what can be done by looking at the <a href="CSharp.html#CSharp_typemap_examples">corresponding C# section</a>.</p>
<H2><a name="D_planned_features">23.10 Work in progress and planned features</a></H2>
<H2><a name="D_planned_features">24.10 Work in progress and planned features</a></H2>
<p>There are a couple of features which are not implemented yet, but would be very useful and might be added in the near future:</p>

766
Doc/Manual/Doxygen.html
View file

File diff suppressed because it is too large Load diff

114
Doc/Manual/Extending.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Extending">39 Extending SWIG to support new languages</a></H1>
<H1><a name="Extending">40 Extending SWIG to support new languages</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -81,7 +81,7 @@
<H2><a name="Extending_nn2">39.1 Introduction</a></H2>
<H2><a name="Extending_nn2">40.1 Introduction</a></H2>
<p>
@ -97,7 +97,7 @@ Also, this chapter is not meant to be a hand-holding tutorial. As a starting po
you should probably look at one of SWIG's existing modules.
</p>
<H2><a name="Extending_nn3">39.2 Prerequisites</a></H2>
<H2><a name="Extending_nn3">40.2 Prerequisites</a></H2>
<p>
@ -127,7 +127,7 @@ obvious, but almost all SWIG directives as well as the low-level generation of
wrapper code are driven by C++ datatypes.
</p>
<H2><a name="Extending_nn4">39.3 The Big Picture</a></H2>
<H2><a name="Extending_nn4">40.3 The Big Picture</a></H2>
<p>
@ -164,7 +164,7 @@ role in making the system work. For example, both typemaps and declaration anno
based on pattern matching and interact heavily with the underlying type system.
</p>
<H2><a name="Extending_nn5">39.4 Execution Model</a></H2>
<H2><a name="Extending_nn5">40.4 Execution Model</a></H2>
<p>
@ -209,7 +209,7 @@ latter stage of compilation.
The next few sections briefly describe some of these stages.
</p>
<H3><a name="Extending_nn6">39.4.1 Preprocessing</a></H3>
<H3><a name="Extending_nn6">40.4.1 Preprocessing</a></H3>
<p>
@ -290,7 +290,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">39.4.2 Parsing</a></H3>
<H3><a name="Extending_nn7">40.4.2 Parsing</a></H3>
<p>
@ -391,7 +391,7 @@ returning a <tt>foo</tt> and taking types <tt>a</tt> and <tt>b</tt> as
arguments).
</p>
<H3><a name="Extending_nn8">39.4.3 Parse Trees</a></H3>
<H3><a name="Extending_nn8">40.4.3 Parse Trees</a></H3>
<p>
@ -646,7 +646,7 @@ $ swig -c++ -python -debug-module 4 example.i
</pre>
</div>
<H3><a name="Extending_nn9">39.4.4 Attribute namespaces</a></H3>
<H3><a name="Extending_nn9">40.4.4 Attribute namespaces</a></H3>
<p>
@ -665,7 +665,7 @@ that matches the name of the target language. For example, <tt>python:foo</tt>
<tt>perl:foo</tt>.
</p>
<H3><a name="Extending_nn10">39.4.5 Symbol Tables</a></H3>
<H3><a name="Extending_nn10">40.4.5 Symbol Tables</a></H3>
<p>
@ -756,7 +756,7 @@ example.i:5. Previous declaration is foo_i(int )
</pre>
</div>
<H3><a name="Extending_nn11">39.4.6 The %feature directive</a></H3>
<H3><a name="Extending_nn11">40.4.6 The %feature directive</a></H3>
<p>
@ -812,7 +812,7 @@ For example, the exception code above is simply
stored without any modifications.
</p>
<H3><a name="Extending_nn12">39.4.7 Code Generation</a></H3>
<H3><a name="Extending_nn12">40.4.7 Code Generation</a></H3>
<p>
@ -934,7 +934,7 @@ public :
The role of these functions is described shortly.
</p>
<H3><a name="Extending_nn13">39.4.8 SWIG and XML</a></H3>
<H3><a name="Extending_nn13">40.4.8 SWIG and XML</a></H3>
<p>
@ -947,7 +947,7 @@ internal data structures, it may be useful to keep XML in the back of
your mind as a model.
</p>
<H2><a name="Extending_nn14">39.5 Primitive Data Structures</a></H2>
<H2><a name="Extending_nn14">40.5 Primitive Data Structures</a></H2>
<p>
@ -993,7 +993,7 @@ typedef Hash Typetab;
</pre>
</div>
<H3><a name="Extending_nn15">39.5.1 Strings</a></H3>
<H3><a name="Extending_nn15">40.5.1 Strings</a></H3>
<p>
@ -1134,7 +1134,7 @@ Returns the number of replacements made (if any).
</div>
<H3><a name="Extending_nn16">39.5.2 Hashes</a></H3>
<H3><a name="Extending_nn16">40.5.2 Hashes</a></H3>
<p>
@ -1211,7 +1211,7 @@ Returns the list of hash table keys.
</div>
<H3><a name="Extending_nn17">39.5.3 Lists</a></H3>
<H3><a name="Extending_nn17">40.5.3 Lists</a></H3>
<p>
@ -1300,7 +1300,7 @@ If <tt>t</tt> is not a standard object, it is assumed to be a <tt>char *</tt>
and is used to create a String object.
</div>
<H3><a name="Extending_nn18">39.5.4 Common operations</a></H3>
<H3><a name="Extending_nn18">40.5.4 Common operations</a></H3>
The following operations are applicable to all datatypes.
@ -1355,7 +1355,7 @@ objects and report errors.
Gets the line number associated with <tt>x</tt>.
</div>
<H3><a name="Extending_nn19">39.5.5 Iterating over Lists and Hashes</a></H3>
<H3><a name="Extending_nn19">40.5.5 Iterating over Lists and Hashes</a></H3>
To iterate over the elements of a list or a hash table, the following functions are used:
@ -1400,7 +1400,7 @@ for (j = First(j); j.item; j= Next(j)) {
</div>
<H3><a name="Extending_nn20">39.5.6 I/O</a></H3>
<H3><a name="Extending_nn20">40.5.6 I/O</a></H3>
Special I/O functions are used for all internal I/O. These operations
@ -1534,7 +1534,7 @@ Printf(f, "%s\n", s);
Similarly, the preprocessor and parser all operate on string-files.
</p>
<H2><a name="Extending_nn21">39.6 Navigating and manipulating parse trees</a></H2>
<H2><a name="Extending_nn21">40.6 Navigating and manipulating parse trees</a></H2>
Parse trees are built as collections of hash tables. Each node is a hash table in which
@ -1668,7 +1668,7 @@ Deletes a node from the parse tree. Deletion reconnects siblings and properly u
the parent so that sibling nodes are unaffected.
</div>
<H2><a name="Extending_nn22">39.7 Working with attributes</a></H2>
<H2><a name="Extending_nn22">40.7 Working with attributes</a></H2>
<p>
@ -1785,7 +1785,7 @@ the attribute is optional. <tt>Swig_restore()</tt> must always be called after
function.
</div>
<H2><a name="Extending_nn23">39.8 Type system</a></H2>
<H2><a name="Extending_nn23">40.8 Type system</a></H2>
<p>
@ -1794,7 +1794,7 @@ pointers, references, and pointers to members. A detailed discussion of
type theory is impossible here. However, let's cover the highlights.
</p>
<H3><a name="Extending_nn24">39.8.1 String encoding of types</a></H3>
<H3><a name="Extending_nn24">40.8.1 String encoding of types</a></H3>
<p>
@ -1895,7 +1895,7 @@ make the final type, the two parts are just joined together using
string concatenation.
</p>
<H3><a name="Extending_nn25">39.8.2 Type construction</a></H3>
<H3><a name="Extending_nn25">40.8.2 Type construction</a></H3>
<p>
@ -2064,7 +2064,7 @@ Returns the prefix of a type. For example, if <tt>ty</tt> is
<tt>ty</tt> is unmodified.
</div>
<H3><a name="Extending_nn26">39.8.3 Type tests</a></H3>
<H3><a name="Extending_nn26">40.8.3 Type tests</a></H3>
<p>
@ -2151,7 +2151,7 @@ Checks if <tt>ty</tt> is a varargs type.
Checks if <tt>ty</tt> is a templatized type.
</div>
<H3><a name="Extending_nn27">39.8.4 Typedef and inheritance</a></H3>
<H3><a name="Extending_nn27">40.8.4 Typedef and inheritance</a></H3>
<p>
@ -2253,7 +2253,7 @@ Fully reduces <tt>ty</tt> according to typedef rules. Resulting datatype
will consist only of primitive typenames.
</div>
<H3><a name="Extending_nn28">39.8.5 Lvalues</a></H3>
<H3><a name="Extending_nn28">40.8.5 Lvalues</a></H3>
<p>
@ -2290,7 +2290,7 @@ Literal y; // type = 'Literal', ltype='p.char'
</pre>
</div>
<H3><a name="Extending_nn29">39.8.6 Output functions</a></H3>
<H3><a name="Extending_nn29">40.8.6 Output functions</a></H3>
<p>
@ -2352,7 +2352,7 @@ SWIG, but is most commonly associated with type-descriptor objects
that appear in wrappers (e.g., <tt>SWIGTYPE_p_double</tt>).
</div>
<H2><a name="Extending_nn30">39.9 Parameters</a></H2>
<H2><a name="Extending_nn30">40.9 Parameters</a></H2>
<p>
@ -2451,7 +2451,7 @@ included. Used to emit prototypes.
Returns the number of required (non-optional) arguments in <tt>p</tt>.
</div>
<H2><a name="Extending_nn31">39.10 Writing a Language Module</a></H2>
<H2><a name="Extending_nn31">40.10 Writing a Language Module</a></H2>
<p>
@ -2466,7 +2466,7 @@ describes the creation of a minimal Python module. You should be able to extra
this to other languages.
</p>
<H3><a name="Extending_nn32">39.10.1 Execution model</a></H3>
<H3><a name="Extending_nn32">40.10.1 Execution model</a></H3>
<p>
@ -2476,7 +2476,7 @@ the parsing of command line options, all aspects of code generation are controll
different methods of the <tt>Language</tt> that must be defined by your module.
</p>
<H3><a name="Extending_starting_out">39.10.2 Starting out</a></H3>
<H3><a name="Extending_starting_out">40.10.2 Starting out</a></H3>
<p>
@ -2584,7 +2584,7 @@ that activates your module. For example, <tt>swig -python foo.i</tt>. The
messages from your new module should appear.
</p>
<H3><a name="Extending_nn34">39.10.3 Command line options</a></H3>
<H3><a name="Extending_nn34">40.10.3 Command line options</a></H3>
<p>
@ -2643,7 +2643,7 @@ to mark the option as valid. If you forget to do this, SWIG will terminate wit
unrecognized command line option error.
</p>
<H3><a name="Extending_nn35">39.10.4 Configuration and preprocessing</a></H3>
<H3><a name="Extending_nn35">40.10.4 Configuration and preprocessing</a></H3>
<p>
@ -2692,7 +2692,7 @@ an implementation file <tt>python.cxx</tt> and a configuration file
<tt>python.swg</tt>.
</p>
<H3><a name="Extending_nn36">39.10.5 Entry point to code generation</a></H3>
<H3><a name="Extending_nn36">40.10.5 Entry point to code generation</a></H3>
<p>
@ -2750,7 +2750,7 @@ int Python::top(Node *n) {
</pre>
</div>
<H3><a name="Extending_nn37">39.10.6 Module I/O and wrapper skeleton</a></H3>
<H3><a name="Extending_nn37">40.10.6 Module I/O and wrapper skeleton</a></H3>
<!-- please report bugs in this section to mgossage -->
@ -2898,7 +2898,7 @@ functionWrapper : void Shape_y_set(Shape *self, double y)
</pre>
</div>
<H3><a name="Extending_nn38">39.10.7 Low-level code generators</a></H3>
<H3><a name="Extending_nn38">40.10.7 Low-level code generators</a></H3>
<!-- please report bugs in this section to mgossage -->
@ -3052,7 +3052,7 @@ but without the typemaps, there is still work to do.
</p>
<H3><a name="Extending_configuration_files">39.10.8 Configuration files</a></H3>
<H3><a name="Extending_configuration_files">40.10.8 Configuration files</a></H3>
<!-- please report bugs in this section to ttn -->
@ -3196,7 +3196,7 @@ politely displays the ignoring language message.
</dl>
<H3><a name="Extending_nn40">39.10.9 Runtime support</a></H3>
<H3><a name="Extending_nn40">40.10.9 Runtime support</a></H3>
<p>
@ -3205,7 +3205,7 @@ Discuss the kinds of functions typically needed for SWIG runtime support (e.g.
the SWIG files that implement those functions.
</p>
<H3><a name="Extending_nn41">39.10.10 Standard library files</a></H3>
<H3><a name="Extending_nn41">40.10.10 Standard library files</a></H3>
<p>
@ -3224,7 +3224,7 @@ The following are the minimum that are usually supported:
Please copy these and modify for any new language.
</p>
<H3><a name="Extending_nn42">39.10.11 User examples</a></H3>
<H3><a name="Extending_nn42">40.10.11 User examples</a></H3>
<p>
@ -3253,7 +3253,7 @@ during this process, see the section on <a href="#Extending_configuration_files"
files</a>.
</p>
<H3><a name="Extending_test_suite">39.10.12 Test driven development and the test-suite</a></H3>
<H3><a name="Extending_test_suite">40.10.12 Test driven development and the test-suite</a></H3>
<p>
@ -3312,7 +3312,7 @@ It is therefore essential that the runtime tests are written in a manner that di
but error/exception out with an error message on stderr on failure.
</p>
<H4><a name="Extending_running_test_suite">39.10.12.1 Running the test-suite</a></H4>
<H4><a name="Extending_running_test_suite">40.10.12.1 Running the test-suite</a></H4>
<p>
@ -3504,7 +3504,7 @@ It can be run in the same way as the other language test-suites, replacing [lang
The test cases used and the way it works is described in <tt>Examples/test-suite/errors/Makefile.in</tt>.
</p>
<H3><a name="Extending_nn43">39.10.13 Documentation</a></H3>
<H3><a name="Extending_nn43">40.10.13 Documentation</a></H3>
<p>
@ -3536,7 +3536,7 @@ Some topics that you'll want to be sure to address include:
if available.
</ul>
<H3><a name="Extending_coding_style_guidelines">39.10.14 Coding style guidelines</a></H3>
<H3><a name="Extending_coding_style_guidelines">40.10.14 Coding style guidelines</a></H3>
<p>
@ -3561,7 +3561,7 @@ should be avoided as unlike the SWIG developers, users will never have consisten
</p>
<H3><a name="Extending_language_status">39.10.15 Target language status</a></H3>
<H3><a name="Extending_language_status">40.10.15 Target language status</a></H3>
<p>
@ -3570,7 +3570,7 @@ the <a href="Introduction.html#Introduction_target_languages">Target language in
This section provides more details on how this status is given.
</p>
<H4><a name="Extending_supported_status">39.10.15.1 Supported status</a></H4>
<H4><a name="Extending_supported_status">40.10.15.1 Supported status</a></H4>
<p>
@ -3613,11 +3613,11 @@ A target language is given the 'Supported' status when
Examples must be available and run successfully.
</li>
<li>
The examples and test-suite must be fully functioning on the Travis Continuous Integration platform.
The examples and test-suite must be fully functioning on the Github Actions Continuous Integration platform.
</li>
</ul>
<H4><a name="Extending_experimental_status">39.10.15.2 Experimental status</a></H4>
<H4><a name="Extending_experimental_status">40.10.15.2 Experimental status</a></H4>
<p>
@ -3660,9 +3660,9 @@ Some minimum requirements and notes about languages with the 'Experimental' stat
The number of tests in these lists should be no greater than half of the number of tests in the full test-suite.
</li>
<li>
The examples and test-suite must also be fully functioning on the Travis Continuous Integration platform.
However, experimental languages will be set as 'allow_failures'.
This means that pull requests and normal development commits will not break the entire Travis build should an experimental language fail.
The examples and test-suite must also be fully functioning on the Github Actions Continuous Integration platform.
However, experimental languages will be flagged as 'continue-on-error'.
This means that pull requests and normal development commits will not break the entire Github Actions build should an experimental language fail.
</li>
<li>
Any new failed tests will be fixed on a 'best effort' basis by core developers with no promises made.
@ -3682,7 +3682,7 @@ Some minimum requirements and notes about languages with the 'Experimental' stat
</li>
</ul>
<H3><a name="Extending_prerequisites">39.10.16 Prerequisites for adding a new language module to the SWIG distribution</a></H3>
<H3><a name="Extending_prerequisites">40.10.16 Prerequisites for adding a new language module to the SWIG distribution</a></H3>
<p>
@ -3746,7 +3746,7 @@ the existing tests.
</p>
<H2><a name="Extending_debugging_options">39.11 Debugging Options</a></H2>
<H2><a name="Extending_debugging_options">40.11 Debugging Options</a></H2>
<p>
@ -3773,7 +3773,7 @@ There are various command line options which can aid debugging a SWIG interface
The complete list of command line options for SWIG are available by running <tt>swig -help</tt>.
</p>
<H2><a name="Extending_nn46">39.12 Guide to parse tree nodes</a></H2>
<H2><a name="Extending_nn46">40.12 Guide to parse tree nodes</a></H2>
<p>
@ -4181,7 +4181,7 @@ extern "X" { ... } declaration.
</pre>
</div>
<H2><a name="Extending_further_info">39.13 Further Development Information</a></H2>
<H2><a name="Extending_further_info">40.13 Further Development Information</a></H2>
<p>

121
Doc/Manual/Go.html
View file

@ -6,7 +6,7 @@
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="Go">24 SWIG and Go</a></H1>
<H1><a name="Go">25 SWIG and Go</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -57,7 +57,7 @@ the Go programming language
see <a href="http://golang.org/">golang.org</a>.
</p>
<H2><a name="Go_overview">24.1 Overview</a></H2>
<H2><a name="Go_overview">25.1 Overview</a></H2>
<p>
@ -71,6 +71,7 @@ code. SWIG fills this gap.
There are (at least) two different Go compilers. The first is the gc compiler
of the <a href="https://golang.org/doc/install">Go distribution</a>, normally
invoked via the <a href="https://golang.org/cmd/go/">go tool</a>.
SWIG supports the gc compiler version 1.2 or later.
The second Go compiler is the <a href="https://golang.org/doc/install/gccgo">
gccgo compiler</a>, which is a frontend to the GCC compiler suite.
The interface to C/C++ code is completely different for the two Go compilers.
@ -86,7 +87,7 @@ type-safe as well. In case of type issues the build will fail and hence SWIG's
are not used.
</p>
<H2><a name="Go_examples">24.2 Examples</a></H2>
<H2><a name="Go_examples">25.2 Examples</a></H2>
<p>
@ -101,7 +102,7 @@ SWIG interface file extension for backwards compatibility with Go 1.
</p>
<H2><a name="Go_running_swig">24.3 Running SWIG with Go</a></H2>
<H2><a name="Go_running_swig">25.3 Running SWIG with Go</a></H2>
<p>
@ -142,46 +143,8 @@ You will now have a Go package that you can import from other Go packages as
usual.
</p>
<p>
SWIG can be used without cgo, via the <tt>-no-cgo</tt> option, but
more steps are required. This only works with Go versions before 1.5.
When using Go version 1.2 or later, or when using gccgo, the code
generated by SWIG can be linked directly into the Go program. A
typical command sequence when using the Go compiler of the Go
distribution would look like this:
</p>
<div class="code"><pre>
% swig -go -no-cgo example.i
% gcc -c code.c # The C library being wrapped.
% gcc -c example_wrap.c
% go tool 6g example.go
% go tool 6c example_gc.c
% go tool pack grc example.a example.6 example_gc.6 code.o example_wrap.o
% go tool 6g main.go
% go tool 6l main.6
</pre></div>
<p>
You can also put the wrapped code into a shared library, and when using the Go
versions before 1.2 this is the only supported option. A typical command
sequence for this approach would look like this:
</p>
<div class="code"><pre>
% swig -go -no-cgo -use-shlib example.i
% gcc -c -fpic example.c
% gcc -c -fpic example_wrap.c
% gcc -shared example.o example_wrap.o -o example.so
% go tool 6g example.go
% go tool 6c example_gc.c
% go tool pack grc example.a example.6 example_gc.6
% go tool 6g main.go # your code, not generated by SWIG
% go tool 6l main.6
</pre></div>
<H3><a name="Go_commandline">24.3.1 Go-specific Commandline Options</a></H3>
<H3><a name="Go_commandline">25.3.1 Go-specific Commandline Options</a></H3>
<p>
@ -206,9 +169,7 @@ swig -go -help
<tr>
<td>-no-cgo</td>
<td>Generate files that can be used directly, rather than via the Go
cgo tool. This option does not work with Go 1.5 or later. It is
required for versions of Go before 1.2.</td>
<td>This option is no longer supported.</td>
</tr>
<tr>
@ -276,16 +237,13 @@ swig -go -help
</table>
<H3><a name="Go_outputs">24.3.2 Generated Wrapper Files</a></H3>
<H3><a name="Go_outputs">25.3.2 Generated Wrapper Files</a></H3>
<p>There are two different approaches to generating wrapper files,
controlled by SWIG's <tt>-no-cgo</tt> option. The <tt>-no-cgo</tt>
option only works with version of Go before 1.5. It is required
when using versions of Go before 1.2.</p>
<p>With or without the <tt>-no-cgo</tt> option, SWIG will generate the
following files when generating wrapper code:</p>
<p>
SWIG will generate the following files when generating wrapper
code:
</p>
<ul>
<li>
@ -308,19 +266,8 @@ or C++ compiler.
</li>
</ul>
<p>When the <tt>-no-cgo</tt> option is used, and the <tt>-gccgo</tt>
option is not used, SWIG will also generate an additional file:</p>
<ul>
<li>
MODULE_gc.c will contain C code which should be compiled with the C
compiler distributed as part of the gc compiler. It should then be
combined with the compiled MODULE.go using go tool pack.
</li>
</ul>
<H2><a name="Go_basic_tour">24.4 A tour of basic C/C++ wrapping</a></H2>
<H2><a name="Go_basic_tour">25.4 A tour of basic C/C++ wrapping</a></H2>
<p>
@ -330,7 +277,7 @@ modifications have to occur. This section briefly covers the
essential aspects of this wrapping.
</p>
<H3><a name="Go_package">24.4.1 Go Package Name</a></H3>
<H3><a name="Go_package">25.4.1 Go Package Name</a></H3>
<p>
@ -340,7 +287,7 @@ directive. You may override this by using SWIG's <tt>-package</tt>
command line option.
</p>
<H3><a name="Go_names">24.4.2 Go Names</a></H3>
<H3><a name="Go_names">25.4.2 Go Names</a></H3>
<p>
@ -372,7 +319,7 @@ followed by that name, and the destructor will be
named <tt>Delete</tt> followed by that name.
</p>
<H3><a name="Go_constants">24.4.3 Go Constants</a></H3>
<H3><a name="Go_constants">25.4.3 Go Constants</a></H3>
<p>
@ -380,7 +327,7 @@ C/C++ constants created via <tt>#define</tt> or the <tt>%constant</tt>
directive become Go constants, declared with a <tt>const</tt>
declaration.
<H3><a name="Go_enumerations">24.4.4 Go Enumerations</a></H3>
<H3><a name="Go_enumerations">25.4.4 Go Enumerations</a></H3>
<p>
@ -390,7 +337,7 @@ usual). The values of the enumeration will become variables in Go;
code should avoid modifying those variables.
</p>
<H3><a name="Go_classes">24.4.5 Go Classes</a></H3>
<H3><a name="Go_classes">25.4.5 Go Classes</a></H3>
<p>
@ -468,7 +415,7 @@ returns a go interface. If the returned pointer can be null, you can check
for this by calling the Swigcptr() method.
</p>
<H4><a name="Go_class_memory">24.4.5.1 Go Class Memory Management</a></H4>
<H4><a name="Go_class_memory">25.4.5.1 Go Class Memory Management</a></H4>
<p>
@ -590,7 +537,7 @@ func (o *GoClassName) Close() {
</pre>
</div>
<H4><a name="Go_class_inheritance">24.4.5.2 Go Class Inheritance</a></H4>
<H4><a name="Go_class_inheritance">25.4.5.2 Go Class Inheritance</a></H4>
<p>
@ -602,7 +549,7 @@ Doing the reverse will require an explicit type assertion, which will
be checked dynamically.
</p>
<H3><a name="Go_templates">24.4.6 Go Templates</a></H3>
<H3><a name="Go_templates">25.4.6 Go Templates</a></H3>
<p>
@ -611,7 +558,7 @@ wrappers for a particular template instantiation. To do this, use
the <tt>%template</tt> directive.
<H3><a name="Go_director_classes">24.4.7 Go Director Classes</a></H3>
<H3><a name="Go_director_classes">25.4.7 Go Director Classes</a></H3>
<p>
@ -629,7 +576,7 @@ completely to avoid common pitfalls with directors in Go.
</p>
<H4><a name="Go_director_example_cpp_code">24.4.7.1 Example C++ code</a></H4>
<H4><a name="Go_director_example_cpp_code">25.4.7.1 Example C++ code</a></H4>
<p>
@ -701,7 +648,7 @@ be found in <a href="#Go_director_foobargo_class">the end of the guide</a>.
</p>
<H4><a name="Go_director_enable">24.4.7.2 Enable director feature</a></H4>
<H4><a name="Go_director_enable">25.4.7.2 Enable director feature</a></H4>
<p>
@ -736,7 +683,7 @@ documentation on directors.
</p>
<H4><a name="Go_director_ctor_dtor">24.4.7.3 Constructor and destructor</a></H4>
<H4><a name="Go_director_ctor_dtor">25.4.7.3 Constructor and destructor</a></H4>
<p>
@ -789,7 +736,7 @@ embedding</a>.
</p>
<H4><a name="Go_director_overriding">24.4.7.4 Override virtual methods</a></H4>
<H4><a name="Go_director_overriding">25.4.7.4 Override virtual methods</a></H4>
<p>
@ -857,7 +804,7 @@ the Go methods.
</p>
<H4><a name="Go_director_base_methods">24.4.7.5 Call base methods</a></H4>
<H4><a name="Go_director_base_methods">25.4.7.5 Call base methods</a></H4>
<p>
@ -894,7 +841,7 @@ be found in <a href="#Go_director_foobargo_class">the end of the guide</a>.
</p>
<H4><a name="Go_director_subclass">24.4.7.6 Subclass via embedding</a></H4>
<H4><a name="Go_director_subclass">25.4.7.6 Subclass via embedding</a></H4>
<p>
@ -962,7 +909,7 @@ class.
</p>
<H4><a name="Go_director_finalizer">24.4.7.7 Memory management with runtime.SetFinalizer</a></H4>
<H4><a name="Go_director_finalizer">25.4.7.7 Memory management with runtime.SetFinalizer</a></H4>
<p>
@ -1027,7 +974,7 @@ before using <tt>runtime.SetFinalizer</tt> to know all of its gotchas.
</p>
<H4><a name="Go_director_foobargo_class">24.4.7.8 Complete FooBarGo example class</a></H4>
<H4><a name="Go_director_foobargo_class">25.4.7.8 Complete FooBarGo example class</a></H4>
<p>
@ -1156,7 +1103,7 @@ SWIG/Examples/go/director/</a>.
</p>
<H3><a name="Go_primitive_type_mappings">24.4.8 Default Go primitive type mappings</a></H3>
<H3><a name="Go_primitive_type_mappings">25.4.8 Default Go primitive type mappings</a></H3>
<p>
@ -1263,7 +1210,7 @@ that typemap, or add new values, to control how C/C++ types are mapped
into Go types.
</p>
<H3><a name="Go_output_arguments">24.4.9 Output arguments</a></H3>
<H3><a name="Go_output_arguments">25.4.9 Output arguments</a></H3>
<p>Because of limitations in the way output arguments are processed in swig,
@ -1316,7 +1263,7 @@ void f(char *output);
</pre>
</div>
<H3><a name="Go_adding_additional_code">24.4.10 Adding additional go code</a></H3>
<H3><a name="Go_adding_additional_code">25.4.10 Adding additional go code</a></H3>
<p>Often the APIs generated by swig are not very natural in go, especially if
@ -1411,7 +1358,7 @@ func bar() {
</pre>
</div>
<H3><a name="Go_typemaps">24.4.11 Go typemaps</a></H3>
<H3><a name="Go_typemaps">25.4.11 Go typemaps</a></H3>
<p>

46
Doc/Manual/Guile.html
View file

@ -8,7 +8,7 @@
<body bgcolor="#ffffff">
<H1><a name="Guile">25 SWIG and Guile</a></H1>
<H1><a name="Guile">26 SWIG and Guile</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -48,7 +48,7 @@
<p>
This section details guile-specific support in SWIG.
<H2><a name="Guile_nn1">25.1 Supported Guile Versions</a></H2>
<H2><a name="Guile_nn1">26.1 Supported Guile Versions</a></H2>
<p>
@ -62,7 +62,7 @@ improved performance. This is currently not tested with swig
so your mileage may vary. To be safe set environment variable
GUILE_AUTO_COMPILE to 0 when using swig generated guile code.
<H2><a name="Guile_nn2">25.2 Meaning of "Module"</a></H2>
<H2><a name="Guile_nn2">26.2 Meaning of "Module"</a></H2>
<p>
@ -70,7 +70,7 @@ There are three different concepts of "module" involved, defined
separately for SWIG, Guile, and Libtool. To avoid horrible confusion,
we explicitly prefix the context, e.g., "guile-module".
<H2><a name="Guile_nn3">25.3 Old GH Guile API</a></H2>
<H2><a name="Guile_nn3">26.3 Old GH Guile API</a></H2>
<p>Guile 1.8 and older could be interfaced using two different api's, the SCM
@ -81,7 +81,7 @@ or the GH API. The GH interface to guile is deprecated. Read more about why in
version of SWIG that can still generate guile GH wrapper code is 2.0.9. Please
use that version if you really need the GH wrapper code.
<H2><a name="Guile_nn4">25.4 Linkage</a></H2>
<H2><a name="Guile_nn4">26.4 Linkage</a></H2>
<p>
@ -89,7 +89,7 @@ Guile support is complicated by a lack of user community cohesiveness,
which manifests in multiple shared-library usage conventions. A set of
policies implementing a usage convention is called a <b>linkage</b>.
<H3><a name="Guile_nn5">25.4.1 Simple Linkage</a></H3>
<H3><a name="Guile_nn5">26.4.1 Simple Linkage</a></H3>
<p>
@ -183,7 +183,7 @@ information by including a directive like this in the interface file:
</div>
<p>
(The <code>%scheme</code> directive allows to insert arbitrary Scheme
(The <code>%scheme</code> directive allows inserting arbitrary Scheme
code into the generated file <code><var>module.scm</var></code>; it is
placed between the <code>define-module</code> form and the
<code>export</code> form.)
@ -194,7 +194,7 @@ placed between the <code>define-module</code> form and the
<code>SWIG_init</code> via a preprocessor define to avoid symbol
clashes. For this case, however, passive linkage is available.
<H3><a name="Guile_nn6">25.4.2 Passive Linkage</a></H3>
<H3><a name="Guile_nn6">26.4.2 Passive Linkage</a></H3>
<p>Passive linkage is just like simple linkage, but it generates an
@ -204,7 +204,7 @@ package name (see below).
<p>You should use passive linkage rather than simple linkage when you
are using multiple modules.
<H3><a name="Guile_nn7">25.4.3 Native Guile Module Linkage</a></H3>
<H3><a name="Guile_nn7">26.4.3 Native Guile Module Linkage</a></H3>
<p>SWIG can also generate wrapper code that does all the Guile module
@ -245,7 +245,7 @@ Newer Guile versions have a shorthand procedure for this:
</div>
</ul>
<H3><a name="Guile_nn8">25.4.4 Old Auto-Loading Guile Module Linkage</a></H3>
<H3><a name="Guile_nn8">26.4.4 Old Auto-Loading Guile Module Linkage</a></H3>
<p>Guile used to support an autoloading facility for object-code
@ -271,7 +271,7 @@ option, SWIG generates an exported module initialization function with
an appropriate name.
<H3><a name="Guile_nn9">25.4.5 Hobbit4D Linkage</a></H3>
<H3><a name="Guile_nn9">26.4.5 Hobbit4D Linkage</a></H3>
<p>
@ -296,7 +296,7 @@ my/lib/libfoo.so.X.Y.Z and friends. This scheme is still very
experimental; the (hobbit4d link) conventions are not well understood.
</p>
<H2><a name="Guile_nn10">25.5 Underscore Folding</a></H2>
<H2><a name="Guile_nn10">26.5 Underscore Folding</a></H2>
<p>
@ -308,7 +308,7 @@ complained so far.
<code>%rename</code> to specify the Guile name of the wrapped
functions and variables (see CHANGES).
<H2><a name="Guile_nn11">25.6 Typemaps</a></H2>
<H2><a name="Guile_nn11">26.6 Typemaps</a></H2>
<p>
@ -400,7 +400,7 @@ constant will appear as a scheme variable. See
<a href="Customization.html#Customization_features">Features and the %feature directive</a>
for info on how to apply the %feature.</p>
<H2><a name="Guile_nn12">25.7 Representation of pointers as smobs</a></H2>
<H2><a name="Guile_nn12">26.7 Representation of pointers as smobs</a></H2>
<p>
@ -421,7 +421,7 @@ representing the expected pointer type. See also
If the Scheme object passed was not a SWIG smob representing a compatible
pointer, a <code>wrong-type-arg</code> exception is raised.
<H3><a name="Guile_nn14">25.7.1 Smobs</a></H3>
<H3><a name="Guile_nn14">26.7.1 Smobs</a></H3>
<p>
@ -440,7 +440,7 @@ structure describing this type. If a generated GOOPS module has been loaded, sm
the corresponding GOOPS class.</p>
<H3><a name="Guile_nn15">25.7.2 Garbage Collection</a></H3>
<H3><a name="Guile_nn15">26.7.2 Garbage Collection</a></H3>
<p>Garbage collection is a feature of Guile since version 1.6. As SWIG now requires Guile &gt; 1.8,
@ -454,14 +454,14 @@ is exactly like described in <a href="Customization.html#Customization_ownership
Object ownership and %newobject</a> in the SWIG manual. All typemaps use an $owner var, and
the guile module replaces $owner with 0 or 1 depending on feature:new.</p>
<H2><a name="Guile_nn16">25.8 Native Guile pointers</a></H2>
<H2><a name="Guile_nn16">26.8 Native Guile pointers</a></H2>
<p>
In addition to SWIG smob pointers, <a href="https://www.gnu.org/software/guile/manual/html_node/Foreign-Pointers.html">Guile's native pointer type</a> are accepted as arguments to wrapped SWIG functions. This can be useful for passing <a href="https://www.gnu.org/software/guile/manual/html_node/Void-Pointers-and-Byte-Access.html#">pointers to bytevector data</a> to wrapped functions.
</p>
<H2><a name="Guile_nn17">25.9 Exception Handling</a></H2>
<H2><a name="Guile_nn17">26.9 Exception Handling</a></H2>
<p>
@ -487,7 +487,7 @@ mapping:
The default when not specified here is to use "swig-error".
See Lib/exception.i for details.
<H2><a name="Guile_nn18">25.10 Procedure documentation</a></H2>
<H2><a name="Guile_nn18">26.10 Procedure documentation</a></H2>
<p>If invoked with the command-line option <code>-procdoc
@ -522,7 +522,7 @@ like this:
typemap argument <code>doc</code>. See <code>Lib/guile/typemaps.i</code> for
details.
<H2><a name="Guile_nn19">25.11 Procedures with setters</a></H2>
<H2><a name="Guile_nn19">26.11 Procedures with setters</a></H2>
<p>For global variables, SWIG creates a single wrapper procedure
@ -550,7 +550,7 @@ struct members, the procedures <code>(<var>struct</var>-<var>member</var>-get
pointer)</code> and <code>(<var>struct-member</var>-set pointer
value)</code> are <em>not</em> generated.
<H2><a name="Guile_nn20">25.12 GOOPS Proxy Classes</a></H2>
<H2><a name="Guile_nn20">26.12 GOOPS Proxy Classes</a></H2>
<p>SWIG can also generate classes and generic functions for use with
@ -696,7 +696,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_nn21">25.12.1 Naming Issues</a></H3>
<H3><a name="Guile_nn21">26.12.1 Naming Issues</a></H3>
<p>As you can see in the example above, there are potential naming conflicts. The default exported
@ -733,7 +733,7 @@ guile-modules. For example,</p>
(use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:)))
</pre></div>
<H3><a name="Guile_nn22">25.12.2 Linking</a></H3>
<H3><a name="Guile_nn22">26.12.2 Linking</a></H3>
<p>The guile-modules generated above all need to be linked together. GOOPS support requires

1
Doc/Manual/Introduction.html
View file

@ -416,6 +416,7 @@ major features include:
Most of C++11 is also supported. Details are in the <a href="CPlusPlus11.html#CPlusPlus11">C++11</a> chapter.
C++14 support is covered in the <a href="CPlusPlus14.html#CPlusPlus14">C++14</a> chapter.
C++17 support is covered in the <a href="CPlusPlus17.html#CPlusPlus17">C++17</a> chapter.
C++20 support is covered in the <a href="CPlusPlus20.html#CPlusPlus20">C++20</a> chapter.
</p>
<p>

237
Doc/Manual/Java.html
View file

@ -6,7 +6,7 @@
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="Java">26 SWIG and Java</a></H1>
<H1><a name="Java">27 SWIG and Java</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -167,7 +167,7 @@ It covers most SWIG features, but certain low-level details are covered in less
</p>
<H2><a name="Java_overview">26.1 Overview</a></H2>
<H2><a name="Java_overview">27.1 Overview</a></H2>
<p>
@ -202,7 +202,7 @@ Various customisation tips and techniques using SWIG directives are covered.
The latter sections cover the advanced techniques of using typemaps for complete control of the wrapping process.
</p>
<H2><a name="Java_preliminaries">26.2 Preliminaries</a></H2>
<H2><a name="Java_preliminaries">27.2 Preliminaries</a></H2>
<p>
@ -222,7 +222,7 @@ This is the commonly used method to load JNI code so your system will more than
Android uses Java JNI and also works with SWIG. Please read the <a href="Android.html#Android">Android chapter</a> in conjunction with this one if you are targeting Android.
</p>
<H3><a name="Java_running_swig">26.2.1 Running SWIG</a></H3>
<H3><a name="Java_running_swig">27.2.1 Running SWIG</a></H3>
<p>
@ -281,7 +281,7 @@ The following sections have further practical examples and details on how you mi
compiling and using the generated files.
</p>
<H3><a name="Java_commandline">26.2.2 Additional Commandline Options</a></H3>
<H3><a name="Java_commandline">27.2.2 Additional Commandline Options</a></H3>
<p>
@ -318,7 +318,7 @@ swig -java -help
Their use will become clearer by the time you have finished reading this section on SWIG and Java.
</p>
<H3><a name="Java_getting_right_headers">26.2.3 Getting the right header files</a></H3>
<H3><a name="Java_getting_right_headers">27.2.3 Getting the right header files</a></H3>
<p>
@ -333,7 +333,7 @@ They are usually in directories like this:</p>
<p>
The exact location may vary on your machine, but the above locations are typical. </p>
<H3><a name="Java_compiling_dynamic">26.2.4 Compiling a dynamic module</a></H3>
<H3><a name="Java_compiling_dynamic">27.2.4 Compiling a dynamic module</a></H3>
<p>
@ -368,7 +368,7 @@ The name of the shared library output file is important.
If the name of your SWIG module is "<tt>example</tt>", the name of the corresponding shared library file should be "<tt>libexample.so</tt>" (or equivalent depending on your machine, see <a href="#Java_dynamic_linking_problems">Dynamic linking problems</a> for more information).
The name of the module is specified using the <tt>%module</tt> directive or <tt>-module</tt> command line option.</p>
<H3><a name="Java_using_module">26.2.5 Using your module</a></H3>
<H3><a name="Java_using_module">27.2.5 Using your module</a></H3>
<p>
@ -403,7 +403,7 @@ $
If it doesn't work have a look at the following section which discusses problems loading the shared library.
</p>
<H3><a name="Java_dynamic_linking_problems">26.2.6 Dynamic linking problems</a></H3>
<H3><a name="Java_dynamic_linking_problems">27.2.6 Dynamic linking problems</a></H3>
<p>
@ -490,7 +490,7 @@ The following section also contains some C++ specific linking problems and solut
</p>
<H3><a name="Java_compilation_problems_cpp">26.2.7 Compilation problems and compiling with C++</a></H3>
<H3><a name="Java_compilation_problems_cpp">27.2.7 Compilation problems and compiling with C++</a></H3>
<p>
@ -542,7 +542,7 @@ Finally make sure the version of JDK header files matches the version of Java th
</p>
<H3><a name="Java_building_windows">26.2.8 Building on Windows</a></H3>
<H3><a name="Java_building_windows">27.2.8 Building on Windows</a></H3>
<p>
@ -551,7 +551,7 @@ You will want to produce a DLL that can be loaded by the Java Virtual Machine.
This section covers the process of using SWIG with Microsoft Visual C++ 6 although the procedure may be similar with other compilers.
In order for everything to work, you will need to have a JDK installed on your machine in order to read the JNI header files.</p>
<H4><a name="Java_visual_studio">26.2.8.1 Running SWIG from Visual Studio</a></H4>
<H4><a name="Java_visual_studio">27.2.8.1 Running SWIG from Visual Studio</a></H4>
<p>
@ -590,7 +590,7 @@ To run the native code in the DLL (example.dll), make sure that it is in your pa
If the library fails to load have a look at <a href="#Java_dynamic_linking_problems">Dynamic linking problems</a>.
</p>
<H4><a name="Java_nmake">26.2.8.2 Using NMAKE</a></H4>
<H4><a name="Java_nmake">27.2.8.2 Using NMAKE</a></H4>
<p>
@ -649,7 +649,7 @@ Of course you may want to make changes for it to work for C++ by adding in the -
</p>
<H2><a name="Java_basic_tour">26.3 A tour of basic C/C++ wrapping</a></H2>
<H2><a name="Java_basic_tour">27.3 A tour of basic C/C++ wrapping</a></H2>
<p>
@ -659,7 +659,7 @@ variables are wrapped with JavaBean type getters and setters and so forth.
This section briefly covers the essential aspects of this wrapping.
</p>
<H3><a name="Java_module_packages_classes">26.3.1 Modules, packages and generated Java classes</a></H3>
<H3><a name="Java_module_packages_classes">27.3.1 Modules, packages and generated Java classes</a></H3>
<p>
@ -695,7 +695,7 @@ swig -java -package com.bloggs.swig -outdir com/bloggs/swig example.i
SWIG won't create the directory, so make sure it exists beforehand.
</p>
<H3><a name="Java_functions">26.3.2 Functions</a></H3>
<H3><a name="Java_functions">27.3.2 Functions</a></H3>
<p>
@ -729,7 +729,7 @@ System.out.println(example.fact(4));
</pre></div>
<H3><a name="Java_global_variables">26.3.3 Global variables</a></H3>
<H3><a name="Java_global_variables">27.3.3 Global variables</a></H3>
<p>
@ -816,7 +816,7 @@ extern char *path; // Read-only (due to %immutable)
</div>
<H3><a name="Java_constants">26.3.4 Constants</a></H3>
<H3><a name="Java_constants">27.3.4 Constants</a></H3>
<p>
@ -956,7 +956,7 @@ Or if you decide this practice isn't so bad and your own class implements <tt>ex
</p>
<H3><a name="Java_enumerations">26.3.5 Enumerations</a></H3>
<H3><a name="Java_enumerations">27.3.5 Enumerations</a></H3>
<p>
@ -970,7 +970,7 @@ The final two approaches use simple integers for each enum item.
Before looking at the various approaches for wrapping named C/C++ enums, anonymous enums are considered.
</p>
<H4><a name="Java_anonymous_enums">26.3.5.1 Anonymous enums</a></H4>
<H4><a name="Java_anonymous_enums">27.3.5.1 Anonymous enums</a></H4>
<p>
@ -1033,7 +1033,7 @@ As in the case of constants, you can access them through either the module class
</p>
<H4><a name="Java_typesafe_enums">26.3.5.2 Typesafe enums</a></H4>
<H4><a name="Java_typesafe_enums">27.3.5.2 Typesafe enums</a></H4>
<p>
@ -1126,7 +1126,7 @@ When upgrading to JDK 1.5 or later, proper Java enums could be used instead, wit
The following section details proper Java enum generation.
</p>
<H4><a name="Java_proper_enums">26.3.5.3 Proper Java enums</a></H4>
<H4><a name="Java_proper_enums">27.3.5.3 Proper Java enums</a></H4>
<p>
@ -1179,7 +1179,7 @@ The additional support methods need not be generated if none of the enum items h
<a href="#Java_simpler_enum_classes">Simpler Java enums for enums without initializers</a> section.
</p>
<H4><a name="Java_typeunsafe_enums">26.3.5.4 Type unsafe enums</a></H4>
<H4><a name="Java_typeunsafe_enums">27.3.5.4 Type unsafe enums</a></H4>
<p>
@ -1227,7 +1227,7 @@ Note that unlike typesafe enums, this approach requires users to mostly use diff
Thus the upgrade path to proper enums provided in JDK 1.5 is more painful.
</p>
<H4><a name="Java_simple_enums">26.3.5.5 Simple enums</a></H4>
<H4><a name="Java_simple_enums">27.3.5.5 Simple enums</a></H4>
<p>
@ -1246,7 +1246,7 @@ SWIG-1.3.21 and earlier versions wrapped all enums using this approach.
The type unsafe approach is preferable to this one and this simple approach is only included for backwards compatibility with these earlier versions of SWIG.
</p>
<H3><a name="Java_pointers">26.3.6 Pointers</a></H3>
<H3><a name="Java_pointers">27.3.6 Pointers</a></H3>
<p>
@ -1334,7 +1334,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return
a NULL pointer if the conversion can't be performed.
</p>
<H3><a name="Java_structures">26.3.7 Structures</a></H3>
<H3><a name="Java_structures">27.3.7 Structures</a></H3>
<p>
@ -1502,7 +1502,7 @@ x.setA(3); // Modify x.a - this is the same as b.f.a
</div>
<H3><a name="Java_classes">26.3.8 C++ classes</a></H3>
<H3><a name="Java_classes">27.3.8 C++ classes</a></H3>
<p>
@ -1565,7 +1565,7 @@ int bar = Spam.getBar();
</div>
<H3><a name="Java_inheritance">26.3.9 C++ inheritance</a></H3>
<H3><a name="Java_inheritance">27.3.9 C++ inheritance</a></H3>
<p>
@ -1626,7 +1626,7 @@ Note that Java does not support multiple inheritance so any multiple inheritance
A warning is given when multiple inheritance is detected and only the first base class is used.
</p>
<H3><a name="Java_pointers_refs_arrays">26.3.10 Pointers, references, arrays and pass by value</a></H3>
<H3><a name="Java_pointers_refs_arrays">27.3.10 Pointers, references, arrays and pass by value</a></H3>
<p>
@ -1681,7 +1681,7 @@ to hold the result and a pointer is returned (Java will release this memory
when the returned object's finalizer is run by the garbage collector).
</p>
<H4><a name="Java_null_pointers">26.3.10.1 Null pointers</a></H4>
<H4><a name="Java_null_pointers">27.3.10.1 Null pointers</a></H4>
<p>
@ -1705,7 +1705,7 @@ For <tt>spam1</tt> and <tt>spam4</tt> above the Java <tt>null</tt> gets translat
The converse also occurs, that is, NULL pointers are translated into <tt>null</tt> Java objects when returned from a C/C++ function.
</p>
<H3><a name="Java_overloaded_functions">26.3.11 C++ overloaded functions</a></H3>
<H3><a name="Java_overloaded_functions">27.3.11 C++ overloaded functions</a></H3>
<p>
@ -1820,7 +1820,7 @@ void spam(unsigned short); // Ignored
</pre>
</div>
<H3><a name="Java_default_arguments">26.3.12 C++ default arguments</a></H3>
<H3><a name="Java_default_arguments">27.3.12 C++ default arguments</a></H3>
<p>
@ -1863,7 +1863,7 @@ Further details on default arguments and how to restore this approach are given
</p>
<H3><a name="Java_namespaces">26.3.13 C++ namespaces</a></H3>
<H3><a name="Java_namespaces">27.3.13 C++ namespaces</a></H3>
<p>
@ -1953,7 +1953,7 @@ If the resulting use of the nspace feature and hence packages results in a proxy
you will need to open up the visibility for the pointer constructor and <tt>getCPtr</tt> method from the default 'protected' to 'public' with the <tt>SWIG_JAVABODY_PROXY</tt> macro. See <a href="#Java_code_typemaps">Java code typemaps</a>.
</p>
<H3><a name="Java_templates">26.3.14 C++ templates</a></H3>
<H3><a name="Java_templates">27.3.14 C++ templates</a></H3>
<p>
@ -2002,10 +2002,10 @@ Obviously, there is more to template wrapping than shown in this example.
More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a> chapter.
</p>
<H3><a name="Java_smart_pointers">26.3.15 C++ Smart Pointers</a></H3>
<H3><a name="Java_smart_pointers">27.3.15 C++ Smart Pointers</a></H3>
<H4><a name="Java_smart_pointers_shared_ptr">26.3.15.1 The shared_ptr Smart Pointer</a></H4>
<H4><a name="Java_smart_pointers_shared_ptr">27.3.15.1 The shared_ptr Smart Pointer</a></H4>
<p>
@ -2016,7 +2016,7 @@ in the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a
</p>
<H4><a name="Java_smart_pointers_generic">26.3.15.2 Generic Smart Pointers</a></H4>
<H4><a name="Java_smart_pointers_generic">27.3.15.2 Generic Smart Pointers</a></H4>
<p>
@ -2100,7 +2100,7 @@ Foo f = p.__deref__(); // Returns underlying Foo *
</pre>
</div>
<H2><a name="Java_further_details">26.4 Further details on the generated Java classes</a></H2>
<H2><a name="Java_further_details">27.4 Further details on the generated Java classes</a></H2>
<p>
@ -2115,7 +2115,7 @@ Finally enum classes are covered.
First, the crucial intermediary JNI class is considered.
</p>
<H3><a name="Java_imclass">26.4.1 The intermediary JNI class</a></H3>
<H3><a name="Java_imclass">27.4.1 The intermediary JNI class</a></H3>
<p>
@ -2235,7 +2235,7 @@ If <tt>name</tt> is the same as <tt>modulename</tt> then the module class name g
from <tt>modulename</tt> to <tt>modulenameModule</tt>.
</p>
<H4><a name="Java_imclass_pragmas">26.4.1.1 The intermediary JNI class pragmas</a></H4>
<H4><a name="Java_imclass_pragmas">27.4.1.1 The intermediary JNI class pragmas</a></H4>
<p>
@ -2317,7 +2317,7 @@ For example, let's change the intermediary JNI class access to just the default
All the methods in the intermediary JNI class will then not be callable outside of the package as the method modifiers have been changed from public access to default access. This is useful if you want to prevent users calling these low level functions.
</p>
<H3><a name="Java_module_class">26.4.2 The Java module class</a></H3>
<H3><a name="Java_module_class">27.4.2 The Java module class</a></H3>
<p>
@ -2348,7 +2348,7 @@ example.egg(new Foo());
The primary reason for having the module class wrapping the calls in the intermediary JNI class is to implement static type checking. In this case only a <tt>Foo</tt> can be passed to the <tt>egg</tt> function, whereas any <tt>long</tt> can be passed to the <tt>egg</tt> function in the intermediary JNI class.
</p>
<H4><a name="Java_module_class_pragmas">26.4.2.1 The Java module class pragmas</a></H4>
<H4><a name="Java_module_class_pragmas">27.4.2.1 The Java module class pragmas</a></H4>
<p>
@ -2399,7 +2399,7 @@ See <a href="#Java_imclass_pragmas">The intermediary JNI class pragmas</a> secti
</p>
<H3><a name="Java_proxy_classes">26.4.3 Java proxy classes</a></H3>
<H3><a name="Java_proxy_classes">27.4.3 Java proxy classes</a></H3>
<p>
@ -2475,7 +2475,7 @@ int y = f.spam(5, new Foo());
</pre>
</div>
<H4><a name="Java_memory_management">26.4.3.1 Memory management</a></H4>
<H4><a name="Java_memory_management">27.4.3.1 Memory management</a></H4>
<p>
@ -2637,7 +2637,7 @@ and
</p>
<H4><a name="Java_inheritance_mirroring">26.4.3.2 Inheritance</a></H4>
<H4><a name="Java_inheritance_mirroring">27.4.3.2 Inheritance</a></H4>
<p>
@ -2753,7 +2753,7 @@ However, true cross language polymorphism can be achieved using the <a href="#Ja
</p>
<H4><a name="Java_proxy_classes_gc">26.4.3.3 Proxy classes and garbage collection</a></H4>
<H4><a name="Java_proxy_classes_gc">27.4.3.3 Proxy classes and garbage collection</a></H4>
<p>
@ -2836,7 +2836,7 @@ The section on <a href="#Java_typemaps">Java typemaps</a> details how to specify
See the <a href="http://www.devx.com/Java/Article/30192">How to Handle Java Finalization's Memory-Retention Issues</a> article for alternative approaches to managing memory by avoiding finalizers altogether.
</p>
<H4><a name="Java_pgcpp">26.4.3.4 The premature garbage collection prevention parameter for proxy class marshalling</a></H4>
<H4><a name="Java_pgcpp">27.4.3.4 The premature garbage collection prevention parameter for proxy class marshalling</a></H4>
<p>
@ -2958,7 +2958,7 @@ For example:
<b>Compatibility note:</b> The generation of this additional parameter did not occur in versions prior to SWIG-1.3.30.
</p>
<H4><a name="Java_multithread_libraries">26.4.3.5 Single threaded applications and thread safety</a></H4>
<H4><a name="Java_multithread_libraries">27.4.3.5 Single threaded applications and thread safety</a></H4>
<p>
@ -3046,7 +3046,7 @@ for (int i=0; i&lt;100000; i++) {
</pre></div>
<H3><a name="Java_type_wrapper_classes">26.4.4 Type wrapper classes</a></H3>
<H3><a name="Java_type_wrapper_classes">27.4.4 Type wrapper classes</a></H3>
<p>
@ -3133,7 +3133,7 @@ public static void spam(SWIGTYPE_p_int x, SWIGTYPE_p_int y, int z) { ... }
</div>
<H3><a name="Java_enum_classes">26.4.5 Enum classes</a></H3>
<H3><a name="Java_enum_classes">27.4.5 Enum classes</a></H3>
<p>
@ -3142,7 +3142,7 @@ The <a href="#Java_enumerations">Enumerations</a> section discussed these but om
The following sub-sections detail the various types of enum classes that can be generated.
</p>
<H4><a name="Java_typesafe_enums_classes">26.4.5.1 Typesafe enum classes</a></H4>
<H4><a name="Java_typesafe_enums_classes">27.4.5.1 Typesafe enum classes</a></H4>
<p>
@ -3226,7 +3226,7 @@ The <tt>swigValue</tt> method is used for marshalling in the other direction.
The <tt>toString</tt> method is overridden so that the enum name is available.
</p>
<H4><a name="Java_proper_enums_classes">26.4.5.2 Proper Java enum classes</a></H4>
<H4><a name="Java_proper_enums_classes">27.4.5.2 Proper Java enum classes</a></H4>
<p>
@ -3304,7 +3304,7 @@ These needn't be generated if the enum being wrapped does not have any initializ
<a href="#Java_simpler_enum_classes">Simpler Java enums for enums without initializers</a> section describes how typemaps can be used to achieve this.
</p>
<H4><a name="Java_typeunsafe_enums_classes">26.4.5.3 Type unsafe enum classes</a></H4>
<H4><a name="Java_typeunsafe_enums_classes">27.4.5.3 Type unsafe enum classes</a></H4>
<p>
@ -3335,7 +3335,7 @@ public final class Beverage {
</pre>
</div>
<H3><a name="Java_interfaces">26.4.6 Interfaces</a></H3>
<H3><a name="Java_interfaces">27.4.6 Interfaces</a></H3>
<p>
@ -3580,7 +3580,7 @@ typemap which is only used when a class is marked with the <tt>interface</tt> fe
See <a href="Java.html#Java_code_typemaps">Java code typemaps</a> for details.
</p>
<H2><a name="Java_directors">26.5 Cross language polymorphism using directors</a></H2>
<H2><a name="Java_directors">27.5 Cross language polymorphism using directors</a></H2>
<p>
@ -3602,7 +3602,7 @@ The upshot is that C++ classes can be extended in Java and from C++ these extens
Neither C++ code nor Java code needs to know where a particular method is implemented: the combination of proxy classes, director classes, and C wrapper functions transparently takes care of all the cross-language method routing.
</p>
<H3><a name="Java_enabling_directors">26.5.1 Enabling directors</a></H3>
<H3><a name="Java_enabling_directors">27.5.1 Enabling directors</a></H3>
<p>
@ -3670,7 +3670,7 @@ public:
</pre>
</div>
<H3><a name="Java_directors_classes">26.5.2 Director classes</a></H3>
<H3><a name="Java_directors_classes">27.5.2 Director classes</a></H3>
<p>
@ -3698,7 +3698,7 @@ If the correct implementation is in Java, the Java API is used to call the metho
</p>
<H3><a name="Java_directors_overhead">26.5.3 Overhead and code bloat</a></H3>
<H3><a name="Java_directors_overhead">27.5.3 Overhead and code bloat</a></H3>
<p>
@ -3716,7 +3716,7 @@ This situation can be optimized by selectively enabling director methods (using
</p>
<H3><a name="Java_directors_example">26.5.4 Simple directors example</a></H3>
<H3><a name="Java_directors_example">27.5.4 Simple directors example</a></H3>
<p>
@ -3779,7 +3779,7 @@ DirectorDerived.upcall_method() invoked.
</pre>
</div>
<H3><a name="Java_directors_threading">26.5.5 Director threading issues</a></H3>
<H3><a name="Java_directors_threading">27.5.5 Director threading issues</a></H3>
<p>
@ -3799,7 +3799,7 @@ Macros can be defined on the commandline when compiling your C++ code, or altern
</pre>
</div>
<H3><a name="Java_directors_performance">26.5.6 Director performance tuning</a></H3>
<H3><a name="Java_directors_performance">27.5.6 Director performance tuning</a></H3>
<p>
@ -3820,7 +3820,7 @@ However, if all director methods are expected to usually be overridden by Java s
The disadvantage is that invocation of director methods from C++ when Java doesn't actually override the method will require an additional call up into Java and back to C++. As such, this option is only useful when overrides are extremely common and instantiation is frequent enough that its performance is critical.
</p>
<H3><a name="Java_exceptions_from_directors">26.5.7 Java exceptions from directors</a></H3>
<H3><a name="Java_exceptions_from_directors">27.5.7 Java exceptions from directors</a></H3>
<p>
@ -3896,7 +3896,7 @@ Exception in thread "main" java.lang.RuntimeException: There was a problem!
More on the <tt>Swig::DirectorException</tt> class can be found in the next section which details how to customize the handling of director exceptions.
</p>
<H4><a name="Java_customizing_director_exceptions">26.5.7.1 Customizing director exceptions</a></H4>
<H4><a name="Java_customizing_director_exceptions">27.5.7.1 Customizing director exceptions</a></H4>
<p>
@ -4030,7 +4030,7 @@ repetitive duplication of the <code>director:except</code> feature code
for each director method.
To mitigate this, a second approach is provided via typemaps in a
fashion analogous to
the <a href="Typemaps.html#throws_typemap">"throws" typemap</a>.
the <a href="Typemaps.html#Typemaps_throws_typemap">"throws" typemap</a>.
The "throws" typemap provides a way to map all the C++
exceptions listed in a method's defined exceptions (either from
a C++ <em>exception specification</em> or a <code>%catches</code>
@ -4081,7 +4081,7 @@ has the <code>$directorthrowshandlers</code> special variable replaced with the
the relevant "directorthrows" typemaps, for each and every exception defined for the method.
The relevant exceptions can be defined either with a C++ exception
specification or <code>%catches</code> as described for the
<a href="Typemaps.html#throws_typemap">"throws" typemap</a>.
<a href="Typemaps.html#Typemaps_throws_typemap">"throws" typemap</a>.
</p>
<p>
@ -4454,7 +4454,7 @@ Exception in thread "main" java.lang.IndexOutOfBoundsException: Index is negativ
</pre>
</div>
<H2><a name="Java_allprotected">26.6 Accessing protected members</a></H2>
<H2><a name="Java_allprotected">27.6 Accessing protected members</a></H2>
<p>
@ -4550,7 +4550,7 @@ class MyProtectedBase extends ProtectedBase
<H2><a name="Java_common_customization">26.7 Common customization features</a></H2>
<H2><a name="Java_common_customization">27.7 Common customization features</a></H2>
<p>
@ -4562,7 +4562,7 @@ be awkward. This section describes some common SWIG features that are used
to improve the interface to existing C/C++ code.
</p>
<H3><a name="Java_helper_functions">26.7.1 C/C++ helper functions</a></H3>
<H3><a name="Java_helper_functions">27.7.1 C/C++ helper functions</a></H3>
<p>
@ -4628,7 +4628,7 @@ hard to implement. It is possible to improve on this using Java code, typemaps,
customization features as covered in later sections, but sometimes helper functions are a quick and easy solution to difficult cases.
</p>
<H3><a name="Java_class_extension">26.7.2 Class extension with %extend</a></H3>
<H3><a name="Java_class_extension">27.7.2 Class extension with %extend</a></H3>
<p>
@ -4691,7 +4691,7 @@ Vector(2, 3, 4)
in any way---the extensions only show up in the Java interface.
</p>
<H3><a name="Java_proxycode">26.7.3 Class extension with %proxycode</a></H3>
<H3><a name="Java_proxycode">27.7.3 Class extension with %proxycode</a></H3>
<p>
@ -4828,7 +4828,7 @@ public class ValueUnsignedInt {
</pre>
</div>
<H3><a name="Java_exception_handling">26.7.4 Exception handling with %exception and %javaexception</a></H3>
<H3><a name="Java_exception_handling">27.7.4 Exception handling with %exception and %javaexception</a></H3>
<p>
@ -4987,7 +4987,7 @@ to raise exceptions. See the <a href="Library.html#Library">SWIG Library</a> ch
The typemap example <a href="#Java_exception_typemap">Handling C++ exception specifications as Java exceptions</a> provides further exception handling capabilities.
</p>
<H3><a name="Java_method_access">26.7.5 Method access with %javamethodmodifiers</a></H3>
<H3><a name="Java_method_access">27.7.5 Method access with %javamethodmodifiers</a></H3>
<p>
@ -5013,7 +5013,7 @@ protected static void protect_me() {
</pre>
</div>
<H2><a name="Java_tips_techniques">26.8 Tips and techniques</a></H2>
<H2><a name="Java_tips_techniques">27.8 Tips and techniques</a></H2>
<p>
@ -5023,7 +5023,7 @@ strings and arrays. This chapter discusses the common techniques for
solving these problems.
</p>
<H3><a name="Java_input_output_parameters">26.8.1 Input and output parameters using primitive pointers and references</a></H3>
<H3><a name="Java_input_output_parameters">27.8.1 Input and output parameters using primitive pointers and references</a></H3>
<p>
@ -5197,7 +5197,7 @@ void foo(Bar *OUTPUT);
will not have the intended effect since <tt>typemaps.i</tt> does not define an OUTPUT rule for <tt>Bar</tt>.
</p>
<H3><a name="Java_simple_pointers">26.8.2 Simple pointers</a></H3>
<H3><a name="Java_simple_pointers">27.8.2 Simple pointers</a></H3>
<p>
@ -5263,7 +5263,7 @@ System.out.println("3 + 4 = " + result);
See the <a href="Library.html#Library">SWIG Library</a> chapter for further details.
</p>
<H3><a name="Java_c_arrays">26.8.3 Wrapping C arrays with Java arrays</a></H3>
<H3><a name="Java_c_arrays">27.8.3 Wrapping C arrays with Java arrays</a></H3>
<p>
@ -5330,7 +5330,7 @@ Please be aware that the typemaps in this library are not efficient as all the e
There is an alternative approach using the SWIG array library and this is covered in the next section.
</p>
<H3><a name="Java_unbounded_c_arrays">26.8.4 Unbounded C Arrays</a></H3>
<H3><a name="Java_unbounded_c_arrays">27.8.4 Unbounded C Arrays</a></H3>
<p>
@ -5475,7 +5475,7 @@ well suited for applications in which you need to create buffers,
package binary data, etc.
</p>
<H3><a name="Java_binary_char">26.8.5 Binary data vs Strings</a></H3>
<H3><a name="Java_binary_char">27.8.5 Binary data vs Strings</a></H3>
<p>
@ -5519,7 +5519,7 @@ len: 5 data: 68 69 0 6a 6b
</pre></div>
<H3><a name="Java_heap_allocations">26.8.6 Overriding new and delete to allocate from Java heap</a></H3>
<H3><a name="Java_heap_allocations">27.8.6 Overriding new and delete to allocate from Java heap</a></H3>
<p>
@ -5636,7 +5636,7 @@ model and use these functions in place of malloc and free in your own
code.
</p>
<H2><a name="Java_typemaps">26.9 Java typemaps</a></H2>
<H2><a name="Java_typemaps">27.9 Java typemaps</a></H2>
<p>
@ -5657,7 +5657,7 @@ Before proceeding, it should be stressed that typemaps are not a required
part of using SWIG---the default wrapping behavior is enough in most cases.
Typemaps are only used if you want to change some aspect of the generated code.
<H3><a name="Java_default_primitive_type_mappings">26.9.1 Default primitive type mappings</a></H3>
<H3><a name="Java_default_primitive_type_mappings">27.9.1 Default primitive type mappings</a></H3>
<p>
@ -5809,7 +5809,7 @@ However, the mappings allow the full range of values for each C type from Java.
</p>
<H3><a name="Java_default_non_primitive_typemaps">26.9.2 Default typemaps for non-primitive types</a></H3>
<H3><a name="Java_default_non_primitive_typemaps">27.9.2 Default typemaps for non-primitive types</a></H3>
<p>
@ -5824,7 +5824,7 @@ So in summary, the C/C++ pointer to non-primitive types is cast into the 64 bit
The Java type is either the proxy class or type wrapper class.
</p>
<H3><a name="Java_jvm64">26.9.3 Sixty four bit JVMs</a></H3>
<H3><a name="Java_jvm64">27.9.3 Sixty four bit JVMs</a></H3>
<p>
@ -5837,7 +5837,7 @@ Unfortunately it won't of course hold true for JNI code.
</p>
<H3><a name="Java_what_is_typemap">26.9.4 What is a typemap?</a></H3>
<H3><a name="Java_what_is_typemap">27.9.4 What is a typemap?</a></H3>
<p>
@ -5960,7 +5960,7 @@ int c = example.count('e', "Hello World");
</pre>
</div>
<H3><a name="Java_typemaps_c_to_java_types">26.9.5 Typemaps for mapping C/C++ types to Java types</a></H3>
<H3><a name="Java_typemaps_c_to_java_types">27.9.5 Typemaps for mapping C/C++ types to Java types</a></H3>
<p>
@ -6240,7 +6240,7 @@ These are listed below:
</table>
<H3><a name="Java_typemap_attributes">26.9.6 Java typemap attributes</a></H3>
<H3><a name="Java_typemap_attributes">27.9.6 Java typemap attributes</a></H3>
<p>
@ -6286,7 +6286,7 @@ The "javain" typemap has the optional 'pre', 'post' and 'pgcppname' attributes.
Note that when the 'pre' or 'post' attributes are specified and the associated type is used in a constructor, a constructor helper function is generated. This is necessary as the Java proxy constructor wrapper makes a call to a support constructor using a <i>this</i> call. In Java the <i>this</i> call must be the first statement in the constructor body. The constructor body thus calls the helper function and the helper function instead makes the JNI call, ensuring the 'pre' code is called before the JNI call is made. There is a <a href="#Java_date_marshalling">Date marshalling</a> example showing 'pre', 'post' and 'pgcppname' attributes in action.
</p>
<H3><a name="Java_special_variables">26.9.7 Java special variables</a></H3>
<H3><a name="Java_special_variables">27.9.7 Java special variables</a></H3>
<p>
@ -6468,7 +6468,7 @@ in that it is not fully qualified with the package name when using the
<a href="SWIGPlus.html#SWIGPlus_nspace">nspace feature</a>.
</p>
<H3><a name="Java_typemaps_for_c_and_cpp">26.9.8 Typemaps for both C and C++ compilation</a></H3>
<H3><a name="Java_typemaps_for_c_and_cpp">27.9.8 Typemaps for both C and C++ compilation</a></H3>
<p>
@ -6505,7 +6505,7 @@ If you do not intend your code to be targeting both C and C++ then your typemaps
</p>
<H3><a name="Java_code_typemaps">26.9.9 Java code typemaps</a></H3>
<H3><a name="Java_code_typemaps">27.9.9 Java code typemaps</a></H3>
<p>
@ -6610,6 +6610,15 @@ Below shows an example modifying the finalizer, assuming the <tt>delete</tt> met
</div>
<p><tt>%typemap(javainterfacemodifiers)</tt></p>
<div class="indent">
Interface modifiers for the Java interface generated when using the <tt>interface</tt> feature, see <a href="Java.html#Java_interfaces">Java interfaces</a> section. The default is "public interface".
<p>
<b>Compatibility note:</b> This typemap was added in SWIG-4.1.0.
</p>
</div>
<p><tt>%typemap(javainterfacecode, declaration="...", cptrmethod="...")</tt></p>
<div class="indent">
<p>
@ -6709,7 +6718,7 @@ The "javaimports" typemap is ignored if the enum class is wrapped by an inner Ja
<div class="code">
<pre>
[ javaimports typemap ]
public interface [ javainterfacename ] {
[ javainterfacemodifiers typemap ] [ javainterfacename ] {
[ javainterfacecode:cptrmethod typemap attribute ]
... interface declarations ...
}
@ -6803,7 +6812,7 @@ to make the method and constructor public:
</pre>
</div>
<H3><a name="Java_directors_typemaps">26.9.10 Director specific typemaps</a></H3>
<H3><a name="Java_directors_typemaps">27.9.10 Director specific typemaps</a></H3>
<p>
@ -7080,7 +7089,7 @@ The basic strategy here is to provide a default package typemap for the majority
</div>
<H2><a name="Java_typemap_examples">26.10 Typemap Examples</a></H2>
<H2><a name="Java_typemap_examples">27.10 Typemap Examples</a></H2>
<p>
@ -7090,7 +7099,7 @@ the SWIG library.
</p>
<H3><a name="Java_simpler_enum_classes">26.10.1 Simpler Java enums for enums without initializers</a></H3>
<H3><a name="Java_simpler_enum_classes">27.10.1 Simpler Java enums for enums without initializers</a></H3>
<p>
@ -7169,7 +7178,7 @@ This would be done by using the original versions of these typemaps in "enums.sw
</p>
<H3><a name="Java_exception_typemap">26.10.2 Handling C++ exception specifications as Java exceptions</a></H3>
<H3><a name="Java_exception_typemap">27.10.2 Handling C++ exception specifications as Java exceptions</a></H3>
<p>
@ -7294,7 +7303,7 @@ We could alternatively have used <tt>%rename</tt> to rename <tt>what()</tt> into
</p>
<H3><a name="Java_nan_exception_typemap">26.10.3 NaN Exception - exception handling for a particular type</a></H3>
<H3><a name="Java_nan_exception_typemap">27.10.3 NaN Exception - exception handling for a particular type</a></H3>
<p>
@ -7449,7 +7458,7 @@ If we were a martyr to the JNI cause, we could replace the succinct code within
If we had, we would have put it in the "in" typemap which, like all JNI and Java typemaps, also supports the 'throws' attribute.
</p>
<H3><a name="Java_converting_java_string_arrays">26.10.4 Converting Java String arrays to char ** </a></H3>
<H3><a name="Java_converting_java_string_arrays">27.10.4 Converting Java String arrays to char ** </a></H3>
<p>
@ -7593,7 +7602,7 @@ Lastly the "jni", "jtype" and "jstype" typemaps are also required to specify
what Java types to use.
</p>
<H3><a name="Java_expanding_java_object">26.10.5 Expanding a Java object to multiple arguments</a></H3>
<H3><a name="Java_expanding_java_object">27.10.5 Expanding a Java object to multiple arguments</a></H3>
<p>
@ -7675,7 +7684,7 @@ example.foo(new String[]{"red", "green", "blue", "white"});
</div>
<H3><a name="Java_using_typemaps_return_arguments">26.10.6 Using typemaps to return arguments</a></H3>
<H3><a name="Java_using_typemaps_return_arguments">27.10.6 Using typemaps to return arguments</a></H3>
<p>
@ -7793,7 +7802,7 @@ $ java runme
1 12.0 340.0
</pre></div>
<H3><a name="Java_adding_downcasts">26.10.7 Adding Java downcasts to polymorphic return types</a></H3>
<H3><a name="Java_adding_downcasts">27.10.7 Adding Java downcasts to polymorphic return types</a></H3>
<p>
@ -7999,7 +8008,7 @@ SWIG usually generates code which constructs the proxy classes using Java code a
Note that the JNI code above uses a number of string lookups to call a constructor, whereas this would not occur using byte compiled Java code.
</p>
<H3><a name="Java_adding_equals_method">26.10.8 Adding an equals method to the Java classes</a></H3>
<H3><a name="Java_adding_equals_method">27.10.8 Adding an equals method to the Java classes</a></H3>
<p>
@ -8043,7 +8052,7 @@ System.out.println("foo1? " + foo1.equals(foo2));
</div>
<H3><a name="Java_void_pointers">26.10.9 Void pointers and a common Java base class</a></H3>
<H3><a name="Java_void_pointers">27.10.9 Void pointers and a common Java base class</a></H3>
<p>
@ -8102,7 +8111,7 @@ This example contains some useful functionality which you may want in your code.
<li> It also has a function which effectively implements a cast from the type of the proxy/type wrapper class to a void pointer. This is necessary for passing a proxy class or a type wrapper class to a function that takes a void pointer.
</ul>
<H3><a name="Java_struct_pointer_pointer">26.10.10 Struct pointer to pointer</a></H3>
<H3><a name="Java_struct_pointer_pointer">27.10.10 Struct pointer to pointer</a></H3>
<p>
@ -8282,7 +8291,7 @@ The C functional interface has been completely morphed into an object-oriented i
the Butler class would behave much like any pure Java class and feel more natural to Java users.
</p>
<H3><a name="Java_memory_management_member_variables">26.10.11 Memory management when returning references to member variables</a></H3>
<H3><a name="Java_memory_management_member_variables">27.10.11 Memory management when returning references to member variables</a></H3>
<p>
@ -8405,7 +8414,7 @@ public class Bike {
Note the <tt>addReference</tt> call.
</p>
<H3><a name="Java_memory_management_objects">26.10.12 Memory management for objects passed to the C++ layer</a></H3>
<H3><a name="Java_memory_management_objects">27.10.12 Memory management for objects passed to the C++ layer</a></H3>
<p>
@ -8533,7 +8542,7 @@ as mentioned earlier, <tt>setElement</tt> is actually:
</pre>
</div>
<H3><a name="Java_date_marshalling">26.10.13 Date marshalling using the javain typemap and associated attributes</a></H3>
<H3><a name="Java_date_marshalling">27.10.13 Date marshalling using the javain typemap and associated attributes</a></H3>
<p>
@ -8710,7 +8719,7 @@ A few things to note:
<H2><a name="Java_directors_faq">26.11 Living with Java Directors</a></H2>
<H2><a name="Java_directors_faq">27.11 Living with Java Directors</a></H2>
<p>
@ -8889,10 +8898,10 @@ public abstract class UserVisibleFoo extends Foo {
</li>
</ol>
<H2><a name="Java_odds_ends">26.12 Odds and ends</a></H2>
<H2><a name="Java_odds_ends">27.12 Odds and ends</a></H2>
<H3><a name="Java_javadoc_comments">26.12.1 JavaDoc comments</a></H3>
<H3><a name="Java_javadoc_comments">27.12.1 JavaDoc comments</a></H3>
<p>
@ -8948,7 +8957,7 @@ public class Barmy {
<H3><a name="Java_functional_interface">26.12.2 Functional interface without proxy classes</a></H3>
<H3><a name="Java_functional_interface">27.12.2 Functional interface without proxy classes</a></H3>
<p>
@ -9009,7 +9018,7 @@ All destructors have to be called manually for example the <tt>delete_Foo(foo)</
</p>
<H3><a name="Java_using_own_jni_functions">26.12.3 Using your own JNI functions</a></H3>
<H3><a name="Java_using_own_jni_functions">27.12.3 Using your own JNI functions</a></H3>
<p>
@ -9059,7 +9068,7 @@ This directive is only really useful if you want to mix your own hand crafted JN
</p>
<H3><a name="Java_performance">26.12.4 Performance concerns and hints</a></H3>
<H3><a name="Java_performance">27.12.4 Performance concerns and hints</a></H3>
<p>
@ -9080,13 +9089,13 @@ However, you will have to be careful about memory management and make sure that
This method normally calls the C++ destructor or <tt>free()</tt> for C code.
</p>
<H3><a name="Java_debugging">26.12.5 Debugging</a></H3>
<H3><a name="Java_debugging">27.12.5 Debugging</a></H3>
<p>
The generated code can be debugged using both a Java debugger and a C++ debugger using the usual debugging techniques.
Breakpoints can be set in either Java or C++ code and so both can be debugged simultaneously.
Most debuggers do not understand both Java and C++, with one noteable exception of Sun Studio,
Most debuggers do not understand both Java and C++, with one notable exception of Sun Studio,
where it is possible to step from Java code into a JNI method within one environment.
</p>
@ -9102,7 +9111,7 @@ The -verbose:jni and -verbose:gc are also useful options for monitoring code beh
</p>
<H2><a name="Java_examples">26.13 Java Examples</a></H2>
<H2><a name="Java_examples">27.13 Java Examples</a></H2>
<p>

63
Doc/Manual/Javascript.html
View file

@ -7,7 +7,7 @@
</head>
<body>
<H1><a name="Javascript">27 SWIG and Javascript</a></H1>
<H1><a name="Javascript">28 SWIG and Javascript</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -52,7 +52,7 @@
<p>This chapter describes SWIG's support of Javascript. It does not cover SWIG basics, but only information that is specific to this module.</p>
<H2><a name="Javascript_overview">27.1 Overview</a></H2>
<H2><a name="Javascript_overview">28.1 Overview</a></H2>
<p>Javascript is a prototype-based scripting language that is dynamic, weakly typed and has first-class functions. Its arguably the most popular language for web development.
@ -63,10 +63,10 @@ Javascript has gone beyond being a browser-based scripting language and with <a
With <a href="https://github.com/rogerwang/node-webkit">node-webkit</a> there is a platform which uses Google's <code>Chromium</code> as Web-Browser widget and <code>node.js</code> for javascript extensions.
</p>
<H2><a name="Javascript_preliminaries">27.2 Preliminaries</a></H2>
<H2><a name="Javascript_preliminaries">28.2 Preliminaries</a></H2>
<H3><a name="Javascript_running_swig">27.2.1 Running SWIG</a></H3>
<H3><a name="Javascript_running_swig">28.2.1 Running SWIG</a></H3>
<p>Suppose that you defined a SWIG module such as the following:</p>
@ -89,19 +89,10 @@ $ swig -javascript -jsc example.i</pre>
<pre>
$ swig -c++ -javascript -jsc example.i</pre>
</div>
<p>The V8 code that SWIG generates should work with most versions from 3.11.10 up to 3.29.14 and later.</p>
<p>The API headers for V8 &gt;= 4.3.0 define constants which SWIG can use to
determine the V8 version it is compiling for. For versions &lt; 4.3.0, you
need to specify the V8 version when running SWIG. This is specified as a hex
constant, but the constant is read as pairs of decimal digits, so for V8
3.25.30 use constant 0x032530. This scheme can't represent components &gt; 99,
but this constant is only useful for V8 &lt; 4.3.0, and no V8 versions from
that era had a component &gt; 99. For example:</p>
<div class="shell">
<pre>
$ swig -c++ -javascript -v8 -DV8_VERSION=0x032530 example.i</pre>
</div>
<p>If you're targeting V8 &gt;= 4.3.0, you would just run swig like so:</p>
<p>The V8 code that SWIG generates requires at least V8 5.0. Keep in mind
that this is theV8 version, not Node.js. To give some perspective, Node.js v6.0
uses V8 5.0, v12.0 - 7.4, v14.0 - 8.1...</p>
<p>To generate code for V8, you would run swig like so:</p>
<div class="shell">
<pre>
$ swig -c++ -javascript -v8 example.i</pre>
@ -121,7 +112,7 @@ void example_initialize(v8::Handle&lt;v8::Object&gt; exports)</pre>
<b>Note</b>: be aware that <code>v8</code> has a C++ API, and thus, the generated modules must be compiled as C++.
</p>
<H3><a name="Javascript_running_tests_examples">27.2.2 Running Tests and Examples</a></H3>
<H3><a name="Javascript_running_tests_examples">28.2.2 Running Tests and Examples</a></H3>
<p>The configuration for tests and examples currently supports Linux and Mac only and not MinGW (Windows) yet.</p>
@ -153,7 +144,7 @@ $ make check-javascript-test-suite ENGINE=jsc</pre>
$ make check-javascript-examples V8_VERSION=0x032530 ENGINE=v8</pre>
</div>
<H3><a name="Javascript_known_issues">27.2.3 Known Issues</a></H3>
<H3><a name="Javascript_known_issues">28.2.3 Known Issues</a></H3>
<p>At the moment, the Javascript generators pass all tests syntactically, i.e., the generated source code compiles. However, there are still remaining runtime issues.</p>
@ -169,12 +160,12 @@ $ make check-javascript-examples V8_VERSION=0x032530 ENGINE=v8</pre>
<p>The primary development environment has been Linux (Ubuntu 12.04). Windows and Mac OS X have been tested sporadically. Therefore, the generators might have more issues on those platforms. Please report back any problem you observe to help us improving this module quickly.</p>
<H2><a name="Javascript_integration">27.3 Integration</a></H2>
<H2><a name="Javascript_integration">28.3 Integration</a></H2>
<p>This chapter gives a short introduction how to use a native Javascript extension: as a <code>node.js</code> module, and as an extension for an embedded Webkit.</p>
<H3><a name="Javascript_node_extensions">27.3.1 Creating node.js Extensions</a></H3>
<H3><a name="Javascript_node_extensions">28.3.1 Creating node.js Extensions</a></H3>
<p>To install <code>node.js</code> you can download an installer from their <a href="https://launchpad.net/~chris-lea/+archive/node.js">web-site</a> for Mac OS X and Windows. For Linux you can either build the source yourself and run <code>sudo checkinstall</code> or keep to the (probably stone-age) packaged version. For Ubuntu there is a <a href="https://launchpad.net/~chris-lea/+archive/ubuntu/node.js/">PPA</a> available.</p>
@ -220,7 +211,7 @@ require("./build/Release/example")</pre>
</div>
<p>A more detailed explanation is given in the <a href="#Javascript_examples">Examples</a> section.</p>
<H4><a name="Javascript_troubleshooting">27.3.1.1 Troubleshooting</a></H4>
<H4><a name="Javascript_troubleshooting">28.3.1.1 Troubleshooting</a></H4>
<ul>
@ -232,12 +223,12 @@ require("./build/Release/example")</pre>
$ sudo apt-get remove gyp</pre>
</div>
<H3><a name="Javascript_embedded_webkit">27.3.2 Embedded Webkit</a></H3>
<H3><a name="Javascript_embedded_webkit">28.3.2 Embedded Webkit</a></H3>
<p>Webkit is pre-installed on Mac OS X and available as a library for GTK.</p>
<H4><a name="Javascript_osx">27.3.2.1 Mac OS X</a></H4>
<H4><a name="Javascript_osx">28.3.2.1 Mac OS X</a></H4>
<p>There is general information about programming with WebKit on <a href="https://developer.apple.com/library/mac/documentation/cocoa/conceptual/DisplayWebContent/DisplayWebContent.html">Apple Developer Documentation</a>. Details about <code>Cocoa</code> programming are not covered here.</p>
@ -285,7 +276,7 @@ extern bool example_initialize(JSGlobalContextRef context, JSObjectRef* exports)
@end</pre>
</div>
<H4><a name="Javascript_gtk">27.3.2.2 GTK</a></H4>
<H4><a name="Javascript_gtk">28.3.2.2 GTK</a></H4>
<p>There is general information about programming GTK at <a href="https://developer.gnome.org/gtk2/">GTK documentation</a> and in the <a href="https://developer.gnome.org/gtk-tutorial/">GTK tutorial</a>, and for Webkit there is a <a href="http://webkitgtk.org/reference/webkitgtk/stable/index.html">Webkit GTK+ API Reference</a>.</p>
@ -330,7 +321,7 @@ int main(int argc, char* argv[])
}</pre>
</div>
<H3><a name="Javascript_applications_webkit">27.3.3 Creating Applications with node-webkit</a></H3>
<H3><a name="Javascript_applications_webkit">28.3.3 Creating Applications with node-webkit</a></H3>
<p>To get started with <code>node-webkit</code> there is a very informative set of <a href="https://github.com/rogerwang/node-webkit/wiki">wiki pages</a>.</p>
@ -401,7 +392,7 @@ the main window.</p>
<p>
As known from <code>node.js</code> one can use <code>require</code> to load javascript modules.
Additionally, <code>node-webkit</code> provides an API that allows to manipulate the window's menu,
Additionally, <code>node-webkit</code> provides an API that allows manipulating the window's menu,
open new windows, and many more things.
</p>
@ -421,12 +412,12 @@ open new windows, and many more things.
};</pre>
</div>
<H2><a name="Javascript_examples">27.4 Examples</a></H2>
<H2><a name="Javascript_examples">28.4 Examples</a></H2>
<p>Some basic examples are shown here in more detail.</p>
<H3><a name="Javascript_simple_example">27.4.1 Simple</a></H3>
<H3><a name="Javascript_simple_example">28.4.1 Simple</a></H3>
<p>The common example <code>simple</code> looks like this:</p>
@ -476,7 +467,7 @@ example.Foo = 3.1415926;</pre>
<p><b>Note</b>: ECMAScript 5, the currently implemented Javascript standard, does not have modules. <code>node.js</code> and other implementations provide this mechanism defined by the <a href="http://wiki.commonjs.org/wiki/CommonJS">CommonJS</a> group. For browsers this is provided by <a href="http://browserify.org">Browserify</a>, for instance.</p>
<H3><a name="Javascript_class_example">27.4.2 Class</a></H3>
<H3><a name="Javascript_class_example">28.4.2 Class</a></H3>
<p>The common example <code>class</code> defines three classes, <code>Shape</code>, <code>Circle</code>, and <code>Square</code>:</p>
@ -606,12 +597,12 @@ at emitKey (readline.js:1095:12)</pre>
<b>Note</b>: In ECMAScript 5 there is no concept for classes. Instead each function can be used as a constructor function which is executed by the 'new' operator. Furthermore, during construction the key property <code>prototype</code> of the constructor function is used to attach a prototype instance to the created object. A prototype is essentially an object itself that is the first-class delegate of a class used whenever the access to a property of an object fails. The very same prototype instance is shared among all instances of one type. Prototypal inheritance is explained in more detail on in <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain">Inheritance and the prototype chain</a>, for instance.
</p>
<H2><a name="Javascript_implementation">27.5 Implementation</a></H2>
<H2><a name="Javascript_implementation">28.5 Implementation</a></H2>
<p>The Javascript Module implementation has taken a very different approach compared to other language modules in order to support different Javascript interpreters.</p>
<H3><a name="Javascript_source_code">27.5.1 Source Code</a></H3>
<H3><a name="Javascript_source_code">28.5.1 Source Code</a></H3>
<p>The Javascript module is implemented in <code>Source/Modules/javascript.cxx</code>. It dispatches the code generation to a <code>JSEmitter</code> instance, <code>V8Emitter</code> or <code>JSCEmitter</code>. Additionally there are some helpers: <code>Template</code>, for templated code generation, and <code>JSEmitterState</code>, which is used to manage state information during AST traversal. This rough map shall make it easier to find a way through this huge source file:</p>
@ -712,7 +703,7 @@ Template::Template(const String *code_) { ... }
...</pre>
</div>
<H3><a name="Javascript_code_templates">27.5.2 Code Templates</a></H3>
<H3><a name="Javascript_code_templates">28.5.2 Code Templates</a></H3>
<p>All generated code is created on the basis of code templates. The templates for <em>JavascriptCore</em> can be found in <code>Lib/javascript/jsc/javascriptcode.swg</code>, for <em>v8</em> in <code>Lib/javascript/v8/javascriptcode.swg</code>.</p>
@ -751,7 +742,7 @@ t_register.replace("$jsparent", state.clazz(NAME_MANGLED))
</div>
<p><code>Template</code> creates a copy of that string and <code>Template::replace</code> uses Swig's <code>Replaceall</code> to replace variables in the template. <code>Template::trim</code> can be used to eliminate leading and trailing whitespaces. <code>Template::print</code> is used to write the final template string to a Swig <code>DOH</code> (based on <code>Printv</code>). All methods allow chaining.</p>
<H3><a name="Javascript_emitter">27.5.3 Emitter</a></H3>
<H3><a name="Javascript_emitter">28.5.3 Emitter</a></H3>
<p>The Javascript module delegates code generation to a <code>JSEmitter</code> instance. The following extract shows the essential interface:</p>
@ -870,7 +861,7 @@ int JAVASCRIPT::classHandler(Node *n) {
</div>
<p>In <code>enterClass</code> the emitter stores state information that is necessary when processing class members. In <code>exitClass</code> the wrapper code for the whole class is generated.</p>
<H3><a name="Javascript_emitter_states">27.5.4 Emitter states</a></H3>
<H3><a name="Javascript_emitter_states">28.5.4 Emitter states</a></H3>
<p>For storing information during the AST traversal the emitter provides a <code>JSEmitterState</code> with different slots to store data representing the scopes global, class, function, and variable.</p>
@ -914,7 +905,7 @@ state.clazz(NAME, Getattr(n, "sym:name"));</pre>
<p>State information can be retrieved using <code>state.clazz(NAME)</code> or with <code>Getattr</code> on <code>state.clazz()</code> which actually returns a <code>Hash</code> instance.</p>
<H3><a name="Javascript_jsc_exceptions">27.5.5 Handling Exceptions in JavascriptCore</a></H3>
<H3><a name="Javascript_jsc_exceptions">28.5.5 Handling Exceptions in JavascriptCore</a></H3>
<p>Applications with an embedded JavascriptCore should be able to present detailed exception messages that occur in the Javascript engine. Below is an example derived from code provided by Brian Barnes on how these exception details can be extracted.</p>

50
Doc/Manual/Library.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Library">11 SWIG library</a></H1>
<H1><a name="Library">12 SWIG library</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -67,7 +67,7 @@ Alternative libraries provide similar functionality. Please read this chapter
carefully if you used the old libraries.
</p>
<H2><a name="Library_nn2">11.1 The %include directive and library search path</a></H2>
<H2><a name="Library_nn2">12.1 The %include directive and library search path</a></H2>
<p>
@ -99,7 +99,7 @@ Set the environment variable to hold an alternative library directory.
The directories that are searched are displayed when using <tt>-verbose</tt> commandline option.
</p>
<H2><a name="Library_nn3">11.2 C arrays and pointers</a></H2>
<H2><a name="Library_nn3">12.2 C arrays and pointers</a></H2>
<p>
@ -111,7 +111,7 @@ pointers as class-like objects. Since these functions provide direct access to
memory, their use is potentially unsafe and you should exercise caution.
</p>
<H3><a name="Library_nn4">11.2.1 cpointer.i</a></H3>
<H3><a name="Library_nn4">12.2.1 cpointer.i</a></H3>
<p>
@ -327,7 +327,7 @@ In this example, the function <tt>int_to_uint()</tt> would be used to cast type
<b>Note:</b> When working with simple pointers, typemaps can often be used to provide more seamless operation.
</p>
<H3><a name="Library_carrays">11.2.2 carrays.i</a></H3>
<H3><a name="Library_carrays">12.2.2 carrays.i</a></H3>
<p>
@ -506,7 +506,7 @@ used with types of <tt>char</tt> or <tt>char *</tt>.
SWIG's default handling of these types is to handle them as character strings and the two macros do not do enough to change this.
</p>
<H3><a name="Library_nn6">11.2.3 cmalloc.i</a></H3>
<H3><a name="Library_nn6">12.2.3 cmalloc.i</a></H3>
<p>
@ -667,7 +667,7 @@ Now, in a script:
</pre>
</div>
<H3><a name="Library_nn7">11.2.4 cdata.i</a></H3>
<H3><a name="Library_nn7">12.2.4 cdata.i</a></H3>
<p>
@ -769,7 +769,7 @@ char *cdata_<em>name</em>(type* ptr, int nitems)
Clearly they are unsafe.
</p>
<H2><a name="Library_nn8">11.3 C string handling</a></H2>
<H2><a name="Library_nn8">12.3 C string handling</a></H2>
<p>
@ -789,7 +789,7 @@ morality. The modules in this section provide basic functionality
for manipulating raw C strings.
</p>
<H3><a name="Library_nn9">11.3.1 Default string handling</a></H3>
<H3><a name="Library_nn9">12.3.1 Default string handling</a></H3>
<p>
@ -830,7 +830,7 @@ interpreter and lead to a crash). Furthermore, the default behavior does
not work well with binary data. Instead, strings are assumed to be NULL-terminated.
</p>
<H3><a name="Library_nn10">11.3.2 Passing binary data</a></H3>
<H3><a name="Library_nn10">12.3.2 Passing binary data</a></H3>
<p>
@ -872,7 +872,7 @@ In the wrapper function, the passed string will be expanded to a pointer and len
The <tt>(char *STRING, int LENGTH)</tt> multi-argument typemap is also available in addition to <tt>(char *STRING, size_t LENGTH)</tt>.
</p>
<H3><a name="Library_nn11">11.3.3 Using %newobject to release memory</a></H3>
<H3><a name="Library_nn11">12.3.3 Using %newobject to release memory</a></H3>
<p>
@ -913,7 +913,7 @@ however, you may need to provide your own "newfree" typemap for other types.
See <a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for more details.
</p>
<H3><a name="Library_nn12">11.3.4 cstring.i</a></H3>
<H3><a name="Library_nn12">12.3.4 cstring.i</a></H3>
<p>
@ -1373,7 +1373,7 @@ structure or class instead.
</li>
</ul>
<H2><a name="Library_stl_cpp_library">11.4 STL/C++ library</a></H2>
<H2><a name="Library_stl_cpp_library">12.4 STL/C++ library</a></H2>
<p>
@ -1420,7 +1420,7 @@ Please look for the library files in the appropriate language library directory.
</p>
<H3><a name="Library_std_string">11.4.1 std::string</a></H3>
<H3><a name="Library_std_string">12.4.1 std::string</a></H3>
<p>
@ -1504,7 +1504,7 @@ void foo(string s, const String &amp;t); // std_string typemaps still applie
</pre>
</div>
<H3><a name="Library_std_vector">11.4.2 std::vector</a></H3>
<H3><a name="Library_std_vector">12.4.2 std::vector</a></H3>
<p>
@ -1683,7 +1683,7 @@ if you want to make their head explode.
details and the public API exposed to the interpreter vary.
</p>
<H3><a name="Library_stl_exceptions">11.4.3 STL exceptions</a></H3>
<H3><a name="Library_stl_exceptions">12.4.3 STL exceptions</a></H3>
<p>
@ -1733,10 +1733,10 @@ The <tt>%exception</tt> directive can be used by placing the following code befo
Any thrown STL exceptions will then be gracefully handled instead of causing a crash.
</p>
<H3><a name="Library_std_shared_ptr">11.4.4 shared_ptr smart pointer</a></H3>
<H3><a name="Library_std_shared_ptr">12.4.4 shared_ptr smart pointer</a></H3>
<H4><a name="Library_shared_ptr_basics">11.4.4.1 shared_ptr basics</a></H4>
<H4><a name="Library_shared_ptr_basics">12.4.4.1 shared_ptr basics</a></H4>
<p>
@ -1832,7 +1832,7 @@ System.out.println(val1 + " " + val2);
</pre>
</div>
<H4><a name="Library_shared_ptr_inheritance">11.4.4.2 shared_ptr and inheritance</a></H4>
<H4><a name="Library_shared_ptr_inheritance">12.4.4.2 shared_ptr and inheritance</a></H4>
<p>
@ -1923,7 +1923,7 @@ Adding the missing <tt>%shared_ptr</tt> macros will fix this:
</pre>
</div>
<H4><a name="Library_shared_ptr_overloading">11.4.4.3 shared_ptr and method overloading</a></H4>
<H4><a name="Library_shared_ptr_overloading">12.4.4.3 shared_ptr and method overloading</a></H4>
<p>
@ -1945,7 +1945,7 @@ SWIG will choose to wrap just the first method by default.
For the interested reader, SWIG detects that they are equivalent types via the <a href=Typemaps.html#Typemaps_typecheck_pointer>typecheck typemaps</a> in the shared_ptr library.
</p>
<H4><a name="Library_shared_ptr_templates">11.4.4.4 shared_ptr and templates</a></H4>
<H4><a name="Library_shared_ptr_templates">12.4.4.4 shared_ptr and templates</a></H4>
<p>
@ -1987,7 +1987,7 @@ The SWIG code below shows the required ordering:
</pre>
</div>
<H4><a name="Library_shared_ptr_directors">11.4.4.5 shared_ptr and directors</a></H4>
<H4><a name="Library_shared_ptr_directors">12.4.4.5 shared_ptr and directors</a></H4>
<p>
@ -1995,7 +1995,7 @@ The languages that support shared_ptr also have support for using shared_ptr wit
</p>
<H3><a name="Library_std_auto_ptr">11.4.5 auto_ptr smart pointer</a></H3>
<H3><a name="Library_std_auto_ptr">12.4.5 auto_ptr smart pointer</a></H3>
<p>
@ -2044,10 +2044,10 @@ int value = k.getValue();
</pre>
</div>
<H2><a name="Library_nn16">11.5 Utility Libraries</a></H2>
<H2><a name="Library_nn16">12.5 Utility Libraries</a></H2>
<H3><a name="Library_nn17">11.5.1 exception.i</a></H3>
<H3><a name="Library_nn17">12.5.1 exception.i</a></H3>
<p>

108
Doc/Manual/Lua.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Lua">28 SWIG and Lua</a></H1>
<H1><a name="Lua">29 SWIG and Lua</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -83,14 +83,14 @@ Lua is an extension programming language designed to support general procedural
eLua stands for Embedded Lua (can be thought of as a flavor of Lua) and offers the full implementation of the Lua programming language to the embedded world, extending it with specific features for efficient and portable software embedded development. eLua runs on smaller devices like microcontrollers and provides the full features of the regular Lua desktop version. More information on eLua can be found here: <a href="http://www.eluaproject.net">http://www.eluaproject.net</a>
</p>
<H2><a name="Lua_nn2">28.1 Preliminaries</a></H2>
<H2><a name="Lua_nn2">29.1 Preliminaries</a></H2>
<p>
The current SWIG implementation is designed to work with Lua 5.0.x, 5.1.x and 5.2.x. It should work with later versions of Lua, but certainly not with Lua 4.0 due to substantial API changes. It is possible to either static link or dynamic link a Lua module into the interpreter (normally Lua static links its libraries, as dynamic linking is not available on all platforms). SWIG also has support for eLua starting from eLua 0.8. Due to substantial changes between SWIG 2.x and SWIG 3.0 and unavailability of testing platform, eLua status was downgraded to 'experimental'.
</p>
<H2><a name="Lua_nn3">28.2 Running SWIG</a></H2>
<H2><a name="Lua_nn3">29.2 Running SWIG</a></H2>
<p>
@ -138,14 +138,14 @@ $ swig -lua -eluac example.i
The <tt>-elua</tt> option puts all the C function wrappers and variable get/set wrappers in rotables. It also generates a metatable which will control the access to these variables from eLua. It also offers a significant amount of module size compression. On the other hand, the <tt>-eluac</tt> option puts all the wrappers in a single rotable. With this option, no matter how huge the module, it will consume no additional microcontroller SRAM (crass compression). There is a catch though: Metatables are not generated with <tt>-eluac</tt>. To access any value from eLua, one must directly call the wrapper function associated with that value.
</p>
<H3><a name="Lua_commandline">28.2.1 Additional command line options</a></H3>
<H3><a name="Lua_commandline">29.2.1 Additional command line options</a></H3>
<p>
The following table list the additional commandline options available for the Lua module. They can also be seen by using:
</p>
<div class="code"><pre>
<div class="shell"><pre>
swig -lua -help
</pre></div>
@ -179,7 +179,7 @@ swig -lua -help
</tr>
</table>
<H3><a name="Lua_nn4">28.2.2 Compiling and Linking and Interpreter</a></H3>
<H3><a name="Lua_nn4">29.2.2 Compiling and Linking and Interpreter</a></H3>
<p>
@ -250,7 +250,7 @@ LUALIB_API int ( luaopen_mod )(lua_State *L );
More information on building and configuring eLua can be found here: <a href="http://www.eluaproject.net/doc/v0.8/en_building.html">http://www.eluaproject.net/doc/v0.8/en_building.html</a>
</p>
<H3><a name="Lua_nn5">28.2.3 Compiling a dynamic module</a></H3>
<H3><a name="Lua_nn5">29.2.3 Compiling a dynamic module</a></H3>
<p>
@ -318,7 +318,7 @@ Is quite obvious (Go back and consult the Lua documents on how to enable loadlib
<H3><a name="Lua_nn6">28.2.4 Using your module</a></H3>
<H3><a name="Lua_nn6">29.2.4 Using your module</a></H3>
<p>
@ -336,19 +336,19 @@ $ ./my_lua
&gt;
</pre></div>
<H2><a name="Lua_nn7">28.3 A tour of basic C/C++ wrapping</a></H2>
<H2><a name="Lua_nn7">29.3 A tour of basic C/C++ wrapping</a></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">28.3.1 Modules</a></H3>
<H3><a name="Lua_nn8">29.3.1 Modules</a></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">28.3.2 Functions</a></H3>
<H3><a name="Lua_nn9">29.3.2 Functions</a></H3>
<p>
@ -389,7 +389,7 @@ It is also possible to rename the module with an assignment.
24
</pre></div>
<H3><a name="Lua_nn10">28.3.3 Global variables</a></H3>
<H3><a name="Lua_nn10">29.3.3 Global variables</a></H3>
<p>
@ -477,7 +477,7 @@ If you have used the <tt>-eluac</tt> option for your eLua module, you will have
In general, functions of the form <tt>"variable_get()"</tt> and <tt>"variable_set()"</tt> are automatically generated by SWIG for use with <tt>-eluac</tt>.
</p>
<H3><a name="Lua_nn11">28.3.4 Constants and enums</a></H3>
<H3><a name="Lua_nn11">29.3.4 Constants and enums</a></H3>
<p>
@ -512,7 +512,7 @@ If you're using eLua and have used <tt>-elua</tt> or <tt>-eluac</tt> to generate
Hello World
</pre></div>
<H4><a name="Lua_nn13">28.3.4.1 Constants/enums and classes/structures</a></H4>
<H4><a name="Lua_nn13">29.3.4.1 Constants/enums and classes/structures</a></H4>
<p>
@ -568,7 +568,7 @@ If the <tt>-no-old-metatable-bindings</tt> option is used, then these old-style
It is worth mentioning, that <tt>example.Test.TEST1</tt> and <tt>example.Test_TEST1</tt> are different entities and changing one does not change the other.
Given the fact that these are constantes and they are not supposed to be changed, it is up to you to avoid such issues.
</p>
<H3><a name="Lua_nn12">28.3.5 Pointers</a></H3>
<H3><a name="Lua_nn12">29.3.5 Pointers</a></H3>
<p>
@ -606,7 +606,7 @@ Lua enforces the integrity of its userdata, so it is virtually impossible to cor
nil
</pre></div>
<H3><a name="Lua_structures">28.3.6 Structures</a></H3>
<H3><a name="Lua_structures">29.3.6 Structures</a></H3>
<p>
@ -710,7 +710,7 @@ For eLua with the <tt>-eluac</tt> option, structure manipulation has to be perfo
In general, functions of the form <tt>"new_struct()"</tt>, <tt>"struct_member_get()"</tt>, <tt>"struct_member_set()"</tt> and <tt>"free_struct()"</tt> are automatically generated by SWIG for each structure defined in C. (Please note: This doesn't apply for modules generated with the <tt>-elua</tt> option)
</p>
<H3><a name="Lua_nn14">28.3.7 C++ classes</a></H3>
<H3><a name="Lua_nn14">29.3.7 C++ classes</a></H3>
<p>
@ -747,7 +747,8 @@ Stout
<p>
Class data members are accessed in the same manner as C structures. Static class members present a special problem for Lua, as Lua doesn't have support for such features. Therefore, SWIG generates wrappers that try to work around some of these issues. To illustrate, suppose you have a class like this:
</p>
<div class="targetlang"><pre>class Spam {
<div class="code"><pre>
class Spam {
public:
static void foo();
static int bar;
@ -756,7 +757,7 @@ public:
<p>
In Lua, C++ static members can be accessed as follows:
</p>
<div class="code"><pre>
<div class="targetlang"><pre>
&gt; example.Spam.foo() -- calling Spam::foo()
&gt; a=example.Spam.bar -- reading Spam::bar
&gt; example.Spam.bar=b -- writing to Spam::bar
@ -774,7 +775,7 @@ It is not (currently) possible to access static members of an instance:
<b>Compatibility Note:</b> In versions prior to SWIG-3.0.0 only the following names would work:
</p>
<div class="code"><pre>
<div class="targetlang"><pre>
&gt; example.Spam_foo() -- calling Spam::foo()
&gt; a=example.Spam_bar -- reading Spam::bar
&gt; example.Spam_bar=b -- writing to Spam::bar
@ -785,7 +786,7 @@ Both style names are generated by default now.
However, if the <tt>-no-old-metatable-bindings</tt> option is used, then the backward compatible names are not generated in addition to ordinary ones.
</p>
<H3><a name="Lua_nn15">28.3.8 C++ inheritance</a></H3>
<H3><a name="Lua_nn15">29.3.8 C++ inheritance</a></H3>
<p>
@ -810,7 +811,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">28.3.9 Pointers, references, values, and arrays</a></H3>
<H3><a name="Lua_nn16">29.3.9 Pointers, references, values, and arrays</a></H3>
<p>
@ -841,7 +842,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">28.3.10 C++ overloaded functions</a></H3>
<H3><a name="Lua_nn17">29.3.10 C++ overloaded functions</a></H3>
<p>
@ -927,7 +928,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">28.3.11 C++ operators</a></H3>
<H3><a name="Lua_nn18">29.3.11 C++ operators</a></H3>
<p>
@ -964,7 +965,8 @@ When wrapped, it works like you expect:
<p>
One restriction with operator overloading support is that SWIG is not able to fully handle operators that aren't defined as part of the class. For example, if you had code like this
</p>
<div class="targetlang"><pre>class Complex {
<div class="code"><pre>
class Complex {
...
friend Complex operator+(double, const Complex &amp;c);
...
@ -973,7 +975,8 @@ friend Complex operator+(double, const Complex &amp;c);
<p>
then SWIG doesn't know what to do with the friend function--in fact, it simply ignores it and issues a warning. You can still wrap the operator, but you may have to encapsulate it in a special function. For example:
</p>
<div class="targetlang"><pre>%rename(Complex_add_dc) operator+(double, const Complex &amp;);
<div class="code"><pre>
%rename(Complex_add_dc) operator+(double, const Complex &amp;);
...
Complex operator+(double, const Complex &amp;c);
</pre></div>
@ -1059,7 +1062,7 @@ operators and pseudo-operators):</p>
</ul>
<p>No other lua metafunction is inherited. For example, __gc is not inherited and must be redefined in every class. <tt>__tostring</tt> is subject to a special handling. If absent in class and in class bases, a default one will be provided by SWIG.
</p>
<H3><a name="Lua_nn19">28.3.12 Class extension with %extend</a></H3>
<H3><a name="Lua_nn19">29.3.12 Class extension with %extend</a></H3>
<p>
@ -1116,7 +1119,7 @@ true
Extend works with both C and C++ code, on classes and structs. It does not modify the underlying object in any way---the extensions only show up in the Lua interface. The only item to take note of is the code has to use the '$self' instead of 'this', and that you cannot access protected/private members of the code (as you are not officially part of the class).
</p>
<H3><a name="Lua_nn20">28.3.13 Using %newobject to release memory</a></H3>
<H3><a name="Lua_nn20">29.3.13 Using %newobject to release memory</a></H3>
<p> If you have a function that allocates memory like this,</p>
@ -1140,7 +1143,7 @@ char *foo();
</div>
<p> This will release the allocated memory.</p>
<H3><a name="Lua_nn21">28.3.14 C++ templates</a></H3>
<H3><a name="Lua_nn21">29.3.14 C++ templates</a></H3>
<p>
@ -1175,7 +1178,7 @@ In Lua:
<p>
Obviously, there is more to template wrapping than shown in this example. More details can be found in the SWIG and C++ chapter. Some more complicated examples will appear later.
</p>
<H3><a name="Lua_nn22">28.3.15 C++ Smart Pointers</a></H3>
<H3><a name="Lua_nn22">29.3.15 C++ Smart Pointers</a></H3>
<p>
@ -1227,7 +1230,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_nn23">28.3.16 C++ Exceptions</a></H3>
<H3><a name="Lua_nn23">29.3.16 C++ Exceptions</a></H3>
<p>
@ -1370,7 +1373,7 @@ and the "<a href="Customization.html#Customization_exception">Exception handling
add exception specification to functions or globally (respectively).
</p>
<H3><a name="Lua_namespaces">28.3.17 Namespaces </a></H3>
<H3><a name="Lua_namespaces">29.3.17 Namespaces </a></H3>
<p>
@ -1421,7 +1424,7 @@ Now, from Lua usage is as follows:
19
&gt;
</pre></div>
<H4><a name="Lua_nn27">28.3.17.1 Compatibility Note </a></H4>
<H4><a name="Lua_nn27">29.3.17.1 Compatibility Note </a></H4>
<p>
@ -1437,7 +1440,7 @@ If SWIG is running in a backwards compatible way, i.e. without the <tt>-no-old-m
</pre></div>
<H4><a name="Lua_nn29">28.3.17.2 Names </a></H4>
<H4><a name="Lua_nn29">29.3.17.2 Names </a></H4>
<p> If SWIG is launched without <tt>-no-old-metatable-bindings</tt> option, then it enters backward-compatible mode. While in this mode, it tries
@ -1446,6 +1449,7 @@ Those names are in a form <tt>$classname_$symbolname</tt> and are added to the s
If %nspace is enabled, then class namespace is taken as scope. If there is no namespace, or %nspace is disabled,
then module is considered a class namespace.</p>
<p> Consider the following C++ code </p>
<div class="code"><pre>%module example
%nspace MyWorld::Test;
namespace MyWorld {
@ -1481,11 +1485,12 @@ surrounding scope without any prefixing. Pretending that Test2 is a struct, not
&gt;
</pre></div>
<H4><a name="Lua_nn30">28.3.17.3 Inheritance </a></H4>
<H4><a name="Lua_nn30">29.3.17.3 Inheritance </a></H4>
<p> The internal organization of inheritance has changed.
Consider the following C++ code:</p>
<div class="code"><pre>%module example
class Base {
public:
@ -1502,6 +1507,7 @@ were squashed and added to corresponding derived class <tt>ST</tt>: Everything f
was copied to <tt>.fn</tt> table of class Derived and so on. This was a recursive procedure, so in the end the whole
inheritance tree of derived class was squashed into derived class. </p>
<p> That means that any changes done to class Base after module initialization wouldn't affect class Derived:</p>
<div class="targetlang"><pre>
base = example.Base()
der = example.Derived()
@ -1516,18 +1522,20 @@ nil
</pre></div>
<p> This behaviour was changed. Now unless -squash-bases option is provided, Derived store a list of it's bases and if some symbol is not found in it's own service tables
then its bases are searched for it. Option -squash-bases will effectively return old behaviour.
</p>
<div class="targetlang"><pre>
&gt; print(der.new_func) -- Now it works
function
&gt;
</pre></div>
<H2><a name="Lua_nn24">28.4 Typemaps</a></H2>
<H2><a name="Lua_nn24">29.4 Typemaps</a></H2>
<p>This section explains what typemaps are and how to use them. The default wrapping behaviour of SWIG is enough in most cases. However sometimes SWIG may need a little additional assistance to know which typemap to apply to provide the best wrapping. This section will be explaining how to use typemaps to best effect</p>
<H3><a name="Lua_nn25">28.4.1 What is a typemap?</a></H3>
<H3><a name="Lua_nn25">29.4.1 What is a typemap?</a></H3>
<p>A typemap is nothing more than a code generation rule that is attached to a specific C datatype. For example, to convert integers from Lua to C, you might define a typemap like this:</p>
@ -1555,7 +1563,7 @@ Received an integer : 6
720
</pre></div>
<H3><a name="Lua_nn26">28.4.2 Using typemaps</a></H3>
<H3><a name="Lua_nn26">29.4.2 Using typemaps</a></H3>
<p>There are many ready written typemaps built into SWIG for all common types (int, float, short, long, char*, enum and more), which SWIG uses automatically, with no effort required on your part.</p>
@ -1608,7 +1616,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_typemap_arrays">28.4.3 Typemaps and arrays</a></H3>
<H3><a name="Lua_typemap_arrays">29.4.3 Typemaps and arrays</a></H3>
<p>Arrays present a challenge for SWIG, because like pointers SWIG does not know whether these are input or output values, nor
@ -1672,7 +1680,7 @@ and Lua tables to be 1..N, (the indexing follows the norm for the language). In
<p>Note: SWIG also can support arrays of pointers in a similar manner.</p>
<H3><a name="Lua_typemaps_ptr_ptr_functions">28.4.4 Typemaps and pointer-pointer functions</a></H3>
<H3><a name="Lua_typemaps_ptr_ptr_functions">29.4.4 Typemaps and pointer-pointer functions</a></H3>
<p>Several C++ libraries use a pointer-pointer functions to create its objects. These functions require a pointer to a pointer which is then filled with the pointer to the new object. Microsoft's COM and DirectX as well as many other libraries have this kind of function. An example is given below:</p>
@ -1706,7 +1714,7 @@ int Create_Math(iMath** pptr); // its creator (assume it mallocs)
ptr=nil -- the iMath* will be GC'ed as normal
</pre></div>
<H2><a name="Lua_writing_typemaps">28.5 Writing typemaps</a></H2>
<H2><a name="Lua_writing_typemaps">29.5 Writing typemaps</a></H2>
<p>This section describes how you can modify SWIG's default wrapping behavior for various C/C++ datatypes using the <tt>%typemap</tt> directive. This is an advanced topic that assumes familiarity with the Lua C API as well as the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter.</p>
@ -1715,7 +1723,7 @@ ptr=nil -- the iMath* will be GC'ed as normal
<p>Before proceeding, you should read the previous section on using typemaps, and look at the existing typemaps found in luatypemaps.swg and typemaps.i. These are both well documented and fairly easy to read. You should not attempt to write your own typemaps until you have read and can understand both of these files (they may well also give you an idea to base your work on).</p>
<H3><a name="Lua_typemaps_write">28.5.1 Typemaps you can write</a></H3>
<H3><a name="Lua_typemaps_write">29.5.1 Typemaps you can write</a></H3>
<p>There are many different types of typemap that can be written, the full list can be found in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. However the following are the most commonly used ones.</p>
@ -1728,7 +1736,7 @@ ptr=nil -- the iMath* will be GC'ed as normal
(the syntax for the typecheck is different from the typemap, see typemaps for details).</li>
</ul>
<H3><a name="Lua_nn31">28.5.2 SWIG's Lua-C API</a></H3>
<H3><a name="Lua_nn31">29.5.2 SWIG's Lua-C API</a></H3>
<p>This section explains the SWIG specific Lua-C API. It does not cover the main Lua-C api, as this is well documented and not worth covering.</p>
@ -1777,7 +1785,7 @@ This macro, when called within the context of a SWIG wrapped function, will disp
<div class="indent">
Similar to SWIG_fail_arg, except that it will display the swig_type_info information instead.</div>
<H2><a name="Lua_nn32">28.6 Customization of your Bindings</a></H2>
<H2><a name="Lua_nn32">29.6 Customization of your Bindings</a></H2>
<p>
@ -1786,7 +1794,7 @@ This section covers adding of some small extra bits to your module to add the la
<H3><a name="Lua_nn33">28.6.1 Writing your own custom wrappers</a></H3>
<H3><a name="Lua_nn33">29.6.1 Writing your own custom wrappers</a></H3>
<p>
@ -1805,7 +1813,7 @@ int native_function(lua_State*L) // my native code
The <tt>%native</tt> directive in the above example, tells SWIG that there is a function <tt>int native_function(lua_State*L);</tt> which is to be added into the module under the name '<tt>my_func</tt>'. SWIG will not add any wrapper for this function, beyond adding it into the function table. How you write your code is entirely up to you.
</p>
<H3><a name="Lua_nn34">28.6.2 Adding additional Lua code</a></H3>
<H3><a name="Lua_nn34">29.6.2 Adding additional Lua code</a></H3>
<p>
@ -1843,7 +1851,7 @@ Good uses for this feature is adding of new code, or writing helper functions to
See Examples/lua/arrays for an example of this code.
</p>
<H2><a name="Lua_nn35">28.7 Details on the Lua binding</a></H2>
<H2><a name="Lua_nn35">29.7 Details on the Lua binding</a></H2>
<p>
@ -1854,7 +1862,7 @@ See Examples/lua/arrays for an example of this code.
</i>
</p>
<H3><a name="Lua_nn36">28.7.1 Binding global data into the module.</a></H3>
<H3><a name="Lua_nn36">29.7.1 Binding global data into the module.</a></H3>
<p>
@ -1914,7 +1922,7 @@ end
<p>
That way when you call '<tt>a=example.Foo</tt>', the interpreter looks at the table 'example' sees that there is no field 'Foo' and calls __index. This will in turn check in '.get' table and find the existence of 'Foo' and then return the value of the C function call 'Foo_get()'. Similarly for the code '<tt>example.Foo=10</tt>', the interpreter will check the table, then call the __newindex which will then check the '.set' table and call the C function 'Foo_set(10)'.
</p>
<H3><a name="Lua_nn37">28.7.2 Userdata and Metatables</a></H3>
<H3><a name="Lua_nn37">29.7.2 Userdata and Metatables</a></H3>
<p>
@ -1994,7 +2002,7 @@ Note: Both the opaque structures (like the FILE*) and normal wrapped classes/str
<p>
Note: Operator overloads are basically done in the same way, by adding functions such as '__add' &amp; '__call' to the class' metatable. The current implementation is a bit rough as it will add any member function beginning with '__' into the metatable too, assuming its an operator overload.
</p>
<H3><a name="Lua_nn38">28.7.3 Memory management</a></H3>
<H3><a name="Lua_nn38">29.7.3 Memory management</a></H3>
<p>

942
Doc/Manual/Modula3.html
View file

@ -1,942 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and Modula-3</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="Modula3">31 SWIG and Modula-3</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Modula3_modula3_overview">Overview</a>
<ul>
<li><a href="#Modula3_motivation">Motivation</a>
</ul>
<li><a href="#Modula3_conception">Conception</a>
<ul>
<li><a href="#Modula3_cinterface">Interfaces to C libraries</a>
<li><a href="#Modula3_cppinterface">Interfaces to C++ libraries</a>
</ul>
<li><a href="#Modula3_preliminaries">Preliminaries</a>
<ul>
<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>
<ul>
<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="#Modula3_hints">More hints to the generator</a>
<ul>
<li><a href="#Modula3_features">Features</a>
<li><a href="#Modula3_pragmas">Pragmas</a>
</ul>
<li><a href="#Modula3_remarks">Remarks</a>
</ul>
</div>
<!-- INDEX -->
<p>
This chapter describes SWIG's support for
<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">typemaps</a>.
</p>
<H2><a name="Modula3_modula3_overview">31.1 Overview</a></H2>
<p>
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!
However, the Modula-3 generator was already useful for interfacing
to the libraries:
</p>
<ol>
<li>
<a href="http://www.elegosoft.com/cgi-bin/cvsweb.cgi/cm3/m3-libs/plplot/">
PLPlot
</a>
</li>
<li>
<a href="http://www.elegosoft.com/cgi-bin/cvsweb.cgi/cm3/m3-libs/fftw/">
FFTW
</a>
</li>
</ol>
<H3><a name="Modula3_motivation">31.1.1 Motivation</a></H3>
<p>
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>
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>
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>
If the library API is ill designed
writing appropriate typemaps can still be time-consuming.
E.g. C programmers are very creative to work-around
missing data types like (real) enumerations and sets.
You should turn such work-arounds back to the Modula-3 way
otherwise you lose static safety and consistency.
</p>
<p>
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 Modula-3.
To make it complete you can then hide the C interface with Modula-3 classes and
exceptions.
</p>
<p>
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 Modula-3 module into
a C/C++ project.
</p>
<H2><a name="Modula3_conception">31.2 Conception</a></H2>
<H3><a name="Modula3_cinterface">31.2.1 Interfaces to C libraries</a></H3>
<p>
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
modula3.swg
contain code that uses these features.
Because of the built-in support there is no need
for calling the SWIG kernel to generate wrappers written in C.
All conversion and argument checking can be done in Modula-3
and the interfacing is quite efficient.
All you have to do is to write pieces of Modula-3 code
that SWIG puts together.
</p>
<table border summary="Modula-3 C library support">
<tr><th colspan=2>C library support integrated in Modula-3<th></tr>
<tr>
<td>Pragma <tt>&lt;* EXTERNAL *&gt;</tt></td>
<td>Precedes a declaration of a PROCEDURE that is implemented
in an external library instead of a Modula-3 module.</td>
</tr>
<tr>
<td>Pragma <tt>&lt;* CALLBACK *&gt;</tt></td>
<td>Precedes a declaration of a PROCEDURE that should be called
by external library code.</td>
</tr>
<tr>
<td>Module <tt>Ctypes</tt></td>
<td>Contains Modula-3 types that match some basic C types.</td>
</tr>
<tr>
<td>Module <tt>M3toC</tt></td>
<td>Contains routines that convert between Modula-3's <tt>TEXT</tt> type
and C's <tt>char *</tt> type.</td>
</tr>
</table>
<p>
In each run of SWIG the Modula-3 part
generates several files:
</p>
<table border summary="Modula-3 generated files">
<tr>
<th>Module name scheme</th>
<th>Identifier for <tt>%insert</tt></th>
<th>Description</th>
</tr>
<tr>
<td>Module<tt>Raw.i3</tt></td>
<td><tt>m3rawintf</tt></td>
<td>Declaration of types that are equivalent to those of the C library,
<tt>EXTERNAL</tt> procedures as interface to the C library functions</td>
</tr>
<tr>
<td>Module<tt>Raw.m3</tt></td>
<td><tt>m3rawimpl</tt></td>
<td>Almost empty.</td>
</tr>
<tr>
<td>Module<tt>.i3</tt></td>
<td><tt>m3wrapintf</tt></td>
<td>Declaration of comfortable wrappers to the C library functions.</td>
</tr>
<tr>
<td>Module<tt>.m3</tt></td>
<td><tt>m3wrapimpl</tt></td>
<td>Implementation of the wrappers that
convert between Modula-3 and C types,
check for validity of values,
hand-over resource management to the garbage collector using <tt>WeakRef</tt>s
and raises exceptions.</td>
</tr>
<tr>
<td><tt>m3makefile</tt></td>
<td><tt>m3makefile</tt></td>
<td>Add the modules above to the Modula-3 project and
specify the name of the Modula-3 wrapper library
to be generated.
Today I'm not sure if it is a good idea
to create a <tt>m3makefile</tt> in each run,
because SWIG must be started for each Modula-3 module it creates.
Thus the m3makefile is overwritten each time. :-(
</td>
</tr>
</table>
<p>
Here's a scheme of how the function calls to Modula-3 wrappers
are redirected to C library functions:
</p>
<table summary="Modula-3 C library">
<tr>
<td align=center>
Modula-3 wrapper<br>
Module<tt>.i3</tt><br>
generated by Modula-3 part of SWIG
</td>
<td></td>
<td align=center></td>
</tr>
<tr>
<td align=center>
<!-- pre tag overrides centering -->
|<br>
v
</td>
<td></td>
<td align=center></td>
</tr>
<tr>
<td align=center>
Modula-3 interface to C<br>
Module<tt>Raw.i3</tt><br>
generated by Modula-3 part of SWIG
</td>
<td>--&gt;</td>
<td align=center>
C library
</td>
</tr>
</table>
<p>
I have still no good conception how one can split C library interfaces
into type oriented interfaces.
A Module in Modula-3 represents an Abstract DataType
(or call it a static classes, i.e. a class without virtual methods).
E.g. if you have a principal type, say <tt>Database</tt>,
it is good Modula-3 style to set up one Module with the name <tt>Database</tt>
where the database type is declared with the name <tt>T</tt>
and where all functions are declared that operates on it.
</p>
<p>
The normal operation of SWIG is to generate a fixed set of files per call.
To generate multiple modules one has to write one SWIG interface
(different SWIG interfaces can share common data) per module.
Identifiers belonging to a different module may ignored (<tt>%ignore</tt>)
and the principal type must be renamed (<tt>%typemap</tt>).
</p>
<H3><a name="Modula3_cppinterface">31.2.2 Interfaces to C++ libraries</a></H3>
<p>
Interfaces to C++ files are much more complicated and
there are some more design decisions that are not made, yet.
Modula-3 has no support for C++ functions
but C++ compilers should support generating C++ functions
with a C interface.
</p>
<p>
Here's a scheme of how the function calls to Modula-3 wrappers
are redirected to C library functions:
</p>
<table summary="Modula-3 C++ library">
<tr>
<td align=center>
Modula-3 wrapper<br>
Module<tt>.i3</tt><br>
generated by Modula-3 part of SWIG
</td>
<td></td>
<td align=center>C++ library</td>
</tr>
<tr>
<td align=center>
<!-- pre tag overrides centering -->
|<br>
v
</td>
<td></td>
<td align=center>
^<br>
|
</td>
</tr>
<tr>
<td align=center>
Modula-3 interface to C<br>
Module<tt>Raw.i3</tt><br>
generated by Modula-3 part of SWIG
</td>
<td>--&gt;</td>
<td align=center>
C interface to C++<br>
module<tt>_wrap.cxx</tt><br>
generated by the SWIG core
</td>
</tr>
</table>
<p>
Wrapping C++ libraries arises additional problems:
</p>
<ul>
<li>
Is it sensible to wrap C++ classes with Modula-3 classes?
</li>
<li>
How to find the wrapping Modula-3 class
for a class pointer that is returned by a C++ routine?
</li>
<li>
How to deal with multiple inheritance
which was neglected for Modula-3 for good reasons?
</li>
<li>
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#Python_directors">Python</a>.
</li>
<li>
How to manage storage with the garbage collector of Modula-3?
Support for
<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
but shall be passed back to the storage management of the C++ library?
This is a general issue which is not solved in a satisfying fashion
as far as I know.
</li>
<li>
How to turn C++ exceptions into Modula-3 exceptions?
There's also no support for
<a href="Customization.html#Customization_exception">
<tt>%exception</tt></a>, yet.
</li>
</ul>
<p>
Be warned:
There is no C++ library I wrote a SWIG interface for,
so I'm not sure if this is possible or sensible, yet.
</p>
<H2><a name="Modula3_preliminaries">31.3 Preliminaries</a></H2>
<H3><a name="Modula3_compilers">31.3.1 Compilers</a></H3>
<p>
There are different Modula-3 compilers around:
cm3, pm3, ezm3, Klagenfurth Modula-3, Cambridge Modula-3.
SWIG itself does not contain compiler specific code
but the modula3.swg library file
may do so.
For testing examples I use Critical Mass cm3.
</p>
<H3><a name="Modula3_commandline">31.3.2 Additional Commandline Options</a></H3>
<p>
There are some experimental command line options
that prevent SWIG from generating interface files.
Instead files are emitted that may assist you
when writing SWIG interface files.
</p>
<table border summary="Modula-3 specific options">
<tr>
<th>Modula-3 specific options</th>
<th>Description</th>
</tr>
<tr>
<td valign=top>-generateconst &lt;file&gt;</td>
<td>
Disable generation of interfaces and wrappers.
Instead write code for computing numeric values of constants
to the specified file.
<br>
C code may contain several constant definitions
written as preprocessor macros.
Other language modules of SWIG use
compute-once-use-readonly variables or
functions to wrap such definitions.
All of them can invoke C code dynamically
for computing the macro values.
But if one wants to turn them into Modula-3
integer constants, enumerations or set types,
the values of these expressions has to be known statically.
Although definitions like <tt>(1 &lt;&lt; FLAG_MAXIMIZEWINDOW)</tt>
must be considered as good C style
they are hard to convert to Modula-3
since the value computation can use every feature of C.
<br>
Thus I implemented these switch
to extract all constant definitions
and write a C program that output the values of them.
It works for numeric constants only
and treats all of them as <tt>double</tt>.
Future versions may generate a C++ program
that can detect the type of the macros
by overloaded output functions.
Then strings can also be processed.
</td>
</tr>
<tr>
<td valign=top>-generaterename &lt;file&gt;</td>
<td>
Disable generation of interfaces and wrappers.
Instead generate suggestions for <tt>%rename</tt>.
<br>
C libraries use a naming style
that is neither homogeneous nor similar to that of Modula-3.
C function names often contain a prefix denoting the library
and some name components separated by underscores
or capitalization changes.
To get library interfaces that are really Modula-3 like
you should rename the function names with the <tt>%rename</tt> directive.
This switch outputs a list of such directives
with a name suggestion generated by a simple heuristic.
</td>
</tr>
<tr>
<td valign=top>-generatetypemap &lt;file&gt;</td>
<td>
Disable generation of interfaces and wrappers.
Instead generate templates for some basic typemaps.
</td>
</tr>
</table>
<H2><a name="Modula3_typemaps">31.4 Modula-3 typemaps</a></H2>
<H3><a name="Modula3_inoutparam">31.4.1 Inputs and outputs</a></H3>
<p>
Each C procedure has a bunch of inputs and outputs.
Inputs are passed as function arguments,
outputs are updated referential arguments and
the function value.
</p>
<p>
Each C type can have several typemaps
that apply only in case if a type is used
for an input argument, for an output argument,
or for a return value.
A further typemap may specify
the direction that is used for certain parameters.
I have chosen this separation
in order to be able to write general typemaps for the modula3.swg typemap library.
In the library code the final usage of the type is not known.
Using separate typemaps for each possible use
allows appropriate definitions for each case.
If these pre-definitions are fine
then the direction of the function parameter
is the only hint the user must give.
</p>
<p>
The typemaps specific to Modula-3 have a common name scheme:
A typemap name starts with "m3",
followed by "raw" or "wrap"
depending on whether it controls the generation
of the Module<tt>Raw.i3</tt> or the Module<tt>.i3</tt>, respectively.
It follows an "in" for typemaps applied to input argument,
"out" for output arguments, "arg" for all kind of arguments,
"ret" for returned values.
</p>
<p>
The main task of SWIG is to build wrapper function,
i.e. functions that convert values between C and Modula-3
and call the corresponding C function.
Modula-3 wrapper functions generated by SWIG
consist of the following parts:
</p>
<ul>
<li>Generate <tt>PROCEDURE</tt> signature.</li>
<li>Declare local variables.</li>
<li>Convert input values from Modula-3 to C.</li>
<li>Check for input value integrity.</li>
<li>Call the C function.</li>
<li>Check returned values, e.g. error codes.</li>
<li>Convert and write back values into Modula-3 records.</li>
<li>Free temporary storage.</li>
<li>Return values.</li>
</ul>
<table border summary="Modula-3 typemaps">
<tr>
<th>Typemap</th>
<th>Example</th>
<th>Description</th>
</tr>
<tr>
<td>m3wrapargvar</td>
<td><tt>$1: INTEGER := $1_name;</tt></td>
<td>
Declaration of some variables needed for temporary results.
</td>
</tr>
<tr>
<td>m3wrapargconst</td>
<td><tt>$1 = "$1_name";</tt></td>
<td>
Declaration of some constant, maybe for debug purposes.
</td>
</tr>
<tr>
<td>m3wrapargraw</td>
<td><tt>ORD($1_name)</tt></td>
<td>
The expression that should be passed as argument to the raw Modula-3 interface function.
</td>
</tr>
<tr>
<td>m3wrapargdir</td>
<td><tt>out</tt></td>
<td>
Referential arguments can be used for input, output, update.
???
</td>
</tr>
<tr>
<td>m3wrapinmode</td>
<td><tt>READONLY</tt></td>
<td>
One of Modula-3 parameter modes
<tt>VALUE</tt> (or empty),
<tt>VAR</tt>,
<tt>READONLY</tt>
</td>
</tr>
<tr>
<td>m3wrapinname</td>
<td></td>
<td>
New name of the input argument.
</td>
</tr>
<tr>
<td>m3wrapintype</td>
<td></td>
<td>
Modula-3 type of the input argument.
</td>
</tr>
<tr>
<td>m3wrapindefault</td>
<td></td>
<td>
Default value of the input argument
</td>
</tr>
<tr>
<td>m3wrapinconv</td>
<td><tt>$1 := M3toC.SharedTtoS($1_name);</tt></td>
<td>
Statement for converting the Modula-3 input value to C compliant value.
</td>
</tr>
<tr>
<td>m3wrapincheck</td>
<td><tt>IF Text.Length($1_name) &gt; 10 THEN RAISE E("str too long"); END;</tt></td>
<td>
Check the integrity of the input value.
</td>
</tr>
<tr>
<td>m3wrapoutname</td>
<td></td>
<td>
Name of the <tt>RECORD</tt> field to be used for returning multiple values.
This applies to referential output arguments that shall be turned
into return values.
</td>
</tr>
<tr>
<td>m3wrapouttype</td>
<td></td>
<td>
Type of the value that is returned instead of a referential output argument.
</td>
</tr>
<tr>
<td>m3wrapoutconv</td>
<td></td>
<td>
</td>
</tr>
<tr>
<td>m3wrapoutcheck</td>
<td></td>
<td>
</td>
</tr>
<tr>
<td>m3wrapretraw</td>
<td></td>
<td>
</td>
</tr>
<tr>
<td>m3wrapretname</td>
<td></td>
<td>
</td>
</tr>
<tr>
<td>m3wraprettype</td>
<td></td>
<td>
</td>
</tr>
<tr>
<td>m3wrapretvar</td>
<td></td>
<td>
</td>
</tr>
<tr>
<td>m3wrapretconv</td>
<td></td>
<td>
</td>
</tr>
<tr>
<td>m3wrapretcheck</td>
<td></td>
<td>
</td>
</tr>
<tr>
<td>m3wrapfreearg</td>
<td><tt>M3toC.FreeSharedS(str, arg1);</tt></td>
<td>
Free resources that were temporarily used in the wrapper.
Since this step should never be skipped,
SWIG will put it in the <tt>FINALLY</tt> branch
of a <tt>TRY .. FINALLY</tt> structure.
</td>
</tr>
</table>
<H3><a name="Modula3_ordinals">31.4.2 Subranges, Enumerations, Sets</a></H3>
<p>
Subranges, enumerations, and sets are machine oriented types
that make Modula very strong and expressive compared
with the type systems of many other languages.
</p>
<ul>
<li>
Subranges are used for statically restricted choices of integers.
</li>
<li>
Enumerations are used for named choices.
</li>
<li>
Sets are commonly used for flag (option) sets.
</li>
</ul>
<p>
Using them extensively makes Modula code very safe and readable.
</p>
<p>
C supports enumerations, too, but they are not as safe as the ones of Modula.
Thus they are abused for many things:
For named choices, for integer constant definitions, for sets.
To make it complete every way of defining a value in C
(<tt>#define</tt>, <tt>const int</tt>, <tt>enum</tt>)
is somewhere used for defining something
that must be handled completely different in Modula-3
(<tt>INTEGER</tt>, enumeration, <tt>SET</tt>).
</p>
<p>
I played around with several <tt>%feature</tt>s and <tt>%pragma</tt>s
that split the task up into converting
the C bit patterns (integer or bit set)
into Modula-3 bit patterns (integer or bit set)
and change the type as requested.
See the corresponding example in the
Examples/modula3/enum/example.i file.
This is quite messy and not satisfying.
So the best what you can currently do is
to rewrite constant definitions manually.
Though this is a tedious work
that I'd like to automate.
</p>
<H3><a name="Modula3_class">31.4.3 Objects</a></H3>
<p>
Declarations of C++ classes are mapped to <tt>OBJECT</tt> types
while it is tried to retain the access hierarchy
"public - protected - private" using partial revelation.
Though the example in
Examples/modula3/class/example.i
is not really useful, yet.
</p>
<H3><a name="Modula3_imports">31.4.4 Imports</a></H3>
<p>
Pieces of Modula-3 code provided by typemaps
may contain identifiers from foreign modules.
If the typemap <tt>m3wrapinconv</tt> for <tt>blah *</tt>
contains code using the function <tt>M3toC.SharedTtoS</tt>
you may declare <tt>%typemap("m3wrapinconv:import") blah * %{M3toC%}</tt>.
Then the module <tt>M3toC</tt> is imported
if the <tt>m3wrapinconv</tt> typemap for <tt>blah *</tt>
is used at least once.
Use <tt>%typemap("m3wrapinconv:import") blah * %{MyConversions AS M3toC%}</tt>
if you need module renaming.
Unqualified import is not supported.
</p>
<p>
It is cumbersome to add this typemap to each piece of Modula-3 code.
It is especially useful when writing general typemaps
for the modula3.swg typemap library.
For a monolithic module you might be better off
if you add the imports directly:
</p>
<div class="code">
<pre>
%insert(m3rawintf) %{
IMPORT M3toC;
%}
</pre></div>
<H3><a name="Modula3_exceptions">31.4.5 Exceptions</a></H3>
<p>
Modula-3 provides another possibility
of an output of a function: exceptions.
</p>
<p>
Any piece of Modula-3 code that SWIG inserts
due to a typemap can raise an exception.
This way you can also convert an error code
from a C function into a Modula-3 exception.
</p>
<p>
The <tt>RAISES</tt> clause is controlled
by typemaps with the <tt>throws</tt> extension.
If the typemap <tt>m3wrapinconv</tt> for <tt>blah *</tt>
contains code that may raise the exceptions <tt>OSError.E</tt>
you should declare
<tt>%typemap("m3wrapinconv:throws") blah * %{OSError.E%}</tt>.
</p>
<H3><a name="Modula3_typemap_example">31.4.6 Example</a></H3>
<p>
The generation of wrappers in Modula-3 needs very fine control
to take advantage of the language features.
Here is an example of a generated wrapper
where almost everything is generated by a typemap:
</p>
<div class="code"><pre>
<I> (* %relabel m3wrapinmode m3wrapinname m3wrapintype m3wrapindefault *)</I>
PROCEDURE Name (READONLY str : TEXT := "" )
<I> (* m3wrapoutcheck:throws *)</I>
: NameResult RAISES {E} =
CONST
arg1name = "str"; <I>(* m3wrapargconst *)</I>
VAR
arg0 : C.char_star; <I>(* m3wrapretvar *)</I>
arg1 : C.char_star; <I>(* m3wrapargvar *)</I>
arg2 : C.int;
result : RECORD
<I> (*m3wrapretname m3wraprettype*)</I>
unixPath : TEXT;
<I> (*m3wrapoutname m3wrapouttype*)</I>
checksum : CARDINAL;
END;
BEGIN
TRY
arg1 := M3toC.SharedTtoS(str); <I>(* m3wrapinconv *)</I>
IF Text.Length(arg1) &gt; 10 THEN <I>(* m3wrapincheck *)</I>
RAISE E("str too long");
END;
<I> (* m3wrapretraw m3wrapargraw *)</I>
arg0 := MessyToUnix (arg1, arg2);
result.unixPath := M3toC.CopyStoT(arg0); <I>(* m3wrapretconv *)</I>
result.checksum := arg2; <I>(* m3wrapoutconv *)</I>
IF result.checksum = 0 THEN <I>(* m3wrapoutcheck *)</I>
RAISE E("invalid checksum");
END;
FINALLY
M3toC.FreeSharedS(str, arg1); <I>(* m3wrapfreearg *)</I>
END;
END Name;
</pre></div>
<H2><a name="Modula3_hints">31.5 More hints to the generator</a></H2>
<H3><a name="Modula3_features">31.5.1 Features</a></H3>
<table border summary="Modula-3 features">
<tr>
<th>Feature</th>
<th>Example</th>
<th>Description</th>
</tr>
<tr>
<td>multiretval</td>
<td><tt>%m3multiretval get_box;</tt> or
<tt>%feature("modula3:multiretval") get_box;</tt></td>
<td>Let the denoted function return a <tt>RECORD</tt>
rather than a plain value.
This <tt>RECORD</tt> contains all arguments with "out" direction
including the return value of the C function (if there is one).
If more than one argument is "out"
then the function <b>must</b> have the <tt>multiretval</tt> feature activated,
but it is explicitly requested from the user to prevent mistakes.</td>
</tr>
<tr>
<td>constnumeric</td>
<td><tt>%constnumeric(12) twelve;</tt> or
<tt>%feature("constnumeric", "12") twelve;</tt></td>
<td>This feature can be used to tell Modula-3's back-end of SWIG
the value of an identifier.
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="#Modula3_commandline">option</a>.
In future it may be generalized to other kind of values
such as strings.
</td>
</tr>
</table>
<H3><a name="Modula3_pragmas">31.5.2 Pragmas</a></H3>
<table border summary="Modula-3 pragmas">
<tr>
<th>Pragma</th>
<th>Example</th>
<th>Description</th>
</tr>
<tr>
<td>unsafe</td>
<td><tt>%pragma(modula3) unsafe="true";</tt></td>
<td>Mark the raw interface modules as <tt>UNSAFE</tt>.
This will be necessary in many cases.</td>
</tr>
<tr>
<td>library</td>
<td><tt>%pragma(modula3) library="m3fftw";</tt></td>
<td>Specifies the library name for the wrapper library to be created.
It should be distinct from the name of the library to be wrapped.</td>
</tr>
</table>
<H2><a name="Modula3_remarks">31.6 Remarks</a></H2>
<ul>
<li>
The Modula-3 part of SWIG doesn't try to generate nicely formatted code.
If you need to read the generated code, use <tt>m3pp</tt> to postprocess the
Modula files.
</li>
</ul>
</body>
</html>

16
Doc/Manual/Modules.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Modules">19 Working with Modules</a></H1>
<H1><a name="Modules">20 Working with Modules</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -24,7 +24,7 @@
<H2><a name="Modules_introduction">19.1 Modules Introduction</a></H2>
<H2><a name="Modules_introduction">20.1 Modules Introduction</a></H2>
<p>
@ -78,7 +78,7 @@ where you want to create a collection of modules.
Each module in the collection is created via separate invocations of SWIG.
</p>
<H2><a name="Modules_nn1">19.2 Basics</a></H2>
<H2><a name="Modules_nn1">20.2 Basics</a></H2>
<p>
@ -177,7 +177,7 @@ in parallel from multiple threads as SWIG provides no locking - for more on that
issue, read on.
</p>
<H2><a name="Modules_nn2">19.3 The SWIG runtime code</a></H2>
<H2><a name="Modules_nn2">20.3 The SWIG runtime code</a></H2>
<p>
@ -243,7 +243,7 @@ can peacefully coexist. So the type structures are separated by the
is empty. Only modules compiled with the same pair will share type information.
</p>
<H2><a name="Modules_external_run_time">19.4 External access to the runtime</a></H2>
<H2><a name="Modules_external_run_time">20.4 External access to the runtime</a></H2>
<p>As described in <a href="Typemaps.html#Typemaps_runtime_type_checker">The run-time type checker</a>,
@ -282,7 +282,7 @@ SWIG_TYPE_TABLE to be the same as the module whose types you are trying to
access.
</p>
<H2><a name="Modules_nn4">19.5 A word of caution about static libraries</a></H2>
<H2><a name="Modules_nn4">20.5 A word of caution about static libraries</a></H2>
<p>
@ -293,7 +293,7 @@ into it. This is very often <b>NOT</b> what you want and it can lead to unexpect
behavior. When working with dynamically loadable modules, you should try to work exclusively with shared libraries.
</p>
<H2><a name="Modules_nn5">19.6 References</a></H2>
<H2><a name="Modules_nn5">20.6 References</a></H2>
<p>
@ -301,7 +301,7 @@ Due to the complexity of working with shared libraries and multiple modules, it
an outside reference. John Levine's "Linkers and Loaders" is highly recommended.
</p>
<H2><a name="Modules_nn6">19.7 Reducing the wrapper file size</a></H2>
<H2><a name="Modules_nn6">20.7 Reducing the wrapper file size</a></H2>
<p>

8
Doc/Manual/Mzscheme.html
View file

@ -8,7 +8,7 @@
<body bgcolor="#ffffff">
<H1><a name="Mzscheme">37 SWIG and MzScheme/Racket</a></H1>
<H1><a name="Mzscheme">38 SWIG and MzScheme/Racket</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -24,7 +24,7 @@
<p>
This section contains information on SWIG's support of Racket, formally known as MzScheme.
<H2><a name="MzScheme_nn2">37.1 Creating native structures</a></H2>
<H2><a name="MzScheme_nn2">38.1 Creating native structures</a></H2>
<p>
@ -65,7 +65,7 @@ Then in scheme, you can use regular struct access procedures like
</pre>
</div>
<H2><a name="MzScheme_simple">37.2 Simple example</a></H2>
<H2><a name="MzScheme_simple">38.2 Simple example</a></H2>
<p>
@ -166,7 +166,7 @@ Some points of interest:
<li> The above requests mzc to create an extension using the CGC garbage-collector. The alternative -- the 3m collector -- has generally better performance, but work is still required for SWIG to emit code which is compatible with it.
</ul>
<H2><a name="MzScheme_external_docs">37.3 External documentation</a></H2>
<H2><a name="MzScheme_external_docs">38.3 External documentation</a></H2>
<p>

66
Doc/Manual/Ocaml.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Ocaml">38 SWIG and OCaml</a></H1>
<H1><a name="Ocaml">39 SWIG and OCaml</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -88,7 +88,7 @@ If you're not familiar with the Objective Caml language, you can visit
<a href="http://ocaml.org/">The Ocaml Website</a>.
</p>
<H2><a name="Ocaml_nn2">38.1 Preliminaries</a></H2>
<H2><a name="Ocaml_nn2">39.1 Preliminaries</a></H2>
<p>
@ -106,7 +106,7 @@ file Examples/Makefile illustrate how to compile and link SWIG modules that
will be loaded dynamically. This has only been tested on Linux so far.
</p>
<H3><a name="Ocaml_nn3">38.1.1 Running SWIG</a></H3>
<H3><a name="Ocaml_nn3">39.1.1 Running SWIG</a></H3>
<p>
@ -129,7 +129,7 @@ you will compile the file <tt>example_wrap.c</tt> with <tt>ocamlc</tt> or
the resulting .ml and .mli files as well, and do the final link with -custom
(not needed for native link).</p>
<H3><a name="Ocaml_nn4">38.1.2 Compiling the code</a></H3>
<H3><a name="Ocaml_nn4">39.1.2 Compiling the code</a></H3>
<p>
@ -166,7 +166,7 @@ in C++ mode, you must:</p>
</pre>
</div>
<H3><a name="Ocaml_nn5">38.1.3 The camlp4 module</a></H3>
<H3><a name="Ocaml_nn5">39.1.3 The camlp4 module</a></H3>
<p>
@ -242,7 +242,7 @@ let b = C_string (getenv "PATH")
</td></tr>
</table>
<H3><a name="Ocaml_nn6">38.1.4 Using your module</a></H3>
<H3><a name="Ocaml_nn6">39.1.4 Using your module</a></H3>
<p>
@ -256,7 +256,7 @@ option to build your functions into the primitive list. This
option is not needed when you build native code.
</p>
<H3><a name="Ocaml_nn7">38.1.5 Compilation problems and compiling with C++</a></H3>
<H3><a name="Ocaml_nn7">39.1.5 Compilation problems and compiling with C++</a></H3>
<p>
@ -267,7 +267,7 @@ liberal with pointer types may not compile under the C++ compiler.
Most code meant to be compiled as C++ will not have problems.
</p>
<H2><a name="Ocaml_nn8">38.2 The low-level Ocaml/C interface</a></H2>
<H2><a name="Ocaml_nn8">39.2 The low-level Ocaml/C interface</a></H2>
<p>
@ -367,7 +367,7 @@ value items pass through directly, but you must make your own type
signature for a function that uses value in this way.
</p>
<H3><a name="Ocaml_nn9">38.2.1 The generated module</a></H3>
<H3><a name="Ocaml_nn9">39.2.1 The generated module</a></H3>
<p>
@ -401,7 +401,7 @@ it describes the output SWIG will generate for class definitions.
</td></tr>
</table>
<H3><a name="Ocaml_nn10">38.2.2 Enums</a></H3>
<H3><a name="Ocaml_nn10">39.2.2 Enums</a></H3>
<p>
@ -464,7 +464,7 @@ val x : Enum_test.c_obj = C_enum `a
</pre>
</div>
<H4><a name="Ocaml_nn11">38.2.2.1 Enum typing in Ocaml</a></H4>
<H4><a name="Ocaml_nn11">39.2.2.1 Enum typing in Ocaml</a></H4>
<p>
@ -477,10 +477,10 @@ functions imported from different modules. You must convert values to master
values using the swig_val function before sharing them with another module.
</p>
<H3><a name="Ocaml_nn12">38.2.3 Arrays</a></H3>
<H3><a name="Ocaml_nn12">39.2.3 Arrays</a></H3>
<H4><a name="Ocaml_nn13">38.2.3.1 Simple types of bounded arrays</a></H4>
<H4><a name="Ocaml_nn13">39.2.3.1 Simple types of bounded arrays</a></H4>
<p>
@ -501,7 +501,7 @@ arrays of simple types with known bounds in your code, but this only works
for arrays whose bounds are completely specified.
</p>
<H4><a name="Ocaml_nn14">38.2.3.2 Complex and unbounded arrays</a></H4>
<H4><a name="Ocaml_nn14">39.2.3.2 Complex and unbounded arrays</a></H4>
<p>
@ -514,7 +514,7 @@ SWIG can't predict which of these methods will be used in the array,
so you have to specify it for yourself in the form of a typemap.
</p>
<H4><a name="Ocaml_nn15">38.2.3.3 Using an object</a></H4>
<H4><a name="Ocaml_nn15">39.2.3.3 Using an object</a></H4>
<p>
@ -528,7 +528,7 @@ Consider writing an object when the ending condition of your array is complex,
such as using a required sentinel, etc.
</p>
<H4><a name="Ocaml_nn16">38.2.3.4 Example typemap for a function taking float * and int</a></H4>
<H4><a name="Ocaml_nn16">39.2.3.4 Example typemap for a function taking float * and int</a></H4>
<p>
@ -579,7 +579,7 @@ void printfloats( float *tab, int len );
</pre></td></tr></table>
<H3><a name="Ocaml_nn17">38.2.4 C++ Classes</a></H3>
<H3><a name="Ocaml_nn17">39.2.4 C++ Classes</a></H3>
<p>
@ -622,7 +622,7 @@ the underlying pointer, so using create_[x]_from_ptr alters the
returned value for the same object.
</p>
<H4><a name="Ocaml_nn18">38.2.4.1 STL vector and string Example</a></H4>
<H4><a name="Ocaml_nn18">39.2.4.1 STL vector and string Example</a></H4>
<p>
@ -702,7 +702,7 @@ baz
#
</pre></div>
<H4><a name="Ocaml_nn19">38.2.4.2 C++ Class Example</a></H4>
<H4><a name="Ocaml_nn19">39.2.4.2 C++ Class Example</a></H4>
<p>
@ -732,7 +732,7 @@ public:
};
</pre></td></tr></table>
<H4><a name="Ocaml_nn20">38.2.4.3 Compiling the example</a></H4>
<H4><a name="Ocaml_nn20">39.2.4.3 Compiling the example</a></H4>
<div class="code"><pre>
@ -750,7 +750,7 @@ bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \
-L$QTPATH/lib -cclib -lqt
</pre></div>
<H4><a name="Ocaml_nn21">38.2.4.4 Sample Session</a></H4>
<H4><a name="Ocaml_nn21">39.2.4.4 Sample Session</a></H4>
<div class="code"><pre>
@ -777,10 +777,10 @@ Assuming you have a working installation of QT, you will see a window
containing the string "hi" in a button.
</p>
<H3><a name="Ocaml_nn22">38.2.5 Director Classes</a></H3>
<H3><a name="Ocaml_nn22">39.2.5 Director Classes</a></H3>
<H4><a name="Ocaml_nn23">38.2.5.1 Director Introduction</a></H4>
<H4><a name="Ocaml_nn23">39.2.5.1 Director Introduction</a></H4>
<p>
@ -807,7 +807,7 @@ class foo {
};
</pre></div>
<H4><a name="Ocaml_nn24">38.2.5.2 Overriding Methods in Ocaml</a></H4>
<H4><a name="Ocaml_nn24">39.2.5.2 Overriding Methods in Ocaml</a></H4>
<p>
@ -835,7 +835,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">38.2.5.3 Director Usage Example</a></H4>
<H4><a name="Ocaml_nn25">39.2.5.3 Director Usage Example</a></H4>
<table border="1" bgcolor="#dddddd" summary="Director usage example">
@ -896,7 +896,7 @@ in a more effortless style in ocaml, while leaving the "engine" part of the
program in C++.
</p>
<H4><a name="Ocaml_nn26">38.2.5.4 Creating director objects</a></H4>
<H4><a name="Ocaml_nn26">39.2.5.4 Creating director objects</a></H4>
<p>
@ -937,7 +937,7 @@ object from causing a core dump, as long as the object is destroyed
properly.
</p>
<H4><a name="Ocaml_nn27">38.2.5.5 Typemaps for directors, directorin, directorout, directorargout</a></H4>
<H4><a name="Ocaml_nn27">39.2.5.5 Typemaps for directors, directorin, directorout, directorargout</a></H4>
<p>
@ -948,7 +948,7 @@ well as a function return value in the same way you provide function arguments,
and to receive arguments the same way you normally receive function returns.
</p>
<H4><a name="Ocaml_nn28">38.2.5.6 directorin typemap</a></H4>
<H4><a name="Ocaml_nn28">39.2.5.6 directorin typemap</a></H4>
<p>
@ -959,7 +959,7 @@ code receives when you are called. In general, a simple <tt>directorin</tt> typ
can use the same body as a simple <tt>out</tt> typemap.
</p>
<H4><a name="Ocaml_nn29">38.2.5.7 directorout typemap</a></H4>
<H4><a name="Ocaml_nn29">39.2.5.7 directorout typemap</a></H4>
<p>
@ -970,7 +970,7 @@ for the same type, except when there are special requirements for object
ownership, etc.
</p>
<H4><a name="Ocaml_nn30">38.2.5.8 directorargout typemap</a></H4>
<H4><a name="Ocaml_nn30">39.2.5.8 directorargout typemap</a></H4>
<p>
@ -987,7 +987,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">38.2.6 Exceptions</a></H3>
<H3><a name="Ocaml_nn31">39.2.6 Exceptions</a></H3>
<p>
@ -1075,7 +1075,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="Ocaml_nn32">38.3 Documentation Features</a></H2>
<H2><a name="Ocaml_nn32">39.3 Documentation Features</a></H2>
<p>
@ -1084,7 +1084,7 @@ comments (colloquially referred to as "docstrings") that can be read by
<a href="https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html">OCamldoc</a>.
</p>
<H3><a name="Ocaml_nn33">38.3.1 Module docstring</a></H3>
<H3><a name="Ocaml_nn33">39.3.1 Module docstring</a></H3>
<p>

52
Doc/Manual/Octave.html
View file

@ -9,7 +9,7 @@
<body bgcolor="#ffffff">
<H1><a name="Octave">29 SWIG and Octave</a></H1>
<H1><a name="Octave">30 SWIG and Octave</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -60,7 +60,7 @@ This chapter is intended to give an introduction to using the module. You should
Also, there are a dozen or so examples in the Examples/octave directory, and hundreds in the test suite (Examples/test-suite and Examples/test-suite/octave).
</p>
<H2><a name="Octave_nn2">29.1 Preliminaries</a></H2>
<H2><a name="Octave_nn2">30.1 Preliminaries</a></H2>
<p>
@ -76,7 +76,7 @@ This cannot be guaranteed however, as in recent times new Octave releases have r
The SWIG runtime exports the function <tt>swig_octave_prereq()</tt> for checking the version of Octave.
</p>
<H2><a name="Octave_nn3">29.2 Running SWIG</a></H2>
<H2><a name="Octave_nn3">30.2 Running SWIG</a></H2>
<p>
@ -108,7 +108,7 @@ The <tt>-c++</tt> option is also required when wrapping C++ code:
This creates a C++ source file "example_wrap.cpp". A C++ file is generated even when wrapping C code as Octave is itself written in C++ and requires wrapper code to be in the same language. The generated C++ source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application (in this case, the gcd implementation) to create an extension module.
</p>
<H3><a name="Octave_nn4">29.2.1 Command-line options</a></H3>
<H3><a name="Octave_nn4">30.2.1 Command-line options</a></H3>
<p>
@ -131,7 +131,7 @@ The special name "." loads C global variables into the module namespace, i.e. al
The <em>-opprefix</em> options sets the prefix of the names of global/friend <a href="#Octave_nn18">operator</a> functions.
</p>
<H3><a name="Octave_nn5">29.2.2 Compiling a dynamic module</a></H3>
<H3><a name="Octave_nn5">30.2.2 Compiling a dynamic module</a></H3>
<p>
@ -158,7 +158,7 @@ $ mkoctfile example_wrap.cpp example.c
<div class="targetlang"><pre>octave:1&gt; swigexample</pre></div>
<H3><a name="Octave_nn6">29.2.3 Using your module</a></H3>
<H3><a name="Octave_nn6">30.2.3 Using your module</a></H3>
<p>
@ -176,10 +176,10 @@ octave:4&gt; swigexample.cvar.Foo=4;
octave:5&gt; swigexample.cvar.Foo
ans = 4 </pre></div>
<H2><a name="Octave_nn7">29.3 A tour of basic C/C++ wrapping</a></H2>
<H2><a name="Octave_nn7">30.3 A tour of basic C/C++ wrapping</a></H2>
<H3><a name="Octave_nn8">29.3.1 Modules</a></H3>
<H3><a name="Octave_nn8">30.3.1 Modules</a></H3>
<p>
@ -224,7 +224,7 @@ octave:4&gt; swigexample.gcd(4, 6)
ans = 2
</pre></div>
<H3><a name="Octave_nn9">29.3.2 Functions</a></H3>
<H3><a name="Octave_nn9">30.3.2 Functions</a></H3>
<p>
@ -241,7 +241,7 @@ int fact(int n); </pre></div>
<div class="targetlang"><pre>octave:1&gt; swigexample.fact(4)
24 </pre></div>
<H3><a name="Octave_nn10">29.3.3 Global variables</a></H3>
<H3><a name="Octave_nn10">30.3.3 Global variables</a></H3>
<p>
@ -294,7 +294,7 @@ octave:2&gt; swigexample.PI=3.142;
octave:3&gt; swigexample.PI
ans = 3.1420 </pre></div>
<H3><a name="Octave_nn11">29.3.4 Constants and enums</a></H3>
<H3><a name="Octave_nn11">30.3.4 Constants and enums</a></H3>
<p>
@ -316,7 +316,7 @@ swigexample.SCONST="Hello World"
swigexample.SUNDAY=0
.... </pre></div>
<H3><a name="Octave_nn12">29.3.5 Pointers</a></H3>
<H3><a name="Octave_nn12">30.3.5 Pointers</a></H3>
<p>
@ -363,7 +363,7 @@ octave:2&gt; f=swigexample.fopen("not there", "r");
error: value on right hand side of assignment is undefined
error: evaluating assignment expression near line 2, column 2 </pre></div>
<H3><a name="Octave_nn13">29.3.6 Structures and C++ classes</a></H3>
<H3><a name="Octave_nn13">30.3.6 Structures and C++ classes</a></H3>
<p>
@ -498,7 +498,7 @@ ans = 1
Depending on the ownership setting of a <tt>swig_ref</tt>, it may call C++ destructors when its reference count goes to zero. See the section on memory management below for details.
</p>
<H3><a name="Octave_nn15">29.3.7 C++ inheritance</a></H3>
<H3><a name="Octave_nn15">30.3.7 C++ inheritance</a></H3>
<p>
@ -507,7 +507,7 @@ This information contains the full class hierarchy. When an indexing operation (
the tree is walked to find a match in the current class as well as any of its bases. The lookup is then cached in the <tt>swig_ref</tt>.
</p>
<H3><a name="Octave_nn17">29.3.8 C++ overloaded functions</a></H3>
<H3><a name="Octave_nn17">30.3.8 C++ overloaded functions</a></H3>
<p>
@ -517,7 +517,7 @@ The dispatch function selects which overload to call (if any) based on the passe
<tt>typecheck</tt> typemaps are used to analyze each argument, as well as assign precedence. See the chapter on typemaps for details.
</p>
<H3><a name="Octave_nn18">29.3.9 C++ operators</a></H3>
<H3><a name="Octave_nn18">30.3.9 C++ operators</a></H3>
<p>
@ -621,7 +621,7 @@ On the C++ side, the default mappings are as follows:
Octave can also utilise friend (i.e. non-member) operators with a simple %rename: see the example in the Examples/octave/operator directory.
</p>
<H3><a name="Octave_nn19">29.3.10 Class extension with %extend</a></H3>
<H3><a name="Octave_nn19">30.3.10 Class extension with %extend</a></H3>
<p>
@ -660,7 +660,7 @@ Similarly, Octave can use the <tt>__float__</tt> method to convert an object to
Octave 3.8.0 and later versions will also map unary functions X() to the corresponding <tt>__X__</tt> method, where X includes: abs(), acos(), acosh(), angle(), arg(), asin(), asinh(), atan(), atanh(), cbrt(), ceil(), conj(), cos(), cosh(), dawson(), erf(), erfc(), erfcinv(), erfcx(), erfi(), erfinv(), exp(), expm1(), finite(), fix(), floor(), gamma(), imag(), isalnum(), isalpha(), isascii(), iscntrl(), isdigit(), isgraph(), isinf(), islower(), isna(), isnan(), isprint(), ispunct(), isspace(), isupper(), isxdigit(), lgamma(), log(), log10(), log1p(), log2(), real(), round(), roundb(), signbit(), signum(), sin(), sinh(), sqrt(), tan(), tanh(), toascii(), tolower(), toupper()
</p>
<H3><a name="Octave_nn20">29.3.11 C++ templates</a></H3>
<H3><a name="Octave_nn20">30.3.11 C++ templates</a></H3>
<p>
@ -737,10 +737,10 @@ ans =
</pre></div>
<H3><a name="Octave_nn21">29.3.12 C++ Smart Pointers</a></H3>
<H3><a name="Octave_nn21">30.3.12 C++ Smart Pointers</a></H3>
<H4><a name="Octave_smart_pointers_shared_ptr">29.3.12.1 The shared_ptr Smart Pointer</a></H4>
<H4><a name="Octave_smart_pointers_shared_ptr">30.3.12.1 The shared_ptr Smart Pointer</a></H4>
<p>
@ -751,14 +751,14 @@ in the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a
</p>
<H4><a name="Octave_smart_pointers_generic">29.3.12.2 Generic Smart Pointers</a></H4>
<H4><a name="Octave_smart_pointers_generic">30.3.12.2 Generic Smart Pointers</a></H4>
<p>
C++ smart pointers are fully supported as in other modules.
</p>
<H3><a name="Octave_nn22">29.3.13 Directors (calling Octave from C++ code)</a></H3>
<H3><a name="Octave_nn22">30.3.13 Directors (calling Octave from C++ code)</a></H3>
<p>
@ -839,14 +839,14 @@ c-side routine called
octave-side routine called
</pre></div>
<H3><a name="Octave_nn23">29.3.14 Threads</a></H3>
<H3><a name="Octave_nn23">30.3.14 Threads</a></H3>
<p>
The use of threads in wrapped Director code is not supported; i.e., an Octave-side implementation of a C++ class must be called from the Octave interpreter's thread. Anything fancier (apartment/queue model, whatever) is left to the user. Without anything fancier, this amounts to the limitation that Octave must drive the module... like, for example, an optimization package that calls Octave to evaluate an objective function.
</p>
<H3><a name="Octave_nn24">29.3.15 Memory management</a></H3>
<H3><a name="Octave_nn24">30.3.15 Memory management</a></H3>
<p>
@ -880,14 +880,14 @@ The %newobject directive may be used to control this behavior for pointers retur
In the case where one wishes for the C++ side to own an object that was created in Octave (especially a Director object), one can use the __disown() method to invert this logic. Then letting the Octave reference count go to zero will not destroy the object, but destroying the object will invalidate the Octave-side object if it still exists (and call destructors of other C++ bases in the case of multiple inheritance/<tt>subclass()</tt>'ing).
</p>
<H3><a name="Octave_nn25">29.3.16 STL support</a></H3>
<H3><a name="Octave_nn25">30.3.16 STL support</a></H3>
<p>
Various STL library files are provided for wrapping STL containers.
</p>
<H3><a name="Octave_nn26">29.3.17 Matrix typemaps</a></H3>
<H3><a name="Octave_nn26">30.3.17 Matrix typemaps</a></H3>
<p>

110
Doc/Manual/Perl5.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Perl5">30 SWIG and Perl5</a></H1>
<H1><a name="Perl5">31 SWIG and Perl5</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -97,7 +97,7 @@ later. We're no longer testing regularly with older versions, but
Perl 5.6 seems to mostly work, while older versions don't.
</p>
<H2><a name="Perl5_nn2">30.1 Overview</a></H2>
<H2><a name="Perl5_nn2">31.1 Overview</a></H2>
<p>
@ -118,7 +118,7 @@ described. Advanced customization features, typemaps, and other
options are found near the end of the chapter.
</p>
<H2><a name="Perl5_nn3">30.2 Preliminaries</a></H2>
<H2><a name="Perl5_nn3">31.2 Preliminaries</a></H2>
<p>
@ -143,7 +143,7 @@ To build the module, you will need to compile the file
<tt>example_wrap.c</tt> and link it with the rest of your program.
</p>
<H3><a name="Perl5_nn4">30.2.1 Getting the right header files</a></H3>
<H3><a name="Perl5_nn4">31.2.1 Getting the right header files</a></H3>
<p>
@ -175,7 +175,7 @@ $ perl -e 'use Config; print "$Config{archlib}\n";'
</pre>
</div>
<H3><a name="Perl5_nn5">30.2.2 Compiling a dynamic module</a></H3>
<H3><a name="Perl5_nn5">31.2.2 Compiling a dynamic module</a></H3>
<p>
@ -208,7 +208,7 @@ the target should be named `<tt>example.so</tt>',
`<tt>example.sl</tt>', or the appropriate dynamic module name on your system.
</p>
<H3><a name="Perl5_nn6">30.2.3 Building a dynamic module with MakeMaker</a></H3>
<H3><a name="Perl5_nn6">31.2.3 Building a dynamic module with MakeMaker</a></H3>
<p>
@ -242,7 +242,7 @@ the preferred approach to compilation. More information about MakeMaker can be
found in "Programming Perl, 2nd ed." by Larry Wall, Tom Christiansen,
and Randal Schwartz.</p>
<H3><a name="Perl5_nn7">30.2.4 Building a static version of Perl</a></H3>
<H3><a name="Perl5_nn7">31.2.4 Building a static version of Perl</a></H3>
<p>
@ -311,7 +311,7 @@ added to it. Depending on your machine, you may need to link with
additional libraries such as <tt>-lsocket, -lnsl, -ldl</tt>, etc.
</p>
<H3><a name="Perl5_nn8">30.2.5 Using the module</a></H3>
<H3><a name="Perl5_nn8">31.2.5 Using the module</a></H3>
<p>
@ -464,7 +464,7 @@ system configuration (this requires root access and you will need to
read the man pages).
</p>
<H3><a name="Perl5_nn9">30.2.6 Compilation problems and compiling with C++</a></H3>
<H3><a name="Perl5_nn9">31.2.6 Compilation problems and compiling with C++</a></H3>
<p>
@ -607,7 +607,7 @@ have to find the macro that conflicts and add an #undef into the .i file. Pleas
any conflicting macros you find to <a href="http://www.swig.org/mail.html">swig-user mailing list</a>.
</p>
<H3><a name="Perl5_nn10">30.2.7 Compiling for 64-bit platforms</a></H3>
<H3><a name="Perl5_nn10">31.2.7 Compiling for 64-bit platforms</a></H3>
<p>
@ -634,7 +634,7 @@ also introduce problems on platforms that support more than one
linking standard (e.g., -o32 and -n32 on Irix).
</p>
<H2><a name="Perl5_nn11">30.3 Building Perl Extensions under Windows</a></H2>
<H2><a name="Perl5_nn11">31.3 Building Perl Extensions under Windows</a></H2>
<p>
@ -645,7 +645,7 @@ section assumes you are using SWIG with Microsoft Visual C++
although the procedure may be similar with other compilers.
</p>
<H3><a name="Perl5_nn12">30.3.1 Running SWIG from Developer Studio</a></H3>
<H3><a name="Perl5_nn12">31.3.1 Running SWIG from Developer Studio</a></H3>
<p>
@ -708,7 +708,7 @@ print "$a\n";
</pre></div>
<H3><a name="Perl5_nn13">30.3.2 Using other compilers</a></H3>
<H3><a name="Perl5_nn13">31.3.2 Using other compilers</a></H3>
<p>
@ -716,7 +716,7 @@ SWIG is known to work with Cygwin and may work with other compilers on Windows.
For general hints and suggestions refer to the <a href="Windows.html#Windows">Windows</a> chapter.
</p>
<H2><a name="Perl5_nn14">30.4 The low-level interface</a></H2>
<H2><a name="Perl5_nn14">31.4 The low-level interface</a></H2>
<p>
@ -726,7 +726,7 @@ can be used to control your application. However, it is also used to
construct more user-friendly proxy classes as described in the next section.
</p>
<H3><a name="Perl5_nn15">30.4.1 Functions</a></H3>
<H3><a name="Perl5_nn15">31.4.1 Functions</a></H3>
<p>
@ -749,7 +749,7 @@ use example;
$a = &amp;example::fact(2);
</pre></div>
<H3><a name="Perl5_nn16">30.4.2 Global variables</a></H3>
<H3><a name="Perl5_nn16">31.4.2 Global variables</a></H3>
<p>
@ -819,7 +819,7 @@ extern char *path; // Declared later in the input
</pre>
</div>
<H3><a name="Perl5_nn17">30.4.3 Constants</a></H3>
<H3><a name="Perl5_nn17">31.4.3 Constants</a></H3>
<p>
@ -859,7 +859,7 @@ print example::FOO, "\n";
</pre>
</div>
<H3><a name="Perl5_nn18">30.4.4 Pointers</a></H3>
<H3><a name="Perl5_nn18">31.4.4 Pointers</a></H3>
<p>
@ -968,7 +968,7 @@ as XS and <tt>xsubpp</tt>. Given the advancement of the SWIG typesystem and the
SWIG and XS, this is no longer supported.
</p>
<H3><a name="Perl5_nn19">30.4.5 Structures</a></H3>
<H3><a name="Perl5_nn19">31.4.5 Structures</a></H3>
<p>
@ -1102,7 +1102,7 @@ void Bar_f_set(Bar *b, Foo *val) {
</div>
<H3><a name="Perl5_nn20">30.4.6 C++ classes</a></H3>
<H3><a name="Perl5_nn20">31.4.6 C++ classes</a></H3>
<p>
@ -1167,7 +1167,7 @@ provides direct access to C++ objects. A higher level interface using Perl prox
can be built using these low-level accessors. This is described shortly.
</p>
<H3><a name="Perl5_nn21">30.4.7 C++ classes and type-checking</a></H3>
<H3><a name="Perl5_nn21">31.4.7 C++ classes and type-checking</a></H3>
<p>
@ -1203,7 +1203,7 @@ If necessary, the type-checker also adjusts the value of the pointer (as is nece
multiple inheritance is used).
</p>
<H3><a name="Perl5_nn22">30.4.8 C++ overloaded functions</a></H3>
<H3><a name="Perl5_nn22">31.4.8 C++ overloaded functions</a></H3>
<p>
@ -1247,7 +1247,7 @@ example::Spam_foo_d($s, 3.14);
Please refer to the "SWIG Basics" chapter for more information.
</p>
<H3><a name="Perl5_nn23">30.4.9 Operators</a></H3>
<H3><a name="Perl5_nn23">31.4.9 Operators</a></H3>
<p>
@ -1274,7 +1274,7 @@ The following C++ operators are currently supported by the Perl module:
<li>operator or </li>
</ul>
<H3><a name="Perl5_nn24">30.4.10 Modules and packages</a></H3>
<H3><a name="Perl5_nn24">31.4.10 Modules and packages</a></H3>
<p>
@ -1369,7 +1369,7 @@ print Foo::fact(4), "\n"; # Call a function in package FooBar
</pre></div>
-->
<H2><a name="Perl5_nn25">30.5 Input and output parameters</a></H2>
<H2><a name="Perl5_nn25">31.5 Input and output parameters</a></H2>
<p>
@ -1588,7 +1588,7 @@ print "$c\n";
<b>Note:</b> The <tt>REFERENCE</tt> feature is only currently supported for numeric types (integers and floating point).
</p>
<H2><a name="Perl5_nn26">30.6 Exception handling</a></H2>
<H2><a name="Perl5_nn26">31.6 Exception handling</a></H2>
<p>
@ -1752,7 +1752,7 @@ This is still supported, but it is deprecated. The newer <tt>%exception</tt> di
functionality, but it has additional capabilities that make it more powerful.
</p>
<H2><a name="Perl5_nn27">30.7 Remapping datatypes with typemaps</a></H2>
<H2><a name="Perl5_nn27">31.7 Remapping datatypes with typemaps</a></H2>
<p>
@ -1769,7 +1769,7 @@ Typemaps are only used if you want to change some aspect of the primitive
C-Perl interface.
</p>
<H3><a name="Perl5_nn28">30.7.1 A simple typemap example</a></H3>
<H3><a name="Perl5_nn28">31.7.1 A simple typemap example</a></H3>
<p>
@ -1873,7 +1873,7 @@ example::count("e", "Hello World");
</div>
<H3><a name="Perl5_nn29">30.7.2 Perl5 typemaps</a></H3>
<H3><a name="Perl5_nn29">31.7.2 Perl5 typemaps</a></H3>
<p>
@ -1978,7 +1978,7 @@ Return of C++ member data (all languages).
Check value of input parameter.
</div>
<H3><a name="Perl5_nn30">30.7.3 Typemap variables</a></H3>
<H3><a name="Perl5_nn30">31.7.3 Typemap variables</a></H3>
<p>
@ -2049,7 +2049,7 @@ properly assigned.
The Perl name of the wrapper function being created.
</div>
<H3><a name="Perl5_nn31">30.7.4 Useful functions</a></H3>
<H3><a name="Perl5_nn31">31.7.4 Useful functions</a></H3>
<p>
@ -2118,7 +2118,7 @@ int sv_isa(SV *, char *0;
</div>
<H2><a name="Perl5_nn32">30.8 Typemap Examples</a></H2>
<H2><a name="Perl5_nn32">31.8 Typemap Examples</a></H2>
<p>
@ -2127,7 +2127,7 @@ might look at the files "<tt>perl5.swg</tt>" and "<tt>typemaps.i</tt>" in
the SWIG library.
</p>
<H3><a name="Perl5_nn33">30.8.1 Converting a Perl5 array to a char **</a></H3>
<H3><a name="Perl5_nn33">31.8.1 Converting a Perl5 array to a char **</a></H3>
<p>
@ -2219,7 +2219,7 @@ print @$b, "\n"; # Print it out
</pre></div>
<H3><a name="Perl5_nn34">30.8.2 Return values</a></H3>
<H3><a name="Perl5_nn34">31.8.2 Return values</a></H3>
<p>
@ -2243,12 +2243,12 @@ can be done using the <tt>EXTEND()</tt> macro as in:
EXTEND(sp, 1); /* Extend the stack by 1 object */
}
$result = sv_newmortal();
sv_setiv($target, (IV) *($1));
sv_setiv($result, (IV) *($1));
argvi++;
}
</pre></div>
<H3><a name="Perl5_nn35">30.8.3 Returning values from arguments</a></H3>
<H3><a name="Perl5_nn35">31.8.3 Returning values from arguments</a></H3>
<p>
@ -2302,7 +2302,7 @@ print "multout(7, 13) = @r\n";
($x, $y) = multout(7, 13);
</pre></div>
<H3><a name="Perl5_nn36">30.8.4 Accessing array structure members</a></H3>
<H3><a name="Perl5_nn36">31.8.4 Accessing array structure members</a></H3>
<p>
@ -2365,7 +2365,7 @@ the "in" typemap in the previous section would be used to convert an
to copy the converted array into a C data structure.
</p>
<H3><a name="Perl5_nn37">30.8.5 Turning Perl references into C pointers</a></H3>
<H3><a name="Perl5_nn37">31.8.5 Turning Perl references into C pointers</a></H3>
<p>
@ -2430,7 +2430,7 @@ print "$c\n";
</pre></div>
<H3><a name="Perl5_nn38">30.8.6 Pointer handling</a></H3>
<H3><a name="Perl5_nn38">31.8.6 Pointer handling</a></H3>
<p>
@ -2515,7 +2515,7 @@ For example:
</pre>
</div>
<H2><a name="Perl5_nn39">30.9 Proxy classes</a></H2>
<H2><a name="Perl5_nn39">31.9 Proxy classes</a></H2>
<p>
@ -2531,7 +2531,7 @@ to the underlying code. This section describes the implementation
details of the proxy interface.
</p>
<H3><a name="Perl5_nn40">30.9.1 Preliminaries</a></H3>
<H3><a name="Perl5_nn40">31.9.1 Preliminaries</a></H3>
<p>
@ -2553,7 +2553,7 @@ SWIG creates a collection of high-level Perl wrappers. In your scripts, you wil
high level wrappers. The wrappers, in turn, interact with the low-level procedural module.
</p>
<H3><a name="Perl5_nn41">30.9.2 Structure and class wrappers</a></H3>
<H3><a name="Perl5_nn41">31.9.2 Structure and class wrappers</a></H3>
<p>
@ -2680,7 +2680,7 @@ $v-&gt;DESTROY();
</pre></div>
<H3><a name="Perl5_nn42">30.9.3 Object Ownership</a></H3>
<H3><a name="Perl5_nn42">31.9.3 Object Ownership</a></H3>
<p>
@ -2767,7 +2767,7 @@ counting, garbage collection, or advanced features one might find in
sophisticated languages.
</p>
<H3><a name="Perl5_nn43">30.9.4 Nested Objects</a></H3>
<H3><a name="Perl5_nn43">31.9.4 Nested Objects</a></H3>
<p>
@ -2820,7 +2820,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">30.9.5 Proxy Functions</a></H3>
<H3><a name="Perl5_nn44">31.9.5 Proxy Functions</a></H3>
<p>
@ -2854,7 +2854,7 @@ This function replaces the original function, but operates in an
identical manner.
</p>
<H3><a name="Perl5_nn45">30.9.6 Inheritance</a></H3>
<H3><a name="Perl5_nn45">31.9.6 Inheritance</a></H3>
<p>
@ -2930,7 +2930,7 @@ particular, inheritance of data members is extremely tricky (and I'm
not even sure if it really works).
</p>
<H3><a name="Perl5_nn46">30.9.7 Modifying the proxy methods</a></H3>
<H3><a name="Perl5_nn46">31.9.7 Modifying the proxy methods</a></H3>
<p>
@ -2958,7 +2958,7 @@ public:
};
</pre></div>
<H2><a name="Perl5_nn47">30.10 Adding additional Perl code</a></H2>
<H2><a name="Perl5_nn47">31.10 Adding additional Perl code</a></H2>
<p>
@ -3009,7 +3009,7 @@ set_transform($im, $a);
</pre>
</div>
<H2><a name="Perl5_directors">30.11 Cross language polymorphism</a></H2>
<H2><a name="Perl5_directors">31.11 Cross language polymorphism</a></H2>
<p>
@ -3043,7 +3043,7 @@ proxy classes, director classes, and C wrapper functions takes care of
all the cross-language method routing transparently.
</p>
<H3><a name="Perl5_nn48">30.11.1 Enabling directors</a></H3>
<H3><a name="Perl5_nn48">31.11.1 Enabling directors</a></H3>
<p>
@ -3133,7 +3133,7 @@ sub one {
</div>
<H3><a name="Perl5_nn49">30.11.2 Director classes</a></H3>
<H3><a name="Perl5_nn49">31.11.2 Director classes</a></H3>
@ -3214,7 +3214,7 @@ so there is no need for the extra overhead involved with routing the
calls through Perl.
</p>
<H3><a name="Perl5_nn50">30.11.3 Ownership and object destruction</a></H3>
<H3><a name="Perl5_nn50">31.11.3 Ownership and object destruction</a></H3>
<p>
@ -3263,7 +3263,7 @@ sub DESTROY {
</div>
<H3><a name="Perl5_nn51">30.11.4 Exception unrolling</a></H3>
<H3><a name="Perl5_nn51">31.11.4 Exception unrolling</a></H3>
<p>
@ -3319,7 +3319,7 @@ Swig::DirectorMethodException is thrown, Perl will register the
exception as soon as the C wrapper function returns.
</p>
<H3><a name="Perl5_nn52">30.11.5 Overhead and code bloat</a></H3>
<H3><a name="Perl5_nn52">31.11.5 Overhead and code bloat</a></H3>
<p>
@ -3353,7 +3353,7 @@ directive) for only those methods that are likely to be extended in
Perl.
</p>
<H3><a name="Perl5_nn53">30.11.6 Typemaps</a></H3>
<H3><a name="Perl5_nn53">31.11.6 Typemaps</a></H3>
<p>

245
Doc/Manual/Php.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Php">31 SWIG and PHP</a></H1>
<H1><a name="Php">32 SWIG and PHP</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -50,18 +50,21 @@
<p>
In this chapter, we discuss SWIG's support of PHP. SWIG currently supports
generating wrappers for PHP7. Support for PHP5 was removed in SWIG 4.0.0
and support for PHP4 was removed in SWIG 1.3.37.
In this chapter, we discuss SWIG's support of PHP. Currently any PHP7 or PHP8
release should work.
</p>
<p>
Currently any PHP7 release should work.
Support for PHP7 was added in SWIG 3.0.11 and for PHP8 in 4.1.0.
Support for PHP5 was removed in SWIG 4.0.0 and support for PHP4 was removed in
SWIG 1.3.37. There never was a PHP6 release.
</p>
</p>
<p>
In order to use this module, you will need to have a copy of the PHP
include files to compile the SWIG generated files. If you installed
include files to compile the SWIG generated C/C++ sources. If you installed
PHP from a binary package, you may need to install a "php-dev" or "php-devel"
package for these to be installed. You can find out where these files are
by running <tt>php-config --includes</tt>. To use the built PHP module you
@ -70,7 +73,7 @@ your extension into php directly, you will need the complete PHP source tree
available.
</p>
<H2><a name="Php_nn1">31.1 Generating PHP Extensions</a></H2>
<H2><a name="Php_nn1">32.1 Generating PHP Extensions</a></H2>
<p>
@ -84,16 +87,21 @@ swig -php7 example.i
</pre></div>
<p>
This will produce 3 files example_wrap.c, php_example.h and
example.php. The first file, <tt>example_wrap.c</tt> contains all of
This will produce 2 files: example_wrap.c and php_example.h.
The first file, <tt>example_wrap.c</tt> contains all of
the C code needed to build a PHP extension. The second file,
<tt>php_example.h</tt> contains the header information needed if
you wish to statically link the extension into the php interpreter.
The third file,
<tt>example.php</tt> can be included by PHP scripts. It attempts to
dynamically load the extension and contains extra php code specified
in the interface file. If wrapping C++ code with PHP classes, it will
also contain PHP class wrappers.
</p>
<p>
If the interface file uses <tt>%pragma(php) include=</tt>... or
<tt>%pragma(php) code=</tt>... then SWIG will also generate a third file,
<tt>example.php</tt> to contain what these specify. In SWIG &lt; 4.1.0,
this third file was always generated as it defined the PHP classes, etc
(but this is now done via C code in <tt>example_wrap.c</tt>) and also
contained code to dynamically load the extension (but this used the
PHP <tt>dl()</tt> function, which isn't recommended nowadays).
</p>
<p>
@ -119,7 +127,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">31.1.1 Building a loadable extension</a></H3>
<H3><a name="Php_nn1_1">32.1.1 Building a loadable extension</a></H3>
<p>
@ -134,13 +142,25 @@ least work for Linux though):
gcc -shared example_wrap.o example.o -o example.so
</pre></div>
<H3><a name="Php_nn1_3">31.1.2 Using PHP Extensions</a></H3>
<H3><a name="Php_nn1_3">32.1.2 Using PHP Extensions</a></H3>
<p>
To test the extension from a PHP script, you first need to tell PHP to
load it. To do this, add a line like this to the <tt>[PHP]</tt> section of
<tt>php.ini</tt>:
load it. Assuming you're using PHP 7.2 or higher, the recommended (and
simplest!) way to do this is to copy it to PHP's default extension directory
and add a line like this to the <tt>[PHP]</tt> section of <tt>php.ini</tt>:
</p>
<div class="code"><pre>
extension=modulename
</pre></div>
<p>
PHP &lt; 7.2 doesn't support loading by just the module name, so you need
to specify the filename of the module to be specified, which varies
between platforms. And for any PHP version, if the module is not in PHP's
default extension directory, you also need to specify the path, for example:
</p>
<div class="code"><pre>
@ -148,13 +168,9 @@ load it. To do this, add a line like this to the <tt>[PHP]</tt> section of
</pre></div>
<p>
If the module is in PHP's default extension directory, you can omit the path.
</p>
<p>
For some SAPIs (for example, the CLI SAPI) you can instead use the
<a href="https://www.php.net/manual/en/function.dl.php">dl() function</a> to load
an extension at run time, by adding a line like this to the start of each
If you're using the PHP CLI SAPI it's possible (but not recommended) to use the
<a href="https://www.php.net/manual/en/function.dl.php">dl() function</a> to
load an extension at run time, by adding a line like this to the start of each
PHP script which uses your extension:
</p>
@ -163,26 +179,14 @@ PHP script which uses your extension:
</pre></div>
<p>
But note that <tt>dl()</tt> isn't supported when running PHP through a
webserver - you'll need to use <tt>extension</tt> in <tt>php.ini</tt> as
described above.
But to do this portably you need to take into account that pathnames and the
filename extension vary by platform, and for security reasons PHP no longer
supports <tt>dl()</tt> when running PHP through a webserver. Overall it's
better to instead use <tt>extension</tt> in <tt>php.ini</tt> as described
above.
</p>
<p>
The PHP module which SWIG generates will also attempt to do the <tt>dl()</tt>
call for you if the extension isn't already loaded:
</p>
<div class="code"><pre>
include("example.php");
</pre></div>
<p>
This PHP module also defines the PHP classes for the wrapped API, so you'll
almost certainly want to include it anyway.
</p>
<H2><a name="Php_nn2">31.2 Basic PHP interface</a></H2>
<H2><a name="Php_nn2">32.2 Basic PHP interface</a></H2>
<p>
@ -194,7 +198,7 @@ SWIG doesn't have support for generating wrappers which make use of PHP's
namespace feature.
</p>
<H3><a name="Php_nn2_1">31.2.1 Constants</a></H3>
<H3><a name="Php_nn2_1">32.2.1 Constants</a></H3>
<p>
@ -219,24 +223,19 @@ you can access the constants in your PHP script like this,
</p>
<div class="code"><pre>
include("example.php");
echo "PI = " . PI . "\n";
echo "E = " . E . "\n";
</pre>
</div>
<p>
There's one peculiarity of how constants work in PHP which it is useful
to note (this is not specific to SWIG though) - if you try to use an undeclared
constant, PHP will emit a warning (or a notice in PHP 7.1 and earlier) and then
expand the constant to a string version of the constant's name. Unfortunately
it is easy to miss the warning message if you're using PHP in a webserver as
it will probably end up in error.log or similar. Apparently this will throw
an Error in a future version of PHP, but until then it's something to be
aware of.
There's one peculiarity of how constants work in PHP prior to PHP 8
which it is useful to note (this is not specific to SWIG though) - if you try
to use an undeclared constant, PHP will emit a warning (or a notice in PHP 7.1
and earlier) and then expand the constant to a string version of the constant's
name. Unfortunately it is easy to miss the warning message if you're using PHP
in a webserver as it will probably end up in error.log or similar. PHP 8.0
made this an error.
</p>
<p>
@ -256,8 +255,6 @@ accessed incorrectly in PHP,
<div class="code">
<pre>
include("example.php");
if(EASY_TO_MISPEL) {
...
} else {
@ -273,7 +270,7 @@ is treated as true by the if test, when the value of the intended constant
would be treated as false!
</p>
<H3><a name="Php_nn2_2">31.2.2 Global Variables</a></H3>
<H3><a name="Php_nn2_2">32.2.2 Global Variables</a></H3>
<p>
@ -298,7 +295,6 @@ is accessed as follows:
</p>
<div class="code"><pre>
include("example.php");
print seki_get();
seki_set( seki_get() * 2); # The C variable is now 4.
print seki_get();
@ -306,8 +302,10 @@ print seki_get();
<p>
SWIG supports global variables of all C datatypes including pointers
and complex objects. Additional types can be supported by using the
<tt>varinit</tt> typemap.
and complex objects. To support additional types, you just need to
supply the standard <tt>in</tt> and <tt>out</tt> typemaps, which get
used because of the wrapping as <tt>_get()</tt> and <tt>_set()</tt>
functions.
</p>
<p>
@ -322,7 +320,7 @@ undefined.
At this time SWIG does not support custom accessor methods.
</p>
<H3><a name="Php_nn2_3">31.2.3 Functions</a></H3>
<H3><a name="Php_nn2_3">32.2.3 Functions</a></H3>
<p>
@ -342,7 +340,6 @@ Will be accessed in PHP like this :
</p>
<div class="code"><pre>
include("example.php");
$a = foo(2);
$b = bar(3.5, -1.5);
$c = bar(3.5); # Use default argument for 2nd parameter
@ -375,7 +372,7 @@ print $s; # The value of $s was not changed.
-->
<H3><a name="Php_nn2_4">31.2.4 Overloading</a></H3>
<H3><a name="Php_nn2_4">32.2.4 Overloading</a></H3>
<p>
@ -430,12 +427,15 @@ taking the integer argument.
</p>
-->
<H3><a name="Php_nn2_5">31.2.5 Pointers and References</a></H3>
<H3><a name="Php_nn2_5">32.2.5 Pointers and References</a></H3>
<p>
Pointers to C/C++ objects are represented
as PHP resources, rather like MySQL connection handles.
Since SWIG 4.1.0, SWIG wraps C/C++ classes directly with PHP objects.
Pointers to other types are also wrapped as PHP objects - mostly this is an
implementation detail, but it's visible from PHP via <tt>is_object()</tt> and
similar. In earlier SWIG versions, PHP resources were used to wrap both
classes and pointers to other types.
</p>
<p>
@ -467,8 +467,6 @@ This will result in the following usage in PHP:
<div class="code"><pre>
&lt;?php
include("example.php");
$in1=copy_intp(3);
$in2=copy_intp(5);
$result=new_intp();
@ -476,7 +474,6 @@ $result=new_intp();
add( $in1, $in2, $result );
echo "The sum " . intp_value($in1) . " + " . intp_value($in2) . " = " . intp_value( $result) . "\n";
?&gt;
</pre></div>
<p>
@ -501,14 +498,11 @@ This will result in the following usage in PHP:
<div class="code"><pre>
&lt;?php
include("example.php");
$in1 = 3;
$in2 = 5;
$result= add($in1, $in2); # Note using variables for the input is unnecessary.
echo "The sum $in1 + $in2 = $result\n";
?&gt;
</pre></div>
<p>
@ -539,15 +533,12 @@ This will result in the following usage in PHP:
<div class="code"><pre>
&lt;?php
include("example.php");
$in1 = 3;
$in2 = 5;
$result = 0;
add($in1, $in2, $result);
echo "The sum $in1 + $in2 = $result\n";
?&gt;
</pre></div>
<p>
@ -568,15 +559,20 @@ 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">31.2.6 Structures and C++ classes</a></H3>
<H3><a name="Php_nn2_6">32.2.6 Structures and C++ classes</a></H3>
<p>
SWIG defaults to wrapping C++ structs and classes with PHP classes - this
is done by generating a PHP wrapper script which defines proxy classes
which calls a set of flat functions which actually wrap the C++ class.
You can disable this wrapper layer by passing the command-line option
"-noproxy" in which case you'll just get the flat functions.
SWIG defaults to wrapping C++ structs and classes with PHP classes.
Since SWIG 4.1.0, this is done entirely via PHP's C API - earlier SWIG
versions generated a PHP wrapper script which defined proxy classes
which called a set of flat functions which actually wrapped the C++ class.
</p>
<p>
If you don't want the class wrappers, you can pass the command-line option
"-noproxy" in which case you'll get C++ classes wrapped as flat functions
as described below.
</p>
<p>
@ -605,7 +601,6 @@ Would be used in the following way from PHP:
<div class="code"><pre>
&lt;?php
require "vector.php";
$v = new Vector();
$v-&gt;x = 3;
@ -622,14 +617,13 @@ Would be used in the following way from PHP:
$c-&gt;im = 0;
# $c destructor called when $c goes out of scope.
?&gt;
</pre></div>
<p>
Member variables and methods are accessed using the <tt>-&gt;</tt> operator.
</p>
<H4><a name="Php_nn2_6_1">31.2.6.1 Using -noproxy</a></H4>
<H4><a name="Php_nn2_6_1">32.2.6.1 Using -noproxy</a></H4>
<p>
@ -655,7 +649,7 @@ Complex_im_set($obj, $d);
Complex_im_get($obj);
</pre></div>
<H4><a name="Php_nn2_6_2">31.2.6.2 Constructors and Destructors</a></H4>
<H4><a name="Php_nn2_6_2">32.2.6.2 Constructors and Destructors</a></H4>
<p>
@ -667,8 +661,8 @@ constructor to execute.
</p>
<p>
Because PHP uses reference counting to manage resources, simple
assignment of one variable to another such as:
Because PHP uses reference counting, simple assignment of one variable to
another such as:
</p>
<div class="code"><pre>
@ -696,7 +690,7 @@ the programmer can either reassign the variable or call
<tt>unset($v)</tt>
</p>
<H4><a name="Php_nn2_6_3">31.2.6.3 Static Member Variables</a></H4>
<H4><a name="Php_nn2_6_3">32.2.6.3 Static Member Variables</a></H4>
<p>
@ -721,8 +715,6 @@ would be accessed in PHP as,
</p>
<div class="code"><pre>
include("example.php");
echo "There have now been " . Ko::threats() . " threats\n";
</pre></div>
@ -739,7 +731,7 @@ Ko::threats(10);
echo "There have now been " . Ko::threats() . " threats\n";
</pre></div>
<H4><a name="Php_nn2_6_4">31.2.6.4 Static Member Functions</a></H4>
<H4><a name="Php_nn2_6_4">32.2.6.4 Static Member Functions</a></H4>
<p>
@ -756,12 +748,11 @@ class Ko {
would be executed in PHP as,
<div class="code"><pre>
include("example.php");
Ko::threats();
</pre></div>
<H4><a name="Php_nn2_6_5">31.2.6.5 Specifying Implemented Interfaces</a></H4>
<H4><a name="Php_nn2_6_5">32.2.6.5 Specifying Implemented Interfaces</a></H4>
<p>
@ -779,13 +770,12 @@ so:
If there are multiple interfaces, just list them separated by commas.
</p>
<H3><a name="Php_nn2_7">31.2.7 PHP Pragmas, Startup and Shutdown code</a></H3>
<H3><a name="Php_nn2_7">32.2.7 PHP Pragmas, Startup and Shutdown code</a></H3>
<p>
To place PHP code in the generated "example.php" file one can use the
<b>code</b> pragma. The code is inserted after loading the shared
object.
You can get SWIG to generate an "example.php" file by specifying
the code to put in it using the <b>code</b> pragma.
</p>
<div class="code"><pre>
@ -876,14 +866,14 @@ The <tt>%rinit</tt> and <tt>%rshutdown</tt> statements are very similar but inse
into the request init (PHP_RINIT_FUNCTION) and request shutdown (PHP_RSHUTDOWN_FUNCTION) code respectively.
</p>
<H2><a name="Php_nn3">31.3 Cross language polymorphism</a></H2>
<H2><a name="Php_nn3">32.3 Cross language polymorphism</a></H2>
<p>
Proxy classes provide a more natural, object-oriented way to access
extension classes. As described above, each proxy instance has an
associated C++ instance, and method calls to the proxy are passed to the
C++ instance transparently via C wrapper functions.
C++ instance transparently.
</p>
<p>
@ -911,7 +901,7 @@ wrapper functions takes care of all the cross-language method routing
transparently.
</p>
<H3><a name="Php_nn3_1">31.3.1 Enabling directors</a></H3>
<H3><a name="Php_nn3_1">32.3.1 Enabling directors</a></H3>
<p>
@ -989,8 +979,6 @@ then at the PHP side you can define
<div class="targetlang">
<pre>
require("mymodule.php");
class MyFoo extends Foo {
function one() {
print "one from php\n";
@ -1000,7 +988,7 @@ class MyFoo extends Foo {
</div>
<H3><a name="Php_nn3_2">31.3.2 Director classes</a></H3>
<H3><a name="Php_nn3_2">32.3.2 Director classes</a></H3>
@ -1012,8 +1000,8 @@ that derives from both the class in question and a special
<tt>Swig::Director</tt> class. These new classes, referred to as director
classes, can be loosely thought of as the C++ equivalent of the PHP
proxy classes. The director classes store a pointer to their underlying
PHP object. Indeed, this is quite similar to the "_cPtr" and "thisown"
members of the PHP proxy classes.
PHP object. Indeed, this is quite similar to <tt>struct swig_object_wrapper</tt>
which is used to implement the PHP proxy classes.
</p>
<p>
@ -1068,12 +1056,12 @@ infinite loop.
<p>
One more point needs to be made about the relationship between director
classes and proxy classes. When a proxy class instance is created in
PHP, SWIG creates an instance of the original C++ class and assigns it
to <tt>-&gt;_cPtr</tt>. This is exactly what happens without directors
and is true even if directors are enabled for the particular class in
question. When a class <i>derived</i> from a proxy class is created,
however, SWIG then creates an instance of the corresponding C++ director
class. The reason for this difference is that user-defined subclasses
PHP, SWIG creates an instance of the original C++ class and stores it
in the <tt>struct swig_object_wrapper</tt>. This is true whether or not
directors are enabled for the particular class in question. However
when a class <i>derived</i> from a proxy class is created, SWIG instead
creates an instance of the corresponding C++ director class.
The reason for this difference is that user-defined subclasses
may override or extend methods of the original class, so the director
class is needed to route calls to these methods correctly. For
unmodified proxy classes, all methods are ultimately implemented in C++
@ -1081,7 +1069,7 @@ so there is no need for the extra overhead involved with routing the
calls through PHP.
</p>
<H3><a name="Php_nn3_3">31.3.3 Ownership and object destruction</a></H3>
<H3><a name="Php_nn3_3">32.3.3 Ownership and object destruction</a></H3>
<p>
@ -1137,7 +1125,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">31.3.4 Exception unrolling</a></H3>
<H3><a name="Php_nn3_4">32.3.4 Exception unrolling</a></H3>
<p>
@ -1161,13 +1149,32 @@ should suffice in most cases:
<div class="code">
<pre>
%feature("director:except") {
if ($error == FAILURE) {
#if SWIG_VERSION &gt;= 0x040100
if ($error != NULL)
#else
if ($error == FAILURE)
#endif
{
throw Swig::DirectorMethodException();
}
}
</pre>
</div>
<p>
If you only need to support SWIG &gt;= 4.1.0, you can just use the
<tt>($error != NULL)</tt> condition.
</p>
<p>
In SWIG 4.1.0, <tt>$error</tt> was changed in the SWIG/PHP director
implementation to make it work more like how it does for other languages.
Previously, <tt>$error</tt> didn't actually indicate an exception, but instead
was only set to <tt>FAILURE</tt> if there was a problem calling the PHP method.
Now <tt>$error</tt> indicates if the PHP method threw a PHP exception, and
directorout typemaps for PHP no longer need to be gated by <tt>if (EG(exception))</tt>.
</p>
<p>
This code will check the PHP error state after each method call from a
director into PHP, and throw a C++ exception if an error occurred. This
@ -1204,7 +1211,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">31.3.5 Overhead and code bloat</a></H3>
<H3><a name="Php_nn3_5">32.3.5 Overhead and code bloat</a></H3>
<p>
@ -1237,7 +1244,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">31.3.6 Typemaps</a></H3>
<H3><a name="Php_nn3_6">32.3.6 Typemaps</a></H3>
<p>
@ -1251,7 +1258,7 @@ need to be supported.
</p>
<H3><a name="Php_nn3_7">31.3.7 Miscellaneous</a></H3>
<H3><a name="Php_nn3_7">32.3.7 Miscellaneous</a></H3>
<p> Director typemaps for STL classes are mostly in place, and hence you

246
Doc/Manual/Pike.html
View file

@ -1,246 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and Pike</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Pike">37 SWIG and Pike</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Pike_nn2">Preliminaries</a>
<ul>
<li><a href="#Pike_nn3">Running SWIG</a>
<li><a href="#Pike_nn4">Getting the right header files</a>
<li><a href="#Pike_nn5">Using your module</a>
</ul>
<li><a href="#Pike_nn6">Basic C/C++ Mapping</a>
<ul>
<li><a href="#Pike_nn7">Modules</a>
<li><a href="#Pike_nn8">Functions</a>
<li><a href="#Pike_nn9">Global variables</a>
<li><a href="#Pike_nn10">Constants and enumerated types</a>
<li><a href="#Pike_nn11">Constructors and Destructors</a>
<li><a href="#Pike_nn12">Static Members</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<p>
This chapter describes SWIG support for Pike. As of this writing, the
SWIG Pike module is still under development and is not considered
ready for prime time. The Pike module is being developed against the
Pike 7.4.10 release and may not be compatible with previous versions
of Pike.
</p>
<p>
This chapter covers most SWIG features, but certain low-level details
are covered in less depth than in earlier chapters. At the very
least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>"
chapter.<br>
</p>
<H2><a name="Pike_nn2">37.1 Preliminaries</a></H2>
<H3><a name="Pike_nn3">37.1.1 Running SWIG</a></H3>
<p>
Suppose that you defined a SWIG module such as the following:
</p>
<div class="code">
<pre>%module example<br><br>%{<br>#include "example.h"<br>%}<br><br>int fact(int n);<br></pre>
</div>
<p>
To build a C extension module for Pike, run SWIG using the <tt>-pike</tt> option :
</p>
<div class="code">
<pre>$ <b>swig -pike example.i</b><br></pre>
</div>
<p>
If you're building a C++ extension, be sure to add the <tt>-c++</tt> option:
</p>
<div class="code">
<pre>$ <b>swig -c++ -pike example.i</b><br></pre>
</div>
<p>
This creates a single source file named <tt>example_wrap.c</tt> (or <tt>example_wrap.cxx</tt>, if you
ran SWIG with the <tt>-c++</tt> option).
The SWIG-generated source file contains the low-level wrappers that need
to be compiled and linked with the rest of your C/C++ application to
create an extension module.
</p>
<p>
The name of the wrapper file is derived from the name of the input
file. For example, if the input file is <tt>example.i</tt>, the name
of the wrapper file is <tt>example_wrap.c</tt>. To change this, you
can use the <tt>-o</tt> option:
</p>
<div class="code">
<pre>$ <b>swig -pike -o pseudonym.c example.i</b><br></pre>
</div>
<H3><a name="Pike_nn4">37.1.2 Getting the right header files</a></H3>
<p>
In order to compile the C/C++ wrappers, the compiler needs to know the
path to the Pike header files. These files are usually contained in a
directory such as
</p>
<div class="code">
<pre>/usr/local/pike/7.4.10/include/pike<br></pre>
</div>
<p>
There doesn't seem to be any way to get Pike itself to reveal the
location of these files, so you may need to hunt around for them.
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">37.1.3 Using your module</a></H3>
<p>
To use your module, simply use Pike's <tt>import</tt> statement:
</p>
<div class="code"><pre>
$ <b>pike</b>
Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend)
&gt; <b>import example;</b>
&gt; <b>fact(4);</b>
(1) Result: 24
</pre></div>
<H2><a name="Pike_nn6">37.2 Basic C/C++ Mapping</a></H2>
<H3><a name="Pike_nn7">37.2.1 Modules</a></H3>
<p>
All of the code for a given SWIG module is wrapped into a single Pike
module. Since the name of the shared library that implements your
module ultimately determines the module's name (as far as Pike is
concerned), SWIG's <tt>%module</tt> directive doesn't really have any
significance.
</p>
<H3><a name="Pike_nn8">37.2.2 Functions</a></H3>
<p>
Global functions are wrapped as new Pike built-in functions. For
example,
</p>
<div class="code"><pre>
%module example
int fact(int n);
</pre></div>
<p>
creates a new built-in function <tt>example.fact(n)</tt> that works
exactly as you'd expect it to:
</p>
<div class="code"><pre>
&gt; <b>import example;</b>
&gt; <b>fact(4);</b>
(1) Result: 24
</pre></div>
<H3><a name="Pike_nn9">37.2.3 Global variables</a></H3>
<p>
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>
<div class="code"><pre>
%module example
double Foo;
</pre></div>
<p>
will result in two functions, <tt>Foo_get()</tt> and <tt>Foo_set()</tt>:
</p>
<div class="code"><pre>
&gt; <b>import example;</b>
&gt; <b>Foo_get();</b>
(1) Result: 3.000000
&gt; <b>Foo_set(3.14159);</b>
(2) Result: 0
&gt; <b>Foo_get();</b>
(3) Result: 3.141590
</pre></div>
<H3><a name="Pike_nn10">37.2.4 Constants and enumerated types</a></H3>
<p>
Enumerated types in C/C++ declarations are wrapped as Pike constants,
not as Pike enums.
</p>
<H3><a name="Pike_nn11">37.2.5 Constructors and Destructors</a></H3>
<p>
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">37.2.6 Static Members</a></H3>
<p>
Since Pike doesn't support static methods or data for Pike classes, static
member functions in your C++ classes are wrapped as regular functions and
static member variables are wrapped as pairs of functions (one to get the
value of the static member variable, and another to set it). The names of
these functions are prepended with the name of the class.
For example, given this C++ class declaration:
</p>
<div class="code"><pre>
class Shape
{
public:
static void print();
static int nshapes;
};
</pre></div>
<p>
SWIG will generate a <tt>Shape_print()</tt> method that invokes the static
<tt>Shape::print()</tt> member function, as well as a pair of methods,
<tt>Shape_nshapes_get()</tt> and <tt>Shape_nshapes_set()</tt>, to get and set
the value of <tt>Shape::nshapes</tt>.
</p>
</body>
</html>

56
Doc/Manual/Preprocessor.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Preprocessor">10 Preprocessing</a></H1>
<H1><a name="Preprocessor">11 Preprocessing</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -38,7 +38,7 @@ However, a number of modifications and enhancements have been made. This
chapter describes some of these modifications.
</p>
<H2><a name="Preprocessor_nn2">10.1 File inclusion</a></H2>
<H2><a name="Preprocessor_nn2">11.1 File inclusion</a></H2>
<p>
@ -64,7 +64,7 @@ By default, the <tt>#include</tt> is ignored unless you run SWIG with the
is that you often don't want SWIG to try and wrap everything included
in standard header system headers and auxiliary files.
<H2><a name="Preprocessor_nn3">10.2 File imports</a></H2>
<H2><a name="Preprocessor_nn3">11.2 File imports</a></H2>
<p>
@ -93,7 +93,7 @@ The <tt>-importall</tt> directive tells SWIG to follow all <tt>#include</tt> sta
as imports. This might be useful if you want to extract type definitions from system
header files without generating any wrappers.
<H2><a name="Preprocessor_condition_compilation">10.3 Conditional Compilation</a></H2>
<H2><a name="Preprocessor_condition_compilation">11.3 Conditional Compilation</a></H2>
<p>
@ -110,18 +110,20 @@ SWIG_VERSION Hexadecimal (binary-coded decimal) number contai
such as 0x010311 (corresponding to SWIG-1.3.11).
SWIGCSHARP Defined when using C#
SWIGD Defined when using D
SWIGGO Defined when using Go
SWIGGUILE Defined when using Guile
SWIGJAVA Defined when using Java
SWIGJAVASCRIPT Defined when using Javascript
SWIG_JAVASCRIPT_JSC Defined when using Javascript for JavascriptCore
SWIG_JAVASCRIPT_V8 Defined when using Javascript for v8 or node.js
SWIG_JAVASCRIPT_JSC Defined when using Javascript with -jsc
SWIG_JAVASCRIPT_V8 Defined when using Javascript with -v8 or -node
SWIGLUA Defined when using Lua
SWIGMZSCHEME Defined when using Mzscheme
SWIGOCAML Defined when using OCaml
SWIGOCTAVE Defined when using Octave
SWIGPERL Defined when using Perl
SWIGPHP Defined when using PHP (any version)
SWIGPHP7 Defined when using PHP7
SWIGPHP7 Defined when using PHP 7 or later (with a compatible C API)
SWIGPYTHON Defined when using Python
SWIGR Defined when using R
SWIGRUBY Defined when using Ruby
@ -144,14 +146,26 @@ __cplusplus Defined when -c++ option used
</div>
<p>
Interface files can look at these symbols as necessary to change the
way in which an interface is generated or to mix SWIG directives with
C code. These symbols are also defined within the C code generated by
SWIG (except for the symbol `<tt>SWIG</tt>' which is only defined
within the SWIG compiler).
The following are language specific symbols that might be defined:
</p>
<H2><a name="Preprocessor_nn5">10.4 Macro Expansion</a></H2>
<div class="code"><pre>
SWIG_D_VERSION Unsigned integer target version when using D
SWIGGO_CGO Defined when using Go for cgo
SWIGGO_GCCGO Defined when using Go for gccgo
SWIGGO_INTGO_SIZE Size of the Go type int when using Go (32 or 64)
SWIGPYTHON_PY3 Defined when using Python with -py3
SWIGPYTHON_BUILTIN Defined when using Python with -builtin
SWIG_RUBY_AUTORENAME Defined when using Ruby with -autorename
</pre></div>
<p>
Interface files can look at these symbols as necessary to change the
way in which an interface is generated or to mix SWIG directives with
C code.
</p>
<H2><a name="Preprocessor_nn5">11.4 Macro Expansion</a></H2>
<p>
@ -206,7 +220,7 @@ like <tt>#x</tt>. This is a non-standard SWIG extension.
</li>
</ul>
<H2><a name="Preprocessor_nn6">10.5 SWIG Macros</a></H2>
<H2><a name="Preprocessor_nn6">11.5 SWIG Macros</a></H2>
<p>
@ -252,7 +266,7 @@ many of SWIG's advanced features and libraries are built using this mechanism (s
support).
</p>
<H2><a name="Preprocessor_nn7">10.6 C99 and GNU Extensions</a></H2>
<H2><a name="Preprocessor_nn7">11.6 C99 and GNU Extensions</a></H2>
<p>
@ -308,14 +322,14 @@ interface building. However, they are used internally to implement a number of
SWIG directives and are provided to make SWIG more compatible with C99 code.
</p>
<H2><a name="Preprocessor_delimiters">10.7 Preprocessing and delimiters</a></H2>
<H2><a name="Preprocessor_delimiters">11.7 Preprocessing and delimiters</a></H2>
<p>
The preprocessor handles { }, " " and %{ %} delimiters differently.
</p>
<H3><a name="Preprocessor_nn8">10.7.1 Preprocessing and %{ ... %} &amp; " ... " delimiters</a></H3>
<H3><a name="Preprocessor_nn8">11.7.1 Preprocessing and %{ ... %} &amp; " ... " delimiters</a></H3>
<p>
@ -340,7 +354,7 @@ the contents of the <tt>%{ ... %}</tt> block are copied without
modification to the output (including all preprocessor directives).
</p>
<H3><a name="Preprocessor_nn9">10.7.2 Preprocessing and { ... } delimiters</a></H3>
<H3><a name="Preprocessor_nn9">11.7.2 Preprocessing and { ... } delimiters</a></H3>
<p>
@ -382,7 +396,7 @@ to actually go into the wrapper file, prefix the preprocessor directives with <t
SWIG will strip the extra <tt>%</tt> and leave the preprocessor directive in the code.
</p>
<H2><a name="Preprocessor_typemap_delimiters">10.8 Preprocessor and Typemaps</a></H2>
<H2><a name="Preprocessor_typemap_delimiters">11.8 Preprocessor and Typemaps</a></H2>
<p>
@ -453,7 +467,7 @@ would generate
</div>
<H2><a name="Preprocessor_nn10">10.9 Viewing preprocessor output</a></H2>
<H2><a name="Preprocessor_nn10">11.9 Viewing preprocessor output</a></H2>
<p>
@ -463,7 +477,7 @@ Instead the results after the preprocessor has run are displayed.
This might be useful as an aid to debugging and viewing the results of macro expansions.
</p>
<H2><a name="Preprocessor_warning_error">10.10 The #error and #warning directives</a></H2>
<H2><a name="Preprocessor_warning_error">11.10 The #error and #warning directives</a></H2>
<p>

227
Doc/Manual/Python.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Python">32 SWIG and Python</a></H1>
<H1><a name="Python">33 SWIG and Python</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -168,7 +168,7 @@ very least, make sure you read the "<a href="SWIG.html#SWIG">SWIG
Basics</a>" chapter.
</p>
<H2><a name="Python_nn2">32.1 Overview</a></H2>
<H2><a name="Python_nn2">33.1 Overview</a></H2>
<p>
@ -195,10 +195,10 @@ described followed by a discussion of low-level implementation
details.
</p>
<H2><a name="Python_nn3">32.2 Preliminaries</a></H2>
<H2><a name="Python_nn3">33.2 Preliminaries</a></H2>
<H3><a name="Python_nn4">32.2.1 Running SWIG</a></H3>
<H3><a name="Python_nn4">33.2.1 Running SWIG</a></H3>
<p>
@ -295,7 +295,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">32.2.2 Using distutils</a></H3>
<H3><a name="Python_nn6">33.2.2 Using distutils</a></H3>
<p>
@ -387,7 +387,7 @@ This same approach works on all platforms if the appropriate compiler is install
can even build extensions to the standard Windows Python using MingGW)
</p>
<H3><a name="Python_nn7">32.2.3 Hand compiling a dynamic module</a></H3>
<H3><a name="Python_nn7">33.2.3 Hand compiling a dynamic module</a></H3>
<p>
@ -435,7 +435,7 @@ module actually consists of two files; <tt>socket.py</tt> and
</p>
<H3><a name="Python_nn8">32.2.4 Static linking</a></H3>
<H3><a name="Python_nn8">33.2.4 Static linking</a></H3>
<p>
@ -514,7 +514,7 @@ If using static linking, you might want to rely on a different approach
(perhaps using distutils).
</p>
<H3><a name="Python_nn9">32.2.5 Using your module</a></H3>
<H3><a name="Python_nn9">33.2.5 Using your module</a></H3>
<p>
@ -671,7 +671,7 @@ system configuration (this requires root access and you will need to
read the man pages).
</p>
<H3><a name="Python_nn10">32.2.6 Compilation of C++ extensions</a></H3>
<H3><a name="Python_nn10">33.2.6 Compilation of C++ extensions</a></H3>
<p>
@ -763,7 +763,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">32.2.7 Compiling for 64-bit platforms</a></H3>
<H3><a name="Python_nn11">33.2.7 Compiling for 64-bit platforms</a></H3>
<p>
@ -800,7 +800,7 @@ and -m64 allow you to choose the desired binary format for your Python
extension.
</p>
<H3><a name="Python_nn12">32.2.8 Building Python extensions under Windows</a></H3>
<H3><a name="Python_nn12">33.2.8 Building Python extensions under Windows</a></H3>
<p>
@ -930,7 +930,7 @@ SWIG Wiki</a>.
</p>
<H3><a name="Python_commandline">32.2.9 Additional Python commandline options</a></H3>
<H3><a name="Python_commandline">33.2.9 Additional Python commandline options</a></H3>
<p>
@ -974,7 +974,7 @@ swig -python -help
Many of these options are covered later on and their use should become clearer by the time you have finished reading this section on SWIG and Python.
</p>
<H2><a name="Python_nn13">32.3 A tour of basic C/C++ wrapping</a></H2>
<H2><a name="Python_nn13">33.3 A tour of basic C/C++ wrapping</a></H2>
<p>
@ -983,7 +983,7 @@ to your C/C++ code. Functions are wrapped as functions, classes are wrapped as
This section briefly covers the essential aspects of this wrapping.
</p>
<H3><a name="Python_nn14">32.3.1 Modules</a></H3>
<H3><a name="Python_nn14">33.3.1 Modules</a></H3>
<p>
@ -996,7 +996,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">32.3.2 Functions</a></H3>
<H3><a name="Python_nn15">33.3.2 Functions</a></H3>
<p>
@ -1020,7 +1020,7 @@ like you think it does:
&gt;&gt;&gt;
</pre></div>
<H3><a name="Python_nn16">32.3.3 Global variables</a></H3>
<H3><a name="Python_nn16">33.3.3 Global variables</a></H3>
<p>
@ -1158,7 +1158,7 @@ that starts with a leading underscore. SWIG does not create <tt>cvar</tt>
if there are no global variables in a module.
</p>
<H3><a name="Python_nn17">32.3.4 Constants and enums</a></H3>
<H3><a name="Python_nn17">33.3.4 Constants and enums</a></H3>
<p>
@ -1198,7 +1198,7 @@ other object. Unfortunately, there is no easy way for SWIG to
generate code that prevents this. You will just have to be careful.
</p>
<H3><a name="Python_nn18">32.3.5 Pointers</a></H3>
<H3><a name="Python_nn18">33.3.5 Pointers</a></H3>
<p>
@ -1339,7 +1339,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return
<tt>None</tt> if the conversion can't be performed.
</p>
<H3><a name="Python_nn19">32.3.6 Structures</a></H3>
<H3><a name="Python_nn19">33.3.6 Structures</a></H3>
<p>
@ -1549,7 +1549,7 @@ memory and use of it results in a segfault or some sort of other undefined behav
</p>
<H3><a name="Python_nn20">32.3.7 C++ classes</a></H3>
<H3><a name="Python_nn20">33.3.7 C++ classes</a></H3>
<p>
@ -1608,7 +1608,7 @@ public:
</div>
<p>
In Python, the static member can be access in three different ways:
In Python, the static member can be accessed in three different ways:
</p>
<div class="targetlang">
@ -1616,7 +1616,7 @@ In Python, the static member can be access in three different ways:
&gt;&gt;&gt; example.Spam_foo() # Spam::foo()
&gt;&gt;&gt; s = example.Spam()
&gt;&gt;&gt; s.foo() # Spam::foo() via an instance
&gt;&gt;&gt; example.Spam.foo() # Spam::foo(). Python-2.2 only
&gt;&gt;&gt; example.Spam.foo() # Spam::foo() using Python-2.2 and later
</pre>
</div>
@ -1627,17 +1627,32 @@ last technique is only available in Python-2.2 and later versions.
<p>
Static member variables are currently accessed as global variables. This means,
they are accessed through <tt>cvar</tt> like this:
they are accessed through <tt>cvar</tt> or via an instance property:
</p>
<div class="targetlang">
<pre>
&gt;&gt;&gt; print example.cvar.Spam_bar
&gt;&gt;&gt; example.cvar.Spam_bar # Spam::bar
7
&gt;&gt;&gt; s = example.Spam()
&gt;&gt;&gt; s.bar # Spam::bar via an instance property
7
</pre>
</div>
<H3><a name="Python_nn21">32.3.8 C++ inheritance</a></H3>
<p>
The <tt>-builtin</tt> option uses a metaclass to additionally provide access as follows:
</p>
<div class="targetlang">
<pre>
&gt;&gt;&gt; example.Spam.bar # Spam::bar using -builtin option only
7
</pre>
</div>
<H3><a name="Python_nn21">33.3.8 C++ inheritance</a></H3>
<p>
@ -1692,7 +1707,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">32.3.9 Pointers, references, values, and arrays</a></H3>
<H3><a name="Python_nn22">33.3.9 Pointers, references, values, and arrays</a></H3>
<p>
@ -1753,7 +1768,7 @@ treated as a returning value, and it will follow the same
allocation/deallocation process.
</p>
<H3><a name="Python_nn23">32.3.10 C++ overloaded functions</a></H3>
<H3><a name="Python_nn23">33.3.10 C++ overloaded functions</a></H3>
<p>
@ -1876,7 +1891,7 @@ first declaration takes precedence.
Please refer to the "SWIG and C++" chapter for more information about overloading.
</p>
<H3><a name="Python_nn24">32.3.11 C++ operators</a></H3>
<H3><a name="Python_nn24">33.3.11 C++ operators</a></H3>
<p>
@ -1973,7 +1988,7 @@ instead of raising an exception when the comparison fails, that is, on any kind
This follows the guidelines in <a href="https://www.python.org/dev/peps/pep-0207/">PEP 207 - Rich Comparisons</a> and <a href="https://docs.python.org/3/library/constants.html#NotImplemented">NotImplemented Python constant</a>.
</p>
<H3><a name="Python_nn25">32.3.12 C++ namespaces</a></H3>
<H3><a name="Python_nn25">33.3.12 C++ namespaces</a></H3>
<p>
@ -2040,7 +2055,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">32.3.13 C++ templates</a></H3>
<H3><a name="Python_nn26">33.3.13 C++ templates</a></H3>
<p>
@ -2094,10 +2109,10 @@ Some more complicated
examples will appear later.
</p>
<H3><a name="Python_nn27">32.3.14 C++ Smart Pointers</a></H3>
<H3><a name="Python_nn27">33.3.14 C++ Smart Pointers</a></H3>
<H4><a name="Python_smart_pointers_shared_ptr">32.3.14.1 The shared_ptr Smart Pointer</a></H4>
<H4><a name="Python_smart_pointers_shared_ptr">33.3.14.1 The shared_ptr Smart Pointer</a></H4>
<p>
@ -2108,7 +2123,7 @@ in the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a
</p>
<H4><a name="Python_smart_pointers_generic">32.3.14.2 Generic Smart Pointers</a></H4>
<H4><a name="Python_smart_pointers_generic">33.3.14.2 Generic Smart Pointers</a></H4>
<p>
@ -2192,7 +2207,7 @@ simply use the <tt>__deref__()</tt> method. For example:
</pre>
</div>
<H3><a name="Python_nn27a">32.3.15 C++ reference counted objects</a></H3>
<H3><a name="Python_nn27a">33.3.15 C++ reference counted objects</a></H3>
<p>
@ -2201,7 +2216,7 @@ Python examples of memory management using referencing counting.
</p>
<H2><a name="Python_nn28">32.4 Further details on the Python class interface</a></H2>
<H2><a name="Python_nn28">33.4 Further details on the Python class interface</a></H2>
<p>
@ -2224,7 +2239,7 @@ the <tt>-builtin</tt> option are in the <a href="#Python_builtin_types">Built-in
section.
</p>
<H3><a name="Python_nn29">32.4.1 Proxy classes</a></H3>
<H3><a name="Python_nn29">33.4.1 Proxy classes</a></H3>
<p>
@ -2313,7 +2328,7 @@ you can attach new Python methods to the class and you can even inherit from it
by Python built-in types until Python 2.2).
</p>
<H3><a name="Python_builtin_types">32.4.2 Built-in Types</a></H3>
<H3><a name="Python_builtin_types">33.4.2 Built-in Types</a></H3>
<p>
@ -2357,7 +2372,7 @@ please refer to the Python documentation:</p>
<p><a href="https://docs.python.org/3/extending/newtypes.html">https://docs.python.org/3/extending/newtypes.html</a></p>
<H4><a name="Python_builtin_limitations">32.4.2.1 Limitations</a></H4>
<H4><a name="Python_builtin_limitations">33.4.2.1 Limitations</a></H4>
<p>Use of the <tt>-builtin</tt> option implies a couple of limitations:
@ -2518,7 +2533,7 @@ assert(issubclass(B.Derived, A.Base))
</li>
</ul>
<H4><a name="Python_builtin_overloads">32.4.2.2 Operator overloads and slots -- use them!</a></H4>
<H4><a name="Python_builtin_overloads">33.4.2.2 Operator overloads and slots -- use them!</a></H4>
<p>The entire justification for the <tt>-builtin</tt> option is improved
@ -2568,7 +2583,7 @@ but <b>the line that uses the '+' operator is much faster</b>.
(<tt>operator==, operator&lt;</tt>, etc.) are also converted to Python
slot operators. For a complete list of C++ operators that are
automatically converted to Python slot operators, refer to the file
<tt>python/pyopers.swig</tt> in the SWIG library.
<tt>python/pyopers.swg</tt> in the SWIG library.
</p>
@ -2674,11 +2689,11 @@ the chosen closure function.
<p>
There is further information on <tt>%feature("python:slot")</tt>
in the file <tt>python/pyopers.swig</tt> in the SWIG library.
in the file <tt>python/pyopers.swg</tt> in the SWIG library.
</p>
<H3><a name="Python_nn30">32.4.3 Memory management</a></H3>
<H3><a name="Python_nn30">33.4.3 Memory management</a></H3>
<p>NOTE: Although this section refers to proxy objects, everything here also applies
@ -2873,7 +2888,7 @@ It is also possible to deal with situations like this using
typemaps--an advanced topic discussed later.
</p>
<H2><a name="Python_directors">32.5 Cross language polymorphism</a></H2>
<H2><a name="Python_directors">33.5 Cross language polymorphism</a></H2>
<p>
@ -2907,7 +2922,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">32.5.1 Enabling directors</a></H3>
<H3><a name="Python_nn33">33.5.1 Enabling directors</a></H3>
<p>
@ -2999,7 +3014,7 @@ class MyFoo(mymodule.Foo):
</div>
<H3><a name="Python_nn34">32.5.2 Director classes</a></H3>
<H3><a name="Python_nn34">33.5.2 Director classes</a></H3>
<p>
@ -3079,7 +3094,7 @@ so there is no need for the extra overhead involved with routing the
calls through Python.
</p>
<H3><a name="Python_nn35">32.5.3 Ownership and object destruction</a></H3>
<H3><a name="Python_nn35">33.5.3 Ownership and object destruction</a></H3>
<p>
@ -3146,7 +3161,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">32.5.4 Exception unrolling</a></H3>
<H3><a name="Python_nn36">33.5.4 Exception unrolling</a></H3>
<p>
@ -3205,7 +3220,7 @@ Swig::DirectorMethodException is thrown, Python will register the
exception as soon as the C wrapper function returns.
</p>
<H3><a name="Python_nn37">32.5.5 Overhead and code bloat</a></H3>
<H3><a name="Python_nn37">33.5.5 Overhead and code bloat</a></H3>
<p>
@ -3239,7 +3254,7 @@ directive) for only those methods that are likely to be extended in
Python.
</p>
<H3><a name="Python_nn38">32.5.6 Typemaps</a></H3>
<H3><a name="Python_nn38">33.5.6 Typemaps</a></H3>
<p>
@ -3253,7 +3268,7 @@ need to be supported.
</p>
<H3><a name="Python_nn39">32.5.7 Miscellaneous</a></H3>
<H3><a name="Python_nn39">33.5.7 Miscellaneous</a></H3>
<p>
@ -3300,7 +3315,7 @@ methods that return const references.
</p>
<H2><a name="Python_nn40">32.6 Common customization features</a></H2>
<H2><a name="Python_nn40">33.6 Common customization features</a></H2>
<p>
@ -3313,7 +3328,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">32.6.1 C/C++ helper functions</a></H3>
<H3><a name="Python_nn41">33.6.1 C/C++ helper functions</a></H3>
<p>
@ -3394,7 +3409,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">32.6.2 Adding additional Python code</a></H3>
<H3><a name="Python_nn42">33.6.2 Adding additional Python code</a></H3>
<p>
@ -3650,7 +3665,7 @@ The same applies for overloaded constructors.
</p>
<H3><a name="Python_nn43">32.6.3 Class extension with %extend</a></H3>
<H3><a name="Python_nn43">33.6.3 Class extension with %extend</a></H3>
<p>
@ -3739,7 +3754,7 @@ Vector(12, 14, 16)
in any way---the extensions only show up in the Python interface.
</p>
<H3><a name="Python_nn44">32.6.4 Exception handling with %exception</a></H3>
<H3><a name="Python_nn44">33.6.4 Exception handling with %exception</a></H3>
<p>
@ -3873,10 +3888,10 @@ 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>
<H3><a name="Python_optimization">32.6.5 Optimization options</a></H3>
<H3><a name="Python_optimization">33.6.5 Optimization options</a></H3>
<H4><a name="Python_fastproxy">32.6.5.1 -fastproxy</a></H4>
<H4><a name="Python_fastproxy">33.6.5.1 -fastproxy</a></H4>
<p>
@ -4009,7 +4024,7 @@ While this possibly provides the best of both worlds, the time to import the mod
The command line options mentioned above also apply to wrapped C/C++ global functions, not just class methods.
</p>
<H2><a name="Python_nn45">32.7 Tips and techniques</a></H2>
<H2><a name="Python_nn45">33.7 Tips and techniques</a></H2>
<p>
@ -4019,7 +4034,7 @@ strings, binary data, and arrays. This chapter discusses the common techniques
solving these problems.
</p>
<H3><a name="Python_nn46">32.7.1 Input and output parameters</a></H3>
<H3><a name="Python_nn46">33.7.1 Input and output parameters</a></H3>
<p>
@ -4232,7 +4247,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">32.7.2 Simple pointers</a></H3>
<H3><a name="Python_nn47">33.7.2 Simple pointers</a></H3>
<p>
@ -4301,7 +4316,7 @@ If you replace <tt>%pointer_functions()</tt> by <tt>%pointer_class(type, name)</
See the <a href="Library.html#Library">SWIG Library</a> chapter for further details.
</p>
<H3><a name="Python_nn48">32.7.3 Unbounded C Arrays</a></H3>
<H3><a name="Python_nn48">33.7.3 Unbounded C Arrays</a></H3>
<p>
@ -4363,7 +4378,7 @@ well suited for applications in which you need to create buffers,
package binary data, etc.
</p>
<H3><a name="Python_nn49">32.7.4 String handling</a></H3>
<H3><a name="Python_nn49">33.7.4 String handling</a></H3>
<p>
@ -4433,7 +4448,7 @@ also be used to extra binary data from arbitrary pointers.
</p>
<H3><a name="Python_default_args">32.7.5 Default arguments</a></H3>
<H3><a name="Python_default_args">33.7.5 Default arguments</a></H3>
<p>
@ -4532,7 +4547,7 @@ Versions of SWIG prior to this varied in their ability to convert C++ default va
equivalent Python default argument values.
</p>
<H2><a name="Python_nn53">32.8 Typemaps</a></H2>
<H2><a name="Python_nn53">33.8 Typemaps</a></H2>
<p>
@ -4549,7 +4564,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">32.8.1 What is a typemap?</a></H3>
<H3><a name="Python_nn54">33.8.1 What is a typemap?</a></H3>
<p>
@ -4665,7 +4680,7 @@ parameter is omitted):
</pre>
</div>
<H3><a name="Python_nn55">32.8.2 Python typemaps</a></H3>
<H3><a name="Python_nn55">33.8.2 Python typemaps</a></H3>
<p>
@ -4706,7 +4721,7 @@ a look at the SWIG library version 1.3.20 or so.
</p>
<H3><a name="Python_nn56">32.8.3 Typemap variables</a></H3>
<H3><a name="Python_nn56">33.8.3 Typemap variables</a></H3>
<p>
@ -4777,7 +4792,7 @@ properly assigned.
The Python name of the wrapper function being created.
</div>
<H3><a name="Python_nn57">32.8.4 Useful Python Functions</a></H3>
<H3><a name="Python_nn57">33.8.4 Useful Python Functions</a></H3>
<p>
@ -4905,7 +4920,7 @@ write me
</pre>
</div>
<H2><a name="Python_nn58">32.9 Typemap Examples</a></H2>
<H2><a name="Python_nn58">33.9 Typemap Examples</a></H2>
<p>
@ -4914,7 +4929,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">32.9.1 Converting Python list to a char ** </a></H3>
<H3><a name="Python_nn59">33.9.1 Converting Python list to a char ** </a></H3>
<p>
@ -4994,7 +5009,7 @@ memory allocation is used to allocate memory for the array, the
the C function.
</p>
<H3><a name="Python_nn60">32.9.2 Expanding a Python object into multiple arguments</a></H3>
<H3><a name="Python_nn60">33.9.2 Expanding a Python object into multiple arguments</a></H3>
<p>
@ -5113,7 +5128,7 @@ TypeError: Wrong number or type of arguments for overloaded function 'foo'.
</pre>
</div>
<H3><a name="Python_nn61">32.9.3 Using typemaps to return arguments</a></H3>
<H3><a name="Python_nn61">33.9.3 Using typemaps to return arguments</a></H3>
<p>
@ -5201,7 +5216,7 @@ function can now be used as follows:
&gt;&gt;&gt;
</pre></div>
<H3><a name="Python_nn62">32.9.4 Mapping Python tuples into small arrays</a></H3>
<H3><a name="Python_nn62">33.9.4 Mapping Python tuples into small arrays</a></H3>
<p>
@ -5250,7 +5265,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">32.9.5 Mapping sequences to C arrays</a></H3>
<H3><a name="Python_nn63">33.9.5 Mapping sequences to C arrays</a></H3>
<p>
@ -5339,7 +5354,7 @@ static int convert_darray(PyObject *input, double *ptr, int size) {
</pre>
</div>
<H3><a name="Python_nn64">32.9.6 Pointer handling</a></H3>
<H3><a name="Python_nn64">33.9.6 Pointer handling</a></H3>
<p>
@ -5436,7 +5451,7 @@ that has a <tt>this</tt> attribute. In addition,
class object (if applicable).
</p>
<H3><a name="Python_memory_management_member_variables">32.9.7 Memory management when returning references to member variables</a></H3>
<H3><a name="Python_memory_management_member_variables">33.9.7 Memory management when returning references to member variables</a></H3>
<p>
@ -5597,7 +5612,7 @@ static PyObject *bike_reference() {
<H2><a name="Python_nn65">32.10 Docstring Features</a></H2>
<H2><a name="Python_nn65">33.10 Docstring Features</a></H2>
<p>
@ -5625,7 +5640,7 @@ of your users much simpler.
</p>
<H3><a name="Python_nn66">32.10.1 Module docstring</a></H3>
<H3><a name="Python_nn66">33.10.1 Module docstring</a></H3>
<p>
@ -5659,7 +5674,7 @@ layout of controls on a panel, etc. to be loaded from an XML file."
</div>
<H3><a name="Python_nn67">32.10.2 %feature("autodoc")</a></H3>
<H3><a name="Python_nn67">33.10.2 %feature("autodoc")</a></H3>
<p>
@ -5687,7 +5702,7 @@ four levels for autodoc controlled by the value given to the
feature, <tt>%feature("autodoc", "<i>level</i>")</tt>.
The four values for <i>level</i> are covered in the following sub-sections.
<H4><a name="Python_nn68">32.10.2.1 %feature("autodoc", "0")</a></H4>
<H4><a name="Python_nn68">33.10.2.1 %feature("autodoc", "0")</a></H4>
<p>
@ -5716,7 +5731,7 @@ def function_name(*args, **kwargs):
</div>
<H4><a name="Python_nn69">32.10.2.2 %feature("autodoc", "1")</a></H4>
<H4><a name="Python_nn69">33.10.2.2 %feature("autodoc", "1")</a></H4>
<p>
@ -5741,7 +5756,7 @@ def function_name(*args, **kwargs):
</div>
<H4><a name="Python_autodoc2">32.10.2.3 %feature("autodoc", "2")</a></H4>
<H4><a name="Python_autodoc2">33.10.2.3 %feature("autodoc", "2")</a></H4>
<p>
@ -5803,7 +5818,7 @@ def function_name(*args, **kwargs):
</pre>
</div>
<H4><a name="Python_autodoc3">32.10.2.4 %feature("autodoc", "3")</a></H4>
<H4><a name="Python_autodoc3">33.10.2.4 %feature("autodoc", "3")</a></H4>
<p>
@ -5829,7 +5844,7 @@ def function_name(*args, **kwargs):
</div>
<H4><a name="Python_nn70">32.10.2.5 %feature("autodoc", "docstring")</a></H4>
<H4><a name="Python_nn70">33.10.2.5 %feature("autodoc", "docstring")</a></H4>
<p>
@ -5848,7 +5863,7 @@ void GetPosition(int* OUTPUT, int* OUTPUT);
</div>
<H3><a name="Python_nn71">32.10.3 %feature("docstring")</a></H3>
<H3><a name="Python_nn71">33.10.3 %feature("docstring")</a></H3>
<p>
@ -5880,7 +5895,7 @@ with more than one line.
</pre>
</div>
<H2><a name="Python_nn72">32.11 Python Packages</a></H2>
<H2><a name="Python_nn72">33.11 Python Packages</a></H2>
<p>Python has concepts of modules and packages. Modules are separate units of
@ -5954,7 +5969,7 @@ users may need to use special features such as the <tt>package</tt> option in th
<tt>%module</tt> directive or import related command line options. These are
explained in the following sections.</p>
<H3><a name="Python_modulepackage">32.11.1 Setting the Python package</a></H3>
<H3><a name="Python_modulepackage">33.11.1 Setting the Python package</a></H3>
<p>
@ -6008,7 +6023,7 @@ pkg1/pkg2/_foo.so # (shared library built from C/C++ code generated by SWI
</pre>
</div>
<H3><a name="Python_absrelimports">32.11.2 Absolute and relative imports</a></H3>
<H3><a name="Python_absrelimports">33.11.2 Absolute and relative imports</a></H3>
<p>Suppose, we have the following hierarchy of files:</p>
@ -6145,7 +6160,7 @@ uses relative imports. Second case is, when one puts import directives in
<tt>__init__.py</tt> to import symbols from submodules or subpackages and the
submodule depends on other submodules (discussed later).</p>
<H3><a name="Python_absimport">32.11.3 Enforcing absolute import semantics</a></H3>
<H3><a name="Python_absimport">33.11.3 Enforcing absolute import semantics</a></H3>
<p>As you may know, there is an incompatibility in import semantics (for the
@ -6182,7 +6197,7 @@ from __future__ import absolute_import
</pre>
</div>
<H3><a name="Python_importfrominit">32.11.4 Importing from __init__.py</a></H3>
<H3><a name="Python_importfrominit">33.11.4 Importing from __init__.py</a></H3>
<p>Imports in <tt>__init__.py</tt> are handy when you want to populate a
@ -6292,7 +6307,7 @@ class Bar(pkg3.foo.Foo): pass
effect (note, that the Python 2 case also needs the <tt>-relativeimport</tt>
workaround).</p>
<H3><a name="Python_implicit_namespace_packages">32.11.5 Implicit namespace packages</a></H3>
<H3><a name="Python_implicit_namespace_packages">33.11.5 Implicit namespace packages</a></H3>
<p> Python 3.3 introduced
@ -6370,7 +6385,7 @@ zipimporter requires python-3.5.1 or newer to work with subpackages.
</p>
<H3><a name="Python_package_search">32.11.6 Location of modules</a></H3>
<H3><a name="Python_package_search">33.11.6 Location of modules</a></H3>
<p>
@ -6406,7 +6421,7 @@ The following sub-sections look more closely at the two default configurations a
An input interface file, foo.i, results in the two modules foo.py and _foo.so for each of the configurations.
</p>
<H4><a name="Python_package_search_both_package_modules">32.11.6.1 Both modules in the same package</a></H4>
<H4><a name="Python_package_search_both_package_modules">33.11.6.1 Both modules in the same package</a></H4>
<p>
@ -6441,7 +6456,7 @@ from mypackage import foo
</div>
<H4><a name="Python_package_search_both_global_modules">32.11.6.2 Both modules are global</a></H4>
<H4><a name="Python_package_search_both_global_modules">33.11.6.2 Both modules are global</a></H4>
<p>
@ -6473,7 +6488,7 @@ import foo
</pre>
</div>
<H4><a name="Python_package_search_wrapper_split">32.11.6.3 Split modules custom configuration</a></H4>
<H4><a name="Python_package_search_wrapper_split">33.11.6.3 Split modules custom configuration</a></H4>
<p>In this non-standard 'split module' configuration, the pure Python module is in a package and the low level C/C++ module is global.
@ -6523,7 +6538,7 @@ Using one of the two default configurations is the recommended approach now.
</p>
<H4><a name="Python_custom_module_import">32.11.6.4 More on customizing the module import code</a></H4>
<H4><a name="Python_custom_module_import">33.11.6.4 More on customizing the module import code</a></H4>
<p>
@ -6643,7 +6658,7 @@ The following will do this for the <a href="#Python_package_search_wrapper_split
</pre>
</div>
<H4><a name="Python_package_search_static">32.11.6.5 Statically linked C modules</a></H4>
<H4><a name="Python_package_search_static">33.11.6.5 Statically linked C modules</a></H4>
<p>It is strongly recommended to use dynamically linked modules for the C
@ -6715,7 +6730,7 @@ module then you will either need to refer to the Python documentation on how
to do this (remember you are now the Python importer) or use dynamic linking.
</p>
<H2><a name="Python_python3support">32.12 Python 3 Support</a></H2>
<H2><a name="Python_python3support">33.12 Python 3 Support</a></H2>
<p>
@ -6740,7 +6755,7 @@ The following are Python 3 new features that are currently supported by
SWIG.
</p>
<H3><a name="Python_nn74">32.12.1 Function annotation</a></H3>
<H3><a name="Python_nn74">33.12.1 Function annotation</a></H3>
<p>
@ -6773,7 +6788,7 @@ For detailed usage of function annotation, see
<a href="https://www.python.org/dev/peps/pep-3107/">PEP 3107</a>.
</p>
<H3><a name="Python_nn75">32.12.2 Buffer interface</a></H3>
<H3><a name="Python_nn75">33.12.2 Buffer interface</a></H3>
<p>
@ -6925,7 +6940,7 @@ modify the buffer.
</div>
<H3><a name="Python_nn76">32.12.3 Abstract base classes</a></H3>
<H3><a name="Python_nn76">33.12.3 Abstract base classes</a></H3>
<p>
@ -6975,7 +6990,7 @@ The <tt>collections.abc</tt> module was introduced in Python 3.3 and hence this
requires Python 3.3 or later.
</p>
<H3><a name="Python_nn77">32.12.4 Byte string output conversion</a></H3>
<H3><a name="Python_nn77">33.12.4 Byte string output conversion</a></H3>
<p>
@ -7156,7 +7171,7 @@ overloads taking both std::string (as Python bytes) and std::wstring
(as Python unicode).
</p>
<H3><a name="Python_2_unicode">32.12.5 Python 2 Unicode</a></H3>
<H3><a name="Python_2_unicode">33.12.5 Python 2 Unicode</a></H3>
<p>
@ -7228,7 +7243,7 @@ the first is allowing unicode conversion and the second is explicitly
prohibiting it.
</p>
<H2><a name="Python_multithreaded">32.13 Support for Multithreaded Applications</a></H2>
<H2><a name="Python_multithreaded">33.13 Support for Multithreaded Applications</a></H2>
<p>By default, SWIG does not enable support for multithreaded Python applications. More
@ -7243,7 +7258,7 @@ will not be able to run any other threads, even if the wrapped C/C++ code is wai
interface for this is described in the next section.
</p>
<H3><a name="Python_thread_UI">32.13.1 UI for Enabling Multithreading Support</a></H3>
<H3><a name="Python_thread_UI">33.13.1 UI for Enabling Multithreading Support</a></H3>
<p>The user interface is as follows:</p>
@ -7286,7 +7301,7 @@ will not be able to run any other threads, even if the wrapped C/C++ code is wai
</li>
</ol>
<H3><a name="Python_thread_performance">32.13.2 Multithread Performance</a></H3>
<H3><a name="Python_thread_performance">33.13.2 Multithread Performance</a></H3>
<p>

156
Doc/Manual/R.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="R">33 SWIG and R</a></H1>
<H1><a name="R">34 SWIG and R</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -17,6 +17,9 @@
<li><a href="#R_nn5">General policy</a>
<li><a href="#R_language_conventions">Language conventions</a>
<li><a href="#R_nn6">C++ classes</a>
<ul>
<li><a href="#R_class_examples">Examples</a>
</ul>
<li><a href="#R_nn7">Enumerations</a>
</ul>
</div>
@ -33,10 +36,14 @@ href="http://www.r-project.org/">www.r-project.org</a>.
<p>
The R bindings are under active development. They have been used to
compile and run an R interface to QuantLib running on Mandriva Linux
with gcc. The R bindings also work on Microsoft Windows using Visual C++.
with gcc. They are also used to create the SimpleITK R package, which
runs on Linux and MacOS. SWIG is used to create all wrapper
interfaces
to <a href="http://http://www.simpleitk.org/">SimpleITK</a>. The R
bindings also work on Microsoft Windows using Visual C++.
</p>
<H2><a name="R_nn2">33.1 Bugs</a></H2>
<H2><a name="R_nn2">34.1 Bugs</a></H2>
<p>
@ -44,11 +51,13 @@ Currently the following features are not implemented or broken:
</p>
<ul>
<li>Garbage collection of created objects
<li>Garbage collection of some created objects. Finalizers are
available for wrapped C++ classes and are called by the
garbage collection system.
<li>C Array wrappings
</ul>
<H2><a name="R_nn3">33.2 Using R and SWIG</a></H2>
<H2><a name="R_nn3">34.2 Using R and SWIG</a></H2>
<p>
@ -138,7 +147,7 @@ Error in .Call("R_swig_fact", s_arg1, as.logical(.copy), PACKAGE = "example") :
<li>Make sure the architecture of the shared library(x64 for instance), matches the architecture of the R program you want to load your shared library into
</ul>
<H2><a name="R_nn4">33.3 Precompiling large R files</a></H2>
<H2><a name="R_nn4">34.3 Precompiling large R files</a></H2>
<p>
@ -158,9 +167,12 @@ This will generate a compiled R file called BigFile.RData that
will save a large amount of loading time.
</p>
<p>
There is no need to precompile large R files if the SWIG-generated code is being included
in an R package. The package infrastructure provides this service during package installation.
</p>
<H2><a name="R_nn5">33.4 General policy</a></H2>
<H2><a name="R_nn5">34.4 General policy</a></H2>
<p>
@ -169,28 +181,136 @@ wrapping over the underlying functions and rely on the R type system
to provide R syntax.
</p>
<H2><a name="R_language_conventions">33.5 Language conventions</a></H2>
<H2><a name="R_language_conventions">34.5 Language conventions</a></H2>
<p>
getitem and setitem use C++ conventions (i.e. zero based indices). [<-
getitem and setitem use C++ conventions (i.e. zero based indices). [&lt;-
and [ are overloaded to allow for R syntax (one based indices and
slices)
</p>
<H2><a name="R_nn6">33.6 C++ classes</a></H2>
<H2><a name="R_nn6">34.6 C++ classes</a></H2>
<p>
C++ objects are implemented as external pointer objects with the class
being the mangled name of the class. The C++ classes are encapsulated
as an SEXP with an external pointer type. The class is the mangled
name of the class. The nice thing about R is that is allows you to
keep track of the pointer object which removes the necessity for a lot
of the proxy class baggage you see in other languages.
Wrapping of C++ classes for R works quite well. R has a special
type, known as an external reference, that can be used as a pointer
to arbitrary things, including C++ classes. The proxy layers generated
for other classes are not required.
</p>
<H2><a name="R_nn7">33.7 Enumerations</a></H2>
<p>
SWIG currently creates a custom hierarchy of R classes derived from the
external reference type and implements
type checking and function overloading in the R code it generates. In
the future we hope to utilise the built in R6 class structures.
</p>
<p>
The R interface has the following capabilities:
</p>
<ul>
<li> Destructor methods are registered and called automatically by the R garbage collector.
<li> A range of std::vector types are converted automatically to R equivalents via the std_vector.i library.
<li> The $ operator is used for method access.
<li> Variable accessors are automatically generated and called via the $, [, [[, $&lt;-, [&lt;-, [[&lt;- operators.
</ul>
<H3><a name="R_class_examples">34.6.1 Examples</a></H3>
<p>
Consider the following simple example:
</p>
<div class="code">
<pre>
class Vehicle {
private:
int m_axles;
public:
int Axles() {
return(m_axles);
}
bool Available;
Vehicle() {
Available=false;
m_axles=2;
}
Vehicle(int ax) {
Available=false;
m_axles=ax;
}
};
</pre>
</div>
<p>
The following options are available in R:
</p>
<div class="code">
<pre>
v1 &lt;- Vehicle()
v2 &lt;- Vehicle(4)
# access members
v1$Axles()
[1] 2
v2$Axles
[1] 4
v1$Available
[1] FALSE
# Set availability
v1$Available &lt;- TRUE
v1$Available
[1] TRUE
</pre>
</div>
<p>
A useful trick to determine the methods that are available is to
query the R method definition as follows:
</p>
<div class="code">
<pre>
# display the methods for the class
getMethod("$", class(v1))
Method Definition:
function (x, name)
{
accessorFuns = list(Axles = Vehicle_Axles, Available = Vehicle_Available_get)
vaccessors = c("Available")
idx = pmatch(name, names(accessorFuns))
if (is.na(idx))
return(callNextMethod(x, name))
f = accessorFuns[[idx]]
if (is.na(match(name, vaccessors)))
function(...) {
f(x, ...)
}
else f(x)
}
Signatures:
x
target "_p_Vehicle"
defined "_p_Vehicle"
</pre>
</div>
<p>
The names in the <tt>accessorFuns</tt> list correspond to class methods while names in the <tt>vaccessors</tt> section
correspond to variables that may be modified.
</p>
<H2><a name="R_nn7">34.7 Enumerations</a></H2>
<p>

218
Doc/Manual/Ruby.html
View file

@ -8,7 +8,7 @@
<body bgcolor="#ffffff">
<H1><a name="Ruby">34 SWIG and Ruby</a></H1>
<H1><a name="Ruby">35 SWIG and Ruby</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -149,7 +149,7 @@
<p>This chapter describes SWIG's support of Ruby.</p>
<H2><a name="Ruby_nn2">34.1 Preliminaries</a></H2>
<H2><a name="Ruby_nn2">35.1 Preliminaries</a></H2>
<p> SWIG 4.0 is known to work with Ruby versions 1.9 and later.
@ -164,7 +164,7 @@ read the "<a href="SWIG.html#SWIG">SWIG Basics</a>"
chapter. It is also assumed that the reader has a basic understanding
of Ruby. </p>
<H3><a name="Ruby_nn3">34.1.1 Running SWIG</a></H3>
<H3><a name="Ruby_nn3">35.1.1 Running SWIG</a></H3>
<p> To build a Ruby module, run SWIG using the <tt>-ruby</tt>
@ -188,7 +188,7 @@ if compiling a C++ extension) that contains all of the code needed to
build a Ruby extension module. To finish building the module, you need
to compile this file and link it with the rest of your program. </p>
<H3><a name="Ruby_nn4">34.1.2 Getting the right header files</a></H3>
<H3><a name="Ruby_nn4">35.1.2 Getting the right header files</a></H3>
<p> In order to compile the wrapper code, the compiler needs the <tt>ruby.h</tt>
@ -202,7 +202,7 @@ the compiler options needed to compile the code is to ask Ruby itself:</p>
</pre>
</div>
<H3><a name="Ruby_nn5">34.1.3 Compiling a dynamic module</a></H3>
<H3><a name="Ruby_nn5">35.1.3 Compiling a dynamic module</a></H3>
<p> Ruby extension modules are typically compiled into shared
@ -275,7 +275,7 @@ manual pages for your compiler and linker to determine the correct set
of options. You might also check the <a href="https://github.com/swig/swig/wiki">SWIG Wiki</a>
for additional information. </p>
<H3><a name="Ruby_nn6">34.1.4 Using your module</a></H3>
<H3><a name="Ruby_nn6">35.1.4 Using your module</a></H3>
<p> Ruby <i>module</i> names must be capitalized,
@ -305,7 +305,7 @@ begins with: </p>
<p> will result in an extension module using the feature name
"example" and Ruby module name "Example". </p>
<H3><a name="Ruby_nn7">34.1.5 Static linking</a></H3>
<H3><a name="Ruby_nn7">35.1.5 Static linking</a></H3>
<p> An alternative approach to dynamic linking is to rebuild the
@ -320,7 +320,7 @@ finding the Ruby source, adding an entry to the <tt>ext/Setup</tt>
file, adding your directory to the list of extensions in the file, and
finally rebuilding Ruby. </p>
<H3><a name="Ruby_nn8">34.1.6 Compilation of C++ extensions</a></H3>
<H3><a name="Ruby_nn8">35.1.6 Compilation of C++ extensions</a></H3>
<p> On most machines, C++ extension modules should be linked
@ -352,7 +352,7 @@ $libs = append_library($libs, "supc++")
create_makefile('example')</pre>
</div>
<H2><a name="Ruby_nn9">34.2 Building Ruby Extensions under Windows 95/NT</a></H2>
<H2><a name="Ruby_nn9">35.2 Building Ruby Extensions under Windows 95/NT</a></H2>
<p> Building a SWIG extension to Ruby under Windows 95/NT is
@ -377,7 +377,7 @@ order to build extensions, you may need to download the source
distribution to the Ruby package, as you will need the Ruby header
files. </p>
<H3><a name="Ruby_nn10">34.2.1 Running SWIG from Developer Studio</a></H3>
<H3><a name="Ruby_nn10">35.2.1 Running SWIG from Developer Studio</a></H3>
<p> If you are developing your application within Microsoft
@ -441,13 +441,13 @@ Foo = 3.0
</pre>
</div>
<H2><a name="Ruby_nn11">34.3 The Ruby-to-C/C++ Mapping</a></H2>
<H2><a name="Ruby_nn11">35.3 The Ruby-to-C/C++ Mapping</a></H2>
<p> This section describes the basics of how SWIG maps C or C++
declarations in your SWIG interface files to Ruby constructs. </p>
<H3><a name="Ruby_nn12">34.3.1 Modules</a></H3>
<H3><a name="Ruby_nn12">35.3.1 Modules</a></H3>
<p> The SWIG <tt>%module</tt> directive specifies
@ -519,7 +519,7 @@ option to wrap everything into the global module, take care that the
names of your constants, classes and methods don't conflict with any of
Ruby's built-in names. </p>
<H3><a name="Ruby_nn13">34.3.2 Functions</a></H3>
<H3><a name="Ruby_nn13">35.3.2 Functions</a></H3>
<p> Global functions are wrapped as Ruby module methods. For
@ -553,7 +553,7 @@ irb(main):002:0&gt; <b>Example.fact(4)</b>
24</pre>
</div>
<H3><a name="Ruby_nn14">34.3.3 Variable Linking</a></H3>
<H3><a name="Ruby_nn14">35.3.3 Variable Linking</a></H3>
<p> C/C++ global variables are wrapped as a pair of singleton
@ -615,7 +615,25 @@ directive. For example: </p>
effect until it is explicitly disabled using <tt>%mutable</tt>.
</p>
<H3><a name="Ruby_nn15">34.3.4 Constants</a></H3>
<p>Note: When SWIG is invoked with the <tt>-globalmodule</tt> option in
effect, the C/C++ global variables will be translated into Ruby global
variables. Type-checking and the optional read-only characteristic are
available in the same way as described above. However the example would
then have to be modified and executed in the following way:
<div class="code targetlang">
<pre>$ <b>irb</b>
irb(main):001:0&gt; <b>require 'Example'</b>
true
irb(main):002:0&gt; <b>$variable1 = 2</b>
2
irb(main):003:0&gt; <b>$Variable2 = 4 * 10.3</b>
41.2
irb(main):004:0&gt; <b>$Variable2</b>
41.2</pre>
</div>
<H3><a name="Ruby_nn15">35.3.4 Constants</a></H3>
<p> C/C++ constants are wrapped as module constants initialized
@ -643,7 +661,7 @@ irb(main):002:0&gt; <b>Example::PI</b>
3.14159</pre>
</div>
<H3><a name="Ruby_nn16">34.3.5 Pointers</a></H3>
<H3><a name="Ruby_nn16">35.3.5 Pointers</a></H3>
<p> "Opaque" pointers to arbitrary C/C++ types (i.e. types that
@ -667,7 +685,7 @@ returns an instance of an internally generated Ruby class: </p>
<p> A <tt>NULL</tt> pointer is always represented by
the Ruby <tt>nil</tt> object. </p>
<H3><a name="Ruby_nn17">34.3.6 Structures</a></H3>
<H3><a name="Ruby_nn17">35.3.6 Structures</a></H3>
<p> C/C++ structs are wrapped as Ruby classes, with accessor
@ -772,7 +790,7 @@ void Bar_f_set(Bar *b, Foo *val) {
}</pre>
</div>
<H3><a name="Ruby_nn18">34.3.7 C++ classes</a></H3>
<H3><a name="Ruby_nn18">35.3.7 C++ classes</a></H3>
<p> Like structs, C++ classes are wrapped by creating a new Ruby
@ -827,7 +845,7 @@ Ale
3</pre>
</div>
<H3><a name="Ruby_nn19">34.3.8 C++ Inheritance</a></H3>
<H3><a name="Ruby_nn19">35.3.8 C++ Inheritance</a></H3>
<p> The SWIG type-checker is fully aware of C++ inheritance.
@ -980,7 +998,7 @@ inherit from both <tt>Base1</tt> and <tt>Base2</tt>
(i.e. they exhibit <a href="http://c2.com/cgi/wiki?DuckTyping">"Duck
Typing"</a>). </p>
<H3><a name="Ruby_nn20">34.3.9 C++ Overloaded Functions</a></H3>
<H3><a name="Ruby_nn20">35.3.9 C++ Overloaded Functions</a></H3>
<p> C++ overloaded functions, methods, and constructors are
@ -1070,7 +1088,7 @@ arises--in this case, the first declaration takes precedence. </p>
<p>Please refer to the <a href="SWIGPlus.html#SWIGPlus">"SWIG
and C++"</a> chapter for more information about overloading. </p>
<H3><a name="Ruby_nn21">34.3.10 C++ Operators</a></H3>
<H3><a name="Ruby_nn21">35.3.10 C++ Operators</a></H3>
<p> For the most part, overloaded operators are handled
@ -1112,7 +1130,7 @@ c = Example.add_complex(a, b)</pre>
is discussed in the <a href="#Ruby_operator_overloading">section
on operator overloading</a>. </p>
<H3><a name="Ruby_nn22">34.3.11 C++ namespaces</a></H3>
<H3><a name="Ruby_nn22">35.3.11 C++ namespaces</a></H3>
<p> SWIG is aware of C++ namespaces, but namespace names do not
@ -1169,7 +1187,7 @@ and create extension modules for each namespace separately. If your
program utilizes thousands of small deeply nested namespaces each with
identical symbol names, well, then you get what you deserve. </p>
<H3><a name="Ruby_nn23">34.3.12 C++ templates</a></H3>
<H3><a name="Ruby_nn23">35.3.12 C++ templates</a></H3>
<p> C++ templates don't present a huge problem for SWIG. However,
@ -1211,7 +1229,7 @@ irb(main):004:0&gt; <b>p.second</b>
4</pre>
</div>
<H3><a name="Ruby_nn23_1">34.3.13 C++ Standard Template Library (STL)</a></H3>
<H3><a name="Ruby_nn23_1">35.3.13 C++ Standard Template Library (STL)</a></H3>
<p> On a related note, the standard SWIG library contains a
@ -1304,7 +1322,7 @@ puts v
shown in these examples. More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a>
chapter.</p>
<H3><a name="Ruby_C_STL_Functors">34.3.14 C++ STL Functors</a></H3>
<H3><a name="Ruby_C_STL_Functors">35.3.14 C++ STL Functors</a></H3>
<p>Some containers in the STL allow you to modify their default
@ -1365,7 +1383,7 @@ b
</pre>
</div>
<H3><a name="Ruby_C_Iterators">34.3.15 C++ STL Iterators</a></H3>
<H3><a name="Ruby_C_Iterators">35.3.15 C++ STL Iterators</a></H3>
<p>The STL is well known for the use of iterators. There
@ -1448,10 +1466,10 @@ i
<p>If you'd rather have STL classes without any iterators, you should define <tt>-DSWIG_NO_EXPORT_ITERATOR_METHODS</tt> when running swig.</p>
<H3><a name="Ruby_nn24">34.3.16 C++ Smart Pointers</a></H3>
<H3><a name="Ruby_nn24">35.3.16 C++ Smart Pointers</a></H3>
<H4><a name="Ruby_smart_pointers_shared_ptr">34.3.16.1 The shared_ptr Smart Pointer</a></H4>
<H4><a name="Ruby_smart_pointers_shared_ptr">35.3.16.1 The shared_ptr Smart Pointer</a></H4>
<p>
@ -1462,7 +1480,7 @@ in the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a
</p>
<H4><a name="Ruby_smart_pointers_generic">34.3.16.2 Generic Smart Pointers</a></H4>
<H4><a name="Ruby_smart_pointers_generic">35.3.16.2 Generic Smart Pointers</a></H4>
<p> In certain C++ programs, it is common to use classes that
@ -1527,7 +1545,7 @@ method. For example: </p>
<pre>irb(main):004:0&gt; <b>f = p.__deref__()</b> # Returns underlying Foo *</pre>
</div>
<H3><a name="Ruby_nn25">34.3.17 Cross-Language Polymorphism</a></H3>
<H3><a name="Ruby_nn25">35.3.17 Cross-Language Polymorphism</a></H3>
<p> SWIG's Ruby module supports cross-language polymorphism
@ -1536,7 +1554,7 @@ module. Rather than duplicate the information presented in the <a href="Python.h
section just notes the differences that you need to be aware of when
using this feature with Ruby. </p>
<H4><a name="Ruby_nn26">34.3.17.1 Exception Unrolling</a></H4>
<H4><a name="Ruby_nn26">35.3.17.1 Exception Unrolling</a></H4>
<p> Whenever a C++ director class routes one of its virtual
@ -1559,7 +1577,7 @@ method is "wrapped" using the <tt>rb_rescue2()</tt>
function from Ruby's C API. If any Ruby exception is raised, it will be
caught here and a C++ exception is raised in its place. </p>
<H2><a name="Ruby_nn27">34.4 Naming</a></H2>
<H2><a name="Ruby_nn27">35.4 Naming</a></H2>
<p>Ruby has several common naming conventions. Constants are
@ -1597,7 +1615,7 @@ generated
by SWIG, it is turned off by default in SWIG 1.3.28. However, it is
planned to become the default option in future releases.</p>
<H3><a name="Ruby_nn28">34.4.1 Defining Aliases</a></H3>
<H3><a name="Ruby_nn28">35.4.1 Defining Aliases</a></H3>
<p> It's a fairly common practice in the Ruby built-ins and
@ -1667,7 +1685,7 @@ matching rules used for other kinds of features apply (see the chapter
on <a href="Customization.html#Customization">"Customization
Features"</a>) for more details).</p>
<H3><a name="Ruby_nn29">34.4.2 Predicate Methods</a></H3>
<H3><a name="Ruby_nn29">35.4.2 Predicate Methods</a></H3>
<p> Ruby methods that return a boolean value and end in a
@ -1716,7 +1734,7 @@ using SWIG's "features" mechanism and so the same name matching rules
used for other kinds of features apply (see the chapter on <a href="Customization.html#Customization">"Customization
Features"</a>) for more details). </p>
<H3><a name="Ruby_nn30">34.4.3 Bang Methods</a></H3>
<H3><a name="Ruby_nn30">35.4.3 Bang Methods</a></H3>
<p> Ruby methods that modify an object in-place and end in an
@ -1748,7 +1766,7 @@ using SWIG's "features" mechanism and so the same name matching rules
used for other kinds of features apply (see the chapter on <a href="Customization.html#Customization">"Customization
Features"</a>) for more details). </p>
<H3><a name="Ruby_nn31">34.4.4 Getters and Setters</a></H3>
<H3><a name="Ruby_nn31">35.4.4 Getters and Setters</a></H3>
<p> Often times a C++ library will expose properties through
@ -1783,7 +1801,7 @@ irb(main):003:0&gt; <b>puts foo.value</b></pre>
%rename("value=") Foo::setValue(int value);</pre>
</div>
<H2><a name="Ruby_nn32">34.5 Input and output parameters</a></H2>
<H2><a name="Ruby_nn32">35.5 Input and output parameters</a></H2>
<p> A common problem in some C programs is handling parameters
@ -1922,10 +1940,10 @@ void get_dimensions(Matrix *m, int *rows, int*columns);</pre>
<pre>r, c = Example.get_dimensions(m)</pre>
</div>
<H2><a name="Ruby_nn33">34.6 Exception handling </a></H2>
<H2><a name="Ruby_nn33">35.6 Exception handling </a></H2>
<H3><a name="Ruby_nn34">34.6.1 Using the %exception directive </a></H3>
<H3><a name="Ruby_nn34">35.6.1 Using the %exception directive </a></H3>
<p>The SWIG <tt>%exception</tt> directive can be
@ -2034,7 +2052,7 @@ methods and functions named <tt>getitem</tt> and <tt>setitem</tt>.
limited to C++ exception handling. See the chapter on <a href="Customization.html#Customization">Customization
Features</a> for more examples.</p>
<H3><a name="Ruby_nn34_2">34.6.2 Handling Ruby Blocks </a></H3>
<H3><a name="Ruby_nn34_2">35.6.2 Handling Ruby Blocks </a></H3>
<p>One of the highlights of Ruby and most of its standard library
@ -2101,7 +2119,7 @@ a special in typemap, like:</p>
<p>For more information on typemaps, see <a href="#Ruby_nn37">Typemaps</a>.</p>
<H3><a name="Ruby_nn35">34.6.3 Raising exceptions </a></H3>
<H3><a name="Ruby_nn35">35.6.3 Raising exceptions </a></H3>
<p>There are three ways to raise exceptions from C++ code to
@ -2258,7 +2276,7 @@ function. The first argument passed to <tt>rb_raise()</tt>
is the exception type. You can raise a custom exception type or one of
the built-in Ruby exception types.</p>
<H3><a name="Ruby_nn36">34.6.4 Exception classes </a></H3>
<H3><a name="Ruby_nn36">35.6.4 Exception classes </a></H3>
<p>Starting with SWIG 1.3.28, the Ruby module supports the <tt>%exceptionclass</tt>
@ -2295,7 +2313,7 @@ end </pre>
<p>For another example look at swig/Examples/ruby/exception_class.
</p>
<H2><a name="Ruby_nn37">34.7 Typemaps</a></H2>
<H2><a name="Ruby_nn37">35.7 Typemaps</a></H2>
<p> This section describes how you can modify SWIG's default
@ -2310,7 +2328,7 @@ a required part of using SWIG---the default wrapping behavior is enough
in most cases. Typemaps are only used if you want to change some aspect
of the primitive C-Ruby interface.</p>
<H3><a name="Ruby_nn38">34.7.1 What is a typemap?</a></H3>
<H3><a name="Ruby_nn38">35.7.1 What is a typemap?</a></H3>
<p> A typemap is nothing more than a code generation rule that is
@ -2467,7 +2485,7 @@ to be used as follows (notice how the length parameter is omitted): </p>
2</pre>
</div>
<H3><a name="Ruby_Typemap_scope">34.7.2 Typemap scope</a></H3>
<H3><a name="Ruby_Typemap_scope">35.7.2 Typemap scope</a></H3>
<p> Once defined, a typemap remains in effect for all of the
@ -2513,7 +2531,7 @@ where the class itself is defined. For example:</p>
};</pre>
</div>
<H3><a name="Ruby_Copying_a_typemap">34.7.3 Copying a typemap</a></H3>
<H3><a name="Ruby_Copying_a_typemap">35.7.3 Copying a typemap</a></H3>
<p> A typemap is copied by using assignment. For example:</p>
@ -2555,7 +2573,7 @@ rules as for <tt>
%apply (char *buf, int len) { (char *buffer, int size) }; // Multiple arguments</pre>
</div>
<H3><a name="Ruby_Deleting_a_typemap">34.7.4 Deleting a typemap</a></H3>
<H3><a name="Ruby_Deleting_a_typemap">35.7.4 Deleting a typemap</a></H3>
<p> A typemap can be deleted by simply defining no code. For
@ -2580,7 +2598,7 @@ defined by typemaps, clearing a fundamental type like <tt>int</tt>
will make that type unusable unless you also define a new set of
typemaps immediately after the clear operation.</p>
<H3><a name="Ruby_Placement_of_typemaps">34.7.5 Placement of typemaps</a></H3>
<H3><a name="Ruby_Placement_of_typemaps">35.7.5 Placement of typemaps</a></H3>
<p> Typemap declarations can be declared in the global scope,
@ -2651,13 +2669,13 @@ In this example, this is done using the class declaration <tt>class
string</tt>
.</p>
<H3><a name="Ruby_nn39">34.7.6 Ruby typemaps</a></H3>
<H3><a name="Ruby_nn39">35.7.6 Ruby typemaps</a></H3>
<p>The following list details all of the typemap methods that
can be used by the Ruby module: </p>
<H4><a name="Ruby_in_typemap">34.7.6.1 "in" typemap</a></H4>
<H4><a name="Ruby_in_typemap">35.7.6.1 "in" typemap</a></H4>
<p>Converts Ruby objects to input
@ -2724,7 +2742,7 @@ arguments to be specified. For example:</p>
<p> At this time, only zero or one arguments may be converted.</p>
<H4><a name="Ruby_typecheck_typemap">34.7.6.2 "typecheck" typemap</a></H4>
<H4><a name="Ruby_typecheck_typemap">35.7.6.2 "typecheck" typemap</a></H4>
<p> The "typecheck" typemap is used to support overloaded
@ -2746,7 +2764,7 @@ program uses overloaded methods, you should also define a collection of
"typecheck" typemaps. More details about this follow in a later section
on "Typemaps and Overloading."</p>
<H4><a name="Ruby_out_typemap">34.7.6.3 "out" typemap</a></H4>
<H4><a name="Ruby_out_typemap">35.7.6.3 "out" typemap</a></H4>
<p>Converts return value of a C function
@ -2797,7 +2815,7 @@ version of the C datatype matched by the typemap.</td>
</table>
</div>
<H4><a name="Ruby_arginit_typemap">34.7.6.4 "arginit" typemap</a></H4>
<H4><a name="Ruby_arginit_typemap">35.7.6.4 "arginit" typemap</a></H4>
<p> The "arginit" typemap is used to set the initial value of a
@ -2812,7 +2830,7 @@ applications. For example:</p>
}</pre>
</div>
<H4><a name="Ruby_default_typemap">34.7.6.5 "default" typemap</a></H4>
<H4><a name="Ruby_default_typemap">35.7.6.5 "default" typemap</a></H4>
<p> The "default" typemap is used to turn an argument into a
@ -2837,7 +2855,7 @@ arguments that follow must have default values. See the <a href="SWIG.html#SWIG_
Default/optional arguments</a> section for further information on
default argument wrapping.</p>
<H4><a name="Ruby_check_typemap">34.7.6.6 "check" typemap</a></H4>
<H4><a name="Ruby_check_typemap">35.7.6.6 "check" typemap</a></H4>
<p> The "check" typemap is used to supply value checking code
@ -2852,7 +2870,7 @@ arguments have been converted. For example:</p>
}</pre>
</div>
<H4><a name="Ruby_argout_typemap_">34.7.6.7 "argout" typemap</a></H4>
<H4><a name="Ruby_argout_typemap_">35.7.6.7 "argout" typemap</a></H4>
<p> The "argout" typemap is used to return values from arguments.
@ -2906,7 +2924,7 @@ some function like SWIG_Ruby_AppendOutput.</p>
<p> See the <tt>typemaps.i</tt> library for examples.</p>
<H4><a name="Ruby_freearg_typemap_">34.7.6.8 "freearg" typemap</a></H4>
<H4><a name="Ruby_freearg_typemap_">35.7.6.8 "freearg" typemap</a></H4>
<p> The "freearg" typemap is used to cleanup argument data. It is
@ -2933,7 +2951,7 @@ This code is also placed into a special variable <tt>$cleanup</tt>
that may be used in other typemaps whenever a wrapper function needs to
abort prematurely.</p>
<H4><a name="Ruby_newfree_typemap">34.7.6.9 "newfree" typemap</a></H4>
<H4><a name="Ruby_newfree_typemap">35.7.6.9 "newfree" typemap</a></H4>
<p> The "newfree" typemap is used in conjunction with the <tt>%newobject</tt>
@ -2957,7 +2975,7 @@ string *foo();</pre>
<p> See <a href="Customization.html#Customization_ownership">Object
ownership and %newobject</a> for further details.</p>
<H4><a name="Ruby_memberin_typemap">34.7.6.10 "memberin" typemap</a></H4>
<H4><a name="Ruby_memberin_typemap">35.7.6.10 "memberin" typemap</a></H4>
<p> The "memberin" typemap is used to copy data from<em> an
@ -2975,21 +2993,21 @@ example:</p>
already provides a default implementation for arrays, strings, and
other objects.</p>
<H4><a name="Ruby_varin_typemap">34.7.6.11 "varin" typemap</a></H4>
<H4><a name="Ruby_varin_typemap">35.7.6.11 "varin" typemap</a></H4>
<p> The "varin" typemap is used to convert objects in the target
language to C for the purposes of assigning to a C/C++ global variable.
This is implementation specific.</p>
<H4><a name="Ruby_varout_typemap_">34.7.6.12 "varout" typemap</a></H4>
<H4><a name="Ruby_varout_typemap_">35.7.6.12 "varout" typemap</a></H4>
<p> The "varout" typemap is used to convert a C/C++ object to an
object in the target language when reading a C/C++ global variable.
This is implementation specific.</p>
<H4><a name="Ruby_throws_typemap">34.7.6.13 "throws" typemap</a></H4>
<H4><a name="Ruby_throws_typemap">35.7.6.13 "throws" typemap</a></H4>
<p> The "throws" typemap is only used when SWIG parses a C++
@ -3030,7 +3048,7 @@ specification yet they do throw exceptions, SWIG cannot know how to
deal with them. For a neat way to handle these, see the <a href="Customization.html#Customization_exception">Exception
handling with %exception</a> section.</p>
<H4><a name="Ruby_directorin_typemap">34.7.6.14 directorin typemap</a></H4>
<H4><a name="Ruby_directorin_typemap">35.7.6.14 directorin typemap</a></H4>
<p>Converts C++ objects in director
@ -3089,7 +3107,7 @@ referring to the class itself.</td>
</table>
</div>
<H4><a name="Ruby_directorout_typemap">34.7.6.15 directorout typemap</a></H4>
<H4><a name="Ruby_directorout_typemap">35.7.6.15 directorout typemap</a></H4>
<p>Converts Ruby objects in director
@ -3162,7 +3180,7 @@ exception.
</p>
<H4><a name="Ruby_directorargout_typemap">34.7.6.16 directorargout typemap</a></H4>
<H4><a name="Ruby_directorargout_typemap">35.7.6.16 directorargout typemap</a></H4>
<p>Output argument processing in director
@ -3220,19 +3238,19 @@ referring to the instance of the class itself</td>
</table>
</div>
<H4><a name="Ruby_ret_typemap">34.7.6.17 ret typemap</a></H4>
<H4><a name="Ruby_ret_typemap">35.7.6.17 ret typemap</a></H4>
<p>Cleanup of function return values
</p>
<H4><a name="Ruby_globalin_typemap">34.7.6.18 globalin typemap</a></H4>
<H4><a name="Ruby_globalin_typemap">35.7.6.18 globalin typemap</a></H4>
<p>Setting of C global variables
</p>
<H3><a name="Ruby_nn40">34.7.7 Typemap variables</a></H3>
<H3><a name="Ruby_nn40">35.7.7 Typemap variables</a></H3>
<p>
@ -3282,7 +3300,7 @@ so that their values can be properly assigned. </div>
<div class="indent">The Ruby name of the wrapper function
being created. </div>
<H3><a name="Ruby_nn41">34.7.8 Useful Functions</a></H3>
<H3><a name="Ruby_nn41">35.7.8 Useful Functions</a></H3>
<p> When you write a typemap, you usually have to work directly
@ -3297,7 +3315,7 @@ stick to the swig functions instead of the native Ruby functions.
That should help you avoid having to rewrite a lot of typemaps
across multiple languages.</p>
<H4><a name="Ruby_nn42">34.7.8.1 C Datatypes to Ruby Objects</a></H4>
<H4><a name="Ruby_nn42">35.7.8.1 C Datatypes to Ruby Objects</a></H4>
<div class="diagram">
@ -3339,7 +3357,7 @@ SWIG_From_float(float)</td>
</table>
</div>
<H4><a name="Ruby_nn43">34.7.8.2 Ruby Objects to C Datatypes</a></H4>
<H4><a name="Ruby_nn43">35.7.8.2 Ruby Objects to C Datatypes</a></H4>
<p>Here, while the Ruby versions return the value directly, the SWIG
@ -3407,7 +3425,7 @@ versions do not, but return a status value to indicate success (<tt>SWIG_OK</tt>
</table>
</div>
<H4><a name="Ruby_nn44">34.7.8.3 Macros for VALUE</a></H4>
<H4><a name="Ruby_nn44">35.7.8.3 Macros for VALUE</a></H4>
<p> <tt>RSTRING_LEN(str)</tt> </p>
@ -3430,7 +3448,7 @@ versions do not, but return a status value to indicate success (<tt>SWIG_OK</tt>
<div class="indent">pointer to array storage</div>
<H4><a name="Ruby_nn45">34.7.8.4 Exceptions</a></H4>
<H4><a name="Ruby_nn45">35.7.8.4 Exceptions</a></H4>
<p> <tt>void rb_raise(VALUE exception, const char *fmt,
@ -3509,7 +3527,7 @@ message to standard error if Ruby was invoked with the <tt>-w</tt>
flag. The given format string <i>fmt</i> and remaining
arguments are interpreted as with <tt>printf()</tt>. </div>
<H4><a name="Ruby_nn46">34.7.8.5 Iterators</a></H4>
<H4><a name="Ruby_nn46">35.7.8.5 Iterators</a></H4>
<p> <tt>void rb_iter_break()</tt> </p>
@ -3555,14 +3573,14 @@ VALUE), VALUE value)</tt></p>
<div class="indent"> Equivalent to Ruby's <tt>throw</tt>.
</div>
<H3><a name="Ruby_nn47">34.7.9 Typemap Examples</a></H3>
<H3><a name="Ruby_nn47">35.7.9 Typemap Examples</a></H3>
<p> This section includes a few examples of typemaps. For more
examples, you might look at the examples in the <tt>Example/ruby</tt>
directory. </p>
<H3><a name="Ruby_nn48">34.7.10 Converting a Ruby array to a char **</a></H3>
<H3><a name="Ruby_nn48">35.7.10 Converting a Ruby array to a char **</a></H3>
<p> A common problem in many C programs is the processing of
@ -3627,7 +3645,7 @@ array. Since dynamic memory allocation is used to allocate memory for
the array, the "freearg" typemap is used to later release this memory
after the execution of the C function. </p>
<H3><a name="Ruby_nn49">34.7.11 Collecting arguments in a hash</a></H3>
<H3><a name="Ruby_nn49">35.7.11 Collecting arguments in a hash</a></H3>
<p> Ruby's solution to the "keyword arguments" capability of some
@ -3841,7 +3859,7 @@ memory leak. Fortunately, this typemap is a lot easier to write: </p>
program that uses the extension, can be found in the <tt>Examples/ruby/hashargs</tt>
directory of the SWIG distribution. </p>
<H3><a name="Ruby_nn50">34.7.12 Pointer handling</a></H3>
<H3><a name="Ruby_nn50">35.7.12 Pointer handling</a></H3>
<p> Occasionally, it might be necessary to convert pointer values
@ -3900,7 +3918,7 @@ For example: </p>
}</pre>
</div>
<H4><a name="Ruby_nn51">34.7.12.1 Ruby Datatype Wrapping</a></H4>
<H4><a name="Ruby_nn51">35.7.12.1 Ruby Datatype Wrapping</a></H4>
<p> <tt>VALUE Data_Wrap_Struct(VALUE class, void
@ -3927,7 +3945,7 @@ as above. </div>
type <i>c-type</i> from the data object <i>obj</i>
and assigns that pointer to <i>ptr</i>. </div>
<H3><a name="Ruby_nn52">34.7.13 Example: STL Vector to Ruby Array</a></H3>
<H3><a name="Ruby_nn52">35.7.13 Example: STL Vector to Ruby Array</a></H3>
<p>Another use for macros and type maps is to create a Ruby array
@ -4019,7 +4037,7 @@ STL with ruby, you are advised to use the standard swig STL library,
which does much more than this. Refer to the section called
the<a href="#Ruby_nn23_1"> C++ Standard Template Library</a>.
<H2><a name="Ruby_nn65">34.8 Docstring Features</a></H2>
<H2><a name="Ruby_nn65">35.8 Docstring Features</a></H2>
<p>
@ -4053,7 +4071,7 @@ generate ri documentation from a c wrap file, you could do:</p>
$ rdoc -r file_wrap.c
</pre></div>
<H3><a name="Ruby_nn66">34.8.1 Module docstring</a></H3>
<H3><a name="Ruby_nn66">35.8.1 Module docstring</a></H3>
<p>
@ -4083,7 +4101,7 @@ layout of controls on a panel, etc. to be loaded from an XML file."
%module(docstring=DOCSTRING) xrc</pre>
</div>
<H3><a name="Ruby_nn67">34.8.2 %feature("autodoc")</a></H3>
<H3><a name="Ruby_nn67">35.8.2 %feature("autodoc")</a></H3>
<p>Since SWIG does know everything about the function it wraps,
@ -4104,7 +4122,7 @@ several options for autodoc controlled by the value given to the
feature, described below.
</p>
<H4><a name="Ruby_nn68">34.8.2.1 %feature("autodoc", "0")</a></H4>
<H4><a name="Ruby_nn68">35.8.2.1 %feature("autodoc", "0")</a></H4>
<p>
@ -4128,7 +4146,7 @@ Then Ruby code like this will be generated:
...</pre>
</div>
<H4><a name="Ruby_autodoc1">34.8.2.2 %feature("autodoc", "1")</a></H4>
<H4><a name="Ruby_autodoc1">35.8.2.2 %feature("autodoc", "1")</a></H4>
<p>
@ -4148,7 +4166,7 @@ this:
...</pre>
</div>
<H4><a name="Ruby_autodoc2">34.8.2.3 %feature("autodoc", "2")</a></H4>
<H4><a name="Ruby_autodoc2">35.8.2.3 %feature("autodoc", "2")</a></H4>
<p>
@ -4160,7 +4178,7 @@ parameter types with the "2" option will result in Ruby code like
this:
</p>
<H4><a name="Ruby_feature_autodoc3">34.8.2.4 %feature("autodoc", "3")</a></H4>
<H4><a name="Ruby_feature_autodoc3">35.8.2.4 %feature("autodoc", "3")</a></H4>
<p>
@ -4181,7 +4199,7 @@ Parameters:
bar - Bar</pre>
</div>
<H4><a name="Ruby_nn70">34.8.2.5 %feature("autodoc", "docstring")</a></H4>
<H4><a name="Ruby_nn70">35.8.2.5 %feature("autodoc", "docstring")</a></H4>
<p>
@ -4197,7 +4215,7 @@ generated string. For example:
void GetPosition(int* OUTPUT, int* OUTPUT);</pre>
</div>
<H3><a name="Ruby_nn71">34.8.3 %feature("docstring")</a></H3>
<H3><a name="Ruby_nn71">35.8.3 %feature("docstring")</a></H3>
<p>
@ -4208,10 +4226,10 @@ docstring associated with classes, function or methods are output.
If an item already has an autodoc string then it is combined with the
docstring and they are output together. </p>
<H2><a name="Ruby_nn53">34.9 Advanced Topics</a></H2>
<H2><a name="Ruby_nn53">35.9 Advanced Topics</a></H2>
<H3><a name="Ruby_operator_overloading">34.9.1 Operator overloading</a></H3>
<H3><a name="Ruby_operator_overloading">35.9.1 Operator overloading</a></H3>
<p> SWIG allows operator overloading with, by using the <tt>%extend</tt>
@ -4392,7 +4410,7 @@ separate method for handling <i>inequality</i> since Ruby
parses the expression <i>a != b</i> as <i>!(a == b)</i>.
</p>
<H3><a name="Ruby_nn55">34.9.2 Creating Multi-Module Packages</a></H3>
<H3><a name="Ruby_nn55">35.9.2 Creating Multi-Module Packages</a></H3>
<p> The chapter on <a href="Modules.html#Modules">Working
@ -4518,7 +4536,7 @@ irb(main):005:0&gt; <b>c.getX()</b>
5.0</pre>
</div>
<H3><a name="Ruby_nn56">34.9.3 Specifying Mixin Modules</a></H3>
<H3><a name="Ruby_nn56">35.9.3 Specifying Mixin Modules</a></H3>
<p> The Ruby language doesn't support multiple inheritance, but
@ -4585,7 +4603,7 @@ matching rules used for other kinds of features apply (see the chapter
on <a href="Customization.html#Customization">"Customization
Features"</a>) for more details). </p>
<H2><a name="Ruby_nn57">34.10 Memory Management</a></H2>
<H2><a name="Ruby_nn57">35.10 Memory Management</a></H2>
<p>One of the most common issues in generating SWIG bindings for
@ -4608,7 +4626,7 @@ to C++ (or vice versa) depending on what function or methods are
invoked. Clearly, developing a SWIG wrapper requires a thorough
understanding of how the underlying library manages memory.</p>
<H3><a name="Ruby_nn58">34.10.1 Mark and Sweep Garbage Collector </a></H3>
<H3><a name="Ruby_nn58">35.10.1 Mark and Sweep Garbage Collector </a></H3>
<p>Ruby uses a mark and sweep garbage collector. When the garbage
@ -4639,7 +4657,7 @@ any memory has been allocated in creating the underlying C struct or
C++ struct, then a "free" function must be defined that deallocates
this memory. </p>
<H3><a name="Ruby_nn59">34.10.2 Object Ownership</a></H3>
<H3><a name="Ruby_nn59">35.10.2 Object Ownership</a></H3>
<p>As described above, memory management depends on clearly
@ -4784,7 +4802,7 @@ public:
<p> This code can be seen in swig/examples/ruby/tracking.</p>
<H3><a name="Ruby_nn60">34.10.3 Object Tracking</a></H3>
<H3><a name="Ruby_nn60">35.10.3 Object Tracking</a></H3>
<p>The remaining parts of this section will use the class library
@ -5010,7 +5028,7 @@ However, if you implement your own free functions (see below) you may
also have to call the <tt>SWIG_RubyRemoveTracking</tt> and <tt>RubyUnlinkObjects</tt>
methods.</p>
<H3><a name="Ruby_nn61">34.10.4 Mark Functions</a></H3>
<H3><a name="Ruby_nn61">35.10.4 Mark Functions</a></H3>
<p>With a bit more testing, we see that our class library still
@ -5139,7 +5157,7 @@ irb(main):016:0&gt;</pre>
<p>This code can be seen in swig/examples/ruby/mark_function.</p>
<H3><a name="Ruby_nn62">34.10.5 Free Functions</a></H3>
<H3><a name="Ruby_nn62">35.10.5 Free Functions</a></H3>
<p>By default, SWIG creates a "free" function that is called when
@ -5307,7 +5325,7 @@ been freed, and thus raises a runtime exception.</p>
<p>This code can be seen in swig/examples/ruby/free_function.</p>
<H3><a name="Ruby_nn63">34.10.6 Embedded Ruby and the C++ Stack</a></H3>
<H3><a name="Ruby_nn63">35.10.6 Embedded Ruby and the C++ Stack</a></H3>
<p>As has been said, the Ruby GC runs and marks objects before

4
Doc/Manual/SWIG.html
View file

@ -127,7 +127,7 @@ Supported Target Language Options
-lua - Generate Lua wrappers
-octave - Generate Octave wrappers
-perl5 - Generate Perl 5 wrappers
-php7 - Generate PHP 7 wrappers
-php7 - Generate PHP 7 or later wrappers
-python - Generate Python wrappers
-r - Generate R (aka GNU S) wrappers
-ruby - Generate Ruby wrappers
@ -2020,7 +2020,7 @@ and a more descriptive one, but the two functions are otherwise equivalent:
<tr>
<td><span style="white-space: nowrap;"><tt>regex:/pattern/subst/</tt></span></td>
<td>String after (Perl-like) regex substitution operation. This function
allows to apply arbitrary regular expressions to the identifier names. The
allows applying arbitrary regular expressions to the identifier names. The
<i>pattern</i> part is a regular expression in Perl syntax (as supported
by the <a href="http://www.pcre.org/">Perl Compatible Regular Expressions (PCRE)</a>)
library and the <i>subst</i> string

5
Doc/Manual/SWIGPlus.html
View file

@ -91,6 +91,7 @@ For additions to the original C++ standard, please read the
<a href="CPlusPlus11.html#CPlusPlus11">SWIG and C++11</a>,
<a href="CPlusPlus14.html#CPlusPlus14">SWIG and C++14</a> and
<a href="CPlusPlus17.html#CPlusPlus17">SWIG and C++17</a> chapters.
<a href="CPlusPlus20.html#CPlusPlus20">SWIG and C++20</a> chapters.
As a prerequisite,
you should first read the chapter <a href="SWIG.html#SWIG">SWIG Basics</a> to see
how SWIG wraps ISO C. Support for C++ builds upon ISO C
@ -3631,7 +3632,7 @@ Alternatively, you could expand the constructor template in selected instantiati
// Create default and conversion constructors
%extend pair&lt;double, double&gt; {
%template(paird) pair&lt;double, dobule&gt;; // Default constructor
%template(paird) pair&lt;double, double&gt;; // Default constructor
%template(pairc) pair&lt;int, int&gt;; // Conversion constructor
};
</pre>
@ -3646,7 +3647,7 @@ instead:
<pre>
// Create default and conversion constructors
%extend pair&lt;double, double&gt; {
%template(pair) pair&lt;double, dobule&gt;; // Default constructor
%template(pair) pair&lt;double, double&gt;; // Default constructor
%template(pair) pair&lt;int, int&gt;; // Conversion constructor
};
</pre>

90
Doc/Manual/Scilab.html
View file

@ -9,7 +9,7 @@
<body bgcolor="#ffffff">
<H1><a name="Scilab">35 SWIG and Scilab</a></H1>
<H1><a name="Scilab">36 SWIG and Scilab</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -88,7 +88,7 @@ This chapter explains how to use SWIG for Scilab. After this introduction, you s
</p>
<H2><a name="Scilab_preliminaries">35.1 Preliminaries</a></H2>
<H2><a name="Scilab_preliminaries">36.1 Preliminaries</a></H2>
<p>
@ -105,7 +105,7 @@ SWIG for Scilab supports C language. C++ is partially supported. See <a href="#S
</p>
<H2><a name="Scilab_running_swig">35.2 Running SWIG</a></H2>
<H2><a name="Scilab_running_swig">36.2 Running SWIG</a></H2>
<p>
@ -139,7 +139,7 @@ Note: a code in an <tt>%inline</tt> section is both parsed and wrapped by SWIG,
</p>
<H3><a name="Scilab_running_swig_generating_module">35.2.1 Generating the module</a></H3>
<H3><a name="Scilab_running_swig_generating_module">36.2.1 Generating the module</a></H3>
<p>
@ -182,7 +182,7 @@ The <tt>swig</tt> executable has several other command line options you can use.
</p>
<H3><a name="Scilab_running_swig_building_module">35.2.2 Building the module</a></H3>
<H3><a name="Scilab_running_swig_building_module">36.2.2 Building the module</a></H3>
<p>
@ -202,7 +202,7 @@ $ gcc -shared example_wrap.o -o libexample.so
Note: we supposed in this example that the path to the Scilab include directory is <tt>/usr/local/include/scilab</tt> (which is the case in a Debian environment), this should be changed for another environment.
</p>
<H3><a name="Scilab_running_swig_loading_module">35.2.3 Loading the module</a></H3>
<H3><a name="Scilab_running_swig_loading_module">36.2.3 Loading the module</a></H3>
<p>
@ -226,7 +226,7 @@ Link done.
which means that Scilab has successfully loaded the shared library. The module functions and other symbols are now available in Scilab.
</p>
<H3><a name="Scilab_running_swig_using_module">35.2.4 Using the module</a></H3>
<H3><a name="Scilab_running_swig_using_module">36.2.4 Using the module</a></H3>
<p>
@ -260,7 +260,7 @@ ans =
Note: for conciseness, we assume in the subsequent Scilab code examples that the modules have been beforehand built and loaded in Scilab.
</p>
<H3><a name="Scilab_running_swig_options">35.2.5 Scilab command line options</a></H3>
<H3><a name="Scilab_running_swig_options">36.2.5 Scilab command line options</a></H3>
<p>
@ -320,10 +320,10 @@ $ swig -scilab -help
</pre></div>
<H2><a name="Scilab_wrapping">35.3 A basic tour of C/C++ wrapping</a></H2>
<H2><a name="Scilab_wrapping">36.3 A basic tour of C/C++ wrapping</a></H2>
<H3><a name="Scilab_wrapping_overview">35.3.1 Overview</a></H3>
<H3><a name="Scilab_wrapping_overview">36.3.1 Overview</a></H3>
<p>
@ -332,7 +332,7 @@ This means that functions, structs, classes, variables, etc... are interfaced th
There are a few exceptions, such as constants and enumerations, which can be wrapped directly as Scilab variables.
</p>
<H3><a name="Scilab_wrapping_identifiers">35.3.2 Identifiers</a></H3>
<H3><a name="Scilab_wrapping_identifiers">36.3.2 Identifiers</a></H3>
<p>
@ -347,7 +347,7 @@ In these cases, the <a href="SWIG.html#SWIG_rename_ignore">%rename directive</a>
Note: truncations can be disabled by specifying the target version 6 of Scilab in the <tt>targetversion</tt> argument (i.e. <tt>-targetversion 6</tt>).
</p>
<H3><a name="Scilab_wrapping_functions">35.3.3 Functions</a></H3>
<H3><a name="Scilab_wrapping_functions">36.3.3 Functions</a></H3>
<p>
@ -378,7 +378,7 @@ ans =
24.
</pre></div>
<H4><a name="Scilab_nn13">35.3.3.1 Argument passing</a></H4>
<H4><a name="Scilab_nn13">36.3.3.1 Argument passing</a></H4>
<p>
@ -431,7 +431,7 @@ In Scilab, parameters are passed by value. The output (and inout) parameters are
7.
</pre></div>
<H4><a name="Scilab_nn14">35.3.3.2 Multiple output arguments</a></H4>
<H4><a name="Scilab_nn14">36.3.3.2 Multiple output arguments</a></H4>
<p>
@ -480,7 +480,7 @@ int divide(int n, int d, int *OUTPUT, int *OUTPUT);
</pre></div>
<H3><a name="Scilab_wrapping_global_variables">35.3.4 Global variables</a></H3>
<H3><a name="Scilab_wrapping_global_variables">36.3.4 Global variables</a></H3>
<p>
@ -549,10 +549,10 @@ It works the same:</p>
</pre></div>
<H3><a name="Scilab_wrapping_constants_and_enums">35.3.5 Constants and enumerations</a></H3>
<H3><a name="Scilab_wrapping_constants_and_enums">36.3.5 Constants and enumerations</a></H3>
<H4><a name="Scilab_wrapping_constants">35.3.5.1 Constants</a></H4>
<H4><a name="Scilab_wrapping_constants">36.3.5.1 Constants</a></H4>
<p>
@ -693,7 +693,7 @@ are mapped to Scilab variables, with the same name:
3.14
</pre></div>
<H4><a name="Scilab_wrapping_enums">35.3.5.2 Enumerations</a></H4>
<H4><a name="Scilab_wrapping_enums">36.3.5.2 Enumerations</a></H4>
<p>
@ -758,7 +758,7 @@ typedef enum { RED, BLUE, GREEN } color;
</pre></div>
<H3><a name="Scilab_wrapping_pointers">35.3.6 Pointers</a></H3>
<H3><a name="Scilab_wrapping_pointers">36.3.6 Pointers</a></H3>
<p>
@ -820,7 +820,7 @@ Note: the type name <tt>_p_FILE</tt> which means "pointer to FILE".
The user of a pointer is responsible for freeing it or, like in the example, closing any resources associated with it (just as is required in a C program).
</p>
<H4><a name="Scilab_wrapping_pointers_utility_functions">35.3.6.1 Utility functions</a></H4>
<H4><a name="Scilab_wrapping_pointers_utility_functions">36.3.6.1 Utility functions</a></H4>
<p>
@ -861,7 +861,7 @@ ans =
</pre></div>
<H4><a name="Scilab_wrapping_pointers_null_pointers">35.3.6.2 Null pointers:</a></H4>
<H4><a name="Scilab_wrapping_pointers_null_pointers">36.3.6.2 Null pointers:</a></H4>
<p>
@ -877,7 +877,7 @@ Using the previous <tt>SWIG_this()</tt> and <tt>SWIG_ptr()</tt>, it is possible
</pre></div>
<H3><a name="Scilab_wrapping_structs">35.3.7 Structures</a></H3>
<H3><a name="Scilab_wrapping_structs">36.3.7 Structures</a></H3>
<p>
@ -986,7 +986,7 @@ Note: the pointer to the struct works as described in <a href="#Scilab_wrapping_
--&gt; delete_Bar(b);
</pre></div>
<H3><a name="Scilab_wrapping_cpp_classes">35.3.8 C++ classes</a></H3>
<H3><a name="Scilab_wrapping_cpp_classes">36.3.8 C++ classes</a></H3>
<p>
@ -1054,7 +1054,7 @@ Note: like structs, class pointers are mapped as described in <a href="#Scilab_w
--&gt; delete_Point(p);
</pre></div>
<H3><a name="Scilab_wrapping_cpp_inheritance">35.3.9 C++ inheritance</a></H3>
<H3><a name="Scilab_wrapping_cpp_inheritance">36.3.9 C++ inheritance</a></H3>
<p>
@ -1129,7 +1129,7 @@ But we can use either use the <tt>get_perimeter()</tt> function of the parent cl
18.84
</pre></div>
<H3><a name="Scilab_wrapping_cpp_overloading">35.3.10 C++ overloading</a></H3>
<H3><a name="Scilab_wrapping_cpp_overloading">36.3.10 C++ overloading</a></H3>
<p>
@ -1169,7 +1169,7 @@ void magnify(Circle *circle, double factor) {
</pre></div>
<H3><a name="Scilab_wrapping_pointers_references_values_arrays">35.3.11 Pointers, references, values, and arrays</a></H3>
<H3><a name="Scilab_wrapping_pointers_references_values_arrays">36.3.11 Pointers, references, values, and arrays</a></H3>
<p>
@ -1227,7 +1227,7 @@ All these functions will return a pointer to an instance of <tt>Foo</tt>.
As the function <tt>spam7</tt> returns a value, new instance of <tt>Foo</tt> has to be allocated, and a pointer on this instance is returned.
</p>
<H3><a name="Scilab_wrapping_cpp_templates">35.3.12 C++ templates</a></H3>
<H3><a name="Scilab_wrapping_cpp_templates">36.3.12 C++ templates</a></H3>
<p>
@ -1286,7 +1286,7 @@ Then in Scilab:
More details on template support can be found in the <a href="SWIGPlus.html#SWIGPlus_nn30">templates</a> documentation.
</p>
<H3><a name="Scilab_wrapping_cpp_operators">35.3.13 C++ operators</a></H3>
<H3><a name="Scilab_wrapping_cpp_operators">36.3.13 C++ operators</a></H3>
<p>
@ -1339,7 +1339,7 @@ private:
</pre></div>
<H3><a name="Scilab_wrapping_cpp_namespaces">35.3.14 C++ namespaces</a></H3>
<H3><a name="Scilab_wrapping_cpp_namespaces">36.3.14 C++ namespaces</a></H3>
<p>
@ -1417,7 +1417,7 @@ Note: the <a href="SWIGPlus.html#SWIGPlus_nspace">nspace</a> feature is not supp
</p>
<H3><a name="Scilab_wrapping_cpp_exceptions">35.3.15 C++ exceptions</a></H3>
<H3><a name="Scilab_wrapping_cpp_exceptions">36.3.15 C++ exceptions</a></H3>
<p>
@ -1500,17 +1500,17 @@ More complex or custom exception types require specific exception typemaps to be
See the <a href="SWIGPlus.html#SWIGPlus">SWIG C++ documentation</a> for more details.
</p>
<H3><a name="Scilab_wrapping_cpp_stl">35.3.16 C++ STL</a></H3>
<H3><a name="Scilab_wrapping_cpp_stl">36.3.16 C++ STL</a></H3>
<p>
The Standard Template Library (STL) is partially supported. See <a href="#Scilab_typemaps_stl">STL</a> for more details.
</p>
<H2><a name="Scilab_typemaps">35.4 Type mappings and libraries</a></H2>
<H2><a name="Scilab_typemaps">36.4 Type mappings and libraries</a></H2>
<H3><a name="Scilab_typemaps_primitive_types">35.4.1 Default primitive type mappings</a></H3>
<H3><a name="Scilab_typemaps_primitive_types">36.4.1 Default primitive type mappings</a></H3>
<p>
@ -1561,7 +1561,7 @@ The default behaviour is for SWIG to generate code that will give a runtime erro
<H3><a name="Scilab_typemaps_arrays">35.4.2 Arrays</a></H3>
<H3><a name="Scilab_typemaps_arrays">36.4.2 Arrays</a></H3>
<p>
@ -1616,7 +1616,7 @@ void printArray(int values[], int len) {
[ 0 1 2 3 ]
</pre></div>
<H3><a name="Scilab_typemaps_pointer-to-pointers">35.4.3 Pointer-to-pointers</a></H3>
<H3><a name="Scilab_typemaps_pointer-to-pointers">36.4.3 Pointer-to-pointers</a></H3>
<p>
@ -1689,7 +1689,7 @@ void print_matrix(double **M, int nbRows, int nbCols) {
</pre></div>
<H3><a name="Scilab_typemaps_matrices">35.4.4 Matrices</a></H3>
<H3><a name="Scilab_typemaps_matrices">36.4.4 Matrices</a></H3>
<p>
@ -1782,7 +1782,7 @@ The remarks made earlier for arrays also apply here:
<li>There is no control while converting <tt>double</tt> values to integers, <tt>double</tt> values are truncated without any checking or warning.</li>
</ul>
<H3><a name="Scilab_typemaps_stl">35.4.5 STL</a></H3>
<H3><a name="Scilab_typemaps_stl">36.4.5 STL</a></H3>
<p>
@ -1982,7 +1982,7 @@ ans =
--&gt; delete_PersonPtrSet(p);
</pre></div>
<H2><a name="Scilab_module_initialization">35.5 Module initialization</a></H2>
<H2><a name="Scilab_module_initialization">36.5 Module initialization</a></H2>
<p>
@ -2006,7 +2006,7 @@ For example, to initialize the module <tt>example</tt>:
--&gt; example_Init();
</pre></div>
<H2><a name="Scilab_building_modes">35.6 Building modes</a></H2>
<H2><a name="Scilab_building_modes">36.6 Building modes</a></H2>
<p>
@ -2021,7 +2021,7 @@ To produce a dynamic module, when generating the wrapper, there are two possibil
<li>the <tt>builder</tt> mode. In this mode, Scilab is responsible of building.
</ul>
<H3><a name="Scilab_building_modes_nobuilder_mode">35.6.1 No-builder mode</a></H3>
<H3><a name="Scilab_building_modes_nobuilder_mode">36.6.1 No-builder mode</a></H3>
<p>
@ -2034,7 +2034,7 @@ This mode is the best option to use when you have to integrate the module build
</p>
<H3><a name="Scilab_building_modes_builder_mode">35.6.2 Builder mode</a></H3>
<H3><a name="Scilab_building_modes_builder_mode">36.6.2 Builder mode</a></H3>
<p>
@ -2074,14 +2074,14 @@ The command is:
$ swig -scilab -builder -buildercflags -I/opt/foo/include -builderldflags "-L/opt/foo/lib -lfoo" -buildersources baa1.cxx, baa2.cxx example.i
</pre></div>
<H2><a name="Scilab_generated_scripts">35.7 Generated scripts</a></H2>
<H2><a name="Scilab_generated_scripts">36.7 Generated scripts</a></H2>
<p>
In this part we give some details about the generated Scilab scripts.
</p>
<H3><a name="Scilab_generated_scripts_builder_script">35.7.1 Builder script</a></H3>
<H3><a name="Scilab_generated_scripts_builder_script">36.7.1 Builder script</a></H3>
<p>
@ -2106,7 +2106,7 @@ ilib_build(ilib_name, table, files, libs);
<li><tt><b>table</b></tt>: two column string matrix containing a table of pairs of 'scilab function name', 'C function name'.</li>
</ul>
<H3><a name="Scilab_generated_scripts_loader_script">35.7.2 Loader script</a></H3>
<H3><a name="Scilab_generated_scripts_loader_script">36.7.2 Loader script</a></H3>
<p>
@ -2145,7 +2145,7 @@ clear get_file_path;
</ul>
<H2><a name="Scilab_other_resources">35.8 Other resources</a></H2>
<H2><a name="Scilab_other_resources">36.8 Other resources</a></H2>
<ul>

3
Doc/Manual/Sections.html
View file

@ -8,7 +8,7 @@
<H1><a name="Sections">SWIG-4.0 Documentation</a></H1>
<p>
Last update : SWIG-4.0.2 (in progress)
Last update : SWIG-4.1.0 (in progress)
</p>
<H2><a name="Sections_Sections">Sections</a></H2>
@ -24,6 +24,7 @@ Last update : SWIG-4.0.2 (in progress)
<li><a href="CPlusPlus11.html#CPlusPlus11">SWIG and C++11</a></li>
<li><a href="CPlusPlus14.html#CPlusPlus14">SWIG and C++14</a></li>
<li><a href="CPlusPlus17.html#CPlusPlus17">SWIG and C++17</a></li>
<li><a href="CPlusPlus20.html#CPlusPlus20">SWIG and C++20</a></li>
<li><a href="Preprocessor.html#Preprocessor">The SWIG preprocessor</a></li>
<li><a href="Library.html#Library">The SWIG library</a></li>
<li><a href="Arguments.html#Arguments">Argument handling</a></li>

92
Doc/Manual/Tcl.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Tcl">36 SWIG and Tcl</a></H1>
<H1><a name="Tcl">37 SWIG and Tcl</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -84,7 +84,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">36.1 Preliminaries</a></H2>
<H2><a name="Tcl_nn2">37.1 Preliminaries</a></H2>
<p>
@ -110,7 +110,7 @@ build a Tcl extension module. To finish building the module, you
need to compile this file and link it with the rest of your program.
</p>
<H3><a name="Tcl_nn3">36.1.1 Getting the right header files</a></H3>
<H3><a name="Tcl_nn3">37.1.1 Getting the right header files</a></H3>
<p>
@ -128,7 +128,7 @@ this is the case, you should probably make a symbolic link so that <tt>tcl.h</tt
header file.
</p>
<H3><a name="Tcl_nn4">36.1.2 Compiling a dynamic module</a></H3>
<H3><a name="Tcl_nn4">37.1.2 Compiling a dynamic module</a></H3>
<p>
@ -164,7 +164,7 @@ The name of the module is specified using the <tt>%module</tt> directive or the
<tt>-module</tt> command line option.
</p>
<H3><a name="Tcl_nn5">36.1.3 Static linking</a></H3>
<H3><a name="Tcl_nn5">37.1.3 Static linking</a></H3>
<p>
@ -230,7 +230,7 @@ minimal in most situations (and quite frankly not worth the extra
hassle in the opinion of this author).
</p>
<H3><a name="Tcl_nn6">36.1.4 Using your module</a></H3>
<H3><a name="Tcl_nn6">37.1.4 Using your module</a></H3>
<p>
@ -358,7 +358,7 @@ to the default system configuration (this requires root access and you will need
the man pages).
</p>
<H3><a name="Tcl_nn7">36.1.5 Compilation of C++ extensions</a></H3>
<H3><a name="Tcl_nn7">37.1.5 Compilation of C++ extensions</a></H3>
<p>
@ -441,7 +441,7 @@ erratic program behavior. If working with lots of software components, you
might want to investigate using a more formal standard such as COM.
</p>
<H3><a name="Tcl_nn8">36.1.6 Compiling for 64-bit platforms</a></H3>
<H3><a name="Tcl_nn8">37.1.6 Compiling for 64-bit platforms</a></H3>
<p>
@ -468,7 +468,7 @@ also introduce problems on platforms that support more than one
linking standard (e.g., -o32 and -n32 on Irix).
</p>
<H3><a name="Tcl_nn9">36.1.7 Setting a package prefix</a></H3>
<H3><a name="Tcl_nn9">37.1.7 Setting a package prefix</a></H3>
<p>
@ -487,7 +487,7 @@ option will append the prefix to the name when creating a command and
call it "<tt>Foo_bar</tt>".
</p>
<H3><a name="Tcl_nn10">36.1.8 Using namespaces</a></H3>
<H3><a name="Tcl_nn10">37.1.8 Using namespaces</a></H3>
<p>
@ -509,7 +509,7 @@ When the <tt>-namespace</tt> option is used, objects in the module
are always accessed with the namespace name such as <tt>Foo::bar</tt>.
</p>
<H2><a name="Tcl_nn11">36.2 Building Tcl/Tk Extensions under Windows 95/NT</a></H2>
<H2><a name="Tcl_nn11">37.2 Building Tcl/Tk Extensions under Windows 95/NT</a></H2>
<p>
@ -520,7 +520,7 @@ covers the process of using SWIG with Microsoft Visual C++.
although the procedure may be similar with other compilers.
</p>
<H3><a name="Tcl_nn12">36.2.1 Running SWIG from Developer Studio</a></H3>
<H3><a name="Tcl_nn12">37.2.1 Running SWIG from Developer Studio</a></H3>
<p>
@ -578,7 +578,7 @@ MSDOS &gt; tclsh80
%
</pre></div>
<H3><a name="Tcl_nn13">36.2.2 Using NMAKE</a></H3>
<H3><a name="Tcl_nn13">37.2.2 Using NMAKE</a></H3>
<p>
@ -641,7 +641,7 @@ to get you started. With a little practice, you'll be making lots of
Tcl extensions.
</p>
<H2><a name="Tcl_nn14">36.3 A tour of basic C/C++ wrapping</a></H2>
<H2><a name="Tcl_nn14">37.3 A tour of basic C/C++ wrapping</a></H2>
<p>
@ -652,7 +652,7 @@ classes. This section briefly covers the essential aspects of this
wrapping.
</p>
<H3><a name="Tcl_nn15">36.3.1 Modules</a></H3>
<H3><a name="Tcl_nn15">37.3.1 Modules</a></H3>
<p>
@ -686,7 +686,7 @@ To fix this, supply an extra argument to <tt>load</tt> like this:
</pre>
</div>
<H3><a name="Tcl_nn16">36.3.2 Functions</a></H3>
<H3><a name="Tcl_nn16">37.3.2 Functions</a></H3>
<p>
@ -711,7 +711,7 @@ like you think it does:
%
</pre></div>
<H3><a name="Tcl_nn17">36.3.3 Global variables</a></H3>
<H3><a name="Tcl_nn17">37.3.3 Global variables</a></H3>
<p>
@ -791,7 +791,7 @@ extern char *path; // Read-only (due to %immutable)
</pre>
</div>
<H3><a name="Tcl_nn18">36.3.4 Constants and enums</a></H3>
<H3><a name="Tcl_nn18">37.3.4 Constants and enums</a></H3>
<p>
@ -875,7 +875,7 @@ When an identifier name is given, it is used to perform an implicit hash-table l
conversion. This allows the <tt>global</tt> statement to be omitted.
</p>
<H3><a name="Tcl_nn19">36.3.5 Pointers</a></H3>
<H3><a name="Tcl_nn19">37.3.5 Pointers</a></H3>
<p>
@ -971,7 +971,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return
<tt>None</tt> if the conversion can't be performed.
</p>
<H3><a name="Tcl_nn20">36.3.6 Structures</a></H3>
<H3><a name="Tcl_nn20">37.3.6 Structures</a></H3>
<p>
@ -1253,7 +1253,7 @@ Note: Tcl only destroys the underlying object if it has ownership. See the
memory management section that appears shortly.
</p>
<H3><a name="Tcl_nn21">36.3.7 C++ classes</a></H3>
<H3><a name="Tcl_nn21">37.3.7 C++ classes</a></H3>
<p>
@ -1319,7 +1319,7 @@ In Tcl, the static member is accessed as follows:
</pre>
</div>
<H3><a name="Tcl_nn22">36.3.8 C++ inheritance</a></H3>
<H3><a name="Tcl_nn22">37.3.8 C++ inheritance</a></H3>
<p>
@ -1368,7 +1368,7 @@ For instance:
It is safe to use multiple inheritance with SWIG.
</p>
<H3><a name="Tcl_nn23">36.3.9 Pointers, references, values, and arrays</a></H3>
<H3><a name="Tcl_nn23">37.3.9 Pointers, references, values, and arrays</a></H3>
<p>
@ -1422,7 +1422,7 @@ to hold the result and a pointer is returned (Tcl will release this memory
when the return value is garbage collected).
</p>
<H3><a name="Tcl_nn24">36.3.10 C++ overloaded functions</a></H3>
<H3><a name="Tcl_nn24">37.3.10 C++ overloaded functions</a></H3>
<p>
@ -1545,7 +1545,7 @@ first declaration takes precedence.
Please refer to the "SWIG and C++" chapter for more information about overloading.
</p>
<H3><a name="Tcl_nn25">36.3.11 C++ operators</a></H3>
<H3><a name="Tcl_nn25">37.3.11 C++ operators</a></H3>
<p>
@ -1647,7 +1647,7 @@ There are ways to make this operator appear as part of the class using the <tt>%
Keep reading.
</p>
<H3><a name="Tcl_nn26">36.3.12 C++ namespaces</a></H3>
<H3><a name="Tcl_nn26">37.3.12 C++ namespaces</a></H3>
<p>
@ -1711,7 +1711,7 @@ utilizes thousands of small deeply nested namespaces each with
identical symbol names, well, then you get what you deserve.
</p>
<H3><a name="Tcl_nn27">36.3.13 C++ templates</a></H3>
<H3><a name="Tcl_nn27">37.3.13 C++ templates</a></H3>
<p>
@ -1763,7 +1763,7 @@ More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</
examples will appear later.
</p>
<H3><a name="Tcl_nn28">36.3.14 C++ Smart Pointers</a></H3>
<H3><a name="Tcl_nn28">37.3.14 C++ Smart Pointers</a></H3>
<p>
@ -1847,7 +1847,7 @@ simply use the <tt>__deref__()</tt> method. For example:
</pre>
</div>
<H2><a name="Tcl_nn29">36.4 Further details on the Tcl class interface</a></H2>
<H2><a name="Tcl_nn29">37.4 Further details on the Tcl class interface</a></H2>
<p>
@ -1860,7 +1860,7 @@ of low-level details were omitted. This section provides a brief overview
of how the proxy classes work.
</p>
<H3><a name="Tcl_nn30">36.4.1 Proxy classes</a></H3>
<H3><a name="Tcl_nn30">37.4.1 Proxy classes</a></H3>
<p>
@ -1925,7 +1925,7 @@ function. This allows objects to be encapsulated objects that look a lot like
as shown in the last section.
</p>
<H3><a name="Tcl_nn31">36.4.2 Memory management</a></H3>
<H3><a name="Tcl_nn31">37.4.2 Memory management</a></H3>
<p>
@ -2113,7 +2113,7 @@ typemaps--an advanced topic discussed later.
</p>
<H2><a name="Tcl_nn32">36.5 Input and output parameters</a></H2>
<H2><a name="Tcl_nn32">37.5 Input and output parameters</a></H2>
<p>
@ -2301,7 +2301,7 @@ set c [lindex $dim 1]
</pre>
</div>
<H2><a name="Tcl_nn33">36.6 Exception handling </a></H2>
<H2><a name="Tcl_nn33">37.6 Exception handling </a></H2>
<p>
@ -2435,7 +2435,7 @@ Since SWIG's exception handling is user-definable, you are not limited to C++ ex
See the chapter on "<a href="Customization.html#Customization">Customization Features</a>" for more examples.
</p>
<H2><a name="Tcl_nn34">36.7 Typemaps</a></H2>
<H2><a name="Tcl_nn34">37.7 Typemaps</a></H2>
<p>
@ -2452,7 +2452,7 @@ Typemaps are only used if you want to change some aspect of the primitive
C-Tcl interface.
</p>
<H3><a name="Tcl_nn35">36.7.1 What is a typemap?</a></H3>
<H3><a name="Tcl_nn35">37.7.1 What is a typemap?</a></H3>
<p>
@ -2572,7 +2572,7 @@ parameter is omitted):
</pre>
</div>
<H3><a name="Tcl_nn36">36.7.2 Tcl typemaps</a></H3>
<H3><a name="Tcl_nn36">37.7.2 Tcl typemaps</a></H3>
<p>
@ -2710,7 +2710,7 @@ Initialize an argument to a value before any conversions occur.
Examples of these methods will appear shortly.
</p>
<H3><a name="Tcl_nn37">36.7.3 Typemap variables</a></H3>
<H3><a name="Tcl_nn37">37.7.3 Typemap variables</a></H3>
<p>
@ -2781,7 +2781,7 @@ properly assigned.
The Tcl name of the wrapper function being created.
</div>
<H3><a name="Tcl_nn38">36.7.4 Converting a Tcl list to a char ** </a></H3>
<H3><a name="Tcl_nn38">37.7.4 Converting a Tcl list to a char ** </a></H3>
<p>
@ -2843,7 +2843,7 @@ argv[2] = Larry
3
</pre></div>
<H3><a name="Tcl_nn39">36.7.5 Returning values in arguments</a></H3>
<H3><a name="Tcl_nn39">37.7.5 Returning values in arguments</a></H3>
<p>
@ -2885,7 +2885,7 @@ result, a Tcl function using these typemaps will work like this :
%
</pre></div>
<H3><a name="Tcl_nn40">36.7.6 Useful functions</a></H3>
<H3><a name="Tcl_nn40">37.7.6 Useful functions</a></H3>
<p>
@ -2961,7 +2961,7 @@ int Tcl_IsShared(Tcl_Obj *obj);
</pre>
</div>
<H3><a name="Tcl_nn41">36.7.7 Standard typemaps</a></H3>
<H3><a name="Tcl_nn41">37.7.7 Standard typemaps</a></H3>
<p>
@ -3045,7 +3045,7 @@ work)
</pre>
</div>
<H3><a name="Tcl_nn42">36.7.8 Pointer handling</a></H3>
<H3><a name="Tcl_nn42">37.7.8 Pointer handling</a></H3>
<p>
@ -3127,7 +3127,7 @@ For example:
</pre>
</div>
<H2><a name="Tcl_nn43">36.8 Turning a SWIG module into a Tcl Package.</a></H2>
<H2><a name="Tcl_nn43">37.8 Turning a SWIG module into a Tcl Package.</a></H2>
<p>
@ -3199,7 +3199,7 @@ As a final note, most SWIG examples do not yet use the
to use the <tt>load</tt> command instead.
</p>
<H2><a name="Tcl_nn44">36.9 Building new kinds of Tcl interfaces (in Tcl)</a></H2>
<H2><a name="Tcl_nn44">37.9 Building new kinds of Tcl interfaces (in Tcl)</a></H2>
<p>
@ -3298,7 +3298,7 @@ danger of blowing something up (although it is easily accomplished
with an out of bounds array access).
</p>
<H3><a name="Tcl_nn45">36.9.1 Proxy classes</a></H3>
<H3><a name="Tcl_nn45">37.9.1 Proxy classes</a></H3>
<p>
@ -3419,7 +3419,7 @@ short, but clever Tcl script can be combined with SWIG to do many
interesting things.
</p>
<H2><a name="Tcl_nn46">36.10 Tcl/Tk Stubs</a></H2>
<H2><a name="Tcl_nn46">37.10 Tcl/Tk Stubs</a></H2>
<p>

132
Doc/Manual/Typemaps.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Typemaps">13 Typemaps</a></H1>
<H1><a name="Typemaps">14 Typemaps</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -102,7 +102,7 @@
<H2><a name="Typemaps_nn2">13.1 Introduction</a></H2>
<H2><a name="Typemaps_nn2">14.1 Introduction</a></H2>
<p>
@ -119,7 +119,7 @@ to re-read the earlier chapters if you have found your way to this
chapter with only a vague idea of what SWIG already does by default.
</p>
<H3><a name="Typemaps_nn3">13.1.1 Type conversion</a></H3>
<H3><a name="Typemaps_nn3">14.1.1 Type conversion</a></H3>
<p>
@ -212,7 +212,7 @@ to read the extension documentation for your favorite language to know
how it works (an exercise left to the reader).
</p>
<H3><a name="Typemaps_nn4">13.1.2 Typemaps</a></H3>
<H3><a name="Typemaps_nn4">14.1.2 Typemaps</a></H3>
<p>
@ -313,7 +313,7 @@ parts of the generated wrapper functions. Because arbitrary code can be insert
possible to completely change the way in which values are converted.
</p>
<H3><a name="Typemaps_nn5">13.1.3 Pattern matching</a></H3>
<H3><a name="Typemaps_nn5">14.1.3 Pattern matching</a></H3>
<p>
@ -415,7 +415,7 @@ In this case, a single input object is expanded into a pair of C arguments. Thi
provides a hint to the unusual variable naming scheme involving <tt>$1</tt>, <tt>$2</tt>, and so forth.
</p>
<H3><a name="Typemaps_nn6">13.1.4 Reusing typemaps</a></H3>
<H3><a name="Typemaps_nn6">14.1.4 Reusing typemaps</a></H3>
<p>
@ -493,7 +493,7 @@ typedef int size_t;
then SWIG already knows that the <tt>int</tt> typemaps apply. You don't have to do anything.
</p>
<H3><a name="Typemaps_nn7">13.1.5 What can be done with typemaps?</a></H3>
<H3><a name="Typemaps_nn7">14.1.5 What can be done with typemaps?</a></H3>
<p>
@ -605,7 +605,7 @@ typemaps that expand upon this list. For example, the Java module defines a var
aspects of the Java bindings. Consult language specific documentation for further details.
</p>
<H3><a name="Typemaps_nn8">13.1.6 What can't be done with typemaps?</a></H3>
<H3><a name="Typemaps_nn8">14.1.6 What can't be done with typemaps?</a></H3>
<p>
@ -668,7 +668,7 @@ void wrap_foo(char *s, int x) {
</pre>
</div>
<H3><a name="Typemaps_aspects">13.1.7 Similarities to Aspect Oriented Programming</a></H3>
<H3><a name="Typemaps_aspects">14.1.7 Similarities to Aspect Oriented Programming</a></H3>
<p>
@ -686,7 +686,7 @@ SWIG can also be viewed as has having a second set of aspects based around <a hr
Features such as <tt>%exception</tt> are also cross-cutting concerns as they encapsulate code that can be used to add logging or exception handling to any function.
</p>
<H3><a name="Typemaps_nn9">13.1.8 The rest of this chapter</a></H3>
<H3><a name="Typemaps_nn9">14.1.8 The rest of this chapter</a></H3>
<p>
@ -706,14 +706,14 @@ of "The C Programming Language" by Kernighan and Ritchie or
"The C++ Programming Language" by Stroustrup before going any further.
</p>
<H2><a name="Typemaps_nn10">13.2 Typemap specifications</a></H2>
<H2><a name="Typemaps_nn10">14.2 Typemap specifications</a></H2>
<p>
This section describes the behavior of the <tt>%typemap</tt> directive itself.
</p>
<H3><a name="Typemaps_defining">13.2.1 Defining a typemap</a></H3>
<H3><a name="Typemaps_defining">14.2.1 Defining a typemap</a></H3>
<p>
@ -826,7 +826,7 @@ Admittedly, it's not the most readable syntax at first glance. However, the pur
individual pieces will become clear.
</p>
<H3><a name="Typemaps_nn12">13.2.2 Typemap scope</a></H3>
<H3><a name="Typemaps_nn12">14.2.2 Typemap scope</a></H3>
<p>
@ -876,7 +876,7 @@ class Foo {
</pre>
</div>
<H3><a name="Typemaps_nn13">13.2.3 Copying a typemap</a></H3>
<H3><a name="Typemaps_nn13">14.2.3 Copying a typemap</a></H3>
<p>
@ -934,7 +934,7 @@ The patterns for <tt>%apply</tt> follow the same rules as for <tt>%typemap</tt>.
</pre>
</div>
<H3><a name="Typemaps_nn14">13.2.4 Deleting a typemap</a></H3>
<H3><a name="Typemaps_nn14">14.2.4 Deleting a typemap</a></H3>
<p>
@ -968,7 +968,7 @@ For example:
after the clear operation.
</p>
<H3><a name="Typemaps_nn15">13.2.5 Placement of typemaps</a></H3>
<H3><a name="Typemaps_nn15">14.2.5 Placement of typemaps</a></H3>
<p>
@ -1048,7 +1048,7 @@ It should be noted that for scoping to work, SWIG has to know that <tt>string</t
within a particular namespace. In this example, this is done using the forward class declaration <tt>class string</tt>.
</p>
<H2><a name="Typemaps_pattern_matching">13.3 Pattern matching rules</a></H2>
<H2><a name="Typemaps_pattern_matching">14.3 Pattern matching rules</a></H2>
<p>
@ -1056,7 +1056,7 @@ The section describes the pattern matching rules by which C/C++ datatypes are as
The matching rules can be observed in practice by using the debugging options also described.
</p>
<H3><a name="Typemaps_nn17">13.3.1 Basic matching rules</a></H3>
<H3><a name="Typemaps_nn17">14.3.1 Basic matching rules</a></H3>
<p>
@ -1155,7 +1155,7 @@ void F(int x[1000]); // int [ANY] rule (typemap 5)
stripped all qualifiers in one step.
</p>
<H3><a name="Typemaps_typedef_reductions">13.3.2 Typedef reductions matching</a></H3>
<H3><a name="Typemaps_typedef_reductions">14.3.2 Typedef reductions matching</a></H3>
<p>
@ -1330,7 +1330,7 @@ void go(Struct aStruct);
</pre>
</div>
<H3><a name="Typemaps_nn19">13.3.3 Default typemap matching rules</a></H3>
<H3><a name="Typemaps_nn19">14.3.3 Default typemap matching rules</a></H3>
<p>
@ -1468,7 +1468,7 @@ Finally the best way to view the typemap matching rules in action is via the <a
simpler scheme to match the current C++ class template partial specialization matching rules.
</p>
<H3><a name="Typemaps_multi_argument_typemaps_patterns">13.3.4 Multi-arguments typemaps</a></H3>
<H3><a name="Typemaps_multi_argument_typemaps_patterns">14.3.4 Multi-arguments typemaps</a></H3>
<p>
@ -1498,7 +1498,7 @@ but all subsequent arguments must match exactly.
</p>
<H3><a name="Typemaps_matching_template_comparison">13.3.5 Matching rules compared to C++ templates</a></H3>
<H3><a name="Typemaps_matching_template_comparison">14.3.5 Matching rules compared to C++ templates</a></H3>
<p>
@ -1657,7 +1657,7 @@ are similar to those for specialized template handling.
</p>
<H3><a name="Typemaps_debugging_search">13.3.6 Debugging typemap pattern matching</a></H3>
<H3><a name="Typemaps_debugging_search">14.3.6 Debugging typemap pattern matching</a></H3>
<p>
@ -1870,7 +1870,7 @@ Also the types may be displayed slightly differently - <tt>char const *</tt> and
</li>
</ul>
<H2><a name="Typemaps_nn21">13.4 Code generation rules</a></H2>
<H2><a name="Typemaps_nn21">14.4 Code generation rules</a></H2>
<p>
@ -1878,7 +1878,7 @@ This section describes rules by which typemap code is inserted into
the generated wrapper code.
</p>
<H3><a name="Typemaps_nn22">13.4.1 Scope</a></H3>
<H3><a name="Typemaps_nn22">14.4.1 Scope</a></H3>
<p>
@ -1956,7 +1956,7 @@ a block scope when it is emitted. This sometimes results in a less complicated
Note that only the third of the three typemaps have the typemap code passed through the SWIG preprocessor.
</p>
<H3><a name="Typemaps_nn23">13.4.2 Declaring new local variables</a></H3>
<H3><a name="Typemaps_nn23">14.4.2 Declaring new local variables</a></H3>
<p>
@ -2123,7 +2123,7 @@ each type must have its own local variable declaration.
</div>
<H3><a name="Typemaps_special_variables">13.4.3 Special variables</a></H3>
<H3><a name="Typemaps_special_variables">14.4.3 Special variables</a></H3>
<p>
@ -2375,7 +2375,7 @@ Another approach, which only works for arrays is to use the <tt>$1_basetype</tt>
</pre>
</div>
<H3><a name="Typemaps_special_variable_macros">13.4.4 Special variable macros</a></H3>
<H3><a name="Typemaps_special_variable_macros">14.4.4 Special variable macros</a></H3>
<p>
@ -2387,7 +2387,7 @@ it is done during the SWIG parsing/compilation stages.
The following special variable macros are available across all language modules.
</p>
<H4><a name="Typemaps_special_macro_descriptor">13.4.4.1 $descriptor(type)</a></H4>
<H4><a name="Typemaps_special_macro_descriptor">14.4.4.1 $descriptor(type)</a></H4>
<p>
@ -2398,7 +2398,7 @@ For example, <tt>$descriptor(std::vector&lt;int&gt; *)</tt> will expand into <tt
This macro is mostly used in the scripting target languages and is demonstrated later in the <a href="#Typemaps_runtime_type_checker_usage">Run-time type checker usage</a> section.
</p>
<H4><a name="Typemaps_special_macro_typemap">13.4.4.2 $typemap(method, typepattern)</a></H4>
<H4><a name="Typemaps_special_macro_typemap">14.4.4.2 $typemap(method, typepattern)</a></H4>
<p>
@ -2456,7 +2456,7 @@ The result is the following expansion
</div>
<H3><a name="Typemaps_special_variable_attributes">13.4.5 Special variables and typemap attributes</a></H3>
<H3><a name="Typemaps_special_variable_attributes">14.4.5 Special variables and typemap attributes</a></H3>
<p>
@ -2483,7 +2483,7 @@ is equivalent to the following as <tt>$*1_ltype</tt> expands to <tt>unsigned int
</pre>
</div>
<H3><a name="Typemaps_special_variables_and_macros">13.4.6 Special variables combined with special variable macros</a></H3>
<H3><a name="Typemaps_special_variables_and_macros">14.4.6 Special variables combined with special variable macros</a></H3>
<p>
@ -2525,7 +2525,7 @@ which then expands to:
</div>
<H2><a name="Typemaps_nn25">13.5 Common typemap methods</a></H2>
<H2><a name="Typemaps_nn25">14.5 Common typemap methods</a></H2>
<p>
@ -2533,7 +2533,7 @@ The family of typemaps recognized by a language module may vary. However,
the following typemap methods are nearly universal:
</p>
<H3><a name="Typemaps_nn26">13.5.1 "in" typemap</a></H3>
<H3><a name="Typemaps_nn26">14.5.1 "in" typemap</a></H3>
<p>
@ -2593,7 +2593,7 @@ Usually <tt>numinputs</tt> is not specified, whereupon the default value is 1, t
is the same as the old "ignore" typemap.
</p>
<H3><a name="Typemaps_nn27">13.5.2 "typecheck" typemap</a></H3>
<H3><a name="Typemaps_nn27">14.5.2 "typecheck" typemap</a></H3>
<p>
@ -2620,7 +2620,7 @@ If you define new "in" typemaps <em>and</em> your program uses overloaded method
"typecheck" typemaps. More details about this follow in the <a href="#Typemaps_overloading">Typemaps and overloading</a> section.
</p>
<H3><a name="Typemaps_nn28">13.5.3 "out" typemap</a></H3>
<H3><a name="Typemaps_nn28">14.5.3 "out" typemap</a></H3>
<p>
@ -2651,7 +2651,7 @@ $symname - Name of function/method being wrapped
The "out" typemap supports an optional attribute flag called "optimal". This is for code optimisation and is detailed in the <a href="#Typemaps_optimal">Optimal code generation when returning by value</a> section.
</p>
<H3><a name="Typemaps_nn29">13.5.4 "arginit" typemap</a></H3>
<H3><a name="Typemaps_nn29">14.5.4 "arginit" typemap</a></H3>
<p>
@ -2670,7 +2670,7 @@ For example:
</pre>
</div>
<H3><a name="Typemaps_nn30">13.5.5 "default" typemap</a></H3>
<H3><a name="Typemaps_nn30">14.5.5 "default" typemap</a></H3>
<p>
@ -2703,7 +2703,7 @@ See the <a href="SWIG.html#SWIG_default_args">Default/optional arguments</a> sec
for further information on default argument wrapping.
</p>
<H3><a name="Typemaps_nn31">13.5.6 "check" typemap</a></H3>
<H3><a name="Typemaps_nn31">14.5.6 "check" typemap</a></H3>
<p>
@ -2722,7 +2722,7 @@ converted. For example:
</pre>
</div>
<H3><a name="Typemaps_nn32">13.5.7 "argout" typemap</a></H3>
<H3><a name="Typemaps_nn32">14.5.7 "argout" typemap</a></H3>
<p>
@ -2768,7 +2768,7 @@ return values are often appended to return value of the function.
See the <tt>typemaps.i</tt> library file for examples.
</p>
<H3><a name="Typemaps_nn33">13.5.8 "freearg" typemap</a></H3>
<H3><a name="Typemaps_nn33">14.5.8 "freearg" typemap</a></H3>
<p>
@ -2801,7 +2801,7 @@ be used in other typemaps whenever a wrapper function needs to abort
prematurely.
</p>
<H3><a name="Typemaps_nn34">13.5.9 "newfree" typemap</a></H3>
<H3><a name="Typemaps_nn34">14.5.9 "newfree" typemap</a></H3>
<p>
@ -2830,7 +2830,7 @@ string *foo();
See <a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for further details.
</p>
<H3><a name="Typemaps_ret">13.5.10 "ret" typemap</a></H3>
<H3><a name="Typemaps_ret">14.5.10 "ret" typemap</a></H3>
<p>
@ -2869,7 +2869,7 @@ This approach is an alternative to using the "newfree" typemap and <tt>%newobjec
is no need to list all the functions that require the memory cleanup, it is purely done on types.
</p>
<H3><a name="Typemaps_nn35">13.5.11 "memberin" typemap</a></H3>
<H3><a name="Typemaps_nn35">14.5.11 "memberin" typemap</a></H3>
<p>
@ -2891,7 +2891,7 @@ It is rarely necessary to write "memberin" typemaps---SWIG already provides
a default implementation for arrays, strings, and other objects.
</p>
<H3><a name="Typemaps_nn36">13.5.12 "varin" typemap</a></H3>
<H3><a name="Typemaps_nn36">14.5.12 "varin" typemap</a></H3>
<p>
@ -2899,7 +2899,7 @@ The "varin" typemap is used to convert objects in the target language to C for t
purposes of assigning to a C/C++ global variable. This is implementation specific.
</p>
<H3><a name="Typemaps_nn37">13.5.13 "varout" typemap</a></H3>
<H3><a name="Typemaps_nn37">14.5.13 "varout" typemap</a></H3>
<p>
@ -2907,7 +2907,7 @@ The "varout" typemap is used to convert a C/C++ object to an object in the targe
language when reading a C/C++ global variable. This is implementation specific.
</p>
<H3><a name="Typemaps_throws_typemap">13.5.14 "throws" typemap</a></H3>
<H3><a name="Typemaps_throws_typemap">14.5.14 "throws" typemap</a></H3>
<p>
@ -2957,7 +2957,7 @@ Note that if your methods do not have an exception specification but they do thr
Please also see the <a href="Customization.html#Customization_exception">Exception handling with %exception</a> section for another way to handle exceptions.
</p>
<H2><a name="Typemaps_nn39">13.6 Some typemap examples</a></H2>
<H2><a name="Typemaps_nn39">14.6 Some typemap examples</a></H2>
<p>
@ -2965,7 +2965,7 @@ This section contains a few examples. Consult language module documentation
for more examples.
</p>
<H3><a name="Typemaps_nn40">13.6.1 Typemaps for arrays</a></H3>
<H3><a name="Typemaps_nn40">14.6.1 Typemaps for arrays</a></H3>
<p>
@ -3224,7 +3224,7 @@ Now, you will find that member access is quite nice:
useless and has since been eliminated. To return structure members, simply use the "out" typemap.
</p>
<H3><a name="Typemaps_nn41">13.6.2 Implementing constraints with typemaps</a></H3>
<H3><a name="Typemaps_nn41">14.6.2 Implementing constraints with typemaps</a></H3>
<p>
@ -3272,7 +3272,7 @@ a NULL pointer. As a result, SWIG can often prevent a potential
segmentation faults or other run-time problems by raising an exception
rather than blindly passing values to the underlying C/C++ program.</p>
<H2><a name="Typemaps_nn43">13.7 Typemaps for multiple target languages</a></H2>
<H2><a name="Typemaps_nn43">14.7 Typemaps for multiple target languages</a></H2>
<p>
@ -3302,7 +3302,7 @@ The example above also shows a common approach of issuing a warning for an as ye
<tt>%typemap(ruby, in) int "$1 = NUM2INT($input);"</tt>.
</p>
<H2><a name="Typemaps_optimal">13.8 Optimal code generation when returning by value</a></H2>
<H2><a name="Typemaps_optimal">14.8 Optimal code generation when returning by value</a></H2>
<p>
@ -3491,7 +3491,7 @@ example.i:7: Warning 475: optimal attribute usage in the out typemap.
However, it doesn't always get it right, for example when <tt>$1</tt> is within some commented out code.
</p>
<H2><a name="Typemaps_multi_argument_typemaps">13.9 Multi-argument typemaps</a></H2>
<H2><a name="Typemaps_multi_argument_typemaps">14.9 Multi-argument typemaps</a></H2>
<p>
@ -3768,7 +3768,7 @@ with non-consecutive C/C++ arguments; a workaround such as a helper function re-
the arguments to make them consecutive will need to be written.
</p>
<H2><a name="Typemaps_warnings">13.10 Typemap warnings</a></H2>
<H2><a name="Typemaps_warnings">14.10 Typemap warnings</a></H2>
<p>
@ -3777,7 +3777,7 @@ See the information in the <a href="Warnings.html#Warnings_nn5">issuing warnings
</p>
<H2><a name="Typemaps_fragments">13.11 Typemap fragments</a></H2>
<H2><a name="Typemaps_fragments">14.11 Typemap fragments</a></H2>
<p>
@ -4113,7 +4113,7 @@ fragment usage unless a desire to really get to grips
with some powerful but tricky macro and fragment usage that is used in parts of the SWIG typemap library.
</p>
<H3><a name="Typemaps_fragment_type_specialization">13.11.1 Fragment type specialization</a></H3>
<H3><a name="Typemaps_fragment_type_specialization">14.11.1 Fragment type specialization</a></H3>
<p>
@ -4146,7 +4146,7 @@ struct A {
</pre>
</div>
<H3><a name="Typemaps_automatic_specialization">13.11.2 Fragments and automatic typemap specialization</a></H3>
<H3><a name="Typemaps_automatic_specialization">14.11.2 Fragments and automatic typemap specialization</a></H3>
<p>
@ -4192,7 +4192,7 @@ The interested (or very brave) reader can take a look at the fragments.swg file
</p>
<H2><a name="Typemaps_runtime_type_checker">13.12 The run-time type checker</a></H2>
<H2><a name="Typemaps_runtime_type_checker">14.12 The run-time type checker</a></H2>
<p>
@ -4218,7 +4218,7 @@ language modules.</li>
<li>Modules can be unloaded from the type system.</li>
</ul>
<H3><a name="Typemaps_nn45">13.12.1 Implementation</a></H3>
<H3><a name="Typemaps_nn45">14.12.1 Implementation</a></H3>
<p>
@ -4412,7 +4412,7 @@ structures rather than creating new ones. These <tt>swig_module_info</tt>
structures are chained together in a circularly linked list.
</p>
<H3><a name="Typemaps_runtime_type_checker_usage">13.12.2 Usage</a></H3>
<H3><a name="Typemaps_runtime_type_checker_usage">14.12.2 Usage</a></H3>
<p>This section covers how to use these functions from typemaps. To learn how to
@ -4508,7 +4508,7 @@ probably just look at the output of SWIG to get a better sense for how types are
managed.
</p>
<H2><a name="Typemaps_overloading">13.13 Typemaps and overloading</a></H2>
<H2><a name="Typemaps_overloading">14.13 Typemaps and overloading</a></H2>
<p>
@ -4847,7 +4847,7 @@ Subsequent "in" typemaps would then perform more extensive type-checking.
</li>
</ul>
<H3><a name="Typemaps_typecheck_pointer">13.13.1 SWIG_TYPECHECK_POINTER precedence level and the typecheck typemap</a></H3>
<H3><a name="Typemaps_typecheck_pointer">14.13.1 SWIG_TYPECHECK_POINTER precedence level and the typecheck typemap</a></H3>
<p>
@ -4949,7 +4949,7 @@ Otherwise both can be wrapped by removing the overloading name ambiguity by rena
The 'equivalent' attribute is used in the implementation for the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a> library.
</p>
<H2><a name="Typemaps_nn48">13.14 More about %apply and %clear</a></H2>
<H2><a name="Typemaps_nn48">14.14 More about %apply and %clear</a></H2>
<p>
@ -5054,7 +5054,7 @@ will delete the typemaps for all the typemap methods; namely "in", "check" and "
</pre>
</div>
<H2><a name="Typemaps_nn47">13.15 Passing data between typemaps</a></H2>
<H2><a name="Typemaps_nn47">14.15 Passing data between typemaps</a></H2>
<p>
@ -5091,7 +5091,7 @@ sure that the typemaps sharing information have exactly the same types and names
</p>
<H2><a name="Typemaps_nn52">13.16 C++ "this" pointer</a></H2>
<H2><a name="Typemaps_nn52">14.16 C++ "this" pointer</a></H2>
<p>
@ -5151,7 +5151,7 @@ will also match the typemap. One work around is to create an interface file tha
the method, but gives the argument a name other than <tt>self</tt>.
</p>
<H2><a name="Typemaps_nn51">13.17 Where to go for more information?</a></H2>
<H2><a name="Typemaps_nn51">14.17 Where to go for more information?</a></H2>
<p>

20
Doc/Manual/Varargs.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Varargs">16 Variable Length Arguments</a></H1>
<H1><a name="Varargs">17 Variable Length Arguments</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -43,7 +43,7 @@ added in SWIG-1.3.12. Most other wrapper generation tools have
wisely chosen to avoid this issue.
</p>
<H2><a name="Varargs_nn2">16.1 Introduction</a></H2>
<H2><a name="Varargs_nn2">17.1 Introduction</a></H2>
<p>
@ -140,7 +140,7 @@ List make_list(const char *s, ...) {
</pre>
</div>
<H2><a name="Varargs_nn3">16.2 The Problem</a></H2>
<H2><a name="Varargs_nn3">17.2 The Problem</a></H2>
<p>
@ -233,7 +233,7 @@ can also support real varargs wrapping (with stack-frame manipulation) if you
are willing to get hands dirty. Keep reading.
</p>
<H2><a name="Varargs_nn4">16.3 Default varargs support</a></H2>
<H2><a name="Varargs_nn4">17.3 Default varargs support</a></H2>
<p>
@ -302,7 +302,7 @@ Read on for further solutions.
</p>
<H2><a name="Varargs_nn5">16.4 Argument replacement using %varargs</a></H2>
<H2><a name="Varargs_nn5">17.4 Argument replacement using %varargs</a></H2>
<p>
@ -413,7 +413,7 @@ mixed argument types such as <tt>printf()</tt>. Providing general purpose
wrappers to such functions presents special problems (covered shortly).
</p>
<H2><a name="Varargs_nn6">16.5 Varargs and typemaps</a></H2>
<H2><a name="Varargs_nn6">17.5 Varargs and typemaps</a></H2>
<p>
@ -593,7 +593,7 @@ really want to elevate your guru status and increase your job
security, continue to the next section.
</p>
<H2><a name="Varargs_nn7">16.6 Varargs wrapping with libffi</a></H2>
<H2><a name="Varargs_nn7">17.6 Varargs wrapping with libffi</a></H2>
<p>
@ -845,7 +845,7 @@ provide an argument number for the first extra argument. This can be used to in
values. Please consult the chapter on each language module for more details.
</p>
<H2><a name="Varargs_nn8">16.7 Wrapping of va_list</a></H2>
<H2><a name="Varargs_nn8">17.7 Wrapping of va_list</a></H2>
<p>
@ -899,7 +899,7 @@ int my_vprintf(const char *fmt, ...) {
</pre>
</div>
<H2><a name="Varargs_nn9">16.8 C++ Issues</a></H2>
<H2><a name="Varargs_nn9">17.8 C++ Issues</a></H2>
<p>
@ -968,7 +968,7 @@ design or to provide an alternative interface using a helper function than it is
fully general wrapper to a varargs C++ member function.
</p>
<H2><a name="Varargs_nn10">16.9 Discussion</a></H2>
<H2><a name="Varargs_nn10">17.9 Discussion</a></H2>
<p>

40
Doc/Manual/Warnings.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Warnings">18 Warning Messages</a></H1>
<H1><a name="Warnings">19 Warning Messages</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -37,7 +37,7 @@
<H2><a name="Warnings_nn2">18.1 Introduction</a></H2>
<H2><a name="Warnings_nn2">19.1 Introduction</a></H2>
<p>
@ -57,7 +57,7 @@ where the generated wrapper code will probably compile, but it may not
work like you expect.
</p>
<H2><a name="Warnings_suppression">18.2 Warning message suppression</a></H2>
<H2><a name="Warnings_suppression">19.2 Warning message suppression</a></H2>
<p>
@ -149,7 +149,7 @@ your interface. Ignore the warning messages at your own peril.
</p>
<H2><a name="Warnings_nn4">18.3 Enabling extra warnings</a></H2>
<H2><a name="Warnings_nn4">19.3 Enabling extra warnings</a></H2>
<p>
@ -222,7 +222,7 @@ that is, any warnings suppressed or added in <tt>%warnfilter</tt>, <tt>#pragma S
or the <tt>-w</tt> option.
</p>
<H2><a name="Warnings_nn5">18.4 Issuing a warning message</a></H2>
<H2><a name="Warnings_nn5">19.4 Issuing a warning message</a></H2>
<p>
@ -276,7 +276,7 @@ example.i:24: Warning 901: You are really going to regret this usage of blah * s
</pre>
</div>
<H2><a name="Warnings_symbolic_symbols">18.5 Symbolic symbols</a></H2>
<H2><a name="Warnings_symbolic_symbols">19.5 Symbolic symbols</a></H2>
<p>
@ -311,7 +311,7 @@ or
</pre>
</div>
<H2><a name="Warnings_nn6">18.6 Commentary</a></H2>
<H2><a name="Warnings_nn6">19.6 Commentary</a></H2>
<p>
@ -328,7 +328,7 @@ no obvious recovery. There is no mechanism for suppressing error
messages.
</p>
<H2><a name="Warnings_nn7">18.7 Warnings as errors</a></H2>
<H2><a name="Warnings_nn7">19.7 Warnings as errors</a></H2>
<p>
@ -337,7 +337,7 @@ option. This will cause SWIG to exit with a non successful exit code if a
warning is encountered.
</p>
<H2><a name="Warnings_nn8">18.8 Message output format</a></H2>
<H2><a name="Warnings_nn8">19.8 Message output format</a></H2>
<p>
@ -356,10 +356,10 @@ $ swig -python -Fmicrosoft example.i
example.i(4) : Syntax error in input(1).
</pre></div>
<H2><a name="Warnings_nn9">18.9 Warning number reference</a></H2>
<H2><a name="Warnings_nn9">19.9 Warning number reference</a></H2>
<H3><a name="Warnings_nn10">18.9.1 Deprecated features (100-199)</a></H3>
<H3><a name="Warnings_nn10">19.9.1 Deprecated features (100-199)</a></H3>
<ul>
@ -387,7 +387,7 @@ example.i(4) : Syntax error in input(1).
<li>126. The 'nestedworkaround' feature is deprecated.
</ul>
<H3><a name="Warnings_nn11">18.9.2 Preprocessor (200-299)</a></H3>
<H3><a name="Warnings_nn11">19.9.2 Preprocessor (200-299)</a></H3>
<ul>
@ -399,7 +399,7 @@ example.i(4) : Syntax error in input(1).
<li>206. Unexpected tokens after #<em>directive</em> directive.
</ul>
<H3><a name="Warnings_nn12">18.9.3 C/C++ Parser (300-399)</a></H3>
<H3><a name="Warnings_nn12">19.9.3 C/C++ Parser (300-399)</a></H3>
<ul>
@ -476,14 +476,14 @@ example.i(4) : Syntax error in input(1).
<li>395. operator delete[] ignored.
</ul>
<H3><a name="Warnings_nn13">18.9.4 Types and typemaps (400-499) </a></H3>
<H3><a name="Warnings_nn13">19.9.4 Types and typemaps (400-499) </a></H3>
<ul>
<li>401. Nothing known about class 'name'. Ignored.
<li>402. Base class 'name' is incomplete.
<li>403. Class 'name' might be abstract.
<li>450. Deprecated typemap feature ($source/$target).
<li>450. Reserved
<li>451. Setting const char * variable may leak memory.
<li>452. Reserved
<li>453. Can't apply (pattern). No typemaps are defined.
@ -507,7 +507,7 @@ example.i(4) : Syntax error in input(1).
<H3><a name="Warnings_nn14">18.9.5 Code generation (500-559)</a></H3>
<H3><a name="Warnings_nn14">19.9.5 Code generation (500-559)</a></H3>
<ul>
@ -538,7 +538,7 @@ example.i(4) : Syntax error in input(1).
<li>525. Destructor <em>declaration</em> is final, <em>name</em> cannot be a director class.
</ul>
<H3><a name="Warnings_doxygen">18.9.6 Doxygen comments (560-599)</a></H3>
<H3><a name="Warnings_doxygen">19.9.6 Doxygen comments (560-599)</a></H3>
<ul>
@ -549,7 +549,7 @@ example.i(4) : Syntax error in input(1).
<li>564: Error parsing Doxygen command <em>command</em>: <em>error text</em>. Command ignored."</li>
</ul>
<H3><a name="Warnings_nn15">18.9.7 Language module specific (700-899) </a></H3>
<H3><a name="Warnings_nn15">19.9.7 Language module specific (700-899) </a></H3>
<ul>
@ -600,14 +600,14 @@ example.i(4) : Syntax error in input(1).
<li>871. Unrecognized pragma <em>pragma</em>. (Php).
</ul>
<H3><a name="Warnings_nn16">18.9.8 User defined (900-999)</a></H3>
<H3><a name="Warnings_nn16">19.9.8 User defined (900-999)</a></H3>
<p>
These numbers can be used by your own application.
</p>
<H2><a name="Warnings_nn17">18.10 History</a></H2>
<H2><a name="Warnings_nn17">19.10 History</a></H2>
<p>

153
Doc/Manual/Windows.html
View file

@ -33,9 +33,10 @@
<ul>
<li><a href="#Windows_swig_exe">Building swig.exe on Windows</a>
<ul>
<li><a href="#Windows_cmake">Building swig.exe using CMake</a>
<li><a href="#Windows_msys2">Building swig.exe using MSYS2</a>
<li><a href="#Windows_mingw_msys">Building swig.exe using MinGW and MSYS</a>
<li><a href="#Windows_cygwin">Building swig.exe using Cygwin</a>
<li><a href="#Windows_building_alternatives">Building swig.exe alternatives</a>
</ul>
<li><a href="#Windows_examples_cygwin">Running the examples on Windows using Cygwin</a>
</ul>
@ -77,10 +78,10 @@ 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.
Microsoft Visual C++ is the most commonly used compiler for compiling and linking SWIG's output on Windows.
The Examples directory has a few Visual C++ project files (.dsp files).
These were produced by Visual C++ 6.
Newer versions of Visual Studio should be able to open and convert these project files.
Newer versions of Visual Studio are able to open and convert these project files.
Each C# example comes with a Visual Studio 2005 solution and associated 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.
Alternatively run the <a href="#Windows_examples_cygwin">examples using Cygwin</a>.
@ -95,9 +96,11 @@ More information on each of the examples is available with the examples distribu
Ensure the SWIG executable is as supplied in the SWIG root directory in order for the examples to work.
Most languages require some environment variables to be set <b>before</b> running Visual C++.
Note that Visual C++ must be re-started to pick up any changes in environment variables.
Open up an example .dsp file, Visual C++ will create a workspace for you (.dsw file).
Ensure the Release build is selected then do a Rebuild All from the Build menu.
The required environment variables are displayed with their current values.
Open up an example .dsp file, Visual C++ will prompt you to upgrade the project and convert
it into an MSBuild project (.vcxproj file) and Solution (.sln file).
Note that older versions of Visual C++ will simply create a workspace for you (.dsw file).
Ensure the Release build is selected then do a Rebuild Solution from the Build menu.
The required environment variables are displayed with their current values during the build.
</p>
<p>
The list of required environment variables for each module language is also listed below.
@ -111,7 +114,7 @@ If you are interested in how the project files are set up there is explanatory i
<p>
The C# examples do not require any environment variables to be set as a C# project file is included.
Just open up the .sln solution file in Visual Studio .NET 2003 or later, select Release Build, and do a Rebuild All from the Build menu.
Just open up the .sln solution file in Visual Studio 2005 or later, select Release Build, and do a Rebuild Solution from the Build menu.
The accompanying C# and C++ project files are automatically used by the solution file.
</p>
@ -224,7 +227,130 @@ This information is provided for those that want to modify the SWIG source code
Normally this is not needed, so most people will want to ignore this section.
</p>
<H4><a name="Windows_mingw_msys">3.3.1.1 Building swig.exe using MinGW and MSYS</a></H4>
<H4><a name="Windows_cmake">3.3.1.1 Building swig.exe using CMake</a></H4>
<p>
SWIG can also be built using <a href="https://cmake.org/">CMake</a> and Visual Studio rather than autotools. As with the other approaches to
building SWIG the dependencies need to be installed. The steps below are one of a number of ways of installing the dependencies without requiring Cygwin or MinGW.
For fully working build steps always check the Continuous Integration setups currently detailed in the <a href="https://github.com/swig/swig/blob/master/appveyor.yml">Appveyor YAML file</a>.
</p>
<ol>
<li>
Install Nuget from <a href="https://www.nuget.org/downloads">https://www.nuget.org/downloads</a> (v5.8.1 is used in this example, and installed to C:\Tools). Nuget is the package manager
for .NET, but allows us to easily install <a href="https://www.pcre.org/">PCRE</a> and other dependencies required by SWIG.
</li>
<li>
Install CMake using the following command: <pre>C:\Tools\nuget install CMake-win64 -Version 3.15.5 -OutputDirectory C:\Tools\CMake</pre>
Alternatively you can download CMake from <a href="https://cmake.org/download/">https://cmake.org/download/</a>.
</li>
<li>
Install Bison using the following command: <pre>C:\Tools\nuget install bison-win32 -Version 2.4.1.1 -OutputDirectory C:\Tools\bison</pre>
Alternatively download Bison from <a href="https://sourceforge.net/projects/gnuwin32/files/bison/">https://sourceforge.net/projects/gnuwin32/files/bison/</a> (2.4.1 is used in this example)
and save to a folder e.g. C:\Tools\Bison
</li>
<li>
Install PCRE using Nuget using the following command: <pre>C:\Tools\nuget install pcre -Version 8.33.0.1 -OutputDirectory C:\Tools\pcre</pre>.
Alternatively, use <tt>WITH_PCRE</tt> option to disable PCRE support if you are sure not to need it.
</li>
<li>
We will also need the SWIG source code. Either download a zipped archive from GitHub, or if git is installed clone the latest codebase
using <pre>git clone https://github.com/swig/swig.git</pre>
In this example we are assuming the source code is available at C:\swig
</li>
</ol>
<p>
We are assuming Visual Studio 2017 is installed. For other versions of Visual Studio change <i>"Visual Studio 15 2017 Win64"</i> to the relevant
<a href="https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#visual-studio-generators">Visual Studio Generator</a>.
Now we have all the required dependencies we can build SWIG using the commands below. We add the required build tools to the system PATH, and then
build a Release version of SWIG. If all runs successfully a new swig.exe should be generated in a /Release folder.
</p>
<div class="shell">
<pre>
cd C:\swig
SET PATH=C:\Tools\CMake\CMake-win64.3.15.5\bin;C:\Tools\bison\bison-win32.2.4.1.1\tools\native\bin;%PATH%
SET PCRE_ROOT=C:\Tools\pcre\pcre.8.33.0.1\build\native
SET PCRE_PLATFORM=x64
cmake -G "Visual Studio 15 2017 Win64" -DCMAKE_INSTALL_PREFIX="%CD:\=/%/install2" -DCMAKE_C_FLAGS="/DPCRE_STATIC" ^
-DPCRE_INCLUDE_DIR=%PCRE_ROOT%/include -DPCRE_LIBRARY=%PCRE_ROOT%/lib/v110/%PCRE_PLATFORM%/Release/static/utf8/pcre8.lib .
cmake --build . --config Release
REM to test the exe
cd /Release
swig.exe -help
</pre>
</div>
<p>
In addition to Release builds you can create a Debug build using:
</p>
<div class="shell">
<pre>cmake --build . --config Debug</pre>
</div>
<p>
A Visual Studio solution file should be generated named swig.sln. This can be opened and debugged by running the swig project and setting the
Debugging Command Arguments. For example to debug one of the test-suite .i files included with the SWIG source use the following:
</p>
<div class="shell">
<pre>-python -c++ -o C:\Temp\doxygen_parsing.cpp C:\swig\Examples\test-suite\doxygen_parsing.i</pre>
</div>
<H4><a name="Windows_msys2">3.3.1.2 Building swig.exe using MSYS2</a></H4>
<p>
Download and install MSYS2 from <a href="https://www.msys2.org/">www.msys2.org</a> (tested with version msys2-x86_64-20201109).
Launch the MSYS2 shell.
</p>
<p>
Install the packages needed to build swig:<br>
</p>
<div class="shell">
<pre>
pacman -S git autoconf automake bison gcc make pcre-devel
</pre>
</div>
<p>
Clone the repository to /usr/src/:
</p>
<div class="shell">
<pre>
mkdir /usr/src/
cd /usr/src/
git clone https://github.com/swig/swig.git
</pre>
</div>
<p>
Configure and build:
</p>
<div class="shell">
<pre>
cd /usr/src/swig
./autogen.sh
./configure
make
</pre>
</div>
<p>
Finally you may also want to install SWIG:
</p>
<div class="shell">
<pre>
make install
</pre>
</div>
<H4><a name="Windows_mingw_msys">3.3.1.3 Building swig.exe using MinGW and MSYS</a></H4>
<p>
@ -342,7 +468,7 @@ make
</ol>
<H4><a name="Windows_cygwin">3.3.1.2 Building swig.exe using Cygwin</a></H4>
<H4><a name="Windows_cygwin">3.3.1.4 Building swig.exe using Cygwin</a></H4>
<p>
@ -353,15 +479,6 @@ Note that the Cygwin environment will also allow one to regenerate the autotool
These files are generated using the <tt>autogen.sh</tt> script and will only need regenerating in circumstances such as changing the build system.
</p>
<H4><a name="Windows_building_alternatives">3.3.1.3 Building swig.exe alternatives</a></H4>
<p>
If you don't want to install Cygwin or MinGW, use a different compiler to build
SWIG. For example, all the source code files can be added to a Visual C++ project
file in order to build swig.exe from the Visual C++ IDE.
</p>
<H3><a name="Windows_examples_cygwin">3.3.2 Running the examples on Windows using Cygwin</a></H3>

1
Doc/Manual/chapters
View file

@ -7,6 +7,7 @@ SWIGPlus.html
CPlusPlus11.html
CPlusPlus14.html
CPlusPlus17.html
CPlusPlus20.html
Preprocessor.html
Library.html
Arguments.html

4
Doc/Manual/style.css
View file

@ -65,6 +65,10 @@ div.diagram {
font-family: "Courier New", Courier, "Courier 10 Pitch", monospace;
}
div.diagram li {
margin-left: 0;
}
ul li p {
margin-left: 0;
margin-right: 0;

100
Examples/Makefile.in
View file

@ -58,6 +58,7 @@ INTERFACE =
INTERFACEDIR =
INTERFACEPATH = $(SRCDIR)$(INTERFACEDIR)$(INTERFACE)
SWIGOPT =
PCHSUPPORT = @PCHSUPPORT@
# SWIG_LIB_DIR and SWIGEXE must be explicitly set by Makefiles using this Makefile
SWIG_LIB_DIR = ./Lib
@ -164,6 +165,7 @@ TCL_SO = @TCL_SO@
TCLLDSHARED = @TCLLDSHARED@
TCLCXXSHARED = @TCLCXXSHARED@
TCL_SCRIPT = $(SRCDIR)$(RUNME).tcl
TCL_LINK = @TCLLINK@
# -----------------------------------------------------------
# Build a new version of the tclsh shell
@ -186,7 +188,7 @@ tclsh_cpp: $(SRCDIR_SRCS)
tcl: $(SRCDIR_SRCS)
$(SWIG) -tcl8 $(SWIGOPT) $(TCL_SWIGOPTS) -o $(ISRCS) $(INTERFACEPATH)
$(CC) -c $(CCSHARED) $(CPPFLAGS) $(CFLAGS) $(SRCDIR_SRCS) $(ISRCS) $(INCLUDES) $(TCL_INCLUDE)
$(TCLLDSHARED) $(CFLAGS) $(LDFLAGS) $(OBJS) $(IOBJS) $(TCL_DLNK) $(LIBS) -o $(LIBPREFIX)$(TARGET)$(TCL_SO)
$(TCLLDSHARED) $(CFLAGS) $(LDFLAGS) $(OBJS) $(IOBJS) $(TCL_DLNK) $(LIBS) -o $(LIBPREFIX)$(TARGET)$(TCL_SO) $(TCL_LINK)
# -----------------------------------------------------------
# Build a Tcl7.5 dynamic loadable module for C++
@ -195,7 +197,7 @@ tcl: $(SRCDIR_SRCS)
tcl_cpp: $(SRCDIR_SRCS)
$(SWIG) -tcl8 -c++ $(SWIGOPT) $(TCL_SWIGOPTS) -o $(ICXXSRCS) $(INTERFACEPATH)
$(CXX) -c $(CCSHARED) $(CPPFLAGS) $(CXXFLAGS) $(SRCDIR_SRCS) $(SRCDIR_CXXSRCS) $(ICXXSRCS) $(INCLUDES) $(TCL_INCLUDE)
$(TCLCXXSHARED) $(CXXFLAGS) $(LDFLAGS) $(OBJS) $(IOBJS) $(TCL_DLNK) $(LIBS) $(CPP_DLLIBS) -o $(LIBPREFIX)$(TARGET)$(TCL_SO)
$(TCLCXXSHARED) $(CXXFLAGS) $(LDFLAGS) $(OBJS) $(IOBJS) $(TCL_DLNK) $(LIBS) $(CPP_DLLIBS) -o $(LIBPREFIX)$(TARGET)$(TCL_SO) $(TCL_LINK)
# -----------------------------------------------------------------
# Run Tcl example
@ -380,13 +382,7 @@ python_static_cpp: $(SRCDIR_SRCS)
# Running a Python example
# -----------------------------------------------------------------
ifeq (,$(PY3))
PYSCRIPT = $(RUNME).py
else
PYSCRIPT = $(RUNME)3.py
endif
PY2TO3 = @PY2TO3@ `@PY2TO3@ -l | grep -v -E "Available|import$$" | awk '{print "-f "$$0}'`
PYSCRIPT = $(RUNME).py
python_run: $(PYSCRIPT)
ifneq (,$(PYCODESTYLE))
@ -399,10 +395,6 @@ $(RUNME).py: $(SRCDIR)$(RUNME).py
cp $< $@
endif
$(RUNME)3.py: $(SRCDIR)$(RUNME).py
cp $< $@
$(PY2TO3) -w $@ >/dev/null 2>&1
# -----------------------------------------------------------------
# Version display
# -----------------------------------------------------------------
@ -420,7 +412,6 @@ python_clean:
rm -f core @EXTRA_CLEAN@
rm -f *.@OBJEXT@ *@SO@ *$(PYTHON_SO)
rm -f $(TARGET).py
if test -f $(SRCDIR)$(RUNME).py; then rm -f $(RUNME)3.py $(RUNME)3.py.bak; fi
case "x$(SRCDIR)" in x|x./);; *) rm -f $(RUNME).py;; esac
@ -438,14 +429,37 @@ OCTAVE_SO = @OCTAVE_SO@
OCTAVE_SCRIPT = $(SRCDIR)$(RUNME).m
# ----------------------------------------------------------------
# Pre-compile Octave headers, if supported
# ----------------------------------------------------------------
ifeq (yes,$(PCHSUPPORT))
octave_precompile_headers:
echo "precompiling $(OCTHEADERS)"
cp -f $(OCTHEADERSSRC) $(OCTHEADERS)
if $(CXX) -c $(CCSHARED) $(CPPFLAGS) $(CXXFLAGS) $(INCLUDES) $(OCTAVE_CXX) $(OCTHEADERS); then \
: ; \
else \
rm -f $(OCTHEADERSGCH); \
exit 1; \
fi
else
octave_precompile_headers:
echo "precompiling Octave headers not supported"; exit 1
endif
# ----------------------------------------------------------------
# Build a C dynamically loadable module
# Note: Octave requires C++ compiler when compiling C wrappers
# ----------------------------------------------------------------
octave: $(SRCDIR_SRCS)
$(SWIG) -octave $(SWIGOPT) -o $(ICXXSRCS) $(INTERFACEPATH)
$(CXX) -g -c $(CCSHARED) $(CPPFLAGS) $(CXXFLAGS) $(ICXXSRCS) $(INCLUDES) $(OCTAVE_CXX)
$(SWIG) -octave $(SWIGOCTHDROPT) $(SWIGOPT) -o $(ICXXSRCS) $(INTERFACEPATH)
$(CXX) -g -c $(IOCTHEADERS) $(CCSHARED) $(CPPFLAGS) $(CXXFLAGS) $(ICXXSRCS) $(INCLUDES) $(OCTAVE_CXX)
$(CC) -g -c $(CCSHARED) $(CPPFLAGS) $(CFLAGS) $(SRCDIR_SRCS) $(SRCDIR_CSRCS) $(INCLUDES)
$(LDSHARED) $(CFLAGS) $(LDFLAGS) $(OBJS) $(IOBJS) $(OCTAVE_DLNK) $(LIBS) -o $(LIBPREFIX)$(TARGET)$(OCTAVE_SO)
@ -454,8 +468,8 @@ octave: $(SRCDIR_SRCS)
# -----------------------------------------------------------------
octave_cpp: $(SRCDIR_SRCS)
$(SWIG) -c++ -octave $(SWIGOPT) -o $(ICXXSRCS) $(INTERFACEPATH)
$(CXX) -g -c $(CCSHARED) $(CPPFLAGS) $(CXXFLAGS) $(ICXXSRCS) $(SRCDIR_SRCS) $(SRCDIR_CXXSRCS) $(INCLUDES) $(OCTAVE_CXX)
$(SWIG) -c++ -octave $(SWIGOCTHDROPT) $(SWIGOPT) -o $(ICXXSRCS) $(INTERFACEPATH)
$(CXX) -g -c $(IOCTHEADERS) $(CCSHARED) $(CPPFLAGS) $(CXXFLAGS) $(ICXXSRCS) $(SRCDIR_SRCS) $(SRCDIR_CXXSRCS) $(INCLUDES) $(OCTAVE_CXX)
$(CXXSHARED) -g $(CXXFLAGS) $(LDFLAGS) $(OBJS) $(IOBJS) $(OCTAVE_DLNK) $(LIBS) $(CPP_DLLIBS) -o $(LIBPREFIX)$(TARGET)$(OCTAVE_SO)
# -----------------------------------------------------------------
@ -481,6 +495,7 @@ octave_clean:
rm -f *_wrap* *~ .~* myoctave@EXEEXT@ *.pyc
rm -f core @EXTRA_CLEAN@
rm -f *.@OBJEXT@ *@SO@ *$(OCTAVE_SO)
rm -f $(OCTHEADERS) $(OCTHEADERSGCH)
##################################################################
##### GUILE ######
@ -1031,20 +1046,21 @@ ruby_clean:
rm -f *.@OBJEXT@ *$(RUBY_SO)
##################################################################
##### PHP7 ######
##### PHP ######
##################################################################
PHP = @PHP@
PHP_INCLUDE = @PHPINC@
PHP_SO = @PHP_SO@
PHP_SCRIPT = $(SRCDIR)$(RUNME).php
PHP_EXTENSION = example$(PHP_SO)
# -------------------------------------------------------------------
# Build a PHP dynamically loadable module (C)
# -------------------------------------------------------------------
php: $(SRCDIR_SRCS)
$(SWIG) -php7 $(SWIGOPT) -o $(ISRCS) $(INTERFACEPATH)
$(SWIG) -php $(SWIGOPT) -o $(ISRCS) $(INTERFACEPATH)
$(CC) -c $(CCSHARED) $(CPPFLAGS) $(CFLAGS) $(SRCDIR_SRCS) $(ISRCS) $(INCLUDES) $(PHP_INCLUDE)
$(LDSHARED) $(CFLAGS) $(LDFLAGS) $(OBJS) $(IOBJS) $(LIBS) -o $(LIBPREFIX)$(TARGET)$(PHP_SO)
@ -1053,7 +1069,7 @@ php: $(SRCDIR_SRCS)
# --------------------------------------------------------------------
php_cpp: $(SRCDIR_SRCS)
$(SWIG) -php7 -c++ $(SWIGOPT) -o $(ICXXSRCS) $(INTERFACEPATH)
$(SWIG) -php -c++ $(SWIGOPT) -o $(ICXXSRCS) $(INTERFACEPATH)
$(CXX) -c $(CCSHARED) $(CPPFLAGS) $(CXXFLAGS) $(SRCDIR_SRCS) $(SRCDIR_CXXSRCS) $(ICXXSRCS) $(INCLUDES) $(PHP_INCLUDE)
$(CXXSHARED) $(CXXFLAGS) $(LDFLAGS) $(OBJS) $(IOBJS) $(LIBS) $(CPP_DLLIBS) -o $(LIBPREFIX)$(TARGET)$(PHP_SO)
@ -1062,7 +1078,7 @@ php_cpp: $(SRCDIR_SRCS)
# -----------------------------------------------------------------
php_run:
$(RUNTOOL) $(PHP) -n -q -d extension_dir=. -d safe_mode=Off -d display_errors=stderr $(PHP_SCRIPT) $(RUNPIPE)
$(RUNTOOL) $(PHP) -n -d extension_dir=. -d extension=$(PHP_EXTENSION) -d display_errors=stderr -r 'set_error_handler(function($$n,$$s,$$f,$$l){if($$f!==Null){print$$f;if($$l!==Null)print":$$l";print": ";}print"$$s\n";exit(1);});include($$argv[1]);' $(PHP_SCRIPT) $(RUNPIPE)
# -----------------------------------------------------------------
# Version display
@ -1234,46 +1250,6 @@ lua_clean:
rm -f core @EXTRA_CLEAN@
rm -f *.@OBJEXT@ *$(LUA_SO)
##################################################################
##### ALLEGRO CL ######
##################################################################
ALLEGROCL = @ALLEGROCLBIN@
ALLEGROCL_SCRIPT=$(RUNME).lisp
allegrocl: $(SRCDIR_SRCS)
$(SWIG) -allegrocl -cwrap $(SWIGOPT) -o $(ISRCS) $(INTERFACEPATH)
$(CC) -c $(CCSHARED) $(CPPFLAGS) $(CFLAGS) $(ISRCS) $(INCLUDES) $(SRCDIR_SRCS)
$(LDSHARED) $(CFLAGS) $(LDFLAGS) $(OBJS) $(IOBJS) $(LIBS) -o $(LIBPREFIX)$(TARGET)$(SO)
allegrocl_cpp: $(SRCDIR_SRCS)
$(SWIG) -c++ -allegrocl $(SWIGOPT) -o $(ICXXSRCS) $(INTERFACEPATH)
$(CXX) -c $(CCSHARED) $(CPPFLAGS) $(CXXFLAGS) $(ICXXSRCS) $(SRCDIR_SRCS) $(SRCDIR_CXXSRCS) $(INCLUDES)
$(CXXSHARED) $(CXXFLAGS) $(LDFLAGS) $(OBJS) $(IOBJS) $(LIBS) $(CPP_DLLIBS) -o $(LIBPREFIX)$(TARGET)$(SO)
# -----------------------------------------------------------------
# Run ALLEGRO CL example
# -----------------------------------------------------------------
allegrocl_run:
$(RUNTOOL) $(ALLEGROCL) -batch -s $(ALLEGROCL_SCRIPT) $(RUNPIPE)
# -----------------------------------------------------------------
# Version display
# -----------------------------------------------------------------
allegrocl_version:
$(ALLEGROCL) --version
# -----------------------------------------------------------------
# Cleaning the ALLEGRO CL examples
# -----------------------------------------------------------------
allegrocl_clean:
rm -f *_wrap* *~ .~*
rm -f core @EXTRA_CLEAN@
rm -f *.@OBJEXT@ *@SO@
##################################################################
##### CFFI ######
##################################################################

12
Examples/chicken/README
View file

@ -1,12 +0,0 @@
This directory contains examples for CHICKEN.
class -- illustrates the proxy class C++ interface
constants -- handling #define and %constant literals
egg -- examples of building chicken extension libraries
multimap -- typemaps with multiple sub-types
overload -- C++ function overloading
simple -- the simple example from the user manual
zlib -- a wrapping of the zlib compression library
You should be able to run make in each of the examples. By default, a shared
library will be built. Run make check to execute the test.

6
Examples/chicken/check.list
View file

@ -1,6 +0,0 @@
# see top-level Makefile.in
class
constants
multimap
overload
simple

40
Examples/chicken/class/Makefile
View file

@ -1,40 +0,0 @@
TOP = ../..
SWIGEXE = $(TOP)/../swig
SWIG_LIB_DIR = $(TOP)/../$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
INTERFACE = example.i
SRCS =
CXXSRCS = example.cxx
TARGET = class
INCLUDE =
SWIGOPT =
VARIANT =
# uncomment the following lines to build a static exe (only pick one of the CHICKEN_MAIN lines)
#CHICKEN_MAIN = runme-lowlevel.scm
#CHICKEN_MAIN = runme-tinyclos.scm
#VARIANT = _static
check: build
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' CHICKEN_SCRIPT='runme-lowlevel.scm' chicken_run
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' CHICKEN_SCRIPT='runme-tinyclos.scm' chicken_run
build: $(TARGET) $(TARGET)_proxy
$(TARGET): $(INTERFACE) $(SRCS)
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' \
SRCS='$(SRCS)' CXXSRCS='$(CXXSRCS)' CHICKEN_MAIN='$(CHICKEN_MAIN)' \
SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
INCLUDE='$(INCLUDE)' SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' \
INTERFACE='$(INTERFACE)' CHICKENOPTS='$(CHICKENOPTS)' chicken$(VARIANT)_cpp
$(TARGET)_proxy: $(INTERFACE) $(SRCS)
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' \
SRCS='$(SRCS)' CXXSRCS='$(CXXSRCS)' CHICKEN_MAIN='$(CHICKEN_MAIN)' \
SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
INCLUDE='$(INCLUDE)' SWIGOPT='$(SWIGOPT) -proxy' TARGET='$(TARGET)_proxy' \
INTERFACE='$(INTERFACE)' CHICKENOPTS='$(CHICKENOPTS)' chicken$(VARIANT)_cpp
clean:
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_clean
rm -f example.scm
rm -f $(TARGET)

28
Examples/chicken/class/example.cxx
View file

@ -1,28 +0,0 @@
/* File : example.cxx */
#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() {
return M_PI*radius*radius;
}
double Circle::perimeter() {
return 2*M_PI*radius;
}
double Square::area() {
return width*width;
}
double Square::perimeter() {
return 4*width;
}

41
Examples/chicken/class/example.h
View file

@ -1,41 +0,0 @@
/* 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;
enum SomeEnum {
First = 0,
Second,
Third,
Last = 1000
};
};
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();
};

9
Examples/chicken/class/example.i
View file

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

76
Examples/chicken/class/runme-lowlevel.scm
View file

@ -1,76 +0,0 @@
;; This file illustrates the low-level C++ interface generated
;; by SWIG.
(load-library 'example "class.so")
(declare (uses example))
;; ----- Object creation -----
(display "Creating some objects:\n")
(define c (new-Circle 10.0))
(display " Created circle ")
(display c)
(display "\n")
(define s (new-Square 10.0))
(display " Created square ")
(display s)
(display "\n")
;; ----- Access a static member -----
(display "\nA total of ")
(display (Shape-nshapes))
(display " shapes were created\n")
;; ----- Member data access -----
;; Set the location of the object
(Shape-x-set c 20.0)
(Shape-y-set c 30.0)
(Shape-x-set s -10.0)
(Shape-y-set s 5.0)
(display "\nHere is their current position:\n")
(display " Circle = (")
(display (Shape-x-get c))
(display ", ")
(display (Shape-y-get c))
(display ")\n")
(display " Square = (")
(display (Shape-x-get s))
(display ", ")
(display (Shape-y-get s))
(display ")\n")
;; ----- Call some methods -----
(display "\nHere are some properties of the shapes:\n")
(let
((disp (lambda (o)
(display " ")
(display o)
(display "\n")
(display " area = ")
(display (Shape-area o))
(display "\n")
(display " perimeter = ")
(display (Shape-perimeter o))
(display "\n"))))
(disp c)
(disp s))
(display "\nGuess I'll clean up now\n")
;; Note: this invokes the virtual destructor
(set! c #f)
(set! s #f)
(gc #t)
(set! s 3)
(display (Shape-nshapes))
(display " shapes remain\n")
(display "Goodbye\n")
(exit)

76
Examples/chicken/class/runme-tinyclos.scm
View file

@ -1,76 +0,0 @@
;; This file illustrates the proxy C++ interface generated
;; by SWIG.
(load-library 'example "class_proxy.so")
(declare (uses example))
(declare (uses tinyclos))
;; ----- Object creation -----
(display "Creating some objects:\n")
(define c (make <Circle> 10.0))
(display " Created circle ")
(display c)
(display "\n")
(define s (make <Square> 10.0))
(display " Created square ")
(display s)
(display "\n")
;; ----- Access a static member -----
(display "\nA total of ")
(display (Shape-nshapes))
(display " shapes were created\n")
;; ----- Member data access -----
;; Set the location of the object
(slot-set! c 'x 20.0)
(slot-set! c 'y 30.0)
(slot-set! s 'x -10.0)
(slot-set! s 'y 5.0)
(display "\nHere is their current position:\n")
(display " Circle = (")
(display (slot-ref c 'x))
(display ", ")
(display (slot-ref c 'y))
(display ")\n")
(display " Square = (")
(display (slot-ref s 'x))
(display ", ")
(display (slot-ref s 'y))
(display ")\n")
;; ----- Call some methods -----
(display "\nHere are some properties of the shapes:\n")
(let
((disp (lambda (o)
(display " ")
(display o)
(display "\n")
(display " area = ")
(display (area o))
(display "\n")
(display " perimeter = ")
(display (perimeter o))
(display "\n"))))
(disp c)
(disp s))
(display "\nGuess I'll clean up now\n")
;; Note: Invoke the virtual destructors by forcing garbage collection
(set! c 77)
(set! s 88)
(gc #t)
(display (Shape-nshapes))
(display " shapes remain\n")
(display "Goodbye\n")
(exit)

31
Examples/chicken/constants/Makefile
View file

@ -1,31 +0,0 @@
TOP = ../..
SWIGEXE = $(TOP)/../swig
SWIG_LIB_DIR = $(TOP)/../$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
INTERFACE = example.i
SRCS =
CXXSRCS =
TARGET = constants
INCLUDE =
SWIGOPT =
VARIANT =
# uncomment the following two lines to build a static exe
#CHICKEN_MAIN = runme.scm
#VARIANT = _static
check: build
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_run
build: $(TARGET)
$(TARGET): $(INTERFACE) $(SRCS)
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' \
SRCS='$(SRCS)' CXXSRCS='$(CXXSRCS)' CHICKEN_MAIN='$(CHICKEN_MAIN)' \
SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
INCLUDE='$(INCLUDE)' SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' \
INTERFACE='$(INTERFACE)' CHICKENOPTS='$(CHICKENOPTS)' chicken$(VARIANT)
clean:
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_clean
rm -f example.scm
rm -f $(TARGET)

27
Examples/chicken/constants/example.i
View file

@ -1,27 +0,0 @@
/* 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. Remember that
CHICKEN is normally case-insensitive, so don't rely on differing
case to differentiate variable names */
%constant int iconstX = 37;
%constant double fconstX = 3.14;

16
Examples/chicken/constants/runme.scm
View file

@ -1,16 +0,0 @@
;; feel free to uncomment and comment sections
(load-library 'example "./constants.so")
(display "starting test ... you will see 'finished' if successful.\n")
(or (= (ICONST) 42) (exit 1))
(or (< (abs (- (FCONST) 2.1828)) 0.00001) (exit 1))
(or (char=? (CCONST) #\x) (exit 1))
(or (char=? (CCONST2) #\newline) (exit 1))
(or (string=? (SCONST) "Hello World") (exit 1))
(or (string=? (SCONST2) "\"Hello World\"") (exit 1))
(or (< (abs (- (EXPR) (+ (ICONST) (* 3 (FCONST))))) 0.00001) (exit 1))
(or (= (iconstX) 37) (exit 1))
(or (< (abs (- (fconstX) 3.14)) 0.00001) (exit 1))
(display "finished test.\n")
(exit 0)

41
Examples/chicken/egg/Makefile
View file

@ -1,41 +0,0 @@
TOP = ../..
SWIGEXE = $(TOP)/../swig
SWIG_LIB_DIR = $(TOP)/../$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
check: build
cd eggs/install && csi ../../test.scm
build: single multi
# This creates an egg which contains only the single module. Any additional implementation files
# that implement the interface being wrapped should also be added to this egg
single: single_wrap.cxx
mkdir -p eggs
tar czf eggs/single.egg single.setup single.scm single_wrap.cxx
rm -f single.scm single_wrap.cxx
# compile the single module with -nounit
single_wrap.cxx: single.i
$(SWIGEXE) -chicken -c++ -proxy -nounit single.i
# Now build both mod1 and mod2 into a single egg
multi: mod1_wrap.cxx mod2_wrap.cxx
mkdir -p eggs
tar czf eggs/multi.egg multi.setup multi_init.scm mod1.scm mod1_wrap.cxx mod2.scm mod2_wrap.cxx
rm -f mod1.scm mod1_wrap.cxx mod2.scm mod2_wrap.cxx
mod1_wrap.cxx: mod1.i
$(SWIGEXE) -chicken -c++ -proxy mod1.i
mod2_wrap.cxx: mod2.i
$(SWIGEXE) -chicken -c++ -proxy mod2.i
clean:
rm -rf eggs
# this part is for testing...
setup:
cd eggs && \
mkdir -p install && \
chicken-setup -repository `pwd`/install single.egg && \
chicken-setup -repository `pwd`/install multi.egg

19
Examples/chicken/egg/README
View file

@ -1,19 +0,0 @@
These examples show how to build a chicken extension module in the form of an
egg. There are two eggs that get built, single.egg which contains a single
module which is built with -nounit and multi.egg, which contains two modules
mod1 and mod2. These are built normally, and multi_init.scm loads them both.
Read section "17.4.2 Building chicken extension libraries" in the manual
for a description of these two techniques.
To build:
$ make
$ make setup
$ make run
$ make clean
The eggs are built into an eggs subdirectory, because chicken-setup has
problems installing eggs when there are other files named similar in
the same directory. The make setup step runs chicken-setup to install
the eggs into the eggs/install directory.

8
Examples/chicken/egg/mod1.i
View file

@ -1,8 +0,0 @@
%module mod1
%inline %{
class Bar {
public:
int b;
};
%}

17
Examples/chicken/egg/mod2.i
View file

@ -1,17 +0,0 @@
%module mod2
%import "mod1.i"
%{
class Bar {
public:
int b;
};
%}
%inline %{
class Bar2 : public Bar {
public:
int c;
};
%}

2
Examples/chicken/egg/multi.setup
View file

@ -1,2 +0,0 @@
(run (csc -s -o multi.so multi_init.scm mod1.scm mod1_wrap.cxx mod2.scm mod2_wrap.cxx))
(install-extension 'multi '("multi.so"))

2
Examples/chicken/egg/multi_init.scm
View file

@ -1,2 +0,0 @@
(declare (uses mod1))
(declare (uses mod2))

8
Examples/chicken/egg/single.i
View file

@ -1,8 +0,0 @@
%module single
%inline %{
class Foo {
public:
int a;
};
%}

2
Examples/chicken/egg/single.setup
View file

@ -1,2 +0,0 @@
(run (csc -s -o single.so single.scm single_wrap.cxx))
(install-extension 'single '("single.so"))

18
Examples/chicken/egg/test.scm
View file

@ -1,18 +0,0 @@
(require-extension single)
(require-extension multi)
(define f (make <Foo>))
(slot-set! f 'a 3)
(print (slot-ref f 'a))
(define b (make <Bar>))
(slot-set! b 'b 2)
(print (slot-ref b 'b))
(define b2 (make <Bar2>))
(slot-set! b2 'b 4)
(slot-set! b2 'c 6)
(print (slot-ref b2 'b))
(print (slot-ref b2 'c))
(exit 0)

31
Examples/chicken/multimap/Makefile
View file

@ -1,31 +0,0 @@
TOP = ../..
SWIGEXE = $(TOP)/../swig
SWIG_LIB_DIR = $(TOP)/../$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
INTERFACE = example.i
SRCS = example.c
CXXSRCS =
TARGET = multimap
INCLUDE =
SWIGOPT =
VARIANT =
# uncomment the following two lines to build a static exe
#CHICKEN_MAIN = runme.scm
#VARIANT = _static
check: build
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_run
build: $(TARGET)
$(TARGET): $(INTERFACE) $(SRCS)
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' \
SRCS='$(SRCS)' CXXSRCS='$(CXXSRCS)' CHICKEN_MAIN='$(CHICKEN_MAIN)' \
SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
INCLUDE='$(INCLUDE)' SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' \
INTERFACE='$(INTERFACE)' CHICKENOPTS='$(CHICKENOPTS)' chicken$(VARIANT)
clean:
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_clean
rm -f example.scm
rm -f $(TARGET)

53
Examples/chicken/multimap/example.c
View file

@ -1,53 +0,0 @@
/* 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);
}
}

96
Examples/chicken/multimap/example.i
View file

@ -1,96 +0,0 @@
/* 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);
%}
%include exception.i
%include typemaps.i
extern int gcd(int x, int y);
%typemap(in) (int argc, char *argv[]) {
int i;
if (!C_swig_is_vector ($input)) {
swig_barf (SWIG_BARF1_BAD_ARGUMENT_TYPE, "Argument $input is not a vector");
}
$1 = C_header_size ($input);
$2 = (char **) malloc(($1+1)*sizeof(char *));
for (i = 0; i < $1; i++) {
C_word o = C_block_item ($input, i);
if (!C_swig_is_string (o)) {
char err[50];
free($2);
sprintf (err, "$input[%d] is not a string", i);
swig_barf (SWIG_BARF1_BAD_ARGUMENT_TYPE, err);
}
$2[i] = C_c_string (o);
}
$2[i] = 0;
}
%typemap(freearg) (int argc, char *argv[]) {
free($2);
}
extern int gcdmain(int argc, char *argv[]);
%typemap(in) (char *bytes, int len) {
if (!C_swig_is_string ($input)) {
swig_barf (SWIG_BARF1_BAD_ARGUMENT_TYPE, "Argument $input is not a string");
}
$1 = C_c_string ($input);
$2 = C_header_size ($input);
}
extern int count(char *bytes, int len, char c);
/* This example shows how to wrap a function that mutates a string */
%typemap(in) (char *str, int len)
%{ if (!C_swig_is_string ($input)) {
swig_barf (SWIG_BARF1_BAD_ARGUMENT_TYPE, "Argument $input is not a string");
}
$2 = C_header_size ($input);
$1 = (char *) malloc ($2+1);
memmove ($1, C_c_string ($input), $2);
%}
/* Return the mutated string as a new object. Notice the if MANY construct ... they must be at column 0. */
%typemap(argout) (char *str, int len) (C_word *scmstr)
%{ scmstr = C_alloc (C_SIZEOF_STRING ($2));
SWIG_APPEND_VALUE(C_string (&scmstr, $2, $1));
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_exception (SWIG_ValueError, "cx and cy must be in unit circle");
}
}
extern void circle (double cx, double cy);
/* Test out multiple return values */
extern int squareCubed (int n, int *OUTPUT);
%{
/* Returns n^3 and set n2 to n^2 */
int squareCubed (int n, int *n2) {
*n2 = n * n;
return (*n2) * n;
};
%}

58
Examples/chicken/multimap/runme.scm
View file

@ -1,58 +0,0 @@
;; feel free to uncomment and comment sections
(load-library 'example "multimap.so")
(display "(gcd 90 12): ")
(display (gcd 90 12))
(display "\n")
(display "(circle 0.5 0.5): ")
(display (circle 0.5 0.5))
(display "\n")
(display "(circle 1.0 1.0): ")
(handle-exceptions exvar
(if (= (car exvar) 9)
(display "success: exception thrown")
(display "an incorrect exception was thrown"))
(begin
(circle 1.0 1.0)
(display "an exception was not thrown when it should have been")))
(display "\n")
(display "(circle 1 1): ")
(handle-exceptions exvar
(if (= (car exvar) 9)
(display "success: exception thrown")
(display "an incorrect exception was thrown"))
(begin
(circle 1 1)
(display "an exception was not thrown when it should have been")))
(display "\n")
(display "(capitalize \"will this be all capital letters?\"): ")
(display (capitalize "will this be all capital letters?"))
(display "\n")
(display "(count \"jumpity little spider\" #\\t): ")
(display (count "jumpity little spider" #\t))
(display "\n")
(display "(gcdmain '#(\"hi\" \"there\")): ")
(display (gcdmain '#("hi" "there")))
(display "\n")
(display "(gcdmain '#(\"gcd\" \"9\" \"28\")): ")
(gcdmain '#("gcd" "9" "28"))
(display "\n")
(display "(gcdmain '#(\"gcd\" \"12\" \"90\")): ")
(gcdmain '#("gcd" "12" "90"))
(display "\n")
(display "squarecubed 3: ")
(call-with-values (lambda() (squareCubed 3))
(lambda (a b) (printf "~A ~A" a b)))
(display "\n")
(exit)

31
Examples/chicken/overload/Makefile
View file

@ -1,31 +0,0 @@
TOP = ../..
SWIGEXE = $(TOP)/../swig
SWIG_LIB_DIR = $(TOP)/../$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
INTERFACE = example.i
SRCS =
CXXSRCS = example.cxx
TARGET = overload
INCLUDE =
SWIGOPT = -proxy -unhideprimitive
VARIANT =
# uncomment the following lines to build a static exe
#CHICKEN_MAIN = runme.scm
#VARIANT = _static
check: build
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_run
build: $(TARGET)
$(TARGET): $(INTERFACE) $(SRCS)
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' \
SRCS='$(SRCS)' CXXSRCS='$(CXXSRCS)' CHICKEN_MAIN='$(CHICKEN_MAIN)' \
SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
INCLUDE='$(INCLUDE)' SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' \
INTERFACE='$(INTERFACE)' CHICKENOPTS='$(CHICKENOPTS)' chicken$(VARIANT)_cpp
clean:
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_clean
rm -f example.scm
rm -f $(TARGET)

2
Examples/chicken/overload/README
View file

@ -1,2 +0,0 @@
Overloading example from Chapter 5.14 of SWIG Core Documentation for
version 1.3.

33
Examples/chicken/overload/example.cxx
View file

@ -1,33 +0,0 @@
/* File : example.c */
#include "example.h"
#include <stdio.h>
void foo(int x) {
printf("x is %d\n", x);
}
void foo(char *x) {
printf("x is '%s'\n", x);
}
Foo::Foo () {
myvar = 55;
printf ("Foo constructor called\n");
}
Foo::Foo (const Foo &) {
myvar = 66;
printf ("Foo copy constructor called\n");
}
void Foo::bar (int x) {
printf ("Foo::bar(x) method ... \n");
printf("x is %d\n", x);
}
void Foo::bar (char *s, int y) {
printf ("Foo::bar(s,y) method ... \n");
printf ("s is '%s'\n", s);
printf ("y is %d\n", y);
}

14
Examples/chicken/overload/example.h
View file

@ -1,14 +0,0 @@
/* File : example.h */
extern void foo (int x);
extern void foo (char *x);
class Foo {
private:
int myvar;
public:
Foo();
Foo(const Foo &); // Copy constructor
void bar(int x);
void bar(char *s, int y);
};

16
Examples/chicken/overload/example.i
View file

@ -1,16 +0,0 @@
/* File : example.i */
%module example
%{
#include "example.h"
%}
/* Let "Foo" objects be converted back and forth from TinyCLOS into
low-level CHICKEN SWIG procedures */
%typemap(clos_in) Foo * = SIMPLE_CLOS_OBJECT *;
%typemap(clos_out) Foo * = SIMPLE_CLOS_OBJECT *;
/* Let's just grab the original header file here */
%include "example.h"

45
Examples/chicken/overload/runme.scm
View file

@ -1,45 +0,0 @@
;; This file demonstrates the overloading capabilities of SWIG
(load-library 'example "overload.so")
;; Low level
;; ---------
(display "
Trying low level code ...
(foo 1)
(foo \"some string\")
(define A-FOO (new-Foo))
(define ANOTHER-FOO (new-Foo A-FOO)) ;; copy constructor
(Foo-bar A-FOO 2)
(Foo-bar ANOTHER-FOO \"another string\" 3)
")
(primitive:foo 1)
(primitive:foo "some string")
(define A-FOO (slot-ref (primitive:new-Foo) 'swig-this))
(define ANOTHER-FOO (slot-ref (primitive:new-Foo A-FOO) 'swig-this)) ;; copy constructor
(primitive:Foo-bar A-FOO 2)
(primitive:Foo-bar ANOTHER-FOO "another string" 3)
;; TinyCLOS
;; --------
(display "
Trying TinyCLOS code ...
(+foo+ 1)
(+foo+ \"some string\")
(define A-FOO (make <Foo>))
(define ANOTHER-FOO (make <Foo> A-FOO)) ;; copy constructor
(-bar- A-FOO 2)
(-bar- ANOTHER-FOO \"another string\" 3)
")
(foo 1)
(foo "some string")
(define A-FOO (make <Foo>))
(define ANOTHER-FOO (make <Foo> A-FOO)) ;; copy constructor
(bar A-FOO 2)
(bar ANOTHER-FOO "another string" 3)
(exit)

31
Examples/chicken/simple/Makefile
View file

@ -1,31 +0,0 @@
TOP = ../..
SWIGEXE = $(TOP)/../swig
SWIG_LIB_DIR = $(TOP)/../$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib
INTERFACE = example.i
SRCS = example.c
CXXSRCS =
TARGET = simple
INCLUDE =
SWIGOPT =
VARIANT =
# uncomment the following two lines to build a static exe
#CHICKEN_MAIN = runme.scm
#VARIANT = _static
check: build
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_run
build: $(TARGET)
$(TARGET): $(INTERFACE) $(SRCS)
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' \
SRCS='$(SRCS)' CXXSRCS='$(CXXSRCS)' CHICKEN_MAIN='$(CHICKEN_MAIN)' \
SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \
INCLUDE='$(INCLUDE)' SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' \
INTERFACE='$(INTERFACE)' CHICKENOPTS='$(CHICKENOPTS)' chicken$(VARIANT)
clean:
$(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' chicken_clean
rm -f example.scm example-generic.scm example-clos.scm
rm -f $(TARGET)

1
Examples/chicken/simple/README
View file

@ -1 +0,0 @@
Simple example from users manual.

24
Examples/chicken/simple/example.c
View file

@ -1,24 +0,0 @@
/* Simple example from documentation */
/* File : example.c */
#include <time.h>
double My_variable = 3.0;
/* Compute factorial of n */
int fact(int n) {
if (n <= 1) return 1;
else return n*fact(n-1);
}
/* Compute n mod m */
int my_mod(int n, int m) {
return (n % m);
}
char *get_time() {
long ltime;
time(&ltime);
return ctime(&ltime);
}

16
Examples/chicken/simple/example.i
View file

@ -1,16 +0,0 @@
/* File : example.i */
%module example
%{
/* Put headers and other declarations here */
%}
%include typemaps.i
%rename(mod) my_mod;
%inline %{
extern double My_variable;
extern int fact(int);
extern int my_mod(int n, int m);
extern char *get_time();
%}

28
Examples/chicken/simple/runme.scm
View file

@ -1,28 +0,0 @@
;; feel free to uncomment and comment sections
(load-library 'example "simple.so")
(display "(My-variable): ")
(display (My-variable))
(display "\n")
(display "(My-variable 3.141259): ")
(display (My-variable 3.141259))
(display "\n")
(display "(My-variable): ")
(display (My-variable))
(display "\n")
(display "(fact 5): ")
(display (fact 5))
(display "\n")
(display "(mod 75 7): ")
(display (mod 75 7))
(display "\n")
(display "(get-time): ")
(display (get-time))
(display "\n")
(exit)

11
Examples/contract/simple_c/example.c
View file

@ -1,11 +0,0 @@
#include <stdio.h>
int Circle (int x, int y, int radius) {
/* Draw Circle */
printf("Drawing the circle...\n");
/* Return -1 to test contract post assertion */
if (radius == 2)
return -1;
else
return 1;
}

19
Examples/contract/simple_c/example.i
View file

@ -1,19 +0,0 @@
/* File : example.i */
/* Basic C example for swig contract */
/* Tiger, University of Chicago, 2003 */
%module example
%contract Circle (int x, int y, int radius) {
require:
x >= 0;
y >= 0;
radius > x;
ensure:
Circle >= 0;
}
%inline %{
extern int Circle (int x, int y, int radius);
%}

17
Examples/contract/simple_c/runme1.py
View file

@ -1,17 +0,0 @@
import example
# Call the Circle() function correctly
x = 1;
y = 1;
r = 3;
c = example.Circle(x, y, r)
# test post-assertion
x = 1;
y = 1;
r = 2;
c = example.Circle(x, y, r)
print "The return value of Circle(%d, %d, %d) is %d" % (x,y,r,c)

20
Examples/contract/simple_c/runme2.py
View file

@ -1,20 +0,0 @@
import example
# Call the Circle() function correctly
x = 1;
y = 1;
r = 3;
c = example.Circle(x, y, r)
print "The return value of Circle(%d, %d, %d) is %d" % (x,y,r,c)
# test pre-assertion
x = 1;
y = -1;
r = 3;
c = example.Circle(x, y, r)
print "The return value of Circle(%d, %d, %d) is %d" % (x,y,r,c)

30
Examples/contract/simple_cxx/example.cxx
View file

@ -1,30 +0,0 @@
#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 -1 is to test post-assertion */
if (radius == 1)
return -1;
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;
}

34
Examples/contract/simple_cxx/example.h
View file

@ -1,34 +0,0 @@
/* 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);
};

28
Examples/contract/simple_cxx/example.i
View file

@ -1,28 +0,0 @@
%module example
%contract Circle::Circle(double radius) {
require:
radius > 0;
}
%contract Circle::area(void) {
ensure:
area > 0;
}
%contract Shape::move(double dx, double dy) {
require:
dx > 0;
}
/* should be no effect, since there is no move() for class Circle */
%contract Circle::move(double dx, double dy) {
require:
dy > 1;
}
# include must be after contracts
%{
#include "example.h"
%}
%include "example.h"

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