diff --git a/R/qenv-join.R b/R/qenv-join.R index 1d214bf4f..f644223a0 100644 --- a/R/qenv-join.R +++ b/R/qenv-join.R @@ -7,102 +7,101 @@ #' See below for an example. #' #' There are some situations where `join()` cannot be properly performed, such as these three scenarios: -#' \enumerate{ -#' \item Both `qenv` objects contain an object of the same name but are not identical. \cr\cr -#' Example: -#' \preformatted{ -#' x <- qenv( -#' code = c(mtcars1 = "mtcars1 <- mtcars"), -#' env = list2env(list(mtcars1 = mtcars)) -#' ) -#' y <- 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.\cr -#' `mtcars1` in the `x qenv` object has more columns than `mtcars1` in the `y qenv` object (only has one column). -#' \item `join()` will look for identical `@id` values in both `qenv` objects. -#' The index position of these `@id`s must be the same to determine the evaluation order. -#' Otherwise, `join()` will throw an error message.\cr\cr -#' Example: -#' \preformatted{ -#' common_q <- 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. -#' \item The usage of temporary variable in the code expression could cause `join()` to fail. \cr\cr -#' Example: -#' \preformatted{ -#' common_q <- 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.\cr -#' To fix this, we can set `i <- NULL` in the code expression for both objects. -#' \preformatted{ -#' common_q <- 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) -#' } -#' } +#' 1. Both `qenv` objects contain an object of the same name but are not identical. +#' +#' Example: +#' +#' ```r +#' x <- eval_code(qenv(), expression(mtcars1 <- mtcars)) +#' y <- eval_code(qenv(), expression(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 `@id`s must be the same to determine the evaluation order. +#' Otherwise, `join()` will throw an error message. +#' +#' Example: +#' ```r +#' common_q <- eval_code(qenv(), expression(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: +#' ```r +#' common_q <- 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. +#' ```r +#' common_q <- 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) +#' ``` #' #' @param x (`qenv`) #' @param y (`qenv`) @@ -167,7 +166,7 @@ setMethod("join", signature = c("qenv.error", "ANY"), function(x, y) { #' If two `qenv` can be joined #' #' Checks if two `qenv` objects can be combined. -#' For more information, please see \code{\link{join}} +#' For more information, please see [`join`] #' @param x (`qenv`) #' @param y (`qenv`) #' @return `TRUE` if able to join or `character` used to print error message. diff --git a/R/utils.R b/R/utils.R index 623fb90a6..6866b7752 100644 --- a/R/utils.R +++ b/R/utils.R @@ -1,13 +1,13 @@ #' Suppresses plot display in the IDE by opening a PDF graphics device #' -#' This function opens a PDF graphics device using \code{\link[grDevices]{pdf}} to suppress +#' 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. #' #' @param x lazy binding which generates the plot(s) #' -#' @details The function uses \code{\link[base]{on.exit}} to ensure that the PDF graphics -#' device is closed (using \code{\link[grDevices]{dev.off}}) when the function exits, +#' @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. #' diff --git a/man/dev_suppress.Rd b/man/dev_suppress.Rd index 95ec62e25..5cbea7569 100644 --- a/man/dev_suppress.Rd +++ b/man/dev_suppress.Rd @@ -13,13 +13,13 @@ dev_suppress(x) No return value, called for side effects. } \description{ -This function opens a PDF graphics device using \code{\link[grDevices]{pdf}} to suppress +This function opens a PDF graphics device using \code{\link[grDevices:pdf]{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. } \details{ -The function uses \code{\link[base]{on.exit}} to ensure that the PDF graphics -device is closed (using \code{\link[grDevices]{dev.off}}) when the function exits, +The function uses \code{\link[base:on.exit]{base::on.exit}} to ensure that the PDF graphics +device is closed (using \code{\link[grDevices:dev]{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. } diff --git a/man/join.Rd b/man/join.Rd index d88808b09..40f60d0c4 100644 --- a/man/join.Rd +++ b/man/join.Rd @@ -27,100 +27,101 @@ See below for an example. There are some situations where \code{join()} cannot be properly performed, such as these three scenarios: \enumerate{ -\item Both \code{qenv} objects contain an object of the same name but are not identical. \cr\cr +\item Both \code{qenv} objects contain an object of the same name but are not identical. + Example: -\preformatted{ - x <- qenv( - code = c(mtcars1 = "mtcars1 <- mtcars"), - env = list2env(list(mtcars1 = mtcars)) - ) - y <- qenv( - code = c(mtcars1 = "mtcars1 <- mtcars['wt']"), - env = list2env(list(mtcars1 = mtcars['wt'])) - ) - z <- join(x, y) - # Error message will occur - } -In this example, \code{mtcars1} object exists in both \code{x} and \code{y} objects but the content are not identical.\cr + +\if{html}{\out{