SCHEME(1)

📦 version 10.3.0, in alpine 3.24

💖 SCHEME(1) — chez & petite 💖

✨ NAME ✨

  • chez — Chez Scheme
  • petite — Petite Chez Scheme

🌸 SYNOPSIS 🌸

chez [ options ] file ...
petite [ options ] file ...

💅 DESCRIPTION 💅

Okay bestie, so Chez Scheme is literally a programming language based on R6RS Scheme — and also a high-performance implementation of that language, no cap. It compiles source expressions incrementally to machine code, which gives you the speed of compiled code in an interactive system. Iconic behavior, honestly. ✨

Petite Chez Scheme is the interpreted version of Chez Scheme that may be used as a run-time environment for Chez Scheme applications or as a stand-alone Scheme system. With the 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. Debugging and profiling support is also limited for interpreted code. 🫶

Scheme is normally used interactively. The system prompts the user with a right angle bracket (>) at the beginning of each input line. Any Scheme expression may be entered. The system evaluates the expression and prints the result. After printing the result, the system prompts again for more input. The user can exit the system by typing Ctrl+D or by using the procedure exit. 💀✨

🎀 COMMAND-LINE OPTIONS 🎀

Chez Scheme recognizes the following command line options, and yes, I’m listing every single one:

  • -q, --quiet — Suppress greeting and prompts. Lowkey peaceful. 🤫
  • --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. Compile first, ask later. 🔥
  • --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.
⚠️ Bestie, the following options are recognized but cause the system to print an error message and exit because saved heaps are not presently supported. So they exist, but they are not giving usable heap energy in this build:
  • -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 which case the remaining arguments are made available to the script via the command-line parameter (see SCHEME SCRIPTS). 🦋

🧚 WAITERS and CAFES 🧚

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. It is 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 is 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 energy, honestly. 💅

You can tell what level you are 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 would have to exit from three cafes to get out of Chez Scheme. If you wish to abort from Chez Scheme and you are several cafes deep, the procedure abort leaves the system directly. 🌀

You can exit the system by typing the end-of-file character (normally Ctrl+D) or by using the procedure exit. Typing Ctrl+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. 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. 😭

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

⭐ 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. 🌸

✨ EXPRESSION EDITOR ✨

So when Chez Scheme is chillin' in a shell window interactively, the waiter's "prompt and read" procedure pulls up an expression editor — and bestie, it's lowkey iconic. It lets you type and edit single- and multiple-line expressions, auto-indents stuff as you go, and does name-completion based on the identifiers that actually exist in your interactive environment. It also keeps a history of everything you typed during and across sessions, with tcsh(1)-style history movement and search commands. Other editing commands include simple cursor movement via the arrow keys, deleting characters with backspace and delete, and moving/deleting/doing-other-stuff with mostly emacs key bindings.

The expression editor does not run if the TERM environment variable isn't set, if standard input or output have been redirected, or if you used the --eedisable command-line option. No vibe check, no editor. 💀

The history gets saved across sessions by default in the file $HOME/.chezscheme_history (well, “$HOME/.chezscheme_history” — same thing, bestie, the quotes are just the manpage being dramatic). You can change that default by setting the CHEZSCHEME_HISTORY environment variable, and the --eehistory command-line option lets you point the history file somewhere else entirely — or straight up disable the saving and restoring of it.

🎀 The keys, the tea ☕

Keys for nearly all printing characters (letters, digits, special characters) are "self inserting" by default. The open parenthesis, close parenthesis, open bracket, and close bracket keys are self inserting too, but they also make the editor "flash" to the matching delimiter, if there is one. And when you type a close parenthesis or close bracket, it automatically gets corrected to match the corresponding open delimiter, if any. It's giving ✨attention to detail✨.

Key bindings for the other keys and key sequences the expression editor recognizes initially are below, grouped by function. Some keys or key sequences do more than one thing depending on context — like tab, which is both identifier completion and indentation. Those show up in every applicable group, so don't come for me about the duplicates. 💅

Multiple-key sequences are shown with hyphens between the keys, but do not type the hyphens, bestie, I'm begging. And when two or more key sequences do the same thing, they're separated by commas.

🌸 Newlines, acceptance, exiting, and redisplay

  • enter, ^M — accept a balanced entry if you use it at the end of the entry; otherwise it adds a newline before the cursor and indents.
  • ^J — accept the entry unconditionally. No notes, periodt.
  • ^O — insert a newline after the cursor and indent.
  • ^D — exit from the waiter if the entry is empty; otherwise delete the character under the cursor.
  • ^Z — suspend to the shell, if the shell supports job control.
  • ^L — redisplay the entry.
  • ^L-^L — clear the screen and redisplay the entry.

