Evaluate R expressions in an attached environment.

Description

Evaluate R expressions in an attached environment.

Usage

attach_eval(
  unquoted_expr,
  name = "local:utils",
  pos = 2L,
  warn.conflicts = TRUE,
  ...,
  expr = substitute(unquoted_expr),
  mask.ok = NULL
)

Arguments

Value

The result after evaluating expr, invisibly.

Examples

attach_eval({
  my_helper_funct <- function(x, y) x + y
})

search() # environment "local:utils" is now attached
my_helper_funct(1, 1) # the local utility is now available

detach(local:utils) # cleanup

Source R files into an attached environment

Description

Source R files into an attached environment

Usage

attach_source(
  ...,
  name = as_tidy_env_name(c(...), prefix = "source:"),
  recursive = FALSE,
  pos = 2L,
  chdir = FALSE,
  warn.conflicts = TRUE,
  mask.ok = NULL,
  parent = .GlobalEnv
)

Arguments

Value

The attached environment, invisibly.

See Also

import_from, set_library_default_pos

import objects

Description

This is inspired by the python idiom ⁠from module import object as new_name⁠.

Usage

import_from(
  x,
  ...,
  .into = parent.frame(),
  .parent = .GlobalEnv,
  .overwrite = interactive(),
  .chdir = FALSE,
  .recursive = FALSE,
  .pos = 2L
)

Arguments

Value

The R environment or object that x resolved to, invisibly.

Note

If x is a package name, then no check is performed to ensure the object being imported is an exported function. As such, import_from() can be used to access package internal objects, though doing so is usually bad practice.

Examples

show_whats_imported <- function(...) {
  import_from(...)
  setdiff(names(environment()), "...")
}

## Importing from an R package
# import one object
show_whats_imported(envir, include)

# rename an object on import
show_whats_imported(envir, sys_source = include)

# import all NAMESPACE exports
show_whats_imported(envir, "*")
show_whats_imported(envir) # missing `...` is interpreted as "*"

# import all NAMESPACE exports, except for `include`
show_whats_imported(envir, "*", -include)

# import all NAMESPACE exports, except rename `include` to `sys_source`
show_whats_imported(envir, "*", sys_source = include)

# exclude more than one
show_whats_imported(envir, "*", -include, -attach_eval)
show_whats_imported(envir, "*", -c(include, attach_eval))

# import all NAMESPACE exports, also one internal function names `find_r_files`
show_whats_imported(envir, "*", find_r_files)

# import ALL package functions, including all internal functions
show_whats_imported(envir, "**")

# import ALL objects in the package NAMESPACE, including R's NAMESPACE machinery
show_whats_imported(envir, "***")


## Importing from R files
# setup
dir.create(tmpdir <- tempfile())
owd <- setwd(tmpdir)
writeLines(c("useful_function <- function() 'I am useful'",
             ".less_useful_fn <- function() 'less useful'"),
           "my_helpers.R")

# import one function by name
show_whats_imported("my_helpers.R", useful_function)

# import all objects whose names don't start with a "." or "_"
show_whats_imported("my_helpers.R", "*")

# import all objects
show_whats_imported("my_helpers.R", "**")

# if the filepath to your scripts is stored in a variable, supply it in a call
x <- "my_helpers.R"
try(show_whats_imported(x)) # errors out, because no package 'x'
# to force the value to be used, just supply it as a call rather than a bare symbol.
# the simplest call can be just wrapping in () or {}
show_whats_imported({x})
show_whats_imported((x))
show_whats_imported(c(x))
show_whats_imported({{x}}) # tidyverse style unquoting

## Importing R objects

# if you have an actual R object that you want to import from, you will
# have to supply it in a call
x <- list(obj1 = "one", obj2 = "two")
show_whats_imported({x})

## Not run: 
  # don't run this so we don't take a reticulate dependency
  import_from(reticulate, py_module = import) # rename object on import

  # import one object
  show_whats_imported(py_module("numpy"), random)

  # to prevent automatic conversion
  show_whats_imported(py_module("numpy", convert = FALSE), random)

  # import all objects that don't begin with a `_`
  # by default, other modules found in the module are also not imported
  show_whats_imported(py_module("glob"), "*")

  # to import EVERYTHING pass "**"
  # now includes modules that your modules imported, like `os`
  show_whats_imported(py_module("glob"), "**")

  rm(py_module) # clean up

## End(Not run)

# cleanup
setwd(owd)
unlink(tmpdir, recursive = TRUE)
rm(show_whats_imported, tmpdir, owd)

Source R files

Description

Source R files

Usage

include(
  files_andor_dirs,
  envir = parent.frame(),
  chdir = FALSE,
  recursive = FALSE
)

Arguments

Details

This is a vectorized wrapper around base::sys.source with some differences. Notably:

• envir defaults to the current frame

• envir is returned (invisibly)

• keep.source and keep.parse.data default to getOption("keep.source") and getOption("keep.parse.data") respectively, instead of getOption("keep.source.pkgs") and getOption("keep.parse.data.pkgs")

• toplevel.env is set to getOption("topLevelEnvironment", envir). In other words, if the option topLevelEnvironment is already set, it is respected.

Value

The environment envir, invisibly.

Modify default attach position for base::library()

Description

This function is documented but not exported. Reach in with envir:::set_library_default_pos() to use it.

Usage

set_library_default_pos(..., after = NULL, before = NULL, value = NULL)

Arguments

Details

This is primarily a way to "pin" a particular environment on the search path. For example, say you have a "project_utils" environment where you've defined a variety of useful functions. To prevent future library() calls from masking any objects in your attached "project_utils" environment, you can modify the default pos argument to library.

attach_source("project_utils.R", name = "project_utils)
set_library_default_pos(after = "project_utils")
library(foo) # now foo will attach after the "project_utils" environment

Value

The original default value of pos, invisibly

within methods for R environments

Description

within methods for R environments

Usage

## S3 method for class 'environment'
within(data, expr, ..., quote = substitute(expr))

## S3 method for class 'character'
within(
  data,
  expr,
  ...,
  pos = 2L,
  warn.conflicts = TRUE,
  mask.ok = NULL,
  quote = substitute(expr)
)

Arguments

Details

The only difference between attach_eval and within.character is the order of the arguments and the return value; the first returns the result of evaluating the expression, the latter the environment.

Value

The R environment, invisibly.

Note

See the note in attach_source about a potential pitfall of evaluating code directly in an attached environment.

See Also

attach_eval attach_source eval within