Add vignette on reading and writing items

vignettes/articles/read-write.Rmd

@@ -0,0 +1,160 @@
+---
+title: "Reading and writing items from SharePoint"
+---
+
+
+
+Note: this vignette is pre-computed to utilize the Microsoft Graph login that is only available locally to me as a logged in SharePoint user.
+
+
+``` r
+library(sharepointr)
+```
+
+## Downloading and reading files from SharePoint
+
+You can use `download_sp_item()` to download files or folders from SharePoint:
+
+
+``` r
+docx_url <- "https://bmore.sharepoint.com/:w:/r/sites/MayorsOffice-DataGovernance/Policy%20Documents/Data%20Classification%20Standard.docx?d=w54a9ae7eaa894e94b6d6d14516f3aaa4&csf=1&web=1&e=ee7ZSX"
+
+download_sp_item(
+  path = docx_url,
+  new_path = tempdir()
+)
+#> Loading Microsoft Graph login for default tenant
+#> ℹ Downloading SharePoint item to
+#> '/var/folders/3f/50m42dx1333_dfqb5772j6_4…
+#> Error: Path exists and overwrite is FALSE
+#> ✖ Downloading SharePoint item to '/var/folders/3f/50m42dx1333_dfqb5772j6_4…
+```
+
+For files on SharePoint, `read_sharepoint()` extends `download_sp_item()` by downloading the selected item to a temporary folder by default and, depending on the file extension, tries to read the file using `{readr}`, `{readxl}`, `{officer}`, or `{sf}`.
+
+
+``` r
+docx <- read_sharepoint(docx_url)
+#> Loading Microsoft Graph login for default tenant
+#> ℹ Downloading SharePoint item to '/var/folders/3f/50m42dx1333_dfqb5772j6_4…✔ Downloading SharePoint item to '/var/folders/3f/50m42dx1333_dfqb5772j6_4…
+#> ℹ Reading item with `officer::read_docx()`✔ Reading item with `officer::read_docx()` [37ms]
+```
+
+``` r
+
+docx
+#> rdocx document with 62 element(s)
+#> 
+#> * styles:
+#>                 Normal              heading 1              heading 2 
+#>            "paragraph"            "paragraph"            "paragraph" 
+#> Default Paragraph Font           Normal Table                No List 
+#>            "character"                "table"            "numbering" 
+#>         Heading 1 Char             Table Grid         List Paragraph 
+#>            "character"                "table"            "paragraph" 
+#>         Heading 2 Char                  Title             Title Char 
+#>            "character"            "paragraph"            "character" 
+#>           Normal (Web)                 header            Header Char 
+#>            "paragraph"            "paragraph"            "character" 
+#>                 footer            Footer Char          markedcontent 
+#>            "paragraph"            "character"            "character" 
+#>            TOC Heading                  toc 1                  toc 2 
+#>            "paragraph"            "paragraph"            "paragraph" 
+#>              Hyperlink                  toc 3                  toc 4 
+#>            "character"            "paragraph"            "paragraph" 
+#>                  toc 5                  toc 6                  toc 7 
+#>            "paragraph"            "paragraph"            "paragraph" 
+#>                  toc 8                  toc 9     Unresolved Mention 
+#>            "paragraph"            "paragraph"            "character" 
+#>      FollowedHyperlink               Revision    Unresolved Mention1 
+#>            "character"            "paragraph"            "character" 
+#>   annotation reference        annotation text      Comment Text Char 
+#>            "character"            "paragraph"            "character" 
+#>     annotation subject   Comment Subject Char           Balloon Text 
+#>            "paragraph"            "character"            "paragraph" 
+#>      Balloon Text Char          footnote text     Footnote Text Char 
+#>            "character"            "paragraph"            "character" 
+#>     footnote reference 
+#>            "character" 
+#> 
+#> * Content at cursor location:
+#>   level num_id text style_name content_type
+#> 1    NA     NA       heading 1    paragraph
+```
+
+## Writing and uploading files to SharePoint
+
+You can use `upload_sp_item()` to upload a local file to a SharePoint folder or document library.
+
+
+``` r
+folder_url <- "https://bmore.sharepoint.com/:f:/r/sites/MayorsOffice-DataGovernance/Shared%20Documents/RStats?csf=1&web=1&e=S1XxVU"
+
+upload_sp_item(
+  file = system.file("gpkg/nc.gpkg", package = "sf"),
+  dest = folder_url
+)
+#> Loading Microsoft Graph login for default tenant
+#> ℹ Uploading file 'nc.gpkg' to SharePoint drive✔ File upload complete [1.1s]                 
+```
+
+Using `read_sharepoint()`, we can confirm that the file has been uploaded:
+
+
+``` r
+sp_drive <- get_sp_drive(folder_url)
+#> Loading Microsoft Graph login for default tenant
+```
+
+``` r
+
+nc <- read_sharepoint(
+  "RStats/nc.gpkg",
+  drive = sp_drive
+)
+#> ℹ Downloading SharePoint item to
+#> '/var/folders/3f/50m42dx1333_dfqb5772j6_4…
+#> ✔ Downloading SharePoint item to '/var/folders/3f/50m42dx1333_dfqb5772j6_4…
+#> ℹ Reading item with `sf::read_sf()`✔ Reading item with `sf::read_sf()` [29ms]
+```
+
+``` r
+
+plot(nc["AREA"])
+```
+
+![plot of chunk unnamed-chunk-20](figure/unnamed-chunk-20-1.png)
+
+`write_sharepoint()` extends `upload_sp_item()` by allowing you to pass an R object instead of a file path. Like `read_sharepoint()` tries to guess the appropriate input function, `write_sharepoint()` tries to guess the appropriate output function based on the object class.
+
+
+``` r
+write_sharepoint(
+  mtcars,
+  file = "mtcars.csv",
+  dest = folder_url
+)
+#> Loading Microsoft Graph login for default tenant
+#> ℹ Uploading file 'mtcars.csv' to SharePoint drive✔ File upload complete [1.1s]                    
+```
+
+To wrap up this example, we need to remove the uploaded files from SharePoint to keep a tidy shared file system.
+
+`delete_sp_item()` supports the option to use a shared item URL to select which file to remove but, in this case, it is easier to set the `drive` argument along with a relative filepath:
+
+
+``` r
+# Remove the file
+delete_sp_item(
+  file.path("RStats", "nc.gpkg"),
+  drive = sp_drive,
+  confirm = FALSE
+)
+
+delete_sp_item(
+  file.path("RStats", "mtcars.csv"),
+  drive = sp_drive,
+  confirm = FALSE
+)
+```
+

