
S9(1)                  Scheme 9 from Empty Space                 S9(1)



NAME
          s9 - Scheme Interpreter

USAGE
          s9 [-h?] [-i name] [-gnqv] [-m size[m]] [-f prog [args]]
             [-l prog] [-t count] [-d image] [-- [args]]

DESCRIPTION
          Scheme  9 from Empty Space is an interpreter for R4RS Scheme
          with some additional procedures for accessing  typical  Unix
          system  calls  and  Unix  and  Curses  library functions (if
          compiled-in). The s9 command starts the interpreter.

OPTIONS
          -h or -?
              Display a brief summary of options.
          -i name
              Load alternative image file `name.image'. When no  image
              file can be found, try to load `name.scm'. The file will
              be  searched  in  the  entire  S9FES_LIBRARY_PATH   (see
              below).  When  this option is used, it must be the first
              one of the s9 command.
              When `-' is specified as name, no  heap  image  will  be
              loaded,  and  the  core  library  will  be read from the
              source file `s9.scm'.
          -d file
              Dump heap image to file and exit.
          -f program [arguments]
              Run program and exit (implies -q). When  there  are  any
              arguments,  they  are  passed to the program, where they
              can be extracted using the command-line procedure.
          -g
              Print GC summaries (-gg = more verbose).
          -n
              Do not load $HOME/.s9fes/rc file, if any.
          -l program
              Load program before entering the REPL or  processing  -f
              (may be repeated).
          -m N[m]
              Set  memory  limit to N kilo (or mega) nodes (-m 0 means
              no limit; use with care!).
          -q
              Be quiet: skip banners and prompts, exit on errors.
          -t count
              Display count procedures at most in call traces.
          -v
              Display version and exit.
          -- [argument ...]
              Arguments following -- are not interpreted by S9fES, but
              passed  to  the command-line procedure instead (requires
              the unix extension).

ONLINE HELP
          When the interpreter is running and the default  heap  image
          is  loaded, just type (help) or ,h to invoke the online help
          system.  When the online help system is not loaded, you will
          have to run the following command first:


S9 Interpreter                  Page 1                           S9(1)


S9(1)                  Scheme 9 from Empty Space                 S9(1)


          (load-from-library "help.scm")

META COMMANDS
          In  order  to  facilitate  the invocation of frequently-used
          top-level  procedures,  s9  provides  the  following   "meta
          commands"  (they  work  only when entered directly at the s9
          prompt):

              ,a text  =  (apropos "text")
              ,h text  =  (help "text")
              ,l file  =  (load-from-library "file")
              ,q       =  (sys:exit)

          The arguments of ,a and ,h are optional.

ADDITIONS
          S9fES supports nestable block comments of the form

              #| comment ... |#.

          Square brackets may be used in the places of parentheses:

              (cond [(foo) (bar)]).

          The same type of bracket must be used  on  both  ends  of  a
          list.

          These S9fES procedures are not in R4RS:

          (bit-op integer1 integer2 integer3 ...)  ==>  integer | #f
              Implement  a variety of bitwise operations. See the bit-
              op help page for details.

          (delete-file string)  ==>  unspecific
              Delete the file specified in the string argument. If the
              file  does  not  exist  or  cannot be deleted, report an
              error.

          (dump-image string)  ==>  unspecific
              Write a heap image to  the  file  given  in  the  string
              argument. If the file already exists, report an error.

          (error string)         ==>  undefined
          (error string object)  ==>  undefined
              Print an error message of the form error: string: object
              and terminate program execution.

          (exponent real)  ==>  integer
              Extract the exponent part from a real number.

          (file-exists? string)  ==>  boolean
              Return #t if the file specified in the  string  argument
              exists and otherwise #f.

          (fold-left proc base list ...)  ==>  object
              Combine  the  elements of the lists using proc.  Combine
              elements  left-associatively.   Base  is  the   leftmost
              element.


S9 Interpreter                  Page 2                           S9(1)


