rave_context | R Documentation |
'RAVE' Context: Read and Set Context of Environments
rave_context(
context,
require_contexts,
disallowed_context,
error_msg,
spos = 2L,
senv,
tpos = 1L,
tenv
)
context |
context string for target environment, optional, see ‘Details’ |
require_contexts |
characters, (optional): required context for current function. If any context is missing, the function will raise errors |
disallowed_context |
characters, (optional): defines the contexts that don't work for the function. If running within such contexts, the function will raise errors |
error_msg |
characters, (optional): if running in improper contexts, the
message to display, will passed to |
spos |
levels to go up to search for |
senv |
environment to read 'RAVE' contexts |
tpos |
levels to go up to search for |
tenv |
environment to set 'RAVE' contexts |
Context strings tells the function which context it's running,
and it will affect the behaviors of functions within its environment.
Because 'RAVE' modules are usually R packages, the context strings help
the module writers determine where the function is running. For example,
running locally, or in 'RAVE' container, or debug mode. A typical example
would be get_path
function. All external scripts used
in R packages require to be obtained using system.file
.
However, because the files are subject to change, using system file function
requires re-compile the package, which is time-consuming. Function
get_path
returns the file path relative to current
working directory during the development (in "default" context), and it
calls system.file
when 'RAVE' instance is running.
There are four contexts: "default"
, "rave_module_debug"
,
"rave_running"
, and "rave_running_local"
.
default
Default context: this means the function is running without any additional information.
rave_module_debug
Debug mode: used to develop and debug modules locally. Under the context, the function will be aware of the package that module belongs to
rave_running
If the function is running under this context,
this means it's running inside of shiny application (usually within
start_rave
). The function will be able to get more
contexts such as module ID, and current runtime environment
(ExecEnvir
)
rave_running_local
Similar to "rave_running"
, but
without run-time environment. Under this context, the module is
running locally without shiny. All reactive observers are disabled, and
the modules will be compiled into a function with all the inputs defined
by define_input
as arguments, and code within
"main.R"
as the main body of the function.
Function rave_context
uses reserved variables in the environment:
.__rave_context__.
, .__rave_package__.
,
.__rave_module__.
, and .__rave_module_instance__.
. Please
don't use these variables for other purposes. See ‘Examples’ for how to
set and read the context.
A list of current context, including the package name, module ID,
and current ExecEnvir
instance if running under "rave_running"
context.
# ------- 1. Read/Set Context ---------
library(dipsaus)
library(rave)
# Reset context for current environment
rave_context('default')
# Read from current caller's environment
fun <- function(...){
ctx <- rave_context()
cat2('The function is running under context - ', ctx$context)
cat2('The package under the context - ', ctx$package)
cat2('Module ID is - ', ctx$module_id)
cat2('Running instance is - ', ctx$instance)
}
fun()
## The function is running under context - default
## The package under the context -
## ...
# Set debug context
debug_env <- new.env()
rave_context('rave_module_debug', tenv = debug_env)
debug_env$.__rave_package__. <- 'ravebuiltins'
# With debug_env, the function is aware of the package it's under
with(debug_env, { fun() })
## The function is running under context - rave_module_debug
## The package under the context - ravebuiltins
## ...
# To set context within the function and affect the functions inide
fun2 <- function(module_id){
# Run rave_context and then set module ID
rave_context('rave_running_local')
.__rave_module__. <- module_id
fun()
}
with(debug_env, { fun2('power_explorer') })
## The function is running under context - rave_running_local
## The package under the context - ravebuiltins
## Module ID is - power_explorer
## ...
# Let's see what we can do with rave_module_debug
with(debug_env, { get_path('inst/rave.yaml') })
# When I develop the package, it returns:
## "/Users/beauchamplab/.../ravebuiltins/inst/settings.yaml"
# When I run in other places, it returns
## "/Users/beauchamplab/Library/R/3.6/library/ravebuiltins/rave.yaml"
# ------- 2. Setting behaviors for context ---------
# One way to set different behaviors is to using `ctx`
## Not run:
fun <- function(){
ctx <- rave_context()
switch(ctx$context, ...)
}
## End(Not run)
# The other way is to use S3 generics provided by R syntax
fun <- rave_context_generics('fun', function(module_id, ...){})
# action for default
fun.default <- function(...){
cat2('Function is not supposed to run under default context...',
level = 'ERROR')
}
# for debug, set module ID and run with rave_running_local
fun.rave_module_debug <- function(module_id, ...){
cat2('Debug mode... loading a test subject')
# Do something ... like automatically mount_demo_subject
# by running mount_demo_subject()
rave_context('rave_running_local')
.__rave_module__. <- module_id
# Recall the function under rave_running_local context
fun(module_id, ...)
}
# When running within RAVE container, local and with shiny
fun.rave_running_local <- function(...){
ctx <- rave_context()
cat2('Yay, running ', ctx$module_id, ' under context ',
ctx$context, level='INFO')
}
fun.rave_running <- fun.rave_running_local
# Run in default mode, expect error message
fun('power_explorer')
# Run in debug mode
debug_env <- new.env()
rave_context('rave_module_debug', tenv = debug_env)
debug_env$.__rave_package__. <- 'ravebuiltins'
# The function will run in debug mode, then rave_running_local
with(debug_env, { fun('power_explorer') })
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.