gitlab.com/thomasboni/go-enry/v2@v2.8.3-0.20220418031202-30b0d7a3de98/_testdata/R/import.Rd (about)

     1  % Generated by roxygen2: do not edit by hand
     2  % Please edit documentation in R/hello.R
     3  \name{import}
     4  \alias{import}
     5  \title{Import a module into the current scope}
     6  \usage{
     7  import(module, attach, attach_operators = TRUE)
     8  }
     9  \arguments{
    10  \item{module}{an identifier specifying the full module path}
    11  
    12  \item{attach}{if \code{TRUE}, attach the newly loaded module to the object
    13  search path (see \code{Details})}
    14  
    15  \item{attach_operators}{if \code{TRUE}, attach operators of module to the
    16  object search path, even if \code{attach} is \code{FALSE}}
    17  }
    18  \value{
    19  the loaded module environment (invisible)
    20  }
    21  \description{
    22  \code{module = import('module')} imports a specified module and makes its
    23  code available via the environment-like object it returns.
    24  }
    25  \details{
    26  Modules are loaded in an isolated environment which is returned, and
    27  optionally attached to the object search path of the current scope (if
    28  argument \code{attach} is \code{TRUE}).
    29  \code{attach} defaults to \code{FALSE}. However, in interactive code it is
    30  often helpful to attach packages by default. Therefore, in interactive code
    31  invoked directly from the terminal only (i.e. not within modules),
    32  \code{attach} defaults to the value of \code{options('import.attach')}, which
    33  can be set to \code{TRUE} or \code{FALSE} depending on the user’s preference.
    34  
    35  \code{attach_operators} causes \emph{operators} to be attached by default,
    36  because operators can only be invoked in R if they re found in the search
    37  path. Not attaching them therefore drastically limits a module’s usefulness.
    38  
    39  Modules are searched in the module search path \code{options('import.path')}.
    40  This is a vector of paths to consider, from the highest to the lowest
    41  priority. The current directory is \emph{always} considered first. That is,
    42  if a file \code{a.r} exists both in the current directory and in a module
    43  search path, the local file \code{./a.r} will be loaded.
    44  
    45  Module names can be fully qualified to refer to nested paths. See
    46  \code{Examples}.
    47  }
    48  \note{
    49  Unlike for packages, attaching happens \emph{locally}: if
    50  \code{import} is executed in the global environment, the effect is the same.
    51  Otherwise, the imported module is inserted as the parent of the current
    52  \code{environment()}. When used (globally) \emph{inside} a module, the newly
    53  imported module is only available inside the module’s search path, not
    54  outside it (nor in other modules which might be loaded).
    55  }
    56  \examples{
    57  # `a.r` is a file in the local directory containing a function `f`.
    58  a = import('a')
    59  a$f()
    60  
    61  # b/c.r is a file in path `b`, containing a function `g`.
    62  import('b/c', attach = TRUE)
    63  g() # No module name qualification necessary
    64  
    65  }
    66  \seealso{
    67  \code{unload}
    68  
    69  \code{reload}
    70  
    71  \code{module_name}
    72  }