---
title: "Generating a Log"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Generating a Log}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  markdown: 
    wrap: 72
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(logrx)
```

`logrx` has been built with both the flexibility of code execution and a number of different use cases in mind.  While the basic case has been outlined in our [Get Started](https://pharmaverse.github.io/logrx/articles/logrx.html) vignette, here we will be discussing different methods of execution and creation of log files.  These examples are meant to guide users who wish to explore different methods of execution or for those using ```logrx``` to create scripting.

# Methods of Execution
Below you will find a number of examples for different methods of execution, these go in an increasing level of complexity and increasing level of technical knowledge.  The below examples are meant to be starting points for those interested in using ```logrx``` in more complex settings.

## `axecute()`
The easiest of the execution methods to use is `axecute()`.  This function can be used to execute code from an R terminal or using command line scripts. A log is 
set-up around the program, and its code is run safely and loudly (using `safely()` from `{purrr}`).
```{r axecute, eval = FALSE}
axecute("my_script.R")
```

## `log_*()` functions
The `log_*()` family of functions are the core of ```logrx``` and are used internally to configure, write, and remove the log and other objects.  While these are exported functions of the package, they are intended to be used in special cases where `axecute()` will not work.

Use the `log_*()` functions to do the following:

* `log_init()` to create the environment `log.rx`

* `log_config()` to add the core elements of the log to the environment, and basic elements that are available at the time of configuration

* `run_safely_loudly()` to execute the program code, and capture errors, warnings,
messages, output, and result.  This must be passed an executable R file to run and create the log elements from

* `log_write()` to generate and format the log

* `log_remove()` to remove the `log.rx` environment created by code execution

```{r log_*, eval = FALSE}
log_config("my_script.R")
run_safely_loudly("my_script.R")
log_write()
log_remove()
```

## Command Line Execution
While executing from an R terminal is nice if you have access to one, you can also execute your code using system command line.  This is done using the `Rscript -e` command which executes a file using the registered Rscript executable.  Below are a few examples of how to use the command line to execute a file and create a log as well as how to manipulate the outputs of the execution.  These are likely to be advanced examples for most users.

The below chunk will run the file my_script.R and output any standard output that is created by the execution of the file to the default location.
```{r, engine = 'bash', eval = FALSE}
Rscript -e "logrx::axecute('my_script.R', log_name = 'my_script.log', log_path = '.')"
```

The below chunk will run the file `my_script.R` and output any standard output that is created by the execution of the file to a file called `temp.log`.  This output can then later be accessed should the user want to check the output of the file execution.
```{r, engine = 'bash', eval = FALSE}
Rscript -e "logrx::axecute('my_script.R', log_name = 'my_script.log', log_path = '.')" > temp.log 2>&1
```

The below chunk will run the file `my_script.R` and output any standard output that is created by the execution of the file to a file called `temp.log`.  It will then take the contents of the `temp.log` file and add those to the end of the log file generated by the file execution and remove the temporary output log.
```{r, engine = 'bash', eval = FALSE}
Rscript -e "logrx::axecute('my_script.R', log_name = 'my_script.log', log_path = '.')" > temp.log 2>&1; cat my_script.log >> my_script.log; rm my_script.log
```


# Scripting with ```logrx```
While ```logrx``` is built around creating a log for a program it can just as easily be used when running an entire set of programs.  The `axecute()` function has been built with both single file execution and scripted file execution in mind.  With the use of simple functions such as `lapply()` scripting is easy.  Below is some sample code of how `lapply()` can be used with `axecute()`.

```{r scripting, eval = FALSE}
lapply(c("file.R", "otherfile.R"), axecute)
```

If your scripting needs to work on the contents of a directory instead of a pre-defined list, functions such as `list.files` can be used to obtain a list of files to use.  Below is an example of how this can be applied in practice by getting all files ending in `.R` in the current working directory using a regular expression, and then using `lapply()` to run the files using `axecute()`.

```{r scripting-dir, eval = FALSE}
r_script_list <- list.files(path = ".", pattern = "\\.R$")
lapply(r_script_list, axecute)
```

Additionally, if you need your code to run using a shell scripting language such as bash these files can be created to run using the previously outlined Command Line Execution examples. The above scripting examples can be translated into a variety of different scripting languages.  Below is an example where the bash script is executed in a directory of R files, this should execute all R files in the directory using `axecute()` and create a corresponding set of log files.

```{r, engine = 'bash', eval = FALSE}
for file in *.R; do
    [ -f "$file" ] || continue
    Rscript -e "logrx::axecute('$file')"
done
```