README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# m365filer

<!-- badges: start -->
[<img src="https://img.shields.io/badge/License-MIT-blue.svg">](https://github.com/atorus-research/Tplyr/blob/master/LICENSE)
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental-1)
<!-- badges: end -->

Welcome! If you haven't seen Microsoft's [Microsoft365R](https://github.com/Azure/Microsoft365R) package, I suggest you check it out! It provides a sleek, high level interface into Microsoft's Graph API leveraging the facilities provided by the [AzureGraph](https://cran.r-project.org/package=AzureGraph) package.


The aim of m365filer is much more simple in scope. While Microsoft365R has broad range of capabilities, m365filer focuses only on file handling and interfacing with Microsoft drives such as OneDrive and SharePoint. The specific goal of m365filer is to make the experience of reading and writing files to OneDrive feel more natural and intuitive to your typical R Programmer. 

## Installation

You can install the released version of m365filer via GitHub with:

``` r
# install.packages("devtools")
devtools::install_github("atorus-research/m365filer")
```

## Setup

A prerequisite of using m365filer is setting up your connection to OneDrive or SharePoint. Note that if you're trying to use corporate systems, there will likely be some coordination necessary with your Microsoft 365 Administrators. Refer to the Microsof365R [Authenticatiing to Microsoft 365](https://github.com/Azure/Microsoft365R/blob/master/vignettes/auth.Rmd) vignette and the [app registration](https://github.com/Azure/Microsoft365R/blob/master/inst/app_registration.md) documentation for instructions on getting started. Note that the user experience within m365filer will overall be the same if you're using a personal OneDrive account, which allows more user level control. 

```{r OneDrive Setup}
library(m365filer)

# Get ms_drive object
od <- Microsoft365R::get_personal_onedrive()
od
```
Once the drive object is available, m365filer will take it the rest of the way:

```{r example}
library(dplyr)
mtcars %>% 
  write.csv(onedrive_file('Documents/example.csv', drive=od))

read.csv(onedrive_file('Documents/example.csv', drive=od)) %>% 
  head()
```

## An Important Note

This package is experimental! As such, I'm not heavily committed to function APIs and this package is generally subject to change. 

## Want to help?

If you want to get your hands dirty, I'd love your input! If you have suggestions, corrections, ideas, or requests - drop an issue [here](https://github.com/atorus-research/m365filer/issues) on GitHub. 

An area in particular that I could truly use assistance is with a unit testing framework. The interface with Microsoft 365 systems makes this a bit complex.