logr-globals.Rmd

---
title: "Global Options"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Global Options}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```
There are situations when you want to control log printing globally.  For
those cases, **logr** has some global options.  

The option "logr.on" accepts
a `TRUE` or `FALSE` value, and determines whether the **logr** log is on 
or off.  The option "logr.notes" also accepts a `TRUE` or `FALSE` value,
and determines whether to include notes in the log.  Both of these global 
options will override any local settings.  

The following code sample demonstrates how to use these options:
```{r eval=FALSE, echo=TRUE}
# Turn logger off 
options("logr.on" = FALSE)

# Turn logger on and show notes 
options("logr.on" = TRUE, "logr.notes" = TRUE)

# Turn off notes
options("logr.notes" = FALSE)
```

There is also a global option to turn on the **autolog** feature.  Autolog
will automatically print logging entries for many **dplyr** and **tidyr**
functions.  This option can greatly reduce the number of `log_print()` or
`put()` statements needed to obtain a complete log. The autolog feature 
can be turned on or off
by a parameter on the `log_open()` statement, or by the "logr.autolog"
global option, as follows:

```{r eval=FALSE, echo=TRUE}
# Turn autolog on
options("logr.autolog" = TRUE)

# Turn autolog off
options("logr.autolog" = FALSE)

```

If you want to minimize the size of the log, there is a global option 
called "compact" to remove any blank spaces between log entries.  This setting
essentially forces the "blank_after" parameter on `log_print()` to FALSE
for all entries.

```{r eval=FALSE, echo=TRUE}
# Turn on compact option
options("logr.compact" = TRUE)

# Turn off compact option
options("logr.compact" = FALSE)
```

By default, **logr** will print a traceback of all error messages.  In most
cases, this is a useful feature to help you precisely identify the source of
an error.  In some cases, the traceback provides too much unnecessary information.
The "logr.traceback" global option can be used to turn the traceback messaging
on or off.  The option accepts a TRUE or FALSE value, which will override
anything set on `log_open()`.

```{r eval=FALSE, echo=TRUE}
# Turn on traceback messaging
options("logr.traceback" = TRUE)

# Turn off traceback messaging
options("logr.traceback" = FALSE)
```

If warnings are generated during execution of a program, they will be written
to both the log and the message file.  Warnings can also be returned
programmatically using the `get_warnings()` function.  The **logr** package will
additionally populate a global variable named "logr.warnings" with a vector of 
the warnings. This global variable can be accessed as follows:

```{r eval=FALSE, echo=TRUE}
# Get warnings from function
w1 <- get_warnings()

# Get warnings from global variable
w2 <- getOption("logr.warnings")
```

In some situations, you may want to print the log to the console instead
of a file.  The "logr.stdout" option allows you to do that.  The syntax to
set the global option is this:
```{r eval=FALSE, echo=TRUE}
# Print log to stdout (console)
options("logr.stdout" = TRUE)
```

To restore printing to a file, you can set the "stdout" option to FALSE, or remove
the option entirely.  Like this:
```{r eval=FALSE, echo=TRUE}
# Restore printing
options("logr.stdout" = FALSE)

# Remove stdout option
options("logr.stdout" = NULL)
```

Next: [Aliases for log_print()](logr-put.html)