Option to send $sample() output to file instead of console #473

Summary

I would like to be able to route to a file all of the messages (diagnostics, etc.) that $sample() prints to the console.

Possible interface options

There are two obvious options for how to expose this:

1. Have a new argument (something like messages_file or messages_out_path) that take a file path and sends all output to that file.
2. Change the show_messages argument to accept a boolean or a file path:

• TRUE prints messages to console
• FALSE prints no messages
• path sends messages to file instead of console

The second option has the appeal of not adding another (fairly specific) argument, though it does make this argument take mixed types (logical or character). This is a little messy, but not unprecedented (for example, callr does it here).

This second option would also mean that the user could either print to console or save to file, but not both. Looking at the implementation in processx, we may be stuck with this behavior regardless, in which case I'd prefer this second solution. However, I think ideally the user could choose console, file, or both.

Additional context

This originally came out of discussion in #424 and @rok-cesnovar suggested splitting this into its own issue.

There are some possible workarounds, which I think makes this not super high priority. For example, @wlandau uses withr for this purpose in stantargets. It's also possible to call $sample() within either callr::r() or callr::r_bg() and use the show, stdout, and stderr args to accomplish any desired combo of logging to the console and/or a file:

res <- callr::r(
  {function() stanmod$sample(...)},
  args = list(stanmod),
  show = TRUE,                # controls printing to console
  stdout = "/some/log/file",  # sends stdout to file
  stderr = "2>&1"             # interleaves stderr with stdout
)