The whole file is wider on this screen: https://github.com/Cvikli/JuliaMacroCheatSheet/blob/main/README.md

For me https://docs.julialang.org/en/v1/manual/metaprogramming/ just couldn't make these things understand so I tried to be as short as possible to reach understanding in each point.

Please help us correct things and any simplification is welcomed, It is still a little bit too complicated I know, this have to be even shorter!

In short: Escape: = "Access the local scope from where the macro is called!" In macro hygiene, each interpolated variable(VAR) in the macro points to the module where the macro is defined (ex: Main.VAR or MyModule.VAR) instead of the local VAR in the macro's calling scope.

a=1
macro wrong(); :($:a);  end        
     let a=2; @wrong(); end            # =1
eval(let a=2;  :($a);   end)           # =2  (exactly the same like: (`let a=2; a; end`))
macro correct(); :($(esc(:a))); end   
     let a=2;    @correct();    end    # =2
eval(let a=2;    :($(esc(:a))); end)   # ERROR: syntax: invalid syntax (escape (outerref a))

BUT it generates new variable for the macro scope instead of the "local" scope. So eventually it doesn't see the outer scope variables in this case and believe this is the "new scope where the expression has to work".

a=1
macro ✖(ex); :($ex); end         
macro ✓(ex); :($(esc(ex))); end    # this works similarly: `:(:ey)`
eval(        :(a=2))               # a=2
# eval(        :($(esc(a=3))))     # ERROR: MethodError: no method matching esc(; b::Int64)
@✖ a=4                             # a=2
@✓ a=5                             # a=5
display(@macroexpand @✖ a=4)       # :(var"#54#a" = 4)
display(@macroexpand @✓ a=5)       # :(a = 5)

also

macro ✖(va, ex); :($va=$ex); end 
macro ✓(va, ex); :($(esc(va))=$(esc(ex))); end 
@✖ a 5
@✓ a 6
display(@macroexpand @✖ a 5) # :(var"#7#a" = 5)
display(@macroexpand @✓ a 6) # :(a = 6)

First time it works in the macro scope, so it shadows(gensym(:a)) the variable, second time it creates :a symbol into the scope as a variable. We need to use esc to reach the local scope.

quote 2+3 end == :(begin 2+3 end)  # both preserve the linenumbers (verifiable with `dump(…)`)
:(2+3)                             # also similar but without FIRST Linenumber

$ (expression interpolation) evaluates when the expression is constructed (at parse time)

:(…) or quote … end(Quotations) evaluates only when the expression is passed to eval at runtime.

Note:

• All test has included using Base.Meta: quot, QuoteNode.
• Linenumbers are removed from the CheatSheet!

x=:p   # Main.x
p=7    # Main.p

x=:p   # Main.x
p=7    # Main.p

n=:(1 + 2)

ex=:ey  # Main.ex
p=7     # Main.p

ex=:ey  # Main.ex
x=:p    # Main.x
p=7     # Main.p

ex=:ey  # Main.ex
p=7     # Main.p

ex=:ey   # Main.ex
x=:p     # Main.x
p=7      # Main.p

q=:p  # Main.q
p=7   # Main.p

• If you validate the ex.head, then using the function in a macro can lead to unusability due to escaping the expression to reach local scope. Because it is $(Expr(:escape, VAR)) where ex.head == :escape. Issue: JuliaLang/julia#37691 (So while this is an edge case we should be keep it in our mind if we want to create really universal macros.)

• $esc(…) instead of $(esc(…))

• $QuoteNode(…) instead of $(QuoteNode(…))

• https://riptutorial.com/julia-lang/example/24364/quotenode--meta-quot--and-ex--quote-

• https://nextjournal.com/a/KpqWNKDvNLnkBrgiasA35?change-id=CQRuZrWB1XaT71H92x8Y2Q

Section: https://docs.julialang.org/en/v1/manual/metaprogramming/#man-quote-node

Still total chaotic for me and cannot make a simple explanation. My weak explanation throught tests:

                       :(   $:(1+2))   #                               :(1 + 2)  note if it would be $n then of course the interpolation would be visible!
                    Expr(:$, :(1+2))   #                  :($(Expr(:$, :(1 + 2))))
               quot(Expr(:$, :(1+2))   # :($(Expr(:quote, :($(Expr(:$, :(1 + 2)))))))
          QuoteNode(Expr(:$, :(1+2))   #    :($(QuoteNode(:($(Expr(:$, :(1 + 2)))))))
               eval(Expr(:$, :(1+2))   # ERROR: syntax: "$" expression outside quote
          eval(quot(Expr(:$, :(1+2)))  # 3
     eval(QuoteNode(Expr(:$, :(1+2)))  #                  :($(Expr(:$, :(1 + 2))))
eval(eval(QuoteNode(Expr(:$, :(1+2)))) # 3

Unfinished but main doc is okay actually:

• https://docs.julialang.org/en/v1/manual/metaprogramming/#meta-non-standard-string-literals

• https://docs.julialang.org/en/v1/manual/metaprogramming/#Generated-functions