Add a clear_output function to IRdisplay

DESCRIPTION

@@ -20,4 +20,4 @@ Imports:
     repr
 License: MIT + file LICENSE
 Encoding: UTF-8
-RoxygenNote: 7.1.1
+RoxygenNote: 7.1.2

NAMESPACE

@@ -1,5 +1,6 @@
 # Generated by roxygen2: do not edit by hand
 
+export(clear_output)
 export(display)
 export(display_html)
 export(display_javascript)

R/display.r

@@ -1,23 +1,39 @@
 #' Display data by mimetype, with optional alternative representations.
 #' 
-#' Calls the function stored as option value of \code{jupyter.base_display_func}. (see: \link{IRdisplay-options})
+#' \code{publish_mimebundle} calls the function stored as option value of \code{jupyter.base_display_func},
+#' \code{clear_output} calls the value of option \code{jupyter.clear_output_func}. (see: \link{IRdisplay-options})
 #' 
 #' @param data      A named list mapping mimetypes to content (\code{\link[base]{character}} or \code{\link[base]{raw} vectors})
 #' @param metadata  A named list mapping mimetypes to named lists of metadata, e.g. \code{list('image/png' = list(width = 5))}
+#' @param wait      Wait to clear the output until new output is available. Default \code{TRUE}.
+#'                  If \code{FALSE}, clears the existing output immediately before the new output is displayed.
 #' 
 #' @seealso \code{\link{prepare_mimebundle}}
 #' 
 #' @examples \dontrun{## (Run inside of an IRkernel)
 #' publish_mimebundle(list('text/html' = '<h1>Hi!</h1>'))
 #' publish_mimebundle(
 #'   list('image/svg+xml' = '<svg xmlns="http://www.w3.org/2000/svg"><circle r="100"/></svg>'),
-#'   list('image/svg+xml' = list(width = 100, height = 100)))}
+#'   list('image/svg+xml' = list(width = 100, height = 100)))
+#' 
+#' for (i in 1:5) {
+#'   Sys.sleep(.2)    # simulate work
+#'   clear_output()   # clear previous iteration
+#'   cat(i)           # alternative: IRdisplay::display(i)
+#'   flush.console()  # make output available
+#' }}
 #' 
 #' @export
 publish_mimebundle <- function(data, metadata = NULL) {
     getOption('jupyter.base_display_func')(data, metadata)
 }
 
+#' @describeIn publish_mimebundle Clear the output from the current cell.
+#' @export
+clear_output <- function(wait = TRUE) {
+    getOption('jupyter.clear_output_func')(wait)
+}
+
 #' Create and use multiple available reprs
 #' 
 #' Both functions create a mimebundle for multiple reprs.

R/options.r

@@ -15,34 +15,40 @@
 #' 	Has the signature \code{function(data, metadata = NULL)}.
 #' 	Per default emits a \code{\link{warning}}, and is set when running an \code{IRkernel}.
 #' }
-#' 
+#' \item{\code{jupyter.clear_output_func}}{
+#' 	Function used by \code{\link{clear_output}}. Has the signature \code{function(wait = TRUE)}.
+#' 	Per default emits a \code{\link{warning}}, and is set when running an \code{IRkernel}.
 #' }
-#' 
-#' @rdname IRdisplay-options
-#' @aliases IRdisplay-options
+#'
+#' }
+#'
+#' @name IRdisplay-options
 #' @export
 irdisplay_option_defaults <- list(
     jupyter.display_mimetypes = c(
         'text/plain',
         'text/html',
         'text/markdown',
         'text/latex',
-        
+
         'application/json',
         'application/javascript',
-        
+
         'application/geo+json',
         'application/vdom.v1+json',
         'application/vnd.plotly.v1+json',
         'application/vnd.vegalite.v2+json',
         'application/vnd.vega.v4+json',
-        
+
         'application/pdf',
         'image/png',
         'image/jpeg',
         'image/svg+xml'),
     jupyter.base_display_func = function(data, metadata = NULL) {
         warning('IRdisplay can only be used from the IPython R kernel and R magic.')
+    },
+    jupyter.clear_output_func = function(wait = TRUE) {
+        warning('IRdisplay can only be used from the IPython R kernel and R magic.')
     })
 
 .onLoad <- function(libname = NULL, pkgname = NULL) {