update files examples

R/files.R

@@ -1,6 +1,9 @@
+#' Check if two vectors have equal lengths
+#' @keywords internal
+#' @details package \pkg{s3fs} is not checking that
+#' `length(remote_path) == length(path)` as it purports to be doing -
+#' thus the need for this helper function to check this
 equal_lengths <- function(x, y) {
-  # s3fs is not checking that length(remote_path) == length(path) as
-  # it purports to be doing
   if (length(x) != length(y)) {
     xarg <- deparse(substitute(x))
     yarg <- deparse(substitute(y))
@@ -20,51 +23,62 @@ equal_lengths <- function(x, y) {
 #' @return (character) a vector of remote s3 paths
 #' @details to upload a folder of files see [aws_bucket_upload()]
 #' @family files
-#' @examplesIf interactive()
-#' bucket <- random_string("bucket")
-#' aws_bucket_create(bucket)
+#' @examplesIf aws_has_creds()
+#' bucket1 <- random_string("bucket")
+#' aws_bucket_create(bucket1)
 #' demo_rds_file <- file.path(system.file(), "Meta/demo.rds")
 #' aws_file_upload(
 #'   demo_rds_file,
-#'   s3_path(bucket, basename(demo_rds_file))
+#'   s3_path(bucket1, basename(demo_rds_file))
 #' )
 #'
 #' ## many files at once
+#' bucket2 <- random_string("bucket")
+#' aws_bucket_create(bucket2)
 #' links_file <- file.path(system.file(), "Meta/links.rds")
 #' aws_file_upload(
 #'   c(demo_rds_file, links_file),
-#'   s3_path("s64-test-2", c(basename(demo_rds_file), basename(links_file)))
+#'   s3_path(bucket2, c(basename(demo_rds_file), basename(links_file)))
 #' )
 #'
 #' # set expiration, expire 1 minute from now
-#' aws_file_upload(demo_rds_file, s3_path("s64-test-2", "ddd.rds"),
+#' aws_file_upload(demo_rds_file, s3_path(bucket2, "ddd.rds"),
 #'   Expires = Sys.time() + 60
 #' )
 #'
 #' # bucket doesn't exist
-#' aws_file_upload(demo_rds_file, "s3://not-a-bucket/eee.rds")
+#' try(aws_file_upload(demo_rds_file, "s3://not-a-bucket/eee.rds"))
 #'
 #' # path doesn't exist
-#' aws_file_upload(
-#'   "file_doesnt_exist.txt",
-#'   s3_path("s64-test-2", "file_doesnt_exist.txt")
+#' try(
+#'   aws_file_upload(
+#'     "file_doesnt_exist.txt",
+#'     s3_path(bucket2, "file_doesnt_exist.txt")
+#'   )
 #' )
 #'
 #' # Path's without file extensions behave a little weird
 #' ## With extension
-#' ## Both of these lines do the same exact thing: make a file in the
+#' bucket3 <- random_string("bucket")
+#' aws_bucket_create(bucket3)
+#' ## Both the next two lines do the same exact thing: make a file in the
 #' ## same path in a bucket
-#' aws_file_upload("LICENSE.md", s3_path(bucket, "LICENSE.md"))
-#' aws_file_upload("LICENSE.md", s3_path(bucket))
+#' aws_file_upload("LICENSE.md", s3_path(bucket3, "LICENSE.md"))
+#' # aws_file_upload("LICENSE.md", s3_path(bucket3), overwrite=TRUE)
 #'
 #' ## Without extension
 #' ## However, it's different for a file without an extension
 #' ## This makes a file in the bucket at path DESCRIPTION
-#' aws_file_upload("DESCRIPTION", s3_path(bucket))
+#' aws_file_upload("DESCRIPTION", s3_path(bucket3))
 #'
 #' ## Whereas this creates a directory called DESCRIPTION with
 #' ## a file DESCRIPTION within it
-#' aws_file_upload("DESCRIPTION", s3_path(bucket, "DESCRIPTION"))
+#' aws_file_upload("DESCRIPTION", s3_path(bucket3, "DESCRIPTION"))
+#'
+#' # Cleanup
+#' six_bucket_delete(bucket1, force = TRUE)
+#' six_bucket_delete(bucket2, force = TRUE)
+#' six_bucket_delete(bucket3, force = TRUE)
 aws_file_upload <- function(path, remote_path, ...) {
   stopifnot(fs::file_exists(path))
   bucket <- path_s3_parse(remote_path)[[1]]$bucket
@@ -95,27 +109,43 @@ aws_file_upload <- function(path, remote_path, ...) {
 #' @family magicians
 #' @return (character) a vector of remote s3 paths where your
 #' files are located
-#' @examplesIf interactive()
-#' bucket <- random_string("bucket")
+#' @examplesIf aws_has_creds()
+#' bucket1 <- random_string("bucket")
 #' demo_rds_file <- file.path(system.file(), "Meta/demo.rds")
-#' six_file_upload(demo_rds_file, bucket)
+#' six_file_upload(demo_rds_file, bucket1, force = TRUE)
+#'
+#' # path doesn't exist, error
+#' try(
+#'   six_file_upload("file_doesnt_exist.txt", random_string("bucket"))
+#' )
+#'
+#' # directories not supported, error
+#' mydir <- tempdir()
+#' try(
+#'   six_file_upload(mydir, random_string("bucket"))
+#' )
+#'
+#' # Cleanup
+#' six_bucket_delete(bucket1, force = TRUE)
+#' @examplesIf interactive() && aws_has_creds()
+#' # requires user interaction with prompts ...
+#' bucket2 <- random_string("bucket")
+#' demo_rds_file <- file.path(system.file(), "Meta/demo.rds")
+#' six_file_upload(demo_rds_file, bucket2)
 #'
 #' ## many files at once
 #' links_file <- file.path(system.file(), "Meta/links.rds")
-#' six_file_upload(c(demo_rds_file, links_file), bucket)
+#' six_file_upload(c(demo_rds_file, links_file), bucket2)
 #'
 #' # set expiration, expire 1 minute from now
-#' six_file_upload(demo_rds_file, bucket, Expires = Sys.time() + 60)
+#' six_file_upload(demo_rds_file, bucket2, Expires = Sys.time() + 60)
 #'
 #' # bucket doesn't exist, ask if you want to create it
-#' six_file_upload(demo_rds_file, "not-a-buckets")
+#' six_file_upload(demo_rds_file, "not-a-bucket")
 #'
-#' # path doesn't exist
-#' # six_file_upload("file_doesnt_exist.txt", random_string("bucket"))
-#'
-#' # directories not supported
-#' mydir <- tempdir()
-#' # six_file_upload(mydir, random_string("bucket"))
+#' # Cleanup
+#' six_bucket_delete(bucket2, force = TRUE)
+#' six_bucket_delete("not-a-bucket", force = TRUE)
 six_file_upload <- function(path, bucket, force = FALSE, ...) {
   stop_if_not(
     all(fs::file_exists(path)),
@@ -145,32 +175,42 @@ six_file_upload <- function(path, bucket, force = FALSE, ...) {
 #' @param ... named parameters passed on to [s3fs::s3_file_download()]
 #' @return (character) a vector of local file paths
 #' @family files
-#' @examples \dontrun{
-#' tfile <- tempfile()
-#' aws_file_download(remote_path = "s3://s64-test-2/DESCRIPTION", path = tfile)
+#' @examplesIf aws_has_creds()
+#' library(glue)
+#'
+#' # single file
+#' bucket1 <- random_string("bucket")
+#' aws_bucket_create(bucket1)
+#' tfile1 <- tempfile()
+#' remote1 <- s3_path(bucket1, glue("{basename(tfile1)}.txt"))
+#' cat("Hello World!\n", file = tfile1)
+#' aws_file_upload(path = tfile1, remote_path = remote1)
+#' dfile <- tempfile()
+#' aws_file_download(remote_path = remote1, path = dfile)
+#' readLines(dfile)
 #'
 #' # many files
+#' bucket2 <- random_string("bucket")
+#' aws_bucket_create(bucket2)
 #' tfiles <- replicate(n = 3, tempfile())
-#' aws_file_download(
-#'   remote_path =
-#'     s3_path("s64-test-2", c("a_file", "c_file", "d_file")), path = tfiles
-#' )
-#'
-#' ## length of `remote_path` and `path` must be the same
-#' tfiles <- replicate(n = 2, tempfile())
-#' aws_file_download(
-#'   remote_path =
-#'     s3_path("s64-test-2", c("a_file", "c_file", "d_file")), path = tfiles
-#' )
-#'
-#' # S3 file does not exist
-#' temp_path <- tempfile()
-#' aws_file_download(s3_path("s64-test-2", "TESTING123"), temp_path)
+#' for (file in tfiles) cat("Hello mars!!!!!!\n", file = file)
+#' for (file in tfiles) print(readLines(file))
+#' for (file in tfiles) {
+#'   aws_file_upload(file, s3_path(bucket2, glue("{basename(file)}.txt")))
 #' }
+#' downloadedfiles <- replicate(n = 3, tempfile())
+#' for (file in downloadedfiles) print(file.exists(file))
+#' remotes2 <- s3_path(bucket2, glue("{basename(tfiles)}.txt"))
+#' aws_file_download(remote_path = remotes2, path = downloadedfiles)
+#' for (file in downloadedfiles) print(readLines(file))
+#'
+#' # Cleanup
+#' six_bucket_delete(bucket1, force = TRUE)
+#' six_bucket_delete(bucket2, force = TRUE)
 aws_file_download <- function(remote_path, path, ...) {
   equal_lengths(remote_path, path)
   res <- tryCatch(
-    con_s3fs()$file_download(remote_path, path),
+    con_s3fs()$file_download(remote_path, path, ...),
     error = function(e) e
   )
   if (rlang::is_error(res)) {
@@ -191,18 +231,22 @@ aws_file_download <- function(remote_path, path, ...) {
 #' [delete_object](https://www.paws-r-sdk.com/docs/s3_delete_object/)
 #' @family files
 #' @return `NULL` invisibly
-#' @examples \dontrun{
+#' @examplesIf aws_has_creds()
 #' # create a file
+#' bucket <- random_string("bucket")
+#' aws_bucket_create(bucket)
 #' tfile <- tempfile()
-#' cat("Hello World!", file = tfile)
-#' aws_file_upload(remote_path = "s3://s64-test-2", path = tfile)
+#' cat("Hello World!\n", file = tfile)
+#' aws_file_upload(path = tfile, remote_path = s3_path(bucket))
 #'
 #' # delete the file
-#' aws_file_delete(s3_path("s64-test-2", basename(tfile)))
+#' aws_file_delete(s3_path(bucket, basename(tfile)))
 #'
 #' # file does not exist - no error is raised
-#' aws_file_delete(s3_path("s64-test-2", "TESTING123"))
-#' }
+#' aws_file_delete(s3_path(bucket, "TESTING123"))
+#'
+#' # Cleanup
+#' six_bucket_delete(bucket, force = TRUE)
 aws_file_delete <- function(remote_path, ...) {
   map(remote_path, aws_file_delete_one, ...)
   remote_path
@@ -231,14 +275,26 @@ aws_file_delete_one <- function(one_path, ...) {
 #' of `remote_path`
 #' @note uses [s3fs::s3_file_info()] internally
 #' @family files
-#' @examples \dontrun{
+#' @examplesIf aws_has_creds()
+#' bucket <- random_string("bucket")
+#' aws_bucket_create(bucket)
+#'
+#' # upload some files
+#' tfiles <- replicate(n = 3, tempfile())
+#' paths <- s3_path(bucket, glue("{basename(tfiles)}.txt"))
+#' for (file in tfiles) cat("Hello saturn!!!!!!\n", file = file)
+#' for (file in tfiles) print(readLines(file))
+#' aws_file_upload(path = tfiles, remote_path = paths)
+#'
 #' # files one by one
-#' aws_file_attr(s3_path("s64-test-2", "DESCRIPTION"))
-#' aws_file_attr(s3_path("s64-test-2", "ddd"))
-#' aws_file_attr(s3_path("s64-test-2", "doesntexist"))
+#' aws_file_attr(paths[1])
+#' aws_file_attr(paths[2])
+#' aws_file_attr(paths[3])
 #' # or all together
-#' aws_file_attr(s3_path("s64-test-2", c("DESCRIPTION", "ddd")))
-#' }
+#' aws_file_attr(paths)
+#'
+#' # Cleanup
+#' six_bucket_delete(bucket, force = TRUE)
 aws_file_attr <- function(remote_path) {
   con_s3fs()$file_info(remote_path) %>% as_tibble()
 }
@@ -250,16 +306,29 @@ aws_file_attr <- function(remote_path) {
 #' @return vector of booleans (`TRUE` or `FALSE`), length matches
 #' `length(remote_path)`
 #' @family files
-#' @examples \dontrun{
-#' aws_file_exists(s3_path("s64-test-2", "DESCRIPTION"))
-#' aws_file_exists(s3_path("s64-test-2", "doesntexist"))
-#' aws_file_exists(s3_path("s64-test-2", c("DESCRIPTION", "doesntexist")))
-#' }
+#' @examplesIf aws_has_creds()
+#' bucket <- random_string("bucket")
+#' aws_bucket_create(bucket)
+#'
+#' # upload some files
+#' tfiles <- replicate(n = 3, tempfile())
+#' paths <- s3_path(bucket, glue("{basename(tfiles)}.txt"))
+#' for (file in tfiles) cat("Hello saturn!!!!!!\n", file = file)
+#' for (file in tfiles) print(readLines(file))
+#' aws_file_upload(path = tfiles, remote_path = paths)
+#'
+#' # check that files exist
+#' aws_file_exists(paths[1])
+#' aws_file_exists(paths[2])
+#' aws_file_exists(s3_path(bucket, "doesnotexist.txt"))
+#'
+#' # Cleanup
+#' six_bucket_delete(bucket, force = TRUE)
 aws_file_exists <- function(remote_path) {
   con_s3fs()$file_exists(remote_path)
 }
 
-#' Rename a remote file
+#' Rename remote files
 #'
 #' @export
 #' @inheritParams aws_file_attr
@@ -268,21 +337,22 @@ aws_file_exists <- function(remote_path) {
 #' @param ... named parameters passed on to [s3fs::s3_file_move()]
 #' @return vector of paths, length matches `length(remote_path)`
 #' @family files
-#' @examples \dontrun{
-#' aws_file_rename(
-#'   s3_path("s64-test-2", "DESCRIPTION"),
-#'   s3_path("s64-test-2", "DESC")
-#' )
+#' @examplesIf aws_has_creds()
+#' bucket <- random_string("bucket")
+#' aws_bucket_create(bucket)
 #'
+#' # rename files
 #' tfiles <- replicate(n = 3, tempfile())
 #' for (i in tfiles) cat("Hello\nWorld\n", file = i)
-#' paths <- s3_path("s64-test-2", c("aaa", "bbb", "ccc"), ext = "txt")
+#' paths <- s3_path(bucket, c("aaa", "bbb", "ccc"), ext = "txt")
 #' aws_file_upload(tfiles, paths)
-#' new_paths <- s3_path("s64-test-2", c("new_aaa", "new_bbb", "new_ccc"),
+#' new_paths <- s3_path(bucket, c("new_aaa", "new_bbb", "new_ccc"),
 #'   ext = "txt"
 #' )
 #' aws_file_rename(paths, new_paths)
-#' }
+#'
+#' # Cleanup
+#' six_bucket_delete(bucket, force = TRUE)
 aws_file_rename <- function(remote_path, new_remote_path, ...) {
   equal_lengths(remote_path, new_remote_path)
   con_s3fs()$file_move(remote_path, new_remote_path, ...)
@@ -301,21 +371,31 @@ aws_file_rename <- function(remote_path, new_remote_path, ...) {
 #' @param ... named parameters passed on to `s3fs::s3_file_copy()`
 #' @return vector of paths, length matches `length(remote_path)`
 #' @family files
-#' @examples \dontrun{
+#' @examplesIf aws_has_creds()
+#' bucket1 <- random_string("bucket")
+#' aws_bucket_create(bucket1)
+#'
 #' # create files in an existing bucket
 #' tfiles <- replicate(n = 3, tempfile())
 #' for (i in tfiles) cat("Hello\nWorld\n", file = i)
-#' paths <- s3_path("s64-test-2", c("aaa", "bbb", "ccc"), ext = "txt")
+#' paths <- s3_path(bucket1, c("aaa", "bbb", "ccc"), ext = "txt")
 #' aws_file_upload(tfiles, paths)
 #'
 #' # create a new bucket
-#' new_bucket <- aws_bucket_create(bucket = "s64-test-3")
+#' bucket2 <- random_string("bucket")
+#' new_bucket <- aws_bucket_create(bucket = bucket2)
 #'
 #' # add existing files to the new bucket
-#' aws_file_copy(paths, path_as_s3(new_bucket))
-#' # create bucket that doesn't exist yet
-#' aws_file_copy(paths, "s64-test-4")
-#' }
+#' aws_file_copy(paths, bucket2)
+#'
+#' # or, create a bucket that doesn't exist yet
+#' bucket3 <- random_string("bucket")
+#' aws_file_copy(paths, bucket3, force = TRUE)
+#'
+#' # Cleanup
+#' six_bucket_delete(bucket1, force = TRUE)
+#' six_bucket_delete(bucket2, force = TRUE)
+#' six_bucket_delete(bucket3, force = TRUE)
 aws_file_copy <- function(remote_path, bucket, force = FALSE, ...) {
   stop_if(rlang::is_missing(remote_path), "{.strong remote_path} is required")
   stop_if(rlang::is_missing(bucket), "{.strong bucket} is required")