4. Installing and using scsh

Now that you have downloaded scsh, you might want to install and use it. Some help about this subject is provided here.

4.1 Compilation problems

Scsh should compile without problems on most Unix platforms. Particular notes:

1. On MacOS X, with scsh versions older than 0.6.0, you had to specify the host type to configure, since autoconf was not able to autodetect it; you had to include --host=powerpc-apple-bsd in the configure commandline.

2. On Linux, compiling versions older than 0.5.2 with the new version on the glibc caused problems. The 0.5.2 release notes say "problems with the signal system blowing up builds on some of the more obscure Unix systems have been fixed").

4.2 Is there a "port" of scsh for FreeBSD?

Installing scsh on FreeBSD is best done by compiling FreeBSD's scsh "port" (meaning the FreeBSD term of a port, which is an integrated third-party package) or by getting a binary "package" from a FreeBSD ftp server. The FreeBSD port is available under ports/lang/scsh.

4.3 It looks like I do not have enough memory to compile scsh?!?

If you get errors like "not enough memory" when building scsh, you may try to adjust the limits on memory usage imposed by your system. To do this, you have to use the ulimit command under sh and derivatives or the unlimit command under csh and derivatives (tcsh and the like). See the reference manual of your shell for more information.

4.4 Is there some kind of "contributed code archive" for scsh?

The following resources may be of interest to you:

1. The Scheme Untergrund Library, which collects contributed code for Scheme 48 and scsh:
   http://www.nongnu.org/sunterlib/

2. The scsh Wiki on which you can, among other things, share some code snippets http://www.scsh.net/cgi-bin/wiki.cgi
   

3. The resource page, on the scsh home page http://www.scsh.net/resources.html.

4. The scsh contributed code repository, at ftp://ftp.scsh.net/pub/scsh/contrib/, Which currently includes:
   1. sunet, an extensible web server written by Olin Shivers with extensions by Michael Sperber;

   2. Functional Postscript, which provides a Scheme interface to the Postscript page description language;

   3. A text markup system by Scott Draves and Jonathan Rees;

   4. pgscsh, a socket-level interface to the PostgreSQL object-relational DBMS, by Eric Marsden.

   Go on and send more code.

5. The various Scheme code repositories, which are all listed in the Scheme FAQ. The two main repositories are the Scheme Repository at Indiana University:
   http://www.cs.indiana.edu/scheme-repository/home.html
   and the CMU AI Repository, Scheme Section (a.k.a. the CMU Scheme Repository):
   http://www.cs.cmu.edu/Web/Groups/AI/html/repository.html.

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.

If you want to write some code for scsh but you don't know what, you might want to take a look at the scsh home-page (see section 3.8 Where can I get scsh?) which contains a list of interesting projects.

4.5 Can I use "plain" Scheme code with scsh?

Generally speaking, all of the existing Scheme code can be run without problem with scsh. There is only one possibly annoying incompatibility between R5RS-compliant interpreters and scsh: Symbols in scsh are case-sensitive while this is not true for R5RS-compliant interpreters. This means, for example, that the following expression:

(eq? 'symbol 'Symbol)

evaluates to #t with an R5RS-compliant interpreter (including the original Scheme 48), while it evaluates to #f with scsh.

In practice this shouldn't be a big problem, but if you encounter code that works perfectly with all Scheme interpreters except scsh, then this may be the reason.

If you want to know the design decision behind this choice, you should read the technical report describing the design of scsh (see section 3.9 Where can I find documentation about scsh?).

There are also other extensions to R5RS in scsh (e.g. C-like escaped characters in strings) but they shouldn't break existing Scheme code; you should have them in mind, however, when trying to write portable Scheme code under scsh.

4.6 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.

To alleviate these problems, Martin Gasbichler and Eric Knauel have written Commander S, which runs on top of scsh and provides a comfortable interactive environment. One of its novel features is that it can understand the output of many Unix commands, and allows the user to browse and manipulate it in useful ways. More information about Commander S can be found in the paper describing it:
http://www-pu.informatik.uni-tuebingen.de/users/knauel/commander-s.pdf
Instructions about how to obtain and install Commander S are available from the scsh Web site:
http://www.scsh.net/resources/commander-s.html

Another option to obtain interactive features for scsh is to run it inside a tool providing them. A partial list of such tools includes:

1. Emacs: use the `cmuscheme' package, written by Olin. It is now part of Emacs, but if you don't have it on your system, you may use the one provided with scsh, which is also a little more up-to-date (check the directory `emacs'). This mode enables you to run scsh (or any Scheme interpreter by the way) as an inferior process. It provides command-line editing, command-line history, dynamic completion, file-name completion, automatic indentation of Scheme code and more.

   If you want to give it a try right now, just type C-u M-x run-scheme, and then enter scsh at the prompt.

2. A line editor, which can run scsh as a sub-process while providing command-line editing. An example of such a tool is rlwrap, available from the following location:
   http://utopia.knoware.nl/~hlub/uck/software/
   Once installed, rlwrap can be invoked as follows to provide line editing for scsh:

   rlwrap -c -b '(){}[].,=&^%$#@\;|' scsh

3. Some terminal emulator that enables input (or output) editing. An example is the 9term terminal emulator, inspired by the Plan 9 terminal emulator. Check out 9term's home-page at:
   http://www.cs.su.oz.au/~matty/9term/index.html

