18870: Need to declare NODES as array

[arvados.git] / sdk / R / README.Rmd

diff --git a/sdk/R/README.Rmd b/sdk/R/README.Rmd
index cfa0ce5ae6d94b79f16b7fb7ebd6e6dc035f8cf4..8cc89d902051a9ac752bf354a7b476cb344b60fc 100644 (file)
--- a/sdk/R/README.Rmd
+++ b/sdk/R/README.Rmd
@@ -1,3 +1,7 @@
+[comment]: # (Copyright (c) The Arvados Authors. All rights reserved.)
+[comment]: # ()
+[comment]: # (SPDX-License-Identifier: CC-BY-SA-3.0)
+
 ## R SDK for Arvados
 
 This SDK focuses on providing support for accessing Arvados projects, collections, and the files within collections.
@@ -10,7 +14,7 @@ knitr::opts_chunk$set(eval=FALSE)
 ```
 
 ```{r}
-install.packages("ArvadosR", repos=c("http://r.arvados.org", getOption("repos")["CRAN"]), dependencies=TRUE)
+install.packages("ArvadosR", repos=c("https://r.arvados.org", getOption("repos")["CRAN"]), dependencies=TRUE)
 ```
 
 Note: on Linux, you may have to install supporting packages.
@@ -27,6 +31,8 @@ On Debian, this is:
 apt-get install build-essential libxml2-dev libssl-dev libcurl4-gnutls-dev
 ```
 
+Minimum R version required to run ArvadosR is 3.3.0.
+
 
 ### Usage
 
@@ -65,6 +71,12 @@ arv$setNumRetries(5)
 collection <- arv$collections.get("uuid")
 ```
 
+Be aware that the result from `collections.get` is _not_ a
+`Collection` class.  The object returned from this method lets you
+access collection fields like "name" and "description".  The
+`Collection` class lets you access the files in the collection for
+reading and writing, and is described in the next section.
+
 * List collections:
 
 ```{r}
@@ -72,9 +84,7 @@ collection <- arv$collections.get("uuid")
 collectionList <- arv$collections.list(list(list("name", "like", "Test%")))
 
 collectionList <- arv$collections.list(list(list("name", "like", "Test%")), limit = 10, offset = 2)
-```
 
-```{r}
 # count of total number of items (may be more than returned due to paging)
 collectionList$items_available
 
@@ -100,7 +110,7 @@ deletedCollection <- arv$collections.delete("uuid")
 updatedCollection <- arv$collections.update(list(name = "New name", description = "New description"), "uuid")
 ```
 
-* Create collection:
+* Create a new collection:
 
 ```{r}
 newCollection <- arv$collections.create(list(name = "Example", description = "This is a test collection"))
@@ -109,7 +119,7 @@ newCollection <- arv$collections.create(list(name = "Example", description = "Th
 
 #### Manipulating collection content
 
-* Create collection object:
+* Initialize a collection object:
 
 ```{r}
 collection <- Collection$new(arv, "uuid")
@@ -127,7 +137,7 @@ files <- collection$getFileListing()
 arvadosFile <- collection$get("location/to/my/file.cpp")
 ```
 
-    or
+or
 
 ```{r}
 arvadosSubcollection <- collection$get("location/to/my/directory/")
@@ -144,13 +154,13 @@ mytable       <- read.table(arvConnection)
 * Write a table:
 
 ```{r}
-arvadosFile   <- collection$create("myoutput.txt")
+arvadosFile   <- collection$create("myoutput.txt")[[1]]
 arvConnection <- arvadosFile$connection("w")
 write.table(mytable, arvConnection)
 arvadosFile$flush()
 ```
 
-* Write to existing file (override current content of the file):
+* Write to existing file (overwrites current content of the file):
 
 ```{r}
 arvadosFile <- collection$get("location/to/my/file.cpp")
@@ -171,40 +181,25 @@ fileContent <- arvadosFile$read("raw", offset = 1024, length = 512)
 size <- arvadosFile$getSizeInBytes()
 ```
 
-    or
+or
 
 ```{r}
 size <- arvadosSubcollection$getSizeInBytes()
 ```
 
-* Create new file in a collection:
+* Create new file in a collection (returns a vector of one or more ArvadosFile objects):
 
 ```{r}
-collection$create(fileNames, optionalRelativePath)
+collection$create(files)
 ```
 
-    Example:
+Example:
 
 ```{r}
-mainFile <- collection$create("main.cpp", "cpp/src/")
-fileList <- collection$create(c("main.cpp", lib.dll), "cpp/src/")
+mainFile <- collection$create("cpp/src/main.cpp")[[1]]
+fileList <- collection$create(c("cpp/src/main.cpp", "cpp/src/util.h"))
 ```
 
-* Add existing ArvadosFile or Subcollection to a collection:
-
-```{r}
-folder <- Subcollection$new("src")
-file   <- ArvadosFile$new("main.cpp")
-folder$add(file)
-```
-
-```{r}
-collection$add(folder, "cpp")
-```
-
-This examples will add file "main.cpp" in "./cpp/src/" folder if folder exists.
-If subcollection contains more files or folders they will be added recursively.
-
 * Delete file from a collection:
 
 ```{r}
@@ -228,9 +223,9 @@ subcollection$remove("fileInsideSubcollection.exe")
 subcollection$remove("folderInsideSubcollection/")
 ```
 
-* Move file or folder inside collection:
+* Move or rename a file or folder within a collection (moving between collections is currently not supported):
 
-Directley from collection
+Directly from collection
 
 ```{r}
 collection$move("folder/file.cpp", "file.cpp")
@@ -253,6 +248,28 @@ subcollection$move("newDestination/folder")
 Make sure to include new file name in destination.
 In second example file$move("newDestination/") will not work.
 
+* Copy file or folder within a collection (copying between collections is currently not supported):
+
+Directly from collection
+
+```{r}
+collection$copy("folder/file.cpp", "file.cpp")
+```
+
+Or from file
+
+```{r}
+file <- collection$get("location/to/my/file.cpp")
+file$copy("destination/file.cpp")
+```
+
+Or from subcollection
+
+```{r}
+subcollection <- collection$get("location/to/folder")
+subcollection$copy("destination/folder")
+```
+
 #### Working with Aravdos projects
 
 * Get a project: