-
Notifications
You must be signed in to change notification settings - Fork 24
/
README.Rmd
133 lines (87 loc) · 5.68 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
---
output: github_document
params:
url_root: "https://r-box.github.io/boxr/"
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r setup, echo=FALSE, message=FALSE}
library("conflicted")
library("glue")
url <- function(x = "") {
glue::glue("{params$url_root}{x}")
}
```
# boxr <img src="man/figures/logo.png" align="right" alt="" width="120" />
<!-- badges: start -->
[](https://CRAN.R-project.org/package=boxr)
[](https://codecov.io/gh/r-box/boxr)
[](https://github.com/r-box/boxr/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->
A lightweight, *opinionated*, high-level R interface to the box.com API, standing on the shoulders of **[httr](https://github.com/r-lib/httr)**.
[Box](https://www.box.com) is a cloud content-management and file-sharing service. The goal of the **boxr** package is to make it easier for you to integrate your Box account into your R workflow.
## New in boxr 0.3.6 (development)
### Bug fixes
- Harmonizes the default location for tokens; `~` resolves to the home directory for all platforms.
A patch is applied offering to move tokens from "old" locations.
This bug appeared on Windows only.
All changes are detailed in the [NEWS](`r url("news/")`).
## Installation
You can install boxr from [CRAN](https://CRAN.R-project.org/package=boxr), with:
```R
install.packages("boxr")
```
If you'd like to install the development version from GitHub, use:
```R
# install.packages("devtools")
devtools::install_github("r-box/boxr")
```
### Documentation
The package-documentation website is created and maintained using [pkgdown](https://pkgdown.r-lib.org). The documentation website consists of:
- a [CRAN-version site](`r url()`).
- a [development-version site](`r url("dev/")`).
## Usage
We have a [Get-started article](`r url("articles/boxr.html")`) that goes into more detail on interacting with your Box account using R.
### Authentication
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, without arguments:
```r
box_auth()
```
If you don't have access to `client_id` and `client_secret`, you should read the [authentication article](`r url("articles/boxr-apps.html")`) to determine your next steps. In most cases, this next step will be to create an [interactive Box-app](`r url("articles/boxr-app-interactive.html")`)
### Basic operations
- [Accessing Box files](`r url("articles/boxr.html#files")`): `box_ul()`, `box_dl()`, `box_version_history()`.
- [Accessing Box directories](`r url("articles/boxr.html#directories")`): `box_setwd()`, `box_getwd()`, `box_dir_create()`, `box_ls()`, `box_search()`.
- [Directory-wide operations](`r url("articles/boxr.html#directory-wide-operations")`): `box_push()`, `box_fetch()`.
### Advanced operations
- [Interactng with Box files](`r url("articles/boxr.html#box-file-interaction")`): `box_collab_create()`, `box_comment_create()`, `box_add_description()`.
- [Using Box trash](`r url("articles/boxr.html#using-box-trash")`): `box_delete_file()`, `box_delete_folder()`, `box_restore_file()`, `box_restore_folder()`.
- [Interacting with your R session](`r url("articles/boxr.html#interacting-with-your-r-session")`): `box_read()`, `box_write()`, `box_read_rds()`, `box_save_rds()`, `box_save()`, `box_load()`, `box_browse()`.
## Alternatives
Other ways to interact with a Box account include:
- The [Box desktop apps](https://www.box.com/resources/downloads).
- The *other* boxr, [written in Ruby](https://github.com/cburnette/boxr). Its motivations are rather different, and it covers 100% of the box.com API (e.g account administration, etc.).
- Box themselves provide a [wide range of SDKs](https://github.com/box), including [one for Python](https://github.com/box/box-python-sdk).
## Contributing
Always very welcome! If you'd like to submit a pull request for a new feature, ideally it would be documented, come with an addition to [NEWS.md](`r url("news/")`), and have a test or two. This project has a standard [Code of Conduct](`r url("CONDUCT.html")`).
## License
The MIT License (MIT)
Copyright (c) 2015-`r format(Sys.time(), "%Y")` boxr contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.