-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
136 lines (95 loc) · 4.64 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
131
132
133
134
135
136
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
library(cloudstoR)
```
# cloudstoR
<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version/cloudstoR)](https://CRAN.R-project.org/package=cloudstoR)
[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)
[![R-CMD-check](https://github.com/pdparker/cloudstoR/workflows/R-CMD-check/badge.svg)](https://github.com/pdparker/cloudstoR/actions)
[![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/last-month/cloudstoR?color=blue)](https://r-pkg.org/pkg/cloudstoR)
<!-- badges: end -->
The goal of `cloudstoR` is to simplify accessing data stored on [Cloudstor](https://cloudstor.aarnet.edu.au/) via their WebDAV interface. You can use `cloudstoR` to download or upload files, or check the contents of directories.
## Installation
You can install from [CRAN](https://cran.r-project.org/package=cloudstoR) with:
```{r, eval=FALSE}
install.packages("cloudstoR")
```
Or install the development version from [GitHub](https://github.com/pdparker/cloudstoR) with:
```{r, eval=FALSE}
# install.packages("devtools")
devtools::install_github("pdparker/cloudstoR")
```
For additional support for the package, check the [pkgdown site](https://pdparker.github.io/cloudstoR/).
## Setup
You will need your Cloudstor username and password. The password is **not** the one you use to log on to Cloudstor. Instead you need to use an [app password](https://support.aarnet.edu.au/hc/en-us/articles/236034707-How-do-I-manage-change-my-passwords-). `cloudstoR` provides an option to store these credentials using [`keyring`](https://github.com/r-lib/keyring).
## Examples
### Setting credentials
The first time you use a `cloud_*` function, `cloudstoR` will prompt you to store your credentials locally. You can choose not to do this by providing a username and password for each function call.
```{r, eval=FALSE}
library(cloudstoR)
my_data <- cloud_get(
path = "cloudstoR Tests/mydata1.csv",
user = cloudstor_username,
password = cloudstor_appPassword
)
```
### Getting a list of files
To retrieve a list of files in a folder, use `cloud_list()`. The `path` argument specifies the folder to return.
```{r}
cloud_list(path = "cloudstoR Tests")
```
### Getting a specific file
To retrieve a file use `cloud_get()`, and provide the path to the file with the `path` argument.
```{r}
my_data <- cloud_get(path = "cloudstoR Tests/mydata1.csv")
my_data
```
By default, `cloudstoR` will try to open the file using [`rio`](https://github.com/leeper/rio) and return a data.frame. The temporary version of the file is deleted once it is read into memory. If you want to use a different package to open the file, or you just want to download and keep the file without opening it, set `open_file = FALSE` to return a file path instead.
```{r}
my_path <- cloud_get(
path = "cloudstoR Tests/mydata1.csv",
dest = "~/mydata1.csv",
open_file = FALSE
)
file.exists(my_path)
```
### Saving a file to Cloudstor
To upload a file, use `cloud_put()`. You need to provide the path to the saved file (`local_file`), and the path to save the file on Cloudstor (`path`). You can optionally provide a name for the file (`file_name`), otherwise the file name of the local file is used.
```{r, eval=FALSE}
cloud_put(
local_file = "~/datatosave.sav",
path = "additional/path/to/folder",
file_name = "mydata.sav",
)
```
### Navigating the folder tree
If you don't know the exact file path you want to follow, you can find it with `cloud_browse()`.
![Example of `cloud_browse`](man/figures/cloud_browse_demo.gif)
### View file or folder meta-data
You can view meta-data for a file or folder with `cloud_meta()`. This can be especially useful for checking if a file has been modified.
```{r}
cloud_meta(path = "cloudstoR Tests/mydata1.csv")
```
### Updating credentials
If you need to delete your credentials (e.g., because you revoke your app password), you can restore them by calling `cloud_auth()` directly:
```{r, eval=FALSE}
cloud_auth(reset_keys = TRUE)
```
### Using an alternative WebDAV address
The default WebDAV address is `https://cloudstor.aarnet.edu.au/plus/remote.php/webdav/`. If your organisation uses a different address, you can set this globally at the top of your script:
```{r, eval=FALSE}
# Set the global WebDAV address
options(cloudstoR.cloud_address = "https:://my.webdav.address")
# Check the current value
getOption("cloudstoR.cloud_address")
```