Thank you for your comment

Beau­tiful Racket / appendix

From br to racket/base

Now the truth can be told: the br language that we’ve used throughout this book is a not-very-special dialect of Racket. It’s just the foun­da­tional Racket language—which is called #lang racket/base—with some extra Racket libraries auto­mat­i­cally imported, and some br-specific libraries intended to defer a few compli­ca­tions until later in your Racket career. (Namely: now.)

There’s nothing wrong with using #lang br in modules or projects. But as a devel­oper, it’s a more virtuous habit to use #lang racket/base instead. Why?

  1. As a rule of thumb, it’s better prac­tice to start with the foun­da­tional language—that is, racket/base—and use require to import what you need. This makes your project (a little) faster to start up, and reduces depen­den­cies.

  2. Both #lang br and this book will continue to be revised and enlarged. #lang racket/base, by contrast, is guar­an­teed to remain the foun­da­tional config­u­ra­tion of Racket.

  3. racket/base is ubiq­ui­tous throughout other Racket projects, so recog­nizing common racket/base idioms is essen­tial for being able to read other people’s code.

A few options for those switching from br to racket/base:

Using br libraries

Rather than using #lang br, you can import just the parts you like. The br language is built from smaller modules like br/list, br/define, and br/syntax. These are all compat­ible with racket/base. See the docu­men­ta­tion for what’s included in each.

Copying & adapting code

The br code is avail­able under the MIT license. Rather than depend on the br package, you’re welcome to copy the code—indi­vidual func­tions, or whole modules—into your own projects, or adapt it.

None of the code is espe­cially compli­cated, though some of it uses tech­niques not covered in this book. (If you make improve­ments, I welcome pull requests at the beautiful-racket repo).

Rewriting

You can also just learn to rewrite your code without the br idioms and patterns. You can peek inside the br source code to see what’s going on, but these are the high­lights.

Macro defi­n­i­tions

define-macro and define-macro-cases are lightly disguised forms of define-syntax with syntax-parse. Here are three equiv­a­lent ways of writing the same macro:

