R API
The webR R API is provided via a pre-installed webr support package.
Graphics device for drawing to a HTML canvas element
Description
A graphics device that generates HTML canvas API calls and executes them on the worker thread using a JavaScript OffscreenCanvas. Throughout plotting, and if capture is FALSE, JavaScript ImageBitmap objects are transmitted to the main webR thread for display.
Usage
canvas(
width = 504,
height = 504,
pointsize = 12,
bg = "transparent",
capture = FALSE,
...
)
Arguments
width
|
The width of the device. |
height
|
The height of the device. |
pointsize
|
The default point size of plotted text. |
bg
|
The initial background colour. |
capture
|
If |
…
|
Additional graphics device arguments (ignored). |
Details
The resulting webR output messages are of type CanvasMessage, with the type property set as ‘canvas’ and the data property populated with further details about the event that triggered the message.
When the graphics device creates a new page an output message is emitted with the data property set to { event: ‘canvasNewPage’ }.
When bitmap image data is sent to the main thread for display, a message is emitted with the the bitmap additionally included as part of the data property, <U+2060>{ event: ‘canvasImage’, image: ImageBitmap }<U+2060>.
When capture is TRUE, the resulting OffscreenCanvas elements are stored in the canvas cache. The captured plots are then retrieved by eval_r().
A 2x scaling is used to improve the bitmap output visual quality. As such, the width and height of the HTML canvas element should be twice the width and height of the graphics device.
Based on the R canvas package by Jeffrey Horner, released under the GPL v2 Licence.
Value
A function with no arguments. When called returns an integer vector of canvas cache IDs for OffscreenCanvas elements captured by this device.
Interact with the OffscreenCanvas cache
Description
canvas_cache() returns an integer vector containing the current canvas cache IDs.
canvas_destroy() destroys the cached OffscreenCanvas elements with the given IDs.
canvas_purge() destroys all OffscreenCanvas elements in the cache.
Usage
canvas_cache()
canvas_destroy(ids)
canvas_purge()
Arguments
ids
|
Integer vector of canvas cache IDs. |
Use the webR canvas graphics device
Description
Set R options so that the webR canvas graphics device is used as the default graphics device for new plots.
Usage
canvas_install(...)
Arguments
…
|
Arguments to be passed to the graphics device. |
Evaluate JavaScript code
Description
This function evaluates the given character string as JavaScript code. Returned JavaScript objects are converted to R objects using the RObject generic constructor, and specific R object types can be returned by invoking the R object constructor directly in the evaluated JavaScript.
Usage
eval_js(code)
Arguments
code
|
The JavaScript code to evaluate. |
Details
The JavaScript code is evaluated using emscripten_run_script_int from the Emscripten C API. In the event of a JavaScript exception an R error condition will be raised with the exception message.
This is an experimental function that may undergo a breaking changes in the future.
Value
Result of evaluating the JavaScript code, returned as an R object.
Examples
eval_js("123 + 456")
eval_js("Math.sin(1)")
eval_js("true")
eval_js("undefined")
eval_js("(new Date()).toUTCString()")
eval_js("new RList({ foo: 123, bar: 456, baz: ['a', 'b', 'c']})")
Evaluate the provided R code, call, or expression for webR
Description
This function evaluates the provided R code, call, or expression with various settings in place to configure behavior. The function is intended to be used by the webR evalR API, rather than invoked directly by the end user.
Usage
eval_r(
expr,
conditions = TRUE,
streams = FALSE,
autoprint = FALSE,
handlers = TRUE,
env = parent.frame()
)
Arguments
expr
|
The R code, call or expression to evaluate. |
conditions
|
If |
streams
|
If |
autoprint
|
If |
handlers
|
If |
env
|
The environment in which to evaluate. |
Install a global handler to automatically download missing packages
Description
When enabled, packageNotFoundError errors invoke a global handler to download missing R packages from the default webR binary repo.
If it is possible to do so, execution will continue without interrupting the current program.
Usage
global_prompt_install()
Install one or more packages from a webR binary package repo
Description
Install one or more packages from a webR binary package repo
Usage
install(
packages,
repos = NULL,
info = NULL,
lib = NULL,
quiet = FALSE,
mount = TRUE
)
Arguments
packages
|
Character vector containing the names of packages to install. |
repos
|
Character vector containing the URIs of the webR repos to use. |
info
|
A character matrix as from |
lib
|
The library directory where the packages will be installed. |
quiet
|
Logical. If |
mount
|
Logical. If |
Install missing packages from the default webR binary repo
Description
When loading R packages using library_shim() or require_shim(), if a package is missing an attempt will be made to download and install the missing package from the default webR binary repo.
Once downloaded, the original base::library() or base::require() command is invoked to load the package.
Usage
library_shim(pkg, ..., show_menu = getOption("webr.show_menu"))
require_shim(pkg, ..., show_menu = getOption("webr.show_menu"))
Arguments
pkg
|
Character vector of package names |
…
|
Other arguments to be passed to |
show_menu
|
Show a menu asking the user if they would like to install the package if it is missing. Defaults to |
Details
A menu will be shown to the user when the webr.show_menu global option is set to TRUE. Otherwise, the user will not be prompted.
When the menu is enabled, loading a missing package will cause a prompt to be shown to the user asking if they would like to download the missing package. If the user replies in the affirmative, the package is downloaded using install().
The webr.show_menu global option may be overridden by providing the show_menu argument. By default, if no global option is set and no argument is provided, the menu will not be shown.
Mount an Emscripten filesystem object
Description
Uses the Emscripten filesystem API to mount a filesystem object onto a given directory in the virtual filesystem. The mountpoint will be created if it does not already exist.
When mounting an Emscripten “workerfs” type filesystem the source should be the URL or path to a filesystem image, as produced by Emscripten’s file_packager tool or as the result of appending filesystem metadata to an .tar archive using rwasm::add_tar_index(). The filesystem image may be gzip compressed, indicated by the property gzip: true in the associated filesystem metadata. The filesystem metadata and contents will be loaded and mounted onto the directory mountpoint.
When mounting an Emscripten “nodefs” type filesystem, the source should be the path to a physical directory on the host filesystem. The host directory will be mapped into the virtual filesystem and mounted onto the directory mountpoint. This filesystem type can only be used when webR is running under Node.
When mounting an Emscripten “idbfs” type filesystem, files will be persisted to or populated from a browser-based IndexedDB database whenever the JavaScript function Module.FS.syncfs is invoked. See the Emscripten IDBFS documentation for more information. This filesystem type can only be used when webR is running in a web browser and using the PostMessage communication channel.
Usage
mount(mountpoint, source, type = "workerfs")
unmount(mountpoint)
Arguments
mountpoint
|
a character string giving the path to a directory to mount onto in the Emscripten virtual filesystem. |
source
|
a character string giving the location of the data source to be mounted. |
type
|
a character string giving the type of Emscripten filesystem to be mounted: “workerfs”, “nodefs”, or “idbfs”. |
Generate an output message when file is displayed with the pager
Description
When enabled, the R pager function is replaced so that a request to display a file’s contents instead generates a webR output message. The request is forwarded to the main thread to be handled by the application loading webR.
This replaces the default R pager mechanism, which tries to start an external pager binary using the system() function.
Usage
pager_install()
Shim functions from base R
Description
Replace base R functions with implementations that work in the webR environment.
Usage
shim_install()
Details
The shimmed functions are:
-
install.packages() - replaced by webr::install().
-
library() - replaced by webr::library_shim().
-
require() - replaced by webr::require_shim().
Synchronise the Emscripten virtual filesystem
Description
Uses the Emscripten filesystem API to synchronise all mounted virtual filesystems with their backing storage, where it exists. The populate argument controls the direction of the synchronisation between Emscripten’s internal data and the file system’s persistent store.
Usage
syncfs(populate)
Arguments
populate
|
A boolean. When |
Test an installed R package by running the package examples and tests
Description
This function runs R package examples and tests. The implementation is based on tools::testInstalledPackage(), with modifications for webR where the system() function cannot be used.
Usage
test_package(pkg)
Arguments
pkg
|
Name of the package to test. |
Value
0 if the test was successful, otherwise 1.
Generate an output message when a URL is browsed to
Description
When enabled, the R viewer option is set so that a request to display a URL generates a webR output message. The request is forwarded to the main thread to be handled by the application loading webR.
This does the equivalent of the base R function utils::browseURL().
Usage
viewer_install()