vignettes/articles/read-write.Rmd.orig

@@ -0,0 +1,93 @@
+---
+title: "Reading and writing items from SharePoint"
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+Note: this vignette is pre-computed to utilize the Microsoft Graph login that is only available locally to me as a logged in SharePoint user.
+
+```{r setup}
+library(sharepointr)
+```
+
+## Downloading and reading files from SharePoint
+
+You can use `download_sp_item()` to download files or folders from SharePoint:
+
+```{r}
+docx_url <- "https://bmore.sharepoint.com/:w:/r/sites/MayorsOffice-DataGovernance/Policy%20Documents/Data%20Classification%20Standard.docx?d=w54a9ae7eaa894e94b6d6d14516f3aaa4&csf=1&web=1&e=ee7ZSX"
+
+download_sp_item(
+  path = docx_url,
+  new_path = tempdir()
+)
+```
+
+For files on SharePoint, `read_sharepoint()` extends `download_sp_item()` by downloading the selected item to a temporary folder by default and, depending on the file extension, tries to read the file using `{readr}`, `{readxl}`, `{officer}`, or `{sf}`.
+
+```{r}
+docx <- read_sharepoint(docx_url)
+
+docx
+```
+
+## Writing and uploading files to SharePoint
+
+You can use `upload_sp_item()` to upload a local file to a SharePoint folder or document library.
+
+```{r}
+folder_url <- "https://bmore.sharepoint.com/:f:/r/sites/MayorsOffice-DataGovernance/Shared%20Documents/RStats?csf=1&web=1&e=S1XxVU"
+
+upload_sp_item(
+  file = system.file("gpkg/nc.gpkg", package = "sf"),
+  dest = folder_url
+)
+```
+
+Using `read_sharepoint()`, we can confirm that the file has been uploaded:
+
+```{r}
+sp_drive <- get_sp_drive(folder_url)
+
+nc <- read_sharepoint(
+  "RStats/nc.gpkg",
+  drive = sp_drive
+)
+
+plot(nc["AREA"])
+```
+
+`write_sharepoint()` extends `upload_sp_item()` by allowing you to pass an R object instead of a file path. Like `read_sharepoint()` tries to guess the appropriate input function, `write_sharepoint()` tries to guess the appropriate output function based on the object class.
+
+```{r}
+write_sharepoint(
+  mtcars,
+  file = "mtcars.csv",
+  dest = folder_url
+)
+```
+
+To wrap up this example, we need to remove the uploaded files from SharePoint to keep a tidy shared file system.
+
+`delete_sp_item()` supports the option to use a shared item URL to select which file to remove but, in this case, it is easier to set the `drive` argument along with a relative filepath:
+
+```{r}
+# Remove the file
+delete_sp_item(
+  file.path("RStats", "nc.gpkg"),
+  drive = sp_drive,
+  confirm = FALSE
+)
+
+delete_sp_item(
+  file.path("RStats", "mtcars.csv"),
+  drive = sp_drive,
+  confirm = FALSE
+)
+```
+