macro documentation and implementation mismatch

[RauliRuohonen]

From the docs (Manual/Metaprogramming):

macro time(ex)
  quote
    local t0 = time()
    local val = $ex
    local t1 = time()
    println("elapsed time: ", t1-t0, " seconds")
    val
  end
end

Julia’s macro expander solves these problems in the following way. [...] Local variables are then renamed to be unique (using the gensym function, which generates new symbols), and global variables are resolved within the macro definition environment. Therefore both of the above concerns are handled; the macro’s locals will not conflict with any user variables, and time and println will refer to the standard library definitions.

Yet if you put the above code verbatim into a script and tack this to the end:

println("I'm println in the macro definition environment and I'm all right.")

function g()  
    println("That same println still works. Functions' hygiene is impeccable!")
end

function f()
    println = "I'm println the user variable! Thou shalt not conflict with me!"
    g()
    @time sleep(1)
end

f()  

You get the output:

I'm println in the macro definition environment and I'm all right.
That same println still works. Functions' hygiene is impeccable!
ERROR: type: f: in apply, expected Function, got ASCIIString

That println sure doesn't refer to the standard library one like the docs say. Comparing the result to g(), one can clearly see macros' lack of hygiene compared to functions. If the macro is defined in a different module, then it works because println is expanded to TheOtherModule.println. This could be fixed by expanding it to TheCurrentModule.println when it's not from a different module, so that in any case the globals lookups are always done from some module's globals.

Another one: the definition of assert in error.jl is different than claimed in the docs. One might say in the docs that this is a simplified version of the one in error.jl. More importantly, the use of $ex instead of $(esc(ex)) would be better fixed or remarked upon ("this is subtly broken as we see in the next section" or something) lest someone imitate it because the official docs say that this is good enough for the standard library! The unescaped assert from the docs is not that hard to break:

x = 1
@assert (x -> x)(x) == 1

results in:

ERROR: x#12 not defined

[staticfloat]

@JeffBezanson is the best thing to do here to just update the docs? Or ask users to directly use Base.println() etc... inside of macros?

[JeffBezanson]

No, this is a bug.

[staticfloat]

Since macros are executed at parse-time in the caller's scope, how could this work any other way? In order to ignore the function-local println you'd have to define the macro's println function as global somehow, no?

[JeffBezanson]

Yes, but that is (should be) done automatically by the macro expander, which rewrites identifiers as e.g. Base.println as necessary.

[vtjnash]

maybe the new GlobalRef can be inserted now to fix the first macro issue?