opts_current$set should error

[AshesITR]

As per #841 (wontfix), you're not going to support changing the current chunk options.
However, opts_current$set allows modifying the options and doesn't complain about it either.
It even succeeds in changing an option, but at least for results='asis' this leaves opts_current in an inconsistent state because the updated option is not honored.

Note how knitting the MWE, the first section reports results = markup and then results = asis despite the cat(...) being captured and commented instead.

Since programmatically updating the current chunk options will not be supported, I suggest to at least stop() when code is trying to call opts_current$set().

MWE

---
title: "Asis output test"
output: html_document
---

```{r functions}
# This is the source code chunk we want to see
the_source <- c(
  "```r",
  "a <- 'It worked. Yay!'",
  "",
  "cat(a, \"\n\", sep = \"\")",
  "# Comments in the code",
  "```"
)
try_print <- function() {
  cat("opts_current-results=", 
      knitr::opts_current$get("results"), "  \n", sep = "")
  knitr::opts_current$set(results = "asis")
  cat("opts_current-results=", 
      knitr::opts_current$get("results"), "  \n", sep = "")
  cat(the_source, sep = "\n")
  42
}
```

## Default chunk options

```{r}
try_print()
```

## Result=asis chunk option

```{r results='asis'}
try_print()
```

---

By filing an issue to this repo, I promise that

• I have fully read the issue guide at https://yihui.name/issue/.
• I have provided the necessary information about my issue.
  • If I'm asking a question, I have already asked it on Stack Overflow or RStudio Community, waited for at least 24 hours, and included a link to my question there.
  • If I'm filing a bug report, I have included a minimal, self-contained, and reproducible example, and have also included xfun::session_info('knitr'). I have upgraded all my packages to their latest versions (e.g., R, RStudio, and R packages), and also tried the development version: remotes::install_github('yihui/knitr').
  • If I have posted the same issue elsewhere, I have also mentioned it in this issue.
• I have learned the Github Markdown syntax, and formatted my issue correctly.

I understand that my issue may be closed if I don't fulfill my promises.

[AshesITR]

Here's the relevant output of the MWE:

[yihui]

opts_current is locked now. Users can no longer run its $set() method within code chunks. Thanks!

[gadenbuie]

@yihui what's the best way around this if I have a legitimate use of opts_current$set() that just didn't happen to have tests on CRAN yet?

[gadenbuie]

@yihui I figured out a way around this that will work. But I do want to point out that the documentation for opts_current has included the following for a long time

opts_current should be treated as read-only and you are supposed to only query its values via opts_current$get(). Technically you could also call opts_current$set() to change the values, but you are not recommended to do so unless you understand the consequences.

Relative to this advice, locking the binding is quite an aggressive change to make in a minor version release.

[yihui]

@gadenbuie Please feel free to unlock it by yourself with knitr::opts_current$lock(FALSE). Normally I hate forcing a decision onto users, so you can rest assured that the door is rarely tightly shut.

I'll update the documentation accordingly. Thanks for the reminder!

BTW, I'm curious about your use of opts_current$set(). Could you tell me more about it?

[gadenbuie]

Thanks @yihui! I appreciate your open door philosophy 😄 I read the comments in the "different method" commit and was worried that $lock(FALSE) was something that would go away eventually.

My use of opts_current$set() is actually to work around the limitation that opts_current$get() leaks chunk options from full R chunks to subsequent inline chunks (#1988).

```{r full-chunk, my_special_option = "hello", include = FALSE}
# some full chunk
```

`r knitr::opts_current$get("my_special_option")`
`r knitr::opts_current$get("label")`

Which renders to the following since opts_current$get() finds variables set in the previous chunk.

hello full-chunk

I found a clever way around this by using a knit_hook that runs before and after every chunk to set a flag that's only TRUE while inside a full chunk. For it to work, I needed to use opts_current$set() that sets that flag to !before, which later ensures that it's FALSE when opts_current$get() is called inside an inline chunk.

I'm now using a package-scoped global variable to hold the flag, which is fine. But I preferred opts_current$set(), since it's tightly scoped to knitr chunks and I don't have to worry about the knit lifecycle (since the package variable outlives the knit process [again, in this case it's okay but feels slightly shaky]).

[yihui]

Thanks for explaining the use case! That sounds reasonable to me.

Now I feel this change is indeed too aggressive. Let me think more about it and decide whether this should be a warning (with a hint in the message on how to unlock it) instead of an error. Sorry about the hassle!

[atusy]

I would recommend using knit_code$get() rather than opts_curret$get for the usecase of @gadenbuie .

It allows getting from a specific label or listing in the evaluated order.

``` {r x, echo=TRUE}
print(1)
```

## get chunk options of the "x" chunk

```{r, echo=TRUE}
attr(knitr::knit_code$get("x"), "chunk_opts")
```

## get latest chunk (itself)

```{r}
tail(knitr::knit_code$get(), 1L)
```

[gadenbuie]

Thanks @atusy but that's not my use case. To clarify, in my example above, the chunk option my_special_option and the chunk label -- which is essentially a chunk-scoped option -- should not be set outside the chunk in which they are defined unless they're also set globally. In this case, neither are globally scoped, so my position is that opts_current$get("my_special_option") shouldn't return "hello" outside of the full chunk where it was defined. knit_code$get() doesn't help in this case, since its focus is on block chunks only.

[cderv]

I believe the underlying issue is also important to fix (adapt)

• Inline code chunks inheriting labels #1988

as I understand opts_current$set is used to fix it.

opts$current is not something that would be used inline usually so I don't think it was thought about when introduced. I guess opts$current should return only global options and not options from the previous chunk also.

[atusy]

opts$current should return only global options

I agree.

Also, inline chunk may possibly gain chunk options in the future if we implement new syntax like `f()`{r, cache=TRUE}` discussed in #2026 (comment) .
Then, opts_current$get() certainly behave differently.

