Add preview argument

NEWS.md

@@ -1,5 +1,7 @@
 # rphylopic (development version)
 
+* added preview argument to get_phylopic (#59)
+
 # rphylopic 1.1.1
 
 * Minor fixes for Fedora

R/get_phylopic.R

@@ -17,12 +17,16 @@
 #' @param height \code{numeric}. If `format` is "raster", this is the desired
 #'   height of the raster image in pixels. This is ignored if `format` is
 #'   "vector".
+#' @param preview \code{logical}. If `preview` is `TRUE`, the returned
+#'   image is plotted. Defaults to `FALSE`.
 #' @return If `format` is "vector", a [Picture][grImport2::Picture-class] object
 #'   is returned. If `format` is "raster", a png array representing the
 #'   rasterized image is returned. Either way, the uuid and download url are
 #'   included as the "uuid" and "url" attributes, respectively.
 #' @importFrom rsvg rsvg_png
 #' @importFrom png readPNG
+#' @importFrom grid grid.newpage grid.raster
+#' @importFrom grImport2 grid.picture
 #' @export
 #' @examples
 #' # uuid
@@ -31,7 +35,8 @@
 #' # Get data for an image
 #' img_svg <- get_phylopic(uuid, format = "vector") # vector format
 #' img_png <- get_phylopic(uuid, format = "raster") # raster format
-get_phylopic <- function(uuid = NULL, format = "vector", height = 512) {
+get_phylopic <- function(uuid = NULL, format = "vector", height = 512,
+                         preview = FALSE) {
   # Error handling -------------------------------------------------------
   if (is.null(uuid)) {
     stop("A `uuid` is required (hint: use `get_uuid()`).")
@@ -42,6 +47,9 @@
   if (!is.character(uuid)) {
     stop("`uuid` is not of class character.")
   }
+  if (!is.logical(preview)) {
+    stop("`preview` is not of class logical.")
+  }
   if (is.numeric(format) || grepl("^[[:digit:]]+$", as.character(format))) {
     lifecycle::deprecate_warn("1.1.0",
                               paste0("get_phylopic(format = '",
@@ -70,6 +78,16 @@
     url <- image_info$vectorFile$href
     img <- get_svg(url)
   }
+  # Should the image be previewed?
+  if (preview) {
+    grid.newpage()
+    if (format == "vector") {
+      grid.picture(img)
+    } else {
+      grid.raster(img)
+    }
+  }
+
   attr(img, "uuid") <- uuid
   attr(img, "url") <- url
   img

tests/testthat/test-get_phylopic.R

@@ -13,7 +13,6 @@ test_that("get_phylopic works", {
   expect_error(get_phylopic(uuid = c("1", 2)))
   expect_error(get_phylopic(uuid = NULL))
   expect_error(get_phylopic(uuid = uuid, format = "VHS"))
-
   # 512 was deprecated for format
   expect_warning(get_phylopic(uuid = "c8f71c27-71db-4b34-ac2d-e97fea8762cf",
                               format = "512"))