The key words “must”, “must not”, “required”, “shall”, “shall not”, “should”, “should not”, “recommended”, “may”, and “optional” in this report are to be interpreted as described in RFC 2119 [4]. Specifically:
In particular, this report occasionally uses “should” to designate circumstances that are outside the specification of this report, but cannot be practically detected by an implementation; see section 4.4. In such circumstances, a particular implementation may allow the programmer to ignore the recommendation of the report; it may even exhibit reasonable behavior. However, as the report does not specify the behavior, these programs may be unportable.
The chapters that describe bindings in the base library and the standard libraries are organized into entries. Each entry describes one language feature or a group of related features, where a feature is either a syntactic construct or a built-in procedure. An entry begins with one or more header lines of the form
The category defines the kind of binding described by the entry, typically either “syntax” or “procedure”. An entry may specify various restrictions on subforms or arguments. For background on this, see section 4.4.
If category is “syntax”, the entry describes a special syntactic construct, and the template gives the syntax of the forms of the construct. The template is written in a notation similar to a right-hand side of the BNF rules in chapter 3, and describes the set of forms equivalent to the forms matching the template as syntactic datums. Some “syntax” entries carry a suffix (expand), specifying that the syntactic keyword of the construct exported with level 1. Otherwise, the syntatic keyword is exported with level 0; see section 6.2.
Components of the form described by a template are designated by syntactic variables, which are written using angle brackets, for example, <expression>, <variable>. Case is insignificant in syntactic variables. Syntactic variables denote other forms, or, in some cases, sequences of them. A syntactic variable may refer to a non-terminal in the grammar for syntactic datums (see section 3.3.1, in which case only forms matching that non-terminal are permissible in that position. For example, <expression> stands for any form which is a syntactically valid expression. Other non-terminals that are used in templates will be defined as part of the specification.
The notation
<thing1> ...
indicates zero or more occurrences of a <thing>, and
<thing1> <thing2> ...
indicates one or more occurrences of a <thing>.
It is the programmer’s responsibility to ensure that each component of a form has the shape specified by a template. Descriptions of syntax may express other restrictions on the components of a form. Typically, such a restriction is formulated as a phrase of the form “<x> must bea ...”. Again, these specify the programmer’s responsibility. It is the implementation’s responsibility to check that these restrictions are satisfied, as long as the macro transformers involved in expanding the form terminate. If the implementation detects that a component does not meet the restriction, an exception with condition type &syntax is raised.
If category is “procedure”, then the entry describes a procedure, and the header line gives a template for a call to the procedure. Parameter names in the template are italicized. Thus the header line
indicates that the built-in procedure vector-ref takes two arguments, a vector vector and an exact non-negative integer k (see below). The header lines
indicate that the make-vector procedure takes either one or two arguments. The parameter names are case-insensitive: Vector is the same as vector.
As with syntax templates, an ellipsis ... at the end of a header line, as in
indicates that the procedure takes arbitrarily many arguments of the same type as specified for the last parameter name. In this case, = accepts two or more arguments that must all be complex numbers.
A procedure that detects an argument that it is not specified to handle must raise an exception with condition type &assertion. Also, if the number of arguments provided in a procedure call does not match the number of arguments accepted by the procedure, an exception with condition type &assertion must be raised.
For succinctness, the report follows the convention that if a parameter name is also the name of a type, then the corresponding argument must be of the named type. For example, the header line for vector-ref given above dictates that the first argument to vector-ref must be a vector. The following naming conventions imply type restrictions:
| obj | any object |
| z | complex number |
| x | real number |
| y | real number |
| q | rational number |
| n | integer |
| k | exact non-negative integer |
| bool | boolean (#f or #t) |
| octet | exact integer in {0, ..., 255} |
| byte | exact integer in { - 128, ..., 127} |
| char | character (see section 9.12) |
| pair | pair (see section 9.10) |
| vector | vector (see section 9.14) |
| string | string (see section 9.13) |
| condition | condition (see library section on “Conditions”) |
| bytevector | bytevector (see library chapter on “Bytevectors”) |
| proc | procedure (see section 1.6) |
Other type restrictions are expressed through parameter naming conventions that are described in specific chapters. For example, library chapter on “Arithmetic” uses a number of special parameter variables for the various subsets of the numbers.
With the listed type restrictions, it is the programmer’s responsibility to ensure that the corresponding argument is of the specified type. It is the implementation’s responsibility to check for that type.
A parameter called list means that it is the programmer’s responsibility to pass an argument that is a list (see section 9.10). It is the implementation’s responsibility to check that the argument is appropriately structured for the operation to perform its function, to the extent that this is possible and reasonable. The implementation must at least check that the argument is either an empty list or a pair.
Descriptions of procedures may express other restrictions on the arguments of a procedure. Typically, such a restriction is formulated as a phrase of the form “x must be a ...” (or otherwise using the word “must”).
In addition to the restrictions implied by naming conventions, an entry may list additional explicit restrictions. These explicit restrictions usually describe both the programmer’s responsibilities, who must ensure that an appropriate argument is passed, and the implementation’s responsibilities, which must check that the argument is appropriate. A description may explicitly list the implementation’s responsibilities for some arguments in a paragraph labeled “Implementation responsibilities”. In this case, the responsibilities specified for these arguments in the rest of the description are only for the programmer. An paragraph describing implementation responsibility does not affect the implementation’s responsibilities for checking arguments not mentioned in the paragraph.
If category is something other than “syntax” and “procedure”, then the entry describes a non-procedural value, and the category describes the type of that value. The header line
The description of an entry occasionally states that it is the same as another entry. This means that both entries are equivalent. Specifically, it means that if both entries have the same name and are thus exported from different libraries, the entries from both libraries can be imported under the same name without conflict.
The symbol “⇒” used in program examples can be read “evaluates to”. For example,
(* 5 8) ⇒ 40
means that the expression (* 5 8) evaluates to the object 40. Or, more precisely: the expression given by the sequence of characters “(* 5 8)” evaluates, in an environment that imports the relevant library, to an object that may be represented externally by the sequence of characters “40”. See section 3.3 for a discussion of external representations of objects.
The “⇒” symbol is also used when the evaluation of an expression causes a violation. For example,
(integer->char #xD800) ⇒ &assertion exception
means that the evaluation of the expression (integer->char #xD800) must raise an exception with condition type &assertion.
Moreover, the “⇒” symbol is also used to explicitly say that the value of an expression in unspecified. For example:
(eqv? "" "") ⇒ unspecifiedMostly, examples merely illustrate the behavior specified in the entry. In some cases, however, they disambiguate otherwise ambiguous specifications and are thus normative. Note that, in some cases, specifically in the case of inexact numbers, the return value is only specified conditionally or approximately. For example:
(atan -inf.0)
If the value of an expression is said to be “unspecified” or an expression is said to “return unspecified values”, then the expression must evaluate without raising an exception, but the values returned depend on the implementation; this report explicitly does not say how many or what values should be returned. Programmers should not rely on a specific number of return values or the specific values themselves.
When speaking of an exceptional situation (see section 4.3), this report uses the phrase “an exception is raised” to indicate that implementations must detect the situation and report it to the program through the exception system described in library chapter on “Exceptions and conditions”.
Several variations on “an exception is raised” using the keywords described in section 5.1 are possible, in particular “an exception must be raised” (equivalent to “an exception is raised”), “an exception should be raised”, and “an exception may be raised”.
This report uses the phrase “an exception with condition type t” to indicate that the object provided with the exception is a condition object of the specified type.
The phrase “a continuable exception is raised” indicates an exceptional situation that permits the exception handler to return, thereby allowing program execution to continue at the place where the original exception occurred. See library section on “Exceptions”.
By convention, the names of procedures that store values into previously allocated locations (see section 4.8) usually end in “!”. Such procedures are called mutation procedures. By convention, a mutation procedure returns unspecified values, but this convention is not always followed.
By convention, “->” appears within the names of procedures that take an object of one type and return an analogous object of another type. For example, list->vector takes a list and returns a vector whose elements are the same as those of the list.
By convention, the names of predicates—procedures that always return a boolean value—end in “?” when the name contains any letters; otherwise, the predicate’s name does not end with a question mark.
The components of compound names are usually separated by “-” In particular, prefixes that are actual words or can be pronounced as though they were actual words are followed by a hyphen, except when the first character following the hyphen would be something other than a letter, in which case the hyphen is omitted. Short, unpronounceable prefixes (“fx” and “fl”) are not followed by a hyphen.
By convention, the names of condition types usually start with “&”.
Scheme implementations conformant with this report must detect violations of the syntax. A syntax violation is an error with respect to the syntax of library bodies, top-level bodies, or the “syntax” entries in the specification of the base library or the standard libraries. Moreover, attempting to assign to an immutable variable (i.e., the variables exported by a library; see section 6.1) is also considered a syntax violation.
If a top-level or library form is not syntactically correct, then the execution of that top-level program or library must not be allowed to begin.