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

[OCaml] Some documentation improvements for %exception

Browse source 
Use the style of the Java and Python modules.

Tweak some entries in CHANGES.current.

[skip ci]
This commit is contained in:
Zackery Spytz 2019-02-12 19:43:55 -07:00
commit 506be0c28c
2 changed files with 86 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

8
CHANGES.current
View file

@ -15,8 +15,8 @@ Version 4.0.0 (in progress)
#1464 Add support for C++14 binary integer literals.
2019-02-10: ZackerySpytz
#1450 Add support for C++11 UCS-2 and UCS-4 character literals. Also add support for
C++17 UTF8 character literals.
#1450 Add support for C++11 UCS-2 and UCS-4 character literals. Also, add support for
C++17 UTF-8 character literals.
2019-02-10: wsfulton
[MzScheme] #1437 MzScheme/Racket is now an 'Experimental' language. The examples work
@ -173,7 +173,7 @@ Version 4.0.0 (in progress)
int64_t instead of int64.
2019-01-11: ZackerySpytz
[OCaml] #1400 Fix getters and setters.
[OCaml] #1400 Fix the getters and setters of non-static member variables.
2019-01-07: wsfulton
#358 Add VOID to windows.i
@ -195,7 +195,7 @@ Version 4.0.0 (in progress)
prevent accepting a conversion to a NULL pointer.
2019-01-03: ZackerySpytz
[OCaml] #1386 Fix OCaml out-of-source test-suite
[OCaml] #1386 Fix the OCaml examples and test suite for out-of-source builds.
2019-01-01: wsfulton
[Python] #639 remove duplicate proxy method definitions for global function wrappers.

85
Doc/Manual/Ocaml.html
View file

@ -991,9 +991,88 @@ values will read zero, and struct or object returns have undefined results.
<p>
Catching exceptions is now supported using SWIG's %exception feature. A simple
but not too useful example is provided by the throw_exception testcase in
Examples/test-suite. You can provide your own exceptions, too.
If an error occurs in a C or C++ function, you may want to convert that error into an OCaml
exception. To do this, you can use the <tt>%exception</tt> directive. The <tt>%exception</tt>
directive simply lets you rewrite part of the generated wrapper code to include an error check.
It is detailed in full in the <a href="Customization.html#Customization_exception">Exception handling with %exception</a> section.
</p>
<p>
In C, a function often indicates an error by returning a status code (e.g. a negative number
or a NULL pointer). Here is a simple example of how you might handle that:
</p>
<div class="code">
<pre>
%exception malloc {
$action
if (result == NULL) {
caml_failwith("Not enough memory");
}
}
void *malloc(size_t nbytes);
</pre>
</div>
<p>
In OCaml:
</p>
<div class="code">
<pre>
# let a = _malloc (C_int 20000000000);;
Exception: Failure "Not enough memory".
#
</pre>
</div>
<p>
If a library provides some kind of general error handling framework, you can also use
that. For example:
</p>
<div class="code">
<pre>
%exception {
$action
if (err_occurred()) {
caml_failwith(err_message());
}
}
</pre>
</div>
<p>
If no declaration name is given to <tt>%exception</tt>, it is applied to all wrapper functions.
<tt>$action</tt> is a SWIG special variable and is replaced by the C/C++ function call being wrapped.
</p>
<p>
C++ exceptions are also easy to handle. We can catch a C++ exception and rethrow it as
an OCaml exception like this:
</p>
<div class="code">
<pre>
%exception getitem {
try {
$action
} catch (std::out_of_range &amp;e) {
caml_failwith(e.what());
}
}
class FooClass {
public:
int getitem(int index); // Exception handling added
...
};
</pre>
</div>
<p>
The language-independent <tt>exception.i</tt> library file can also be used
to raise exceptions. See the <a href="Library.html#Library">SWIG Library</a> chapter.
</p>
<H2><a name="Ocaml_nn32">38.3 Documentation Features</a></H2>