Notation and Lexicography

This page describes a few lexicographic tidbits related to Scheme itself, and also details the notation used in the rest of this document to represent prescribed values, types, and objects required by certain procedures and other interfaces.

Identifiers

Identifiers have two uses within Scheme programs:

  • Any identifier can be used as a variable or as a syntactic keyword.

  • When an identifier appears as a literal or within a literal, it is being used to denote a symbol.

An identifier is any sequence of letters, digits, and “extended identifier characters” provided that it does not have a prefix which is a valid number. However, the . token (a single period) used in the list syntax is not an identifier.

Cozenage supports the following extended identifier characters:

! $ %  & * + - . / : < = > ? @ ^ _ ~

Alternatively, an identifier can be represented by a sequence of zero or more characters enclosed within vertical bars (|), analogous to string literals. Any character, including whitespace characters, but excluding the backslash and vertical line characters, can appear verbatim in such an identifier.

Here are some examples of valid identifiers:

  • +soup+

  • ->string

  • a34kTMNs

  • list->vector

  • q

  • V17a

  • |two words|

  • the-word-recursion-has-many-meanings

The syntax distinguishes between upper and lower case in identifiers and in characters specified using their names. However, it does not distinguish between upper and lower case in numbers, nor in ⟨inline hex escapes⟩ used in the syntax of identifiers, characters, or strings. None of the identifiers defined in this documentation contain upper-case characters, even when they appear to do so as a result of the English-language convention of capitalizing the first word of a sentence.

Notation used in procedure documentation

Every procedure exported by Cozenage has specific documentation appearing in later pages, which describes its arguments, return values, and provides a prose-description of its intended uses. This documentation is of the form:

(some-procedure arg1 arg2 arg3 ... )

Returns #true if arg1 through arg3 frabdnocate the spelektamazoik, and #false otherwise.

Parameters:

type – The file to load.

Returns:

#true or #false.

Return type:

boolean

The argument types, return values, and domain(s) of each procedure are specified by the following notations:

  • alist - an association list ie, a proper list were each value is a pair

  • boolean - #t or #f; a boolean value

  • byte - an integer, 0-255 inclusive

  • bytevector - a bytevector

  • char - a character

  • start / end - an exact, non-negative integer

  • k, k1, kj - an exact, non-negative integer

  • letter - an alphabetic character (ie: ‘d’, not a Scheme char)

  • list, list1, listj - a proper list

  • n, n1, nj - an integer

  • obj - any Scheme object

  • pair - a proper or improper list

  • port - an input or output port

  • proc - a procedure, either built-in, or a user-defined lambda

  • q, q1, qj - a rational number

  • string - a string

  • symbol - a symbol

  • thunk - a procedure with zero arguments

  • vector - a vector

  • x, x1, xj - a real number

  • y, y1, yj - a real number

  • z, z1, zj - a complex number

The names start and end are used as indexes into strings, vectors, and bytevectors. Their use implies the following:

  • It is an error if start is greater than end.

  • It is an error if end is greater than the length of the string, vector, or bytevector.

  • If start is omitted, it is assumed to be zero.

  • If end is omitted, it assumed to be the length of the string, vector, or bytevector.

  • The index start is always inclusive and the index end is always exclusive. As an example, consider a string. If start and end are the same, an empty substring is referred to, and if start is zero and end is the length of string, then the entire string is referred to.