rearrange box_write(), box_save_rds()

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: boxr
 Type: Package
 Title: Interface for the 'Box.com API'
-Version: 0.3.5.9009
+Version: 0.3.5.9010
 Authors@R: c(
     person("Brendan", "Rocks", email = "[email protected]",
            role = c("aut")),

NEWS.md

@@ -2,6 +2,8 @@
 
 ## Improvements
 
+* deprecates the `x` argument to `box_write()` in favor of `object`. (#187)
+
 * Some return objects can be printed as tibble (vs. data-frame). To enable this behavior, set `options(boxr.print_tibble = TRUE)` (perhaps in your `.Rprofile`).
 
 * new tools to manage [collaborations](https://developer.box.com/reference/resources/collaboration/):

R/boxr_save_load.R

@@ -1,31 +1,31 @@
 #' Download/upload an R workspace from/to a Box file
 #' 
-#' Similar to [save()], [save.image()], [saveRDS()], and [load()]: these functions operate on 
-#' files at Box instead of on local files.
+#' Use these functions to save and load workspaces or collections of objects
+#' to or from Box. Similar to [save()], [save.image()], and [load()]: 
+#' these functions operate on files at Box instead of on local files.
 #' 
 #' \describe{
 #'   \item{`box_save()`}{Save object(s) using [save()], write to Box.}
-#'   \item{`box_save_image()`}{Save image using [save.image()], write to Box.}
-#'   \item{`box_save_rds()`}{Save object using [`saveRDS()`], write to Box.}
+#'   \item{`box_save_image()`}{Save workspace image using [save.image()], 
+#'     write to Box.}
 #'   \item{`box_load()`}{Read from Box, load using [load()].}
 #' }
 #' 
 #' @aliases box_load
-#' @md
 #' 
 #' @inheritParams box_dl
 #' @inheritParams box_write
 #' @param ... Objects to be saved, quoted or unquoted; passed to `save()`.
-#' @param object R object to serialize.
 #'
 #' @return 
 #' \describe{
-#'   \item{`box_save(), box_save_image(), box_save_rds()`}{Object with S3 class [`boxr_file_reference`][boxr_S3_classes].}
-#'   \item{`box_load()`}{From [load()], a character vector of the names of objects 
-#'   created, invisibly.}
+#'   \item{`box_save(), box_save_image()`}{Object with S3 class 
+#'     [`boxr_file_reference`][boxr_S3_classes].}
+#'   \item{`box_load()`}{From [load()], a character vector of the names of
+#'     objects created, invisibly.}
 #' }
 #' 
-#' @seealso [save()], [save.image()], [saveRDS()], [load()]
+#' @seealso [save()], [save.image()], [load()]
 #'   
 #' @export
 #' 
@@ -47,6 +47,7 @@ box_save <- function(..., dir_id = box_getwd(), file_name = ".RData",
 
 #' @rdname box_save
 #' @export
+#' 
 box_save_image <- function(dir_id = box_getwd(), file_name = ".RData", 
                            description = NULL, filename) {
 
@@ -74,19 +75,7 @@ box_save_image <- function(dir_id = box_getwd(), file_name = ".RData",
 
 #' @rdname box_save
 #' @export
-box_save_rds <- function(object, dir_id = box_getwd(), file_name = ".RDS", ...,
-                     description = NULL) {
-
-  temp_file <- fs::path_temp(file_name)
-  on.exit(fs::file_delete(temp_file))
-
-  saveRDS(object, temp_file)
-
-  box_ul(dir_id, temp_file, description = description)
-}
-
-#' @rdname box_save
-#' @export
+#' 
 box_load <- function(file_id) {  
   temp_dir  <- tempdir()
   temp_file <- box_dl(file_id, overwrite = TRUE, local_dir = temp_dir)

R/boxr_write.R

@@ -1,34 +1,47 @@
 #' Write an R object to a Box file
 #' 
-#' This function is used to serialize an R object and write it
-#' to a Box file. For example, you may wish to write a `data.frame`
-#' to Box as a CSV file.
+#' Use these functions to serialize an R object and write it
+#' to a Box file. To write an object using RDS serialization, 
+#' use `box_save_rds()`; for other types of serialization, 
+#' use `box_write()` and provide a serialization function.
 #' 
-#' This is a two-step process. The first is to serialize the contents
-#' of the R object, the second is to upload that serialization to a Box file.
+#' Using `box_save_rds()` is relatively straightforward, your
+#' object will be written to Box as an RDS file.
+#' 
+#' If you want to specify the serialization, use `box_write()`.
+#' For example, you may wish to write a `data.frame`
+#' to Box as a CSV file. Within `box_write()`, this is a 
+#' two-step process:
+#' 
+#'   - serialize the contents of the R object using `write_fun`
+#'   - upload that serialization to a Box file
+#'   
 #' The default serialization-function is [rio::export()].
 #' 
-#' The [rio::export()] function currently only 
-#' supports `data.frame`; to serialize lists, you may wish to use 
-#' `jsonlite::toJSON()`.
+#' The [rio::export()] function currently supports only `data.frame`; 
+#' to serialize lists, you may wish to use `jsonlite::toJSON()`.
 #' 
 #' Please note that `box_write()` is used to write R objects to Box files 
 #' using standard formats. To write R objects as `.RData` files, 
 #' you can use [box_save()].
 #'
 #' @inheritParams box_ul
-#' @param x Object to be written.
+#' @param object Object to be written.
 #' @param file_name `character`, name of the new Box file.
 #' @param write_fun `function`, used to write (serialize) the content from R; 
 #'  default function is [rio::export()].
 #' @param ... Other arguments passed to `write_fun`.
+#' @param x Object to be written, **deprecated**: use `object` instead.
 #' @param filename `character`, **deprecated**: use `file_name` instead.
 #' 
 #' @return Object with S3 class [`boxr_file_reference`][boxr_S3_classes].
 #' 
+#' @seealso [saveRDS()], [box_save()]
+#' 
 #' @export
-box_write <- function(x, file_name, dir_id = box_getwd(), description = NULL,
-                    write_fun = rio::export, filename, ...) {
+#' 
+box_write <- function(object, file_name, dir_id = box_getwd(), description = NULL,
+                    write_fun = rio::export, x, filename, ...) {
 
   # TODO: in future version, remove argument
   if (!missing(filename)) {
@@ -43,7 +56,33 @@ box_write <- function(x, file_name, dir_id = box_getwd(), description = NULL,
     }
   }
 
+  if (!missing(x)) {
+
+    warning(
+      "argument `x` is deprecated; please use `object` instead.", 
+      call. = FALSE
+    )
+
+    if (missing(object)) {
+      object <- x
+    }
+  }
+
   temp_file <- paste0(tempdir(), "/", file_name)
-  write_fun(x, temp_file, ...)
+  write_fun(object, temp_file, ...)
   box_ul(dir_id = dir_id, file = temp_file, description = description)
 }
+
+#' @rdname box_write
+#' @export
+box_save_rds <- function(object, dir_id = box_getwd(), file_name = ".RDS",
+                         description = NULL) {
+
+  temp_file <- fs::path_temp(file_name)
+  on.exit(fs::file_delete(temp_file))
+
+  saveRDS(object, temp_file)
+
+  box_ul(dir_id, temp_file, description = description)
+}
+