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



NAME
          s9 - Scheme Interpreter

USAGE
          s9 [-i file | -] [-hv?] [-gqu] [-e expr] [-d file]
             [-k cells] [-l file] [-n nodes] [-r expr]
             [-- argument ... | [-f] file argument ...]

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, -v, or -?
              Display a brief summary of options.

          -i file | -
              Load alternative image file `file'. Image files will  be
              searched  in  the directory specified in S9FES_IMAGE_DIR
              (see below) except when the file name begins with a  `.'
              or  `/'  character. When this option is used, it must be
              the first one of the s9 command.
              When `-' is specified as file, no  heap  image  will  be
              loaded,  and  the  core  library  will  be read from the
              source file `s9.scm' in the current directory.

          -d file
              Dump heap image to file and exit.

          -e expr
              Read expression from expr, evaluate it,  and  print  its
              value.  Multiple  -e  options  may  be given, which will
              evaluate from left to right.  Interactive mode will  not
              be entered.

          -g[g]
              Print  GC  summaries.  A  single  `g'  will  report pool
              growth, a second `g' will also include data  about  pool
              usage after each collection.

          -k N[m]
              Set  vector  limit to N kilo (or mega) cells (-k 0 means
              no  limit;  use  with  care!).  An  m  suffix  indicates
              2^20*cells, the default is 2^10*cells.

          -l program
              Load  program  before entering the REPL or processing -e
              and -r options  or  running  a  final  program.  May  be
              repeated.

          -n N[m]
              Set  node limit to N kilo (or mega) nodes (-n 0 means no
              limit;  use  with  care!).   An   m   suffix   indicates
              2^20*nodes, the default is 2^10*nodes.



S9 Interpreter                  Page 1                           S9(1)


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


          -q
              Be quiet: skip banners and prompts, exit on errors.

          -r expr
              Like  -e,  but no value will print. Used to run programs
              for effect.

          -u
              Short for -k 0 -n 0 (use unlimited memory).

          -- [argument ...]
              Arguments following -- are not interpreted by S9fES, but
              passed  to  the  interpreted  program, which can extract
              them using the command-line procedure. This option  must
              be the last one.

          [-f] program [argument ...]
              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. This
              option must be the last one.

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:

          (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       =  (quit)

          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:




S9 Interpreter                  Page 2                           S9(1)


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


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

          (command-line)  ==>  list
              Return a list of command line arguments passed to the  a
              program  being  interpreted  or following the -- command
              line option.

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

          (environment-variable 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. When no object argument
              is given, this part will be omitted in the message.

          (eval object)  ==>  object
              Evaluate  object  in  the current environment and return
              its normal form.

          (exponent number)  ==>  integer
              Extract the exponent part from a number. This will be  0
              for integers.

          (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
              Return an unused symbol.

          (load-from-library string)  ==>  unspecific
              Attempt to load the  file  string  from  each  directory
              listed in the top-level variable *library-path*.

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



S9 Interpreter                  Page 3                           S9(1)


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


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

          (mantissa number)  ==>  integer
              Extract the mantissa part from a number.  This  will  be
              the number itself for integers.

          (print object ...)  ==>  unspecific
              Write  multiple  objects  separated by spaces and with a
              trailing newline.

          (require-extension ext ...)  ==>  unspecific
              Require the named extensions to be  compiled-in.  Signal
              an  error  if  not  all  of  the required extensions are
              present.  Ext may be of the form (or ext1 ext2 ...).  In
              this  case, it is sufficient if at least one of the exts
              given in or is present.

          (s9:bytecode proc)  ==>  list
              Return the bytecode of the given procedure as a list  of
              integers.

          (s9:object integer)  ==>  object
              Return  the  data  object stored at the given address in
              the S9 heap.   Use  with  caution!   This  function  may
              return  cyclic  values or nonsensical values or may even
              crash the interpreter.

          (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 expr)  ==>  object
              Evaluate  the  given  expression  and  return   a   list
              containing  its  normal  form  plus  a  summary  of  the
              resources used to compute that normal form:

                  - total nodes allocated
                  - conses allocated
                  - vector cells allocated
                  - garbage collections

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

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


S9 Interpreter                  Page 4                           S9(1)


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



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

          (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 slots of an
              unspecific value 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 more  detailed  descriptions  of
          the Scheme 9 extension procedures.

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

          ** (object)
              The  normal  form  of  the  expression   most   recently
              evaluated  at  the  top  level.  Unspecific  results and
              aborted computations do not change the value of **.

          *arguments* (list of strings)
              A list of command line arguments passed  to  the  Scheme
              program  (not  to  the interpreter), i.e. the args in s9
              file args or s9 -- args.

          *epsilon* (real number)
              The smallest difference between two real numbers.

          *extensions* (list of symbols)
              Identifiers naming the compiled-in extensions.

          *host-system* (symbol)
              The host system running the s9 interpreter: unix, plan9,
              or unknown.

          *image-file* (string or #f)
              The  name of the heap image file loaded at startup time.
              When no image is loaded, the variable is set to #f.

          *library-path* (list of strings)
              A  list  containing   each   path   contained   in   the
              S9FES_LIBRARY_PATH environment variable (see below).



S9 Interpreter                  Page 5                           S9(1)


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


          *loading* (boolean)
              Set to #t when loading a file, else #f.

          *release-date* (string)
              A   string   containing  the  release  date  of  the  S9
              interpreter in the form `YYYY-MM-DD'.

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

