This chapter is a reference manual for the Scheme programming language. Don't read this chapter to learn Scheme, but turn to it when you need more detail about the language than appears in Structure and Interpretation of Computer Programs [1].

This section describes the notation used in this chapter. It also discusses the lexical conventions for writing Scheme program

In this chapter, in text describing a procedure or special form, the names of all formal parameters are italicized. The names of Scheme procedures, special forms, and variables appear in typewriter-style type. Throughout the chapter, whenever a formal parameter has one of the names listed in the left column of the table below, it must be of the type listed in the right column. For example, a formal parameter referred to as n2 in this chapter must be an integer.

57

The symbol "==>" in these examples means "evaluates to." For example,

means that the expression (+ 5 8) evaluates to 40.

Where the value returned by an expression is marked unspecified, Scheme does not guarantee what the value will be. For example,

Feel free to experiment to determine what Scheme returns in any particular case, but remember that a new version of Scheme might return a different value. Avoid writing programs that rely on unspecified values, particularly when working on problem sets.

Scheme numbers are expressed exactly as normal numbers, except that scientific notation looks slightly different. In Scheme scientific notation, the numbers of the exponent are not raised, but instead are separated from the base number by the letter e. For example,

123e10 is Scheme notation for 123 x 10¹⁰, and -123.45e-1 is Scheme notation for -123.45 x 10^-1.

A Scheme identifier is a sequence of letters, digits, and punctuation characters that is not a number. Here are some identifiers:

lambda	q	<=?
list->vector	soup	a34kTMNs
+	V17a	the-word-recursion-has-many-meanings

Upper and lower case forms of a letter are never distinguished except within character and string constants. For example, Foo is the same identifier as FOO.

Identifiers have several uses within Scheme programs:

Whitespace characters are spaces and line breaks (newlines). Whitespace is used to improve readability and to separate tokens (identifiers and numbers) from each other. Whitespace may also occur inside a string value.

A semicolon starts a comment, text which will be seen as whitespace by Scheme. The comment continues from the semicolon to the end of the line. For example:

Here are the special characters used in Scheme notations:

These characters may be used in identifiers as if they were letters.

These appear in numbers and identifiers. The period character is also used in the notation for pairs (section 4.6 ).

Parentheses surround expressions and lists (section 4.6 ).

The single quote character indicates literal data (section 4.3.2 ).

Double quote characters surround string values (section 4.9 ).

Backslash is an escape character within string constants (section 4.9 ).

Left and right square brackets and curly braces are reserved for possible future extensions to the language.

These are the boolean constants true and false (section 4.5 ).

Represents the ASCII standard number representing the immediately following character.

Introduces a vector constant (section 4.10).

Any identifier that does not refer to a special form (see section 4.1.4 ) may be used as a variable. A variable may name a location where a value can be stored. A variable that does so is said to be bound to the location. The set of all bindings in effect at some point in a program is the environment.

Certain expressions create new locations and bind variables to them. The most fundamental of these binding constructs is the lambda expression, because all other binding constructs can be explained in terms of lambda expressions. See section 4.3.5.

Like Algol and Pascal, and unlike most other dialects of Lisp except Common Lisp, Scheme is statically scoped and has block structure. To each place where a variable is bound in a program there corresponds a region of the program text within which the binding is effective. The region is determined by the particular binding construct that establishes the binding; if the binding is established by a lambda expression, for example, then its region is the entire lambda expression. Every reference to or assignment of a variable refers to the binding of the variable that established the innermost of the regions containing the use. If there is no binding of the variable whose region contains the use, then the use refers to the binding for the variable in the top level environment; if there is no binding for the identifier, it is said to be unbound.

A Scheme expression is a piece of code that returns a value. Types of expressions include variable references, literals, procedure calls, and special forms (see section 4.1.4 ). This section describes all Scheme expression types except conditionals and logical operations, which are described in section 4.5.

variable syntax

An expression consisting of a variable (section 4.2 ) is a variable reference. The value of the variable reference is the value stored in the location to which the variable is bound. It is an error to reference an unbound variable.

(quote datum) syntax

' datum syntax

constant syntax

(quote datum) evaluates to datum. Datum may be any printed representation of a Scheme object. This notation is used to include literal constants in Scheme code.

(quote datum) may be abbreviated as datum. The two notations are equivalent in all respects.

Numeric constants, string constants, character constants, and boolean constants evaluate "to themselves"; they need not be quoted.

(operator operand1, ... ) syntax