[cderv]

FWIW @yihui it seems one of the usage is to be able to tweak some chunk options from within another hook
https://github.com/wjschne/apaquarto/pull/17/files/a156dd63a7cf7ed27c07d3e6435ae2e092bed97a#diff-4f7262d8ecef665a4aecd5bd3e1767a34b6085bf40e2f8aa466edb19c9d693e4

Is there another design pattern to be able to do such modification of options from a hook that takes options as argument ?

[yihui]

Is there another design pattern to be able to do such modification of options from a hook that takes options as argument ?

@cderv Normally hooks shouldn't need the opts_current object at all. Current chunk options have already been passed to hooks via the options argument. I don't know why flextable package needs to use opts_current, but it seems to use the $get() method only. I don't know why the apaquarto project needs to set those two options, either. It will be good to know what exactly the problem they are trying to solve. Without understanding more, I feel a better solution for them is probably an option hook like:

knitr::opts_hooks$set(fig.env = function(options) {
  if (using_some_flextable_feature()) {
    # I wonder if they meant `results` instead of `output` here
    options$output = 'asis'; options$fig.env = NULL
  }
  options
})

opts_current should return only global options

The PR #2292 will do it.

[cderv]

I wonder if they meant results instead of output here

I think they meant output because it is a quarto options.

It seems they are trying to fix something related to Quarto rendering and output.

Current chunk options have already been passed to hooks via the options argument.

I think what this all means is that: If you want to tweak options, then you need to modify options hooks.
No way to modify options content from another type of hooks (unless using <<- trick or opts_current unlocking - but not adviced)

[howardbaek]

Is the fig.alt chunk option not supported in opts_current$set()?

I've tried the following:

knitr::opts_current$lock(FALSE)

if (is.null(knitr::opts_current$get("fig.alt"))) {
  knitr::opts_current$set(fig.alt = "hello world")
}

plot(pressure)

and don't see the alt.

[cderv]

@howardbaek setting option using opts_current is not really advise. This issue was about throwing an error when this was done, and it is meant for read only purposes only. We since added a locking / unlocking mechanism to help in some rare situation.
So as it was design for read only purposes, it is highly possible that fig.alt is not processed after you try to modify opts_current.

I believe your usecase is jhudsl/ottrpal#119 - maybe we can help with that and understand if there.

Example of how to modify options with options hook:

---
title: test
output: html_document
---

```{r}
knitr::opts_hooks$set(engine = function(options) {
  # do nothing for non R chunk
  if (tolower(options$engine) != "r") return(options)
  # if not fig.alt, then use a default one
  if(is.null(options$fig.alt)) {
    options$fig.alt = "individual slide notes"
  }
  options
})
```

```{r}
knitr::opts_current$get("fig.alt")
```

@yihui regarding jhudsl/ottrpal#119 use case, maybe you have insights and advices on how to modify options from within a function run in a chunk ? Question has also been asked in Communityso we could maybe follow up there too. (https://community.rstudio.com/t/setting-fig-alt-using-knitr-knit-hooks/174159)

[yihui]

