From: schinz@di.epfl.ch (Michel Schinz) Newsgroups: comp.lang.scheme.scsh,comp.lang.scheme,comp.unix.shell,comp.answers,news.answers Subject: Scsh (a Unix Scheme shell) FAQ Message-ID: <scsh-faq-1-868793109@di.epfl.ch> Reply-To: schinz@di.epfl.ch (Michel Schinz) Followup-To: comp.lang.scheme.scsh Organization: Ecole Polytechnique Federale de Lausanne (EPFL) Expires: Sun, 17 Aug 97 13:25:09 MET Supersedes: <scsh-faq-1-866204383@di.epfl.ch> Keywords: Scheme shell Unix programming script Posix network Summary: This posting describes scsh, a Unix shell that uses Scheme as its scripting language and has a full Posix interface, string manipulation functions, high-level network support and more. Date: 13 Jul 97 11:25:19 GMT Posted-By: auto-faq 3.3 beta (Perl 5.003) Archive-name: unix-faq/shell/scsh-faq Posting-Frequency: monthly URL: http://diwww.epfl.ch/~schinz/scsh-faq.html Frequently Asked Questions ************************** This is the scsh Frequently Asked Questions list, version 1.13, 30 June 1997. 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. Meta-questions ************** This section contains questions and answers about this FAQ, its author(s), etc. What is the aim of this FAQ? ============================ The aim of this FAQ is to provide some help and documentation to people interested in scsh, a Unix shell that uses Scheme as its scripting language. 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 anyway. What was changed recently in this FAQ? ====================================== Here is a list of recent changes. The name of the person who suggested the change (either explicitly by sending a mail, or implicitly by posting in the newsgroup) is mentioned in parentheses. 1. 1996/01/25 v0.1.1 Section about licensing terms added (Paul Wilson) 2. 1996/01/29 v0.1.2 Many many changes (Brian Carlstrom and Olin Shivers) 3. 1996/01/30 v0.1.3 Some text about 9term and wily added (Gary Capell) 4. 1996/01/31 v0.1.4 Minor syntactic changes (Pierre De Pascale) 5. 1996/01/31 v0.1.5 More information about how to contribute code (Olin Shivers) 6. 1996/02/05 v0.1.6 Section about memory problems added (Brian Carlstrom) 7. 1996/02/22 v0.1.7 RFV for comp.lang.scheme.scsh included 8. 1996/02/26 v0.1.8 Expiration date of RFV added. 9. 1996/03/05 v0.1.9 Newsgroup section updated for the new comp.lang.scheme.scsh 10. 1996/04/15 v0.1.10 Paragraph about Shriram Krishnamurthi's notes added (Shriram Krishnamurthi) 11. 1996/04/16 v0.1.11 Section about 64-bit ports updated, and reference to Scott Draves' markup system added (Olin Shivers) 12. 1996/05/06 v0.1.12 Section about networking code bug with Solaris and Irix added (Glenn Barry) 13. 1996/06/03 v1.0 Section about the incompatibilities between scsh and R4RS added; section about the module system added; some revamping; version bumped to 1.0 to celebrate our entry in the *.answers groups. 14. 1996/06/06 v1.01 Some more revamping. 15. 1996/06/14 v1.02 URL for Olin's home-page updated (Olin Shivers). 16. 1996/06/17 v1.03 Small syntax error corrected (Geoffrey S. Knauth). 17. 1996/06/19 v1.04 More syntax errors corrected (Yiorgos Adamopoulos). 18. 1996/08/26 v1.05 Another batch of syntax errors corrected, Evelyn Mitchell mentioned as working on the reference card (Evelyn Mitchell). Mention to RScheme added. 19. 1996/10/28 v1.06 Reference to the texinfo version of the R4RS added. 20. 1996/11/04 v1.07 FAQ updated for scsh 0.4.4. 21. 1996/11/15 v1.08 Mention to Mzscheme added, section about porting scsh updated (Steven Jenkins and Brian Carlstrom). 22. 1996/11/22 v1.09 Location of Scheme 48 v0.46 added (Richard Kelsey). 23. 1997/04/29 v1.10 FAQ updated for scsh 0.5.0. 24. 1997/05/01 v1.11 Section about contributing code updated (Olin Shivers), clarification about licensing terms added (Richard Kelsey), all URLs checked. 25. 1997/06/09 v1.12 FAQ slightly updated for scsh 0.5.1. Old FAQ-managment Perl scripts finally rewritten with scsh, now much less buggy (the links in the HTML version should now all be clickable). 26. 1997/06/30 v1.13 Tomas By's initialization file for SLIB mentioned (Tomas By). Where do I get the latest version of this FAQ? ============================================== The latest version of the FAQ can be found at the "scsh FAQ home-page": http://diwww.epfl.ch/~schinz/scsh-faq.html This home-page contains three versions of this FAQ: an ASCII version, an HTML version and an Info version. If you have access to the Web, I strongly recommend that you get the HTML version, since all the hyperlinks can be followed just by clicking on them. Please notice that this home-page's location may change in the (near) future. Apart from that, this document is posted on the 13th of each month in the newsgroups `comp.lang.scheme.scsh', `comp.lang.scheme', `comp.unix.shell', `comp.answers' and `news.answers'. 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 in producing a useful document by sending me suggestions and material for this FAQ. What I would especially like is finding someone with a good knowledge of English who could fix all the typos and grammatical errors that certainly lie in this document. (English is not my mother tongue, as you have guessed.) General ******* 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, it 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 Jonathan Rees and Richard Kelsey. Scsh currently includes the following features: - A complete Posix interface. - 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 manipulations, etc. - AWK-like macros. However, it is currently aimed primarily at scripting use, rather than interactive use (*Note Interactive scsh::). How do you pronounce scsh? ========================== According to Olin, scsh is pronounced "skishhhh" (it rhymes with "fish"). What is the current version of scsh? ==================================== The current version (as of 30 June 1997) is 0.5.1. What are the licensing terms for scsh? ====================================== Scsh is *not* distributed according to the GPL (General Public License) or some other well known license. Here are the exact terms, which can be found in the file `COPYING': Copyright (C) 1993, 1994 by Richard Kelsey and Jonathan Rees. Copyright (C) 1994, 1995 by Olin Shivers and Brian D. Carlstrom. Use of this program for non-commercial purposes is permitted provided that such use is acknowledged both in the software itself and in accompanying documentation. Use of this program for commercial purposes is also permitted, but only if, in addition to the acknowledgment required for non-commercial users, written notification of such use is provided by the commercial user to the authors prior to the fabrication and distribution of the resulting software. This software is provided "as is" without express or implied warranty. The following little clarification about the term `commercial use' was provided by Richard Kelsey (co-author of Scheme 48): My understanding is that `commercial use' means selling something of which Scheme 48 is a part, either as source code or as an executable. The source itself is covered by the copyright; if you use part of our source code you need to include our copyright notice. If you use part of the source code in a product you need to include the copyright notice and send us a note. 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 (*Note Getting the docs::). What is Scheme 48? ================== Scheme 48 is a small and portable Scheme implementation written by Jonathan 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, and some extensions like exceptions and a module system. 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 applications. Among other things, Scheme (and thus scsh) has serious data structures, not just strings like many scripting languages. It also has powerful control structures like continuations and, in the case of Scheme 48, exceptions. - 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) as their Unix equivalents. - Scsh is somewhat slow, especially on startup. The new static linker (introduced with v0.4.3) can however be used to solve the slow-startup problem, at the expense of higher disk consumption. Where can I get scsh? ===================== The latest version of scsh should be available at the following locations: ftp://ftp-swiss.ai.mit.edu/pub/su/scsh/scsh.tar.gz and http://www.cs.indiana.edu/scheme-repository/ . The official scsh home-page is located at: http://www-swiss.ai.mit.edu/scsh/ . 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: ftp://ftp-swiss.ai.mit.edu/pub/su/scsh/scsh-manual.ps You may also want to take a look at the technical report describing the design of scsh. It is also included in the distribution (`doc/scsh-paper.ps'), and a copy can be found at: ftp://ftp-swiss.ai.mit.edu/pub/su/scsh/scsh-paper.ps . Shriram Krishnamurthi <shriram@cs.rice.edu> also wrote some notes about using scsh, and especially the HTTP server that may be worth reading. These notes can be found at: http://www.cs.rice.edu/~shriram/Notes/Scsh/ The documentation about Scheme 48 is also worth reading. The user's guide is in the file `doc/user-guide.txt' and the documentation about the module system in `doc/module.ps'. Also, since scsh is written on top of a Scheme system, you have access to the great power of Scheme. However, no Scheme documentation is available with scsh, so you may wish to obtain the standard Scheme references as well. Here are some useful pointers: - The Scheme FAQ is maintained by Mark Kantrowitz and Barry Margolin and is available at: `http://www.cs.cmu.edu/Web/Groups/AI/html/faqs/ lang/scheme/top.html'. It is also posted regularly in the newsgroups `comp.lang.scheme', `comp.answers' and `news.answers'. - The Scheme home-page is located at: http://www-swiss.ai.mit.edu/scheme-home.html - The official specification for Scheme is "The Revised^4 Report on the Algorithmic Language Scheme", often abbreviated R4RS. This is the document you should use to look up details about Scheme. The PostScript version is available at: http://www-swiss.ai.mit.edu/ftpdir/scheme-reports/r4rs.ps . Aubrey Jaffer produced an HTML version of this document, available at: http://swissnet.ai.mit.edu/~jaffer/r4rs_toc.html . Furthermore, his version is also available as a texinfo file, which enables you to view it directly in Emacs. This version can be found at the CMU Scheme repository (*Note Scsh code archive::) in `doc/standard/rnrs/r4rs/r4rstexi.tgz'. - 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. - There are many good books about Scheme, for example: "Structure and Interpretation of Computer Programs" by Harold Abelson and Gerald Jay Sussman, MIT Press, 1985 or "Scheme and the Art of Programming" by George Springer and Daniel P. Friedman, MIT Press, 1989. For more references, see the Scheme FAQ. - The Scheme 48 home-page is located at http://www-swiss.ai.mit.edu/~jar/s48.html It contains useful information about Scheme 48, including papers describing its implementation. The home-pages of the various people involved in the design of Scheme, Scheme 48 or scsh may also be of interest to you. Here are some links: - Gerald Jay Sussman: http://www-swiss.ai.mit.edu/~gjs/gjs.html - Jonathan A. Rees: http://www-swiss.ai.mit.edu/~jar/jar.html - Richard Kelsey: http://www.neci.nj.nec.com/homepages/kelsey.html - Olin Shivers: http://www.ai.mit.edu/people/shivers/ - Brian D. Carlstrom: http://www-swiss.ai.mit.edu/~bdc/ 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). Evelyn Mitchell has recently started working on a scsh reference card. If you have ideas about items to include in it, general comments or want to help her, feel free to contact her at: <efm@tummy.com>. Which newsgroups and mailing-lists are related to scsh? ======================================================= Currently, there is a mailing-list and a newsgroup which are completely equivalent. The newsgroup used to be `alt.lang.scheme.scsh', but this has now been replaced by `comp.lang.scheme.scsh'. Please don't use the old alt group, even if it still exists at your site. To (un)subscribe to the mailing-list, send a message to <scsh-request@martigny.ai.mit.edu>. To submit a messages to the mailing-list, send it to <scsh@martigny.ai.mit.edu>. 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, Harris CXUX, HP-UX, IBM AIX, Linux, FreeBSD, NetBSD, NeXTSTEP, SGI IRIX, Solaris, and SunOS. It should also run without too many changes on other 32 bits UNIX platforms (for 64 bits platforms like Digital Unix, *Note Porting scsh::) 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 instructions. 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 in PreScheme, a dialect of Scheme, and the PreScheme compiler isn't distributed with scsh. It is, however, included in the Scheme 48 v0.46 distribution, available at: ftp://ftp.nj.nec.com/pub/kelsey/scheme48-0.46.tgz 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 48. However, you should notice that the next public release of Scheme 48 should be more 64-bits-friendly. Apart from the problems with the Scheme 48 VM, there are also some problems with scsh: the current version contains C code that assumes 32-bitness. This occurs mainly in the foreign-function interfaces (that is, interface between Scheme and C), where integers are converted between their Scheme and C representation. 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. Many alternatives to Scheme 48 would exist, but two of them are worth mentioning: 1. RScheme. RScheme, developed at the University of Texas, Austin, also has a module system (apparently similar to Scheme 48's system) and a foreign function interface (FFI). Moreover, RScheme's embryonic documentation says: "[...] we may port full scsh to RScheme". Wait and see. For more information on RScheme, see: http://www.rosette.com/~donovan/rs/rscheme.html 2. Mzscheme. Mzscheme, developed at Rice University, also has a module system and an FFI. It comes with a nice programming environment, DrScheme, which includes an editor, a graphical stepper, debugging tools and more. Steven Jenkins <sjenkins@iastate.edu> has done some work on porting scsh to this system, and his port is reported to be pretty well underway. You may want to contact him to get more information. For more information on Mzscheme, see: http://www.cs.rice.edu/CS/PLT/packages/mzscheme/index.html 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. 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. Is there some kind of "contributed code archive" for scsh? ========================================================== The following two sites may be of interest to you: 1. The contributed code directory for scsh, which is located at ftp://ftp-swiss.ai.mit.edu/pub/scsh/contrib/ Currently, this directory contains only Olin's networking code, the Functional PostScript package and Scott Draves and Jonathan Rees' markup system. 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 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 contribute some code, you should send it directly to Olin Shivers <shivers@ai.mit.edu>. You can send an URL or an uuencoded tar file. 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 (*Note Getting scsh::) which contains a list of interesting projects. 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 R4RS-compliant interpreters and scsh: Symbols in scsh are case-sensitive while this is not true for R4RS-compliant interpreters. This means, for example, that the following expression: (eq? 'symbol 'Symbol) evaluates to `#t' with an R4RS-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 (*Note Getting the docs::). There are also other extensions to R4RS 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. 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. In the meantime, a nice solution is to use a separate tool which provides some of these features. Here is a partial list of such tools: 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. 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 3. 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.su.oz.au/~gary/wily/ 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. The documentation on Scheme 48 module system can be found in the file `doc/module.ps'. 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 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 literally 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: ftp://ftp-swiss.ai.mit.edu/pub/scsh/contrib/net/ 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. 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 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'. 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. If you need examples on how to use `cig', just check out the scsh source.
Send corrections/additions to the FAQ Maintainer:
Last Update August 13 1997 @ 03:45 AM faq-admin@faqs.org