TECHNICAL DETAILS
          S9fES is a bytecode compiler and SECD abstract machine using
          shallow binding, primitive procedure inlining,  and  in-situ
          lambda   lifting.   It   employs  an  extremely  reliable[1]
          constant-space mark and sweep garbage collector with in-situ
          vector  pool  compaction.   Memory pools grow on demand. The
          interpreter uses arbitrary-precision integer arithmetics and




S9 Interpreter                  Page 6                           S9(1)


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


          decimal-based real number arithmetics.

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

          Load heap image or library.
              The interpreter searches the image directory for a  heap
              image  file  and  loads it. The image directory is taken
              from the S9FES_IMAGE_DIR environment variable. When  the
              variable  is  undefined,  a  compiled-in default will be
              used. The default image  file  is  named  s9.image.   An
              alternative  name  can  be  specified with the -i option
              (see  OPTIONS).   When  no  image  file  is   found   in
              S9FES_IMAGE_DIR,  a fallback image is loaded from a file
              named s9.image in the local directory. When no  fallback
              image  can  be  found,  an  error  is  signalled and the
              interpreter will not start.

          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 last `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.
              First  all  files  specified  in -l file options will be
              loaded in the  specified  order.  Then  all  expressions
              specified  in  -e  expr and -r expr command line options
              will be evaluated in the given order. After that,  a  -d
              file   option  will  be  evaluated,  if  present.  After
              processing such an option,  the  interpreter  will  exit
              immediately.   Finally,  if a program is being passed to
              the interpreter, the program will be run and any options
              following  the  program  name  will  be  passed  to  the
              program.  In  this  case  S9  will  exit  after  program
              execution.

          Enter REPL.
              Interactive  mode is only entered, when no -e, -r, or -d
              option was given and no program was specified.

ALLOCATION STRATEGY
          The S9fES memory pools grow 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 -k, -n, and -u command line options. The limit is
          specified in units of  1024  nodes/cells  (or  in  units  of
          1024*1024 nodes/cells 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 (or using the -u option) disables
          the  memory  limit  completely  and  the  interpreter   will


S9 Interpreter                  Page 7                           S9(1)


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


          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.
          The atan procedure does not accept a second argument.
          Inexact digits of the form #.

BUGS
          You may not quasiquote quasiquote unless in  unquote  (e.g.:
          ``x does not work, but `,`x does).
          Syntax-rules has more bugs than a swarm of locusts. Use low-
          level macros instead!

FILES
          @S9DIR@
              The S9fES procedure library (source code).
          s9.image
              The interpreter heap image.
          *.scm
              Scheme source code.

ENVIRONMENT
          S9FES_IMAGE_DIR
              The directory that will be searched for heap image files
              when the s9 interpreter starts.

          S9FES_LIBRARY_PATH
              A  colon-separated  list  of  directories  which will be
              searched for library files by the load-from-library  and
              locate-file  procedures. The value of this variable will
              be split at the colons and copied to the  *library-path*
              variable when S9 starts.
              Default: .:~/.s9fes:@S9DIR@

SIGNALS
          SIGINT
              Abort input or terminate program execution.
          SIGQUIT
              Terminate the interpreter process (emergency exit).
          "interrupt"
              On  Plan 9, receiving an interrupt note will abort input
              or terminate program execution, as SIGINT would on Unix.

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.





S9 Interpreter                  Page 8                           S9(1)


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


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

