From b49e9bb5861c20f9473dfab5c6cd23e9b6a23039 Mon Sep 17 00:00:00 2001 From: Ian Lyttle Date: Sat, 26 Sep 2020 09:11:37 -0500 Subject: [PATCH 1/2] - deprecate `x` for `object` in box_write() - associate box_save_rds() with box_write() - update docs - bump version --- DESCRIPTION | 2 +- NEWS.md | 2 ++ R/boxr_save_load.R | 35 +++++++++----------------- R/boxr_write.R | 63 +++++++++++++++++++++++++++++++++++++--------- man/box_save.Rd | 29 ++++++++------------- man/box_write.Rd | 44 ++++++++++++++++++++++++-------- 6 files changed, 110 insertions(+), 65 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 0ffe9a72..008bc075 100644 --- a/DESCRIPTION +++ b/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 = "foss@brendanrocks.com", role = c("aut")), diff --git a/NEWS.md b/NEWS.md index 96982efb..a53e9e9a 100644 --- a/NEWS.md +++ b/NEWS.md @@ -2,6 +2,8 @@ ## Improvements +* depercates 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/): diff --git a/R/boxr_save_load.R b/R/boxr_save_load.R index f237cdc6..0a872b43 100644 --- a/R/boxr_save_load.R +++ b/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) diff --git a/R/boxr_write.R b/R/boxr_write.R index 0a834a24..5b6006a6 100644 --- a/R/boxr_write.R +++ b/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) +} + diff --git a/man/box_save.Rd b/man/box_save.Rd index 1776fa49..c41830ca 100644 --- a/man/box_save.Rd +++ b/man/box_save.Rd @@ -4,7 +4,6 @@ \alias{box_save} \alias{box_load} \alias{box_save_image} -\alias{box_save_rds} \title{Download/upload an R workspace from/to a Box file} \usage{ box_save(..., dir_id = box_getwd(), file_name = ".RData", description = NULL) @@ -16,14 +15,6 @@ box_save_image( filename ) -box_save_rds( - object, - dir_id = box_getwd(), - file_name = ".RDS", - ..., - description = NULL -) - box_load(file_id) } \arguments{ @@ -38,29 +29,29 @@ for the local version of the Box file.} \item{filename}{\code{character}, \strong{deprecated}: use \code{file_name} instead.} -\item{object}{R object to serialize.} - \item{file_id}{\code{numeric} or \code{character}, file ID at Box.} } \value{ \describe{ -\item{\verb{box_save(), box_save_image(), box_save_rds()}}{Object with S3 class \code{\link[=boxr_S3_classes]{boxr_file_reference}}.} -\item{\code{box_load()}}{From \code{\link[=load]{load()}}, a character vector of the names of objects -created, invisibly.} +\item{\verb{box_save(), box_save_image()}}{Object with S3 class +\code{\link[=boxr_S3_classes]{boxr_file_reference}}.} +\item{\code{box_load()}}{From \code{\link[=load]{load()}}, a character vector of the names of +objects created, invisibly.} } } \description{ -Similar to \code{\link[=save]{save()}}, \code{\link[=save.image]{save.image()}}, \code{\link[=saveRDS]{saveRDS()}}, and \code{\link[=load]{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 \code{\link[=save]{save()}}, \code{\link[=save.image]{save.image()}}, and \code{\link[=load]{load()}}: +these functions operate on files at Box instead of on local files. } \details{ \describe{ \item{\code{box_save()}}{Save object(s) using \code{\link[=save]{save()}}, write to Box.} -\item{\code{box_save_image()}}{Save image using \code{\link[=save.image]{save.image()}}, write to Box.} -\item{\code{box_save_rds()}}{Save object using \code{\link[=saveRDS]{saveRDS()}}, write to Box.} +\item{\code{box_save_image()}}{Save workspace image using \code{\link[=save.image]{save.image()}}, +write to Box.} \item{\code{box_load()}}{Read from Box, load using \code{\link[=load]{load()}}.} } } \seealso{ -\code{\link[=save]{save()}}, \code{\link[=save.image]{save.image()}}, \code{\link[=saveRDS]{saveRDS()}}, \code{\link[=load]{load()}} +\code{\link[=save]{save()}}, \code{\link[=save.image]{save.image()}}, \code{\link[=load]{load()}} } diff --git a/man/box_write.Rd b/man/box_write.Rd index be23bfdc..8e637f1f 100644 --- a/man/box_write.Rd +++ b/man/box_write.Rd @@ -2,20 +2,29 @@ % Please edit documentation in R/boxr_write.R \name{box_write} \alias{box_write} +\alias{box_save_rds} \title{Write an R object to a Box file} \usage{ box_write( - x, + object, file_name, dir_id = box_getwd(), description = NULL, write_fun = rio::export, + x, filename, ... ) + +box_save_rds( + object, + dir_id = box_getwd(), + file_name = ".RDS", + description = NULL +) } \arguments{ -\item{x}{Object to be written.} +\item{object}{Object to be written.} \item{file_name}{\code{character}, name of the new Box file.} @@ -26,6 +35,8 @@ box_write( \item{write_fun}{\code{function}, used to write (serialize) the content from R; default function is \code{\link[rio:export]{rio::export()}}.} +\item{x}{Object to be written, \strong{deprecated}: use \code{object} instead.} + \item{filename}{\code{character}, \strong{deprecated}: use \code{file_name} instead.} \item{...}{Other arguments passed to \code{write_fun}.} @@ -34,20 +45,33 @@ default function is \code{\link[rio:export]{rio::export()}}.} Object with S3 class \code{\link[=boxr_S3_classes]{boxr_file_reference}}. } \description{ -This function is used to serialize an R object and write it -to a Box file. For example, you may wish to write a \code{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 \code{box_save_rds()}; for other types of serialization, +use \code{box_write()} and provide a serialization function. } \details{ -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 \code{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 \code{box_write()}. +For example, you may wish to write a \code{data.frame} +to Box as a CSV file. Within \code{box_write()}, this is a +two-step process: +\itemize{ +\item serialize the contents of the R object using \code{write_fun} +\item upload that serialization to a Box file +} + The default serialization-function is \code{\link[rio:export]{rio::export()}}. -The \code{\link[rio:export]{rio::export()}} function currently only -supports \code{data.frame}; to serialize lists, you may wish to use -\code{jsonlite::toJSON()}. +The \code{\link[rio:export]{rio::export()}} function currently supports only \code{data.frame}; +to serialize lists, you may wish to use \code{jsonlite::toJSON()}. Please note that \code{box_write()} is used to write R objects to Box files using standard formats. To write R objects as \code{.RData} files, you can use \code{\link[=box_save]{box_save()}}. } +\seealso{ +\code{\link[=saveRDS]{saveRDS()}}, \code{\link[=box_save]{box_save()}} +} From 61658c1e819a608835bc9d4a1a72bf4a789f883a Mon Sep 17 00:00:00 2001 From: Ian Lyttle Date: Sat, 26 Sep 2020 10:15:01 -0500 Subject: [PATCH 2/2] fix typo --- NEWS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/NEWS.md b/NEWS.md index a53e9e9a..bd02040e 100644 --- a/NEWS.md +++ b/NEWS.md @@ -2,7 +2,7 @@ ## Improvements -* depercates the `x` argument to `box_write()` in favor of `object`. (#187) +* 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`).