From a9b58cf621123dafc1e3a57c74e7c8e0414b37c1 Mon Sep 17 00:00:00 2001 From: Florian Rupprecht Date: Tue, 23 Jan 2024 18:14:22 -0500 Subject: [PATCH] CRAN requested changes for 0.1.0 --- DESCRIPTION | 3 +- R/testgraphic.R | 2 + R/unigd.R | 98 +++++++++++++++++----------------------- man/ugd.Rd | 9 ++-- man/ugd_clear.Rd | 5 +- man/ugd_close.Rd | 4 -- man/ugd_id.Rd | 25 ++++++---- man/ugd_info.Rd | 10 ++-- man/ugd_remove.Rd | 3 -- man/ugd_render.Rd | 4 -- man/ugd_render_inline.Rd | 3 -- man/ugd_save.Rd | 12 +++-- man/ugd_save_inline.Rd | 9 ++-- man/ugd_state.Rd | 3 -- man/ugd_test_pattern.Rd | 3 ++ man/unigd-package.Rd | 1 + 16 files changed, 85 insertions(+), 109 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index ef32586..fbfec58 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -6,6 +6,7 @@ Authors@R: c( person(given = "Florian", family = "Rupprecht", email = "floruppr@gmail.com", role = c("aut", "cre"), comment = c(ORCID = "0000-0002-1795-8624")), person(given = "Kun", family = "Ren", role = "ctb", email = "mail@renkun.me"), + person(given = "Tatsuya", family = "Shima", role = "ctb", email = "ts1s1andn@gmail.com"), person("Jeroen", "Ooms", role = c("ctb"), email = "jeroen@berkeley.edu", comment = c(ORCID = "0000-0002-4035-0289")), person("Hadley", "Wickham", email = "hadley@rstudio.com", role = "cph", comment = "Author of included svglite code"), person("Lionel", "Henry", email = "lionel@rstudio.com", role = "cph", comment = "Author of included svglite code"), @@ -24,7 +25,7 @@ Authors@R: person("Andrzej", "Krzemienski", role = "cph", comment = "Author of included std::experimental::optional library") ) Description: A unified R graphics backend. Render R graphics fast and easy to many common file formats. - Provides a thread safe C interface for asynchronous rendering of R graphics. + Provides a thread safe 'C' interface for asynchronous rendering of R graphics. License: GPL (>= 2) Depends: R (>= 3.2.0) diff --git a/R/testgraphic.R b/R/testgraphic.R index 4f4dc35..574f785 100644 --- a/R/testgraphic.R +++ b/R/testgraphic.R @@ -2,6 +2,8 @@ #' Plot a test pattern that can be used to evaluate and compare graphics #' devices. #' +#' @return Nothing, but a plot is generated. +#' #' @export #' #' @examples diff --git a/R/unigd.R b/R/unigd.R index 70db10c..ae5594c 100644 --- a/R/unigd.R +++ b/R/unigd.R @@ -33,17 +33,16 @@ #' @export #' #' @examples -#' \dontrun{ -#' -#' ugd() # Initialize graphics device and start server -#' ugd_browse() # Or copy the displayed link in the browser +#' ugd() # Initialize graphics device #' #' # Plot something #' x <- seq(0, 3 * pi, by = 0.1) #' plot(x, sin(x), type = "l") #' +#' # Render plot as SVG +#' ugd_render(width = 600, height = 400, as = "svg") +#' #' dev.off() # alternatively: ugd_close() -#' } ugd <- function(width = getOption("unigd.width", 720), height = getOption("unigd.height", 576), @@ -84,15 +83,12 @@ stop_if_not_unigd_device <- function(which) { #' @export #' #' @examples -#' \dontrun{ -#' #' ugd() #' ugd_state() #' plot(1, 1) #' ugd_state() #' #' dev.off() -#' } ugd_state <- function(which = dev.cur()) { stop_if_not_unigd_device(which) return(unigd_state_(which)) @@ -113,13 +109,9 @@ ugd_state <- function(which = dev.cur()) { #' @export #' #' @examples -#' \dontrun{ -#' -#' ugd() -#' ugd_info() -#' -#' dev.off() -#' } +#' ugd() # Initialize graphics device +#' ugd_info() # Get device information +#' dev.off() # Close device ugd_info <- function(which = dev.cur()) { stop_if_not_unigd_device(which) return(unigd_info_(which)) @@ -164,29 +156,34 @@ ugd_renderers <- function() { #' @param state Include the current device state in the returned result #' (see also: [ugd_state()]). #' -#' @return TODO +#' @return List containing static plot IDs. #' #' @importFrom grDevices dev.cur #' @export #' #' @examples -#' \dontrun{ +#' ugd() # Initialize graphics device #' -#' ugd() +#' # Page 1 #' plot.new() #' text(.5, .5, "#1") +#' +#' # Page 2 #' plot.new() #' text(.5, .5, "#2") +#' +#' # Page 3 #' plot.new() #' text(.5, .5, "#3") -#' third <- ugd_id() -#' second <- ugd_id(2) -#' all <- ugd_id(1, limit = Inf) -#' ugd_remove(1) -#' ugd_plot(second) #' -#' dev.off() -#' } +#' third <- ugd_id() # Get ID of page 3 (last page) +#' second <- ugd_id(2) # Get ID of page 2 +#' all <- ugd_id(1, limit = Inf) # Get all IDs +#' +#' ugd_remove(1) # Remove page 1 +#' ugd_render(second) # Render page 2 +#' +#' dev.off() # Close device ugd_id <- function(index = 0, limit = 1, which = dev.cur(), state = FALSE) { stop_if_not_unigd_device(which) if (is.infinite(limit)) { @@ -238,20 +235,16 @@ print.unigd_pid <- function(x, ...) cat(x$id) #' @export #' #' @examples -#' \dontrun{ -#' #' ugd() #' plot(1, 1) #' ugd_render(width = 600, height = 400, as = "svg") -#' #' dev.off() -#' } ugd_render <- function(page = 0, - width = -1, - height = -1, - zoom = 1, - as = "svg", - which = dev.cur()) { + width = -1, + height = -1, + zoom = 1, + as = "svg", + which = dev.cur()) { stop_if_not_unigd_device(which) page <- page_id_to_index(page, which) unigd_render_(which, page - 1, width, height, zoom, as) @@ -277,21 +270,23 @@ ugd_render <- function(page = 0, #' extension. #' @param which Which device (ID). #' -#' @return Rendered SVG string. +#' @return No return value. Plot will be saved to file. #' #' @importFrom grDevices dev.cur #' @importFrom tools file_ext #' @export #' #' @examples -#' \dontrun{ -#' #' ugd() +#' #' plot(1, 1) -#' ugd_save(file = tempfile(), width = 600, height = 400, as = "png") +#' +#' tf <- tempfile() +#' on.exit(unlink(tf)) +#' +#' ugd_save(file = tf, width = 600, height = 400, as = "png") #' #' dev.off() -#' } ugd_save <- function(file, page = 0, width = -1, @@ -305,7 +300,8 @@ ugd_save <- function(file, as <- tolower(tools::file_ext(file)) if (!(as %in% ugd_renderers()$id)) { stop("Renderer could not automatically be inferred from file extension.", - " (Set the renderer explicitly with e.g. `ugd_save(..., as = \"svg\")`)") + " (Set the renderer explicitly with ", + "e.g. `ugd_save(..., as = \"svg\")`)") } } ret <- unigd_render_(which, page - 1, width, height, zoom, as) @@ -331,15 +327,12 @@ ugd_save <- function(file, #' @export #' #' @examples -#' \dontrun{ -#' #' ugd() #' plot(1, 1) # page 1 #' hist(rnorm(100)) # page 2 #' ugd_remove(page = 1) # remove page 1 #' #' dev.off() -#' } ugd_remove <- function(page = 0, which = dev.cur()) { stop_if_not_unigd_device(which) if (inherits(page, "unigd_pid")) { @@ -360,16 +353,13 @@ ugd_remove <- function(page = 0, which = dev.cur()) { #' @export #' #' @examples -#' \dontrun{ -#' #' ugd() #' plot(1, 1) #' hist(rnorm(100)) -#' ugd_clear() +#' ugd_clear() # Clear all previous plots #' hist(rnorm(100)) #' #' dev.off() -#' } ugd_clear <- function(which = dev.cur()) { stop_if_not_unigd_device(which) return(unigd_clear_(which)) @@ -390,10 +380,7 @@ ugd_clear <- function(which = dev.cur()) { #' @export #' #' @examples -#' \dontrun{ -#' #' ugd() -#' ugd_browse() # open browser #' hist(rnorm(100)) #' ugd_close() # Equvalent to dev.off() #' @@ -401,7 +388,6 @@ ugd_clear <- function(which = dev.cur()) { #' ugd() #' ugd() #' ugd_close(all = TRUE) -#' } ugd_close <- function(which = dev.cur(), all = FALSE) { if (all) { ds <- dev.list() @@ -437,8 +423,6 @@ ugd_close <- function(which = dev.cur(), all = FALSE) { #' @export #' #' @examples -#' \dontrun{ -#' #' ugd_render_inline({ #' hist(rnorm(100)) #' }, as = "svgz") @@ -448,7 +432,6 @@ ugd_close <- function(which = dev.cur(), all = FALSE) { #' lines(c(0.5, 1, 0.5), c(0.5, 1, 1)) #' }) #' cat(s) -#' } ugd_render_inline <- function(code, page = 0, width = getOption("unigd.width", 720), @@ -500,16 +483,17 @@ ugd_render_inline <- function(code, #' @param as Renderer. #' @param ... Additional parameters passed to `ugd(...)` #' +#' @return No return value. Plot will be saved to file. #' @export #' #' @examples -#' \dontrun{ +#' tf <- tempfile(fileext=".svg") +#' on.exit(unlink(tf)) #' #' ugd_save_inline({ #' plot.new() #' lines(c(0.5, 1, 0.5), c(0.5, 1, 1)) -#' }, file = "plot.svg") -#' } +#' }, file = tf) ugd_save_inline <- function(code, file, page = 0, diff --git a/man/ugd.Rd b/man/ugd.Rd index caf22e9..55efcc1 100644 --- a/man/ugd.Rd +++ b/man/ugd.Rd @@ -52,15 +52,14 @@ All font settings and descriptions are adopted from the excellent 'svglite' package. } \examples{ -\dontrun{ - -ugd() # Initialize graphics device and start server -ugd_browse() # Or copy the displayed link in the browser +ugd() # Initialize graphics device # Plot something x <- seq(0, 3 * pi, by = 0.1) plot(x, sin(x), type = "l") +# Render plot as SVG +ugd_render(width = 600, height = 400, as = "svg") + dev.off() # alternatively: ugd_close() } -} diff --git a/man/ugd_clear.Rd b/man/ugd_clear.Rd index 6ab4ac8..d46e12e 100644 --- a/man/ugd_clear.Rd +++ b/man/ugd_clear.Rd @@ -16,14 +16,11 @@ Whether there were any pages to remove. This function will only work after starting a device with \code{\link[=ugd]{ugd()}}. } \examples{ -\dontrun{ - ugd() plot(1, 1) hist(rnorm(100)) -ugd_clear() +ugd_clear() # Clear all previous plots hist(rnorm(100)) dev.off() } -} diff --git a/man/ugd_close.Rd b/man/ugd_close.Rd index 2185344..5f4eeaf 100644 --- a/man/ugd_close.Rd +++ b/man/ugd_close.Rd @@ -20,10 +20,7 @@ This achieves the same effect as \code{\link[grDevices:dev]{grDevices::dev.off() but will only close the device if it has the unigd type. } \examples{ -\dontrun{ - ugd() -ugd_browse() # open browser hist(rnorm(100)) ugd_close() # Equvalent to dev.off() @@ -32,4 +29,3 @@ ugd() ugd() ugd_close(all = TRUE) } -} diff --git a/man/ugd_id.Rd b/man/ugd_id.Rd index 217baef..3afdd42 100644 --- a/man/ugd_id.Rd +++ b/man/ugd_id.Rd @@ -19,7 +19,7 @@ value > 1 the returned type is a list if IDs. Set to \code{0} for all.} (see also: \code{\link[=ugd_state]{ugd_state()}}).} } \value{ -TODO +List containing static plot IDs. } \description{ Query unigd graphics device static plot IDs. @@ -28,21 +28,26 @@ Available plot IDs starting from \code{index} will be returned. This function will only work after starting a device with \code{\link[=ugd]{ugd()}}. } \examples{ -\dontrun{ +ugd() # Initialize graphics device -ugd() +# Page 1 plot.new() text(.5, .5, "#1") + +# Page 2 plot.new() text(.5, .5, "#2") + +# Page 3 plot.new() text(.5, .5, "#3") -third <- ugd_id() -second <- ugd_id(2) -all <- ugd_id(1, limit = Inf) -ugd_remove(1) -ugd_plot(second) -dev.off() -} +third <- ugd_id() # Get ID of page 3 (last page) +second <- ugd_id(2) # Get ID of page 2 +all <- ugd_id(1, limit = Inf) # Get all IDs + +ugd_remove(1) # Remove page 1 +ugd_render(second) # Render page 2 + +dev.off() # Close device } diff --git a/man/ugd_info.Rd b/man/ugd_info.Rd index 4d18b85..2e93183 100644 --- a/man/ugd_info.Rd +++ b/man/ugd_info.Rd @@ -19,11 +19,7 @@ Access general information of a unigd graphics device. This function will only work after starting a device with \code{\link[=ugd]{ugd()}}. } \examples{ -\dontrun{ - -ugd() -ugd_info() - -dev.off() -} +ugd() # Initialize graphics device +ugd_info() # Get device information +dev.off() # Close device } diff --git a/man/ugd_remove.Rd b/man/ugd_remove.Rd index 63fddaf..3523b8d 100644 --- a/man/ugd_remove.Rd +++ b/man/ugd_remove.Rd @@ -20,8 +20,6 @@ Whether the page existed (and thereby was successfully removed). This function will only work after starting a device with \code{\link[=ugd]{ugd()}}. } \examples{ -\dontrun{ - ugd() plot(1, 1) # page 1 hist(rnorm(100)) # page 2 @@ -29,4 +27,3 @@ ugd_remove(page = 1) # remove page 1 dev.off() } -} diff --git a/man/ugd_render.Rd b/man/ugd_render.Rd index 7ba8dce..35f82dc 100644 --- a/man/ugd_render.Rd +++ b/man/ugd_render.Rd @@ -40,12 +40,8 @@ See \code{\link[=ugd_save]{ugd_save()}} for saving rendered plots as files. This function will only work after starting a device with \code{\link[=ugd]{ugd()}}. } \examples{ -\dontrun{ - ugd() plot(1, 1) ugd_render(width = 600, height = 400, as = "svg") - dev.off() } -} diff --git a/man/ugd_render_inline.Rd b/man/ugd_render_inline.Rd index be3c1e0..c0194be 100644 --- a/man/ugd_render_inline.Rd +++ b/man/ugd_render_inline.Rd @@ -44,8 +44,6 @@ is specified inline and an unigd graphics device is managed therefore not necessary. } \examples{ -\dontrun{ - ugd_render_inline({ hist(rnorm(100)) }, as = "svgz") @@ -56,4 +54,3 @@ s <- ugd_render_inline({ }) cat(s) } -} diff --git a/man/ugd_save.Rd b/man/ugd_save.Rd index d2bd633..4010b41 100644 --- a/man/ugd_save.Rd +++ b/man/ugd_save.Rd @@ -36,7 +36,7 @@ extension.} \item{which}{Which device (ID).} } \value{ -Rendered SVG string. +No return value. Plot will be saved to file. } \description{ See \code{\link[=ugd_render]{ugd_render()}} for accessing plot data directly in memory without @@ -44,12 +44,14 @@ saving as a file. This function will only work after starting a device with \code{\link[=ugd]{ugd()}}. } \examples{ -\dontrun{ - ugd() + plot(1, 1) -ugd_save(file = tempfile(), width = 600, height = 400, as = "png") + +tf <- tempfile() +on.exit(unlink(tf)) + +ugd_save(file = tf, width = 600, height = 400, as = "png") dev.off() } -} diff --git a/man/ugd_save_inline.Rd b/man/ugd_save_inline.Rd index 2f58af0..9d9531e 100644 --- a/man/ugd_save_inline.Rd +++ b/man/ugd_save_inline.Rd @@ -35,6 +35,9 @@ be 50\%.)} \item{...}{Additional parameters passed to \code{ugd(...)}} } +\value{ +No return value. Plot will be saved to file. +} \description{ Convenience function for quick inline plot rendering. This is similar to \code{\link[=ugd_save]{ugd_save()}} but the plotting code @@ -43,11 +46,11 @@ is specified inline and an unigd graphics device is managed therefore not necessary. } \examples{ -\dontrun{ +tf <- tempfile(fileext=".svg") +on.exit(unlink(tf)) ugd_save_inline({ plot.new() lines(c(0.5, 1, 0.5), c(0.5, 1, 1)) -}, file = "plot.svg") -} +}, file = tf) } diff --git a/man/ugd_state.Rd b/man/ugd_state.Rd index 3676232..f98b272 100644 --- a/man/ugd_state.Rd +++ b/man/ugd_state.Rd @@ -20,8 +20,6 @@ Access status information of a unigd graphics device. This function will only work after starting a device with \code{\link[=ugd]{ugd()}}. } \examples{ -\dontrun{ - ugd() ugd_state() plot(1, 1) @@ -29,4 +27,3 @@ ugd_state() dev.off() } -} diff --git a/man/ugd_test_pattern.Rd b/man/ugd_test_pattern.Rd index 25d09ef..e28130c 100644 --- a/man/ugd_test_pattern.Rd +++ b/man/ugd_test_pattern.Rd @@ -7,6 +7,9 @@ devices.} \usage{ ugd_test_pattern() } +\value{ +Nothing, but a plot is generated. +} \description{ Plot a test pattern that can be used to evaluate and compare graphics devices. diff --git a/man/unigd-package.Rd b/man/unigd-package.Rd index 3a61540..daf2eee 100644 --- a/man/unigd-package.Rd +++ b/man/unigd-package.Rd @@ -23,6 +23,7 @@ Useful links: Other contributors: \itemize{ \item Kun Ren \email{mail@renkun.me} [contributor] + \item Tatsuya Shima \email{ts1s1andn@gmail.com} [contributor] \item Jeroen Ooms \email{jeroen@berkeley.edu} (\href{https://orcid.org/0000-0002-4035-0289}{ORCID}) [contributor] \item Hadley Wickham \email{hadley@rstudio.com} (Author of included svglite code) [copyright holder] \item Lionel Henry \email{lionel@rstudio.com} (Author of included svglite code) [copyright holder]