	   Scheme User's Guide				   February 13, 1989
  
  
  
  
  
  
  
			     "Almost Scheme" User's Guide 
  
  
					  by 
  
  
				     David N. Gray 
  
  
			   Original version March 22, 1988 
 |				Revised August 2, 1988 
 |			  Latest revision February 13, 1989 
  
  
  
  
  
	   1  SPECIFICATIONS 
  
		"Almost Scheme" is an implementation of TI Scheme for  a  TI
	   Explorer  (or microExplorer) running software release 3 or later.
	   It consists of a Scheme  function  library  and  patches  to  the
	   evaluator  and  compiler  for  supporting  Scheme  mode.   It  is
	   "almost" Scheme because it has the  fundamental  limitation  that
	   continuation  objects  have  dynamic  scope instead of indefinite
	   scope.  In other words, continuations can be used  to  exit  some
	   currently  running  context  (like  Common  Lisp  RETURN-FROM  or
	   THROW), but cannot be used to re-start a context that has already
	   been exited.  
  
		The language that is  supported  is  a  combination  of  the
	   features in the following two references:  
  
	       1. The "TI Scheme  Language  Reference  Manual",  TI  part
		  number 2537905-0001.  
  
	       2. The  "Revised^3  Report  on  the  Algorithmic  Language
		  Scheme",  SIGPLAN Notices vol.  21, #12, December 1986.
		  Also published as MIT AI  Memo  848a  and  as  TI  part
		  number 2549810-0001.  
  
	   In  instances where there is any conflict between these documents
	   or  any   ambiguity	 in   the   specifications,   the   Explorer
	   implementation  imitates  the  behavior  of  PC  Scheme  wherever
	   feasible without sacrificing performance.  
  
  
  
	   Texas Instruments		 - 1 -			    Explorer

	   Scheme User's Guide				   February 13, 1989
  
  
  
		The following exceptions to standard Scheme are required  in
	   order to fit into the existing Explorer virtual machine:  
  
	      *  Continuations  produced by CALL/CC are limited to having
		 dynamic extent instead of indefinite extent.  
  
	      *  The distinction between "exact"  and  "inexact"  numbers
		 cannot  be  fully  supported,  although  the  associated
		 functions  and  syntax  are  supported  and  try  to  do
		 something  reasonably close to the intent.  Integers and
		 ratios are considered to be  exact  and  floating  point
		 numbers are considered inexact.  
  
	      *  The  false object is identical to the empty list.  (This
		 is also true in PC Scheme and T.)  
  
	      *  Destructive alteration of rest args is not permitted.  
  
 |	      *  Anonymous functions cannot be advised.  
  
  
		"Almost Scheme" also  tries  to  be  compatible  with  MIT's
	   "Pseudoscheme".    This   includes  supporting  the  DEFINE-MACRO
	   construct from Yale.  
  
		Refer to the file "PUBLIC:SCHEME;STATUS.TEXT" for a list  of
	   features  which  are not yet implemented, and a list of currently
	   known bugs.  
  
		Scheme on the Explorer makes use  of  the  existing  editor,
	   debugger,  inspector,  etc.  Scheme and Common Lisp functions are
	   able to call each other and share data structures.  Both compiled
	   and evaluated Scheme code is  supported.   It  is  intended  that
	   compiled  code  should be equally efficient in either Common Lisp
	   or Scheme.  Full tail-recursion semantics are  supported  by  the
	   compiler (but not the evaluator).  
  
		The  Explorer makes available the following features that PC
	   Scheme does not have:  
  
	      *  Complex numbers.  
  
	      *  Ratios (non-integer rational numbers).  
  
	      *  Choice of either single  or  double  precision  floating
		 point.	  (As in Common Lisp, the default is specified by
		 *READ-DEFAULT-FLOAT-FORMAT*.)  Constants can be prefixed
		 by either #S or #L  to  specify  "short"  (32  bits)  or
		 "long" (64 bits).  
  
  
  
	   Texas Instruments		 - 2 -			    Explorer

	   Scheme User's Guide				   February 13, 1989
  
  
  
  
  
  
	   2  LOADING 
  
		"Almost Scheme" is loaded by simply executing the form:  
		    (MAKE-SYSTEM "SCHEME") 
	   (If you are not using the normal Austin SYS host, you may need to
	   copy  the  file  "TI-7|MR-X:SITE;SCHEME.SYSTEM"  to your SYS host
	   before this will work.)  
  
 |		There  is  also  a  "SCHEME-RUNTIME"  system  defined  which
 |	   contains  just  the  files  needed to support execution of Scheme
 |	   programs that have been previously compiled.  
  
  
  
	   3  PACKAGES 
  
		The Scheme functions are external  symbols  in  the  package
	   "SCHEME".   Scheme programs should be in a package which uses the
	   "SCHEME" package.  For example:  
		    (DEFPACKAGE mine (:USE "SCHEME")) 
	   There is a  predefined  package  called  "SCHEME-USER"  which  is
	   available  for  use  as  a  default package while in Scheme mode.
	   Your package cannot :USE  both  the  SCHEME  and  LISP  packages,
	   although you may IMPORT selected symbols from the LISP package.  
  
  
  
	   4  SCHEME MODE 
  
		With the Scheme system loaded, the function (TICL:LISP-MODE)
	   can  return  one  of  three  values:  :COMMON-LISP, :ZETALISP, or
	   :SCHEME.  A file attribute line 
				 -*- Mode: Scheme -*- 
	   specifies Scheme mode.  This causes the Scheme read table  to  be
	   used,  causes  the  default  package to be SCHEME-USER instead of
	   USER, and defaults the base to ten.  Zmacs commands such as CTRL-
	   SHIFT-E and CTRL-SHIFT-C will evaluate or compile in Scheme mode.
	   The Zmacs command 
				  META-X Scheme Mode 
	   may also be used to enter Scheme mode.  
  
		In the Lisp Listener, (SETF (LISP-MODE) :SCHEME) will switch
	   to Scheme mode, which means  using  the  Scheme  read  table  and
	   changing  the  package to SCHEME-USER if the current package does
	   not use SCHEME.  Scheme mode can also be entered by executing the
	   form (SCHEME:SCHEME) and exited by either (EXIT) or (QUIT).	 The
	   listener  and break loop use the command prompt "==> " instead of
  
  
	   Texas Instruments		 - 3 -			    Explorer

	   Scheme User's Guide				   February 13, 1989
  
  
  
	   the usual prompt while in Scheme mode.  This can  be  changed  by
	   setting the variable SYS:*SCHEME-PROMPT*.  
  
  
  
	   5  SOURCE FILES 
  
		There is a canonical file type :SCHEME which can be used for
	   Scheme source code; it maps to ".SCHEME" on the Explorer and ".S"
	   on  MS-DOS.	 File types ".SCM" and ".SCH" are also recognized as
	   aliases for the :SCHEME canonical type.  The editor and  compiler
	   will use Scheme as the default mode for files of this type.  
  
		However, if you want to use MAKE-SYSTEM, you should use file
	   type  ".LISP"  and put "Mode:Scheme" in the attribute line, since
	   MAKE-SYSTEM only knows how to  compile  source  files  with  type
	   "LISP".  
  
		The  function LISP:COMPILE-FILE will compile Scheme files as
	   well as Common Lisp or Zetalisp.  There is also a SCHEME:COMPILE-
	   FILE function which always assumes Scheme mode, only supports two
	   arguments, and loads the file as well as compiling, in accordance
	   with PC Scheme.  
  
  
  
	   6  SCHEME AND COMMON LISP 
  
		Globally defined Scheme functions and macros are  stored  in
	   the  symbol's  definition  cell,  so  that Common Lisp and Scheme
	   functions can call each other by simply including the appropriate
	   package prefix on the function name.  (The Common  Lisp  notation
	   of  using  ":"  for package prefixes is supported as an extension
	   to Scheme.)  Fluid variables  in  Scheme  correspond  exactly  to
	   special  variables in Common Lisp.  A global Scheme DEFINE places
	   the value in the function cell of the symbol, with the value cell
	   forwarded to the function cell; thus it can  be  referenced  from
	   Common Lisp as either a function or special variable.  
  
		Things  defined  by the TI Scheme special form SYNTAX appear
	   as macros to Common  Lisp.	Things  defined  by  the  TI  Scheme
	   special  form DEFINE-INTEGRABLE are not visible from Common Lisp,
	   since Common Lisp has no equivalent capability.  
  
  
  
  
  
  
  
  
  
	   Texas Instruments		 - 4 -			    Explorer

	   Scheme User's Guide				   February 13, 1989
  
  
  
  
  
  
 |	   7  GRAPHICS SUPPORT 
  
 |		Two  video  modes  are  supported  by  the  Explorer  Scheme
 |	   runtime.   (SET-VIDEO-MODE! 3)  selects simulation of TI PC video
 |	   mode 3 (text and graphics), including the use of a similar aspect
 |	   ratio.  This mode is intended to  make  pictures  appear  on  the
 |	   Explorer screen with nearly the same size and proportions as they
 |	   would  appear  on a PC.  Other video mode values used on PCs will
 |	   be treated the same as mode 3  except  that  GET-VIDEO-MODE  will
 |	   still return the actual number given.  
  
 |		(SET-VIDEO-MODE! 9000) enables a native Explorer mode, which
 |	   provides  higher  resolution  and a more convenient 1-to-1 aspect
 |	   ratio; this is the default mode.  In this  mode,  a  normal  Lisp
 |	   Listener  window  on  an  Explorer monitor provides visibility of
 |	   pixels with x coordinates from -510 to +509 (or -410 to +409 with
 |	   suggestion menus on) and y coordinates from -369 to +368.   Other
 |	   monitors  may  vary.	  The  size of a window can be determined by
 |	   evaluating	the   Common   Lisp   forms   (SEND    *TERMINAL-IO*
 |	   :INSIDE-WIDTH) and (SEND *TERMINAL-IO* :INSIDE-HEIGHT).  
  
 |		In  either  mode, the SET-PEN-COLOR!  function can be called
 |	   with the same color names or numbers as  on  a  TI  PC.   With  a
 |	   microExplorer   or  monochrome  Explorer  screen,  BLACK  is  the
 |	   background color, WHITE is the normal foreground color (this will
 |	   actually appear as a negative image on a microExplorer or  on  an
 |	   Explorer  with  black-on-white  mode selected), and the other six
 |	   colors are represented  by  stipple  patterns  producing  various
 |	   shades of gray.  These gray shades look good for filled boxes but
 |	   are less effective for drawing lines.  DRAW-POINT is not affected
 |	   by the pen color.  
  
 |		With  a color monitor on an Explorer-II, SET-PEN-COLOR!  can
 |	   be used the same  as  on  a  color  TI  PC  and  it  does  affect
 |	   DRAW-POINT.	 Additionally,  any of the predefined color names in
 |	   the	 Explorer   W	package	  can	be   used.    For   example,
 |	   (SET-PEN-COLOR! 'W:ORANGE)  selects  orange, a color which is not
 |	   available on PCs.  A numeric argument in the range 8 through  255
 |	   is used as a direct index into the Explorer color map.  Note that
 |	   color  map indexes 0 through 7 (normally used for shades of gray)
 |	   can only be referenced by name, not by number.   The  CLEAR-POINT
 |	   function  sets  the  point to the background color of the window.
 |	   When SET-VIDEO-MODE!  has selected PC simulation,  CLEAR-GRAPHICS
 |	   will set the window's background color to black.  
  
 |		In  PC  Scheme, graphics are written directly to the screen,
 |	   and are not associated with windows,  which  are  only  used  for
  
  
	    Texas Instruments		  - 5 -			     Explorer

	    Scheme User's Guide				    February 13, 1989
  
  
  
 |	   text.  On the Explorer, graphics are written to the *TERMINAL-IO*
 |	   window.   Each  Lisp Listener window has its own pen position and
 |	   pen color, so that two  Scheme  programs  can  run  in  two  Lisp
 |	   Listeners  without  interfering  with  each other.  Note that the
 |	   graphics functions cannot be executed from within Zmacs.  
  
 |		Differences in  VDT  hardware  require  a  couple  of  other
 |	   differences	 between  PC  Scheme  and  "Almost  Scheme"  on  the
 |	   Explorer.  The SET-PALETTE!  function cannot be  supported  on  a
 |	   monochrome  Explorer.   Unlike  the  TI PC, the Explorer does not
 |	   separate text and graphics, so the functions  CLEAR-GRAPHICS  and
 |	   WINDOW-CLEAR both erase both text and graphics.  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
	   Texas Instruments		 - 6 -			    Explorer