(define-macro (mac1 X bar Y)
  #'(list X "second" Y))

(define-macro-cases mac2
  [(mac2 X bar Y) #'(list X "second" Y)])

(require (for-syntax syntax/parse))
(define-syntax (mac3 caller-stx)
  (syntax-parse caller-stx
    [((~literal mac3) X (~literal bar) Y) #'(list X "second" Y)]
    [else
     (raise-syntax-error
      'mac3
      (format "no matching case for calling pattern in: ~a"
              (syntax->datum caller-stx)))]))

(mac1 "first" bar "third") ; '("first" "second" "third")
(mac2 "first" bar "third") ; '("first" "second" "third")
(mac3 "first" bar "third") ; '("first" "second" "third")
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
(define-macro (mac1 X bar Y)
  #'(list X "second" Y))

(define-macro-cases mac2
  [(mac2 X bar Y) #'(list X "second" Y)])

(require (for-syntax syntax/parse))
(define-syntax (mac3 caller-stx)
  (syntax-parse caller-stx
    [((~literal mac3) X (~literal bar) Y) #'(list X "second" Y)]
    [else
     (raise-syntax-error
      'mac3
      (format "no matching case for calling pattern in: ~a"
              (syntax->datum caller-stx)))]))

(mac1 "first" bar "third") ; '("first" "second" "third")
(mac2 "first" bar "third") ; '("first" "second" "third")
(mac3 "first" bar "third") ; '("first" "second" "third")
copy to clipboard

Under the hood, define-macro is just a short­hand version of the one-case instance of define-macro-cases, which is a short­hand version of the full define-syntax + syntax-parse macro.

define-syntax is Racket’s basic tool for intro­ducing a macro. define-syntax can only be used to bind an iden­ti­fier (like mac3, in the example above) to a func­tion that takes one syntax object as an argu­ment, and returns another syntax object.

Racket has a number of tools that create syntax trans­formers, or help process the input of a macro. syntax-parse is in the latter cate­gory: it’s similar to cond or case, in that it takes a syntax object as input and tries to match it to a series of clauses with a syntax pattern on the left. When a match is found, the right side of the clause is eval­u­ated. The (bar) argu­ment in syntax case is a list of iden­ti­fiers that will be matched liter­ally.

Key differ­ences between define-macro or define-macro-cases and define-syntax with syntax-parse:

syntax-parse is Racket’s most powerful macro-making tool. This summary only scratches the surface. If you’re looking for a midrange option, consider syntax-case, which works mostly the same way as syntax-parse, but has fewer moving parts.

Macro helpers

Simi­larly, with-pattern is an alter­na­tive to Racket’s with-syntax.

(define stx #'(foo bar 42))

(syntax->datum
 (with-pattern ([(FIRST SECOND THIRD) stx])
   #'(list THIRD SECOND FIRST))) ; '(list 42 bar foo)

(syntax->datum
 (with-syntax ([(FIRST SECOND THIRD) stx])
   #'(list THIRD SECOND FIRST))) ; '(list 42 bar foo)
1
2
3
4
5
6
7
8
9
(define stx #'(foo bar 42))

(syntax->datum
 (with-pattern ([(FIRST SECOND THIRD) stx])
   #'(list THIRD SECOND FIRST))) ; '(list 42 bar foo)

(syntax->datum
 (with-syntax ([(FIRST SECOND THIRD) stx])
   #'(list THIRD SECOND FIRST))) ; '(list 42 bar foo)
copy to clipboard

Key differ­ences:

prefix-id and suffix-id are conve­nient ways of using format-id (which in turn is just a conve­nient way of using datum->syntax). The major differ­ence is that prefix-id and suffix-id auto­mat­i­cally generate iden­ti­fiers that live in the same lexical context as the base iden­ti­fier. Whereas with datum->syntax and format-id, you always have to provide an explicit lexical-context argu­ment:

(require racket/syntax)

(define-macro (make-bars)
  (define id #'foo)
  (with-pattern ([BAR1 (datum->syntax id 'bar1)]
                 [BAR2 (format-id id "~a" 'bar2)]
                 [BAR23 (suffix-id #'BAR2 "3")])
    #'(begin
        (define BAR1 'BAR1)
        (define BAR2 'BAR2)
        (define BAR23 'BAR23)
        (list BAR1 BAR2 BAR23))))

(make-bars) ; '(bar1 bar2 bar23)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
(require racket/syntax)

(define-macro (make-bars)
  (define id #'foo)
  (with-pattern ([BAR1 (datum->syntax id 'bar1)]
                 [BAR2 (format-id id "~a" 'bar2)]
                 [BAR23 (suffix-id #'BAR2 "3")])
    #'(begin
        (define BAR1 'BAR1)
        (define BAR2 'BAR2)
        (define BAR23 'BAR23)
        (list BAR1 BAR2 BAR23))))

(make-bars) ; '(bar1 bar2 bar23)
copy to clipboard

Func­tion defi­n­i­tions

define-cases: a variant of case-lambda, modi­fied to be more similar in form to define-macro-cases, but other­wise works the same way:

(define f
  (case-lambda
    [() 10]
    [(x) x]
    [(x y) (list y x)]
    [r r]))

(list (f) (f 1) (f 1 2) (f 1 2 3)) ; '(10 1 (2 1) (1 2 3))

(define-cases g
  [(g) 10]
  [(g x) x]
  [(g x y) (list y x)]
  [(g . r) r])

(list (g) (g 1) (g 1 2) (g 1 2 3)) ; '(10 1 (2 1) (1 2 3))
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
(define f
  (case-lambda
    [() 10]
    [(x) x]
    [(x y) (list y x)]
    [r r]))

(list (f) (f 1) (f 1 2) (f 1 2 3)) ; '(10 1 (2 1) (1 2 3))

(define-cases g
  [(g) 10]
  [(g x) x]
  [(g x y) (list y x)]
  [(g . r) r])

(list (g) (g 1) (g 1 2) (g 1 2 3)) ; '(10 1 (2 1) (1 2 3))
copy to clipboard

Condi­tionals

There is no until or while in Racket, but they can be easily derived from unless and when (as they are in br/cond):

(define-macro (until COND EXPR ...)
  #'(let loop ()
      (unless COND
        EXPR ...
        (loop))))

(define-macro (while COND EXPR ...)
  #'(let loop ()
      (when COND
        EXPR ...
        (loop))))
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
(define-macro (until COND EXPR ...)
  #'(let loop ()
      (unless COND
        EXPR ...
        (loop))))

(define-macro (while COND EXPR ...)
  #'(let loop ()
      (when COND
        EXPR ...
        (loop))))
copy to clipboard

The br/quick­lang dialect

#lang br/quicklang is a variant of the #lang br language for expander modules that auto­mat­i­cally exports four inter­po­si­tion points: #%top, #%app, #%datum, and #%top-interaction. As above, if you’re embarking on your own language, you should build on racket/base, because br/quicklang does nothing that you couldn’t do your­self in two lines of code.

← prev next →