Writing servlets in Scheme - basics

Get back to the tutorial page

Since I'd really like this tutorial to be a complete guide, we'll start with creating a new project (our servlet). First, let's go to the directory, where our project should be placed.

$ cd /path/to/the/projects/dir

Now, let's use Scheme and leftparen for the first time, in order to initiate our project:

$ mzscheme -e '(require (planet vegashacker/leftparen:5:=0/generate))' hello-world

If everything went fine, some mesages should be printed and the hello-world directory should be creates. This is the directory, where all the sources of our web app is placed. Now, let's get to this directory:

$ cd hello-world

There are many files and subdirectories here, but so far we are interested only in two files: app.scm and main.scm. The app.scm is the file, where our web application is described (all its web pages are declared). The main.scm is the file, where is the code that generates content for all the pages that our web app consists of.

A web application (web app from now on for short) is a set of web pages that can be displayed in a web browser. Therefore it's very important to understand how web browsers ask servers for data (web pages), and how they send data (forms) to servers.

After an URL address was typed in a web browser, the browser sends a GET request to server. Thus, a servlet (our web app) have to respond to this request. Let's take a look at the code of a basic servlet:


1 (define-app my-app
2   (index-page (url "/")))

(The app.scm file generated by the leftparen generator is already the same, as above. The only difference is syntax formatting of the file; in this tutorial the formatting is more readable.)


1 (define-page (index-page request)
2   (** '(p "Hello, world!")))

The main.scm above file differs slightly from the generated one. You can edit it (leaving the require line untouched), if you want. It won't change the behaviour of our web app.

The result of this servlet is simple: a "Hello, world!" text is displayed by the web browser. It's simple enough to explain basics of both servlets and leftparen.

First of all, we define our web app in the app.scm file. This line:

1 (define-app my-app

tells us, that out web app will be called my-app. (So far I can't tell you, whether this name is really important.) The next line:

2   (index-page (url "/")))

tells us, that our servlet will consist of only one page, the index-page, which will be accessed with the "/" url. In another words: if our servlet will be run on the address "http://www.my-web-app", then typing such an address (with the "/" character optional) will take us to the index-page of our servlet.

So far, so good, but that's not all. The content of our index-page is generated by the function declared in the main.scm file:

1 (define-page (index-page request)

The line above tells us, that our servlet provides a page index-page. The function gets one parameter: request. This is the request data sent by the web browser, which requested the web page from our servlet. As we can see later, this structure is quite complex and might contain various data, but for now it's enough to know only what this request is, and why it is present, although we don't use it.

The content of our web page is produced by the body of the page index-page:

2   (** '(p "Hello, world!")))

The ** is a function which allows us to easily generate HTML code1 from s-expressions.

We want our app to produce the following content:

<p>Hello, world!</p>

Therefore we provide one argument for the ** function - a list:

(p "Hello, world!")

Later on, we'll see how we can make use of unquote function in order to generate much more complicated content, but for now it's enough to use the quote function.

As you can see, our web app is really simple. And it works! :-)

Get back to the tutorial page