Package 'teal.code'

Description

Instead of join() use c().

Usage

## S3 method for class 'qenv'
c(...)

## S3 method for class 'qenv.error'
c(...)

join(...)

Arguments

Examples

q <- qenv()
q1 <- within(q, {
  iris1 <- iris
  mtcars1 <- mtcars
})
q1 <- within(q1, iris2 <- iris)
q2 <- within(q1, mtcars2 <- mtcars)
qq <- c(q1, q2)
cat(get_code(qq))

Description

Combine two qenv objects by simple concatenate their environments and the code.

Usage

concat(x, y)

Arguments

Details

We recommend to use the join method to have a stricter control in case x and y contain duplicated bindings and code. RHS argument content has priority over the LHS one.

Value

qenv object.

Examples

q <- qenv()
q1 <- eval_code(q, expression(iris1 <- iris, mtcars1 <- mtcars))
q2 <- q1
q1 <- eval_code(q1, "iris2 <- iris")
q2 <- eval_code(q2, "mtcars2 <- mtcars")
qq <- concat(q1, q2)
get_code(qq)

Description

This function opens a PDF graphics device using grDevices::pdf to suppress the plot display in the IDE. The purpose of this function is to avoid opening graphic devices directly in the IDE.

Usage

dev_suppress(x)

Arguments

Details

The function uses base::on.exit to ensure that the PDF graphics device is closed (using grDevices::dev.off) when the function exits, regardless of whether it exits normally or due to an error. This is necessary to clean up the graphics device properly and avoid any potential issues.

Value

No return value, called for side effects.

Examples

dev_suppress(plot(1:10))

Description

Evaluate code in qenv

Usage

eval_code(object, code, ...)

Arguments

Details

eval_code() evaluates given code in the qenv environment and appends it to the code slot. Thus, if the qenv had been instantiated empty, contents of the environment are always a result of the stored code.

Value

qenv environment with code/expr evaluated or qenv.error if evaluation fails.

See Also

within.qenv

Examples

# evaluate code in qenv
q <- qenv()
q <- eval_code(q, "a <- 1")
q <- eval_code(q, "b <- 2L # with comment")
q <- eval_code(q, quote(library(checkmate)))
q <- eval_code(q, expression(assert_number(a)))

Description

Retrieves the code stored in the qenv.

Usage

get_code(object, deparse = TRUE, names = NULL, ...)

Arguments

Value

The code used in the qenv in the form specified by deparse.

Extracting dataset-specific code

get_code(object, names) limits the returned code to contain only those lines needed to create the requested objects. The code stored in the qenv is analyzed statically to determine which lines the objects of interest depend upon. The analysis works well when objects are created with standard infix assignment operators (see ?assignOps) but it can fail in some situations.

Consider the following examples:

Case 1: Usual assignments.

q1 <-
  within(qenv(), {
    foo <- function(x) {
      x + 1
    }
    x <- 0
    y <- foo(x)
  })
get_code(q1, names = "y")

x has no dependencies, so get_code(data, names = "x") will return only the second call.
y depends on x and foo, so get_code(data, names = "y") will contain all three calls.

Case 2: Some objects are created by a function's side effects.

q2 <-
  within(qenv(){
    foo <- function() {
      x <<- x + 1
    }
    x <- 0
    foo()
    y <- x
  })
get_code(q2, names = "y")

Here, y depends on x but x is modified by foo as a side effect (not by reassignment) and so get_code(data, names = "y") will not return the foo() call.
To overcome this limitation, code dependencies can be specified manually. Lines where side effects occur can be flagged by adding "⁠# @linksto <object name>⁠" at the end.
Note that within evaluates code passed to expr as is and comments are ignored. In order to include comments in code one must use the eval_code function instead.

