# An Import Mechanism For R

# Motivation
The typical way of using functionality exposed by a package in R scripts is to
load (and attach) the entire package with `library` (or `require`). This can
have the undesirable effect of masking objects in the user's search path
and can also make it difficult and confusing to identify what functionality
comes from which package when using several `library` statements.

An alternative is to import a single object from a package, say `object <-
package::object`. The downside of this approach is that the object is placed
in the user's global work space, rather than being encapsulated somewhere else
in the search path (when using `library` to load `pkg`, a namespace `package:pkg`
will be attached in the search path which will contain the exported functions
from `pkg`). Another minor point is that one can only import one object at a
time using this approach.

The `import` package provides a simple alternative to importing and is inspired
in part by Python's `from some_module import some_function` syntax, and will
solve the two issues raised above. It is also similar to `roxygen2`s
`@importFrom package function1 function2` for packages. While `import` will
also work for package development, it is meant for `R` scripts.


# Installation and usage

To install `import` from CRAN:

    install.packages("import")


You can also install `import` from GitHub using `devtools`:

    devtools::install_github("smbache/import")


The `import` package is named to make usage expressive without having to
load the package using `library`. A basic example, which imports a few functions
from the `dplyr` package is:


    import::from(dplyr, select, arrange, keep_when = filter)


This does pretty much what it says: three functions are imported from `dplyr`,
two of which will keep their original name, and one which is renamed, e.g. to
avoid name clash with `stats::filter`. The imported objects are placed in a
separate entity in the search path which by default is named "imports".
It is therefore also easy to get rid of them again with `detach("imports")`.
The main point is that it is clear which functions
will be used and where they come from.

# Specifying a library
The `import` package will by default only use the latest specified library
(i.e. the result of `.libPaths()[1L]`). It is possible to specify a different
library using the `.library` argument in any of the `import` functions.
One import call can only use *one* library so there will not be ambiguity
as to where imports come from.

# More information
For more details, refer to the package documentation and vignette.
