
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:

          (argv integer)  ==>  string | #f
              Retrieve  the  value of the given command line argument.
              Return #f, if there are less than  integer+1  arguments.
              Arguments start at 0.

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

          (environ string)  ==>  string | #f
              Retrieve  the  value  of the given environment variable.
              Return #f, if the variable is undefined.

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





S9 Interpreter                  Page 2                           S9(1)


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


          (eval object1)          ==>  object
          (eval object1 object2)  ==>  object
              Evaluate  object1  in the current environment and return
              its normal form.  If object2 is also  specified,  it  is
              ignored.

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

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


S9 Interpreter                  Page 3                           S9(1)


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



          (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

              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.

          (system string)  ==>  number
              Run the given shell command and return its exit code.

          (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



S9 Interpreter                  Page 4                           S9(1)


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


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



S9 Interpreter                  Page 5                           S9(1)


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


          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
              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  is  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).


S9 Interpreter                  Page 6                           S9(1)


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


          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.
          Call/cc must be the only argument when used  in  lambda  (or
          derived  binding  syntax,  such as let).  Not observing this
          rule will break the interpreter.

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.


S9 Interpreter                  Page 7                           S9(1)


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



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 8                           S9(1)

