This is Info file scm.info, produced by Makeinfo-1.55 from the input file scm.texi.  File: scm.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir) This file documents the SCM Scheme implementation. Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Aubrey Jaffer Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the author. * Menu: * Copying:: * Overview:: Whats here and how to start using it. * Installing SCM:: * Standard Facilities:: * Packages:: Optional Capabilities * Guile Facilities:: Brave new World * Internals:: How it works * Procedure and Macro Index:: * Variable Index:: * Type Index::  File: scm.info, Node: Copying, Next: Overview, Prev: Top, Up: Top Copying ******* COPYRIGHT (c) 1989 BY PARADIGM ASSOCIATES INCORPORATED, CAMBRIDGE, MASSACHUSETTS. ALL RIGHTS RESERVED Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Paradigm Associates Inc not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. PARADIGM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL PARADIGM BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. gjc@paradigm.com Phone: 617-492-6079 Paradigm Associates Inc 29 Putnam Ave, Suite 6 Cambridge, MA 02138 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. 675 Mass Ave, Cambridge, MA 02139, USA Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. NO WARRANTY BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.  File: scm.info, Node: Overview, Next: Installing SCM, Prev: Copying, Up: Top Overview ******** Scm is a portable Scheme implementation written in C. Scm provides a machine independent platform for [JACAL], a symbolic algebra system. * Menu: * SCM Features:: * SCM Authors:: * Bibliography:: * Invoking SCM:: * SCM Options:: * SCM Variables:: * SCM Examples:: * SCM Session::  File: scm.info, Node: SCM Features, Next: SCM Authors, Prev: Overview, Up: Overview Features ======== * Conforms to Revised^4 Report on the Algorithmic Language Scheme [R4RS] and the [IEEE] P1178 specification. * Support for [SICP], [R2RS], [R3RS], and (proposed) [R5RS] scheme code. * Runs under Amiga, Atari-ST, MacOS, MS-DOS, OS/2, NOS/VE, Unicos, VMS, Unix and similar systems. Supports ASCII and EBCDIC character sets. * Is fully documented in TeXinfo form, allowing documentation to be generated in info, TeX, html, nroff, and troff formats. * Supports inexact real and complex numbers, 30 bit immediate integers and large precision integers. * Many Common Lisp functions: `logand', `logor', `logxor', `lognot', `ash', `logcount', `integer-length', `bit-extract', `defmacro', `macroexpand', `macroexpand1', `gentemp', `defvar', `force-output', `software-type', `get-decoded-time', `get-internal-run-time', `get-internal-real-time', `delete-file', `rename-file', `copy-tree', `acons', and `eval'. * `Char-code-limit', `most-positive-fixnum', `most-negative-fixnum', `and internal-time-units-per-second' constants. `*Features*' and `*load-pathname*' variables. * Arrays and bit-vectors. String ports and software emulation ports. I/O extensions providing ANSI C and POSIX.1 facilities. * Interfaces to standard libraries including REGEX string regular expression matching and the CURSES screen management package. * Available add-on packages including an interactive debugger, database, X-window graphics, BGI graphics, Motif, and Open-Windows packages. * A compiler (HOBBIT, available separately) and dynamic linking of compiled modules. * User definable responses to interrupts and errors, Process-syncronization primitives. Setable levels of monitoring and timing information printed interactively (the `verbose' function). `Restart', `quit', and `exec'.  File: scm.info, Node: SCM Authors, Next: Bibliography, Prev: SCM Features, Up: Overview Authors ======= Aubrey Jaffer (jaffer@ai.mit.edu) Most of SCM. Radey Shouman Arrays. `gsubr's, compiled closures, and records. Jerry D. Hedden Real and Complex functions. Fast mixed type arithmetics. Hugh Secker-Walker Syntax checking and memoization of special forms by evaluator. Storage allocation strategy and parameters. George Carrette "Siod", written by George Carrette, was the starting point for SCM. The major innovations taken from Siod are the evaluator's use of the C-stack and being able to garbage collect off the C-stack (*note Garbage Collection::.). There are many other contributors to SCM. They are acknowledged in the file `ChangeLog', a log of changes that have been made to scm.  File: scm.info, Node: Bibliography, Next: Invoking SCM, Prev: SCM Authors, Up: Overview Bibliography ============ [IEEE] `IEEE Standard 1178-1990. IEEE Standard for the Scheme Programming Language.' IEEE, New York, 1991. [Simply] Brian Harvey and Matthew Wright. `Simply Scheme: Introducing Computer Science' MIT Press, 1994 ISBN 0-262-08226-8 [SICP] Harold Abelson and Gerald Jay Sussman with Julie Sussman. `Structure and Interpretation of Computer Programs.' MIT Press, Cambridge, 1985. [R4RS] William Clinger and Jonathan Rees, Editors. Revised(4) Report on the Algorithmic Language Scheme. In `ACM Lisp Pointers IV' (July-September 1991). *Note Top: (r4rs)Top. [SLIB] Todd R. Eigenschink, Dave Love, and Aubrey Jaffer. SLIB, The Portable Scheme Library. Edition 2.01, for SLIB version 2a2, January 1995. *Note Top: (slib)Top. [JACAL] Aubrey Jaffer. JACAL Symbolic Mathematics System. Version 1a5, April 1994. *Note Top: (jacal)Top. `scm.texi' `scm.info' Documentation of `scm' extensions (beyond Scheme standards). Documentation on the internal representation and how to extend or include `scm' in other programs.  File: scm.info, Node: Invoking SCM, Next: SCM Options, Prev: Bibliography, Up: Overview Invoking SCM ============ scm [-a kbytes] [-ibvqmu] [-p number] [-c expression] [-e expression] [-f filename] [-l filename] [-r feature] [- | - | -s] [filename] [arguments ...] Upon startup `scm' loads the file specified by by the environment variable SCM_INIT_PATH or by the parameter IMPLINIT in the makefile (or `scmfig.h') if SCM_INIT_PATH is not defined. The makefiles attempt to set IMPLINIT to `Init.scm' in the source directory. Unless the option `-no-init-file' occurs in the command line, `Init.scm' checks to see if there is file `ScmInit.scm' in the path specified by the environment variable HOME (or in the current directory if HOME is undefined). If it finds such a file it is loaded. `Init.scm' then looks for command input from one of three sources: From an option on the command line, from a file named on the command line, or from standard input. This explanation applies to SCMLIT or other builds of SCM. GUILE is invoked similarly to SCM. Guile's startup script is `Ginit.scm' rather than `Init.scm'. Scheme-code files can also invoke SCM and its variants. *Note #!: Syntax Extensions.  File: scm.info, Node: SCM Options, Next: SCM Variables, Prev: Invoking SCM, Up: Overview Options ======= The options are processed in the order specified on the command line. - Command Option: -a KBYTES specifies that `scm' should allocate an initial heapsize of KBYTES. This option, if present, must be the first on the command line. - Command Option: -no-init-file Inhibits the loading of `ScmInit.scm' as described above. - Command Option: -e EXPRESSION - Command Option: -c EXPRESSION specifies that the scheme expression EXPRESSION is to be evaluated. These options are inspired by `perl' and `sh' respectively. On Amiga systems the entire option and argument need to be enclosed in quotes. For instance `"-e(newline)"'. - Command Option: -r FEATURE requires FEATURE. This will load a file from [SLIB] if that FEATURE is not already supported. If FEATURE is 2, 3, 4, or 5 `scm' will require the features neccessary to support [R2RS], [R3RS], [R4RS], or proposed [R5RS], respectively. - Command Option: -l FILENAME - Command Option: -f FILENAME loads FILENAME. `Scm' will load the first (unoptioned) file named on the command line if no `-c', `-e', `-f', `-l', or `-s' option preceeds it. - Command Option: -p LEVEL sets the prolixity (verboseness) to LEVEL. This is the same as the `scm' command (verobse LEVEL). - Command Option: -v (verbose mode) specifies that `scm' will print prompts, evaluation times, notice of loading files, and garbage collection statistics. This is the same as `-p3'. - Command Option: -q (quiet mode) specifies that `scm' will print no extra information. This is the same as `-p0'. - Command Option: -m specifies that subsequent loads, evaluations, and user interactions will be with [R4RS] macro capability. To use a specific [R4RS] macro implementation from [SLIB] (instead of [SLIB]'s default) put `-r' MACROPACKAGE before `-m' on the command line. - Command Option: -u specifies that subsequent loads, evaluations, and user interactions will be without [R4RS] macro capability. [R4RS] macro capability can be restored by a subsequent `-m' on the command line or from Scheme code. - Command Option: -i specifies that `scm' should run interactively. That means that `scm' will not terminate until the `(quit)' or `(exit)' command is given, even if there are errors. It also sets the prolixity level to 2 if it is less than 2. This will print prompts, evaluation times, and notice of loading files. The prolixity level can be set by subsequent options. If `scm' is started from a tty, it will assume that it should be interactive unless given a subsequent `-b' option. - Command Option: -b specifies that `scm' should run non-interactively. That means that `scm' will terminate after processing the command line or if there are errors. - Command Option: -s specifies, by analogy with `sh', that further options are to be treated as program aguments. - Command Option: - - Command Option: - specifies that there are no more options on the command line.  File: scm.info, Node: SCM Variables, Next: SCM Examples, Prev: SCM Options, Up: Overview Environment Variables ===================== - Environment Variable: SCM_INIT_PATH is the pathname where `scm' will look for its initialization code. The default is the file `Init.scm' in the source directory. - Environment Variable: SCHEME_LIBRARY_PATH is the [SLIB] Scheme library directory. - Environment Variable: HOME is the directory where `Init.scm' will look for the user initialization file `ScmInit.scm'. Scheme Variables ================ - Variable: *argv* contains the list of arguments to the program. `*argv*' can change during argument processing. This list is suitable for use as an argument to [SLIB] `getopt'. - Variable: *R4RS-macro* controls whether loading and interaction support [R4RS] macros. Define this in `ScmInit.scm' or files specified on the command line. This can be overridden by subsequent `-m' and `-u' options. - Variable: *interactive* controls interactivity as explained for the `-i' and `-b' options. Define this in `ScmInit.scm' or files specified on the command line. This can be overridden by subsequent `-i' and `-b' options.  File: scm.info, Node: SCM Examples, Next: SCM Session, Prev: SCM Variables, Up: Overview Examples ======== `% scm foo.scm' Loads and executes the contents of `foo.scm' and then enters interactive session. `% scm -f foo.scm arg1 arg2 arg3' Parameters `arg1', `arg2', and `arg3' are stored in the global list `*argv*'; Loads and executes the contents of `foo.scm' and exits. `% scm -s foo.scm arg1 arg2' Sets *argv* to `("foo.scm" "arg1" "arg2")' and enters interactive session. `% scm -e `(write (list-ref *argv* *optind*))' bar' Prints `"bar"'. `% scm -rpretty-print -r format -i' Loads `pretty-print' and `format' and enters interactive session. `% scm -r5' Loads `dynamic-wind', `values', and [R4RS] macros and enters interactive (with macros) session. `% scm -r5 -r4' Like above but `rev4-optional-procedures' are also loaded.  File: scm.info, Node: SCM Session, Prev: SCM Examples, Up: Overview SCM Session =========== * Options, file loading and features can be specified from the command line. *Note System interface: (scm)System interface. *Note Require: (slib)Require. * Typing the end-of-file character at the top level session (while SCM is not waiting for parenthesis closure) causes SCM to exit. * Typing the interrupt character aborts evaluation of the current form and resumes the top level read-eval-print loop.  File: scm.info, Node: Installing SCM, Next: Standard Facilities, Prev: Overview, Up: Top Installing SCM ************** * Menu: * SLIB:: * Problems Compiling:: * Problems Linking:: * Problems Running:: * Testing:: * Reporting Problems::  File: scm.info, Node: SLIB, Next: Problems Compiling, Prev: Installing SCM, Up: Installing SCM SLIB ==== [SLIB] is a portable Scheme library meant to provide compatibility and utility functions for all standard Scheme implementations. Although SLIB is not *neccessary* to run SCM, I strongly suggest you obtain and install it. Bug reports about running SCM without SLIB have very low priority. SLIB is available from the same sites as SCM: * altdorf.ai.mit.edu:archive/scm/slib2a2.tar.gz * prep.ai.mit.edu:pub/gnu/jacal/slib2a2.tar.gz * ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2a2.tar.gz * ftp.cs.indiana.edu:/pub/scheme-repository/imp/slib2a2.tar.gz  File: scm.info, Node: Problems Compiling, Next: Problems Linking, Prev: SLIB, Up: Installing SCM Problems Compiling ================== FILE: PROBLEM HOW TO FIX *.c: include file not found Correct the status of STDC_HEADERS in `scmfig.h' fix #include statement or add #define for system type to `scmfig.h'. *.c: Function should return a value in ... *.c: Parameter '...' is never used in ... *.c: Condition is always false in ... *.c: Unreachable code in function ... Ignore. scm.c: assignment between incompatible types change SIGRETTYPE in `scm.c'. time.c: CLK_TCK redefined incompatablility between and . remove STDC_HEADERS in `scmfig.h'. edit to remove incompatability. subr.c: Possibly incorrect assignment in function lgcd Ignore. sys.c: statement not reached sys.c: constant in conditional expression ignore sys.c: `???' undeclared, outside of functions #undef STDC_HEADERS in `scmfig.h'. scl.c: syntax error #define SYSTNAME to your system type in `scl.c' (softtype)  File: scm.info, Node: Problems Linking, Next: Problems Running, Prev: Problems Compiling, Up: Installing SCM Problems Linking ================ PROBLEM HOW TO FIX _sin etc. missing. uncomment LIBS in makefile  File: scm.info, Node: Problems Running, Next: Testing, Prev: Problems Linking, Up: Installing SCM Problems Running ================ PROBLEM HOW TO FIX Opening message and then machine crashes. Change memory model option to C compiler (or makefile). Make sure `sizet' definition is correct in `scmfig.h'. Reduce size of HEAP_SEG_SIZE in `setjump.h'. Input hangs #define NOSETBUF ERROR: heap: need larger initial Need to increase the initial heap allocation using -a or INIT_HEAP_SIZE. ERROR: Could not allocate ... Check `sizet' definition. Use 32 bit compiler mode. Don't try to run as subproccess remove ... in scmfig.h and recompile scm add ... in scmfig.h and recompile scm Do it and recompile files. ERROR: `Init.scm' not found Assign correct IMPLINIT in makefile or `scmfig.h' or define environment variable `SCM_INIT_PATH' to be the full pathname of `Init.scm' (*note Installing SCM::.). WARNING: require.scm not found define environment variable `SCHEME_LIBRARY_PATH' to be the full pathname of the scheme library [SLIB] or change `library-vicinity' in `Init.scm' to point to library or remove. *Note Installation: (slib)Installation. Make sure the value of `(library-vicinity)' has a trailing file separator (like / or \).  File: scm.info, Node: Testing, Next: Reporting Problems, Prev: Problems Running, Up: Installing SCM Testing ======= Loading `test.scm' in the distribution will run an [R4RS] conformance test on `scm'. > (load "test.scm") -| ;loading "test.scm" SECTION(2 1) SECTION(3 4) # # # # ... Loading `pi.scm' in the distribution will enable you to compute digits of pi. > (load "pi") ;loading "pi" ;done loading "pi.scm" ;Evaluation took 20 mSec (0 in gc) 767 cells work, 233 bytes other # > (pi 100 5) 00003 14159 26535 89793 23846 26433 83279 50288 41971 69399 37510 58209 74944 59230 78164 06286 20899 86280 34825 34211 70679 ;Evaluation took 550 mSec (60 in gc) 36976 cells work, 1548 bytes other # PROBLEM HOW TO FIX Runs some and then machine crashes. See above under machine crashes. Runs some and then ERROR: ... (after a GC has happened) Remove optimization option to C compiler and recompile. `#define SHORT_ALIGN' in `scmfig.h'. Some symbol names print incorrectly. Change memory model option to C compiler (or makefile). Check that `HEAP_SEG_SIZE' fits within `sizet'. Increase size of `HEAP_SEG_SIZE' (or `INIT_HEAP_SIZE' if it is smaller than `HEAP_SEG_SIZE'). ERROR: Rogue pointer in Heap. See above under machine crashes. Newlines don't appear correctly in output files. Check file mode (define OPEN_... in `Init.scm' Spaces or control characters appear in symbol names Check character defines in `scmfig.h'. Negative numbers turn positive. Check SRS in `scmfig.h'. VMS: Couldn't unwind stack VAX: botched longjmp `#define CHEAP_CONTIUATIONS' in `scmfig.h'. Sparc(SUN-4) heap is growing out of control You are experiencing a GC problem peculiar to the Sparc. The problem is that SCM doesn't know how to clear register windows. Every location which is not reused still gets marked at GC time. This causes lots of stuff which should be collected to not be. This will be a problem with any *conservative* GC until we find what instruction will clear the register windows. This problem is exacerbated by using lots of call-with-current-continuations.  File: scm.info, Node: Reporting Problems, Prev: Testing, Up: Installing SCM Reporting Problems ================== Reported problems and solutions are grouped under Compiling, Linking, Running, and Testing. If you don't find your problem listed there, you can send a bug report to `jaffer@ai.mit.edu' or `bug-scm@scrg.cs.tcd.ie'. The bug report should include: 1. The version of SCM (printed when SCM is invoked with no arguments). 2. The type of computer you are using. 3. The name and version of your computer's operating system. 4. The values of the environment variables `SCM_INIT_PATH' and `SCHEME_LIBRARY_PATH'. 5. The name and version of your C compiler. 6. If you are using an executable from a distribution, the name, vendor, and date of that distribution. In this case, corresponding with the vendor is recommended.  File: scm.info, Node: Standard Facilities, Next: Packages, Prev: Installing SCM, Up: Top Standard Facilities ******************* * Menu: * Standards Compliance:: Links to sections in [R4RS] and [SLIB] * System Interface:: Like how to exit * Internal State:: GC, errors, and diagnostics * Miscellaneous Procedures:: * Time:: Both real time and processor time * Interrupts:: and exceptions * Process Synchronization:: Because interrupts are preemptive * Files and Ports:: * Soft Ports:: Emulate I/O devices * Syntax Extensions:: and how to Define New Syntax * Low Level Syntactic Hooks::  File: scm.info, Node: Standards Compliance, Next: System Interface, Prev: Standard Facilities, Up: Standard Facilities Standards Compliance ==================== Scm conforms to the `IEEE Standard 1178-1990. IEEE Standard for the Scheme Programming Language.' (*note Bibliography::.), and `Revised(4) Report on the Algorithmic Language Scheme'. *Note Top: (r4rs)Top. All the required features of these specifications are supported. Many of the optional features are supported as well. Optionals of [R4RS] Supported by SCM ------------------------------------ two clause `if': `(if )' *Note Conditionals: (r4rs)Conditionals. `let*' named `let' *Note Binding constructs: (r4rs)Binding constructs. `do' *Note Iteration: (r4rs)Iteration. All varieties of `define' *Note Definitions: (r4rs)Definitions. `list-tail' *Note Pairs and lists: (r4rs)Pairs and lists. `string-copy' `string-fill!' *Note Strings: (r4rs)Strings. `make-vector' of two arguments `vector-fill!' *Note Vectors: (r4rs)Vectors. `apply' of more than 2 arguments *Note Control features: (r4rs)Control features. `-' and `/' of more than 2 arguments `exp' `log' `sin' `cos' `tan' `asin' `acos' `atan' `sqrt' `expt' `make-rectangular' `make-polar' `real-part' `imag-part' `magnitude' `angle' `exact->inexact' `inexact->exact' *Note Numerical operations: (r4rs)Numerical operations. `delay' `force' *Note Control features: (r4rs)Control features. `with-input-from-file' `with-output-to-file' *Note Ports: (r4rs)Ports. `char-ready?' *Note Input: (r4rs)Input. `transcript-on' `transcript-off' *Note System interface: (r4rs)System interface. Optionals of [R4RS] not Supported by SCM ---------------------------------------- `numerator' `denominator' `rationalize' *Note Numerical operations: (r4rs)Numerical operations. [R4RS] appendix Macros *Note Macros: (r4rs)Macros. [SLIB] Features of SCM and SCMLIT --------------------------------- `delay' `full-continuation' `ieee-p1178' `object-hash' `rev4-report' `source' See SLIB file `Template.scm'. `current-time' *Note Time: (slib)Time. `defmacro' *Note Defmacro: (slib)Defmacro. `dynamic-wind' *Note Dynamic-Wind: (slib)Dynamic-Wind. `eval' *Note System: (slib)System. `getenv' `system' *Note System Interface: (slib)System Interface. `hash' *Note Hashing: (slib)Hashing. `logical' *Note Bit-Twiddling: (slib)Bit-Twiddling. `multiarg-apply' *Note Multi-argument Apply: (slib)Multi-argument Apply. `multiarg/and-' *Note Multi-argument / and -: (slib)Multi-argument / and -. `rev4-optional-procedures' *Note Rev4 Optional Procedures: (slib)Rev4 Optional Procedures. `string-port' *Note String Ports: (slib)String Ports. `tmpnam' *Note Input/Output: (slib)Input/Output. `transcript' *Note Transcripts: (slib)Transcripts. `vicinity' *Note Vicinity: (slib)Vicinity. `with-file' *Note With-File: (slib)With-File. [SLIB] Features of SCM ---------------------- `array' *Note Arrays: (slib)Arrays. `array-for-each' *Note Array Mapping: (slib)Array Mapping. `bignum' `complex' `inexact' `rational' `real' *Note Require: (slib)Require.  File: scm.info, Node: System Interface, Next: Internal State, Prev: Standards Compliance, Up: Standard Facilities System Interface ================ For documentation of the procedures `getenv' and `system' *Note System Interface: (slib)System Interface. - Function: quit - Function: quit N - Function: exit - Function: exit N Aliases for `exit' (*note exit: (slib)System.). On many systems, SCM can also tail-call another program. *Note execp: I/O-Extensions. - Function: vms-debug If SCM is compiled under VMS these commands will invoke the editor or debugger respectively. - Function: ed FILENAME If SCM is compiled under VMS `ed' will invoke the editor with a single the single argument FILENAME. - Function: ed ARG1 ... Otherwise, the value of the environment variable `EDITOR' (or just `ed' if it isn't defined) is invoked as a command with arguments ARG1 .... - Function: program-arguments Returns a list of strings of the arguments scm was called with. - Function: errno - Function: errno N With no argument returns the current value of the system variable `errno'. When given an argument, `errno' sets the system variable `errno' to N and returns the previous value of `errno'. `(errno 0)' will clear outstanding errors. This is recommended after `try-load' returns `#f' since this occurs when the file could not be opened. - Function: perror STRING Prints on standard error output the argument STRING, a colon, followed by a space, the error message corresponding to the current value of `errno' and a newline. The value returned is unspecified.  File: scm.info, Node: Internal State, Next: Miscellaneous Procedures, Prev: System Interface, Up: Standard Facilities Internal State ============== - Variable: errobj If SCM encounters a non-fatal error it aborts evaluation of the current form, prints a message explaining the error, and resumes the top level read-eval-print loop. The value of ERROBJ is the offending object if appropriate. ERROBJ is *not* set from calls to the procedure `error'. - Function: error ARG1 ARG2 ARG3 ... Alias for *Note error: (slib)System. Outputs an error message containing the arguments, aborts evaluation of the current form and resumes the top level read-eval-print loop. Error is defined in `Init.scm'; You change it to suit you. - Function: abort Resumes the top level Read-Eval-Print loop. - Function: verbose N Controls how much monitoring information is printed. If N is: 0 no prompt or information is printed. >= 1 a prompt is printed. >= 2 the CPU time is printed after each top level form evaluated. >= 3 messages about heap growth are printed. >= 4 garbage collection (*note Garbage Collection::.) messages are printed. >= 5 a warning will be printed for each top-level symbol which is defined more than one time. - Function: gc Scans all of SCM objects and reclaims for further use those that are no longer accessible. - Function: room - Function: room #T Prints out statistics about SCM's current use of storage. `(room #t)' also gives the hexadecimal heap segment and stack bounds. - Constant: *scm-version* Contains the version string (e.g. `4e2') of SCM. For other configuration constants and procedures *Note Configuration: (slib)Configuration.  File: scm.info, Node: Miscellaneous Procedures, Next: Time, Prev: Internal State, Up: Standard Facilities Miscellaneous Procedures ======================== - Function: try-load FILENAME If the string FILENAME names an existing file, the try-load procedure reads Scheme source code expressions and definitions from the file and evaluates them sequentially and returns `#t'. If not, try-load returns `#f'. The try-load procedure does not affect the values returned by `current-input-port' and `current-output-port'. - Variable: *load-pathname* Is set to the pathname given as argument to `load', `try-load', and `dyn:link' (*note Compiling And Linking::.). `*load-pathname*' is used to compute the value of *Note program-vicinity: (slib)Vicinity. - Function: line-number Returns the current line number of the file currently being loaded. - Function: eval OBJ Alias for *Note eval: (slib)System. - Function: eval-string STR Returns the result of reading an expression from STR and evaluating it. `eval-string' does not change `*load-pathname*' or `line-number'. - Function: load-string STR Reads and evaluates all the expressions from STR. As with `load', the value returned is unspecified. `eval-string' does not change `*load-pathname*' or `line-number'. - Function: vector-set-length! OBJECT LENGTH Change the length of string, vector, bit-vector, or uniform-array OBJECT to LENGTH. If this shortens OBJECT then the remaining contents are lost. If it enlarges OBJECT then the contents of the extended part are undefined but the original part is unchanged. It is an error to change the length of literal datums. The new object is returned. - Function: copy-tree OBJ *Note copy-tree: (slib)Tree Operations. This extends the SLIB version by also copying vectors. - Function: acons OBJ1 OBJ2 OBJ3 Returns (cons (cons obj1 obj2) obj3). The expression (set! a-list (acons key datum a-list)) adds a new association to a-list. - Function: terms This command displays the GNU General Public License. - Function: list-file FILENAME Displays the text contents of FILENAME.  File: scm.info, Node: Time, Next: Interrupts, Prev: Miscellaneous Procedures, Up: Standard Facilities Time ==== - Constant: internal-time-units-per-second Is the integer number of internal time units in a second. - Function: get-internal-run-time Returns the integer run time in internal time units from an unspecified starting time. The difference of two calls to `get-internal-run-time' divided by `internal-time-units-per-second' will give elapsed run time in seconds. - Function: get-internal-real-time Returns the integer time in internal time units from an unspecified starting time. The difference of two calls to `get-internal-real-time' divided by `interal-time-units-per-second' will give elapsed real time in seconds. - Function: current-time Returns the time since 00:00:00 GMT, January 1, 1970, measured in seconds. *Note current-time: (slib)Time. `current-time' is used in *Note Time: (slib)Time.  File: scm.info, Node: Interrupts, Next: Process Synchronization, Prev: Time, Up: Standard Facilities Interrupts ========== - Function: ticks N Returns the number of ticks remaining till the next tick interrupt. Ticks are an arbitrary unit of evaluation. Ticks can vary greatly in the amount of time they represent. If N is 0, any ticks request is canceled. Otherwise a `ticks-interrupt' will be signaled N from the current time. `ticks' is supported if SCM is compiled with the `ticks' flag defined. - Callback procedure: ticks-interrupt ... Establishes a response for tick interrupts. Another tick interrupt will not occur unless `ticks' is called again. Program execution will resume if the handler returns. This procedure should (abort) or some other action which does not return if it does not want processing to continue. - Function: alarm SECS Returns the number of seconds remaining till the next alarm interrupt. If SECS is 0, any alarm request is canceled. Otherwise an `alarm-interrupt' will be signaled SECS from the current time. ALARM is not supported on all systems. - Callback procedure: user-interrupt ... - Callback procedure: alarm-interrupt ... Establishes a response for `SIGINT' (control-C interrupt) and `SIGALRM' interrupts. Program execution will resume if the handler returns. This procedure should `(abort)' or some other action which does not return if it does not want processing to continue after it returns. Interrupt handlers are disabled during execution `system' and `ed' procedures. To unestablish a response for an interrupt set the handler symbol to `#f'. For instance, `(set! user-interrupt #f)'. - Callback procedure: out-of-storage ... - Callback procedure: could-not-open ... - Callback procedure: end-of-program ... - Callback procedure: hang-up ... - Callback procedure: arithmetic-error ... Establishes a response for storage allocation error, file opening error, end of program, SIGHUP (hang up interrupt) and arithmetic errors respectively. This procedure should (abort) or some other action which does not return if it does not want the default error message to also be displayed. If no procedure is defined for HANG-UP then END-OF-PROGRAM (if defined) will be called. To unestablish a response for an error set the handler symbol to `#f'. For instance, `(set! could-not-open #f)'.  File: scm.info, Node: Process Synchronization, Next: Files and Ports, Prev: Interrupts, Up: Standard Facilities Process Synchronization ======================= - Function: make-arbiter NAME Returns an object of type arbiter and name NAME. Its state is initially unlocked. - Function: try-arbiter ARBITER Returns `#t' and locks ARBITER if ARBITER was unlocked. Otherwise, returns `#f'. - Function: release-arbiter ARBITER Returns `#t' and unlocks ARBITER if ARBITER was locked. Otherwise, returns `#f'.  File: scm.info, Node: Files and Ports, Next: Soft Ports, Prev: Process Synchronization, Up: Standard Facilities Files and Ports =============== These procedures generalize and extend the standard capabilities in *Note Ports: (r4rs)Ports. - Function: open-file STRING MODES Returns a port capable of receiving or delivering characters as specified by the MODES string. If a file cannot be opened `#f' is returned. - Constant: open_read - Constant: open_write - Constant: open_both Contain modes strings specifying that a file is to be opened for reading, writing, and both reading and writing respectively. - Function: _ionbf MODESTR Returns a version of modestr which when open-file is called with it as the second argument will return an unbuffered port. A non-file input-port must be unbuffered in order for char-ready? to work correctly on it. The initial value of (current-input-port) is unbuffered if the platform supports it. - Function: close-port PORT Closes PORT. The same as close-input-port and close-output-port. - Function: open-io-file FILENAME - Function: close-io-port PORT These functions are analogous to the standard scheme file functions. The ports are open to FILENAME in read/write mode. Both input and output functions can be used with io-ports. An end of file must be read or a file-set-position done on the port between a read operation and a write operation or vice-versa. - Function: current-error-port Returns the current port to which diagnostic output is directed. - Function: with-error-to-file STRING THUNK THUNK must be a procedure of no arguments, and string must be a string naming a file. The file is opened for output, an output port connected to it is made the default value returned by current-error-port, and the THUNK is called with no arguments. When the thunk returns, the port is closed and the previous default is restored. With-error-to-file returns the value yielded by THUNK. - Function: with-input-from-port PORT THUNK - Function: with-output-to-port PORT THUNK - Function: with-error-to-port PORT THUNK These routines differ from with-input-from-file, with-output-to-file, and with-error-to-file in that the first argument is a port, rather than a string naming a file.  File: scm.info, Node: Soft Ports, Next: Syntax Extensions, Prev: Files and Ports, Up: Standard Facilities Soft Ports ========== A "soft-port" is a port based on a vector of procedures capable of accepting or delivering characters. It allows emulation of I/O ports. - Function: make-soft-port VECTOR MODES Returns a port capable of receiving or delivering characters as specified by the MODES string (*note open-file: Files and Ports.). VECTOR must be a vector of length 6. Its components are as follows: 0. procedure accepting one character for output 1. procedure accepting a string for output 2. thunk for flushing output 3. thunk for getting one character 4. thunk for closing port (not by garbage collection) For an output-only port only elements 0, 1, 2, and 4 need be procedures. For an input-only port only elements 3 and 4 need be procedures. Thunks 2 and 4 can instead be `#f' if there is no useful operation for them to perform. If thunk 3 returns `#f' or an `eof-object' (*note eof-object?: (r4rs)Input.) it indicates that the port has reached end-of-file. For example: (define stdout (current-output-port)) (define p (make-soft-port (vector (lambda (c) (write c stdout)) (lambda (s) (display s stdout)) (lambda () (display "." stdout)) (lambda () (char-upcase (read-char))) (lambda () (display "@" stdout))) "rw")) (write p p) => #  File: scm.info, Node: Syntax Extensions, Next: Low Level Syntactic Hooks, Prev: Soft Ports, Up: Standard Facilities Syntax Extensions ================= - Read syntax: #. EXPRESSION Is read as the object resulting from the evaluation of EXPRESSION. This substitution occurs even inside quoted structure. In order to allow compiled code to work with `#.' it is good practice to define those symbols used inside of EXPRESSION with `#.(define ...)'. For example: #.(define foo 9) => # '(#.foo #.(+ foo foo)) => (9 18) - Read syntax: #+ FEATURE FORM If feature is `provided?' (by `*features*') then FORM is read as a scheme expression. If not, then FORM is treated as whitespace. Feature is a boolean expression composed of symbols and `and', `or', and `not' of boolean expressions. For more information on `provided?' and `*features*', *Note Require: (slib)Require. - Read syntax: #- FEATURE FORM is equivalent to `#+(not feature) expression'. - Read syntax: #' FORM is equivalent to FORM (for compatibility with common-lisp). - Read syntax: #| ANY THING |# Is a balanced comment. Everything up to the matching `|#' is ignored by the `read'. Nested `#|...|#' can occur inside ANY THING. - Read syntax: #! ANY THING On the first line of a file will be ignored when loaded by SCM. This makes SCM files usable as POSIX shell scripts if the first line is: #!/usr/local/bin/scm When such a file is invoked it executes /usr/local/bin/scm with the name of this file as the first argument. The following shell script will print factorial of its argument: #!/usr/local/bin/scm ;;; -*-scheme-*- tells emacs this is a scheme file. (define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n))))) (display (fact (string->number (caddr (program-arguments))))) (newline) (quit) This technique has some drawbacks: * Some Unixes limit the length of the `#!' interpreter line to the size of an object file header, which can be as small as 32 bytes. * A full, explicit pathname must be specified, perhaps requiring more than 32 bytes and making scripts vulnerable to programs being moved. The following approach solves both problems - at the expense of slightly slower startup. `type;' should appear on every line to be executed by the shell. These lines do not have the length restriction mentioned above. Also, `/bin/sh' searches the directories listed in the `PATH' environment variable for `scm', eliminating the need to know absolute locations in order to invoke a program. #!/bin/sh type;exec scm $0 $* ;;; -*-scheme-*- tells emacs this is a scheme file. (define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n))))) (display (fact (string->number (caddr (program-arguments))))) (newline) (quit) - Special Form: defined? SYMBOL Equivalent to `#t' if SYMBOL is a syntactic keyword (such as `if') or a symbol with a value in the top level environment (*note Variables and regions: (r4rs)Variables and regions.). Otherwise equivalent to `#f'. - Special Form: defvar IDENTIFIER INITIAL-VALUE If IDENTIFIER is unbound in the top level environment, then IDENTIFIER is `define'd to the result of evaluating the form INITIAL-VALUE as if the `defvar' form were instead the form `(define identifier initial-value)' . If IDENTIFIER already has a value, then INITIAL-VALUE is *not* evaluated and IDENTIFIER's value is not changed. SCM also supports the following constructs from Common Lisp: `defmacro', `macroexpand', `macroexpand-1', and `gentemp'. *Note Defmacro: (slib)Defmacro.  File: scm.info, Node: Low Level Syntactic Hooks, Prev: Syntax Extensions, Up: Standard Facilities Low Level Syntactic Hooks ========================= - Callback procedure: read:sharp C PORT If a # followed by a character (for a non-standard syntax) is encountered by `read', `read' will call the value of the symbol `read:sharp' with arguments the character and the port being read from. The value returned by this function will be the value of `read' for this expression unless the function returns `#' in which case the expression will be treated as whitespace. `#' is the value returned by the expression `(if #f #f)'. *Note:* When adding new # syntaxes, have your code save the previous value of `read:sharp' when defining it. Call this saved value if an invocation's syntax is not recognized. This will allow `#+', `#-', `#!', and *Note Uniform Array::s to still be supported (as they use `read:sharp'). - Function: procedure->syntax PROC Returns a "macro" which, when a symbol defined to this value appears as the first symbol in an expression, returns the result of applying PROC to the expression and the environment. - Function: procedure->macro PROC - Function: procedure->memoizing-macro PROC Returns a "macro" which, when a symbol defined to this value appears as the first symbol in an expression, evaluates the result of applying PROC to the expression and the environment. The value returned from PROC which has been passed to `PROCEDURE->MEMOIZING-MACRO' replaces the form passed to PROC. For example: (define trace (procedure->macro (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x)))))) (trace foo) == (set! foo (tracef foo 'foo)). An "environment" is a list of "environment frames". There are 2 types of environment frames: `((lambda (variable1 ...) ...) value1 ...)' `(let ((variable1 value1) (variable2 value2) ...) ...)' `(letrec ((variable1 value1) ...) ...)' result in a single enviroment frame: ((variable1 ...) value1 ...) `(let ((variable1 value1)) ...)' `(let* ((variable1 value1) ...) ...)' result in an environment frame for each variable: (variable1 . value1) (variable2 . value2) ... - Special Form: @apply PROCEDURE ARGUMENT-LIST Returns the result of applying procedure to argument-list. (apply procedure argument-list) will produce the same result. - Special Form: @call-with-current-continuation PROCEDURE) Returns the result of applying procedure to the current continuation. `(call-with-current-continuation PROCEDURE)' will have the same effect.  File: scm.info, Node: Packages, Next: Guile Facilities, Prev: Standard Facilities, Up: Top Packages ******** * Menu: * Compiling And Linking:: and Dynamic Linking * Numeric:: * Arrays:: As in APL * I/O-Extensions:: 'i/o-extensions * Posix Extensions:: * Regular Expression Pattern Matching:: 'regex * Line Editing:: * Curses:: Screen Control * Sockets:: Cruise the Net