On this page:
The Racket Reference
8.4

The Racket Reference

Matthew Flatt
and PLT

This manual defines the core Racket language and describes its most prominent libraries. The companion manual The Racket Guide provides a friendlier (though less precise and less complete) overview of the language.

The source of this manual is available on GitHub.

Unless otherwise noted, the bindings defined in this manual are exported by the racket/base and racket languages.

The racket/base library is much smaller than the racket library and will typically load faster.

The racket library combines racket/base, racket/bool, racket/bytes, racket/class, racket/cmdline, racket/contract, racket/dict, racket/file, racket/format, racket/function, racket/future, racket/include, racket/keyword, racket/list, racket/local, racket/match, racket/math, racket/path, racket/place, racket/port, racket/pretty, racket/promise, racket/sequence, racket/set, racket/shared, racket/stream, racket/string, racket/symbol, racket/system, racket/tcp, racket/udp, racket/unit, and racket/vector.

    1 Language Model

      1.1 Evaluation Model

        1.1.1 Sub-expression Evaluation and Continuations

        1.1.2 Tail Position

        1.1.3 Multiple Return Values

        1.1.4 Top-Level Variables

        1.1.5 Objects and Imperative Update

        1.1.6 Garbage Collection

        1.1.7 Procedure Applications and Local Variables

        1.1.8 Variables and Locations

        1.1.9 Modules and Module-Level Variables

          1.1.9.1 Phases

          1.1.9.2 The Separate Compilation Guarantee

          1.1.9.3 Cross-Phase Persistent Modules

          1.1.9.4 Module Redeclarations

          1.1.9.5 Submodules

        1.1.10 Continuation Frames and Marks

        1.1.11 Prompts, Delimited Continuations, and Barriers

        1.1.12 Threads

        1.1.13 Parameters

        1.1.14 Exceptions

        1.1.15 Custodians

      1.2 Syntax Model

        1.2.1 Identifiers, Binding, and Scopes

        1.2.2 Syntax Objects

        1.2.3 Expansion (Parsing)

          1.2.3.1 Fully Expanded Programs

          1.2.3.2 Expansion Steps

          1.2.3.3 Expansion Context

          1.2.3.4 Introducing Bindings

          1.2.3.5 Transformer Bindings

          1.2.3.6 Local Binding Context

          1.2.3.7 Partial Expansion

          1.2.3.8 Internal Definitions

          1.2.3.9 Module Expansion, Phases, and Visits

          1.2.3.10 Macro-Introduced Bindings

        1.2.4 Compilation

        1.2.5 Namespaces

        1.2.6 Inferred Value Names

        1.2.7 Cross-Phase Persistent Module Declarations

      1.3 The Reader

      1.4 The Printer

      1.5 Implementations

    2 Notation for Documentation

      2.1 Notation for Module Documentation

      2.2 Notation for Syntactic Form Documentation

      2.3 Notation for Function Documentation

      2.4 Notation for Structure Type Documentation

      2.5 Notation for Parameter Documentation

      2.6 Notation for Other Documentation

    3 Syntactic Forms

      3.1 Modules: module, module*, ...

      3.2 Importing and Exporting: require and provide

        3.2.1 Additional require Forms

        3.2.2 Additional provide Forms

      3.3 Literals: quote and #%datum

      3.4 Expression Wrapper: #%expression

      3.5 Variable References and #%top

      3.6 Locations: #%variable-reference

      3.7 Procedure Applications and #%app

      3.8 Procedure Expressions: lambda and case-lambda

      3.9 Local Binding: let, let*, letrec, ...

      3.10 Local Definitions: local

      3.11 Constructing Graphs: shared

      3.12 Conditionals: if, cond, and, and or

      3.13 Dispatch: case

      3.14 Definitions: define, define-syntax, ...

        3.14.1 require Macros

        3.14.2 provide Macros

      3.15 Sequencing: begin, begin0, and begin-for-syntax

      3.16 Guarded Evaluation: when and unless

      3.17 Assignment: set! and set!-values

      3.18 Iterations and Comprehensions: for, for/list, ...

        3.18.1 Iteration and Comprehension Forms

        3.18.2 Deriving New Iteration Forms

        3.18.3 Do Loops

      3.19 Continuation Marks: with-continuation-mark

      3.20 Quasiquoting: quasiquote, unquote, and unquote-splicing

      3.21 Syntax Quoting: quote-syntax

      3.22 Interaction Wrapper: #%top-interaction

      3.23 Blocks: block

      3.24 Internal-Definition Limiting: #%stratified-body

      3.25 Performance Hints: begin-encourage-inline

      3.26 Importing Modules Lazily: lazy-require

    4 Datatypes

      4.1 Equality

        4.1.1 Object Identity and Comparisons

        4.1.2 Equality and Hashing

        4.1.3 Implementing Equality for Custom Types

      4.2 Booleans

        4.2.1 Boolean Aliases

      4.3 Numbers

        4.3.1 Number Types

        4.3.2 Generic Numerics

          4.3.2.1 Arithmetic

          4.3.2.2 Number Comparison

          4.3.2.3 Powers and Roots

          4.3.2.4 Trigonometric Functions

          4.3.2.5 Complex Numbers

          4.3.2.6 Bitwise Operations

          4.3.2.7 Random Numbers

          4.3.2.8 Other Randomness Utilities

          4.3.2.9 Number–String Conversions

          4.3.2.10 Extra Constants and Functions

        4.3.3 Flonums

          4.3.3.1 Flonum Arithmetic

          4.3.3.2 Flonum Vectors

        4.3.4 Fixnums

          4.3.4.1 Fixnum Arithmetic

          4.3.4.2 Fixnum Vectors

          4.3.4.3 Fixnum Range

        4.3.5 Extflonums

          4.3.5.1 Extflonum Arithmetic

          4.3.5.2 Extflonum Constants

          4.3.5.3 Extflonum Vectors

          4.3.5.4 Extflonum Byte Strings

      4.4 Strings

        4.4.1 String Constructors, Selectors, and Mutators

        4.4.2 String Comparisons

        4.4.3 String Conversions

        4.4.4 Locale-Specific String Operations

        4.4.5 Additional String Functions

        4.4.6 Converting Values to Strings

      4.5 Byte Strings

        4.5.1 Byte String Constructors, Selectors, and Mutators

        4.5.2 Byte String Comparisons

        4.5.3 Bytes to/from Characters, Decoding and Encoding

        4.5.4 Bytes to Bytes Encoding Conversion

        4.5.5 Additional Byte String Functions

      4.6 Characters

        4.6.1 Characters and Scalar Values

        4.6.2 Character Comparisons

        4.6.3 Classifications

        4.6.4 Character Conversions

      4.7 Symbols

        4.7.1 Additional Symbol Functions

      4.8 Regular Expressions

        4.8.1 Regexp Syntax

        4.8.2 Additional Syntactic Constraints

        4.8.3 Regexp Constructors

        4.8.4 Regexp Matching

        4.8.5 Regexp Splitting

        4.8.6 Regexp Substitution

      4.9 Keywords

        4.9.1 Additional Keyword Functions

      4.10 Pairs and Lists

        4.10.1 Pair Constructors and Selectors

        4.10.2 List Operations

        4.10.3 List Iteration

        4.10.4 List Filtering

        4.10.5 List Searching

        4.10.6 Pair Accessor Shorthands

        4.10.7 Additional List Functions and Synonyms

        4.10.8 Immutable Cyclic Data

      4.11 Mutable Pairs and Lists

        4.11.1 Mutable Pair Constructors and Selectors

      4.12 Vectors

        4.12.1 Additional Vector Functions

      4.13 Boxes

      4.14 Hash Tables

        4.14.1 Additional Hash Table Functions

      4.15 Sequences and Streams

        4.15.1 Sequences

          4.15.1.1 Sequence Predicate and Constructors

          4.15.1.2 Sequence Conversion

          4.15.1.3 Additional Sequence Operations

            4.15.1.3.1 Additional Sequence Constructors

        4.15.2 Streams

        4.15.3 Generators

      4.16 Dictionaries

        4.16.1 Dictionary Predicates and Contracts

        4.16.2 Generic Dictionary Interface

          4.16.2.1 Primitive Dictionary Methods

          4.16.2.2 Derived Dictionary Methods

        4.16.3 Dictionary Sequences

        4.16.4 Contracted Dictionaries

        4.16.5 Custom Hash Tables

        4.16.6 Passing keyword arguments in dictionaries

      4.17 Sets

        4.17.1 Hash Sets

        4.17.2 Set Predicates and Contracts

        4.17.3 Generic Set Interface

          4.17.3.1 Set Methods

        4.17.4 Custom Hash Sets

      4.18 Procedures

        4.18.1 Keywords and Arity

        4.18.2 Reflecting on Primitives

        4.18.3 Additional Higher-Order Functions

      4.19 Void

      4.20 Undefined

    5 Structures

      5.1 Defining Structure Types: struct

      5.2 Creating Structure Types

      5.3 Structure Type Properties

      5.4 Generic Interfaces

      5.5 Copying and Updating Structures

      5.6 Structure Utilities

        5.6.1 Additional Structure Utilities

      5.7 Structure Type Transformer Binding

    6 Classes and Objects

      6.1 Creating Interfaces

      6.2 Creating Classes

        6.2.1 Initialization Variables

        6.2.2 Fields

        6.2.3 Methods

          6.2.3.1 Method Definitions

          6.2.3.2 Inherited and Superclass Methods

          6.2.3.3 Internal and External Names

      6.3 Creating Objects

      6.4 Field and Method Access

        6.4.1 Methods

        6.4.2 Fields

        6.4.3 Generics

      6.5 Mixins

      6.6 Traits

      6.7 Object and Class Contracts

      6.8 Object Equality and Hashing

      6.9 Object Serialization

      6.10 Object Printing

      6.11 Object, Class, and Interface Utilities

      6.12 Surrogates

    7 Units

      7.1 Creating Units

      7.2 Invoking Units

      7.3 Linking Units and Creating Compound Units

      7.4 Inferred Linking

      7.5 Generating A Unit from Context

      7.6 Structural Matching

      7.7 Extending the Syntax of Signatures

      7.8 Unit Utilities

      7.9 Unit Contracts

      7.10 Single-Unit Modules

      7.11 Single-Signature Modules

      7.12 Transformer Helpers

    8 Contracts

      8.1 Data-structure Contracts

      8.2 Function Contracts

      8.3 Parametric Contracts

      8.4 Lazy Data-structure Contracts

      8.5 Structure Type Property Contracts

      8.6 Attaching Contracts to Values

        8.6.1 Nested Contract Boundaries

        8.6.2 Low-level Contract Boundaries

      8.7 Building New Contract Combinators

        8.7.1 Blame Objects

        8.7.2 Contracts as structs

        8.7.3 Obligation Information in Check Syntax

        8.7.4 Utilities for Building New Combinators

      8.8 Contract Utilities

      8.9 racket/contract/base

      8.10 Collapsible Contracts

      8.11 Legacy Contracts

      8.12 Random generation

    9 Pattern Matching

      9.1 Additional Matching Forms

      9.2 Extending match

      9.3 Library Extensions

    10 Control Flow

      10.1 Multiple Values

      10.2 Exceptions

        10.2.1 Error Message Conventions

        10.2.2 Raising Exceptions

        10.2.3 Handling Exceptions

        10.2.4 Configuring Default Handling

        10.2.5 Built-in Exception Types

        10.2.6 Additional Exception Functions

      10.3 Delayed Evaluation

        10.3.1 Additional Promise Kinds

      10.4 Continuations

        10.4.1 Additional Control Operators

      10.5 Continuation Marks

      10.6 Breaks

      10.7 Exiting

      10.8 Unreachable Expressions

        10.8.1 Customized Unreachable Reporting

    11 Concurrency and Parallelism

      11.1 Threads

        11.1.1 Creating Threads

        11.1.2 Suspending, Resuming, and Killing Threads

        11.1.3 Synchronizing Thread State

        11.1.4 Thread Mailboxes

      11.2 Synchronization

        11.2.1 Events

        11.2.2 Channels

        11.2.3 Semaphores

        11.2.4 Buffered Asynchronous Channels

          11.2.4.1 Creating and Using Asynchronous Channels

          11.2.4.2 Contracts and Impersonators on Asynchronous Channels

      11.3 Thread-Local Storage

        11.3.1 Thread Cells

        11.3.2 Parameters

      11.4 Futures

        11.4.1 Creating and Touching Futures

        11.4.2 Future Semaphores

        11.4.3 Future Performance Logging

      11.5 Places

        11.5.1 Using Places

        11.5.2 Syntactic Support for Using Places

        11.5.3 Places Logging

      11.6 Engines

      11.7 Machine Memory Order

    12 Macros

      12.1 Pattern-Based Syntax Matching

      12.2 Syntax Object Content

        12.2.1 Syntax Object Source Locations

      12.3 Syntax Object Bindings

      12.4 Syntax Transformers

        12.4.1 require Transformers

        12.4.2 provide Transformers

        12.4.3 Keyword-Argument Conversion Introspection

        12.4.4 Portal Syntax Bindings

      12.5 Syntax Parameters

        12.5.1 Syntax Parameter Inspection

      12.6 Local Binding with Splicing Body

      12.7 Syntax Object Properties

      12.8 Syntax Taints

      12.9 Expanding Top-Level Forms

        12.9.1 Information on Expanded Modules

      12.10 Serializing Syntax

      12.11 File Inclusion

      12.12 Syntax Utilities

        12.12.1 Creating formatted identifiers

        12.12.2 Pattern variables

        12.12.3 Error reporting

        12.12.4 Recording disappeared uses

        12.12.5 Miscellaneous utilities

      12.13 Phase and Space Utilities

    13 Input and Output

      13.1 Ports

        13.1.1 Encodings and Locales

        13.1.2 Managing Ports

        13.1.3 Port Buffers and Positions

        13.1.4 Counting Positions, Lines, and Columns

        13.1.5 File Ports

        13.1.6 String Ports

        13.1.7 Pipes

        13.1.8 Structures as Ports

        13.1.9 Custom Ports

        13.1.10 More Port Constructors, Procedures, and Events

          13.1.10.1 Port String and List Conversions

          13.1.10.2 Creating Ports

          13.1.10.3 Port Events

          13.1.10.4 Copying Streams

      13.2 Byte and String Input

      13.3 Byte and String Output

      13.4 Reading

      13.5 Writing

      13.6 Pretty Printing

        13.6.1 Basic Pretty-Print Options

        13.6.2 Per-Symbol Special Printing

        13.6.3 Line-Output Hook

        13.6.4 Value Output Hook

        13.6.5 Additional Custom-Output Support

      13.7 Reader Extension

        13.7.1 Readtables

        13.7.2 Reader-Extension Procedures

        13.7.3 Special Comments

      13.8 Printer Extension

      13.9 Serialization

      13.10 Fast-Load Serialization

      13.11 Cryptographic Hashing

    14 Reflection and Security

      14.1 Namespaces

      14.2 Evaluation and Compilation

      14.3 The racket/load Language

      14.4 Module Names and Loading

        14.4.1 Resolving Module Names

        14.4.2 Compiled Modules and References

        14.4.3 Dynamic Module Access

      14.5 Impersonators and Chaperones

        14.5.1 Impersonator Constructors

        14.5.2 Chaperone Constructors

        14.5.3 Impersonator Properties

      14.6 Security Guards

      14.7 Custodians

      14.8 Thread Groups

      14.9 Structure Inspectors

      14.10 Code Inspectors

      14.11 Plumbers

      14.12 Sandboxed Evaluation

        14.12.1 Security Considerations

        14.12.2 Customizing Evaluators

        14.12.3 Interacting with Evaluators

        14.12.4 Miscellaneous

      14.13 The racket/repl Library

      14.14 Linklets and the Core Compiler

    15 Operating System

      15.1 Paths

        15.1.1 Manipulating Paths

        15.1.2 More Path Utilities

        15.1.3 Unix and Mac OS Paths

          15.1.3.1 Unix Path Representation

        15.1.4 Windows Paths

          15.1.4.1 Windows Path Representation

      15.2 Filesystem

        15.2.1 Locating Paths

        15.2.2 Files

        15.2.3 Directories

        15.2.4 Detecting Filesystem Changes

        15.2.5 Declaring Paths Needed at Run Time

        15.2.6 More File and Directory Utilities

      15.3 Networking

        15.3.1 TCP

        15.3.2 UDP

      15.4 Processes

        15.4.1 Simple Subprocesses

      15.5 Logging

        15.5.1 Creating Loggers

        15.5.2 Logging Events

        15.5.3 Receiving Logged Events

        15.5.4 Additional Logging Functions

      15.6 Time

        15.6.1 Date Utilities

      15.7 Environment Variables

      15.8 Environment and Runtime Information

      15.9 Command-Line Parsing

      15.10 Additional Operating System Functions

    16 Memory Management

      16.1 Weak Boxes

      16.2 Ephemerons

      16.3 Wills and Executors

      16.4 Garbage Collection

      16.5 Phantom Byte Strings

    17 Unsafe Operations

      17.1 Unsafe Numeric Operations

      17.2 Unsafe Character Operations

      17.3 Unsafe Compound-Data Operations

      17.4 Unsafe Extflonum Operations

      17.5 Unsafe Impersonators and Chaperones

      17.6 Unsafe Assertions

      17.7 Unsafe Undefined

    18 Running Racket

      18.1 Running Racket or GRacket

        18.1.1 Initialization

        18.1.2 Exit Status

        18.1.3 Init Libraries

        18.1.4 Command Line

        18.1.5 Language Run-Time Configuration

      18.2 Libraries and Collections

        18.2.1 Collection Search Configuration

        18.2.2 Collection Links

        18.2.3 Collection Paths and Parameters

      18.3 Interactive Help

      18.4 Interaction Configuration

      18.5 Interactive Module Loading

        18.5.1 Entering Modules

        18.5.2 Loading and Reloading Modules

      18.6 Debugging

        18.6.1 Tracing

      18.7 Controlling and Inspecting Compilation

        18.7.1 Compilation Modes

          18.7.1.1 BC Compilation Modes

          18.7.1.2 CS Compilation Modes

        18.7.2 Inspecting Compiler Passes

      18.8 Kernel Forms and Functions

    Bibliography

    Index