Here follows a little FAQ for Scsh that I have written. This is the
first release and it is *far* from perfect, so I would *really*
appreciate corrections, comments and suggestions.
Since this group isn't really filled with frequently asked questions,
those included here are mainly questions that I asked myself when I
was discovering Scsh. Also, some questions that I remeber seeing in
this group are included. Since this group isn't archived, however,
there may be some errors due to my bad memory.
This FAQ is aimed at someone who is discovering Scsh and Scheme. I
doubt that the seasoned Scheme programer will find anything useful
here, but I would be glad if he could check what I've written.
Frequently Asked Questions
This is the Scsh Frequently Asked Questions list, version 0.1.0, 23
This article is provided as is without any express or implied
warranties. While every effort has been taken to ensure the accuracy of
the information contained in this article, the maintainer assumes no
responsibility for errors or omissions, or for damages resulting from
the use of the information contained herein.
This section contains questions and answers about this FAQ, its
What is the aim of this FAQ?
The aim of this FAQ is to provide some help and documentation to
people interested in Scsh. It is mainly aimed towards those who do not
know much about Scsh or Scheme. This explains why some questions that
might seem trivial to the seasoned Scheme programmer are included
What was changed recently in this FAQ?
Nothing, this is the first release.
Where do I get the latest version of this FAQ?
The latest version of the FAQ can be found at the following place:
Please notice that this may change in the (near) future.
Where do I send comments about this FAQ?
Comments about this FAQ should be sent to the following address:
<Michel.Schinz@di.epfl.ch>. Please include the words `scsh FAQ' in the
subject to help me sort your mail.
Please help me producing a useful document by sending me suggestions
and material for this FAQ.
This section contains general questions about Scsh: what is it,
where to find it, etc.
What is Scsh?
Scsh is a Scheme shell. That is, a Unix shell which uses Scheme as
its scripting language. It was designed and written by Olin Shivers and
Brian Carlstrom, and is built on top of Scheme 48, an implementation of
Scheme written by Johnatan Rees and Richard Kelsey.
Scsh currently includes the following features:
- An almost complete Posix interface (only signals are missing).
- A very complete support for networking, with high and low level
interfaces. An additional network package, including an HTTP
server, SMTP support, etc. is also available separately.
- Powerful string manipulation functions: pattern matching, file-name
- AWK-like macros.
However, it is currently not practically usable as an interactive
shell, due to its lack of "interactive features" (*Note Interactive
What is the current version of Scsh?
The current version is 0.4.2.
What is Scheme?
Scheme is a small and elegant programming language of the Lisp
family, originally designed by Guy Lewis Steele Jr. and Gerald Jay
Sussman. It includes powerful features like first-class procedures and
continuations, and is statically scoped (like Pascal). For more
information, refer to the Scheme FAQ.
What is Scheme 48?
Scheme 48 is a small and portable Scheme implementation written by
Johnatan Rees and Richard Kelsey. It is based on a virtual machine
architecture (i.e. it does not compile to native code).
Scheme 48 implements all the features described in R4RS (*Note
Getting the docs::) as well as new features from the forthcoming R5RS.
How does Scsh compare to other scripting languages, like Perl?
It is always hard to compare programming languages objectively.
However, here are the main differences between Scsh and its "rivals"
(both positive and negative differences are included):
- Scsh is based on a well-designed and general programming language
(Scheme) that has been developed over many years. Thus, Scsh is a
general programming tool, not a quickly hacked tool with limited
- The interface to Unix functions has been well designed: the names
are consistent, and their behavior is "Scheme-like". For example,
system calls do not use the `errno' global variables to signal
errors, but raise exceptions instead.
This approach is fundamentally different from, say, the Perl
approach, where functions have the same name (often cryptic) and
behavior (often strange) than their Unix equivalents.
- Scsh is somewhat slow, especially on startup. This should be fixed
in future versions, however.
Where can I get Scsh?
The latest version of Scsh should be available at the following
The official Scsh home-page is located at:
Where can I find documentation about Scsh?
The main documentation about Scsh is the Scsh manual. It is included
in the distribution: the ready-to-print PostScript is in
`doc/scsh-manual.ps' and the LaTeX source in `doc/scsh-manual'.
Moreover, a copy of the PostScript file is available at:
You may also want to take a look at the technical report describing
the design of Scsh. It is a little old, but interesting anyway. It is
also included in the distribution (`doc/scsh-paper.ps'), and a copy can
be found at:
Also, since Scsh is written on top of a Scheme system, you also have
access to the great power of Scheme. However, no Scheme documentation is
available with Scsh, so you'll have to find it yourself. Here are some
- The Scheme FAQ is maintained by Mark Kantrowitz and Barry Margolin
and is available at:
It is also posted regularly in the newsgroups `comp.lang.scheme'
- The official specification for Scheme (The Revised^4 Report on the
Algorithmic Language Scheme, often abbreviated R4RS) can be found
Aubrey Jaffer produced an HTML version of this document, available
- An article describing the extensions to be included in the future
report on Scheme (R5RS) is available in `doc/meeting.ps'. This
article describes, among other things, multiple return values,
which are used by some of Scsh's functions.
- The Scheme 48 home-page is located at
It contains useful information about Scheme 48, including papers
describing its implementation.
Is there some kind of reference card for Scsh?
Not exactly. There is a small list of all of Scsh's functions in the
file `doc/cheat.txt'. However, it would be great to have a nice
TeXified reference card, which would include R4RS functions as well
(you know, something like the great Perl reference card). If I can find
some time, I'll do it, but if *you* have some time, just go ahead and
type it. I'm sure it would be useful to a lot of people.
Which newsgroups and mailing-lists are related to Scsh?
Currently, there is a mailing-list and a newsgroup which are
The newsgroup is currently `alt.lang.scheme.scsh'. However, in a few
weeks, a new group should be created, and should be named
To (un)subscribe to the mailing-list, send a message to
<email@example.com>. To submit a messages to the
mailing-list, send it to <firstname.lastname@example.org>.
Also, `comp.lang.scheme', which talks about Scheme in general, may
be of interest to you.
And if Scheme is your first functional language, you might also want
to read `comp.lang.functional'.
Does Scsh run on my system?
Currently, Scsh runs without modification on the following systems:
DEC Ultrix, HP-UX, IBM AIX, Linux, NetBSD/i386, NeXTSTEP, SGI IRIX,
Solaris, and SunOS. It should also run without too many changes on
other 32 bits platforms.
Is Scsh easy to port?
On 32 bits machines, yes, usually. If your system isn't already
supported, take a look at the file `doc/install.txt' which contains
Porting Scsh to 64 bits machines (or, more generally, non-32 bits
machines) is currently harder. The main reason is that this requires
modifications to the Scheme 48 virtual machine (VM). This VM is written
is PreScheme, a dialect of Scheme, and the PreScheme compiler isn't
widely available: you should ask it directly to Richard Kelsey
<email@example.com>. In any case, never try to hack the C code
generated by the PreScheme compiler (file `scheme48vm.c'), this is ugly
and you'll have to restart from scratch for the next release of Scheme
Anyway, according to a message Olin wrote in `alt.lang.scheme.scsh',
Kelsey and his team are working on a port for the Alpha. Wait and see.
Can I run Scsh under some other Scheme implementation?
Currently, Scsh is tightly bound to Scheme 48 because it uses two
non-standard features of Scheme 48: its module system and its foreign
function interface. This does not mean that porting it to another Scheme
implementation is impossible, but it is certainly hard.
Is there some kind of "contributed code archive" for Scsh?
The following sites may be of interest to you:
1. The contributed code directory for Scsh, which is located at
Currently, this directory contains only Olin's networking code. So
please go on, and send more code.
2. The various Scheme code repositories, which are all listed in the
Scheme FAQ. The two main repositories are the Scheme Repository at
and the CMU AI Repository, Scheme Section:
Also, some useful code is included with Scheme 48 (hash tables
support, sorting functions, etc.) in the Big Scheme module. Please
notice that you will have to open the module before being able to
access its functions. For additional information, check the file
`doc/big-scheme.txt' in the Scsh distribution.
Now that you've installed Scsh on your system, you might want to know
how to use it. That's the aim of this section.
Can I use Scsh as an interactive shell?
Well, technically you can: just run the "scsh" command and you will
enter a Scheme 48 session with all Scsh functions available. However,
this is definitely not suitable for interactive work: there is no
command-line editing, no command-line history, no file/function name
completion, no terse syntax, etc. All these features are planned, and
Olin has a design for much of them. However, nobody found the time to
implement them yet.
Some basic IO functions (like EOF testing) seem not available in Scsh?!?
Don't forget that Scsh is built on top of Scheme. Therefore, you have
access to the full power of Scheme in Scsh, and that includes some basic
IO functions, like the test for EOF, etc. However, these functions are
not documented in the Scsh manual, but in the official Scheme
specification (R4RS, *Note Getting the docs::).
How can I return the eof-object?
Some functions and macros (like the nice AWK macro) take a reader
function as an argument. This reader function is required to return the
eof-object at the end of the input. This is easy when the input is a
port, but much harder when the input is something else (like a list of
lines, etc.). The reason is that R4RS specifies that the eof-object
can't be read by the `read' procedure, and therefore can't be included
in your source. However, it can be defined like that:
(define eof-object (read (make-string-input-port "")))
Is there support for protocols like HTTP, SMTP, etc.?
Yes, but it isn't included in the Scsh distribution. You will find
it in the contributed code directory for Scsh:
How do I get the multiple values returned by a function?
This is documented in the file `doc/meeting.ps' (this is *not*
documented in the R4RS). However, with all these continuations, the
documentation might be a little hard to understand for newcomers. So
below is a little program fragment that uses the `parse-file-name'
function, which return multiple values: the directory, file and
extension component of a file name (see the Scsh manual for more
information). The three parts are simply displayed on the standard
output port using the R4RS procedure `display', each on its own line.
(lambda () (parse-file-name "/users/schinz/scsh/test.scm"))
(lambda (dir name extension)
(display dir) (newline)
(display name) (newline)
(display extension) (newline)))
As you can see, the first argument to `call-with-values' is a
procedure of no arguments which returns multiple values. These values
are simply passed as arguments to the second procedure.
On the other hand, you could define an alternate syntax that is
somewhat easier to read. Here is for example a macro called
`multiple-value-bind' (borrowed from Common Lisp) that does exactly
((multiple-value-bind (val ...) vals body ...)
(call-with-values (lambda () vals)
(lambda (val ...) body ...)))))
The first argument to `multiple-value-bind' should be a list of
variables to bind, and the second argument should be an expression
returning multiple values. There should be as many variables in the
list as values returned by the expression. The remaining arguments of
`multiple-value-bind' (which should be expressions) are evaluated with
the variables bound to the values.
For example, with this definition, the above code could be rewritten
(dir name extension) (parse-file-name "/users/schinz/scsh/test.scm")
(display dir) (newline)
(display name) (newline)
(display extension) (newline))
It's up to you to choose which syntax you like best.
How do I interface Scsh with a C function?
You should use the `cig' program, written by Olin Shivers. It is a
nice C interface generator. The program and its documentation are
included in the `cig' directory.