document macro hygienification; expose it to the user

[o-jasper]

The transformation that quoted code generated by macros undergoes before being inserted into a local AST needs two things:

1. documentation in metaprogramming
2. exposure to the user

These are related because documentation will be much easier and more effective if it can be demonstrated.

ORIGINAL ISSUE

On e519c91, the following:

function value_one() #Of course it works
   1
end
macro defv2 ()                      
   :(function value_two()
      2
     end)
end
@defv2
value_two #Not defined!

Found this out with the get_c_fun macro.. I'd much prefer to keep using that.

[StefanKarpinski]

This is a macro hygiene issue. Since modules were introduced, there are now two contexts that each macro needs to work with: the defining context and the evaluating context. The rules are basically that things that are localish — meaning things that in a scope would be made local via assignment or whatever — are automatically renamed not to clash with the calling context (this avoids the need for gensyms most of the time); things that are globalish are assumed to come from the macro definition context and are rewritten as such. In order for something to not be interpreted as in the definition context or as something the be rewritten as a local, it has to be escaped using the esc function. In this case, value_two is rewritten to a non-clashing name as though it were gensym:d. This version does what you want:

julia> macro defv2 ()
          :(function ($esc(:value_two))()
             2
            end)
       end

julia> @defv2

julia> value_two
Methods for generic function value_two
value_two() at none:3

julia> value_two()
2

[toivoh]

So the issue is really to update the julia manual?
I guess a newsletter could be a good place to announce these kind of changes too.

[o-jasper]

If I println the value you don't see value_two replaced by gensyms. Looks like the macro output is hygienized afterward, so i don't really understand how this relates to $ notation, you can get the same avoiding $ completely;

macro defv2 ()
  Expr(:function,{Expr(:call,{:value_two},Any),2},Any)
end

If it is just a function applied afterward, maybe it should be exposed to the user? Then they can esc something and hygienize some subtrees of it.(I can't find an unesc or `hygienize function so far) You could ofcourse leave it up to the user the hygienize, but maybe hygienic macros might get underused that way..

If you do apply hygienize afterward in regular macros, it is probably a good idea to give the user the tools to look at the result. Something like a macro_expand_1. (A macro version could help a bit with the workflow, as then you don't need to quote it.)

[StefanKarpinski]

If it is just a function applied afterward, maybe it should be exposed to the user? Then they can esc something and hygienize some subtrees of it.(I can't find an unesc or `hygienize function so far) You could ofcourse leave it up to the user the hygienize, but maybe hygienic macros might get underused that way.

100% agree. In fact, I'm turning this issue into a request for this to be documented in the metaprogramming section and to expose this functionality to the user.

[JeffBezanson]

Which copy of the manual do I edit? <-- major problem

[StefanKarpinski]

What do you mean? There's only one at this point.

[JeffBezanson]

Done.