🦋 Basic movement and deletion

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

🌈 Line movement and deletion

  • home, ^A — move the cursor to the beginning of the line.
  • end, ^E — move the cursor to the end of the line.
  • ^K, esc-k — delete to the end of the line or, if the cursor is at the end of a line, join with the next line.
  • ^U — delete the contents of the current line.
Heads up bestie: 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, just like ^G (described below). Sneaky. 🙈

🧚 Expression movement and deletion

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

🍓 Entry movement and deletion

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

💜 Indentation

  • tab — re-indent the current line if an identifier prefix was not just entered; otherwise insert identifier completion.
  • esc-tab — re-indent the current line, unconditionally, no matter what.
  • esc-q, esc-Q, esc-^Q — re-indent every line of the entry.

👑 Identifier completion

  • tab — insert identifier completion if you just entered an identifier prefix; otherwise re-indent the current line.
  • tab-tab — show possible identifier completions at the end of the identifier you just typed; otherwise re-indent.
  • ^R — insert the next identifier completion.
If you're at the end of an existing identifier — like, not one you just typed — then the first tab re-indents, the second tab inserts identifier completion, and the third shows possible completions. Three-tab lore. ⭐

💖 History movement

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

To search, you enter a prefix or string followed by one of the search key sequences. Then follow with more search key sequences to keep searching 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 enter (define followed by one or more esc-P key sequences for entries that contain definitions. Chef's kiss. 😭

🫶 Word and page movement

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

🔥 Inserting saved text

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

⭐ Mark operations

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

🌟 Command repetition

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

🦋 TOP-LEVEL ENVIRONMENT SEMANTICS 🦋

At startup, the "interaction environment" that holds the top-level bindings for user-defined variables and other identifiers comes preloaded with an initial set of bindings — some standard, some Chez-Scheme-specific. Any initial identifier binding can be replaced by redefining that identifier with a normal top-level definition. For example, you can replace the initial binding for cons with one that does a "reverse cons", like this:

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

Here's the catch, bestie: 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 have to reenter or reload the code. And on top of that, the initial bindings for variables like cons are immutable, so you can't assign one (e.g., via set! or trace) without first defining it. Why? Because that's what lets the system check at compile time that it's getting the expected two arguments and generate inline code to allocate the pair. ✨ Slay. ✨ But that's not the case if cons gets redefined — even if you redefine it to have the same value — because its value can be changed via set! at any time during a program run. So like... the optimization is gone forever. F. 💀

🌈 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, bestie, read carefully) are loaded before Chez Scheme starts interacting with the user. Every expression in the loaded files gets executed just as if the user had typed it at a prompt. So if you want to load a bunch of definitions every single time, consider setting up a shell script to load the .schemerc file from your home directory:

chez ${HOME}/.schemerc $*

And if you have a substantial number of definitions to load each time, it might be worth your while 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 like vi(1) or emacs(1), then loads that file into Scheme to test them. The conventional filename extension for Chez Scheme source files is .ss. You can load such a file 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. Literally any of them. Go off. 👑

💅 SCHEME SCRIPTS 💅

When the --script option is used, the named file is treated as a Scheme shell script, and the script name plus the 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. Iconic behavior, honestly.

For example, the following script prints its command-line arguments:

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

✨ RNRS TOP-LEVEL PROGRAMS ✨

Okay so --program is literally --script's cousin, no cap: it works the same way except the script file is treated as an RNRS top-level program. The following RNRS top-level program prints its command-line arguments, just like the script above, bestie:

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

And scheme-script may be used in place of scheme --program, possibly prefixed by /usr/bin/env as suggested in the nonnormative R6RS appendix on running top-level programs as scripts. So the first line of the top-level program may be replaced with the following:

#! /usr/bin/env chez-script

If a top-level program depends on libraries other than those built into Chez Scheme, the --libdirs option can be used to specify which source and object directories to search. Similarly, if a library that a top-level program depends on has an extension other than one of the standard extensions, the --libexts option can be used to specify additional extensions to search.

These options set the corresponding Chez Scheme parameters library-directories and library-extensions. The values of both parameters are lists of pairs of strings. The first string in each library-directories pair identifies a source-file root directory, and the second identifies the corresponding object-file root directory. Similarly, the first string in each library-extensions pair identifies a source-file extension, and the second identifies the corresponding object-file extension. The full path of a library source or object file consists of the source or object root followed by the components of the library name prefixed by slashes, with the library extension added on the end. For example, 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 the same: a sequence of substrings separated by a single separator character. The separator character is a colon (:), except under Windows where it is 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 appears at the end of the string, the specified pairs are added to the existing list; otherwise, the specified pairs replace the existing list. The parameters are set after all boot files have been loaded.

