man scheme howto chezscheme-10.0.0-bp161.1.7.x86

MAN page from OpenSuSE chezscheme-10.0.0-bp161.1.7.x86_64.rpm

NAME

Chez Scheme
Petite Chez Scheme

SYNOPSIS

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

DESCRIPTION

Chez Scheme is a programming language, based on R6RS Scheme, and ahigh-performance implementation of that language.Chez Scheme compiles source expressions incrementally to machine code,providing the speed of compiled code in an interactive system.

Petite Chez Scheme is an interpreted version of Chez Scheme that may beused as a run-time environment for Chez Scheme applications or as astand-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 ascompiled code.Debugging and profiling support is also limited for interpretedcode.

Scheme is normally used interactively. The system promptsthe user with a right angle bracket (``>'') at the beginning of eachinput line. Any Scheme expression may be entered. The system evaluatesthe expression and prints the result. After printingthe result, the system prompts again for more input.The user can exit the system by typing Control-D or by using 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.

The following options are recognized but cause the system to print anerror message and exit because saved heaps are not presently supported.

-h file, --heap file
-s[level] file, --saveheap[level] file
-c, --compact

Any remaining command-line arguments are treated as the names offiles to be loaded before Chez Scheme begins interacting with theuser (see COMMAND-LINE FILE ARGUMENTS), unless ``--script'' or``--program'' is present, in which case the remaining argumentsare made available to the script via the command-line parameter(see SCHEME SCRIPTS).

WAITERS and CAFES

Interaction of the system with the user is performedby a Scheme program called a waiter, running in aprogram state called a cafe. The waitermerely prompts, reads, evaluates, prints and loopsback for more. It is possible to open up a chain of Chez Schemecafes by invoking the new-cafe procedure with no arguments.New-cafe is also one of the options when an interruptoccurs. Each cafe has its own reset and exit procedures.Exiting from one cafe in the chain returns you to the next oneback, and so on, until the entire chain closes and you leave thesystem altogether. Sometimes it is useful tointerrupt a long computation by typing the interrupt character,enter a new cafe to execute something (perhaps to check a statusvariable set by computation), and exit the cafe back to the oldcomputation.

You can tell what level you are at by the number of angle bracketsin 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 fromthree cafes to get out of Chez Scheme. If you wish to abortfrom Chez Scheme and you are several cafes deep, the procedureabort 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 displaysthe condition with which the exception was raised, saves it forpossibly 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 theraise continuation, i.e., the stack frames of the pending calls.When an exception occurs in a script or top level program, or when thestandard input and/or output ports are redirected, the default exceptionhandler does not save the continuation of the exception and does not printthe "type (debug)" message.

If the parameter debug-on-exception is set to #t, however, the defaultexception handler directly invokes debug, whether running interactively ornot, and even when running a script or top-level program.The ``--debug-on-exception'' option may be used to setdebug-on-exception to #t from the command line, which is particularlyuseful 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 thecondition and returns.

KEYBOARD INTERRUPTS

Running programs may be interrupted by typing the interruptcharacter (normally Control-C). In response, thesystem enters a break handler, which prompts for input with a``break>'' prompt.Several commands may be issued to the break handler, including``e'' to exit from the handler and continue,``r'' to reset to the current cafe,``a'' to abort Chez Scheme,``n'' to enter a new cafe,``i'' to inspect the current continuation, and``s'' to display statistics about the interrupted program.While typing an expression to the waiter, the interrupt charactersimply resets to the current cafe.

EXPRESSION EDITOR

When Chez Scheme is used interactively in a shell window, the waiter's ``prompt and read''procedure employs an expression editor that permits entry and editing ofsingle- and multiple-line expressions, automatically indents expressionsas they are entered, and supports name-completion based on the identifiersdefined in the interactive environment.The expression editor also maintains a history of expressions typed duringand across sessions and supports tcsh(1)-like history movement and searchcommands.Other editing commands include simple cursor movement viaarrow keys, deletion of characters via backspace and delete, andmovement, deletion, and other commands using mostlyemacs key bindings.

The expression editor does not run if the TERM environment variable isnot set, if the standard input or output files have been redirected, orif the --eedisable command-line option has been used.The history is saved across sessions, by default, in the file``$HOME/.chezscheme_history''.The --eehistory command-line optioncan be used to specify a differentlocation for the history file or to disable the saving and restoring ofthe history file.

Keys for nearly all printing characters (letters, digits, and specialcharacters) are ``self inserting'' by default.The open parenthesis, close parenthesis, open bracket, and close bracketkeys are self inserting as well, but also cause the editor to ``flash''to the matching delimiter, if any.Furthermore, when a close parenthesis or close bracket is typed, it isautomatically corrected to match the corresponding open delimiter, if any.

Key bindings for other keys and key sequences initially recognized bythe expression editor are given below, organized into groups by function.Some keys or key sequences serve more than one purpose depending uponcontext.For example, tab is used both for identifier completion and forindentation.Such bindings are shown in each applicable functional group.

