SCHEME(1)

📦
version 10.3.0 · 17 versions
, in epel 10, fedora 43, fedora 44

💖 SCHEME(1) — General Commands Manual 💖

okay bestie, buckle up, because this is the manual page for Chez Scheme, and it's a whole thing. it lives in section 1 of the manual, so it's a user command. we're doing this in four parts, so don't go anywhere. 🫶

✨ NAME ✨

  • scheme — Chez Scheme
  • petite — Petite Chez Scheme

🌸 SYNOPSIS 🌸

scheme [ options ] file ...
petite [ options ] file ...

🦋 DESCRIPTION 🦋

okay so. Chez Scheme is a programming language based on R6RS Scheme, and it's also a high-performance implementation of that language. the way it works is it compiles source expressions incrementally to machine code, so you get the speed of compiled code but inside an interactive system. it's giving best of both worlds, no cap. ✨

Petite Chez Scheme is an interpreted version of Chez Scheme. you can use it as a run-time environment for Chez Scheme applications, or as a stand-alone Scheme system. here's the tea: with the one exception that the compiler is not present, Petite Chez Scheme is 100% compatible with Chez Scheme. interpreted code is fast in Petite Chez Scheme, but generally not nearly as fast as compiled code. also, debugging and profiling support is limited for interpreted code. 😭

Scheme is normally used interactively. the system prompts you with a right angle bracket (>) at the beginning of each input line. you can enter any Scheme expression. the system evaluates the expression and prints the result. after printing the result, it prompts again for more input. to exit, you can type Control-D or use the procedure exit. 💅

👑 COMMAND-LINE OPTIONS 👑

Chez Scheme recognizes the following command line options:

  • -q, --quiet — suppress greeting and prompts. 🤫
  • --script file — run file as a shell script.
  • --program file — run rnrs program in file as a shell script.
  • --libdirs dir:... — set library directories to dir:....
  • --libexts ext:... — set library extensions to ext:....
  • --compile-imported-libraries — compile libraries before loading them.
  • --import-notify — enable import search messages.
  • --optimize-level 0 | 1 | 2 | 3 — set optimize level to 0, 1, 2, or 3.
  • --debug-on-exception — on uncaught exception, call debug.
  • --eedisable — disables the expression editor.
  • --eehistory off | file — set expression-editor history file, or disable restore and save of history.
  • --enable-object-counts — have collector maintain object counts.
  • --retain-static-relocation — keep reloc information for compute-size, etc.
  • -b file, --boot file — load boot code from file.
  • --verbose — trace boot search process. 👀
  • --version — print version and exit.
  • --help — print brief command-line help and exit.
  • -- — pass all remaining command-line arguments through to Scheme.
⚠️ okay so these next ones are recognized, but they make the system print an error message and exit, because saved heaps are not presently supported. rip. 💀
  • -h file, --heap file
  • -s[level] file, --saveheap[level] file
  • -c, --compact

any remaining command-line arguments are treated as the names of files to be loaded before Chez Scheme begins interacting with the user (see COMMAND-LINE FILE ARGUMENTS), unless --script or --program is present — in that case, the remaining arguments are made available to the script via the command-line parameter (see SCHEME SCRIPTS). 🎀

☕ WAITERS and CAFES ☕

so the interaction of the system with the user is performed by a Scheme program called a waiter, running in a program state called a cafe. the waiter merely prompts, reads, evaluates, prints and loops back for more. iconic behavior honestly. 🍓

it's possible to open up a chain of Chez Scheme cafes by invoking the new-cafe procedure with no arguments. new-cafe is also one of the options when an interrupt occurs. each cafe has its own reset and exit procedures. exiting from one cafe in the chain returns you to the next one back, and so on, until the entire chain closes and you leave the system altogether. sometimes it's useful to interrupt a long computation by typing the interrupt character, enter a new cafe to execute something (perhaps to check a status variable set by computation), and exit the cafe back to the old computation. main character multitasking fr fr. 💅

you can tell what level you're at by the number of angle brackets in the prompt — one for level one, two for level two, and so on. three angle brackets in the prompt means you'd have to exit from three cafes to get out of Chez Scheme. 😳 if you wish to abort from Chez Scheme and you're several cafes deep, the procedure abort leaves the system directly.

