\chapter{User's guide} This chapter details Scheme~48's user interface: its command-line arguments, command processor, debugger, and so forth. \section{Command line arguments} A few command line arguments are processed by Scheme~48 as it starts up. \code{scheme48} [\code{-i} \cvar{image}] [\code{-h} \cvar{heapsize}] % [\code{-s} \cvar{stacksize}] [\code{-a} \cvar{argument \ldots}] \begin{description} \item[{\tt -i} \cvar{image}] specifies a heap image file to resume. This defaults to a heap image that runs a Scheme command processor. Heap images are created by the \code{,dump} and \code{,build commands}, for which see below. \item[{\tt -h} \cvar{heapsize}] specifies how much space should be reserved for allocation. \cvar{Heapsize} is in words (where one word = 4 bytes), and covers both semispaces, only one of which is in use at any given time (except during garbage collection). Cons cells are currently 3 words, so if you want to make sure you can allocate a million cons cells, you should specify \code{-h 6000000} (actually somewhat more than this, to account for the initial heap image and breathing room). The default heap size is 3000000 words. The system will use a larger heap if the specified (or default) size is less than the size of the image being resumed. %\item[{\tt -s} \cvar{stacksize}] % specifies how much space should be reserved for the continuation % and environment stack. If this space is exhausted, continuations % and environments are copied to the heap. \cvar{Stacksize} is in words % and defaults to 2500. \item[{\tt -a} \cvar{argument \ldots}] is only useful with images built using \code{,build}. The arguments are passed as a list of strings to the procedure specified in the \code{,build} command as for example: \begin{example} > (define (f a) (for-each display a) (newline) 0) > ,build f foo.image > ,exit \% scheme48vm -i foo.image -a mumble "foo x" mumblefoo x \% \end{example} \end{description} The usual definition of the \code{s48} or \code{scheme48} command is actually a shell script that starts up the Scheme~48 virtual machine with a \code{-i \cvar{imagefile}} specifying the development environment heap image and a \code{-o \cvar{vm-executable}} specifying the location of the virtual-machine executable (the executable is needed for loading external code on some versions of Unix; see section~\ref{dynamic-externals} \link*{for more information} [for more information] {dynamic-externals}). The file \code{go} in the Scheme~48 installation source directory is an example of such a shell script. \section{Command processor} When you invoke the default heap image, a command processor starts running. The command processor acts as both a read-eval-print loop, reading expressions, evaluating them, and printing the results, and as an interactive debugger and data inspector. See Chapter~\ref{chapter:command-processor} for \link*{a description of the command processor} [a description of the command processor] {chapter:command-processor}. \section{Editing} We recommend running Scheme~48 under GNU Emacs or XEmacs using the \code{cmuscheme48} command package. This is in the Scheme~48 distribution's \code{emacs/} subdirectory and is included in XEmacs's \code{scheme} package. It is a variant of the \code{cmuscheme} library, which comes to us courtesy of Olin Shivers, formerly of CMU. You might want to put the following in your Emacs init file (\code{.emacs}): \begin{example} (setq scheme-program-name "scheme48") (autoload 'run-scheme "cmuscheme48" "Run an inferior Scheme process." t) \end{example} The Emacs function \code{run-scheme} can then be used to start a process running the program \code{scheme48} in a new buffer. To make the \code{autoload} and \code{(require \ldots)} forms work, you will also need to put the directory containing \code{cmuscheme} and related files in your emacs load-path: \begin{example} (setq load-path (append load-path '("\cvar{scheme-48-directory}/emacs"))) \end{example} Further documentation can be found in the files \code{emacs/cmuscheme48.el} and \code{emacs/comint.el}. \section{Performance} \label{section:performance} If you want to generally have your code run faster than it normally would, enter \code{inline-values} mode before loading anything. Otherwise calls to primitives (like \code{+} and \code{cons}) and in-line procedures (like \code{not} and \code{cadr}) won't be open-coded, and programs will run more slowly. The system doesn't start in \code{inline-values} mode by default because the Scheme report permits redefinitions of built-in procedures. With this mode set, such redefinitions don't work according to the report, because previously compiled calls may have in-lined the old definition, leaving no opportunity to call the new definition. \code{Inline-values} mode is controlled by the \code{inline-values} switch. \code{,set inline-values} and \code{,unset inline-values} turn it on and off. \section{Disassembler} The \code{,dis} command prints out the disassembled byte codes of a procedure. \begin{example} > ,dis cons cons 0 (protocol 2) 2 (pop) 3 (make-stored-object 2 pair) 6 (return) > \end{example} The current byte codes are listed in the file \code{scheme/vm/arch.scm}. A somewhat out-of-date description of them can be found in \cite{Kelsey-Rees:Scheme48}. The command argument is optional; if unsupplied it defaults to the current focus object (\code{\#\#}). The disassembler can also be invoked on continuations and templates. \section{Module system} \label{module-guide} This section gives a brief description of modules and related entities. For detailed information, including a description of the module configuration language, see \link*{the module chapter}[chapter~\Ref]{chapter:modules}. % JAR says: this paragraph is muddy. A {\em module} is an isolated namespace, with visibility of bindings controlled by module descriptions written in a special configuration language. A module may be instantiated as a {\em package}, which is an environment in which code can be evaluated. Most modules are instantiated only once and so have a unique package. A {\em structure} is a subset of the bindings in a package. Only by being included in a structure can a binding be made visible in other packages. A structure has two parts, the package whose bindings are being exported and the set of names that are to be exported. This set of names is called an {\em interface}. A module then has three parts: \begin{itemize} \item a set of structures whose bindings are to be visible within the module \item the source code to be evaluated within the module \item a set of exported interfaces \end{itemize} Instantiating a module produces a package and a set of structures, one for each of the exported interfaces. The following example uses \code{define-structure} to create a module that implements simple cells as pairs, instantiates this module, and binds the resulting structure to \code{cells}. The syntax \code{(export \cvar{name \ldots})} creates an interface containing \cvar{name \ldots}. The \code{open} clause lists structures whose bindings are visible within the module. The \code{begin} clause contains source code. \begin{example} (define-structure cells (export make-cell cell-ref cell-set!) (open scheme) (begin (define (make-cell x) (cons 'cell x)) (define cell-ref cdr) (define cell-set! set-cdr!))) \end{example} Cells could also have been implemented using the \link*{record facility}[record facility described in section~\Ref]{records} and available in structure \code{define-record-type}. \begin{example} (define-structure cells (export make-cell cell-ref cell-set!) (open scheme define-record-types) (begin (define-record-type cell :cell (make-cell value) cell? (value cell-ref cell-set!)))) \end{example} With either definition the resulting structure can be used in other modules by including \code{cells} in an \code{open} clause. The command interpreter is always operating within a particular package. Initially this is a package in which only the standard Scheme bindings are visible. The bindings of other structures can be made visible by using the \link*{\code{,open} command} [\code{,open} command described in section~\Ref{} below]{module-command-guide}. Note that this initial package does not include the configuration language. Module code needs to be evaluated in the configuration package, which can be done by using the {\code ,config} command: \begin{example} > ,config (define-structure cells \ldots) > ,open cells > (make-cell 4) '(cell . 4) > (define c (make-cell 4)) > (cell-ref c) 4 \end{example} \section{Library} A number of useful utilities are either built in to Scheme~48 or can be loaded from an external library. These utilities are not visible in the user environment by default, but can be made available with the \code{open} command. For example, to use the \code{tables} structure, do \begin{example} > ,open tables > \end{example} If the utility is not already loaded, then the \code{,open} command will load it. Or, you can load something explicitly (without opening it) using the \code{load-package} command: \begin{example} > ,load-package queues > ,open queues \end{example} When loading a utility, the message "Note: optional optimizer not invoked" is innocuous. Feel free to ignore it. See also the package system documentation, in \link*{the module chapter}[chapter~\Ref]{chapter:modules}. Not all of the the libraries available in Scheme~48 are described in this manual. All are listed in files \code{rts-packages.scm}, \code{comp-packages.scm}, \code{env-packages.scm}, and \code{more-packages.scm} in the \code{scheme} directory of the distribution, and the bindings they export are listed in \code{interfaces.scm} and \code{more-interfaces.scm} in the same directory. %architecture % Information about the virtual machine. E.g. % (enum op eq?) => the integer opcode of the EQ? instruction % %big-scheme % Many generally useful features. See doc/big-scheme.txt. % %bigbit % Extensions to the bitwise logical operators (exported by % the BITWISE structure) so that they operate on bignums. % To use these you should do % % ,load-package bigbit % ,open bitwise % %conditions % Part of the condition system: DEFINE-CONDITION-PREDICATE and % routines for examining condition objects. (See also handle, % signals.) % %defpackage % The module system: DEFINE-STRUCTURE and DEFINE-INTERFACE. % %destructuring % DESTRUCTURE macro. See doc/big-scheme.txt. % %display-conditions % Displaying condition objects. % (DISPLAY-CONDITION condition port) \goesto{} unspecific % Display condition in an easily readable form. E.g. %\begin{example} % > ,open display-conditions handle conditions % > (display-condition % (call-with-current-continuation % (lambda (k) % (with-handler (lambda (c punt) % (if (error? c) % (k c) % (punt))) % (lambda () (+ 1 'a))))) % (current-output-port)) % % Error: exception % (+ 1 'a) % > %\end{example} % %extended-ports % Ports for reading from and writing to strings, and related things. % See doc/big-scheme.txt. % %filenames % Rudimentary file name parsing and synthesis. E.g. % file-name-directory and file-name-nondirectory are as in Gnu emacs. % %floatnums % Floating point numbers. These are in a very crude state; use at % your own risk. They are slow and do not read or print correctly. % %fluids % Dynamically bound "variables." % (MAKE-FLUID top-level-value) \goesto{} a "fluid" object % (FLUID fluid) \goesto{} current value of fluid object % (SET-FLUID! fluid value) \goesto{} unspecific; changes current value of % fluid object % (LET-FLUID fluid value thunk) \goesto{} whatever thunk returns % Within the dynamic extent of execution of (thunk), the fluid % object has value as its binding (unless changed by SET-FLUID! % or overridden by another LET-FLUID). % E.g. % (define f (make-fluid 7)) % (define (baz) (+ (fluid f) 1)) % (baz) ;\goesto{} 8 % (let-fluid f 4 (lambda () (+ (baz) 1))) ;\goesto{} 6 % %formats % A simple FORMAT procedure, similar to Common Lisp's or T's. % See doc/big-scheme.txt for documentation. % %handle % Part of the condition system. % (WITH-HANDLER handler thunk) \goesto{} whatever thunk returns. % handler is a procedure of two arguments. The first argument % is a condition object, and the second is a "punt" procedure. % The handler should examine the condition object (using ERROR?, % etc. from the CONDITIONS structure). If it decides not to do % anything special, it should tail-call the "punt" procedure. % Otherwise it should take appropriate action and perform a % non-local exit. It should not just return unless it knows % damn well what it's doing; returns in certain situations can % cause VM crashes. % %interrupts % Interrupt system % %ports % A few extra port-related operations, notably FORCE-OUTPUT. % %pp % A pretty-printer. (p \cvar{exp}) will pretty-print the result of \cvar{exp}, % which must be an S-expression. (Source code for procedures is not % retained or reconstructed.) You can also do (p \cvar{exp} \cvar{port}) to % print to a specific port. % % The procedure pretty-print takes three arguments: the object to be % printed, a port to write to, and the current horizontal cursor % position. If you've just done a newline, then pass in zero for % the position argument. % % The algorithm is very peculiar, and sometimes buggy. % %queues % FIFO queues. % %random % Not-very-random random number generator. The \cvar{seed} should be between % 0 and 2$^{28}$ exclusive. % % > (define random (make-random \cvar{seed})) % > (random) \goesto{} pseudo-random number between 0 and 2$^{28}$ % %receiving % Convenient interface to the call-with-values procedure, like % Common Lisp's multiple-value-bind macro. See doc/big-scheme.txt. % %records % MAKE-RECORD-TYPE and friends. See the Scheme of Things column in % Lisp Pointers, volume 4, number 1, for documentation. % %recnums % Complex numbers. This should be loaded (e.g. with ,load-package) % but needn't be opened. % %search-trees % Balanced binary search trees. See comments at top of % big/search-tree.scm. % %signals % ERROR, WARN, and related procedures. % %sort % Online merge sort (see comment at top of file big/sort.scm). % % (sort-list \cvar{list} \cvar{pred}) % (sort-list! \cvar{list} \cvar{pred}) % %sicp % Compatibility package for the Scheme dialect used in the book % "Structure and Interpretation of Computer Programs." % %sockets % Interface to Unix BSD sockets. See comments at top of file % misc/socket.scm. % %threads % Multitasking. See doc/threads.txt. % %util % SUBLIST, ANY, REDUCE, FILTER, and some other useful things. % %weak % Weak pointers and populations. % (MAKE-WEAK-POINTER thing) => weak-pointer % (WEAK-POINTER-REF weak-pointer) => thing or \code{\#f} % \code{\#f} if the thing has been gc'ed. % %writing % (RECURRING-WRITE thing port recur) => unspecific % This is the same as WRITE except that recursive calls invoke % the recur argument instead of WRITE. For an example, see % the definition of LIMITED-WRITE in env/dispcond.scm, which % implements processing similar to common Lisp's *print-level* % and *print-length*.