Fast forward main to version to 1.3.4 for release

.github/workflows/pkgdown.yaml

@@ -1,6 +1,6 @@
 on:
   push:
-    branches: [main, docs, x/docs]
+    branches: [main, dev, docs, x/docs]
 
 name: pkgdown
 

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: import
 Type: Package
 Title: An Import Mechanism for R
-Version: 1.3.3
+Version: 1.3.4
 Authors@R:
     c(person(given = "Stefan Milton",
              family = "Bache",

NAMESPACE

@@ -3,3 +3,4 @@
 export(from)
 export(here)
 export(into)
+export(what)

NEWS.md

@@ -1,4 +1,16 @@
 
+Version 1.3.4
+=============
+
+* New function, import::what(), which lists objects available for import from
+  a given package or module.
+
+* Documentation links now point both to release and development documentation.
+
+* Other minor documentation improvements.
+
+
+
 Version 1.3.3
 =============
 

R/from.R

@@ -1,16 +1,23 @@
 #' Import Objects From a Package.
 #'
-#' The `import::from` and `import::into` functions provide an alternative way to
-#' import objects (e.g. functions) from packages. It is sometimes preferred over
-#' using `library` (or `require`) which will import all objects exported by the
-#' package. The benefit over `obj <- pkg::obj` is that the imported objects will
-#' (by default) be placed in a separate entry in the search path (which can be
-#' specified), rather in the global/current environment. Also, it is a more
-#' succinct way of importing several objects. Note that the two functions are
-#' symmetric, and usage is a matter of preference and whether specifying the
-#' `.into` argument is desired. The function `import::here` imports into the
-#' current environment.
+#' @description
+#' The `import::from()`, `import::into()`, and `import::here()` functions
+#' provide an alternative way to import objects (e.g. functions) from packages
+#' or modules (see below). It is sometimes preferred over using `library` (or
+#' `require`) which will import all objects exported by the package. The benefit
+#' over `obj <- pkg::obj` is that the imported objects will (by default) be
+#' placed in a separate entry in the search path (which can be specified),
+#' rather in the global/current environment. Also, it is a more succinct way of
+#' importing several objects.
 #'
+#' `import::from()` and `import::into()` are symmetric, and usage is a matter of
+#' preference and whether specifying the `.into` argument is desired.
+#' `import::here()` is a shorthand that always imports into the current
+#' environment, and `import::what()` provides a way to quickly list
+#' all objects in a package or module that are available for import by the other
+#' functions.
+#'
+#' @details
 #' The function arguments can be quoted or unquoted as with e.g. `library`. In
 #' any case, the character representation is used when unquoted arguments are
 #' provided (and not the value of objects with matching names). The period in
@@ -89,6 +96,8 @@
 #' @examples
 #' import::from(parallel, makeCluster, parLapply)
 #' import::into("imports:parallel", makeCluster, parLapply, .from = parallel)
+#' import::here(parallel, detectCores)
+#' import::what(parallel)
 #'
 #' @seealso
 #'   Helpful links:

R/what.R

@@ -0,0 +1,41 @@
+#' @rdname importfunctions
+#' @export
+what <- function(.from, ...,
+                 .library = .libPaths()[1L], .directory=".",
+                 .chdir = TRUE, .character_only = FALSE, .S3 = FALSE)
+{
+  # Capture the call and check that it is valid.
+  cl <- match.call()
+  if (!identical(cl[[1L]], call( "::", quote(import), quote(what))))
+    stop("Use `import::what()`when listing objects available for import",
+         call. = FALSE)
+
+  # Ensure the needed arguments are provided.
+  if (missing(.from))
+    stop("Argument `.from` must be specified.", call. = FALSE)
+
+  # ... is included to prevent unnamed arguments apart from `.from`,
+  # but including anything there is an error.
+  dots <- as.list(substitute(list(...)))[-1L]
+  if (length(dots) > 0L) {
+    stop("Unexpected arguments passed via `...`")
+  }
+
+  # Create cl which captures the call
+  cl <- match.call()
+
+  # If no symbols were supplied in `...`, list everything
+  dots <- as.list(substitute(list(...)))[-1L]
+  if (length(dots) == 0L) cl[[".all"]] <- TRUE
+
+  # Rewrite the call to import::from syntax and evaluate in new frame.
+  tmp_env <- new.env(parent = emptyenv())
+  cl[[1L]][[3L]] <- quote(from)
+  cl[[".into"]] <- quote(tmp_env)        # import into our temporary env
+
+  # Evaluate in an environment where `tmp_env` is bound, with the parent frame
+  # as enclosure. This preserves parent lookup while exposing `tmp_env`.
+  eval(cl, envir = list2env(list(tmp_env = tmp_env), parent = parent.frame()))
+
+  ls(tmp_env)
+}

README.Rmd

@@ -22,8 +22,8 @@ using the help (`?import::from`).
 
 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
+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.
 
 The `import` package provides a simple alternative, allowing the user specify in
@@ -36,11 +36,7 @@ import those functions only:
 import::from(Hmisc, impute, nomiss)
 ```
 
-For more on the motivation behind the package, see 
-[vignette("import")](https://rticulate.github.io/import/articles/import.html)
-
-
-## Installation
+## Installation and Documentation
 
 Install the release version of `import` from CRAN using `pak` or
 `install.packages()`:
@@ -51,23 +47,40 @@ pak::pak("import")
 install.packages("import")
 ```
 
-Install the development version of `import` from GitHub using `pak` or
-`devtools`:
+A documentation site is available on GitHub. For the `main` branch, which
+usually matches the CRAN release, the link is:
+
+- https://rticulate.github.io/import/
+
+
+### Installing from GitHub
+
+Install the either the `main` (release) or the `dev` (development) branch of
+`import` from GitHub using `pak`:
 
 ```R
+# The main branch typically matches the CRAN release
 pak::pak("rticulate/import")
-  # or
-devtools::install_github("rticulate/import")
+
+# New features are developed on the dev branch
+pak::pak("rticulate/import@dev")
 ```
 
+Documentation for the `dev` branch is available on:
+
+- https://rticulate.github.io/import/dev/
+
+
 ## Usage
 
 ### Importing functions from R packages
 
-The most basic use case is to import a few functions from package (here the
-`psych` package):
+The most basic use case is to import a few functions from package using
+`import::from()`. Here we import from the `psych` package. We start by using
+`import::what()` to list available functions.
 
 ```R
+import::what(psych) |> head()
 import::from(psych, geometric.mean, harmonic.mean)
 geometric.mean(trees$Volume)
 ```
@@ -103,15 +116,18 @@ These and other examples are discussed in more detail in the
 [Importing from Packages](https://rticulate.github.io/import/articles/import.html#importing-from-packages)
 section of the package vignette.
 
+
 ### Importing Functions from "Module" Scripts
 
 The `import` package allows R files to be used as "modules" from which functions
 are loaded. For example, the file
 [sequence_module.R](https://raw.githubusercontent.com/rticulate/import/master/man/examples/sequence_module.R) 
 contains several functions calculating terms of mathematical sequences. It is
-possible to import from such files, just as one imports from packages:
+possible to import from such files, just as one imports from packages. Again,
+we start by using `import::what()` to check what is available in the module:
 
 ```R
+import::what(sequence_module.R)
 import::from(sequence_module.R, fibonacci, square, triangular)
 ```
 

README.md

@@ -6,7 +6,7 @@
 [![CRAN
 status](https://www.r-pkg.org/badges/version/import)](https://CRAN.R-project.org/package=import)
 [![CRAN status
-shields](https://img.shields.io/badge/Git-1.3.3-success)](https://github.com/rticulate/import)
+shields](https://img.shields.io/badge/Git-1.3.4-success)](https://github.com/rticulate/import)
 [![R build
 status](https://github.com/rticulate/import/workflows/R-CMD-check/badge.svg)](https://github.com/rticulate/import/actions)
 <!-- badges: end -->
@@ -24,10 +24,10 @@ or using the help (`?import::from`).
 
 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.
+`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.
 
 The `import` package provides a simple alternative, allowing the user
 specify in a concise way exactly which objects. For example, the `Hmisc`
@@ -39,10 +39,7 @@ and the `nomiss()` functions, can import those functions only:
 import::from(Hmisc, impute, nomiss)
 ```
 
-For more on the motivation behind the package, see
-[vignette(“import”)](https://rticulate.github.io/import/articles/import.html)
-
-## Installation
+## Installation and Documentation
 
 Install the release version of `import` from CRAN using `pak` or
 `install.packages()`:
@@ -53,23 +50,38 @@ pak::pak("import")
 install.packages("import")
 ```
 
-Install the development version of `import` from GitHub using `pak` or
-`devtools`:
+A documentation site is available on GitHub. For the `main` branch,
+which usually matches the CRAN release, the link is:
+
+- <https://rticulate.github.io/import/>
+
+### Installing from GitHub
+
+Install the either the `main` (release) or the `dev` (development)
+branch of `import` from GitHub using `pak`:
 
 ``` r
+# The main branch typically matches the CRAN release
 pak::pak("rticulate/import")
-  # or
-devtools::install_github("rticulate/import")
+
+# New features are developed on the dev branch
+pak::pak("rticulate/import@dev")
 ```
 
+Documentation for the `dev` branch is available on:
+
+- <https://rticulate.github.io/import/dev/>
+
 ## Usage
 
 ### Importing functions from R packages
 
-The most basic use case is to import a few functions from package (here
-the `psych` package):
+The most basic use case is to import a few functions from package using
+`import::from()`. Here we import from the `psych` package. We start by
+using `import::what()` to list available functions.
 
 ``` r
+import::what(psych) |> head()
 import::from(psych, geometric.mean, harmonic.mean)
 geometric.mean(trees$Volume)
 ```
@@ -114,9 +126,11 @@ functions are loaded. For example, the file
 [sequence_module.R](https://raw.githubusercontent.com/rticulate/import/master/man/examples/sequence_module.R)
 contains several functions calculating terms of mathematical sequences.
 It is possible to import from such files, just as one imports from
-packages:
+packages. Again, we start by using `import::what()` to check what is
+available in the module:
 
 ``` r
+import::what(sequence_module.R)
 import::from(sequence_module.R, fibonacci, square, triangular)
 ```
 

_pkgdown.yml

@@ -1,2 +1,7 @@
+url: https://import.rticulate.org/
+
 template:
   bootstrap: 5
+
+development:
+  mode: auto

cran-comments.md

@@ -1,9 +1,12 @@
 ## General
 
-Version 1.3.3 is a bug fix release with the following fixes:
+Version 1.3.4 adds `import::what()` to list available objects for import,
+and provides some documentation improvements:
 
-* When imports conflict, include name of the conflicting object in error message
-* Update docs to point to rticulate.github.io/import (old doc domain is defunct)
+* New function, import::what(), which lists objects available for import from
+  a given package or module.
+* Documentation links now point both to release and development documentation.
+* Other minor documentation improvements.
 
 More info in `NEWS.md`