you can exit the system by typing the end-of-file character (normally Control-D) or by using the procedure exit. typing Control-D is equivalent to (exit), (exit (void)), or (exit 0), each of which is considered a "normal exit". ✨

🔥 DEBUGGER 🔥

ordinarily, if an exception occurs during interactive use of the system, the default exception handler displays the condition with which the exception was raised, saves it for possibly later use by the debugger, and prints the message "type (debug) to enter the debugger." once in the debugger, the user has the option of inspecting the raise continuation, i.e., the stack frames of the pending calls. 👀

⚠️ but heads up: when an exception occurs in a script or top level program, or when the standard input and/or output ports are redirected, the default exception handler does not save the continuation of the exception and does not print the "type (debug)" message. so don't be confused when it's quiet. 😭

if the parameter debug-on-exception is set to #t, however, the default exception handler directly invokes debug, whether running interactively or not, and even when running a script or top-level program. the --debug-on-exception option may be used to set debug-on-exception to #t from the command line, which is particularly useful when debugging scripts or top-level programs run via the --script or --program options. 🛠️✨

none of this applies to exceptions raised with a non-serious (warning) condition, for which the default exception handler simply displays the condition and returns. easy come easy go. 🌈

⌨️ KEYBOARD INTERRUPTS ⌨️

running programs may be interrupted by typing the interrupt character (normally Control-C). in response, the system enters a break handler, which prompts for input with a break> prompt. several commands may be issued to the break handler, including:

  • e — exit from the handler and continue
  • r — reset to the current cafe
  • a — abort Chez Scheme
  • n — enter a new cafe
  • i — inspect the current continuation
  • s — display statistics about the interrupted program

while typing an expression to the waiter, the interrupt character simply resets to the current cafe. 🧚

(part 1 done bestie, more coming 💜)

✨ EXPRESSION EDITOR ✨

Okay so when you're using Chez Scheme interactively in a shell window, the waiter's “prompt and read” procedure is lowkey a whole vibe — it employs an expression editor that lets you enter and edit single- and multiple-line expressions, automatically indents them as you go, and supports name-completion based on the identifiers defined in your interactive environment. 💅

The expression editor also keeps a history of expressions you typed during and across sessions, and it supports tcsh(1)-like history movement and search commands. Other editing commands? Simple cursor movement via arrow keys, deletion of characters via backspace and delete, and movement, deletion, and other commands using mostly emacs key bindings. No cap.

Heads up bestie: the expression editor does not run if the TERM environment variable is not set, if the standard input or output files have been redirected, or if the --eedisable command-line option has been used. 💀

The history is saved across sessions, by default, in the file “$HOME/.chezscheme_history”. You can change that default by setting the “CHEZSCHEME_HISTORY” environment variable. And the --eehistory command-line option can be used to specify a different location for the history file or to disable the saving and restoring of the history file. Periodt.

Keys for nearly all printing characters (letters, digits, and special characters) are “self inserting” by default. The open parenthesis, close parenthesis, open bracket, and close bracket keys are self inserting as well, but they also cause the editor to “flash” to the matching delimiter, if any. And when you type a close parenthesis or close bracket, it's automatically corrected to match the corresponding open delimiter, if any. Slay.

Key bindings for other keys and key sequences initially recognized by the expression editor are given below, organized into groups by function. Some keys or key sequences serve more than one purpose depending upon context. For example, tab is used both for identifier completion and for indentation. Such bindings are shown in each applicable functional group. Multiple-key sequences are displayed with hyphens between the keys of the sequences, but these hyphens should not be entered. When two or more key sequences perform the same operation, the sequences are shown separated by commas.

🌸 Newlines, acceptance, exiting, and redisplay 🌸

  • enter, ^M — accept balanced entry if used at end of entry; else add a newline before the cursor and indent
  • ^J — accept entry unconditionally
  • ^O — insert newline after the cursor and indent
  • ^D — exit from the waiter if entry is empty; else delete character under cursor
  • ^Z — suspend to shell if shell supports job control
  • ^L — redisplay entry
  • ^L-^L — clear screen and redisplay entry