A procedure call is written by enclosing in parentheses expressions for the procedure to be called and the arguments to be passed to it. The operator and operand expressions are evaluated (in an indeterminate order) and the resulting procedure is passed the resulting arguments.

Procedure calls are also called combinations.

(lambda formals body) syntax

Syntax: Formals should be a formal arguments list as described below,

and body should be a sequence of one or more expressions.

Semantics: A lambda expression evaluates to a procedure. The environment in effect when the lambda expression was evaluated is remembered as part of the procedure. When the procedure is later called with some actual arguments, the environment in which the lambda expression was evaluated will be extended by binding the variables in the formal argument list to fresh locations, the corresponding actual argument values will be stored in those locations, and the expressions in the body of the lambda expression will be evaluated sequentially in the extended environment. The result of the last expression in the body will be returned as the result of the procedure call.

Formals should have one of the following forms:

• (variable₁, ... ): The procedure takes a fixed number of arguments; when the procedure is called, the arguments will be stored in the bindings of the corresponding variables.

• variable: The procedure takes any number of arguments; when the procedure is called, the sequence of actual arguments is converted into a newly allocated list, and the list is stored in the binding of the variable.

• (variable₁, ... variable_n-1, . variable_n): If a period surrounded by spaces precedes the last variable, then the value stored in the binding of the last variable will be a list of the actual arguments left over after all the other actual arguments have been matched up against the formal arguments.

The binding construct let gives Scheme a block structure, like Algol 60. The syntax of the three constructs is identical, but they differ in the regions they establish for their variable bindings. In a let expression, the initial values are computed before any of the variables become bound.

(let bindings body) syntax

where each init is an expression, and body should be a sequence of one or more expressions.

Semantics: The inits are evaluated in the current environment (in some unspecified order), the variables are bound to fresh locations holding the results, the body is evaluated in the extended environment, and the value of the last expression of body is returned. Each binding of a variable has body as its region.

(let variable bindings body) syntax

This is an extension of the syntax of let, called "named let" which provides a general looping construct and which may also be used to express recursions.

Named let has the same syntax and semantics as ordinary let except that variable is bound within body to a procedure whose formal arguments are the bound variables and whose body is body. Thus the execution of body may be repeated by invoking the procedure named by variable.

(set! variable expression) syntax

Expression is evaluated, and the resulting value is stored in the location to which variable is bound. Variable must be bound in some region or at top level. The result of the set! expression is unspecified.

(sequence expression, expression2 ... ) syntax

The expressions are evaluated sequentially from left to right, and the value of the last expression is returned. This expression type is used to sequence side effects such as input and output.

