Beau­tiful Racket / explainers



(define-macro (m foo) #'"match")
(m foo) ; "match"
(m bar) ; error: no matching case for pattern

1 2 3

(define-macro (m foo) #'"match") (m foo) ; "match" (m bar) ; error: no matching case for pattern



(define-macro-cases m2
  [(m2) "first"]
  [(m2 foo) "second"]
  [(m2 foo ARG) #'ARG]
  [else "no match"])

(m2) ; "first"
(m2 foo) ; "second"
(m2 foo "bar") ; "bar"
(m2 bar) ; "no match"

1 2 3 4 5 6 7 8 9 10

(define-macro-cases m2 [(m2) "first"] [(m2 foo) "second"] [(m2 foo ARG) #'ARG] [else "no match"]) (m2) ; "first" (m2 foo) ; "second" (m2 foo "bar") ; "bar" (m2 bar) ; "no match"



(define-macro (m3 MID ... LAST)
  (with-pattern ([(ONE TWO THREE) (syntax LAST)]
                 [(ARG ...) #'(MID ...)])
    #'(list ARG ... THREE TWO ONE)))

(m3 25 42 ("foo" "bar" "zam")) ; '(25 42 "zam" "bar" "foo")

1 2 3 4 5 6

(define-macro (m3 MID ... LAST) (with-pattern ([(ONE TWO THREE) (syntax LAST)] [(ARG ...) #'(MID ...)]) #'(list ARG ... THREE TWO ONE))) (m3 25 42 ("foo" "bar" "zam")) ; '(25 42 "zam" "bar" "foo")

• 

  (m3 MID ... LAST) is a syntax pattern that defines the possible input argu­ments to the macro, and matches them to pattern vari­ables.

• 

  (syntax LAST) is a syntax template containing only the element matched by LAST. We could also write this as #'LAST. These elements are matched to another syntax pattern, (ONE TWO THREE).

• 

  #'(MID ...) is a syntax template containing the elements matched by MID .... We could also write this as (syntax (MID ...)). These elements are matched to the syntax pattern (ARG ...).

• 

  #'(list ARG ... THREE TWO ONE) is a syntax template containing the matched elements inside a list.



(m3 25 42 ("foo" "bar"))

1	(m3 25 42 ("foo" "bar"))



with-pattern: unable to match pattern (ONE TWO THREE) in: ("foo" "bar")

1	with-pattern: unable to match pattern (ONE TWO THREE) in: ("foo" "bar")

1. 

   A literal, which only matches itself. Numbers, strings, and symbols are always literals. In define-macro, define-macro-cases, and with-pattern, iden­ti­fiers that are not in UPPERCASE are treated as literals.  + In stan­dard Racket, you need to list out literals sepa­rately (see, e.g., syntax-case). This is a chore that the br syntax func­tions handle auto­mat­i­cally.

   

   (define-macro-cases num
     [(num 42) "match"]
     [else "nope"])
   (num 42) ; "match"
   (num 24) ; "nope"
   (num "foo") ; "nope"
   
   (define-macro-cases str
     [(str "foo") "match"]
     [else "nope"])
   (str "foo") ; "match"
   (str foo) ; "nope"
   (str "bar") ; "nope"
   
   (define-macro-cases sym
     [(sym 'foo) "match"]
     [else "nope"])
   (sym 'foo) ; "match"
   (sym 'bar) ; "nope"
   (sym "foo") ; "nope"
   
   (define-macro-cases id
     [(id foo) "match"]
     [else "nope"])
   (id foo) ; "match"
   (id bar) ; "nope"
   (id "foo") ; "nope"

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27

   (define-macro-cases num [(num 42) "match"] [else "nope"]) (num 42) ; "match" (num 24) ; "nope" (num "foo") ; "nope" (define-macro-cases str [(str "foo") "match"] [else "nope"]) (str "foo") ; "match" (str foo) ; "nope" (str "bar") ; "nope" (define-macro-cases sym [(sym 'foo) "match"] [else "nope"]) (sym 'foo) ; "match" (sym 'bar) ; "nope" (sym "foo") ; "nope" (define-macro-cases id [(id foo) "match"] [else "nope"]) (id foo) ; "match" (id bar) ; "nope" (id "foo") ; "nope"

   
   

   When matching literal iden­ti­fiers, a trap awaits the unwary. A literal iden­ti­fier in a syntax pattern is matched on the basis of its name but also its binding.  + Racket jocks might know this as equality in the sense of free-identifier=?. In the submodule below, mac looks like it will match the literal iden­ti­fier zeta. But outside the submodule, when we import zeta from math and then pass it as input to mac, we don’t get a match:

   

   (module mod br
     (define-macro-cases mac
       [(_ zeta) "match"]
       [else "nope"])
     (provide mac))
   (require (submod "." mod))
   
   (require math)
   (mac zeta) ; "nope"

   1 2 3 4 5 6 7 8 9

   (module mod br (define-macro-cases mac [(_ zeta) "match"] [else "nope"]) (provide mac)) (require (submod "." mod)) (require math) (mac zeta) ; "nope"

   
   

   Why not? Because the iden­ti­fier zeta has no bind­ing at the macro-defi­n­i­tion site.  + And this, in turn, is because of macro hygiene: mac lives in a sepa­rate lexical context, and can’t see the zeta binding at the calling site. Even though the names of the literal iden­ti­fiers are the same, their bind­ings are not. There­fore, the pat­tern doesn’t match, and the result is "nope".

   

   We can make the two zeta iden­ti­fiers match if we also make the same binding avail­able at the macro-defi­n­i­tion site, by importing math:

   

   (module mod br
     (require math)
     (define-macro-cases mac
       [(_ zeta) "match"]
       [else "nope"])
     (provide mac))
   (require (submod "." mod))
   
   (require math)
   (mac zeta) ; "match"

   1 2 3 4 5 6 7 8 9 10

   (module mod br (require math) (define-macro-cases mac [(_ zeta) "match"] [else "nope"]) (provide mac)) (require (submod "." mod)) (require math) (mac zeta) ; "match"

   
2. 

   A pattern vari­able (or wild­card) which can match anything (including a list of things) and assigns the matched item a name. Once a pattern vari­able is defined, all appear­ances of the pattern vari­able within a syntax object are replaced with the matched value.

   

   (define-macro (self ARG) #'ARG)
   (self "foo") ; "foo"
   (self (list 1 2 3)) ; '(1 2 3)
   
   (define-macro (add-three ARG) #'(+ ARG ARG ARG))
   (add-three 42) ; 126

   1 2 3 4 5 6

   (define-macro (self ARG) #'ARG) (self "foo") ; "foo" (self (list 1 2 3)) ; '(1 2 3) (define-macro (add-three ARG) #'(+ ARG ARG ARG)) (add-three 42) ; 126

   
   

   The special wild­card _ also matches anything, but it can be used any number of times in a syntax pattern, and it cannot appear in a syntax template. It’s useful for signaling that an element of the syntax datum is being ignored.

   

   (define-macro (odds FIRST _ THIRD _ FIFTH)
     #'(list FIRST THIRD FIFTH))
   (odds 1 2 3 4 5) ; '(1 3 5)

   1 2 3

   (define-macro (odds FIRST _ THIRD _ FIFTH) #'(list FIRST THIRD FIFTH)) (odds 1 2 3 4 5) ; '(1 3 5)

   
3. 

   A sublist pattern, which will only match elements arranged with the same paren­the­siza­tion. If you know a certain element will be a list, a sublist pattern can be used to imme­di­ately match elements inside that list. Sublist patterns can be nested to any depth.

   

   (define-macro (m NUMS)
     (with-pattern ([(FIRST SECOND THIRD) #'NUMS])
       #'(list THIRD SECOND FIRST)))
   (m (1 2 3)) ; '(3 2 1)
   
   (define-macro (m2 (FIRST SECOND THIRD))
     #'(list THIRD SECOND FIRST))
   (m2 (1 2 3)) ; '(3 2 1)

   1 2 3 4 5 6 7 8

   (define-macro (m NUMS) (with-pattern ([(FIRST SECOND THIRD) #'NUMS]) #'(list THIRD SECOND FIRST))) (m (1 2 3)) ; '(3 2 1) (define-macro (m2 (FIRST SECOND THIRD)) #'(list THIRD SECOND FIRST)) (m2 (1 2 3)) ; '(3 2 1)

   
   

   By the way, a sublist pattern cannot create a sublist where none exists in the input:

   

   (define-macro (m2 (FIRST SECOND THIRD))
     #'(list THIRD SECOND FIRST))
   (m2 1 2 3) ; error: no match, because no sublist

   1 2 3

   (define-macro (m2 (FIRST SECOND THIRD)) #'(list THIRD SECOND FIRST)) (m2 1 2 3) ; error: no match, because no sublist

   
4. 

   An ellipsis, which has to follow a pattern vari­able, and matches as many items as it can (similar to the “greedy” * oper­ator in regular expres­sions).

   

   (define-macro (ellip ARG ...)
     #'(list ARG ...))
   
   (ellip 1 2 3) ; '(1 2 3)
   (ellip "a" "b") ; '("a" "b")
   (ellip) ; '()

   1 2 3 4 5 6

   (define-macro (ellip ARG ...) #'(list ARG ...)) (ellip 1 2 3) ; '(1 2 3) (ellip "a" "b") ; '("a" "b") (ellip) ; '()

   
   

   Even though an ordi­nary pattern vari­able will match exactly one item, a pattern vari­able with an ellipsis can match zero items.

   

   If a pattern vari­able has an ellipsis, when the vari­able appears in a syntax object, the ellipsis must also appear (other­wise it’s an error):

   

   (define-macro (bad-ellip ARG ...)
     #'(list ARG))
   (bad-ellip 1 2 3) ; error: missing ellipsis

   1 2 3

   (define-macro (bad-ellip ARG ...) #'(list ARG)) (bad-ellip 1 2 3) ; error: missing ellipsis

   
   

   You can only have one ellipsis in each sublist of the pattern, including the top level:  + But see syntax/parse, an advanced macro-creation system that supports a richer pattern vocab­u­lary.

   

   ; OK: one ellipsis per sublist
   (define-macro (m (FOO ...) (BAR ...))
     #'(list FOO ... BAR ...))
   (m (1 2 3) (4 5 6)) ; '(1 2 3 4 5 6)
   
   ; not OK: two ellipses at top level
   (define-macro (m2 FOO ... BAR ...)
     #'(list FOO ... BAR ...))

   1 2 3 4 5 6 7 8

   ; OK: one ellipsis per sublist (define-macro (m (FOO ...) (BAR ...)) #'(list FOO ... BAR ...)) (m (1 2 3) (4 5 6)) ; '(1 2 3 4 5 6) ; not OK: two ellipses at top level (define-macro (m2 FOO ... BAR ...) #'(list FOO ... BAR ...))

   
5. 

   A dot, which has to precede a pattern vari­able at the end of a list, and matches all remaining items in the list starting at the dot. The resulting pattern vari­able can either be used in a syntax object alone (in which case it’s treated as a list of items) or with another dot (in which case it’s spliced into the result). This expla­na­tion is more compli­cated than the example:

   

   (define-macro (m . ARGS) #'ARGS)
   (m + 1 2 3) ; means #'(+ 1 2 3) = 6
   
   (define-macro (m2 . ARGS) #'(list . ARGS))
   (m2 1 2 3) ; means #'(list 1 2 3) = '(1 2 3)

   1 2 3 4 5

   (define-macro (m . ARGS) #'ARGS) (m + 1 2 3) ; means #'(+ 1 2 3) = 6 (define-macro (m2 . ARGS) #'(list . ARGS)) (m2 1 2 3) ; means #'(list 1 2 3) = '(1 2 3)

   
   

   “Isn’t a dot just a less flex­ible way of writing an ellipsis?” Pretty much. The above macros could be written with ellipses like so:

   

   (define-macro (m ARG ...) #'(ARG ...))
   (m + 1 2 3) ; means #'(+ 1 2 3) = 6
   
   (define-macro (m2 ARG ...) #'(list ARG ...))
   (m2 1 2 3) ; means #'(list 1 2 3) = '(1 2 3)

   1 2 3 4 5

   (define-macro (m ARG ...) #'(ARG ...)) (m + 1 2 3) ; means #'(+ 1 2 3) = 6 (define-macro (m2 ARG ...) #'(list ARG ...)) (m2 1 2 3) ; means #'(list 1 2 3) = '(1 2 3)

   
   

   You can prob­ably go your whole career as a macro writer without using the dot. But if you come across it in someone else’s source code, you’ll know what it means. (BTW, you can’t use a dot and ellipsis in the same level of a pattern.)



(define-macro (m (WILD _ ELLIP ... literal) . DOT)
  #'(quote ((wild WILD) (ellip ELLIP ...) (dot . DOT))))

(m (1 2 3 4 literal) 5 6) ; '((wild 1) (ellip 3 4) (dot 5 6))

1 2 3 4

(define-macro (m (WILD _ ELLIP ... literal) . DOT) #'(quote ((wild WILD) (ellip ELLIP ...) (dot . DOT)))) (m (1 2 3 4 literal) 5 6) ; '((wild 1) (ellip 3 4) (dot 5 6))



(define-macro (m1 ARGS) #'ARGS)
(m1 (+ 1 2)) ; 3
(define-macro (m2 (ARG ...)) #'(ARG ...))
(m2 (+ 1 2)) ; 3
(define-macro (m3 (1ST 2ND 3RD)) #'(1ST 2ND 3RD))
(m3 (+ 1 2)) ; 3
(define-macro (m4 (1ST REST ...)) #'(1ST REST ...))
(m4 (+ 1 2)) ; 3
(define-macro (m5 (1ST . TAIL)) #'(1ST . TAIL))
(m5 (+ 1 2)) ; 3

1 2 3 4 5 6 7 8 9 10

(define-macro (m1 ARGS) #'ARGS) (m1 (+ 1 2)) ; 3 (define-macro (m2 (ARG ...)) #'(ARG ...)) (m2 (+ 1 2)) ; 3 (define-macro (m3 (1ST 2ND 3RD)) #'(1ST 2ND 3RD)) (m3 (+ 1 2)) ; 3 (define-macro (m4 (1ST REST ...)) #'(1ST REST ...)) (m4 (+ 1 2)) ; 3 (define-macro (m5 (1ST . TAIL)) #'(1ST . TAIL)) (m5 (+ 1 2)) ; 3



(define-macro-cases m
  [(m REQ OPT ...) #'(list REQ OPT ...)]
  [else "nope"])

(m) ; "nope"
(m 1) ; '(1)
(m 1 2) ; '(1 2)
(m 1 2 3) ; '(1 2 3)

1 2 3 4 5 6 7 8

(define-macro-cases m [(m REQ OPT ...) #'(list REQ OPT ...)] [else "nope"]) (m) ; "nope" (m 1) ; '(1) (m 1 2) ; '(1 2) (m 1 2 3) ; '(1 2 3)

• 

  Syntax patterns in the Racket Refer­ence