---
title: "boxr: A high-level R interface for the box.com API"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
resource_files:
  figures
vignette: >
  %\VignetteIndexEntry{boxr}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

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

incl <- function(x){
  path <- paste0("figures/", x)
  knitr::include_graphics(path)
}
```

## Authentication

To use `boxr`, you will need to use a Box-app. You can think of a Box-app as the door through which the `boxr` functions will access Box.  

### tl;dr

If you have access to `client_id` and `client_secret` for a Box-app, you can use `box_auth()` to authenticate:

```r
box_auth(client_id = "your_client_id", client_secret = "your_client_secret")
```

This will kick off a process that, all being well, will keep you authenticated for the rest of the R session. By saving this information to your `.Renviron` file, at your next R session you can use:

```r
box_auth()
```

If you don't have access to  `client_id` and `client_secret` for a Box-app, read on.

### More information

There are two different types of apps, as described in this [overview article](./boxr-apps.html):

- **[Interactive-App](./boxr-app-interactive.html)**: For interactive use on your local computer, this should be the first choice for most situations.
- **[Service-App](./boxr-app-service.html)**: For unattended use, e.g. running scheduled reports.

## Basic operations

Functions that operate on Box files or folders have arguments: `file_id` or `dir_id`. You can use the [box.com](https://box.com) web interface to find these values. Although they look like numbers, it is perhaps simpler to think of them as character strings:


**Files**
```{r, out.width="100%", echo=FALSE}
incl("box-file-id.png")
```

**Folders**
```{r, out.width="100%", echo=FALSE}
incl("box-folder-id.png")
```

Here are a few of this package's functions: 

* `box_dl(file_id)` and `box_ul(file = 'path/to/file')` to download and upload files 
* `box_setwd()`/`box_getwd()` to get/set a default box folder
* `box_load()`/`box_save()` for remote R workspaces
* `box_read()` to read files straight into R (e.g. CSV or Excel files as `data.frame`)
* `box_source()` to read and execute remote code
* `box_write()` to write R objects to Box files
* `box_search()` to query files stored on Box
* `box_add_description()` add text descriptions to your Box files 

### Directory-wide operations

Cloud storage services can complement version control systems for code, which aren't well suited to large binary files (e.g. databases, .RData, or heaps of pdfs). box explicitly versions binary files, keeping old ones, and making it easy fall back to an older copy.

boxr provides *git style* facilities to upload, download, and synchronize the contents of entire local and remote directories. At the time of writing, the box.com API does not support this directly, and so boxr recursively loops through directory structures.

```{r, out.width="100%", echo=FALSE}
incl("boxr-console.png")
```

* `box_push()` will update the remote directory with new/changed local files
* `box_fetch()` will update the local directory with new/changed remote files

These functions all have `overwrite` and `delete` parameters, which are set to `FALSE` by default.

**Disclaimer:** box.com is no replacement for a VCS/remote-database, and familiar verbs are no guarantee of expected behavior! Do check the function documentation before jumping in.

### Piping

boxr's functions have been designed to be 'pipeable'. Here's a little example:

```r
library(boxr)
library(dplyr)
library(magrittr)

# 'nycflights13.json' is the same as nycflights13::flights, if you want to
# follow along at home

box_auth()

box_search("nycflights13.json") %>%                # Find a remote file
  box_read() %>%                                   # Download it as a data.frame
    group_by(origin, dest, month) %>%              #   Do some, er, cutting edge
    summarise(mu = mean(arr_delay), n = n()) %>%   #   analysis with dplyr!
  box_write("delay_summary.xlsx") %>%              # Convert to .xlsx, upload
  box_add_description("Check out these averages!") # Add a description to your file!

```

## Reporting Bugs

If you find anything that looks like a bug while using it, please report it using a GitHub issue:
<https://github.com/r-box/boxr/issues>.
