1 Introduction

The Racket Reference defines the core Racket language and documents its essential libraries.

The remainder of the chapter introduces essential terminology and notation that is used throughout the rest of the document.

1.1 Notation

This section describes the notation used in the rest of this manual to describe syntactic forms and values that are provided by the base language and by Racket libraries.

Syntactic forms, whether provided from the base language or via syntactic extensions, are specified using the same format that is described in the Notation chapter of The Racket Guide.

Procedures and other values are described using a notation based on contracts. In essence, these contract describe the interfaces of the documented library using Racket predicates and expressions.

For example, the following is the header of the definition of a typical procedure:

procedure (char->integer char) → exact-integer?

char : char?

The function being defined, char->integer, is typeset as if it were being applied. The metavariables that come after the function name stand in for arguments. The white text in the corner identifies the kind of value that is being documented.

Each metavariable is described with a contract. In the preceding example, the metavariable char has the contract char?. This contract specifies that any argument char that returns a true value with the char? predicate is valid. The documented function may or may not actually check this property, but the contract signals the intent of the implementer.

The contract on the right of the arrow, exact-integer? in this case, specifies the expected result that is produced by the function.

Contract specifications can be more expressive than just names of predicates. Consider the following header for argmax:

procedure (argmax proc lst) → any

proc : (-> any/c real?)

lst : (and/c pair? list?)

The contract (-> any/c real?) denotes a function contract specifying that proc’s argument can be any single value and the result should be a real number. The contract (and/c pair? list?) for lst specifies that lst should pass both pair? and list? (i.e., that it is a non-empty list).

Both -> and and/c are examples of contract combinators. Contract combinators such as or/c, cons/c, listof, and others are used throughout the documentation. Clicking on the hyperlinked combinator name will provide more information on its meaning.

A Racket function may be documented as having one or more optional arguments. For example, the sort function has two optional, keyword-based arguments:

procedure (sort   lst             less-than?            [ #:key extract-key             #:cache-keys? cache-keys?])   →   list?

lst : list?

less-than? : (any/c any/c . -> . any/c)

extract-key : (any/c . -> . any/c) = (lambda (x) x)

cache-keys? : boolean? = #f

The brackets around the extract-key and cache-keys? arguments indicate that they are optional. The contract section of the header shows the default values that are provided for these arguments.

1.1.1 Modules

Racket programs are usually organized into modules. The Reference reflects this organization with a notation for module declarations. A module declaration often prefaces the beginning of a Reference section or subsection:

The preceding ‘require‘ statement indicates that the bindings that would be documented below are available int the racket/list module. When a module name is not explicitly mentioned, it usually indicates that the documented bindings are contained in racket/base.