S9(1)                  Scheme 9 from Empty Space                 S9(1)



          (fold-right proc base list ...)  ==>  object
              Combine  the  elements of the lists using proc.  Combine
              elements right-associatively.   Base  is  the  rightmost
              element.

          (gensym)         ==>  symbol
          (gensym symbol)  ==>  symbol
          (gensym string)  ==>  symbol
              Return  a fresh symbol. When a string or symbol argument
              is given, use it as prefix for the fresh symbol.

          (load-from-library string)  ==>  unspecific
              Attempt to load the file string from each  directory  of
              S9FES_LIBRARY_PATH.

          (locate-file string)  ==>  string | #f
              Search  for  the  file  string  in  each   directory  of
              S9FES_LIBRARY_PATH in sequence.  When the  file  can  be
              located, return its full path, else return #f.

          (macro-expand object)  ==>  object
          (macro-expand-1 object)  ==>  object
              If  object  is  a  list  resembling a macro application,
              return  the  expanded  form,  else  return  the  object.
              Macro-expand-1  expands  macros  only  once while macro-
              expand expands them recursively.

          (mantissa real)  ==>  integer
              Extract the mantissa part from a real number.

          (print object ...)  ==>  unspecific
              Write multiple objects separated by spaces.

          (require-extension name ...)  ==>  unspecific
              Require the named extensions to be  compiled-in.  Signal
              an  error  if  not  all  of  the required extensions are
              present.

          (reverse! list)  ==>  list
              Reverse list destructively and return the reverse  list.

          (set-input-port! input-port)  ==>  unspecific
              Destructively set the current input port.

          (set-output-port! output-port)  ==>  unspecific
              Destructively set the current output port.

          (stats form)  ==>  form
              Evaluate the given form and return a list containing its
              normal form plus a summary  of  the  resources  used  to
              compute that normal form:

                  - reduction steps
                  - conses allocated
                  - total nodes allocated
                  - garbage collections



S9 Interpreter                  Page 3                           S9(1)


S9(1)                  Scheme 9 from Empty Space                 S9(1)


              Each  resource  count  will  be  returned  as a group of
              integers representing ones,  thousands,  millions,  etc.
              Note  that  form  must be quoted or it will be evaluated
              before passing it to stats.

          (symbols)  ==>  list
              Return a list of all defined symbols.

          (trace symbol ...)  ==>  list | #t
          (trace #t)          ==>  list | #t
              Trace the procedure or syntax object bound to the  given
              symbols.    When  #t  is  passed  to  trace,  trace  all
              procedures and syntax objects (expect lots of  output!).
              When  no  arguments  are  passed to it, disable tracing.
              Trace returns the symbols that were being traced  before
              its invocation.

          (vector-append vector ...)  ==>  vector
              Return  a  fresh  vector containing the concatenation of
              the given vectors.

          (vector-copy vector)                           ==>  vector
          (vector-copy vector integer)                   ==>  vector
          (vector-copy vector integer1 integer2)         ==>  vector
          (vector-copy vector integer1 integer2 object)  ==>  vector
              Return a copy of the  given  vector.  When  integer1  is
              specified,  skip  the  given  number  of  elements. When
              integer2 is also specified, copy elements from  integer1
              up  to,  but  not  including,  integer2.   When integer2
              exceeds the size of the original vector, add  unspecific
              slots  to  the  copy.  When an object argument is given,
              fill extra slots with that argument.

          (void)  ==>  unspecific
              Return an unspecific value.

          Refer to the help pages for descriptions  of  the  Scheme  9
          extension procedures.

SPECIAL VARIABLES
          These  variables  are  predefined  in  the dynamic top-level
          scope of the interpreter.

          ** (form)
              The  normal  form  of  the  expression   most   recently
              evaluated at the top level.
          *extensions* (list of symbols)
              Compiled-in extensions.
          *library-path* (string)
              A  verbatim  copy  of the S9FES_LIBRARY_PATH environment
              variable (see below).
          *loading* (boolean)
              Set to #t when loading a file, else #f.

MACROS
          A macro is a procedure that is applied  to  its  unevaluated
          arguments.  The macro application is replaced with the value
          returned  by  the  procedure.   This  happens   before   the


S9 Interpreter                  Page 4                           S9(1)


S9(1)                  Scheme 9 from Empty Space                 S9(1)


          expression containing the macro application is evaluated, so
          a macro rewrites its own application:

          (define-syntax (when p . c)
            `(if ,p (begin ,@c)))
          (macro-expand '(when (= 1 1) (display "true") (newline) #t))
            ==>  (if (= 1 1)
                     (begin (display "true")
                            (newline)
                            #t))
          (when (= 1 1) 1 2 3)  ==>  3

          The define-syntax form introduces a new macro:

          (define-syntax name procedure)        ==>  unspecific
          (define-syntax (name args ...) body)  ==>  unspecific

          Both of these forms introduce the keyword name and  bind  it
          to  a procedure. The first form requires the second argument
          to be a procedure. Like in define forms the  second  variant
          implies a procedure definition.

          Macros  may contain applications of macros that were defined
          earlier.  Macros may not  recurse  directly,  but  they  may
          implement  recursion internally using letrec or by rewriting
          their own applications. The following  macro,  for  example,
          does not work, because d is undefined in the body of d:

          (define-syntax (d x) (and (pair? x) (d (cdr x)))) ; wrong

          The following version does work, though:

          (define-syntax (d x) (and (pair? x) `(d ,(cdr x)))) ; OK

          The body of define-syntax may be a syntax-rules transformer,
          as described in R4RS, if the syntax-rules extension has been
          loaded.

