Including code that defines a module within a function definition does not fail!?

[PetrKryslUCSD]

I thought this was illegal. Yet with Julia 1.5.3 including the file M.jl runs:

# M.jl

# This works
function main()
    include("A.jl")
end; 
main()

# When the contents of the file A.jl is pasted directly into the function, there is an error.
#function main()
#    module App
#    function main()
#        println("in App")
#    end; main()
#    end
#end; 
#main()

and

# A.jl
module App
function main()
    println("in App")
end; main()
end

[mgkuhn]

Seems to behave as documented, because include evaluates what it loads in the containing module's global scope. It should make no difference whether you put the include inside or outside the function.

help?> include

  include([mapexpr::Function,] path::AbstractString)

  Evaluate the contents of the input source file in the global scope of the
  containing module.

[PetrKryslUCSD]

That is certainly true, that bit is in the documentation. However, one also hears how the include mechanism is essentially copying and pasting the contents at the location where the include statement occurs. So should placing include inside a function be illegal, because the evaluation is occurring in the enclosing scope anyway?

[mgkuhn]

Since include() is a normal Julia function, just like e.g. eval(), it is executed each the time your wrapping function main() is called, and has no access to the local scope of your function main. Why should calling the include() function from other functions be banned? (Important: Julia's include() function is in no way similar to e.g. the C preprocessor's #include instruction; as the latter is a pre-compilation step and not a run-time function call. I suspect being familiar with C might initially hinder some user's understanding of Julia's include() in a way that may not hinder their understanding of say eval().)

See also Discourse thread Is “include” safe to use inside a function?

[KristofferC]

However, one also hears how the include mechanism is essentially copying and pasting the contents at the location where the include statement occurs.

Wherever one hears that one should correct it. It is not true.

I don't think there is anything to do here.

[vtjnash]

If we really wanted to confuse the issue, we could make a @include "file" macro that does literally parse and paste the AST into the parent scope.

[PetrKryslUCSD]

In my opinion that would clarify the issue: I think many programmers, including myself, up to a few minutes ago, sort of get misdirected by the usual form of include which happens outside of the function and hence in the correct scope, to consider include equivalent to copying and pasting. Having a macro pointed to from the documentation for the function would I believe be helpful in that it would highlight the difference.

[mgkuhn]

Also, highlighting in the documentation more clearly that include() is a function call would help to overcome preconceived notions from C's #include. At the moment, the manual gives in “The expression include("source.jl") causes” a bit the impression that it is an "expression" with a special meaning. Change to “Calling the function include("source.jl") evaluates” perhaps?

[yuyichao]

If we really wanted to confuse the issue, we could make a @include "file" macro that does literally parse and paste the AST into the parent scope.

No that will only add to the confusion since people will think the include will happen at the wrong time.

[PetrKryslUCSD]

It may be a good idea to give the macro a different name, dissociating it from the include function. Perhaps @source? In any case I think that putting a little bit more effort into explaining the include function could incorporate contrasting it with the macro, which would literally paste the source at the spot. What is confusing about include is that (most) programmers use include in the global scope, which is equivalent to copying and pasting the code, isn't it?

[KristofferC]

The documentation is already quite explicit about what it does (evaluate into the global scope of the module etc). But perhaps it can be even more clear.

[PetrKryslUCSD]

Sure, but Markus' suggestion above is worth considering, I think. Also, an example might be helpful, because the current examples really evaluate the code in the top scope, and there is none that would illustrate how the code is not evaluated in the scope in which the include function is called.