Improved discussion of source()

[hadley]

• Don't mention sys.source() as people shouldn't be using it anyway
• Use local = TRUE which is simpler and still correct
• Precisely describe the problem caused the default behaviour of source()

[yihui]

• Don't mention sys.source() as people shouldn't be using it anyway

I don't understand that.

• Use local = TRUE which is simpler and still correct

Simpler, true. Correct, I don't think it is guranteed.

• Precisely describe the problem caused the default behaviour of source()

Yes, I agree this needs more clarification.

Thank you!

[yihui]

But this is more robust than local = TRUE. It works anywhere (e.g. inside a function). It's an absolute environment, and local = TRUE is a relative environment, which is subject to your current environment, and could be confusing when it is not called directly in a code chunk but from another function, e.g.,

load_scripts <- function(files) {
  for (f in files) source(f, local = TRUE)
}
load_scripts(c('a.R', 'b.R'))

Both local = TRUE and FALSE have their usefulness. There isn't an absolutely correct choice, so I didn't strongly emphasize one or another. Perhaps the distinction between the two choices should be explained more clearly in this section. In general, I feel source("your-script.R", local = knitr::knit_global()) is still the safest choice.

[hadley]

Yeah, if you want to run source() inside a function and have it impact code outside of the function, you're going to have to do something special. As a general principle, I don't think functions should mutate the global environment in this way, so I do believe that local = TRUE is the correct recommendation here. (And then mention local = knitr::knitr_global() as a special case if you really want to do that)

[hadley]

But this is now really about advice for writing functions that call source, not about calling source() in knitr chunks.

[yihui]

We don't recommend ever using sys.source() as it is designed specifically for internal use by base R.

I haven't heard of this before and am surprised to learn it. Could you point out the source of this claim? The help page ?sys.source didn't say it was designed only for internal use by base R. I mentioned sys.source() because it does a much simpler job than source(), i.e., it basically does eval(parse()), whereas source() does several other things that are irrelevant to evaluating the code.

[hadley]

I think it's implied by the envir argument which defaults to baseenv() — there is no case in which a user would want this. Do you have any evidence to suggest that people are using sys.source() in the wild?

[yihui]

Usually, knitr will evaluate code in a child of the global environment

Usually knitr evaluates code just in the global environment, instead of a child of the global environment. knitr::knit() and rmarkdown::render() have envir = parent.frame() by default, which points to globalenv() if you call them in the global environment.

so any assignments in the source file will be overridden by assignments in earlier chunks

I'm confused: did you mean earlier or later? If you have x <- 1 in the source file, after you source() it, the assignment will be overridden by x <- 2 in a later chunk. Similarly, if you have x <- 0 in an earlier chunk, source() will override it with x <- 1.

[hadley]

I read the following paragraph to imply that knitr usually evaluates in some special environment:

The default values for them may not be the appropriate environment: you may end up creating variables in the wrong environment, and being surprised that certain objects are not found in later code chunks.

If knitr usually evaluates in the global environment, then calling source() with no arguments will usually be safe.