Thank you for your comment

Beau­tiful Racket / explainers

Macros

A macro is a special kind of func­tion that runs at com­pile time, consuming cer­tain code as input and rewrit­ing it as new code. Macros are also known as syn­tax trans­formers.

For instance, and is a macro:

(and (expr a) (expr b) (expr c))
1
(and (expr a) (expr b) (expr c))
copy to clipboard

That rewrites its input like so:

(if (expr a)
    (if (expr b)
        (expr c)
        #f)
    #f)
1
2
3
4
5
(if (expr a)
    (if (expr b)
        (expr c)
        #f)
    #f)
copy to clipboard

The code resulting from a macro is called the expan­sion of the macro, because it’s often longer than the input code (though it can be any length).

Even though macros are func­tions, it’s conven­tional to refer to them strictly as macros, and reserve the term func­tion for the tradi­tional kind of func­tion that’s eval­u­ated at run time. Macros are also called syntactic forms or just forms (espe­cially in the Racket docu­men­ta­tion).

Why macros?

Macros are valu­able for two reasons:

  1. At the program level, macros allow us to imple­ment ideas in code that can’t be achieved with ordi­nary func­tions.

    For instance, let’s figure out how to make report, which prints an expres­sion, and then returns the result of the expres­sion normally.

    (report (* 1 2 3 4))
    1
    (report (* 1 2 3 4))
    copy to clipboard

    Suppose report were an ordi­nary func­tion. The expres­sion (* 1 2 3 4) would be eval­u­ated as 24, which would become the input to report. But then the orig­inal expres­sion couldn’t be printed, because report would never see it. So report can’t be a func­tion.

    Whereas if report is a macro, its input includes the literal code (* 1 2 3 4), which can be manip­u­lated as code:

    (define-macro (report EXPR)
      #'(begin
          ; EXPR used as literal data, and quoted as a datum
          (displayln (format "input was ~a" 'EXPR))
          EXPR)) ; EXPR used for its result
    (report (* 1 2 3 4))
    1
2
3
4
5
6
    (define-macro (report EXPR)
  #'(begin
      ; EXPR used as literal data, and quoted as a datum
      (displayln (format "input was ~a" 'EXPR))
      EXPR)) ; EXPR used for its result
(report (* 1 2 3 4))
    copy to clipboard

    Now if we run report, we get the right result:

    (report (* 1 2 3 4))
    1
    (report (* 1 2 3 4))
    copy to clipboard
    input was (* 1 2 3 4)
    24
    1
2
    input was (* 1 2 3 4)
24
    copy to clipboard

    In this way, macros resemble tools like the C preprocessor. But unlike a preprocessor, which usually involves a limited vocab­u­lary of oper­a­tions, a macro can use every­thing in the Racket language.

    Further­more, macros enforce hygiene, which is a set of guar­an­tees about how macro-gener­ated code will interact with other code. Under­standing hygiene is essen­tial to under­standing macros. See hygiene.

  2. At the compiler level, macros allow forms to be expressed in terms of progres­sively more prim­i­tive forms, all the way down to a set of core syntactic forms. By only handling this small set of core syntactic forms, Racket can compile, opti­mize, and eval­uate programs more effi­ciently. For instance, we saw that and is expressed in terms of if. For that matter, so are when and or. In turn, if is a core syntactic form.

    Within a Racket-imple­mented program­ming language, we often use macros within our expander to convert the forms of our language into stan­dard Racket forms. But really, we’re just stacking more macros atop an existing tower of macros, all of which lead back to the core syntactic forms.

Inter­face & oper­a­tion

Macros are func­tions that take one syntax object as input and return another syntax object. These syntax objects contain literal code, pack­aged with meta­data like lexical context and source loca­tion.  + To get around the limited inter­face, macros can read and write arbi­trary syntax prop­er­ties to pass extra meta­data or argu­ments to other macros. See syntax objects for the whole story.

The syntax object passed to a macro contains the whole calling expres­sion that invoked the macro. So if we invoke and like this:

(and (expr a) (expr b) (expr c))
1
(and (expr a) (expr b) (expr c))
copy to clipboard

and does not get three argu­ments as input, the way an ordi­nary func­tion would. Rather, it gets a syntax object like this, which retains a refer­ence to the lexical context of the calling site:

(and #'(and (expr a) (expr b) (expr c)))
1
(and #'(and (expr a) (expr b) (expr c)))
copy to clipboard

A macro extracts the pieces of the input syntax object and rearranges them into new code. Usually this is done with the help of syntax patterns, which match these pieces to pattern vari­ables. For example, we could imple­ment and as shown below, using three syntax patterns to handle input cases of zero argu­ments, one argu­ment, and two or more argu­ments. The pattern vari­ables are capi­tal­ized:

(define-macro-cases and
  [(and) #'#t]
  [(and COND) #'COND]
  [(and COND OTHER-CONDS ...) #'(if COND
                                    (and OTHER-CONDS ...)
                                    #f)])
(and) ; #t
(and 42) ; 42
(and 42 #f) ; #f
(and 42 #f #t) ; #f
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
(define-macro-cases and
  [(and) #'#t]
  [(and COND) #'COND]
  [(and COND OTHER-CONDS ...) #'(if COND
                                    (and OTHER-CONDS ...)
                                    #f)])
(and) ; #t
(and 42) ; 42
(and 42 #f) ; #f
(and 42 #f #t) ; #f
copy to clipboard

The expres­sion on the right side of each branch is the output code for that branch, using #' to package it as a syntax object. Refer­ences to pattern vari­ables are auto­mat­i­cally replaced with the matched item.

Unlike nested expres­sions, which are eval­u­ated from the inside out, nested macros are eval­u­ated from the outside in. This makes it possible for macros to generate refer­ences to other macros, which in turn are expanded. For instance, the third branch of and includes a recur­sive refer­ence.  + As with ordi­nary func­tions, it’s possible to acci­den­tally create macros with infi­nite recur­sion.

Because macros are expanded at compile time, they can’t access the run-time mean­ings of the input code (because while the macro is running, those mean­ings have yet to be estab­lished). There­fore, a macro has to handle its input argu­ments strictly as syntactic items.

Why not macros?

Macros aren’t a substi­tute for ordi­nary func­tions. Macros are inher­ently more limited:

More­over, because macros can rewrite code in arbi­trary ways, they can make code less read­able and predictable. It’s tempting, for instance, to infer that this line of code creates a vari­able named fruit with the value "banana":

(define fruit "banana")
1
(define fruit "banana")
copy to clipboard

But we’d be assuming that in this language, define has its usual meaning. It might not. What if our language rede­fines define with a macro?

(define-macro (define NAME VALUE)
  #'"orange you glad I didn't say banana?")
(define fruit "banana")
1
2
3
(define-macro (define NAME VALUE)
  #'"orange you glad I didn't say banana?")
(define fruit "banana")
copy to clipboard

Early-stage Rack­e­teers are some­times tempted to use macros to avoid learning the idioms of the core Racket library. Why? Because writing macros is fun; learning the library, less fun. But in the long term, it’s a false economy. You’ll want to under­stand Racket idioms because you’ll even­tu­ally need to read other Racket code (and others will need to read yours).

Mixing macros & func­tions

Macros are powerful, but they’re not free. Expanding a macro is addi­tional work that has to be done at compile time. A macro creates new code, which then has to be compiled and inter­preted at run time.

In general, ordi­nary func­tions have better perfor­mance char­ac­ter­is­tics. There­fore, some tips for combining them effi­ciently:

Further

← prev next →