4. Any text editor that can run a process in one of its windows. An example is wily (although it is more than a text editor), inspired by Plan 9's ACME tool. For more information:
   http://www.cs.yorku.ca/~oz/wily/
   The original ACME tool has also been ported to Unix:
   http://swtch.com/plan9port/

4.7 I get "undefined variable" errors when I try to use some functions?!?

If you get "undefined variable" errors when you use functions from the big-scheme package or macros like define-record, then maybe you didn't open the appropriate packages. To open them, there are two solutions:

1. use the ,open command in interactive mode, or
2. use Scheme 48's module system.

The first solution is nice for interactive work, while the second is the one to use for scripts.

Documentation on the Scheme 48 module system can be found in the Scheme 48 documentation. Olin Shivers also posted a message with further explanations to the scsh newsgroup, which is archived at http://groups.google.com/groups?selm=qijyawastzo.fsf%40lambda.ai.mit.edu.

4.8 Can I use SLIB (a Scheme library) with scsh?

Yes, provided that you get (or write) an initialization file for scsh. Tomas By wrote one that you can get there:
ftp://ftp.dcs.shef.ac.uk/home/tomas/scsh.init

By the way, more information about SLIB is available by following this URL:
http://www-swiss.ai.mit.edu/~jaffer/SLIB.html

4.9 Some basic I/O 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 I/O functions, like the test for EOF, etc. However, these functions are not documented in the scsh manual, but in the official Scheme specification (R5RS, see section 3.9 Where can I find documentation about scsh?).

4.10 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 R5RS specifies that the eof-object can't be read by the read procedure, and therefore can't be included literally in your source. However, it can be defined like that:

(define eof-object (read (make-string-input-port "")))

4.11 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:
ftp://ftp.scsh.net/pub/scsh/contrib/

4.12 I get strange errors with some network functions?!?

If you are using scsh 0.4.2 under Solaris 2 or Irix 5, and the errors you get look like:

Error: 122 "Operation not supported on transport endpoint" #{Procedure 9398 %listen}

then you should switch to a newer version of scsh: this was a known bug of scsh 0.4.2.

If, for some reason, you want to stick with v0.4.2, here is how to fix the bug:

In scsh's distribution directory, edit the file `scsh/solaris/netconst.scm' (if you are under Solaris 2 and above) or `scsh/irix/netconst.scm' (if you are under Irix 5 and above) so that the following lines:

(define socket-type/stream 1) ; stream socket (define socket-type/datagram 2) ; datagram socket (define socket-type/raw 3) ; raw-protocol interface ;;(define socket-type/rdm 4) ; reliably-delivered message ;;(define socket-type/seqpacket 5) ; sequenced packet stream

are replaced by the following lines:

(define socket-type/stream 2) ; stream socket (define socket-type/datagram 1) ; datagram socket (define socket-type/raw 4) ; raw-protocol interface ;;(define socket-type/rdm 5) ; reliably-delivered message ;;(define socket-type/seqpacket 6) ; sequenced packet stream

then recompile scsh, by running make in the main directory, and reinstall it.

4.13 How do I get the multiple values returned by a function?

This is documented in the R5RS. However, with all these continuations, the documentation might be a little hard to understand for newcomers. So here is a little (although not very useful) example that uses values and call-with-values:

(call-with-values (lambda () (values 6 7)) *) => 42

As you can see, the first argument to call-with-values is a procedure which return multiple values, and the second is a procedure which gets these multiple values as arguments.

Scheme 48 provides another syntax to access multiple values: the receive macro. This macro binds multiple values returned by an expression to variables, and then evaluates a sequence of expressions with these bindings active (for Common Lisp fans, this is similar to multiple-value-bind). Here is the above example, rewritten using receive:

(receive (x y) (values 6 7) (* x y)) => 42

For more information on this function, check out `doc/big-scheme.txt'.

While this may not be evident here, the receive macro is often easier to use than call-with-values.

4.14 How do I interface scsh with a C function?

Use the Scheme 48 facility to interface with C, documented in the Scheme 48 manual.

4.15 What is the syntax of regular expressions?

Scsh 0.5.2 introduced support for SREs, or Structural Regular Expressions. These provide an s-expression notation for building up and operating on regular expressions. See the SRE section of the manual for further details.

Standard string-based regexps are also available (and in fact SREs compile to string-based regexps). Henry Spencer's POSIX regular expression engine is used to implement the matching. The syntax accepted by this engine is described in its man page, which can be found in the scsh distribution, in file `scsh/regexp/regex.7'.

4.16 How should I handle errors?

Scsh raises exceptions instead of passing error status codes via the errno variable (this makes error handling much simpler). You can use the with-errno-handler form to handle these errors gracefully.

Certain error conditions are signalled by calls to the error primitive. If you wish to intercept these conditions gracefully you can write your own handler. The following example shows how to intercept the host-not-found condition on DNS lookup.

#!/usr/local/bin/scsh \ -dm -m whnf -e main -s !# (define-structure whnf (export main) (open scheme scsh handle) (begin (define (with-host-not-found* thunk) (call-with-current-continuation (lambda (k) (with-handler (lambda (condition next) (cond ((string-match "^name->host-info" (cadr condition)) (display "No such host") (newline) (k '())) (else (next)))) thunk)))) (define-syntax with-host-not-found (syntax-rules () ((with-host-not-found ?body ...) (with-host-not-found* (lambda () ?body ...))))) (define (main args) (with-host-not-found (host-info "foo.bar.com")))))