This stashes the setup chunks in an environment called setup_chunks. This will enable two things:

1. It will allow remote evaluators to access the setup chunk so that they can run the relevant setup code before running user exercises. e.g. imagine that all of your exercises presume some package is loaded.
2. It will later allow us to keep the exercise-specific -setup chunks private instead of serializing them through the client. This work has not been taken on yet, though.

You'll find the following changes:

• The cache gets cleared every time a tutorial is initialized, so there's no risk of inheriting setup chunks from a previous rmarkdown::run.
• Exercise-specific chunks are saved by the corresponding exercise chunk name (i.e. trim the -setup suffix.
• The global setup chunk is stored under a special name __setup__ (to avoid conflicts with a chunk called setup-setup.
• This PR introduces a new special chunk named setup-global-exercise which -- if it exists -- will take the place of the setup chunk in this setup_chunks environment. We do this because a.) the global setup chunk may include initialization code that takes time and isn't relevant to the exercises, and b.) the global setup chunk may include sensitive information that we don't want to leak into the user's exercise environment. (I presume that by sending a setup chunk to run with arbitrary user code, you're effectively giving access to that code.) Therefore users can opt to define a setup-global-exercise chunk which only prepares the specific environment that their exercises will need. Exercise-specific -setup chunks continue to behave as they did in the past.
• We add a new knitr hook for source. These hooks are documented here. See below for description.

TODO

• tests
• NEWS (no user-visible changes)
• remove hook
• testing & validation notes
• docs (no user-visible changes, the corresponding docs will be folded into the next PR)

knitr hooks

Currently, we set a global knitr option to set tutorial = TRUE: https://github.com/rstudio/learnr/blob/master/R/knitr-hooks.R#L7

This has the same effect as writing tutorial=TRUE as an option on top of each of the code chunks in the learnr document. Then when we want to act on the chunks in the document, we can just use the tutorial hook to do so, since all chunks have that options set to TRUE. https://github.com/rstudio/learnr/blob/master/R/knitr-hooks.R#L118

Unfortunately, setting tutorial to TRUE only affects latter chunks, not the current one. From ?knitr::opts_chunk:

Normally we set up the global options once in the first code chunk in a document using opts_chunk$set(), so that all latter chunks will use these options. Note the global options set in one chunk will not affect the options in this chunk itself, and that is why we often need to set global options in a separate chunk.

Since the knitr hook gets defined in .onAttach (see here), this means that whatever chunk calls library(learnr) will invoke this code, and it will impact all the chunks below that one -- but not the current one. That's a problem for us, since library(learnr) usually gets called in the setup chunk.

Therefore we can't just hook into the tutorial option like we've done in the past -- instead we have to hook onto something that globally has access to all chunks including the setup chunk. Therefore, we add a new hook on source = which handles that. Unfortunately, these hooks are all singletons so we clobber any existing hooks when we assign. Therefore you'll see that we take precaution to preserve the existing hook and invoke it later at the end of our hook. So this hook only has side-effects of stashing setup chunks, but the return value continues to be from whatever hook was defined before us.

Testing & Validation

There are no user-visible changes in this PR, but we can still test a few things.

Run remotes::install_github("rstudio/learnr@save-setup")

Confirm we didn't break exercise-specific setup chunks

• In the RStudio IDE, click New > R Markdown > From Template > Interactive Tutorial to get a learnr template that you can play with

• above the chunk named two-plus-two, add a new chunk named two-plus-two-setup. This is exercise-specific setup code that should be run ahead of whatever code you provide in the exercise. In this -setup chunk, define a variable named x.
  

• click Run Document and in the first exercise, run x. You should see it print out whatever value you assigned in the -setup chunk.

• In another exercise chunk, set the code to x and observe the error: object 'x' not found.

This confirms that the exercise-specific setup chunks still work. They run only for the exercise whose name they match, but not for any others.

Test that setup becomes the global setup chunk

The desired behavior is that the global exercise setup would come from a chunk named setup-global-exercise. If no chunk by that name exists, then it would use the chunk named setup.

1. In the modified learnr tutorial from above, with the tutorial running, run the following code in one of the exercise blocks:

ls(learnr:::setup_chunks) # print all known setup chunks
get("__setup__", envir = learnr:::setup_chunks) # print the contents of the global setup chunk

2. You should see two values printed for the first call ([1] "__setup__" "two-plus-two") and the second call should print out whatever you have in your setup chunk at the top of your document. You can modify that chunk and rerun the tutorial to confirm that it's updated.
3. Add a chunk named setup-global-exercise with some code inside of it. When you rerun the tutorial, you should now see that the above code, when run in an exercise, prints the contents of this new code chunk instead of the original setup chunk.
4. Confirm that even if setup-global-exercise chunk is empty with no code in it, it's still preferred as the global setup chunk (this exercises a different code path than when it has content in it).