changes to documentation, comparison operators added to Value class

1 files changed, 89 insertions, 5 deletions

diff --git a/documentation/exceptions.html b/documentation/exceptions.html
index 485f0de..5d136d9 100644
--- a/documentation/exceptions.html
+++ b/documentation/exceptions.html
@@ -1,8 +1,7 @@
 <h1>Exceptions</h1>
 <p>
     PHP and C++ both support exceptions, and with the PHP-CPP library exception
-    handling between these two languages has become completely transparent -
-    which could very well be the coolest feature of the PHP-CPP library.
+    handling between these two languages has become completely transparent.
     Exceptions that you throw in C++ are automatically passed on to the PHP
     script, and exceptions thrown by PHP scripts can be caught by your C++
     code as if it was a plain C++ exception.
@@ -47,11 +46,96 @@ try
     echo(myDiv(10,2)."\n");
     echo(myDiv(8,4)."\n");
     echo(myDiv(5,0)."\n");
+    echo(myDiv(100,10)."\n");
 }
 catch (Exception $exception)
 {
-    echo($exception);
+    echo("exception caught\n");
 }
-&gt;
+?&gt;
 </code></pre>
-</p>
\ No newline at end of file
+</p>
+<p>
+    The output of this script is as follows:
+</p>
+<p>
+<pre>
+5
+2
+exception caught
+</pre>
+</p>
+<p>
+    The example shows how amazingly simple it is to throw exceptions from your
+    C++ code, and catch them in your PHP script. Just as if you're not even
+    working in two different languages at the same time, you can simply throw
+    a Php::Exception object, and catch it in the PHP script.
+</p>
+<h2>Catching exceptions in C++</h2>
+<p>
+    But it works the other way around too. If your extensions calls a PHP 
+    function, and the function happens to throw an exception, you can catch it
+    just as if it was a normal C++ exception. 
+</p>
+<p>
+<pre class="language-c++"><code>#include &lt;phpcpp.h&gt;
+
+Php::Value callMe(Php::Parameters &params)
+{
+    // prevent that exceptions bubble up
+    try
+    {
+        // call the function that was supplied by the user
+        return params[0]();
+    }
+    catch (Php::Exception &exception)
+    {
+        return "Exception caught!";
+    }
+}
+
+extern "C" {
+    PHPCPP_EXPORT void *get_module() {
+        static Php::Extension extension("my_extension", "1.0");
+        extension.add("callMe", callMe, {
+            Php::ByVal("callback", Php::Type::Callable, true)
+        });
+        return extension;
+    }
+}</code></pre>
+</p>
+<p>
+    This code calls for explanation. As we've mentioned before, a Php::Value object can
+    be used just like a normal PHP $variable is used, and you can thus store 
+    integers, strings, objects, arrays, et cetera in it. But this also means
+    that you can use it to store functions - because PHP variables can 
+    be used to store function too! And that's exactly what we're doing here.
+</p>
+<p>
+    The callMe() function from this example extension receives one single
+    parameter: a callback function that it will immediately call, and whose
+    return value is returned. If this callback function (which was supplied by
+    the user) throws an exception, it is detected by the callMe() function, and
+    it will return an alternative string ("Exception caught!") in stead.
+</p>
+<p>
+<pre class="language-php"><code>
+&lt;?php
+
+// call "callMe" for the first time, and supply a function that returns "first call"
+echo(callMe(function() {
+    return "first call";
+}));
+
+// call "callMe" for the second time, but throw an exception this time
+echo(callMe(function() {
+    throw new Exception("Sorry...");
+    return "second call";
+}));
+</code></pre>
+</p>
+<p>
+    This PHP script uses our extension and calls the callMe() function two times
+    in a row. First with a normal function that returns a string, but then with
+    a function that throws an exception - which will be caught by the extension.
+</p>