Updates the documentation with 0.2/* changes.

Replaces stream operations on Request and Response on their respective 'body'
attributes.

Restructures the documentation:

 - move 'server/*' to 'vsgi/server/*'
 - adds index files to provide toctrees in vsgi and recipes

docs/application.rst

@@ -1,8 +1,8 @@
 Application
 ===========
 
-This document explains step-by-step the sample presented in
-:doc:`getting-started`.
+This document explains step-by-step the sample presented in the
+:doc:`getting-started` document.
 
 Choosing the VSGI implementation
 --------------------------------
@@ -14,8 +14,8 @@ a ``using`` statement, as they all respect a common interface.
 Two implementations exist at the moment and a few more are planned in a future
 minor release.
 
--  :doc:`server/soup`
--  :doc:`server/fastcgi`
+-  :doc:`vsgi/server/soup`
+-  :doc:`vsgi/server/fastcgi`
 
 .. code:: vala
 
@@ -25,12 +25,9 @@ minor release.
 Creating an application
 -----------------------
 
-An application is defined by a class that implements the ``VSGI.Application``
-interface. It declares a simple ``handle`` function that takes
-a :doc:`vsgi/request` and :doc:`vsgi/response` as input and process them.
-
-Valum provides a :doc:`router` with powerful facilities for routing client
-requests. Your application is an instance of that class.
+An application is defined by a function that respects the ``VSGI.ApplicationCallback``
+delegate. The :doc:`router` provides ``handle`` for that purpose along with
+powerful routing facilities for client requests.
 
 .. code:: vala
 
@@ -46,7 +43,7 @@ a :doc:`route` instance.
 .. code:: vala
 
     app.get ("", (req, res, next) => {
-        res.write ("Hello world!".data);
+        res.body.write ("Hello world!".data);
     });
 
 Every route declaration has a callback associated that does the request
@@ -56,29 +53,35 @@ processing. The callback receives three arguments:
 -  a :doc:`vsgi/response` that correspond to that resource
 -  a ``next`` continuation to `keep routing`
 
-These two inherit respectively from ``InputStream`` and ``OutputStream``,
-allowing any synchronous and asynchronous stream operations. You can use
-`GLib.DataOutputStream`_ or any wrapper from the GIO stream API to perform
-advanced write operations.
-
-.. _GLib.DataOutputStream: http://valadoc.org/#!api=gio-2.0/GLib.DataOutputStream
-
 Serving the application
 -----------------------
 
 This part is pretty straightforward: you create a server that will serve your
-application at port ``3003``. This will use the libsoup built-in HTTP server.
+application at port ``3003`` and since ``using VSGI.Soup`` was specified,
+``Server`` refers to :doc:`vsgi/server/soup`.
+
+.. code:: vala
+
+    new Server (app.handle).run ({"app", "--port", "3003"});
 
 Usually, you would only pass the CLI arguments to ``run``, so that your runtime
-can be parametrized easily.
+can be parametrized easily, but in this case we just want our application to
+run with fixed parameters. Common options are documented in the
+:doc:`vsgi/server/index` document.
 
 .. code:: vala
 
-    new Server (app).run ({"app", "--port", "3003"});
+    public static void main (string[] args) {
+        var app = new Router ();
+
+        // assume some route declarations...
+
+        new Server (app.handle).run (args);
+    }
 
-There is also a :doc:`server/fastcgi` implementation for a live deployment,
-although you can still deploy with libsoup if you decide to use a modern
-hosting service like `Heroku`_.
+There is also a :doc:`vsgi/server/fastcgi` implementation for a live
+deployment, although you can still deploy with libsoup-2.4 if you decide to use
+a modern hosting service like `Heroku`_.
 
 .. _Heroku: https://heroku.com
 

docs/ctpl.rst

@@ -90,5 +90,31 @@ application can produce very big output efficiently.
 
     app.get ("", (req, res) => {
         var template = new View.from_string ("");
-        template.stream (res);
+        template.stream (res.body);
+    });
+
+It is unfortunately not possible to stream with non-blocking I/O due to the
+design of CTPL. The only possibility would be to dump the template in
+a temporary ``MemoryOutputStream`` and then splice it asynchronously in the
+response body.
+
+.. code:: vala
+
+    app.get ("", (req, res) => {
+        var template = new View.from_string ("");
+        var buffer = new MemoryOutputStream.resizable ();
+
+        // blocking on memory I/O
+        template.stream (buffer);
+
+        var buffer_reader = new MemoryInputStream (buffer.data);
+
+        // non-blocking on network I/O
+        res.body.splice_async.begin (buffer_reader,
+                                     OutputStreamSpliceFlags.CLOSE_SOURCE,
+                                     Priority.DEFAULT,
+                                     null,
+                                     (obj, result) => {
+            var spliced = res.body.splice_async.end (result);
+        });
     });

docs/getting-started.rst

@@ -31,10 +31,10 @@ changes in the framework.
     var app = new Router ();
 
     app.get("", (req, res) => {
-        res.write ("Hello world!".data);
+        res.body.write ("Hello world!".data);
     });
 
-    new Server (app).run ({"app", "--port", "3003"});
+    new Server (app.handle).run ({"app", "--port", "3003"});
 
 Typically, the ``run`` function contains CLI argument to make runtime the
 parametrizable.

docs/index.rst

@@ -18,25 +18,17 @@ development. If you think that this document could be improved,
 .. _valum-framework/valum: https://github.com/valum-framework/valum
 .. _open a ticket on GitHub: https://github.com/valum-framework/valum/issues
 
-Table Of Contents
------------------
-
 .. toctree::
     :maxdepth: 2
 
     installation
     getting-started
     application
-    vsgi/request
-    vsgi/response
-    vsgi/server
-    vsgi/converters
+    vsgi/index
     redirection-and-error
     route
     router
-    recipes/static-resource
-    server/soup
-    server/fastcgi
+    recipes/index
     module
     ctpl
     persistency

docs/installation.rst

@@ -4,34 +4,54 @@ Installation
 We use the `waf build system`_ and distribute it with the sources. All you need
 is a `Python interpreter`_ to configure and build Valum.
 
+.. _waf build system: https://code.google.com/p/waf/
+.. _Python interpreter: https://www.python.org/
+
 Dependencies
 ------------
 
 The following dependencies are minimal to build the framework under Ubuntu
-12.04 LTS.
-
--  vala
--  waf
--  glib-2.0 (>=2.32)
--  gio-2.0 (>=2.32)
--  libsoup-2.4 (>=2.38)
--  libgee-0.8 (>=0.6.4)
--  ctpl (>=3.3)
-
-Recent dependencies will enable more advanced features.
-
--  gio-2.0 (>=2.40) CLI arguments parsing
--  gio-2.0 (>=2.42) uses ``add_menu_option`` to generate help with ``--help``
--  libsoup-2.4 (>=2.48) new server API
-
-You can also install additionnal dependencies to build the examples.
+12.04 LTS:
+
++-------------+----------+
+| Package     | Version  |
++=============+==========+
+| vala        | latest   |
++-------------+----------+
+| waf         | provided |
++-------------+----------+
+| glib-2.0    | >=2.32   |
++-------------+----------+
+| gio-2.0     | >=2.32   |
++-------------+----------+
+| libsoup-2.4 | >=2.38   |
++-------------+----------+
+| libgee-0.8  | >=0.6.4  |
++-------------+----------+
+| ctpl        | >=3.3    |
++-------------+----------+
+
+Recent dependencies will enable more advanced features:
+
++-------------+---------+------------------------------------------------------+
+| Package     | Version | Feature                                              |
++=============+=========+======================================================+
+| glib-2.0    | >=2.38  | subprocess in tests                                  |
++-------------+---------+------------------------------------------------------+
+| gio-2.0     | >=2.40  | CLI arguments parsing                                |
++-------------+---------+------------------------------------------------------+
+| libsoup-2.4 | >=2.48  | new server API                                       |
++-------------+---------+------------------------------------------------------+
+| libsoup-2.4 | >=2.50  | uses `Soup.ClientContext.steal_connection`_ directly |
++-------------+---------+------------------------------------------------------+
+
+You can also install additional dependencies to build the examples:
 
 -  libmemcached
 -  libluajit
 -  memcached
 
-.. _waf build system: https://code.google.com/p/waf/
-.. _Python interpreter: https://www.python.org/
+.. _Soup.ClientContext.steal_connection: http://valadoc.org/#!api=libsoup-2.4/Soup.ClientContext.steal_connection
 
 Debian and Ubuntu
 ~~~~~~~~~~~~~~~~~

docs/persistency.rst

@@ -42,7 +42,7 @@ maintained in nemequ/vala-extra-vapis GitHub repository.
         Memcached.ReturnCode error;
         var value = memcached.get ("hello", out flags, out error);
 
-        res.write (value);
+        res.body.write (value);
     });
 
     app.post ("<key>", (req, res) => {
@@ -56,5 +56,5 @@ maintained in nemequ/vala-extra-vapis GitHub repository.
         Memcached.ReturnCode error;
         var value = memcached.get ("hello", out flags, out error);
 
-        res.write (value);
+        res.body.write (value);
     });

docs/recipes/index.rst

@@ -0,0 +1,9 @@
+Recipes
+=======
+
+Recipes are documents providing approaches to common web development tasks and
+their potential integration with Valum.
+
+.. toctree::
+
+    static-resource

docs/route.rst

@@ -145,7 +145,7 @@ and optimized.
 .. code:: vala
 
     app.regex (Request.GET, /home\/?/, (req, res) => {
-        var writer = new DataOutputStream (res);
+        var writer = new DataOutputStream (res.body);
         writer.put_string ("Matched using a regular expression.");
     });
 
@@ -163,7 +163,7 @@ A matcher consist of a callback matching a given ``Request`` object.
     Route.MatcherCallback matcher = (req) => { req.path == "/custom-matcher"; };
 
     app.matcher ("GET", matcher, (req, res) => {
-        var writer = new DataOutputStream (res);
+        var writer = new DataOutputStream (res.body);
         writer.put_string ("Matched using a custom matcher.");
     });
 
@@ -175,7 +175,9 @@ fallback to a default route otherwise.
     app.matcher ("GET", (req) => {
         var user = new User (req.query["id"]);
         return "admin" in user.roles;
-    }, (req, res) => {});
+    }, (req, res) => {
+        // ...
+    });
 
     app.route ("<any:path>", (req, res) => {
         res.status = 404;

docs/router.rst

@@ -36,10 +36,10 @@ the ``application/x-www-form-urlencoded`` body of the :doc:`vsgi/request`.
 .. code:: vala
 
     app.post ("login", (req, res) => {
-        var buffer = new MemoryOutputStream (null, realloc, free);
+        var buffer = new MemoryOutputStream.resizable ();
 
         // consume the request body
-        buffer.splice (req, OutputStreamSpliceFlags.CLOSE_SOURCE);
+        buffer.splice (req.body, OutputStreamSpliceFlags.CLOSE_SOURCE);
 
         var data = Soup.Form.decode ((string) buffer.get_data ());
 
@@ -171,7 +171,7 @@ a future release.
 Subrouting
 ----------
 
-Since ``VSGI.Application`` handler is type compatible with
+Since ``VSGI.ApplicationCallback`` is type compatible with
 ``Route.HandlerCallback``, it is possible to delegate request handling to
 another VSGI-compliant application.
 

docs/scripting.rst

@@ -31,7 +31,7 @@ Lua
 
     // GET /lua
     app.get ("lua", (req, res) => {
-        var writer = new DataOutputStream (res);
+        var writer = new DataOutputStream (res.body);
 
         // evaluate a string containing Lua code
         writer.put_string (lua.do_string (
@@ -68,8 +68,8 @@ Scheme can be used to produce template or facilitate computation.
 .. code:: vala
 
     app.get ("hello.scm", (req, res) => {
-        var writer = new DataOutputStream (res);
-        res.put_string (scm.run ("scripts/hello.scm"));
+        var writer = new DataOutputStream (res.body);
+        writer.put_string (scm.run ("scripts/hello.scm"));
     });
 
 Scheme code:

docs/vsgi/index.rst

@@ -0,0 +1,35 @@
+VSGI
+====
+
+VSGI is a middleware that interfaces different web server technologies under a
+common and simple set of abstractions.
+
+For the moment, it is developed along with Valum to target the needs of a web
+framework, but it will eventually be extracted and distributed as a shared
+library.
+
+It actually supports two technologies (libsoup-2.4 and FastCGI) and more
+implementations are planned when the specification will be more stable.
+
+.. toctree::
+
+    request
+    response
+    converters
+    server/index
+
+VSGI produces process-based applications that are able to communicate with
+various HTTP servers with protocols and process their client requests
+asynchrously.
+
+The entry point of a VSGI application is type-compatible with the
+`ApplicationCallback` delegate. It is a function of two arguments:
+a :doc:`request` and a :doc:`response`.
+
+.. code:: vala
+
+    using VSGI.Soup;
+
+    new Server ((req, res) => {
+        // process the request and produce the response...
+    }).run ();