---
title: "matahari"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{matahari}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
Please see the matahari website for full documentation:
*
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
```{r setup}
library(matahari)
```
There are three ways to use the matahari package
1. Record R code as it is typed and output a tidy data frame of the contents
2. Input a character string of R code and output a tidy data frame of the contents
3. Input an R file containing R code and output a tidy data frame of the contents
This vignette will walk through how to do each of these tasks.
## Record R code as it is typed
To record R code as it is typed, use the `dance_start()` and `dance_stop()` functions.
```{r,eval = FALSE}
# Start logging your R commands run in the console
dance_start()
4 + 4
"wow!"
mean(1:10)
# Pause logging
dance_stop()
# Look at your log as a tidy data frame
dance_tbl()
```
```r
#> # A tibble: 6 x 6
#> expr value path contents selection dt
#>
#> 1 2019-05-14 08:15:24
#> 2 2019-05-14 08:15:24
#> 3 2019-05-14 08:15:25
#> 4 2019-05-14 08:15:25
#> 5 2019-05-14 08:15:25
#> 6 2019-05-14 08:15:25
```
Each time `dance_start()` is run, a data frame logging the subsequent code is updated. To start over with a _new_ data frame, you can use `dance_remove()` and then re-run `dance_start()`.
```{r, eval = FALSE}
dance_remove()
```
By default, this just records the R calls typed into the R console, populating the `expr` column of the data frame. You can optionally also record the following by setting the parameter of the name to `TRUE`. Some of these rely on using RStudio as your IDE.
* `value`: The values that are computed
* `path`: The path to the file in focus on the RStudio editor
* `contents`: The file contents of the RStudio editor tab in focus
* `selection`: The text that is highlighted in the RStudio editor tab in focus
For example, the same code with `value = TRUE` results in the following tidy data frame.
```{r, eval = FALSE}
# Start logging your R commands run in the console
dance_start(value = TRUE)
4 + 4
"wow!"
mean(1:10)
# Pause logging
dance_stop()
# Look at your log as a tidy data frame
dance_tbl()
```
```r
#> # A tibble: 6 x 6
#> expr value path contents selection dt
#>
#> 1 2018-06-23 15:26:06
#> 2 2018-06-23 15:26:06
#> 3 2018-06-23 15:26:07
#> 4 2018-06-23 15:26:08
#> 5 2018-06-23 15:26:08
#> 6 2018-06-23 15:26:09
```
Notice now the `value` column is now populated.
## Input a character string of R code
Alternatively you can input a string of R code and output a tidy data frame, using the `dance_recital()` function.
```{r}
dance_recital("
4 + 4
'wow!'
mean(1:10)
")
```
This creates the same `expr` and `value` columns as the `dance_start()` `dance_stop()` workflow described above. In addition, it outputs any `error`s, `output`, `warnings`, or `messages` generated by the R code in the character string. Notice this data frame does not have the session information, since it is not called interactively from the R console. By default, `dance_recital()` will evaluate all R code passed to it to retrieve the `value` column. If you would like to just output the `expr` column, you can set `evaluate = FALSE`. This may be especially useful if you are analyzing lots of code and it would take a long time to run all commands.
## Input a .R file
The same `dance_recital()` function can be used to analyze a .R file. Instead of including the code as a character string, pass the _path_ of the .R file. An example file is included in this package.
```{r}
(file <- system.file("test", "sample_code.R", package = "matahari"))
```
```{r}
dance_recital(file)
```