include {fuj}

Include exports in Search Path

Description

include() checks whether or not the namespace has been loaded to the base::search() path. It uses the naming convention include:{package} to denote the differences from loading via base::library() or base::require(). When exports is NULL, the environment is detached from the search path if found. When exports is not NULL,

Note: This function has the specific purpose of affecting the search path. Use options(fuj.verbose = TRUE) or options(verbose = TRUE) for more information.

Usage

include(package, exports = NULL, lib = .libPaths(), pos = 2L, warn = NULL)

Arguments

package

A package name. This can be given as a name or a character string. See section package class handling.

exports

A character vector of exports. When named, these exports will be aliases as such.

lib

See lib.loc in base::loadNamespace().

pos

An integer specifying the position in the search() path to attach the new environment.

warn

See warn.conflicts in base::attach(), generally. The default NULL converts all messagess with masking errors to verboseMessages, TRUE converts to includeConflictsWarning messages, NA uses packageStartupMessages, and FALSE silently ignores conflicts.

Details

Include (attach) a package and specific exports to Search Path

Value

The attached environment, invisibly.

package class handling

When package is a name or AsIs, assumed an installed package. When package is a file path (via is_path()) then package is assumed a file path. When just a string, a viable path is checked first; if it doesn't exist, then it is assumed a package.

When the package is source()'d the name of the environment defaults to the base name of x (file extension removed). However, if the object .AttachName is found in the sourced file, then that is used as the environment name for the search() path.

Note: include() won't try to attach an environment a second time, however, when package is a path, it must be source()ed each time to check for the .AttachName object. If there are any side effects, they will be repeated each time include(path) is called.

Examples

# include(package) will ensure that the entire package is attached
include(fuj)
head(ls("include:fuj"), 20)
detach("include:fuj", character.only = TRUE)

# include a single export
include(fuj, "collapse")

# include multiple exports, and alias
include(fuj, c(
  no_names = "remove_names",
  match_any = "any_match"
))

# include an export where the alias has a warn conflict
include(fuj, c(attr = "exattr"))

# note that all 4 exports are included
ls("include:fuj")

# all exports are the same
identical(collapse, fuj::collapse)
identical(no_names, fuj::remove_names)
identical(match_any, fuj::any_match)
identical(attr, fuj::exattr)