If multiple --libdirs options appear, all but the final one are ignored, and if multiple --libexts options appear, all but the final are ignored. If no --libdirs option appears and the CHEZSCHEMELIBDIRS environment variable is set, the string value of CHEZSCHEMELIBDIRS is treated as if it were specified by a --libdirs option. Similarly, if no --libexts option appears and the CHEZSCHEMELIBEXTS environment variable is set, the string value of CHEZSCHEMELIBEXTS is treated as if it were specified by a --libexts option.

The library-directories and library-extensions parameters set by these options are consulted by the expander when it encounters an import for a library that has not previously been defined or loaded. The expander first constructs a partial name from the list of components in the library name, e.g., a/b for library (a b). It then searches for the partial name in each pair of root directories, in order, trying each of the source extensions then each of the object extensions in turn before moving onto the next pair of root directories. If the partial name is an absolute pathname, e.g., ~/.myappinit for a library named (~/.myappinit), only the specified absolute path is searched, first with each source extension, then with each object extension. If the expander finds both a source file and its corresponding object file, and the object file is not older than the source file, the expander loads the object file. If the object file does not exist, if the object file is older, or if after loading the object file, the expander determines it was built using a library or include file that has changed, the source file is 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 loads the source file. (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 process if a source or object file exists but is not readable or if an object file cannot be created.

The search process used by the expander when processing an import for a library that has not yet been loaded can be monitored by setting the parameter import-notify to #t. This parameter can be set from the command line via the --import-notify command-line option. 👀✨

💅 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, code generated by the compiler is safe, i.e., it generates full type and bounds checks. At optimize-level 3, code generated by the compiler is unsafe, i.e., it may omit these checks. Unsafe code is usually faster, but optimize-level 3 should be used only for well-tested code since 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. 😭💀

At present, there is no direct difference other than safety among optimize levels.

🛠️ COMPILING FILES 🛠️

Chez Scheme compiles source expressions as it sees them. In order to speed loading of a large file, the file may be compiled with the output placed in an object file. (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 no different from loading the source file, except that loading is faster since compilation is already done.

To compile a program 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 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 upon which the top-level program depends, other than built-in libraries, must be compiled first via compile-file or compile-library. This can be done manually or by setting the parameter compile-imported-libraries to #t before compiling the program.

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

🧚 BOOT and HEAP FILES 🧚

When Chez Scheme is run, it looks 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, 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 may be used to trace the boot file searching process and 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 this may be overridden by setting the environment variable SCHEMEHEAPDIRS. SCHEMEHEAPDIRS should be a colon-separated list of directories, listed in the order in which they should be searched. Within each directory, the two-character escape sequence %v is replaced by the current version, and 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 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 are compiled on-the-fly by make-boot-header.

Multiple alternatives for the boot file upon which the new boot file depends can be listed, e.g.:

(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, just scheme should be specified.

If the new boot file is to be a base boot file, i.e., one that does not depend on another boot file, 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 so the docs for Chez Scheme are literally split into two parts, bestie: The Scheme Programming Language, 4th Edition and The Chez Scheme Version 9 User's Guide. The first one is a real physical book you can get from MIT Press (yes, printed, on paper, iconic), and links to online versions of both documents live at https://cisco.github.io/ChezScheme/. 🫶

There's also a whole pile of example Scheme programs in the examples directory (peep FILES below), ranging from a simple factorial procedure all the way to a somewhat complex unification algorithm. Ngl, reading and poking at example programs is genuinely the best way to start learning Scheme. Do it. 💅

🌈 ENVIRONMENT 🌈

  • SCHEMEHEAPDIRS — you can set this env variable (mentioned above, iykyk) to a colon-separated list of directories to search for boot files — semi-colon separated under Windows, don't forget.
  • CHEZSCHEME_HISTORY — also mentioned above; set this one to the location you want used as the default history file location.

🎀 FILES 🎀

/usr/bin/chez                executable file
/usr/bin/petite              executable file
/usr/bin/chez-script         executable file
/usr/lib/csv10.3.0/examples  example program library
/usr/lib/csv10.3.0/ta6le     boot and include files

Like, the whole layout, served fresh. ✨

👀 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).

The reading list is giving syllabus day and honestly it ate. 📚💜

💖 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 the whole page, bestie! ✨ This was Chez Scheme Version 10.3.0, dated October 2025, page SCHEME(1) — go forth, run some parentheses, and slay 💅🦋🌸

📦 where this page comes from