---
title: "How to use this package"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{How to use this package}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
---

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

## Provide some example R scripts locally

In order to test the functions of this package some R scripts are downloaded
from GitHub and provided locally:

```{r}
# Define URLs to some example scripts
urls <- kwb.utils::resolve(list(
  kwb = "https://raw.githubusercontent.com/KWB-R",
  utils = "<kwb>/kwb.utils/master/R",
  log = "<utils>/log.R",
  main = "<utils>/main.R",
  fakin = "<kwb>/kwb.fakin/master/R/plot_file_distribution.R"
))

# Create a temporary folder
root <- kwb.utils::createDirectory(
  kwb.utils::tempSubdirectory("test"), 
  dbg = FALSE
)

# Helper function to download a text file to the temporary folder
download_script <- function(url) {
  download.file(
    url, 
    destfile = file.path(root, basename(url)), 
    mode = "wt"
  )
}

# Download three scripts to the temporary folder
download_script(urls$fakin)
download_script(urls$log)
download_script(urls$main)
```
## Exported functions

### analyse()

The parse tree is analysed. Each node of the tree is given the following
attributes:

- type
- mode
- class
- length
- text
- is
- n_modes
- n_classes
- path
- fulltype
- children

The idea probably was to use these information to extract objects of special
interest from the parse tree (see below: get_elements_by_type())

```{r}
x <- parse(urls$log)

result <- kwb.code::analyse(x)
```

## arg_names()

This function returns the names of the arguments of a function:

```{r}
kwb.code::arg_names(kwb.utils::selectColumns)
```
## find_string_constants()

This function requires a directory of R scripts. All scripts are parsed. 
String constants that are used in the script are returned.

```{r result = "asis"}
string_constants <- kwb.code::find_string_constants(root)

knitr::kable(string_constants)
```

## find_weaknesses_in_scripts()

Check for expressions in scripts that can be improved.

```{r result = "asis"}
x <- parse(text = c(
  "texts <- c(", 
  "  paste('this is a very long', 'text'),",
  "  paste('this is a very long', 'string')",
  ")",
  "",
  "indices <- 1:length(texts)"
))

weaknesses <- kwb.code::find_weaknesses_in_scripts(
  x = list(test = x), 
  min_duplicate_frequency = 2L
)

knitr::kable(weaknesses)
```

## get_elements_by_type

This function groups similar elements that are found in a parse tree.

```{r}
# Parse an R script file (here, a file from kwb.utils)
x <- parse(urls$log)

# For each "type" of code segment, extract all occurrences
elements <- kwb.code::get_elements_by_type(x, result = result)

# Show all code blocks in curly braces
elements[["language|call|{|2|"]]
```

## get_full_function_info()

This function analyses a list of parse trees each of which has been read from an
R script.

It provides information on the functions that are defined in the scripts:

- script: script name
- functionName: function name 
- n.def: always 1 (?)
- bodyClass: always "{" (?)
- n.args: number of arguments
- n.defaults: number of arguments with a default
- n.expr: number of expressions

```{r results = "asis"}
trees <- kwb.code::parse_scripts(root, dbg = FALSE)
function_info <- kwb.code::get_full_function_info(trees)
knitr::kable(function_info)
```

## get_names_of_used_packages()

What packages are used in the scripts? 

```{r}
kwb.code::get_names_of_used_packages(root)
```
This function simply looks for calls to `library()`. It does not take into 
account functions that are called with `::` as the following simple `grep()`
reveals:

```{r}
pattern <- "[^A-Za-z_.]([A-Za-z_.]+::[A-Za-z_.]+)[^A-Za-z_.]"

text <- grep(pattern, readLines(urls$fakin), value = TRUE)

unique(kwb.utils::extractSubstring(pattern, text, index = 1))
```
TODO: Use another function instead...

## get_package_function_usage()

```{r results = "asis"}
tree <- kwb.code::parse_scripts(root, dbg = FALSE)
function_usage <- kwb.code::get_package_function_usage(
  tree, 
  package = "kwb.utils"
)

knitr::kable(function_usage)
```

## get_package_usage_per_script()

```{r}
package_usage <- kwb.code::get_package_usage_per_script(
  root, 
  packages = "kwb.utils"
)
```

```{r results = "asis"}
knitr::kable(package_usage)
```

## get_string_constants_in_scripts()

```{r}
string_constants <- kwb.code::get_string_constants_in_scripts(root)
```

```{r results = "asis"}
knitr::kable(string_constants)
```

## parse_scripts()

```{r}
x <- kwb.code::parse_scripts(root)

str(x, 2)
```

## to_full_script_info()

This function creates statistics about R scripts.

```{r results = "asis"}
script_statistics <- kwb.code::to_full_script_info(trees)

knitr::kable(script_statistics)
```

## walk_tree()

This function walks along a parse tree.

```{r}
x <- parse(urls$log)

result <- kwb.code::walk_tree(x, dbg = FALSE)
```