Multiple-key sequences are displayed with hyphens between the keys ofthe sequences, but these hyphens should not be entered.When two or more key sequences perform the same operation, the sequencesare 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 lineis displayed, i.e., immediately after history movement, ^U deletes thecontents 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 tabre-indents, the second tab inserts identifier completion, and the thirdshows 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 keysequences.Follow with additional search key sequences to search further backward orforward in the history.For example, enter ``(define'' followed by one or more esc-p key sequencesto search backward for entries that are definitions, or ``(define''followed by one or more esc-P key sequences for entries that containdefinitions.

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 tohold the top-level bindings for user-defined variables and otheridentifiers contains an initial set of bindings, some standardand some specific to Chez Scheme.Any initial identifier binding may be replaced by redefiningthe identifier with a normal top-level definition.For example, the initial binding for cons can be replacedwith 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 thispoint will still use the original binding for cons.If you want it to use the new binding, you must reenter or reloadthe code.Furthermore, the initial bindings for variables like cons are immutable,so you cannot assign one (e.g., via set! or trace) without first definingit.This allows the system to check to make sure it receives the expectedtwo arguments at compile time and generate inline code to allocatethe pair.This is not the case if cons is redefined, even if redefined to havethe same value, since its value can be changed via set! at any timeduring a program run.

COMMAND-LINE FILE ARGUMENTS

In the normal mode of operation,the file names on the command line (except for the argumentsto the various command-line options) areloaded before Chez Scheme begins interacting with the user. Each of theexpressions in the loaded files is executed just as if it weretyped by the user in response to a prompt. If you wish to load aset of definitions each time, consider setting up a shell script toload the file ``.schemerc'' from your home directory:

scheme ${HOME}/.schemerc $*

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

Typically, a Scheme programmer creates a source file ofdefinitions and other Scheme forms using an editor such asvi(1) or emacs(1)and loads the file into Scheme to test them. Theconventional filename extension for Chez Scheme source filesis .ss. Such a file may be loaded during a session by typing(load ``filename''), or by specifying the filename onthe command line as mentioned above. Any expression that may betyped interactively may be placed in a file to be loaded.

SCHEME SCRIPTS

When the ``--script'' option is used, the named file istreated as a Scheme shell script, and the script name and remainingcommand-line arguments are made available via the parameter``command-line''.To support executable shell scripts, the system ignores the firstline of a loaded script if it begins with #! followed bya 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

The ``--program'' option is like the ``--script'' optionexcept that the script file is treated as an RNRS top-level program.The following RNRS top-level program prints its command-line arguments, aswith the script above.

#! /usr/bin/scheme --program
(import (rnrs))
(for-each

(lambda (x) (display x) (newline))

(cdr (command-line)))

``scheme-script'' may be used in place of ``scheme --program'',possibly prefixed by ``/usr/bin/env'' as suggested in the nonnormativeR6RS appendix on running top-level programs as scripts, i.e., the first lineof the top-level program may be replaced with the following.

#! /usr/bin/env scheme-script

If a top-level program depends on libraries other than those built intoChez Scheme, the ``--libdirs'' option can be used to specifywhich source and object directories to search.Similarly, if a library upon which a top-level program depends has anextension other than one of the standard extensions, the``--libexts'' option can be used to specify additional extensionsto search.

These options set the corresponding Chez Scheme parameterslibrary-directories and library-extensions.The values of both parameters are lists of pairs of strings.The first string in each library-directories pair identifies asource-file root directory, and the second identifies the correspondingobject-file root directory.Similarly, the first string in each library-extensions pairidentifies a source-file extension, and the second identifies thecorresponding object-file extension.The full path of a library source or object file consists of the source orobject root followed by the components of the library name prefixed byslashes, 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 separatorcharacter.The separator character is a colon (:), except under Windows where it is asemi-colon (;).Between single separators, the source and object strings, if both arespecified, 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, thespecified pairs replace the existing list.The parameters are set after all boot files have been loaded.

If multiple ``--libdirs'' options appear, all but the finalone are ignored, and if If multiple ``--libexts'' options appear, all but the finalare ignored.If no ``--libdirs'' option appears and the CHEZSCHEMELIBDIRSenvironment variable is set, the string value of CHEZSCHEMELIBDIRS istreated as if it were specified by a ``--libdirs'' option.Similarly, if no ``--libexts'' option appears and the CHEZSCHEMELIBEXTSenvironment variable is set, the string value of CHEZSCHEMELIBEXTS istreated as if it were specified by a ``--libexts'' option.

The library-directories and library-extensionsparameters set by these options are consulted by the expander when itencounters an import for a library that has not previously been defined orloaded.The expander first constructs a partial name from the list of components in thelibrary name, e.g., ``a/b'' for library (a b).It then searches for the partial name in each pairof root directories, in order, trying each of the source extensions theneach of the object extensions in turn before moving onto the next pair ofroot directories.If the partial name is an absolute pathname, e.g., ``~/.myappinit''for a library named (~/.myappinit), only the specified absolutepath is searched, first with each source extension, then with each objectextension.If the expander finds both a source file and its corresponding objectfile, and the object file is not older than the source file, theexpander loads the object file.If the object file does not exist, if the object file is older, orif after loading the object file, the expander determines it wasbuilt using a library or include file that has changed, the sourcefile is loaded or compiled, depending on the value of the parametercompile-imported-libraries.If compile-imported-librariesis set to #t, the expandercompiles 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 compiledcode is not saved to an object file.)An exception is raised during this process if asource or object file exists but is not readable or if an objectfile cannot be created.

The search process used by the expander when processing an importfor a library that has not yet been loaded can be monitored bysetting 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 theChez 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 issafe, i.e., generates full type and bounds checks.At optimize-level 3, code generated by the compiler is unsafe,i.e., may omit these checks.Unsafe code is usually faster, but optimize-level 3 should be used onlyfor well-tested code since the absence of type and bounds checks mayresult in invalid memory references, corruption of the Scheme heap (whichmay cause seemingly unrelated problems later), system crashes, or otherundesirable behaviors.

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

COMPILING FILES

Chez Scheme compiles source expressions as it sees them. Inorder to speed loading of a large file, the file may be compiledwith 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 fromloading the source file, except that loading is faster sincecompilation is already done.

To compile a program to be run with --program, usecompile-program instead of compile-file.compile-program preserves the first line unchanged, if it beginswith #! 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, soit can be recognized by the shell's script executor.Any libraries upon which the top-level program depends, other thanbuilt-in libraries, must be compiled first via compile-fileor compile-library.This can be done manually or by setting the parametercompile-imported-libraries to #t before compiling the program.

To compile a script to be run with --script, usecompile-script instead of compile-file.compile-script is like compile-program, but, like compile-file, implementsthe interactive top-level semantics rather than the RNRS top-levelprogram 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 ofthe Scheme system, including the interpreter, compiler, and mostlibraries.Boot files may be specified explicitly on the commandline via ``-b'' options or implicitly.In the simplest case, no ``-b'' optionsare given and the necessary boot files are loadedautomatically based on the name of the executable.For example, if the executable name is ``myapp'', thesystem looks for ``myapp.boot'' in a set of standarddirectories.It also looks for and loads any subordinate boot files requiredby ``myapp.boot''.Subordinate boot files are also loaded automatically for thefirst boot file explicitly specified via the command line.When multiple boot files are specified via the command line and boot eachfile must be listed before those that depend upon it.

The ``--verbose'' option may be used to trace the boot filesearching process and must appear before any boot argumentsfor which search tracing is desired.

Ordinarily, the search for boot files is limited to a set ofdefault installation directories, but this may be overridden by settingthe environment variable SCHEMEHEAPDIRS.SCHEMEHEAPDIRS should be a colon-separated list of directories, listed inthe 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 secondcharacter; in particular, ``%%'' is replaced by ``%'', and``%:'' is replaced by ``:''.If SCHEMEHEAPDIRS ends in a non-escaped colon, the default directories aresearched after those in SCHEMEHEAPDIRS; otherwise, only those listed inSCHEMEHEAPDIRS are searched.Under Windows, semi-colons are used in place of colons.

Boot files consist of a header followed by ordinary compiled code andmay 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.sowith a header identifying petite.boot as a boot file upon which the newboot file depends.Source files can be provided as well and are compiled on-the-flyby make-boot-header.

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

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

When possible, both ``scheme`` and ``petite`` should bespecified when creating a boot file for an application, as shown above, sothat 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 notdepend on another boot file, petite.boot (or some other boot file createdfrom petite.boot) should be listed first among the input files.

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

DOCUMENTATION

Complete documentation for Chez Scheme is available in two parts:The Scheme Programming Language, 4th Edition, andThe Chez Scheme Version 9 User's Guide.The first document is available in printed form from MIT Press,and links to online versions of both documents are availableat https://cisco.github.io/ChezScheme/.

Several example Scheme programs, ranging from a simple factorial procedureto a somewhat complex unification algorithm, are in the examples directory(see FILES below). Looking at and trying out example programs is a good wayto start learning Scheme.

ENVIRONMENT

The environment variableSCHEMEHEAPDIRS (see above) may be setto a colon-separated (semi-colon under Windows) list of directoriesin which to search for boot files.

FILES

/usr/bin/scheme               executable file

/usr/bin/petite              executable file

/usr/bin/scheme-script       executable file

/usr/lib/csv10.0.0/examples  example program library

/usr/lib/csv10.0.0/ta6le     boot and include files

AUTHOR

Index

NAME
SYNOPSIS
DESCRIPTION
COMMAND-LINE OPTIONS
WAITERS and CAFES
DEBUGGER
KEYBOARD INTERRUPTS
EXPRESSION EDITOR
TOP-LEVEL ENVIRONMENT SEMANTICS
COMMAND-LINE FILE ARGUMENTS
SCHEME SCRIPTS
RNRS TOP-LEVEL PROGRAMS
OPTIMIZE LEVELS
COMPILING FILES
BOOT and HEAP FILES
DOCUMENTATION
ENVIRONMENT
FILES
SEE ALSO
AUTHOR

This document was created byman2html,using the manual pages.