---
title: "Analysing R Scripts"
author: "Hauke Sonnenberg"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Analysing R Scripts}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

It is quite impressive how, since more or less ten years, more and more people 
at our research institute 
[Kompetenzzentrum Wasser Berlin](http://komptenz-wasser.de) began to use
the programming language R to support their daily data-related work.
As a result, we are currently hosting more than one thousand R scripts in 
our internal version control system.

It is difficult to keep control over so many files. 
Therefore, this package contains a function that aims at giving an overview
of R script files and the functions defined within these files.
Use the function `report_about_r_scripts()` to create an R Markdown document 
about all the R script files below a certain root directory:

```{r report-example, eval = FALSE}
kwb.fakin::report_about_r_scripts(root = "path/to/your/script/folder")
```

With the (private) helper functions `github_package_path()` and
`github_package_files()` that are also contained in the package, we can also 
report on the R files that are contained in an R package hosted on 
[GitHub](https://github.com).
For example, we can have a look at the files that are contained in this package.
They are available in the repository 
[kwb.fakin](https://github.com/kwb-r/kwb.fakin) on our 
[GitHub account](https://github.com/kwb-r):

```{r report-scripts, eval = FALSE}
repo <- "kwb-r/kwb.fakin"

kwb.fakin::report_about_r_scripts(
  root = kwb.fakin:::github_package_path(repo, "R"),
  scripts = kwb.fakin:::github_package_files(repo, "R"),
  show = FALSE
)
```

We set `show` to `FALSE` in order to prevent that the created HTML file is
opened in a browser. 

A shortcut to the above call is:

```{r report-github-fakin, eval = FALSE}
kwb.fakin::report_about_github_package("kwb-r/kwb.fakin", show = FALSE)
```

It is up to you to compare with what the great guys do. Try e.g.

```{r report-github-dplyr, eval = FALSE}
kwb.fakin::report_about_github_package("tidyverse/dplyr")
```

## What packages are used by our scripts?

To find out what R-packages are used in our R-scripts, you may use the 
function `get_names_of_used_packages` of our `kwb.code` package:

```{r eval = FALSE}
#devtools::install_github("kwb-r/kwb.code")

# Define the top level directory in which to look recursively for R-scripts
root_dir = "~/Desktop/R-Development/RScripts"

# Get the names of the packages that are loaded in the scripts with "library()"
packages <- kwb.code::get_names_of_used_packages(root_dir)

# Print the script names
writeLines(packages)
```

## Get file properties recursively

The base function `file.info` can be used to get detailed information about
a file. The package `kwb.fakin` contains a function that calls this function
on all files that are below a certain root folder:

```{r eval = FALSE}
# Define the root directory
root_dir <- system.file(package = "kwb.fakin")

# Get information on all files in this directory
file_info <- fakin.path.app::get_recursive_file_info(root_dir)

# Get information on R scripts only...
file_info_scripts <- fakin.path.app::get_recursive_file_info(root_dir, "[.]R$")

print(utils::sessionInfo())

# Show the structure of the result
str(structure(file_info_scripts, class = "data.frame"))
```