Starting a wisp project

Begin by installing Guile 2.0 or later and downloading wisp-0.9.5 or later. Then unpack wisp within your project and get the language folder:

mkdir PROJ
cd PROJ
tar xf wisp*.tar.gz
cp -r wisp*/language language

Now your project is prepared. You can already experiement with wisp by calling

guile -L .

Then try the following:

,L wisp
define : hello world
__       cons 'Hello world
hello 'Eris .

That’s it. You just ran your first wisp code. The first line is a meta-command which switches to the language wisp (discovered via ./language/wisp/spec.scm).

But you won’t only want to run interactively. You’ll also want to build tools — to use wisp in your programs.

To get that, exit the REPL (the interactive read-eval-print-loop you’re running right now) with CTRL-D, then create a text file named hello. To execute it via Guile with wisp via ./hello, you can use shell indirection. Start the file with the following header.¹

#!/bin/sh
# -*- wisp -*-
# precompile the wisp spec
guile -L "$(dirname "$0")" \
      -c '(import (language wisp spec))'
# run your file via wisp
exec guile -L "$(dirname "$0")" \
           -x '.w' --language wisp \
           -s "$0" "$@"
# the sh indirection header ends here !#

Then call chmod +x hello. This allows you to run wisp code directly; if you install wisp systemwide, you can leave out the pre-compilation step.

Let’s discuss how the header works.

• The first line (#!/bin/sh) tells Unix to run the file through the shell.
• The second line (# -*- wisp -*-) tells your editor to use the wisp mode.
• The third and fourth line precompile the wisp spec with the scheme language.
• The fifth and sixth line execute the file as wisp in a new process and switch to that process. The shell won’t see any further lines. We’ll go in depth through that file after finishing the header.
• The seventh line is never seen by the shell (thanks to exec). It ends in !#, the terminator for a multi-line comment in Guile; the comment started with the hashbang line (#!/bin/sh).

Now for line number 6: The line which runs this script as wisp:

exec guile -L "$(dirname "$0")" \
           -x '.w' --language wisp \
           -s "$0" "$@"

• exec ends the shell script after calling its arguments.
• guile uses Guile from the environment.
• -L "$(dirname "$0")" tells Guile to add the directory with the script “to the front of the module load path” (quoted from guile -h ).
• -x .w adds ".w" to the front of the load extensions, so guile will consider .w files for loading. This allows writing modules in wisp.
• --language wisp switches to using wisp as language.
• -s "\(0" "\)@" runs this script with the arguments given to ./hello.

By adding this header, you can write working scripts like the following:

import : only (srfi srfi-1) second

display "Hello "
display
  if : pair? : cdr : command-line
     second : command-line
     . "World"
display "!"
newline 

Call this file hello, then run ./hello Eris.

If you later want to re-use parts of your scripts, you can move them into modules. Create a file hello.w.

One advantage is that this often starts much faster because it can skip processing the source and jump right to the bytecode.

The module-header looks just like the previous header, except for the following exec-line:²

exec -a "$0" guile -L "$(dirname "$0")" \
                   -L "$(dirname "$0")" \
                   -x '.w' --language wisp \
                   -e '('"$(basename "$0" .w)"')' \
                   -c '' "$@"

The body defines a module and wraps the parts to execute in a main procedure.

define-module : hello
    . #:export : main say-hello

import : only (srfi srfi-1) second

define : say-hello world
    display "Hello "
    display world
    display "!"
    newline 

define : main args
  say-hello
    if : pair? : cdr args
       second args
       . "World"

You can now call this file as ./hello.w Eris, but also import the say-hello procedure from another file. For a version with included module-header, see the complete example: htmlo.w.

You can now import say-hello only by using

import : only (hello) say-hello

or import all exported symbols with

import : hello

Let’s do that as a final example. Call the file htmlo.w.

#!/bin/sh
# -*- wisp -*-
# precompile the wisp spec
guile -L "$(dirname "$0")" \
      -c '(import (language wisp spec))'
# run your file via wisp
exec -a "$0" guile -L "$(dirname "$0")" \
                   -L "$(dirname "$0")" \
                   -x '.w' --language wisp \
                   -e '('"$(basename "$0" .w)"')' \
                   -c '' "$@"
# the sh indirection header ends here !#

define-module : htmlo
    . #:export : main htmlo

import : hello

define : say-htmlo world
    display "<html><head><title>"
    say-hello world
    display "</title></head><body>"
    say-hello world
    display "</body></html>"
    newline 

;; this main replaces the imported one
define : main args
  say-htmlo
    if : pair? : cdr args
       car : cdr args
       . "World"

And that is it: Your first full-fledged wisp project!

You can find more information about Wisp on its website: http://draketo.de/english/wisp

For day-to-day programming, refer to the Guile Reference manual, either online or via your friendly info reader (in Emacs that’s C-h i m Guile, in the terminal it’s info Guile). Some basic tasks in Guile are explained in Guile basics and py2guile.

Thank you for reading, and Happy Hacking!

With Guise and Guile

License: cc by-sa