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

  Please see the matahari website for full documentation:
  
  * <https://jhudsl.github.io/matahari/>
  
```{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                 
#>   <list>     <list>            <list>    <list>    <list>    <dttm>             
#> 1 <language> <S3: sessionInfo> <lgl [1]> <lgl [1]> <lgl [1]> 2019-05-14 08:15:24
#> 2 <language> <lgl [1]>         <lgl [1]> <lgl [1]> <lgl [1]> 2019-05-14 08:15:24
#> 3 <language> <lgl [1]>         <lgl [1]> <lgl [1]> <lgl [1]> 2019-05-14 08:15:25
#> 4 <chr [1]>  <lgl [1]>         <lgl [1]> <lgl [1]> <lgl [1]> 2019-05-14 08:15:25
#> 5 <language> <lgl [1]>         <lgl [1]> <lgl [1]> <lgl [1]> 2019-05-14 08:15:25
#> 6 <language> <S3: sessionInfo> <lgl [1]> <lgl [1]> <lgl [1]> 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                 
#>   <list>     <list>            <list>    <list>    <list>    <dttm>             
#> 1 <language> <S3: sessionInfo> <lgl [1]> <lgl [1]> <lgl [1]> 2018-06-23 15:26:06
#> 2 <language> <int [1]>         <lgl [1]> <lgl [1]> <lgl [1]> 2018-06-23 15:26:06
#> 3 <language> <dbl [1]>         <lgl [1]> <lgl [1]> <lgl [1]> 2018-06-23 15:26:07
#> 4 <chr [1]>  <chr [1]>         <lgl [1]> <lgl [1]> <lgl [1]> 2018-06-23 15:26:08
#> 5 <language> <dbl [1]>         <lgl [1]> <lgl [1]> <lgl [1]> 2018-06-23 15:26:08
#> 6 <language> <S3: sessionInfo> <lgl [1]> <lgl [1]> <lgl [1]> 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)
```