TECHNICAL DETAILS
          S9fES  is  a tree-walking interpreter using deep binding and
          hashed environments. It  employs  an  extremely  reliable[1]
          constant-space mark and sweep garbage collector with in-situ
          string and vector pool  compaction.  Memory  pools  grow  on
          demand.  The  interpreter  uses  arbitrary-precision integer
          arithmetics  and  (optional)   decimal-based   real   number
          arithmetics.

INTERPRETER START-UP
          When the s9 interpreter is started, the following steps will
          be performed in this order:

          Load library.
              The interpreter searches its library path (either built-
              in  or  specified  in the S9FES_LIBRARY_PATH environment
              variable) for a heap image file or  the  library  source
              code. The heap image file is the name of the interpreter
              with a .image suffix appended. An alternative  name  can
              be  specified  with  the  -i  option (see OPTIONS).  The


S9 Interpreter                  Page 5                           S9(1)


S9(1)                  Scheme 9 from Empty Space                 S9(1)


              default library source code is named s9.scm.  The  first
              directory  containing either a heap image or the library
              source code is used. When the directory contains both an
              image and the library sources, the image is loaded.

          Initialize extensions.
              Any   extensions   compiled  into  the  interpreter  are
              initialized by calling  the  nullary  procedure  ext:ext
              (where ext is the name of the extension). The procedures
              are optional. The first `extension' being initialized is
              S9  itself,  so  when a procedure named s9:s9 exists, it
              will be called at this point.

          Evaluate command line options.
              When a -l file option is found, the program contained in
              the  given  file  will  be  loaded.  When a -f file args
              option is found, the program contained in the file  will
              be  run  and  then S9 will exit.  Args will be passed to
              the program.

          Load rc file.
              If an `rc file' ($HOME/.s9fes/rc)  exists,  it  will  be
              loaded  at  this  point as if its name was passed to the
              load procedure. (Unless the -n option was specified.)

          Enter REPL.
              Interactive mode is only entered, when no -f option  was
              specified.

ALLOCATION STRATEGY
          The  S9fES  memory pool grows exponentially until the memory
          limit its reached. When the limit is  reached,  the  current
          computation  is  aborted.  A  memory  limit can be specified
          using the -m command line option. The limit is specified  in
          units  of  1024  nodes  (or  in  units of 1024*1024 nodes by
          appending an m suffix).
          Note that computations may abort before the limit is reached
          due  to  the  way  the  pool  grows. Use the -g command line
          option to experiment with pool sizes.
          Specifying  a  limit  of  zero  disables  the  memory  limit
          completely  and the interpreter will allocate as much memory
          as it can get.  This option should be used with care.

LIMITATIONS
          These parts of R4RS are not implemented:

          I/O: char-ready?  (this is in the sys-unix extension).
          Transcripts: transcript-off, transcript-on.
          Rational and complex numbers and related procedures.

BUGS
          You may not quasiquote quasiquote unless in  unquote  (e.g.:
          ``x does not work, but `,`x does).
          Syntax-rules is not fully hygienic.
          Multiple  call/cc's  in the arguments of the same lambda (or
          derived  binding  syntax,  such  as  let)  will  break   the




S9 Interpreter                  Page 6                           S9(1)


S9(1)                  Scheme 9 from Empty Space                 S9(1)


          evaluator.

FILES
          $HOME/.s9fes/rc
              If  present,  this  file  is loaded when the interpreter
              starts in interactive mode.
          @LIBDIR@
              The S9fES procedure library (source code).
          @LIBDIR@/contrib
              Contributions to the procedure library (source code).
          @LIBDIR@/s9.image
              The interpreter heap image.
          *.scm
              Scheme source code.

ENVIRONMENT
          S9FES_LIBRARY_PATH
              A colon-separated list  of  directories  which  will  be
              searched  for  the  s9  library  when the interpreter is
              launched. The same directories will be searched  by  the
              locate-file procedure.
              Default: .:~/.s9fes:@LIBDIR@

SIGNALS
          These  work  only  if  POSIX  signal handling was enabled at
          compile time.

          SIGINT
              Abort input or terminate program execution.
          SIGQUIT
              Terminate the interpreter process (emergency exit).
          SIGTERM
              Silently terminate the interpreter process.

FOOTNOTES
          [1] See comp.lang.scheme Usenet message
              <vhtzl9lupyp.fsf@maharal.csail.mit.edu>
              (Thu, 27 Aug 2009 13:27:42 -0400) and its follow-ups.

REFERENCES
          The Revised^4 Report on the Algorithmic Language Scheme.
              http://www-swiss.ai.mit.edu/~jaffer/r4rs_toc.html

          Scheme 9 from Empty Space -- A Guide to Implementing  Scheme
          in C.
              Available at Lulu.com, see http://www.t3x.org

AUTHOR
          Nils M Holm











S9 Interpreter                  Page 7                           S9(1)

