Join two qenv objects

join() perform checks and merges two qenv objects into one qenv object. Any common code at the start of the qenvs is only placed once at the start of the joined qenv. This allows consistent behavior when joining qenvs which share a common ancestor. See below for an example.

Usage

join(x, y)

# S4 method for qenv,qenv
join(x, y)

# S4 method for qenv.error,ANY
join(x, y)

# S4 method for qenv,qenv.error
join(x, y)

Arguments

x

(qenv)

y

(qenv)

Value

qenv object.

Details

There are some situations where join() cannot be properly performed, such as these three scenarios:

1. Both qenv objects contain an object of the same name but are not identical.
   
   Example:

   
     x <- new_qenv(
       code = c(mtcars1 = "mtcars1 <- mtcars"),
       env = list2env(list(mtcars1 = mtcars))
     )
     y <- new_qenv(
       code = c(mtcars1 = "mtcars1 <- mtcars['wt']"),
       env = list2env(list(mtcars1 = mtcars['wt']))
     )
     z <- join(x, y)
     # Error message will occur
     

   In this example, mtcars1 object exists in both x and y objects but the content are not identical.
   mtcars1 in the x qenv object has more columns than mtcars1 in the y qenv object (only has one column).

2. join() will look for identical @id values in both qenv objects. The index position of these @ids must be the same to determine the evaluation order. Otherwise, join() will throw an error message.
   
   Example:

   
     common_q <- new_qenv(code = "v <- 1", env = list2env(list(v = 1)))
     x <- eval_code(
       common_q,
       "x <- v"
     )
     y <- eval_code(
       common_q,
       "y <- v"
     )
     z <- eval_code(
       y,
       "z <- v"
     )
     q <- join(x, y)
     join_q <- join(q, z)
     # Error message will occur
   
     # Check the order of evaluation based on the id slot
     shared_ids <- intersect(q@id, z@id)
     match(shared_ids, q@id) # Output: 1 3
     match(shared_ids, z@id) # Output: 1 2
     

   The error occurs because the index position of identical @id between the two objects is not the same.

3. The usage of temporary variable in the code expression could cause join() to fail.
   
   Example:

   
     common_q <- new_qenv()
     x <- eval_code(
       common_q,
       "x <- numeric(0)
        for (i in 1:2) {
          x <- c(x, i)
        }"
     )
     y <- eval_code(
       common_q,
       "y <- numeric(0)
        for (i in 1:3) {
          y <- c(y, i)
        }"
     )
     q <- join(x,y)
     # Error message will occur
   
     # Check the value of temporary variable i in both objects
     x@env$i # Output: 2
     y@env$i # Output: 3
     

   join() fails to provide a proper result because of the temporary variable i exists in both objects but has different value.
   To fix this, we can set i <- NULL in the code expression for both objects.

   
     common_q <- new_qenv()
     x <- eval_code(
       common_q,
       "x <- numeric(0)
        for (i in 1:2) {
          x <- c(x, i)
        }
        # dummy i variable to fix it
        i <- NULL"
     )
     y <- eval_code(
       common_q,
       "y <- numeric(0)
        for (i in 1:3) {
          y <- c(y, i)
        }
        # dummy i variable to fix it
        i <- NULL"
     )
     q <- join(x,y)
     

Examples

q1 <- new_qenv(
  code = c(iris1 = "iris1 <- iris", mtcars1 = "mtcars1 <- mtcars"),
  env = list2env(list(
    iris1 = iris,
    mtcars1 = mtcars
  ))
)
q2 <- q1
q1 <- eval_code(q1, "iris2 <- iris")
q2 <- eval_code(q2, "mtcars2 <- mtcars")
qq <- join(q1, q2)
get_code(qq)
#> [1] "iris1 <- iris"     "mtcars1 <- mtcars" "iris2 <- iris"    
#> [4] "mtcars2 <- mtcars"

common_q <- new_qenv(list2env(list(x = 1)), quote(x <- 1))
y_q <- eval_code(common_q, quote(y <- x * 2))
z_q <- eval_code(common_q, quote(z <- x * 3))
join_q <- join(y_q, z_q)
# get_code only has "x <- 1" occurring once
get_code(join_q)
#> [1] "x <- 1"     "y <- x * 2" "z <- x * 3"