---
title: "Operating Outside of R"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Operating Outside of R}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r pre-setup}
#| echo: false
#| message: false

# devtools::install_github("njlyon0/supportR", force = TRUE)
```

Finally, I've written several functions that allow you to interact with APIs (Application Programming Interfaces) outside of R via R functions with hopefully more comfortable syntax. Because these functions rely on user credentials, they cannot be run non-interactively (as in the submission of version updates for `supportR` to CRAN) so the following code chunks are not evaluated but are included as examples of the proper syntax for your reference.

### GitHub-Related Functions

For GitHub users, I've developed two related functions: `github_ls` and `github_tree`. `github_ls` accepts the URL to a GitHub repository to which you have access (public or private). It creates a dataframe of that repository's contents including their names, types, and full paths within the repository. Listing of a particular folder and recursive listing of all nested subfolders within a repository are both supported via additional arguments.

If the `folder` argument is set to `NULL` (the default) the top level of the repository is listed.

```{r github_ls-1}
#| eval: false
# List all files in a GitHub repository
supportR::github_ls(repo = "https://github.com/njlyon0/supportR",
                    recursive = TRUE, quiet = FALSE)

##                          name type                path
## 1               .Rbuildignore file                   .
## 2                     .github  dir                   .
## 3                  .gitignore file                   .
## 4                 DESCRIPTION file                   .
## 5                     LICENSE file                   .
```

```{r github_ls-2}
#| eval: false
# Or list files in only a particular folder
supportR::github_ls(repo = "https://github.com/njlyon0/supportR", folder = "R",
                    recursive = FALSE, quiet = TRUE)

##                   name type path
## 1         array_melt.R file    R
## 2              count.R file    R
## 3           crop_tri.R file    R
## 4         date_check.R file    R
```

`github_tree` is an extension of `github_ls` that identifies all files in a repository and creates a file tree diagram of that folder structure that is simple and human-readable. Unlike `github_ls`, `github_tree` only supports recursive identification of all files beginning at the top level of the repository. It does however allow users to exclude the listings of particular folders by specifying their names in the `exclude` argument.

I think this could be particularly useful to embed in a repository's `README.Rmd` to create a quick-and-easy file map for visitors to use as a guide in navigating the repository's contents.

```{r github_tree}
#| eval: false
# Create a file tree diagram of a GitHub repository
supportR::github_tree(repo = "https://github.com/njlyon0/supportR",
                      exclude = c("docs", "man", ".github"), quiet = FALSE)

##                               levelName
## 1  .                                   
## 2   ¦--.Rbuildignore                   
## 3   ¦--.github                         
## 4   ¦   °--11 excluded items           
## 5   ¦--.gitignore                      
## 6   ¦--DESCRIPTION                     
## 7   ¦--LICENSE                         
```

### External File-Related Functions

Valuable information is sometimes stored as markdown files which--while consistently formatted internally--are not always easily parsed through R. I've written `tabularize_md` to ingest a markdown file and collapse it into a table while still preserving the nested structure of any headings that may be in the source file. This function accepts either a local markdown file name/path or a connection (via URL) to an online markdown file. I'll demonstrate the URL-based variant here but to use it on a local file you need only provide the file name/path as you would to any other reading function (e.g., `read.csv`, etc.)

```{r tabularize_md}
#| eval: false

# Identify URL to the NEWS.md file in `supportR` GitHub repo
md_cxn <- url("https://raw.githubusercontent.com/njlyon0/supportR/main/NEWS.md")

# Transform it into a table
md_df <- tabularize_md(file = md_cxn)

# Close connection (just good housekeeping to do so)
close(md_cxn)

# Check out the table format
str(md_df)

## 'data.frame':	25 obs. of  2 variables:
##  $ level_1: chr  "supportR Version 1.4.0.900" "supportR Version 1.4.0.900" "supportR Version 1.4.0" "supportR Version 1.4.0" ...
##  $ text   : chr  "Development version, changes from preceding version are listed below:" "- Function fix: Fixed issue with `replace_non_ascii` where if `include_letters` was set to `FALSE` a warning wa"| __truncated__ "Changes from preceding version are listed below" "- New function: `replace_non_ascii`. Replaces non-ASCII characters with ASCII characters that are as visually s"| __truncated__
```

### Google Drive-Related Functions

For users who create RMarkdown reports and want to store them in a Google Drive folder,  `rmd_export` knits and exports a given R Markdown file both locally and to a user-designated Google Drive folder. Note that you **_MUST_** authenticate your R session with the `googledrive` package so that it has permission to access the Drive folder you supply. I recommend running `googledrive::drive_auth()` and doing the authentication "dance" in a browser before using `rmd_export` to reduce the chances of any errors.

```{r rmd_export}
#| eval: false

# Authorize R to interact with GoogleDrive
googledrive::drive_auth()

# Use `rmd_export()` to knit and export an .Rmd file
supportR::rmd_export(rmd = "my_markdown.Rmd",
                     in_path = file.path("Folder in my WD with the .Rmd named in `rmd`"),
                     out_path = file.path("Folder in my WD to save the knit file to"),
                     out_name = "desired name for output",
                     out_type = "html",
                     drive_link = "<Full Google Drive link>")
```
