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

Doc update

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@5411 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Dave Beazley 2003-11-25 21:18:30 +00:00
commit eca80d3999
20 changed files with 760 additions and 488 deletions
Download patch file Download diff file Expand all files Collapse all files

93
SWIG/Doc/Manual/Contract.html
View file

@ -5,10 +5,18 @@
</head>
<body bgcolor="#ffffff">
<H1>Contracts</H1>
<a name="n1"></a><H1>10 Contracts</H1>
<!-- INDEX -->
<ul>
<li><a href="#n2">The %contract directive</a>
<li><a href="#n3">%contract and classes</a>
<li><a href="#n4">Constant aggregation and %aggregate_check</a>
<li><a href="#n5">Notes</a>
</ul>
<!-- INDEX -->
A common problem that arises when wrapping C libraries is that of maintaining
reliability and checking for errors. The fact of the matter is that many
C programs are notorious for not providing error checks. Not only that,
@ -24,7 +32,8 @@ check the output values of a function and more.
When one of the rules is violated by a script, a runtime exception is
generated rather than having the program continue to execute.
<H2>The %contract directive</H2>
<a name="n2"></a><H2>10.1 The %contract directive</H2>
Contracts are added to a declaration using the %contract directive. Here
is a simple example:
@ -73,7 +82,8 @@ RuntimeError: Contract violation: require: (arg1>=0)
</pre>
</blockquote>
<h2>%contract and classes</h2>
<a name="n3"></a><H2>10.2 %contract and classes</H2>
The <tt>%contract</tt> directive can also be applied to class methods and constructors. For example:
@ -143,10 +153,83 @@ In other words conditions specified for the base class and conditions
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.
<h2>Constant aggregation and %aggregate_check</h2>
<a name="n4"></a><H2>10.3 Constant aggregation and %aggregate_check</H2>
Consider an interface file that contains the following code:
<blockquote>
<pre>
#define UP 1
#define DOWN 2
#define RIGHT 3
#define LEFT 4
void move(SomeObject *, int direction, int distance);
</pre>
</blockquote>
One thing you might want to do is impose a constraint on the direction parameter to
make sure it's one of a few accepted values. To do that, SWIG provides an easy to
use macro %aggregate_check() that works like this:
<blockquote>
<pre>
%aggregate_check(int, check_direction, UP, DOWN, LEFT, RIGHT);
</pre>
</blockquote>
This merely defines a utility function of the form
<blockquote>
<pre>
int check_direction(int x);
</pre>
</blockquote>
That checks the argument x to see if it is one of the values listed. This utility
function can be used in contracts. For example:
<blockquote>
<pre>
%aggregate_check(int, check_direction, UP, DOWN, RIGHT, LEFT);
%contract move(SomeObject *, int direction, in) {
require:
check_direction(direction);
}
#define UP 1
#define DOWN 2
#define RIGHT 3
#define LEFT 4
void move(SomeObject *, int direction, int distance);
</pre>
</blockquote>
Alternatively, it can be used in typemaps and other directives. For example:
<blockquote>
<pre>
%aggregate_check(int, check_direction, UP, DOWN, RIGHT, LEFT);
%typemap(check) int direction {
if (!check_direction($1)) SWIG_exception(SWIG_ValueError, "Bad direction");
}
#define UP 1
#define DOWN 2
#define RIGHT 3
#define LEFT 4
void move(SomeObject *, int direction, int distance);
</pre>
</blockquote>
Regrettably, there is no automatic way to perform similar checks with enums values. Maybe in a future
release.
<a name="n5"></a><H2>10.4 Notes</H2>
<h2>Notes</h2>
Contract support was implemented by Songyan (Tiger) Feng and first appeared
in SWIG-1.3.20.