🦋 Basic movement and deletion 🦋

  • left, ^B — move cursor left
  • right, ^F — move cursor right
  • up, ^P — move cursor up; from top of unmodified entry, move to preceding history entry.
  • down, ^N — move cursor down; from bottom of unmodified entry, move to next history entry.
  • ^D — delete character under cursor if entry not empty; else exit from the waiter.
  • backspace, ^H — delete character before cursor
  • delete — delete character under cursor

🎀 Line movement and deletion 🎀

  • home, ^A — move cursor to beginning of line
  • end, ^E — move cursor to end of line
  • ^K, esc-k — delete to end of line or, if cursor is at the end of a line, join with next line
  • ^U — delete contents of current line

When used on the first line of a multiline entry of which only the first line is displayed, i.e., immediately after history movement, ^U deletes the contents of the entire entry, like ^G (described below). 😮

💖 Expression movement and deletion 💖

  • esc-^F — move cursor to next expression
  • esc-^B — move cursor to preceding expression
  • esc-] — move cursor to matching delimiter
  • ^] — flash cursor to matching delimiter
  • esc-^K, esc-delete — delete next expression
  • esc-backspace, esc-^H — delete preceding expression

🧚 Entry movement and deletion 🧚

  • esc-< — move cursor to beginning of entry
  • esc-> — move cursor to end of entry
  • ^G — delete current entry contents
  • ^C — delete current entry contents; reset to end of history

🌈 Indentation 🌈

  • tab — re-indent current line if identifier prefix not just entered; else insert identifier completion
  • esc-tab — re-indent current line unconditionally
  • esc-q, esc-Q, esc-^Q — re-indent each line of entry

⭐ Identifier completion ⭐

  • tab — insert identifier completion if just entered identifier prefix; else re-indent current line
  • tab-tab — show possible identifier completions at end of identifier just typed, else re-indent
  • ^R — insert next identifier completion

If at end of existing identifier, i.e., not one just typed, the first tab re-indents, the second tab inserts identifier completion, and the third shows possible completions. 💅

🍓 History movement 🍓

  • up, ^P — move to preceding entry if at top of unmodified entry; else move up within entry
  • down, ^N — move to next entry if at bottom of unmodified entry; else move down within entry
  • esc-up, esc-^P — move to preceding entry from unmodified entry
  • esc-down, esc-^N — move to next entry from unmodified entry
  • esc-p — search backward through history for given prefix
  • esc-n — search forward through history for given prefix
  • esc-P — search backward through history for given string
  • esc-N — search forward through history for given string