There is no way to modify chunk options from within the current code chunk. Currently, the only way to modify chunk options is via option hooks (like @cderv's example above) which occurs before a chunk is evaluated. When a chunk is being evaluated or after it is evaluated, it's no longer possible to modify its chunk options.

Calling opts_current$set() won't set chunk options.

[howardbaek]

@cderv Thanks for the quick response. Your code sheds some light, but brings up followup questions.

I did try options hooks, but this didn't work:

knitr::opts_hooks$set(fig.alt = function(options) {
  # if not fig.alt, then use a default one
  if(is.null(options$fig.alt)) {
    options$fig.alt = "individual slide notes"
  }
  options
})

I don't fully understand how to use opts_hooks$set(). For my learning, why do we set engine as the function name inside opts_hooks$set(). This might be a related question, but what is the purpose of this line? if (tolower(options$engine) != "r") return(options)

Also, regarding jhudsl/ottrpal#119, I inserted your code inside include_slide()

include_slide <- function(url,
                          output_dir = knitr::opts_chunk$get("fig.path"),
                          overwrite = TRUE, ...) {
 # set fig.alt
  knitr::opts_hooks$set(engine = function(options) {
    # do nothing for non R chunk
    if (tolower(options$engine) != "r") return(options)
    # if not fig.alt, then use a default one
    if(is.null(options$fig.alt)) {
      options$fig.alt = "individual slide notes"
    }
    options
  })

  outfile <- gs_png_download(url, output_dir, overwrite = overwrite)
  knitr::include_graphics(outfile, ...)
}

and experimented inside a Rmd:

---
title: "test"
output: html_document
---

```{r}
ottrpal::include_slide("https://docs.google.com/presentation/d/1YmwKdIy9BeQ3EShgZhvtb3MgR8P6iDX4DfFD65W_gdQ/edit#slide=id.gcc4fbee202_0_141")

knitr::opts_current$get("fig.alt")
```

But the last line prints NULL, so don't think its working inside a function?

BTW, how did you insert Rmd code chunks into this issue without having to put a \ before the ```?

[cderv]

I did try options hooks, but this didn't work:

You set an option hook on fig.alt directly. As we document in our doc (https://bookdown.org/yihui/rmarkdown-cookbook/option-hooks.html)

An option hook is a function associated with the option and to be executed when a corresponding chunk option is not NULL.

So you can't set a default fig.alt is there is no fig.alt initially (fig.alt = NULL). You need to set the option hook on another value.

For my learning, why do we set engine as the function name inside opts_hooks$set(). This might be a related question, but what is the purpose of this line? if (tolower(options$engine) != "r") return(options)

This is why I gave you the example with setting the option hook on the engine option, because it will always be non-NULL for a chunk. I added a test on engine R to give an example on how to restrict the behavior to R engine. (engine could be python or bash, or anything and you may want to only target R).

You could set the option hook to anything that has meaning for your issue. For example you could want to set a default fig.alt for figures, and assumes fig.cap will always be provided in this case, and you don't want fig.alt = fig.cap. You will set an option hook on fig.cap to set a default value for fig.alt, before knitr does set fig.alt = fig.cap by default when fig.alt is NULL.

I inserted your code inside include_slide() (...) But the last line prints NULL, so don't think its working inside a function?

You need to run the hook function once before it can apply on a chunk. As you put it in your function, called the function and in the same chunk test that the fig.alt is modified this won't work. However, for other following chunk, you should see the difference. But here you will setup the hook each time your function in run and you want it to apply on the same chunk, so I don't this will work like this.

Setting up a option hook will apply to the whole documents, and all chunks. Usually best way to set them up are:

• Manually by a user in a setup chunk, so that it applies on all other document - but you probably don't want that
• By providing a ottrpal::setup_rmd() (or similar) that a user should run in a setup chunk when using your tool.
• by setting up the hook when your Package is loaded in a knitr context for example. A bit advanced but should work.
  • We're talking about .onLoad() or rlang::on_load()
  • So when a user to library(ottrpal), you would check knitr context and run the hooks setup. this should set up the hooks for all usage
  • You can probably find example of this on Github Search.
• By creating a custom format ottrpal::html_document() that just modifies the default one by adding some knit_hooks for options
  • See output_format() and knitr_options()
  • Example can be found on Github like reportrmd::multi_document() which defines lots of hooks.
  • You can probably find example of this on Github Search too.

Hope it helps

BTW, how did you insert Rmd code chunks into this issue without having to put a \ before the ```?

Just follow the issue guide: https://yihui.org/issue/#please-format-your-issue-correctly

[howardbaek]

Yes, this helps a lot. What I'm trying to implement is not possible in knitr. I'll have to figure out a workaround fix.

[github-actions]

This old thread has been automatically locked. If you think you have found something related to this, please open a new issue by following the issue guide (https://yihui.org/issue/), and link to this old issue if necessary.