[Chicken-users] Chicken Gazette - Issue 8

[Moritz Heidkamp]

     _/_/_/  _/        _/            _/
  _/        _/_/_/          _/_/_/  _/  _/      _/_/    _/_/_/
 _/        _/    _/  _/  _/        _/_/      _/_/_/_/  _/    _/
_/        _/    _/  _/  _/        _/  _/    _/        _/    _/
 _/_/_/  _/    _/  _/    _/_/_/  _/    _/    _/_/_/  _/    _/

--[ Issue 8 ]-------------------------------------- G A Z E T T E
                               brought to you by the Chicken Team


== 0. Introduction

Welcome to issue 8 of the Chicken Gazette!

== 1. The Hatching Farm - New Eggs & The Egg Repository

It has been a good week for the egg repository, although it was one in
a long time which did not have any new eggs. We mainly saw a few bug
fix releases (getopt-long 1.9, dict 1.4, pstk 1.1 and colorize 0.3),
as well as some releases introducing new features:

linenoise 0.4

  Christian Kellermann added the handy procedure
  `make-linenoise-port`. This makes `linenoise` a viable alternative
  to the `readline` egg to be used as the `current-input-port` in
  `csi`.

libsvm 0.2

  Peter Lane new egg has already been bumped to version 0.2 making
  Chicken the first programming language which allows you to be honest
  and humble about your programming skills by means of the newly
  introduced `make-problem` procedure.

hyde 0.10

  The latest release of the website compiler powering the Chicken
  Gazette adds a few handy features, including on-demand
  re-compilation for `hyde serve` (see the change log at
  http://wiki.call-cc.org/egg/hyde#change-log for more).

== 2. The Core - Bleeding Edge Development

Core development has been pretty quiet this week with only a little
activity on the experimental branch. The most visible change is the
addition of a blob literal syntax by Felix Winkelmann.

== 3. Chicken Talk

John Gabriele pointed out a few problems with the code colorization on
the wiki which have been addressed and fixed by Peter Bex and Moritz
Heidkamp. Thanks John!

Christian Kellermann suggested to try the relatively new DVCS fossil
by giving a quick introduction, a few useful links as well as
providing a fossil clone of the chicken-core git repository for us to
play with. Definitely worth checking out!

Most importantly, Peter Bex appealed to all egg authors to document
their undocumented eggs. He was even kind enough to compile a list of
affected eggs. Fellow egg authors, let's remedy those gaps!

== 4. Omelette Recipes - Tips and Tricks

This week I'd like to direct your attention at our web server
Spiffy. Its feature set is comparable to that of the Apache HTTP
Server or lighttpd, although it doesn't sport as many extension
modules (yet). While that may seem intimidating at first, it actually
isn't: Since Spiffy is a Scheme web server, no idiosyncratic
configuration file format is needed to set it up, all you need is a
few s-exprs to get going! Let's start with a simple example:

    (use spiffy)
    
    (vhost-map `(((* any) . ,(lambda (continue)
                            (send-response body: "hey there!\n"
                                           headers: '((content-type 
text/plain)))))))
    
    (start-server port: 12345)

Alright, what does that mean? The `vhost-map` thing may look a little
odd at first. It is necessary because Spiffy has been built from the
ground up to support virtual hosting. The `vhost-map` parameter is
just an alist of hostnames to handlers. Hostnames are given as regular
expressions (either traditional or SREs). In the example we just
define a handler for `(* any)`, i.e. we use the same handler for all
hostnames.

The handler procedure is called whenever a request for the matching
hostname is to be handled. In the example, we always send a static
plain text response regardless of what the request was using the
convenience function `send-response` (let's ignore the `continue`
argument for the moment). Execute the code using `csi` to make Spiffy
listen on TCP port 12345. Try it like this:

       $ curl 'http://localhost:12345/'
       hey there!

Or with a more complex URI, inspecting the response headers:

       
       $ curl -D - 'http://localhost:12345/foo/bar?baz'   
       HTTP/1.1 200 OK
       Content-Type: text/plain
       Server: Spiffy/4.8 (Running on Chicken 4.6.0)
       Content-Length: 11
       Date: Mon, 18 Oct 2010 13:06:39 GMT
       
       hey there!
       

Very well! Now, usually a handler would inspect the `current-request`
parameter (which holds an intarweb request record representing the
currently handled request) to determine how to respond. Let's try to
change our handler so that it only sends `"hey there"` when the path
`/hey` is requested.  Otherwise, we'd like to serve files from a
certain directory (say `/var/www`) or, if no such file exists, send a
`404` response. This is how it can be done:

    (use spiffy uri-common intarweb)
    
    (root-path "/var/www")
    
    (vhost-map `(((* any) . ,(lambda (continue)
                               (if (equal? (uri-path (request-uri 
(current-request))) 
                                           '(/ "hey"))
                                   (send-response body: "hey there!\n"
                                                  headers: '((content-type 
text/plain)))
                                   (continue))))))
    
    (start-server port: 12345)

As you can see, we now need intarweb and uri-common to be able to
inspect `current-request`. We also set the `root-path` which is akin
do Apache's `DocumentRoot` directive. Since it is a paramter, it can
be easily altered by handlers using `paramterize`. The handler itself
is only slightly more complicated now: We check whether
`current-request`'s `uri-path` is `(/ "hey")` (`uri-common`'s way of
representing the path `/hey`) and if so just the response as
before. For any other path we call the `continue` procedure which is
passed to our handler. This tells Spiffy "I am done with that request,
please pass control on to the next handler". As it happens, the next
handler is Spiffy's file system handler which will just take the
`uri-path`, check whether it exists under the current `root-path` and
then delivers the file. If the path doesn't exist, a `404` response is
sent.

If you need more control over the response, you might want to augment
`current-response` (which is, of course, an intarweb response record)
directly instead of using `send-response`.

Spiffy ships a few more useful handlers (see
http://wiki.call-cc.org/egg/spiffy#modules) which you can easily
integrate into your own application. There's also an egg providing a
directory listing handler as well as several eggs that may help you
creating more advanced applications such as spiffy-request-vars,
spiffy-cookies, spiffy-uri-match and http-session.

For real-world uses check out the Spiffy based image gallery
application phoghorn (http://wiki.call-cc.org/eggref/4/phoghorn),
qwiki (http://wiki.call-cc.org/egg/qwiki, the wiki software powering
the Chicken wiki) and, of course, the infamous `awful` web framework
(http://wiki.call-cc.org/eggref/4/awful).

You should now hopefully be able to create your own web applications
with Chicken. Have fun!

== 5. About the Chicken Gazette

The Gazette is produced weekly by a volunteer from the Chicken community.
The latest issue can be found at http://gazette.call-cc.org or you can
follow it in your feed reader at http://gazette.call-cc.org/feed.atom.
If you'd like to write an issue, check out the instructions
(http://bugs.call-cc.org/browser/gazette/README.txt) and come and find
us in #chicken on Freenode!

[ --- End of this issue --- ]