To search, enter a prefix or string followed by one of the search key sequences. Follow with additional search key sequences to search further backward or forward in the history. For example, enter “(define” followed by one or more esc-p key sequences to search backward for entries that are definitions, or “(define” followed by one or more esc-P key sequences for entries that contain definitions. 🔍

🫶 Word and page movement 🫶

  • esc-f, esc-F — move cursor to end of next word
  • esc-b, esc-B — move cursor to start of preceding word
  • ^X-[ — move cursor up one screen page
  • ^X-] — move cursor down one screen page

💜 Inserting saved text 💜

  • ^Y — insert most recently deleted text
  • ^V — insert contents of window selection/paste buffer

👑 Mark operations 👑

  • ^@, ^space, ^^ — set mark to current cursor position
  • ^X-^X — move cursor to mark, leave mark at old cursor
  • ^W — delete between current cursor position and mark

🔥 Command repetition 🔥

  • esc-^U — repeat next command four times
  • esc-^U-n — repeat next command n times

✨ TOP-LEVEL ENVIRONMENT SEMANTICS ✨

Upon startup, the “interaction environment” used to hold the top-level bindings for user-defined variables and other identifiers contains an initial set of bindings, some standard and some specific to Chez Scheme. Any initial identifier binding may be replaced by redefining the identifier with a normal top-level definition. For example, the initial binding for cons can be replaced with one that performs a "reverse cons" as follows. 👇

(define cons (lambda (x y) (import scheme) (cons y x)))

Code entered into the REPL or loaded from a file prior to this point will still use the original binding for cons. If you want it to use the new binding, you must reenter or reload the code. Furthermore, the initial bindings for variables like cons are immutable, so you cannot assign one (e.g., via set! or trace) without first defining it. This allows the system to check to make sure it receives the expected two arguments at compile time and generate inline code to allocate the pair. This is not the case if cons is redefined, even if redefined to have the same value, since its value can be changed via set! at any time during a program run. 💀

✨ COMMAND-LINE FILE ARGUMENTS ✨

In the normal mode of operation, the file names on the command line (except for the arguments to the various command-line options) are loaded before Chez Scheme begins interacting with the user. Each of the expressions in the loaded files is executed just as if it were typed by the user in response to a prompt. If you wish to load a set of definitions each time, consider setting up a shell script to load the file “.schemerc” from your home directory:

scheme ${HOME}/.schemerc $*

If you have a substantial number of definitions to load each time, it might be worthwhile to compile the .schemerc file (that is, compile the definitions and name the resulting object file .schemerc). 🛠️

Typically, a Scheme programmer creates a source file of definitions and other Scheme forms using an editor such as vi(1) or emacs(1) and loads the file into Scheme to test them. The conventional filename extension for Chez Scheme source files is .ss. Such a file may be loaded during a session by typing (load “filename”), or by specifying the filename on the command line as mentioned above. Any expression that may be typed interactively may be placed in a file to be loaded. ✨

✨ SCHEME SCRIPTS ✨

When the “--script” option is used, the named file is treated as a Scheme shell script, and the script name and remaining command-line arguments are made available via the parameter “command-line”. To support executable shell scripts, the system ignores the first line of a loaded script if it begins with #! followed by a space or forward slash. For example, the following script prints its command-line arguments. 🎬

#! /usr/bin/scheme --script
(for-each
  (lambda (x) (display x) (newline))
  (cdr (command-line)))

✨ RNRS TOP-LEVEL PROGRAMS ✨

okay so --program is literally the same vibe as --script except the script file gets treated as an RNRS top-level program 💅. Here's a top-level program that prints its command-line arguments, same energy as the script up above:

#! /usr/bin/scheme --program
(import (rnrs))
(for-each
  (lambda (x) (display x) (newline))
  (cdr (command-line)))

You can use scheme-script in place of scheme --program, possibly prefixed by /usr/bin/env — that's what the nonnormative R6RS appendix on running top-level programs as scripts suggests 🫶. Basically the first line of your top-level program can become this instead:

#! /usr/bin/env scheme-script

If a top-level program depends on libraries other than the ones built into Chez Scheme, use the --libdirs option to say which source and object directories to search 👀. Same deal: if a library your top-level program depends on has an extension that isn't one of the standard ones, the --libexts option lets you add extra extensions to search.

These options set the corresponding Chez Scheme parameters library-directories and library-extensions. Both parameters hold lists of pairs of strings, no cap:

  • In each library-directories pair, the first string names a source-file root directory and the second names the matching object-file root directory.
  • In each library-extensions pair, the first string names a source-file extension and the second names the matching object-file extension.

The full path of a library source or object file is the source or object root, then the components of the library name prefixed by slashes, with the library extension tacked on the end 🎀. So for root /usr/lib/scheme, library name (app lib1), and extension .sls, the full path is /usr/lib/scheme/app/lib1.sls.

The format of the arguments to --libdirs and --libexts is identical, bestie: a sequence of substrings separated by a single separator character 🦋. That separator is a colon (:) — except on Windows, where it's a semi-colon (;). Between single separators, the source and object strings, if both are specified, are separated by two separator characters. If a single separator character sits at the very end of the string, the pairs you specified get added to the existing list; otherwise they replace the existing list. The parameters get set after all boot files have been loaded ✨.

If multiple --libdirs options show up, all but the final one are ignored 🙈 — and if multiple --libexts options show up, all but the final are ignored too. If no --libdirs option appears and the CHEZSCHEMELIBDIRS environment variable is set, the string value of CHEZSCHEMELIBDIRS is treated as if it had been specified by a --libdirs option. Same logic, different variable: if no --libexts option appears and CHEZSCHEMELIBEXTS is set, the string value of CHEZSCHEMELIBEXTS is treated as if it came from a --libexts option 💖.

The library-directories and library-extensions parameters set by these options get consulted by the expander when it runs into an import for a library that hasn't been defined or loaded before 🔍. Here's the whole process, step by step:

  1. The expander builds a partial name from the list of components in the library name — like a/b for library (a b).
  2. It searches for that partial name in each pair of root directories, in order, trying each of the source extensions and then each of the object extensions in turn before it moves on to the next pair of root directories.
  3. If the partial name is an absolute pathname — like ~/.myappinit for a library named (~/.myappinit) — only that specified absolute path gets searched, first with each source extension, then with each object extension.

Now the moment of truth 💅: if the expander finds both a source file and its corresponding object file, and the object file is not older than the source file, it loads the object file. But if the object file doesn't exist, or the object file is older, or after loading the object file the expander figures out it was built using a library or include file that has changed since — then the source file gets loaded or compiled, depending on the value of the parameter compile-imported-libraries. If compile-imported-libraries is set to #t, the expander compiles the library via compile-library (which is described below). Otherwise, the expander just loads the source file. (And fun fact: loading the source file actually causes the code to be compiled, assuming the default value of current-eval, but the compiled code is not saved to an object file 😭.)

An exception is raised during this whole process if a source or object file exists but isn't readable, or if an object file can't be created. Not cute, but it happens.

You can watch the search process the expander uses when processing an import for a library that hasn't been loaded yet by setting the parameter import-notify to #t 👀. And you can set that parameter straight from the command line via the --import-notify command-line option. slay.

🌈 OPTIMIZE LEVELS 🌈

The --optimize-level option sets the initial value of the Chez Scheme optimize-level parameter to 0, 1, 2, or 3. The value is 0 by default.

At optimize levels 0, 1, and 2, the code the compiler generates is safe — meaning it generates full type and bounds checks 🛡️. At optimize level 3, the code generated by the compiler is unsafe, i.e., it may omit those checks.

Unsafe code is usually faster, but optimize level 3 should be used only for well-tested code, because the absence of type and bounds checks may result in invalid memory references, corruption of the Scheme heap (which may cause seemingly unrelated problems later 😭), system crashes, or other undesirable behaviors. Not the vibe. Be careful, bestie.

At present, there is no direct difference other than safety among optimize levels. that's it, that's the tea ☕

🛠️ COMPILING FILES 🛠️

Chez Scheme compiles source expressions as it sees them 👑. To speed up loading of a large file, you can compile the file with the output placed in an object file. So (compile-file "foo") compiles the expressions in the file foo.ss and places the resulting object code on the file foo.so ✨. Loading a pre-compiled file is literally no different from loading the source file, except loading is faster since the compilation is already done 💅.

To compile a program meant to be run with --program, use compile-program instead of compile-file:

  • compile-program preserves the first line unchanged if it begins with #! followed by a forward slash or a space.
  • Also, while compile-file compresses the resulting object file, compile-program does not do so if the #! line is present — so it can be recognized by the shell's script executor 🐚.

Any libraries the top-level program depends on, other than built-in libraries, must be compiled first via compile-file or compile-library. You can do that manually, or by setting the parameter compile-imported-libraries to #t before compiling the program 🫶.

To compile a script meant to be run with --script, use compile-script instead of compile-file. compile-script is like compile-program, but — like compile-file — it implements the interactive top-level semantics rather than the RNRS top-level program semantics 🌸.

👑 BOOT and HEAP FILES 👑

When Chez Scheme runs, it goes looking for one or more boot files to load 🔍. Boot files contain the compiled Scheme code that implements most of the Scheme system, including the interpreter, the compiler, and most libraries.

Boot files may be specified explicitly on the command line via -b options, or implicitly. In the simplest case, no -b options are given and the necessary boot files are loaded automatically based on the name of the executable ✨. For example, if the executable name is myapp, the system looks for myapp.boot in a set of standard directories. It also looks for and loads any subordinate boot files required by myapp.boot 🦋. Subordinate boot files are also loaded automatically for the first boot file explicitly specified via the command line. When multiple boot files are specified via the command line, each file must be listed before those that depend upon it ⚠️.

The --verbose option can be used to trace the boot file searching process, and it must appear before any boot arguments for which search tracing is desired 👀.

Ordinarily the search for boot files is limited to a set of default installation directories, but you can override that by setting the SCHEMEHEAPDIRS environment variable 💖. SCHEMEHEAPDIRS should be a colon-separated list of directories, listed in the order they should be searched. Within each directory:

  • The two-character escape sequence %v is replaced by the current version.
  • The two-character escape sequence %m is replaced by the machine type.
  • A percent followed by any other character is replaced by the second character; in particular, %% is replaced by %, and %: is replaced by :.

If SCHEMEHEAPDIRS ends in a non-escaped colon, the default directories are searched after those in SCHEMEHEAPDIRS; otherwise, only those listed in SCHEMEHEAPDIRS are searched 😳. Under Windows, semi-colons are used in place of colons.

Boot files consist of a header followed by ordinary compiled code, and they may be created with make-boot-file. For example:

(make-boot-file "myapp.boot" '("petite")
  "myapp1.so" "myapp2.so")

creates a boot file containing the code from myapp1.so and myapp2.so, with a header identifying petite.boot as a boot file upon which the new boot file depends 🎀. Source files can be provided as well, and they're compiled on-the-fly by make-boot-header.

You can list multiple alternatives for the boot file upon which the new boot file depends, like so:

(make-boot-file "myapp.boot" '("petite" "scheme")
  "myapp1.so" "myapp2.so")

When possible, both scheme and petite should be specified when creating a boot file for an application — as shown above — so that the application can run in either Petite Chez Scheme or Chez Scheme 👑💅. If the application requires the use of the compiler, then just scheme should be specified.

If the new boot file is meant to be a base boot file — i.e., one that does not depend on another boot file — then petite.boot (or some other boot file created from petite.boot) should be listed first among the input files:

(make-boot-file "myapp.boot" '() "petite.boot"
  "myapp1.so" "myapp2.so")

📚 DOCUMENTATION 📚

okay bestie, the complete docs for Chez Scheme come in two parts, and you're gonna want both:

  • The Scheme Programming Language, 4th Edition
  • The Chez Scheme Version 9 User's Guide

The first one? You can get it as an actual printed book</> from MIT Press. And for both of them, there are links to online versions hanging out at https://cisco.github.io/ChezScheme/ ✨

Also!! There's a whole stash of example Scheme programs in the examples directory (peep FILES down below 👇), and they range from a lil baby factorial procedure all the way up to a genuinely somewhat complex unification algorithm. Ngl, reading through examples and just running them is like the best possible way to start learning Scheme. It's giving study buddy energy fr fr 💖

🌍 ENVIRONMENT 🌍

The environment variable SCHEMEHEAPDIRS (yeah, the one from above 👆) can be set to a colon-separated list of directories — semi-colon separated if you're on Windows — and Scheme will search through them looking for boot files 🦋

The environment variable CHEZSCHEME_HISTORY (also from above 👆) can be set to the location you want used as the default history file location 📝

📁 FILES 📁

  • /usr/bin/scheme — the executable file 💅
  • /usr/bin/petite — the executable file 🎀
  • /usr/bin/scheme-script — the executable file ✨
  • /usr/lib64/csv10.3.0/examples — the example program library 🌸
  • /usr/lib64/csv10.3.0/ta6le — the boot and include files 👑

👀 SEE ALSO 👀

  • R. Kent Dybvig, The Scheme Programming Language, 4th Edition, MIT Press (2009), http://www.scheme.com/tspl4/.
  • Chez Scheme Version 9 User's Guide, Cisco Systems, Inc.
  • Michael Sperber, R. Kent Dybvig, Matthew Flatt, and Anton van Straaten, eds., “Revised^6 Report on the Algorithmic Language Scheme,” (2007), http://www.r6rs.org/.
  • Daniel P. Friedman and Matthias Felleisen, The Little Schemer, fourth edition, MIT Press (1996).
  • Harold Abelson and Gerald J. Sussman with Julie Sussman, Structure and Interpretation of Computer Programs, Second Edition, MIT press (1996).
bestie that reading list is iconic — The Little Schemer and SICP together is a full personality glow-up, no cap 🧚

💖 AUTHOR 💖

Copyright 2025 Cisco Systems, Inc. Licensed under the Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0)

and that's a wrap on the whole page, bestie!! 🫶 this was Chez Scheme Version 10.3.0, dated October 2025, and it lives in the manual as SCHEME(1). go forth and slay some s-expressions, ily, bye 💅✨

📦 where this page comes from