The Racket Reference

8.15

top contents ← prev up next →

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.

#lang racket/base	package: base
#lang racket

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/list, racket/local, racket/match, racket/math, racket/mutability, racket/path, racket/place, racket/port, racket/pretty, racket/promise, racket/sequence, racket/set, racket/shared, racket/stream, racket/string, racket/system, racket/tcp, racket/udp, racket/unit, and racket/vector. In addition, it re-exports for-syntax everything from racket/base.

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.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.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.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.13.1 Variants of 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 Iteration Expansion

3.18.4 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.1.1 Object Identity and Comparisons

4.1.2 Equality and Hashing

4.1.3 Implementing Equality for Custom Types

4.1.4 Honest Custom Equality

4.1.5 Combining Hash Codes

4.2.1 Boolean Aliases

4.2.2 Mutability Predicates

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.1 Flonum Arithmetic

4.3.3.2 Flonum Vectors

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.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 String Grapheme Clusters

4.4.6 Additional String Functions

4.4.7 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.1 Characters and Scalar Values

4.6.2 Character Comparisons

4.6.3 Classifications

4.6.4 Character Conversions

4.6.5 Character Grapheme-Cluster Streaming

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.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.1 Additional Vector Functions

4.13 Stencil Vectors

4.15 Hash Tables

4.15.1 Additional Hash Table Functions

4.16.1 Immutable Treelists

4.16.2 Mutable Treelists

4.17 Sequences and Streams

4.17.1 Sequences

4.17.1.1 Sequence Predicate and Constructors

4.17.1.2 Sequence Conversion

4.17.1.3 Additional Sequence Operations

4.17.1.3.1 Additional Sequence Constructors and Functions

4.17.3 Generators

4.18 Dictionaries

4.18.1 Dictionary Predicates and Contracts

4.18.2 Generic Dictionary Interface

4.18.2.1 Primitive Dictionary Methods

4.18.2.2 Derived Dictionary Methods

4.18.3 Dictionary Sequences

4.18.4 Contracted Dictionaries

4.18.5 Custom Hash Tables

4.18.6 Passing Keyword Arguments in Dictionaries

4.19.1 Hash Sets

4.19.2 Set Predicates and Contracts

4.19.3 Generic Set Interface

4.19.3.1 Set Methods

4.19.4 Custom Hash Sets

4.20 Procedures

4.20.1 Keywords and Arity

4.20.2 Reflecting on Primitives

4.20.3 Additional Higher-Order Functions

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.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.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.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.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.2.7 Realms and Error Message Adjusters

10.3 Delayed Evaluation

10.3.1 Additional Promise Kinds

10.4 Continuations

10.4.1 Additional Control Operators

10.5 Continuation Marks

10.8 Unreachable Expressions

10.8.1 Customized Unreachable Reporting

11 Concurrency and Parallelism

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.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.1 Creating and Touching Futures

11.4.2 Future Semaphores

11.4.3 Future Performance Logging

11.5.1 Using Places

11.5.2 Syntactic Support for Using Places

11.5.3 Places Logging

11.7 Machine Memory Order

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.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.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.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.4.4 Module Cache

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.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.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.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.4.1 Simple Subprocesses

15.5.1 Creating Loggers

15.5.2 Logging Events

15.5.3 Receiving Logged Events

15.5.4 Additional Logging Functions

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.1.6 Language Expand 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.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

top contents ← prev up next →