home *** CD-ROM | disk | FTP | other *** search
/ ftp.pasteur.org/FAQ/ / ftp-pasteur-org-FAQ.zip / FAQ / unix-faq / shell / scsh-faq < prev    next >
Encoding:
Internet Message Format  |  2004-05-13  |  40.0 KB

  1. Path: senator-bedfellow.mit.edu!bloom-beacon.mit.edu!news2.telebyte.nl!fr.ip.ndsoftware.net!newsfeed.freenet.de!eusc.inter.net!news.imp.ch!news.imp.ch!80.83.46.147.MISMATCH!news.alphanet.ch!alphanet.ch!not-for-mail
  2. From: schinz@alphanet.ch (Michel Schinz)
  3. Newsgroups: comp.lang.scheme.scsh,comp.lang.scheme,comp.answers,news.answers
  4. Subject: Scsh (a Unix Scheme shell) FAQ
  5. Supersedes: <scsh-faq-1-1081841402@alphanet.ch>
  6. Followup-To: comp.lang.scheme.scsh
  7. Date: Thu, 13 May 2004 07:30:02 +0000 (UTC)
  8. Organization: Alphanet NF
  9. Lines: 976
  10. Approved: news-answers-request@MIT.EDU
  11. Distribution: world
  12. Expires: Thu, 17 Jun 04 09:30:02 MET
  13. Message-ID: <scsh-faq-1-1084433402@alphanet.ch>
  14. Reply-To: schinz@alphanet.ch (Michel Schinz)
  15. NNTP-Posting-Host: localhost
  16. X-Trace: shakotay.alphanet.ch 1084433404 8850 127.0.0.1 (13 May 2004 07:30:04 GMT)
  17. X-Complaints-To: usenet@alphanet.ch
  18. NNTP-Posting-Date: Thu, 13 May 2004 07:30:04 +0000 (UTC)
  19. Summary: This posting describes scsh, a Unix shell that uses Scheme
  20.      as its scripting language and has a full Posix interface,
  21.      string manipulation functions, high-level network support
  22.      and more.
  23. Keywords: Scheme shell Unix programming script Posix network
  24. Xref: senator-bedfellow.mit.edu comp.lang.scheme.scsh:3732 comp.lang.scheme:59725 comp.answers:57138 news.answers:271214
  25.  
  26. Posted-By: auto-faq 3.3 (Perl 5.006)
  27. Archive-name: unix-faq/shell/scsh-faq
  28. Posting-Frequency: monthly
  29. URL: http://www-internal.alphanet.ch/~schinz/scsh-faq.html
  30.  
  31. Frequently Asked Questions
  32. **************************
  33.  
  34.    This is the scsh Frequently Asked Questions list of 14 March 2004.
  35.  
  36.    This article is provided as is without any express or implied
  37. warranties.  While every effort has been taken to ensure the accuracy of
  38. the information contained in this article, the maintainer assumes no
  39. responsibility for errors or omissions, or for damages resulting from
  40. the use of the information contained herein.
  41.  
  42. Meta-questions
  43. **************
  44.  
  45.    This section contains questions and answers about this FAQ, its
  46. authors, etc.
  47.  
  48. What is the aim of this FAQ?
  49. ============================
  50.  
  51.    The aim of this FAQ is to provide some help and documentation to
  52. people interested in scsh, a Unix shell that uses Scheme as its
  53. scripting language.  It is mainly aimed towards those who do not know
  54. much about scsh or Scheme.  This explains why some questions that might
  55. seem trivial to the seasoned Scheme programmer are included anyway.
  56.  
  57. Who wrote this FAQ?
  58. ===================
  59.  
  60.    Most of the FAQ was written and is still maintained by Michel Schinz
  61. (<schinz@alphanet.ch>) and Eric Marsden (<emarsden@laas.fr>). To send
  62. mail about the FAQ in general, please do not use these personal
  63. addresses, but the alias mentioned below (*note Contact::).
  64.  
  65. What was changed recently in this FAQ?
  66. ======================================
  67.  
  68.    Here is a list of recent changes.  The name of the person who
  69. suggested the change (either explicitly by sending a mail, or
  70. implicitly by posting in the newsgroup) is mentioned in parentheses.
  71.  
  72.   1. 2000/02/29 v2.16 language comparisons, example error handler,
  73.      mention guile-scsh.
  74.  
  75.   2. 2000/08/28 v2.17 binary RPMs for linux distributions, s48.org.
  76.  
  77.   3. 2000/09/05 v2.18 Olin Shivers' e-mail/web page location updated,
  78.      authors section added, history shortened, regexp section updated.
  79.  
  80.   4. 2000/12/22 v2.19 win32 binaries
  81.  
  82.   5. 2001/01/15 v2.20 HTML versions of the scsh manual/paper mentioned
  83.      (Dorai Sitaram).
  84.  
  85.   6. 2001/05/28 v2.21 building on MacOS X, Sourceforge site.
  86.  
  87.   7. 2001/06/08 v2.22 scsh version 0.5.3 released.
  88.  
  89.   8. 2001/06/14 v2.23 section about the guile port updated (Paul
  90.      Emsley).
  91.  
  92.   9. 2001/07/02 v2.24 Matthias Radestock's Scheme FAQ mentioned, URL for
  93.      R5RS updated.
  94.  
  95.  10. 2001/09/06 v2.25 fix Wily URL (Bengt Kleberg)
  96.  
  97.  11. 2001/10/19 v2.26 added Martin Gasbichler among the scsh authors,
  98.      referenced his bugs page.
  99.  
  100.  12. 2002/01/10 v2.27 updates for the 0.6 release, http://www.scsh.net,
  101.      Mike Sperber added among the authors.
  102.  
  103.  13. 2002/02/04 v2.28 improved perl code, thanks to John W. Krahn.
  104.  
  105.  14. 2002/02/26 v2.29 minor update for scsh 0.6.1.
  106.  
  107.  15. 2002/03/20 v2.30 Python example corrected (Beni Cherniavksy)
  108.  
  109.  16. 2002/05/20 v2.31 minor update for scsh 0.6.2.
  110.  
  111.  17. 2002/05/24 v2.32 URL for Windows binary updated (Reini Urban)
  112.  
  113.  18. 2002/06/21 v2.33 Mentioned Cash (partial scsh port to OCaml).
  114.  
  115.  19. 2002/08/16 v2.34 Fix exception-handling example, include OpenBSD in
  116.      the list of supported platforms, update the FreeBSD ports
  117.      information.
  118.  
  119.  20. 2002/12/17 v2.35 Rewrote the part about MzScheme (Paul Steckler)
  120.  
  121.  21. 2003/01/13 v2.36 minor update for scsh 0.6.3.
  122.  
  123.  22. 2003/02/12 rewrote part comparing scsh with other scripting
  124.      languages (Yoann Padioleau), added Ruby script, updated scsh
  125.      license, removed reference to CIG, dropped version numbers for
  126.      this FAQ.
  127.  
  128.  23. 2003/02/14 removed broken and outdated link to notes on the scsh
  129.      Web sever, added reference to the "new" Scheme 48 documentation
  130.      (Michael Sperber), changed home pages of Rees and Kelsey.
  131.  
  132.  24. 2003/02/18 corrected scsh example script to include dot files
  133.      (Sriram Thaiyar).
  134.  
  135.  25. 2003/03/13 added reference to Sunterlib (Anthony Carrico).
  136.  
  137.  26. 2003/04/22 minor update for scsh 0.6.4.
  138.  
  139.  27. 2003/10/03 updated Brian Carlstrom's web page.
  140.  
  141.  28. 2003/11/02 added links to the archives of the newsgroup and the
  142.      mailing list (Brian Carlstrom).
  143.  
  144.  29. 2003/12/01 minor update for scsh 0.6.5.
  145.  
  146.  30. 2004/02/29 finally mention the death of c.l.s.scsh
  147.  
  148.  31. 2004/03/14 mention problems with scsh 0.6.x and Ultrix (Brian
  149.      Carlstrom)
  150.  
  151. Where do I get the latest version of this FAQ?
  152. ==============================================
  153.  
  154.    The latest version of the FAQ can be found at the "scsh FAQ
  155. home-page":
  156. http://www-internal.alphanet.ch/~schinz/scsh-faq.html
  157.  
  158.    This home-page contains three versions of this FAQ: an ASCII
  159. version, an HTML version and an Info version.  If you have access to
  160. the World Wide Web, I strongly recommend that you get the HTML version,
  161. since all the hyperlinks can be followed just by clicking on them.
  162.  
  163.    Apart from that, this document is posted on the 13th of each month to
  164. the newsgroups `comp.lang.scheme.scsh', `comp.lang.scheme',
  165. `comp.answers' and `news.answers'.
  166.  
  167. Where do I send comments about this FAQ?
  168. ========================================
  169.  
  170.    Comments about this FAQ should be sent to the following address:
  171. <scsh-faq@alphanet.ch>.
  172.  
  173.    Please help us in producing a useful document by sending suggestions
  174. and material for this FAQ.  If you find stylistic, grammatical or syntax
  175. errors, please also report them.
  176.  
  177. General
  178. *******
  179.  
  180.    This section contains general questions about scsh: what it is,
  181. where to find it, etc.
  182.  
  183. What is scsh?
  184. =============
  185.  
  186.    Scsh is a Scheme shell. That is, it is a Unix shell which uses Scheme
  187. as its scripting language. It was designed and written by Olin Shivers,
  188. Brian Carlstrom, Martin Gasbichler and Mike Sperber, and is built on
  189. top of Scheme 48, an implementation of Scheme written by Jonathan Rees
  190. and Richard Kelsey.
  191.  
  192.    Scsh currently includes the following features:
  193.  
  194.    - A complete Posix interface.
  195.  
  196.    - A very complete support for networking, with high and low level
  197.      interfaces.  An additional network package, including an HTTP
  198.      server, SMTP support, etc. is also available separately.
  199.  
  200.    - Powerful string manipulation functions: pattern matching, file-name
  201.      manipulations, etc.
  202.  
  203.    - AWK-like macros.
  204.  
  205.    - An s-expression-based notation for regular expressions (SREs).
  206.  
  207.    - Threads.
  208.  
  209.    However, it is currently aimed primarily at scripting use, rather
  210. than interactive use (*note Interactive scsh::).
  211.  
  212. How do you pronounce scsh?
  213. ==========================
  214.  
  215.    According to Olin, scsh is pronounced "skishhhh" (it rhymes with
  216. "fish").
  217.  
  218. What is the current version of scsh?
  219. ====================================
  220.  
  221.    The current version (as of 14 March 2004) is 0.6.5.
  222.  
  223. What are the licensing terms for scsh?
  224. ======================================
  225.  
  226.    Scsh is distributed under a BSD-like open source licence. Here are
  227. the exact terms, which can be found in the file `COPYING' of the
  228. distribution:
  229.  
  230.      Copyright (c) 1993-2002 Richard Kelsey and Jonathan Rees Copyright
  231.      (c) 1994-2002 by Olin Shivers and Brian D. Carlstrom.  Copyright
  232.      (c) 1999-2002 by Martin Gasbichler.  Copyright (c) 2001-2002 by
  233.      Michael Sperber.
  234.  
  235.      All rights reserved.
  236.  
  237.      Redistribution and use in source and binary forms, with or without
  238.      modification, are permitted provided that the following conditions
  239.      are met: 1. Redistributions of source code must retain the above
  240.      copyright    notice, this list of conditions and the following
  241.      disclaimer.  2. Redistributions in binary form must reproduce the
  242.      above copyright    notice, this list of conditions and the
  243.      following disclaimer in the    documentation and/or other
  244.      materials provided with the distribution.  3. The name of the
  245.      authors may not be used to endorse or promote products    derived
  246.      from this software without specific prior written permission.
  247.  
  248.      THIS SOFTWARE IS PROVIDED BY THE AUTHORS "AS IS" AND ANY EXPRESS OR
  249.      IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  250.      WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  251.      ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
  252.      DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  253.      DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  254.      GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  255.      INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  256.      WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  257.      NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  258.      SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  259.  
  260.    Previous to version 0.5.2 scsh was distributed under a more
  261. restrictive licence.
  262.  
  263. What is Scheme?
  264. ===============
  265.  
  266.    Scheme is a small and elegant programming language of the Lisp
  267. family, originally designed by Guy Lewis Steele Jr. and Gerald Jay
  268. Sussman.  It includes powerful features like first-class procedures and
  269. continuations, and is statically scoped (like Pascal).  For more
  270. information, refer to the Scheme FAQ (*note Getting the docs::).
  271.  
  272. What is Scheme 48?
  273. ==================
  274.  
  275.    Scheme 48 is a small and portable Scheme implementation written by
  276. Jonathan Rees and Richard Kelsey.  It is based on a virtual machine
  277. architecture (i.e. it does not compile to native code).
  278.  
  279.    Scheme 48 implements all the features described in R5RS (*note
  280. Getting the docs::) and some extensions like exceptions and a module
  281. system.
  282.  
  283. How does scsh compare to other common scripting languages?
  284. ==========================================================
  285.  
  286.    Many scripting languages are in use today, and comparing scsh with
  287. all of them would be impossible. Here, we therefore restrict ourselves
  288. to the following three popular scripting languages: Perl, Python and
  289. Ruby. Below, they will be collectively referred to as PP&R.
  290.  
  291.    To simplify the comparison, it will be split in three parts: first we
  292. will look at the programming languages themselves, that is the
  293. abstractions they offer to the programmer; then, we will look at the
  294. implementation(s) of these languages; finally, we will look at the
  295. (standard) libraries available for these different languages.
  296.  
  297. Underlying programming languages
  298. --------------------------------
  299.  
  300.    From a programming language perspective, scsh is different than PP&R
  301. in that it is based on a general-purpose programming language, namely
  302. Scheme. PP&R, on the other hand, were all designed to be scripting
  303. languages originally. Today many people use them for relatively large
  304. applications which do not qualify as scripts, but scripts were the
  305. primary target of these languages. This sometimes shows in their
  306. design, for example when it comes to variable declarations which are by
  307. default optional in PP&R but not in Scheme.
  308.  
  309.    Scheme is also special in that it is a functional programming
  310. language, whereas Python and Ruby are object-oriented and Perl is
  311. procedural (even though most modern Perl code is written using
  312. objects). This does not mean that it is not possible to do functional
  313. programming with PP&R or object-oriented programming with Scheme. It
  314. just means that in Ruby and Python the object-oriented programming
  315. style is encouraged both by the language itself (e.g. everything is an
  316. object) and the standard libraries. The same holds for Scheme and the
  317. functional programming style.
  318.  
  319.    Another major difference between Scheme and PP&R is the syntax. PP&R
  320. all have infix syntax with different notations for different concepts.
  321. For example, the `if' conditional expression is syntactically different
  322. from, say, a function call. Scheme, on the other hand, has a very
  323. regular prefix syntax based on so-called s-expressions. In Scheme, an
  324. `if' looks no different than a function call.
  325.  
  326.    This very regular syntax make it possible to extend Scheme using a
  327. sophisticated macro system. Such macros are used in several crucial
  328. places in scsh, for example to support regular expressions with a
  329. syntax based on s-expressions (see below), or to provide a mechanism to
  330. iterate over the contents of a file in a way reminiscent of the AWK
  331. language.
  332.  
  333.    It should finally be noted that Scheme, Ruby and at least one
  334. implementation of Python (Stackless Python) give the programmer a way
  335. to capture the current continuation. This makes it possible to
  336. implement, directly in the language, very powerful control features
  337. including coroutines. More about continuations can be found, for
  338. example, in the Scheme FAQ (*note Getting the docs::).
  339.  
  340. Language implementations
  341. ------------------------
  342.  
  343.    Perl, Python, Ruby and scsh are relatively close to each other when
  344. it comes to the features offered by their current implementation(s).
  345.  
  346.    Ruby, Python and scsh have an interactive mode which enables one to
  347. enter expression and see the result of their evaluation. Perl does not
  348. include such a mode by default, even though its debugger can be used as
  349. a basic interactive evaluator. Ruby, Python and scsh also provide a
  350. debugger.
  351.  
  352. Libraries
  353. ---------
  354.  
  355.    Because of their popularity, there is an impressive amount of
  356. third-party libraries available for PP&R, which cover many application
  357. domains. Currently, the same cannot be said about scsh, although a few
  358. third-party libraries are available (*note Scsh code archive::).
  359.  
  360.    That said, scsh has excellent support for writing scripts in a Posix
  361. environment, which is its main domain of application. A great design
  362. effort has been put into making Posix look nice from scsh. This is
  363. accomplished not only by providing nicer names for Posix functions, but
  364. also by altering their behaviour. This contrasts with PP&R which often
  365. use both the name and the behaviour of the standard Posix functions.
  366.  
  367.    One example situation where scsh diverges both from Posix and PP&R is
  368. child process management. With Posix and PP&R, when child a process
  369. exits, its parent process has to wait on it explicitly. If it fails to
  370. do so, the dead child process (actually some information about it, like
  371. its exit status) remains in the kernel's process table, as a zombie
  372. process. This can be a serious problem, since the kernel's process
  373. table can eventually become full with zombie processes.
  374.  
  375.    Scsh can manage dead children processes in an automatic fashion
  376. through a technique called process reaping. The basic idea is that scsh
  377. takes care of waiting for child processes and stores their exit status
  378. in the Scheme data-structure associated to them. The scsh programmer is
  379. then free to wait or simply ignore its children, without having to
  380. worry about zombie processes.
  381.  
  382.    Another strength of scsh is its handling of regular expressions.
  383. Since regular expressions are important in many scripting applications,
  384. pretty much all scripting languages provide support for them, and PP&R
  385. or scsh are no exceptions. It should be noted that the regular
  386. expressions offered by scsh have some limitations when compared to
  387. PP&R, like the lack of non-greedy versions of some operators. On the
  388. other hand, scsh's regular expressions have some very interesting
  389. properties not found in PP&R:
  390.    * a notation based on s-expressions instead of plain strings, which
  391.      makes it unnecessary to quote special characters in strings, and
  392.      makes it possible to lay out regular expressions nicely, comment
  393.      them, etc.
  394.  
  395.    * a representation of regular expressions as trees instead of
  396.      strings, which eases their manipulation by programs, for example
  397.      to compose large regular expressions out of small ones, or to
  398.      write functions building regular expressions.
  399.  
  400. Example script
  401. --------------
  402.  
  403.    The following code snippets aim to provide an idea of how scsh
  404. compares with other common scripting languages. They all print a list
  405. of all the executables available in the current PATH to the standard
  406. output (improvements to these examples are welcome).
  407.  
  408.    - `sh'
  409.           #!/bin/sh
  410.           
  411.           IFS=':'
  412.           for d in $PATH; do
  413.             for f in $d/*; do
  414.               [ -x $f -a ! -d $f ] && echo $f
  415.             done
  416.           done
  417.  
  418.    - `perl'
  419.  
  420.           What is the sound of Perl? Is it not the sound of a wall that
  421.           people have stopped banging their head against?
  422.           - _Larry Wall_
  423.  
  424.           #!/usr/local/bin/perl
  425.           
  426.           for my $dir (split /:/, $ENV{PATH}) {
  427.              opendir DIR, $dir or die "can't opendir $dir: $!";
  428.              -x "$dir/$_" && !-d _ && print "$_\n" for readdir DIR;
  429.              closedir DIR;
  430.           }
  431.  
  432.    - `python'
  433.           #!/usr/local/bin/python
  434.           
  435.           import os, string, stat
  436.           for d in string.split(os.environ['PATH'], ':'):
  437.              for f in os.listdir(d):
  438.                 mode = os.lstat(d + '/' + f)[stat.ST_MODE]
  439.                 if not stat.S_ISDIR(mode):
  440.                    print f
  441.  
  442.    - `ruby'
  443.           #!/usr/bin/ruby
  444.           
  445.           ENV["PATH"].split(/:/).each {|path|
  446.             Dir.foreach(path) {|file|
  447.               puts(file) if File.stat(File.join(path, file)).executable?
  448.             }
  449.           }
  450.  
  451.    - `scsh'
  452.           #!/usr/local/bin/scsh -s
  453.           !#
  454.           
  455.           (define (executables dir)
  456.             (with-cwd dir
  457.                (filter file-executable? (directory-files dir #t))))
  458.           (define (writeln x) (display x) (newline))
  459.           
  460.           (for-each writeln
  461.              (append-map executables ((infix-splitter ":") (getenv "PATH"))))
  462.  
  463. Where can I get scsh?
  464. =====================
  465.  
  466.    The latest version of scsh can be downloaded from the scsh home page,
  467. located at http://www.scsh.net/.
  468.  
  469.    There is also a SourceForge projet page for scsh at
  470. http://scsh.sourceforge.net/.
  471.  
  472.    Binaries for the Debian distribution of GNU/Linux are available from
  473. http://www.debian.org/Packages/stable/interpreters/scsh.html. A
  474. binary RPM for Red Hat Linux for x86 is available in the shells group of
  475. the libc6 contrib archive (say `rpmfind scsh').
  476.  
  477.    Binaries for win32 using Cygwin32 are available at
  478. http://xarch.tu-graz.ac.at/autocad/lisp/cl/scsh-0.5.2-cygwin-bin.tgz
  479. (thanks to Reini Urban). These require a recent version of cygwin1.dll.
  480. And please notice that this is an old (0.5.2) version of scsh, not the
  481. latest.
  482.  
  483. Where can I find documentation about scsh?
  484. ==========================================
  485.  
  486.    The main documentation about scsh is the scsh manual.  It is
  487. included in the distribution, in `<prefix>/lib/scsh/doc/scsh-manual'
  488. where `<prefix>' is the location where you installed scsh.
  489.  
  490.    You may also want to take a look at the technical report describing
  491. the design of scsh. It is also included in the distribution, in
  492. `<prefix>/lib/scsh/doc/scsh-paper'.
  493.  
  494.    The documentation about Scheme 48 is also worth reading, since it
  495. describes features like the module system, the interface with C, the
  496. command processor and some interesting libraries. It is in
  497. `<prefix>/lib/scsh/doc/s48-manual'.
  498.  
  499.    Also, since scsh is written on top of a Scheme system, you have
  500. access to the great power of Scheme.  However, no Scheme documentation
  501. is available with scsh, so you may wish to obtain the standard Scheme
  502. references as well.  Here are some useful pointers:
  503.  
  504.    - The official specification for Scheme is "The Revised^5 Report on
  505.      the Algorithmic Language Scheme", often abbreviated R5RS.  This is
  506.      the document you should use to look up details about Scheme.  It is
  507.      available in various formats at:
  508.      http://www.schemers.org/Documents/Standards/
  509.  
  510.    - An excellent and up-to-date Scheme FAQ was written by Matthias
  511.      Radestock and is available at:
  512.      http://www.schemers.org/Documents/FAQ/.
  513.      An older FAQ was maintained by Mark Kantrowitz and Barry Margolin
  514.      and, for those interested, is still available at:
  515.      http://www.faqs.org/faqs/scheme-faq/.
  516.    - Schemers.org (http://www.schemers.org/) is a collection of Scheme
  517.      resources maintained by the Programming Languages Team at Rice
  518.      University.
  519.  
  520.    - The Scheme home-page is located at:
  521.      http://www.swiss.ai.mit.edu/projects/scheme/
  522.    - The Scheme 48 home-page is located at http://s48.org/.
  523.  
  524.    - There are many good books about Scheme, for example: "Structure and
  525.      Interpretation of Computer Programs" (2nd ed.) by Harold Abelson
  526.      and Gerald Jay Sussman, MIT Press, 1996 or "Scheme and the Art of
  527.      Programming" by George Springer and Daniel P. Friedman, MIT Press,
  528.      1989. The full text of the first one is available online at the
  529.      following address: http://mitpress.mit.edu/sicp/.
  530.  
  531.      For more references, see the Scheme FAQ.
  532.  
  533.    The home-pages of the various people involved in the design of
  534. Scheme, Scheme 48 or scsh may also be of interest to you.  Here are
  535. some links:
  536.  
  537.    - Gerald Jay Sussman:
  538.      http://www-swiss.ai.mit.edu/~gjs/gjs.html
  539.  
  540.    - Jonathan A. Rees:
  541.      http://mumble.net/jar/
  542.  
  543.    - Richard Kelsey:
  544.      http://s48.org/~kelsey/
  545.  
  546.    - Olin Shivers:
  547.      http://www.cc.gatech.edu/fac/Olin.Shivers/
  548.  
  549.    - Brian D. Carlstrom:
  550.      http://www.carlstrom.com/
  551.  
  552.    - Martin Gasbichler:
  553.      http://www-pu.informatik.uni-tuebingen.de/users/gasbichl/
  554.  
  555.    - Mike Sperber:
  556.      http://www-pu.informatik.uni-tuebingen.de/users/sperber/
  557.  
  558. Is there some kind of reference card for scsh?
  559. ==============================================
  560.  
  561.    Not exactly. There is a small list of all of scsh's functions in the
  562. file `doc/cheat.txt', but it has not been updated for quite some time.
  563. However, it would be great to have a nice TeXified reference card,
  564. which would include R5RS functions as well (something like the nice
  565. Perl reference card).
  566.  
  567. Which newsgroups and mailing-lists are related to scsh?
  568. =======================================================
  569.  
  570.    Currently, there is a mailing-list which is mirrored to a newsgroup.
  571.  
  572.    To (un)subscribe to the mailing-list, send a message to
  573. <scsh-request@zurich.ai.mit.edu>.  To submit a message to the
  574. mailing-list, send it to <scsh@zurich.ai.mit.edu>.
  575.  
  576.    The mailing-list is also readable as a standard newsgroup, thanks to
  577. gmane, a mail-to-news gateway. More information is available at the
  578. following URL:
  579. http://gmane.org/info.php?group=gmane.lisp.scheme.scsh
  580.  
  581.    There used to be a newsgroup dedicated to scsh, called
  582. `comp.lang.scheme.scsh' but it is now deprecated.
  583.  
  584.    Also, `comp.lang.scheme', which talks about Scheme in general, may
  585. be of interest to you. If Scheme is your first functional language, you
  586. might also want to read `comp.lang.functional'.
  587.  
  588. Does scsh run on my system?
  589. ===========================
  590.  
  591.    Currently, scsh runs without modification on the following systems:
  592. Harris CXUX, HP-UX, IBM AIX, Linux, FreeBSD (*note Scsh on FreeBSD::),
  593. OpenBSD, NetBSD, NeXTSTEP, SGI IRIX, Solaris, SunOS, MacOS X and Win32.
  594. It should also run without too many changes on other 32 bits UNIX
  595. platforms (for 64 bit platforms like Digital Unix, *note Porting scsh::)
  596.  
  597.    Since version 0.6, scsh doesn't run on Ultrix anymore, and users of
  598. this system are encouraged to use version 0.5.3 instead.
  599.  
  600. Is scsh easy to port?
  601. =====================
  602.  
  603.    On 32 bits UNIX machines, yes, usually.  If your system isn't already
  604. supported, take a look at the file `doc/install.txt' which contains
  605. porting instructions.
  606.  
  607.    Porting scsh to 64 bit UNIX machines (or, more generally, non-32 bit
  608. machines) is currently harder. The main reason is that this requires
  609. modifications to the Scheme 48 virtual machine (VM). This VM is written
  610. in PreScheme, a dialect of Scheme, and the PreScheme compiler isn't
  611. distributed with scsh. It is, however, included in standard Scheme 48
  612. distributions, which are available on Richard Kelsey's FTP site:
  613. ftp://ftp.nj.nec.com/pub/kelsey/
  614. (you'll also find a paper about PreScheme there).
  615.  
  616.    In any case, never try to hack the C code generated by the PreScheme
  617. compiler (file `scheme48vm.c'); this is ugly and you'll have to restart
  618. from scratch for the next release of Scheme 48.
  619.  
  620.    Apart from the problems with the Scheme 48 VM, there are also some
  621. problems with scsh: the current version contains C code that assumes
  622. 32-bitness.  This occurs mainly in the foreign-function interfaces (that
  623. is, interface between Scheme and C), where integers are converted
  624. between their Scheme and C representation.
  625.  
  626.    Since v0.5.2 there is also a port to Win32 which uses the cygwin32
  627. toolkit (thanks to Brian Carlstrom).
  628.  
  629. Can I run scsh under some other Scheme implementation?
  630. ======================================================
  631.  
  632.    Currently, scsh is tightly bound to Scheme 48 because it uses two
  633. non-standard features of Scheme 48: its module system and its foreign
  634. function interface (FFI). This does not mean that porting it to another
  635. Scheme implementation is impossible, but it is certainly hard.
  636.  
  637.    Mike Sperber and Richard Kelsey are drafting a SRFI for a standard
  638. FFI based on the current Scheme 48 FFI.  This would help in making scsh
  639. portable, since its C part could be easily reused with other
  640. implementations using this FFI.
  641.  
  642.    Matthew Flatt will be implementing this standard FFI for PLT Scheme.
  643. Therefore, PLT Scheme may become a viable alternative to Scheme 48 for
  644. scsh users. PLT Scheme is an umbrella name for a family of
  645. implementations of Scheme, which includes DrScheme and MzScheme. More
  646. information about it can be found at:
  647. http://www.plt-scheme.org/
  648.  
  649.    There is also a near-complete port of scsh to the Guile interpreter
  650. by Gary Houston, which you can access by cvsweb at
  651. http://subversions.gnu.org/cgi-bin/cvsweb/guile/guile-scsh/. It needs
  652. the `guilerxspencer' and `rxspencer' packages, available at
  653. http://arglist.com/guile/.
  654.  
  655.    While scsh was designed primarily for Scheme, most of it can be
  656. ported with some adaptations to other languages. We are currently aware
  657. of one such port for Objective Caml, called Cash, which can be found at:
  658. http://pauillac.inria.fr/cash/
  659.  
  660. Installing and using scsh
  661. *************************
  662.  
  663.    Now that you have downloaded scsh, you might want to install and use
  664. it.  Some help about this subject is provided here.
  665.  
  666. Compilation problems
  667. ====================
  668.  
  669.    Scsh should compile without problems on most Unix platforms.
  670. Particular notes:
  671.  
  672.   1. On MacOS X, with scsh versions older than 0.6.0, you had to specify
  673.      the host type to configure, since autoconf was not able to
  674.      autodetect it; you had to include `--host=powerpc-apple-bsd' in the
  675.      configure commandline.
  676.  
  677.   2. On Linux, compiling versions older than 0.5.2 with the new version
  678.      on the glibc caused problems. The 0.5.2 release notes say
  679.      "problems with the signal system blowing up builds on some of the
  680.      more obscure Unix systems have been fixed").
  681.  
  682. Is there a "port" of scsh for FreeBSD?
  683. ======================================
  684.  
  685.    Installing scsh on FreeBSD is best done by compiling FreeBSD's scsh
  686. "port" (meaning the FreeBSD term of a port, which is an integrated
  687. third-party package) or by getting a binary "package" from a FreeBSD
  688. ftp server. The FreeBSD port is available under `ports/lang/scsh'.
  689.  
  690. It looks like I do not have enough memory to compile scsh?!?
  691. ============================================================
  692.  
  693.    If you get errors like "not enough memory" when building scsh, you
  694. may try to adjust the limits on memory usage imposed by your system.
  695. To do this, you have to use the `ulimit' command under `sh' and
  696. derivatives or the `unlimit' command under `csh' and derivatives
  697. (`tcsh' and the like).  See the reference manual of your shell for more
  698. information.
  699.  
  700. Is there some kind of "contributed code archive" for scsh?
  701. ==========================================================
  702.  
  703.    The following resources may be of interest to you:
  704.  
  705.   1. The Scheme Untergrund Library, which collects contributed code for
  706.      Scheme 48 and scsh:
  707.      http://www.nongnu.org/sunterlib/
  708.  
  709.   2. The scsh Wiki on which you can, among other things, share some
  710.      code snippets http://www.scsh.net/cgi-bin/wiki.cgi
  711.   3. The resource page, on the scsh home page
  712.      http://www.scsh.net/resources.html.
  713.  
  714.   4. The scsh contributed code repository, at
  715.      ftp://ftp.scsh.net/pub/scsh/contrib/, Which currently includes:
  716.  
  717.        1. sunet, an extensible web server written by Olin Shivers with
  718.           extensions by Michael Sperber;
  719.  
  720.        2. Functional Postscript, which provides a Scheme interface to
  721.           the Postscript page description language;
  722.  
  723.        3. A text markup system by Scott Draves and Jonathan Rees;
  724.  
  725.        4. pgscsh, a socket-level interface to the PostgreSQL
  726.           object-relational DBMS, by Eric Marsden.
  727.  
  728.      Go on and send more code.
  729.  
  730.   5. The various Scheme code repositories, which are all listed in the
  731.      Scheme FAQ.  The two main repositories are the Scheme Repository
  732.      at Indiana University:
  733.      http://www.cs.indiana.edu/scheme-repository/home.html
  734.      and the CMU AI Repository, Scheme Section (a.k.a. the CMU Scheme
  735.      Repository):
  736.      http://www.cs.cmu.edu/Web/Groups/AI/html/repository.html.
  737.  
  738.    Also, some useful code is included with Scheme 48 (hash tables
  739. support, sorting functions, etc.) in the Big Scheme module.  Please
  740. notice that you will have to open the module before being able to
  741. access its functions.  For additional information, check the file
  742. `doc/big-scheme.txt' in the scsh distribution.
  743.  
  744.    If you want to write some code for scsh but you don't know what, you
  745. might want to take a look at the scsh home-page (*note Getting scsh::)
  746. which contains a list of interesting projects.
  747.  
  748. Can I use "plain" Scheme code with scsh?
  749. ========================================
  750.  
  751.    Generally speaking, all of the existing Scheme code can be run
  752. without problem with scsh.  There is only *one* possibly annoying
  753. incompatibility between R5RS-compliant interpreters and scsh: Symbols in
  754. scsh are case-sensitive while this is not true for R5RS-compliant
  755. interpreters.  This means, for example, that the following expression:
  756.  
  757.      (eq? 'symbol 'Symbol)
  758.  
  759. evaluates to `#t' with an R5RS-compliant interpreter (including the
  760. original Scheme 48), while it evaluates to `#f' with scsh.
  761.  
  762.    In practice this shouldn't be a big problem, but if you encounter
  763. code that works perfectly with all Scheme interpreters except scsh, then
  764. this may be the reason.
  765.  
  766.    If you want to know the design decision behind this choice, you
  767. should read the technical report describing the design of scsh (*note
  768. Getting the docs::).
  769.  
  770.    There are also other extensions to R5RS in scsh (e.g. C-like escaped
  771. characters in strings) but they shouldn't break existing Scheme code;
  772. you should have them in mind, however, when trying to write portable
  773. Scheme code under scsh.
  774.  
  775. Can I use scsh as an interactive shell?
  776. =======================================
  777.  
  778.    Well, technically you can: just run the "scsh" command and you will
  779. enter a Scheme 48 session with all scsh functions available.  However,
  780. this is definitely not suitable for interactive work: there is no
  781. command-line editing, no command-line history, no file/function name
  782. completion, no terse syntax, etc.  All these features are planned, and
  783. Olin has a design for much of them.  However, nobody found the time to
  784. implement them yet.
  785.  
  786.    In the meantime, a nice solution is to use a separate tool which
  787. provides some of these features.  Here is a partial list of such tools:
  788.  
  789.   1. Emacs: use the `cmuscheme' package, written by Olin.  It is now
  790.      part of Emacs, but if you don't have it on your system, you may
  791.      use the one provided with scsh, which is also a little more
  792.      up-to-date (check the directory `emacs').  This mode enables you
  793.      to run scsh (or any Scheme interpreter by the way) as an inferior
  794.      process.  It provides command-line editing, command-line history,
  795.      dynamic completion, file-name completion, automatic indentation of
  796.      Scheme code and more.
  797.  
  798.      If you want to give it a try right now, just type `C-u M-x
  799.      run-scheme', and then enter `scsh' at the prompt.
  800.  
  801.   2. Some terminal emulator that enables input (or output) editing.  An
  802.      example is the 9term terminal emulator, inspired by the Plan 9
  803.      terminal emulator.  Check out 9term's home-page at:
  804.      http://www.cs.su.oz.au/~matty/9term/index.html
  805.  
  806.   3. Any text editor that can run a process in one of its windows.  An
  807.      example is wily (although it is more than a text editor), inspired
  808.      by Plan 9's ACME tool.  For more information:
  809.      http://www.cs.yorku.ca/~oz/wily/
  810.  
  811. I get "undefined variable" errors when I try to use some functions?!?
  812. =====================================================================
  813.  
  814.    If you get "undefined variable" errors when you use functions from
  815. the big-scheme package or macros like `define-record', then maybe you
  816. didn't open the appropriate packages.  To open them, there are two
  817. solutions:
  818.  
  819.   1. use the `,open' command in interactive mode, or
  820.  
  821.   2. use Scheme 48's module system.
  822.  
  823.    The first solution is nice for interactive work, while the second is
  824. the one to use for scripts.
  825.  
  826.    Documentation on the Scheme 48 module system can be found in the
  827. Scheme 48 documentation. Olin Shivers also posted a message with
  828. further explanations to the scsh newsgroup, which is archived at
  829. http://groups.google.com/groups?selm=qijyawastzo.fsf%40lambda.ai.mit.edu.
  830.  
  831. Can I use SLIB (a Scheme library) with scsh?
  832. ============================================
  833.  
  834.    Yes, provided that you get (or write) an initialization file for
  835. scsh.  Tomas By wrote one that you can get there:
  836. ftp://ftp.dcs.shef.ac.uk/home/tomas/scsh.init
  837.  
  838.    By the way, more information about SLIB is available by following
  839. this URL:
  840. http://www-swiss.ai.mit.edu/~jaffer/SLIB.html
  841.  
  842. Some basic I/O functions (like EOF testing) seem not available in scsh?!?
  843. =========================================================================
  844.  
  845.    Don't forget that scsh is built on top of Scheme.  Therefore, you
  846. have access to the full power of Scheme in scsh, and that includes some
  847. basic I/O functions, like the test for EOF, etc.  However, these
  848. functions are not documented in the scsh manual, but in the official
  849. Scheme specification (R5RS, *note Getting the docs::).
  850.  
  851. How can I return the eof-object?
  852. ================================
  853.  
  854.    Some functions and macros (like the nice AWK macro) take a reader
  855. function as an argument.  This reader function is required to return the
  856. eof-object at the end of the input.  This is easy when the input is a
  857. port, but much harder when the input is something else (like a list of
  858. lines, etc.).  The reason is that R5RS specifies that the eof-object
  859. can't be read by the `read' procedure, and therefore can't be included
  860. literally in your source.  However, it can be defined like that:
  861.  
  862.      (define eof-object (read (make-string-input-port "")))
  863.  
  864. Is there support for protocols like HTTP, SMTP, etc.?
  865. =====================================================
  866.  
  867.    Yes, but it isn't included in the scsh distribution.  You will find
  868. it in the contributed code directory for scsh:
  869. ftp://ftp.scsh.net/pub/scsh/contrib/
  870.  
  871. I get strange errors with some network functions?!?
  872. ===================================================
  873.  
  874.    If you are using scsh 0.4.2 under Solaris 2 or Irix 5, and the errors
  875. you get look like:
  876.  
  877.      Error: 122
  878.             "Operation not supported on transport endpoint"
  879.             #{Procedure 9398 %listen}
  880.  
  881. then you should switch to a newer version of scsh: this was a known bug
  882. of scsh 0.4.2.
  883.  
  884.    If, for some reason, you want to stick with v0.4.2, here is how to
  885. fix the bug:
  886.  
  887.    In scsh's distribution directory, edit the file
  888. `scsh/solaris/netconst.scm' (if you are under Solaris 2 and above) or
  889. `scsh/irix/netconst.scm' (if you are under Irix 5 and above) so that
  890. the following lines:
  891.  
  892.      (define socket-type/stream 1)        ; stream socket
  893.      (define socket-type/datagram 2)        ; datagram socket
  894.      (define socket-type/raw 3)        ; raw-protocol interface
  895.      ;;(define socket-type/rdm 4)        ; reliably-delivered message
  896.      ;;(define socket-type/seqpacket 5)      ; sequenced packet stream
  897.  
  898. are replaced by the following lines:
  899.  
  900.      (define socket-type/stream 2)        ; stream socket
  901.      (define socket-type/datagram 1)        ; datagram socket
  902.      (define socket-type/raw 4)        ; raw-protocol interface
  903.      ;;(define socket-type/rdm 5)        ; reliably-delivered message
  904.      ;;(define socket-type/seqpacket 6)      ; sequenced packet stream
  905.  
  906. then recompile scsh, by running make in the main directory, and
  907. reinstall it.
  908.  
  909. How do I get the multiple values returned by a function?
  910. ========================================================
  911.  
  912.    This is documented in the R5RS.  However, with all these
  913. continuations, the documentation might be a little hard to understand
  914. for newcomers.  So here is a little (although not very useful) example
  915. that uses `values' and `call-with-values':
  916.  
  917.      (call-with-values (lambda () (values 6 7)) *)
  918.        => 42
  919.  
  920.    As you can see, the first argument to `call-with-values' is a
  921. procedure which return multiple values, and the second is a procedure
  922. which gets these multiple values as arguments.
  923.  
  924.    Scheme 48 provides another syntax to access multiple values: the
  925. `receive' macro.  This macro binds multiple values returned by an
  926. expression to variables, and then evaluates a sequence of expressions
  927. with these bindings active (for Common Lisp fans, this is similar to
  928. `multiple-value-bind').  Here is the above example, rewritten using
  929. `receive':
  930.  
  931.      (receive (x y) (values 6 7) (* x y))
  932.        => 42
  933.  
  934.    For more information on this function, check out
  935. `doc/big-scheme.txt'.
  936.  
  937.    While this may not be evident here, the `receive' macro is often
  938. easier to use than `call-with-values'.
  939.  
  940. How do I interface scsh with a C function?
  941. ==========================================
  942.  
  943.    Use the Scheme 48 facility to interface with C, documented in the
  944. Scheme 48 manual.
  945.  
  946. What is the syntax of regular expressions?
  947. ==========================================
  948.  
  949.    Scsh 0.5.2 introduced support for SREs, or Structural Regular
  950. Expressions.  These provide an s-expression notation for building up
  951. and operating on regular expressions. See the SRE section of the manual
  952. for further details.
  953.  
  954.    Standard string-based regexps are also available (and in fact SREs
  955. compile to string-based regexps). Henry Spencer's POSIX regular
  956. expression engine is used to implement the matching. The syntax
  957. accepted by this engine is described in its man page, which can be
  958. found in the scsh distribution, in file `scsh/regexp/regex.7'.
  959.  
  960. How should I handle errors?
  961. ===========================
  962.  
  963.    Scsh raises exceptions instead of passing error status codes via the
  964. `errno' variable (this makes error handling much simpler). You can use
  965. the `with-errno-handler' form to handle these errors gracefully.
  966.  
  967.    Certain error conditions are signalled by calls to the `error'
  968. primitive. If you wish to intercept these conditions gracefully you can
  969. write your own handler. The following example shows how to intercept the
  970. host-not-found condition on DNS lookup.
  971.  
  972.      #!/usr/local/bin/scsh \
  973.      -dm -m whnf -e main -s
  974.      !#
  975.      
  976.      (define-structure whnf
  977.        (export main)
  978.        (open scheme scsh handle)
  979.        (begin
  980.      
  981.          (define (with-host-not-found* thunk)
  982.            (call-with-current-continuation
  983.             (lambda (k)
  984.               (with-handler
  985.                (lambda (condition next)
  986.                  (cond ((string-match "^name->host-info" (cadr condition))
  987.                         (display "No such host")
  988.                         (newline)
  989.                         (k '()))
  990.                        (else (next))))
  991.                thunk))))
  992.      
  993.          (define-syntax with-host-not-found
  994.            (syntax-rules ()
  995.              ((with-host-not-found ?body ...)
  996.               (with-host-not-found* (lambda () ?body ...)))))
  997.      
  998.          (define (main args)
  999.            (with-host-not-found
  1000.             (host-info "foo.bar.com")))))
  1001.  
  1002.