(sequence (set! x 5)

(sequence (princ "4 plus I equals ")

Note: Sequence is a synonym for the begin sequencing construct of the Scheme standard.

Definitions are used to establish bindings. Definitions are not valid in all contexts where expressions are allowed. They are valid only at the top level of a program and at the beginning of a body. A definition should have one of the following forms:

• (define variable expression)
• (define (variable formals) body)
  Formals should be either a sequence of zero or more variables, or a sequence of one or more variables followed by a period surrounded by spaces and another variable (as in a lambda expression). This form is equivalent to

• (define (variable . formal) body)
  Formal should be a single variable. This form is equivalent to

At the top level of a program, a definition

has essentially the same effect as the assignment expression

if variable is bound. If variable is not bound, however, then the definition will bind variable to a new location before performing the assignment, whereas it would be an error to perform a set! on an unbound variable.

Definitions are also permitted at the beginning of a body (that is, the body of a lambda, let, or define expression). Such definitions are known as internal definitions as opposed to the top level definitions described above. The variable defined by an internal definition is local to the body. That is, variable is bound rather than assigned, and the region of the binding is the entire body. For example,

The standard boolean objects for true and false are written as #t and #f. t and nil are alternative ways of writing #t and #f, respectively. What really matters, though, are the objects that the Scheme conditional expressions (if, cond, and, or) treat as true or false. The phrase "a true value" (or sometimes just "true") means any object treated as true by the conditional expressions, and the phrase "a false value" (or "false") means any object treated as false by the conditional expressions.

Of all the standard Scheme values, only #f and the empty list 0 count as false in conditional expressions. Everything else, including #t, pairs, symbols, numbers, strings, vectors, and procedures, counts as true.

Boolean constants evaluate to themselves, so they don't need to be quoted in programs.

true variable

false variable

The variables true and false are initially bound to the values #t and #f respectively. Note that these are ordinary variables, whereas #t and #f are constants.

(not obj ) procedure

Not returns #t if obj is false, and returns #f otherwise.

4.5. BOOLEANS AND CONDITIONALS 69

(and test₁, ... ) syntax

The test expressions are all evaluated. And returns #f if any of its arguments is false, and #t otherwise.

(or test₁, ... ) syntax

The test expressions are all evaluated. Or returns #t if any of its arguments is true, and #f otherwise.

(conjunction test, ... ) syntax

The test expressions are evaluated from left to right, and the value of the first expression that evaluates to a false value is returned. Any remaining expressions are not evaluated. If all the expressions evaluate to true values, the value of the last expression is returned. If there are no expressions then #t is returned.

(disjunction test, syntax

The test expressions are evaluated from left to right, and the value of the first expression that evaluates to a true value is returned. Any remaining expressions are not evaluated. If all expressions evaluate to false values, the

(false) value of the last expression is returned. If there are no expressions then #f is returned.

(if test consequent alternate) syntax

(if test consequent) syntax

Syntax: Test, consequent, and alternate may be arbitrary expressions.

Semantics: An if expression is evaluated as follows: first, test is evaluated. If it yields a true value (see section 4.5), then consequent is evaluated and its value is returned. Otherwise alternate is evaluated and its value is returned. If test yields a false value and no alternate is specified, then the result of the expression is unspecified.

(cond clause₁ clause₂ …) syntax

Syntax: Each clause should be of the form

(test expression …)

where test is any expression. The last clause may be an "else clause," which has the form

(else expression₁ expression₂ … )

Semantics: A cond expression is evaluated by evaluating the test expressions of successive clauses in order until one of them evaluates to a true value (see section 4.5 ). When a test evaluates to a true value, then the remaining expressions in its clause are evaluated in order, and the result of the last expression in the clause is returned as the result of the entire cond expression. If the selected clause contains only the test and no expressions, then the value of the test is returned as the result. If all tests evaluate to false values, and there is no else clause, then the result of the conditional expression is unspecified; if there is an else clause, then its expressions are evaluated, and the value of the last one is returned.

The three predicates described in this section are used to test whether objects are "the same". Of the three predicates, eq? is the finest or most discriminating while equal? is the coarsest. Eqv? is slightly less discriminating than eq?. In general, you should use equal? to test the equivalence of structures and eqv? to test the equivalence of atomic objects. See [2] for a careful description of the rationale for these three different predicates.

(eq? obj₁ obj₂) procedure

Eq? is the primitive equivalence predicate. It returns true if obj₁ and obj₂ are the same object. Unless you are rather advanced, do not use eq? to test identity of objects other than symbols. In particular, two numbers which are equal in value may not be eq?; use = or eqv? to test numerical equality. Also, two lists which have the same elements and print the same may not be eq?; use equal? to test if lists have the same elements.

For more advanced users only: Two structures are eq? if any attempt to modify one of them modifies the other in the same way; i.e., if the two structures share the same location in memory.

(eqv? obj₁ obj2) procedure

Eqv? returns #t if obj₁ and obj₂ are: eq? atoms, = numbers, or character strings containing the same characters in the same order with the same capitalization. Two lists are not in general eqv? even if eq? atom by atom. Eqv? is usually the correct predicate for testing the equality of atoms.

(equal? obj₁ obj₂) procedure

Equal? returns #t if both arguments are eqv? atoms, numbers, or character strings. Equal? list structures are those whose CARs are equal? and whose CDRs are equal?. As illustrated below, eq? and equal? are quite different.

A pair is a structure with two fields called the car and cdr fields (for historical reasons). Pairs are constructed by the procedure cons. The car and cdr fields are accessed by procedures car and cdr, and set by procedures set-car! and set-cdr!.

Pairs are used primarily to represent lists. A list is either empty or a pair whose car is the first element of the list, and whose cdr is the rest of the list. The length of a list is the number of elements, which is the same as the number of pairs.

The empty list is a special object of its own type (it is not a pair); it has no elements and its length is zero.

The most general notation for Scheme pairs is the "dotted" notation ( c1 . c2 ) where c1 is the value of the car field and c2 ) is the value of the cdr field. For example (4 . 5) is a pair whose car is 4 and whose cdr is 5. Note that (4 . 5) is the external representation of a pair, not an expression that evaluates to a pair.

A more streamlined notation can be used for lists: the elements of the list are simply enclosed in parentheses and separated by spaces. The empty list is written (). For example,

and

are both representations of a list of (the same) symbols.

A chain of pairs not ending in the empty list is called an improper list. Note that an improper list is not a list. The list and dotted notations can be combined to represent improper lists:

is equivalent to

Whether a given pair is a list depends upon what is stored in the cdr field. When the set-cdr! procedure is used, an object can be a list one moment and not the next:

(atom? obj) procedure

Returns #t if obj is an atom, and #f otherwise. An atom is anything which cannot be further decomposed via car or cdr. In other words, anything that is not a pair is an atom.

(list? obj)

Returns #t if obj is a list, and #f otherwise.

(pair? obj) procedure

Returns #t if obj is a pair, and #f otherwise. Note that the empty list, '() ) is a list but not a pair.

(cons obj₁ obj₂) procedure

Returns a newly allocated pair whose car is obj₁ and whose cdr is obj₂. The pair is guaranteed to be different (in the sense of eqv?) from every existing object.

(cons "a" '(b c )) ==> ("a" b c)

(car pair) procedure

Returns the contents of the car field of pair. Note that it is an error to take the car of the empty list.

(cdr pair) procedure

Returns the contents of the cdr field of pair. Note that it is an error to take the cdr of the empty list.

(set-car! pair obj) procedure

(set-cdr! pair obj) procedure

(caar pair) procedure

(cadr pair) procedure

(cdddar pair) procedure

(cddddr pair) procedure

These procedures are compositions of car and cdr, where for example caddr could be defined by

Arbitrary compositions, up to four deep, are provided. There are twenty-eight of these procedures in all.

(first pair) procedure

(second pair) procedure

(third pair) procedure

(fourth pair) procedure

(fifth pair) procedure

(sixth pair) procedure

(seventh pair) procedure

(eighth pair) procedure

These procedures return the first, second, third, ..., eighth element of pair, respectively, in exactly the same manner as would car, cadr, caddr, cadddr, ....

78 CHAPTER 4. SCHEME REFERENCE

(null? obj) procedure

(list obj, ... ) procedure

(list* obj₁ obj₂ … ) procedure

List* conses together an arbitrary number of arguments. It constructs a pair whose car is obj, and whose cdr is (list* obj2 ... ). When it has only two arguments, list* behaves in the same way as cons.

(length list) procedure

(append list₁ list₂ ) (append list ... ) procedure

(append list … ) procedure

The resulting list is always newly allocated, except that it shares structure with the last list argument. The last argument may actually be any object; an improper list results if it is not a proper list.

(reverse list) procedure

(list-tail list k) procedure

(nthcdr k list) procedure

For historical reasons, (nthcdr k list) is the same as (list-tail list k)

(last list) procedure

(list-ref list k) procedure

(nth k list) procedure

Both list-ref and nth return the kth element of list, where numbering starts with zero. (This is the same as the car of (list-tail list k).)

(member obj list) procedure

(memq obj list) procedure

(memv obj list) procedure

Returns the first sublist of list whose car is obj. If obj does not occur in list, returns #f. Memq uses eq? to compare obj with the elements of list, while memv uses eqv? and member uses equal?.

(assoc obj alist) procedure

(assq obj alist) procedure

(assv obj alist) procedure

Alist (for "association list") must be a list of pairs. Finds the first pair in alist whose car field is obj and returns that pair. If no pair in alist has obj as its car, returns #f. Assq uses eq? to compare obj with the car fields of the pairs in alist, while assv uses eqv? and assoc uses equal?.

Note: Although they are ordinarily used as predicates, memq, memv, member, assq, assv, and assoc do not have question marks in their names because they return useful values rather than just #t or #f.

Symbols are objects whose usefulness rests on the fact that two symbols are identical (in the sense of eqv?) if and only if their names are spelled the same way. The rules for writing a symbol are exactly the same as the rules for writing an identifier; see section 4.1.4.

(symbol? obj) procedure

Returns #t if obj is a symbol, otherwise returns #f.

(alphaless? symbol₁ symbol₂ ) procedure

Returns #t or #f according to whether the name of symbol₁ alphabetically precedes the name of symbol₂

(explode symbol) procedure

Returns a list of one-character symbols or digits that are the letters in the name of symbol.

(implode list) procedure

The argument must be a list of character symbols or integers. Implode returns a symbol whose name is the concatenation of the names of elements in list.

(char n) procedure

Returns the ASCII character (symbol) whose ASCII code is n.

(ascii symbol) procedure

Returns the ASCII code of the single-character symbol symbol. All alphabetic characters are regarded as upper case, because symbols do not retain the case in which they are typed.

(generate-uninterned-symbol symbol) procedure

Returns a symbol that is guaranteed to be different (not eqv?) from any other symbol. The printed representation of the new symbol will begin with the characters of symbol. Note: The "name" of an uninterned symbol is convenience for the human reader. You cannot reference an uninterned symbol by quoting its name.

Section 4.1.1 lists the names used here to specify restriction on the types of arguments these numerical procedures will accept.

(number? obj) procedure

(integer? obj) procedure

These numerical type predicates can be applied to any kind of argument, including non-numbers. They return true if the object is of the named type. In general, if a type predicate is true of a number then all higher type predicates are also true of that number.

(zero? z) procedure

(positive? x) procedure

(negative? x) procedure

(odd? n) procedure

(even? n) procedure

These numerical predicates test a number for a particular property, returning #t or #f.

(= z₁ z₂) procedure

(< x₁ x₂) procedure

(> x₁ x₂) procedure

(<= x₁ x₂) procedure

(>= x₁ x₂) procedure

These procedures return #t if their arguments are (respectively): numerically equal, monotonically increasing, monotonically decreasing, monotonically nondecreasing, or monotonically nonincreasing.

(max x₁ x₂) procedure

(max x₁ x₂ … ) procedure

(min x₁ x₂) procedure

(min x₁ x₂ … ) procedure

These procedures return the maximum or minimum of their arguments.

(+ z₁ z₂) procedure

(+ z₁ … ) procedure

(* z₁ z₂) procedure

(* z₁ … ) procedure

These procedures return the sum. or product of their arguments.

(- z₁ z₂) procedure

(- z₁ z₂ … ) procedure

(/ z₁ z₂) procedure

(/ z₁ z₂ …) procedure

With two or more arguments, these procedures return the difference or quotient of their arguments, associating to the left. With one argument, however, they return the additive or multiplicative inverse of their argument.

(1+ z) procedure

This procedure returns a value one greater than its argument.

(-1+ z) procedure

This procedure returns a value one less than its argument.

(abs z) procedure

Abs returns the magnitude of its argument.

(quotient n₁ n₂) procedure

(remainder n₁ n₂) procedure

(integer-divide n₁ n₂) procedure

These are intended to implement number-theoretic (integer) division: For

positive integers n₁ and n₂, if n₃ and n₄ are integers such that n₁ = n₂ n₃ + n₄

and 0 < n₄ < n₂, then

integer-divide returns the cons of what quotient and remainder would return given the same arguments.

For all integers n₁ and n2 with n2 not equal to 0,

The value returned by quotient always has the sign of the product of its arguments. Remainder always has the sign of the dividend.

(gcd n₁ … ) procedure

These procedures return the greatest common divisor or least common multiple of their arguments. The result is always non-negative.

(floor x) procedure

(ceiling x) procedure

(truncate x) procedure

(round x) procedure

These procedures create integers and rationals.

Floor returns the largest integer not larger than x. Ceiling returns the smallest integer not smaller than x. Truncate returns the integer of maximal absolute value not larger than the absolute value of x. Round returns the closest integer to x, rounding to even when x is halfway between two integers. Note: Round rounds to even for consistency with the rounding modes required by the IEEE floating point standard.

(exp z) procedure

(log z) procedure

(sin z) procedure

(cos z) procedure

(tan z) procedure

(atan y x) procedure

Log computes the natural logarithm of z (not the base 10 logarithm). Atan returns the arctangent, in radians, of the quotient of its arguments.

For nonzero x, the value of log x is defined to be the one whose imaginary part lies in the range -p (exclusive) to p (inclusive). (Log 0) is undefined.

(sqrt z) procedure

Returns the square root of z.

(expt z x ) procedure

Returns z raised to the power x

(random k) procedure

Returns an integer chosen at random between 0 and k-1, inclusive. The argument k must be a positive integer.

Strings are sequences of characters. Strings are written as sequences of characters enclosed within double quotes (") A double quote inside a string is created by \", as in

Vectors are structures whose elements are indexed by integers. The first element in a vector is indexed by zero, and the last element is indexed by one less than the length of the vector. The printed representation for vectors is a # followed by the sequence of elements, enclosed in parentheses. For example, a vector of length 3 containing the number zero in element 0, the list (2 2 2 2) in element 1, and the string "Anna" in element 2 can be written as following:

Note that this is the external representation, not an expression evaluating to a vector. Like lists, vector constants must be quoted:

Vectors are created by the constructor procedures vector and vector-cons. The elements are accessed and assigned by the procedures vector-ref and vector-set!.

(vector? obj) procedure

(vector-cons size fill) procedure

(vector obj ... ) procedure

(vector-size vector) procedure

(vector-ref vector k) procedure

returns the contents of element k of vector.

(vector-set! vector k obj) procedure

k must be a nonnegative integer less than (vector-length vector). Vector-set!

stores obj in element k of vector. The value returned by vector-set! is unspecified.

(let ((vec (vector 0 '(2 2 2 2) "Anna" )))

This chapter describes various primitive procedures that control the flow of program execution in special ways.

(apply proc args) procedure

(mapcar proc list1 list2 ... ) procedure

Proc must be a procedure which takes as many arguments as there are lists supplied to mapcar. Mapcar returns a list whose first element is proc applied to the first element of each list, whose second element is proc applied to the second element of the list, and so on. Mapcar stops when it reaches the end of the shortest list.

(mapc proc list1 list2 ) procedure

Proc must be a procedure which takes as many arguments as there are lists supplied to mapc. Mapc applies proc to the first element of each list, to the second element of each list, and so on. The difference between mapc and mapcar is that mapcar returns a list of values, while mapc does not. The procedure proc is usually applied for effect, and the value returned by mapc should be ignored.

A stream is a structure with two fields called the head and the tail. Streams are created by cons-stream. The head and tail are accessed using the procedures head and tail. Streams are used for representing sequences of elements, which are retrieved as the heads of successive tails of the stream. In this way, a stream is like a list. The difference is that the items in the stream are delayed, that is, they are computed when they are accessed rather than when the stream is constructed. The empty stream is stream that has no elements. See chapter 3 of [1] for information on programming with streams.

(cons-stream obj1 obj2) syntax

Returns a stream whose head is obj1 and whose tail is obj2. Cons-stream is syntax rather than a procedure because it does not evaluate its second argument.

(head stream) procedure

Returns the head of the given stream.

(tail stream) procedure

Returns the tail of the given stream.

the-empty-stream variable

A variable initially bound to the empty stream.

(empty-stream? obj) procedure

Returns #t or #f depending on whether obj is the empty steam.

(delay expression) syntax

The delay construct, together with the procedure force, implement lazy evaluation or call by need. (delay expression) returns an object called a promise which at some point in the future may be asked (by the force

procedure) to evaluate expression and deliver the resulting value.

(force promise), procedure

Forces the value of promise (see delay above). If no value has been computed for the promise, then a value is computed and returned. The value of the promise is cached (or "memoized") so that if it is forced a second time, the previously computed value is returned without any recomputation.

Force and delay are mainly intended for programs written using streams. The following examples should not be considered to illustrate good programming style, but they illustrate the property that the value of a promise is computed at most once.

This chapter describes the procedures that are used for input and output (I/O). The chapter first describes "ports" and how they are manipulated, then describes the I/O operations. Finally, some low-level procedures are described that permit the implementation of custom ports and high-performance I/O.

Scheme uses ports for I/O. A "port", which can be treated like any other Scheme object, serves as a source or sink for data. A port must be open before it can be read from or written to. The standard I/O port, `console-i/o-port', is opened automatically when you start Scheme. When you use a file for input or output, you need to explicitly open and close a port to the file (with procedures described in this chapter). Additional procedures let you open ports to strings.

Many input procedures, such as `read-char' and `read', read data from the current input port by default, or from a port that you specify. The current input port is initially `console-i/o-port', but Scheme provides procedures that let you change the current input port to be a file or string.

Similarly, many output procedures, such as `write-char' and `display', write data to the current output port by default, or to a port that you specify. The current output port is initially `console-i/o-port', but Scheme provides procedures that let you change the current output port to be a file or string.

All ports read or write only ASCII characters.

4.13.2 File Ports

Before Scheme can access a file for reading or writing, it is necessary to open a port to the file. This section describes procedures used to open ports to files. Such ports are closed (like any other port) by `close-port'. File ports are automatically closed if and when they are reclaimed by the garbage collector.

Before opening a file for input or output, by whatever method, the FILENAME argument is converted to canonical form by calling the procedure `merge-pathnames' with FILENAME as its sole argument. Thus, FILENAME can be either a string or a pathname, and it is merged with the current pathname defaults to produce the pathname that is then opened.

Any file can be opened in one of two modes, "normal" or "binary". Normal mode is for accessing text files, and binary mode is for accessing other files. Some operating systems, e.g. unix, do not distinguish these modes. MS-DOS is an example of an operating system that does distinguish these modes: in normal mode, MS-DOS file ports perform "newline translation", mapping between the carriage-return/linefeed sequence that terminates text lines in files, and the `#\newline' that terminates lines in Scheme. In binary mode, MS-DOS ports do not perform newline translation. Unless otherwise mentioned, the procedures in this section open files in normal mode.

- procedure: open-input-file FILENAME

- procedure: open-output-file FILENAME [APPEND?]

- procedure+: open-i/o-file FILENAME

4.13.3 Input Procedures

This section describes the procedures that read input. Input procedures can read either from the current input port or from a given port. Remember that to read from a file, you must first open a port to the file.

Input ports can be divided into two types, called "interactive" and "non-interactive". Interactive input ports are ports that read input from a source that is time-dependent; for example, a port that reads input from a terminal or from another program. Non-interactive input ports read input from a time-independent source, such as an ordinary file or a character string.

All optional arguments called INPUT-PORT, if not supplied, default to the current input port.

- procedure: read-char [INPUT-PORT]

- procedure: peek-char [INPUT-PORT]

- procedure: char-ready? [INPUT-PORT]

- procedure: read [INPUT-PORT]

- procedure: eof-object? OBJECT

- procedure+: read-char-no-hang [INPUT-PORT]

- procedure+: read-string CHAR-SET [INPUT-PORT]

(define (read-string char-set input-port)

(let ((char (peek-char input-port)))

(if (eof-object? char)

char

(list->string

(let loop ((char char))

(if (or (eof-object? char)

(char-set-member? char-set char))

'()

(begin

(read-char input-port)

(cons char (loop (peek-char input-port))))))))))

---------- Footnotes ----------

1. The value returned by a call to `peek-char' is the same as the value that would have been returned by a call to `read-char' on the same port. The only difference is that the very next call to `read-char' or `peek-char' on that INPUT-PORT will return the value returned by the preceding call to `peek-char'. In particular, a call to `peek-char' on an interactive port will hang waiting for input whenever a call to `read-char' would have hung.
2. `char-ready?' exists to make it possible for a program to accept characters from interactive ports without getting stuck waiting for input. Any input editors associated with such ports must make sure that characters whose existence has been asserted by `char-ready?' cannot be rubbed out. If `char-ready?' were to return `#f' at end of file, a port at end of file would be indistinguishable from an interactive port that has no ready characters.

4.13.4 Output Procedures

Output ports may or may not support "buffering" of output, in which output characters are collected together in a buffer and then sent to the output device all at once. (Most of the output ports implemented by the runtime system support buffering.) Sending all of the characters in the buffer to the output device is called "flushing" the buffer. In general, output procedures do not flush the buffer of an output port unless the buffer is full.

However, the standard output procedures described in this section perform what is called "discretionary" flushing of the buffer. Discretionary output flushing works as follows. After a procedure performs its output (writing characters to the output buffer), it checks to see if the port implements an operation called `discretionary-output-flush'. If so, then that operation is invoked to flush the buffer. At present, only the console port defines `discretionary-output-flush'; this is used to guarantee that output to the console appears immediately after it is written, without requiring calls to `flush-output'.

All optional arguments called OUTPUT-PORT, if not supplied, default to the current output port.

- procedure+: flush-output [OUTPUT-PORT]

- procedure: write-char CHAR [OUTPUT-PORT]

- procedure+: write-string STRING [OUTPUT-PORT]

- procedure: write OBJECT [OUTPUT-PORT]

- procedure: display OBJECT [OUTPUT-PORT]

- procedure: newline [OUTPUT-PORT]

- procedure+: fresh-line [OUTPUT-PORT]

- procedure+: write-line OBJECT [OUTPUT-PORT]

- procedure+: beep [OUTPUT-PORT]

- procedure+: clear [OUTPUT-PORT]

- procedure+: pp OBJECT [OUTPUT-PORT [AS-CODE?]]

---------- Footnotes ----------

1. `write' is intended for producing machine-readable output and `display' is for producing human-readable output.

This section describes procedures that prompt the user for input. Why should the programmer use these procedures when it is possible to do prompting using ordinary input and output procedures? One reason is that the prompting procedures are more succinct. However, a second and better reason is that the prompting procedures can be separately customized for each user interface, providing more natural interaction. The interfaces for Edwin and for GNU Emacs have already been customized in this fashion; because Edwin and Emacs are very similar editors, their customizations provide very similar behavior.

Each of these procedure accepts an optional argument called PORT, which must be an I/O port if given. If not given, this port defaults to the value of `(interaction-i/o-port)'; this is initially the console I/O port. The required argument PROMPT must be a string.

procedure+: prompt-for-command-expression PROMPT [PORT]

- procedure+: prompt-for-command-char PROMPT [PORT]

- procedure+: prompt-for-expression PROMPT [PORT]

- procedure+: prompt-for-confirmation PROMPT [PORT]

Under Edwin or Emacs, the confirmation is read in the minibuffer.

An environment is the set of bindings for variables that is in effect at some point in a program. (See section 4.2.) Environments in Scheme are first-class objects. That is, they may be named by variables, passed as arguments to procedures, and returned as the values of procedures. Scheme includes operations for capturing the environment in effect at any point and for specifying that an expression should be evaluated relative to a particular environment.

(eval exp env) procedure

Returns the result of evaluating exp in the environment env.

(the-environment) syntax

Evaluating the form the-environment returns the environment in which the form is evaluated.

Note: Scheme's static-scoping semantics imply that the-environment is not a procedure.

(environment? obj) procedure

Returns #t or #f depending on whether obj is an environment.

Make-environment constructs a new environment that is contained in the environment in which this form is evaluated. The expressions exp1, exp2, ... are evaluated sequentially in this new environment, and the environment is returned. The expi are typically define expressions. A make-environment form is alternate syntax for

user-initial-environment variable

A variable that is initially bound to the environment in which expressions entered from the console are evaluated when Scheme is first run.

(applicable? obj) procedure

Returns #t if obj can be applied, and #f other-wise. Primitive and compound procedures are applicable.

(object-type obj) procedure

Returns the primitive datatype of the object obj, The following are the data types that would be encountered in user code:

(enable-language-features) procedure

(disable-language-features) procedure

The Scheme system includes many more built-in procedures and special forms than are documented in this manual. Most of these are for system programming only. When Scheme is initially loaded, only the procedures in this manual are accessible from the initial user environment. Evaluating enable-language-features makes the additional procedures accessible.

Evaluating disable-language-features, in turn, disables these features.

Buffer A buffer is a block of text that you may examine and change. Whenever you edit in Edwin, you change the contents of a buffer. To preserve a buffer for another time you will use the Chipmunk, you must save the buffer to a file on disk.

Commands A command is an instruction you give Edwin through special keys. For example, use the Find File command to copy a file from a disk into a new buffer. Edwin commands are normally used by pressing the grey function keys across the top of the Chipmunk keyboard. However, if you're used to Emacs, you may want to use control and escape sequences, instead; in Edwin, most of them work exactly as they work in Emacs. (Use the [RUN] key whenever you would normally use [ESC] )

Cursor The cursor is the blinking underline visible on the screen whenever the Chipmunk is waiting for you to type something. If you type an ordinary character (letter, number, or punctuation), it will be inserted at the current cursor position, and the cursor will move past it.

Extended Commands An extended command is a command used by name, rather than by special keys. To use an extended command, press the [EXTEND] key ( [K2] , followed by the name of the command. Your typing will appear at the bottom of the screen, in the typein window (see below). When you've typed the full name of the extended command, press [ENTER]

File A file is a block of text stored on a disk. A file may be copied from a disk into a buffer. A file is created by saving the contents of a buffer on a disk.

Kills The several most recently-deleted regions axe kept in the kill Ting. Killed text can be retrieved with a yank.

Mark The mark is an invisible point in a buffer. Many commands set it to the buffer location where they were performed. Each buffer has its own mark.

Modes Every buffer has one major mode, and maybe some minor modes. Major modes determine special Edwin behavior particular to the language you are using (e.g., Scheme or English). Minor modes add special features regardless of the language you are using in the buffer.

Point The current cursor location in each buffer is called the point. The cursor is just a reflection of the point in the current buffer.

Region Text between the point and the mark is called the region.

Saving To save is to create a disk file from a buffer. The file and the buffer are identical, but only the file remains when you logout; the buffer is erased.

Window A window is a rectangular area on the screen. Each window displays part of some buffer. Because most buffers are too big to fit in one window, only part of the buffer is visible at any time; you can see other parts by using Edwin commands to scroll through the buffer.

[1] Harold Abelson and Gerald Jay Sussman with Julie Sussman. Structure and Interpretation of Computer Programs. MIT Press, Cambridge, 1985.

[2] Jonathan Rees and William Clinger, editors. Revised' Report on the Algorithmic Language Scheme. Newsletter of the ACM Special Interest Group on Programming Languages, November 1986.

[3] Tod Cass. Don't Panic: A 6.001 User's guide to the Chipmunk System. January, 1984.

[4] Harold Abelson. Go Ahead - Panic: A 6.003 User's Guide to the Bobcat System. Spring Semester, 1987.

[5] Richard M. Stallman. Gnu Emacs manual. Fourth Edition, Version 17. February 1986.

103