Beautiful Racket

Beautiful Racket is a book about making programming languages with Racket.

This library provides the #lang br teaching language used in the book, as well as supporting modules that can be used in other programs.

This library is designed to smooth over some of the small idiosyncrasies and inconsistencies in Racket, so that those new to Racket are more likely to say “ah, that makes sense” rather than “huh? what?”

1 Installation

If you want all the code & documentation, install the package beautiful-racket.

If you just want the code modules (for instance, for use as a dependency in another project) install the package beautiful-racket-lib.

If you just want the br/macro and br/syntax modules, install the package beautiful-racket-macro.

2 Conditionals

3 Datums

A datum is a literal representation of a single unit of Racket code, also known as an S-expression. Unlike a string, a datum preserves the internal structure of the S-expression. Meaning, if the S-expression is a single value, or list-shaped, or tree-shaped, so is its corresponding datum.

Datums are made with quote or its equivalent notation, the ' prefix (see Quoting: quote and ’).

When I use “datum” in its specific Racket sense, I use “datums” as its plural rather than “data” because that term has an existing, more generic meaning.

Two special cases. First, a string that describes a list of datums is parenthesized so the result is a single datum. Second, an empty string returns void (not #f, because that’s a legitimate datum).

4 Debugging

For instance, suppose you wanted to see how first-condition? was being evaluted in this expression:

(if (and (first-condition? x) (second-condition? x))

(one-thing)

(other-thing))

You can wrap it in report and find out:

(if (and (report (first-condition? x)) (second-condition? x))

(one-thing)

(other-thing))

This code will run the same way as before. But when it reaches first-condition?, you willl see in current-error-port:

(first-condition? x) = #t

You can also add standalone calls to report as a debugging aid at points where the return value will be irrelevant, for instance:

(report x x-before-function)

(if (and (report (first-condition? x)) (second-condition? x))

(one-thing)

(other-thing))

x-before-function = 42
(first-condition? x) = #t

But be careful — in the example below, the result of the if expression will be skipped in favor of the last expression, which will be the value of x:

(if (and (report (first-condition? x)) (second-condition? x))

(one-thing)

(other-thing))

(report x)

5 Define

This module also exports the bindings from br/macro.

6 Macro

(define-macro (id pat-arg ...) result-expr ...+)

If the first argument is a syntax pattern starting with id, then create a syntax transformer for this pattern using result-expr ... as the return value. As usual, result-expr ... needs to return a syntax object or you’ll get an error.

The syntax-pattern notation is the same as syntax-case, with one key difference. If a pat-arg has a name written in CAPS, it’s treated as a named wildcard (meaning, it will match any expression in that position, and can be subsequently referred to by that name). Otherwise, pat-arg is treated as a literal (meaning, it will only match the same expression). If pat-arg is a literal identifier, it will only match another identifier with the same name and the same binding (in other words, identifiers are tested with free-identifier=?).

For instance, the sandwich macro below requires three arguments, and the third must be please, but the other two are wildcards:

Examples:

> (define-macro (sandwich TOPPING FILLING please)     #'(format "I love ~a with ~a." 'FILLING 'TOPPING))

> (sandwich brie ham)

sandwich: no matching case for calling pattern

in: (sandwich brie ham)

> (sandwich brie ham now)

sandwich: no matching case for calling pattern

in: (sandwich brie ham now)

> (sandwich brie ham please)

"I love ham with brie."

> (sandwich banana bacon please)

"I love bacon with banana."

The ellipsis ... can be used with a wildcard to match a list of arguments. Please note: though a wildcard standing alone must match one argument, once you add an ellipsis, it’s allowed to match zero:

Examples:

> (define-macro (pizza TOPPING ...)     #'(string-join (cons "Waiter!"                          (list (format "More ~a!" 'TOPPING) ...))                    " "))

> (pizza mushroom)

"Waiter! More mushroom!"

> (pizza mushroom pepperoni)

"Waiter! More mushroom! More pepperoni!"

> (pizza)

"Waiter!"

The capitalization requirement for a wildcard pat-arg makes it easy to mix literals and wildcards in one pattern. But it also makes it easy to mistype a pattern and not get the wildcard you were expecting. Below, bad-squarer doesn’t work because any-number is meant to be a wildcard. But it’s not in caps, so it’s considered a literal, and it triggers an error:

Examples:

> (define-macro (bad-squarer any-number)     #'(* any-number any-number))

> (bad-squarer 0+10i)

bad-squarer: no matching case for calling pattern

in: (bad-squarer 0+10i)

The error is cleared when the argument is in caps, thus making it a wildcard:

Examples:

> (define-macro (good-squarer ANY-NUMBER)     #'(* ANY-NUMBER ANY-NUMBER))

> (good-squarer 0+10i)

-100

You can use the special variable caller-stx — available only within the body of define-macro — to access the original input argument to the macro.

Examples:

> (define-macro (inspect ARG ...)     (with-pattern ([CALLER-STX (syntax->datum caller-stx)])       #`(displayln          (let ([calling-pattern 'CALLER-STX])            (format "Called as ~a with ~a args"                    calling-pattern                    (length (cdr calling-pattern)))))))

> (inspect)

Called as (inspect) with 0 args

> (inspect "foo" "bar")

Called as (inspect foo bar) with 2 args

> (inspect #t #f #f #t)

Called as (inspect #t #f #f #t) with 4 args

This subform of define-macro is useful for macros that have one calling pattern. To make a macro with multiple calling patterns, see define-macro-cases. }

(define-macro id #'other-id)

If the first argument is an identifier id and the second a syntaxed identifier that looks like #'other-id, create a rename transformer, which is a fancy term for “macro that replaces id with other-id.” (This subform is equivalent to make-rename-transformer.)

Why do we need rename transformers? Because an ordinary macro operates on its whole calling expression (which it receives as input) like (macro-name this-arg that-arg . and-so-on). By contrast, a rename transformer operates only on the identifier itself (regardless of where that identifier appears in the code). It’s like making one identifier into an alias for another identifier.

Below, notice how the rename transformer, operating in the macro realm, approximates the behavior of a run-time assignment.

Examples:

> (define foo 'foo-value)

> (define bar foo)

> bar

'foo-value

> (define-macro zam-macro #'foo)

> zam-macro

'foo-value

> (define add +)

> (add 20 22)

42

> (define-macro sum-macro #'+)

> (sum-macro 20 22)

42

(define-macro id (lambda (arg-id) result-expr ...+))

If the first argument is an id and the second a single-argument function, create a macro called id that uses the function as a syntax transformer. This function must return a syntax object, otherwise you’ll trigger an error. Beyond that, the function can do whatever you like. (This subform is equivalent to define-syntax.)

Examples:

> (define-macro nice-sum (lambda (stx) #'(+ 2 2)))

> nice-sum

4

> (define-macro not-nice (lambda (stx) '(+ 2 2)))

> not-nice

not-nice: received value from syntax expander was not syntax

received: '(+ 2 2)

(define-macro id transformer-id)

Similar to the previous subform, but transformer-id holds an existing transformer function. Note that transformer-id needs to be visible during compile time (aka phase 1), so use define-for-syntax or equivalent.

Examples:

> (define-for-syntax summer-compile-time (lambda (stx) #'(+ 2 2)))

> (define-macro nice-summer summer-compile-time)

> nice-summer

4

> (define summer-run-time (lambda (stx) #'(+ 2 2)))

> (define-macro not-nice-summer summer-run-time)

summer-run-time: undefined;

cannot reference an identifier before its definition

in module: top-level

(define-macro id syntax-object)

syntax-object   :   syntax?

If the first argument is an id and the second a syntax-object, create a syntax transformer that returns syntax-object. This is just alternate notation for the previous subform, wrapping syntax-object inside a function body. The effect is to create a macro from id that always returns syntax-object, regardless of how it’s invoked. Not especially useful within programs. Mostly handy for making quick macros at the REPL.

Examples:

> (define-macro bad-listener #'"what?")

> bad-listener

"what?"

> (bad-listener)

"what?"

> (bad-listener "hello")

"what?"

> (bad-listener 1 2 3 4)

"what?"

As with define-macro, wildcards in each syntax pattern must be in CAPS. Everything else is treated as a literal match, except for the ellipsis ... and the wildcard _.

7 Syntax

The optional loc-stx argument supplies the source location for the resulting identifier (or identifiers).

The optional ctxt-stx argument supplies the lexical context for the resulting identifier (or identifiers).

The optional loc-stx argument supplies the source location for the resulting identifier (or identifiers).

The optional ctxt-stx argument supplies the lexical context for the resulting identifier (or identifiers).

The optional loc-stx argument supplies the source location for the resulting identifier (or identifiers).

The optional ctxt-stx argument supplies the lexical context for the resulting identifier (or identifiers).

8 Indentation

Helper functions for DrRacket language indenters.

9 Lists

10 Reader utilities

11 The br teaching languages