q3 <-
  eval_code(qenv(), "
    foo <- function() {
      x <<- x + 1
    }
    x <- 0
    foo() # @linksto x
    y <- x
  ")
get_code(q3, names = "y")

Now the foo() call will be properly included in the code required to recreate y.

Note that two functions that create objects as side effects, assign and data, are handled automatically.

Here are known cases where manual tagging is necessary:

• non-standard assignment operators, e.g. ⁠%<>%⁠

• objects used as conditions in if statements: ⁠if (<condition>)⁠

• objects used to iterate over in for loops: ⁠for(i in <sequence>)⁠

• creating and evaluating language objects, e.g. ⁠eval(<call>)⁠

Examples

# retrieve code
q <- within(qenv(), {
  a <- 1
  b <- 2
})
get_code(q)
get_code(q, deparse = FALSE)
get_code(q, names = "a")

q <- qenv()
q <- eval_code(q, code = c("a <- 1", "b <- 2"))
get_code(q, names = "a")

Description

The access of environment included in the qenv that contains all data objects.

Usage

get_env(object)

Arguments

Value

An environment stored in qenv with all data objects.

Examples

q <- qenv()
q1 <- within(q, {
  a <- 5
  b <- data.frame(x = 1:10)
})
get_env(q1)

Description

Retrieve all messages raised during code evaluation in a qenv.

Usage

get_messages(object)

Arguments

Value

character containing warning information or NULL if no messages.

Examples

data_q <- qenv()
data_q <- eval_code(data_q, "iris_data <- iris")
warning_qenv <- eval_code(
  data_q,
  bquote(p <- hist(iris_data[, .("Sepal.Length")], ff = ""))
)
cat(get_messages(warning_qenv))

Description

eval_code evaluates code silently so plots and prints don't show up in the console or graphic devices. If one wants to use an output outside of the qenv (e.g. use a graph in renderPlot) then use get_outputs.

Usage

get_outputs(object)

Arguments

Value

list of outputs generated in a 'qenv“

Examples

q <- eval_code(
  qenv(),
  quote({
    a <- 1
    print("I'm an output")
    plot(1)
  })
)
get_outputs(q)

Description

Instead of get_var() use native R operators/functions: x[[name]], x$name or get():

Usage

get_var(...)

## S3 method for class 'qenv.error'
x[[i]]

Arguments

Description

Retrieve all warnings raised during code evaluation in a qenv.

Usage

get_warnings(object)

Arguments

Value

character containing warning information or NULL if no warnings.

Examples

data_q <- qenv()
data_q <- eval_code(data_q, "iris_data <- iris")
warning_qenv <- eval_code(
  data_q,
  bquote(p <- hist(iris_data[, .("Sepal.Length")], ff = ""))
)
cat(get_warnings(warning_qenv))

Description

Instantiates a qenv environment.

Usage

qenv()

Details

qenv class has following characteristics:

• It inherits from the environment and methods such as $, get(), ls(), as.list(), parent.env() work out of the box.

• qenv is a locked environment, and data modification is only possible through the eval_code() and within.qenv() functions.

• It stores metadata about the code used to create the data (see get_code()).

• It supports slicing (see subset-qenv)

• It is immutable which means that each code evaluation does not modify the original qenv environment directly. See the following code:

  q1 <- qenv()
  q2 <- eval_code(q1, "a <- 1")
  identical(q1, q2) # FALSE
  

Value

qenv environment.

See Also

eval_code(), get_var(), subset-qenv, get_env(),get_warnings(), join(), concat()

Examples

q <- qenv()
q2 <- within(q, a <- 1)
ls(q2)
q2$a

Description

Prints the qenv object.

Usage

## S4 method for signature 'qenv'
show(object)

Arguments

Value

object, invisibly.

Examples

q <- qenv()
q1 <- eval_code(q, expression(a <- 5, b <- data.frame(x = 1:10)))
q1

Description

Subsets qenv environment and limits the code to the necessary needed to build limited objects.

Usage

## S3 method for class 'qenv'
x[names, ...]

Arguments

Examples

q <- qenv()
q <- eval_code(q, "a <- 1;b<-2")
q["a"]
q[c("a", "b")]

Description

Evaluate code in qenv

Usage

## S3 method for class 'qenv'
within(data, expr, ...)

Arguments

Details

within() is a convenience method that wraps eval_code to provide a simplified way of passing expression. within accepts only inline expressions (both simple and compound) and allows to substitute expr with ... named argument values. Functions that trigger side effects like options or set.seed can be linked to specific objects for further code retrieval (with get_code), but only through eval_code where code input as character. within works on expressions that do not preserve comments, hence you can not use ⁠# @linksto⁠ tag explained in get_code.

Using language objects with within

Passing language objects to expr is generally not intended but can be achieved with do.call. Only single expressions will work and substitution is not available. See examples.

Examples

# evaluate code using within
q <- qenv()
q <- within(q, {
  i <- iris
})
q <- within(q, {
  m <- mtcars
  f <- faithful
})
q
get_code(q)

# inject values into code
q <- qenv()
q <- within(q, i <- iris)
within(q, print(dim(subset(i, Species == "virginica"))))
within(q, print(dim(subset(i, Species == species)))) # fails
within(q, print(dim(subset(i, Species == species))), species = "versicolor")
species_external <- "versicolor"
within(q, print(dim(subset(i, Species == species))), species = species_external)

# pass language objects
expr <- expression(i <- iris, m <- mtcars)
within(q, expr) # fails
do.call(within, list(q, expr))

exprlist <- list(expression(i <- iris), expression(m <- mtcars))
within(q, exprlist) # fails
do.call(within, list(q, do.call(c, exprlist)))