0.1.0 CRAN Release

.Rbuildignore

@@ -1,10 +1,8 @@
-^renv$
-^renv\.lock$
 ^.*\.Rproj$
 ^\.Rproj\.user$
 ^LICENSE\.md$
-^updateme-demo\.gif$
 ^\.github$
 ^_pkgdown\.yml$
 ^docs$
 ^pkgdown$
+^readme-files$

DESCRIPTION

@@ -3,8 +3,8 @@ Type: Package
 Title: Informative Messages About Outdated Packages
 Version: 0.1.0
 Authors@R: person("Jacob", "Scott", email = "[email protected]", role = c("aut", "cre"))
-Description: When a package is loaded, the source repository is checked for 
-    new versions and a message is show in the console indicating whether the 
+Description: When a package is loaded, the source repository is checked for
+    new versions and a message is shown in the console indicating whether the
     package is out of date.
 License: MIT + file LICENSE
 Encoding: UTF-8
@@ -26,6 +26,5 @@ Suggests:
     rmarkdown,
     testthat (>= 3.0.0),
     withr
-VignetteBuilder: knitr
 Roxygen: list(markdown = TRUE)
 Config/testthat/edition: 3

R/available_version.R

@@ -123,8 +123,8 @@ available_version_impl_repo <- function(pkg, repo = NULL, repo_alias = NULL) {
       sub(x = _, "/R/.+$", "") |>
       sub(x = _, "/src/contrib$", "")
 
-    repo_alias <- names(repos_option)[grepl(pattern, repos_option, fixed = TRUE)]
-    if (length(repo_alias) == 0L || identical(repo_alias, ""))
+    repo_alias <- names(repos_option)[grepl(pattern, repos_option, fixed = TRUE)][1]
+    if (is.null(repo_alias) || any(is.na(repo_alias)) || identical(repo_alias, ""))
       repo_alias <- repo
   }
 
@@ -260,25 +260,25 @@ get_git_pat <- function(type = c("github", "gitlab")) {
 
   switch(type,
     github = {
-      updateme_env_var <- "UPDATEME_GITHUB_PAT"
-      git_name         <- "GitHub"
-      git_url          <- "https://github.com"
-      fallback_envvars <- c("GITHUB_PAT", "GITHUB_TOKEN")
+      envvars  <- c("GITHUB_PAT", "GITHUB_TOKEN")
+      git_name <- "GitHub"
+      git_url  <- "https://github.com"
     },
     gitlab = {
-      updateme_env_var <- "UPDATEME_GITLAB_PAT"
-      git_name         <- "GitLab"
-      git_url          <- "https://gitlab.com"
-      fallback_envvars <- c("GITLAB_PAT", "GITLAB_TOKEN")
+      envvars  <- c("GITLAB_PAT", "GITLAB_TOKEN")
+      git_name <- "GitLab"
+      git_url  <- "https://gitlab.com"
     }
   )
 
-  # 1. check special updateme env var
-  updateme_pat <- env_var(updateme_env_var)
-  if (!is.null(updateme_pat))
-    return(updateme_pat)
+  # Check standard env vars
+  for (envvar in envvars) {
+    pat <- env_var(envvar)
+    if (!is.null(pat))
+      return(pat)
+  }
 
-  # 2. check using {gitcreds}
+  # Check using {gitcreds}
   if (is_installed("gitcreds")) {
     # gitcreds may error if no git installed, no creds set, etc
     try(silent = TRUE, {
@@ -287,11 +287,5 @@ get_git_pat <- function(type = c("github", "gitlab")) {
     })
   }
 
-  # 3. Check standard env vars
-  for (envvar in fallback_envvars) {
-    pat <- env_var(envvar)
-    if (!is.null(pat))
-      return(pat)
-  }
   NULL
 }

R/updateme-package.R

@@ -1,17 +1,3 @@
-# TODO:
-#
-# ### Before CRAN
-# - bioconductor support
-# - If curl not installed, don't bother pinging - just try and handle the error.
-#   This should be slightly faster.
-# - reasonable unit testing
-# - handle tidyverse loading message
-#
-# ### One day
-# - add timeouts, and option to control
-# - check for internet connection more intelligently. In some cases, could still
-#   use the `available.packages()` cache, even if internet is down. Currently,
-#   this doesn't happen.
 
 #' @keywords internal
 "_PACKAGE"

R/updateme_on.R

@@ -1,29 +1,22 @@
-#' Temporarily turn {updateme} off for all packages
+#' Temporarily turn updateme off for all packages
 #'
 #' These functions may be useful if you find the slight delay caused by
-#' {updateme} looking up new package versions to be slowing down your workflow.
+#' updateme looking up new package versions to be slowing down your workflow.
 #'
-#' @return `NULL`, invisibly
+#' @return The old `updateme.on` option, as returned by `options()`
 #' @export
 #'
-#' @seealso [updateme_sources_set()] to turn {updateme} off for individual
+#' @seealso [updateme_sources_set()] to turn updateme off for individual
 #'   packages
 #'
-#' @examples
-#' if (FALSE) {
-#'   updateme_off()
-#'   updateme_on()
-#' }
 updateme_on <- function() {
   options(updateme.on = TRUE)
-  invisible(NULL)
 }
 
 #' @rdname updateme_on
 #' @export
 updateme_off <- function() {
   options(updateme.on = FALSE)
-  invisible(NULL)
 }
 
 updateme_is_on <- function() {

R/updateme_sources_set.R

@@ -1,4 +1,4 @@
-#' Configure {updateme} lookup of new package versions
+#' Configure updateme lookup of new package versions
 #'
 #' This function is a helper for setting the `"updateme.sources"`
 #' global option. It provides a user-friendly interface and validation of the
@@ -19,7 +19,7 @@
 #'       `"https://github.com/wurli/updateme"`: the latest version *for this
 #'       particular package* will be taken from this project
 #'
-#'   -  `NA`: {updateme} will not attempt to query new versions.
+#'   -  `NA`: updateme will not attempt to query new versions.
 #'      Note that `NA` inputs must always be named (i.e. you must specify this
 #'      'per package')
 #'
@@ -30,62 +30,60 @@
 #'   examples for more information.
 #'
 #' @section Private Repositories:
-#' {updateme} supports packages installed from private repositories on GitHub
+#' updateme supports packages installed from private repositories on GitHub
 #' and GitLab. To get upstream package version from either, you should only have
 #' to configure a personal access token (PAT):
 #'
-#' * For GitHub packages, {updateme} checks, in order:
-#'   * The `UPDATEME_GITHUB_PAT` environmental variable
-#'   * Any personal access tokens configured using [gitcreds::gitcreds_set()]
+#' * For GitHub packages, updateme checks, in order:
 #'   * The `GITHUB_PAT` environmental variable
 #'   * The `GITHUB_TOKEN` environmental variable
-#' * For GitLab packages, {updateme} checks, in order:
-#'   * The `UPDATEME_GITLAB_PAT` environmental variable
 #'   * Any personal access tokens configured using [gitcreds::gitcreds_set()]
+#' * For GitLab packages, updateme checks, in order:
 #'   * The `GITLAB_PAT` environmental variable
 #'   * The `GITLAB_TOKEN` environmental variable
-#'
+#'   * Any personal access tokens configured using [gitcreds::gitcreds_set()]
 #'
 #' @return The result of setting
 #'   `options(updateme.sources = <new_options>)`
 #'
 #' @export
 #'
-#' @seealso [updateme_on()] and [updateme_off()] to disable {updateme} for all
+#' @seealso [updateme_on()] and [updateme_off()] to disable updateme for all
 #'   packages
 #'
 #' @examples
-#' if (FALSE) {
-#'
-#'   # If you want to check non-standard repos for new versions of packages,
-#'   # you'll first have to set the repos global option. Note that each
-#'   # option must be named for compatibility with {updateme}
-#'   options(repos = c(
-#'
-#'     # Your default repos, e.g. c(CRAN = "https://cloud.r-project.org")
-#'     getOption("repos"),
-#'
-#'     # The tidyverse r-universe, including dev versions of tidyverse packages
-#'     tidyverse = "https://tidyverse.r-universe.dev",
-#'
-#'     # The r-lib r-universe, including dev versions of infrastructure packages
-#'     # like {cli}, {rlang}, etc
-#'     rlib = "https://r-lib.r-universe.dev"
-#'   ))
-#'
-#'   # 1. New versions will first be looked up in the tidyverse r-universe
-#'   # 2. If not found, they will be looked up from your usual CRAN mirror
-#'   # 3. {bslib} will always be first looked up from GitHub
-#'   # 4. {cli} will always be first looked up from the r-lib r-universe
-#'   updateme_sources_set(
-#'     "tidyverse",
-#'     "CRAN",
-#'     bslib = "https://github.com/rstudio/bslib", # Name is optional here
-#'     cli = "rlib"
-#'   )
+#' # If you want to check non-standard repos for new versions of packages,
+#' # you'll first have to set the repos global option. Note that each
+#' # option must be named for compatibility with updateme
+#' old_repos <- options(repos = c(
+#'
+#'   # Your default CRAN mirror will likely be something like this
+#'   CRAN = "https://cloud.r-project.org",
+#'
+#'   # The r-lib r-universe, including dev versions of infrastructure packages
+#'   # like cli, rlang, etc
+#'   `r-lib` = "https://r-lib.r-universe.dev"
+#' ))
+#'
+#' # 1. New versions will first be looked up from the r-lib R universe by default
+#' # 2. If not found, they will be looked up from the usual CRAN mirror
+#' # 3. dplyr will always be first looked up from GitHub
+#' # 4. ggplot2 won't be looked up or notified about
+#' old_updateme_sources <- updateme_sources_set(
+#'   "r-lib",
+#'   "CRAN",
+#'   dplyr = "https://github.com/tidyverse/dplyr", # Name is optional here
+#'   ggplot2 = NA
+#' )
+#'
+#' # memoise should now be looked up from the r-lib r-universe
+#' if (interactive()) {
+#'   library(memoise)
 #' }
 #'
-# TODO: Add .append arg?
+#' # Restore old options
+#' options(old_repos)
+#' options(old_updateme_sources)
 updateme_sources_set <- function(...) {
   options(updateme.sources = updateme_sources_set_impl(...))
 }
@@ -122,17 +120,17 @@ updateme_sources_validate <- function(src, pkg = NULL, throw = cli::cli_abort) {
 
   handle_no_sources <- function() {
     if (!is.null(throw)) {
-      repos <- names(getOption("repos"))
+      repos <- cli::cli_vec(names(getOption("repos")), style = list("vec-last" = " or "))
       throw(call = caller_call(6), c(
         "Invalid package source {.val {src}}.",
-        "i" = "Package sources must be either:",
-        " " = '1. One of {.code names(getOption("repos"))}',
-        " " = "2. {.val bioc} to check te version on Bioconductor",
-        " " = "3. {.val github}/{.val gitlab} to check the version on GitHub/GitLab if possible",
-        " " = "4. The URL of a specific GitHub repository, e.g. {.url https://github.com/wurli/updateme}",
-        " " = "5. The URL of a specific GitLab repository, e.g. {.url https://gitlab.com/r-packages/yum}",
-        " " = "6. {.val NA} to turn {.pkg updateme} off for a package",
-        " " = "7. {.val NULL} to return to the default behaviour"
+        "i" = "Inputs must be:",
+        " " = '- One of {.code names(getOption("repos"))}, i.e. {.val {repos}}',
+        " " = "- {.val bioc} to check the version on Bioconductor",
+        " " = "- {.val github}/{.val gitlab} to check the version on GitHub/GitLab if possible",
+        " " = "- The URL of a specific GitHub repository, e.g. {.val https://github.com/wurli/updateme}",
+        " " = "- The URL of a specific GitLab repository, e.g. {.val https://gitlab.com/r-packages/yum}",
+        " " = "- {.val NA} to turn {.pkg updateme} off for a package",
+        " " = "- {.val NULL} to return to the default behaviour"
       ))
     }
     NULL

R/zzz.R

@@ -5,6 +5,9 @@
     max_age = 60 * getOption("updateme.cache_expiry", 60)
   )
 
+  # Note: <<- does not modify the global environment, it simply memoises
+  # existing functions included in this package. This is the approach
+  # recommended by the {memoise} package itself - see ?memoise::memoise
   available_packages <<- memoise::memoise(
     available_packages, cache = updateme_cache
   )

README.md

@@ -4,63 +4,63 @@
 [![R-CMD-check](https://github.com/wurli/updateme/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/wurli/updateme/actions/workflows/R-CMD-check.yaml)
 <!-- badges: end -->
 
+## Installation
+
+You can install {updateme} from CRAN like so:
+``` r
+install.packages("updateme")
+```
+
+## What's in the box?
+
 {updateme} modifies `library()` to tell you if your packages are up to date when
 you load them:
 
 <!-- GitHub link used b/c pkgdown doesn't like file path -->
-![](https://raw.githubusercontent.com/wurli/updateme/main/updateme-demo.gif)
+![](https://raw.githubusercontent.com/wurli/updateme/main/readme-files/updateme-cran-pkgs.gif)
 
-## Installation
+{updateme} works with packages installed from CRAN (and CRAN-like repos),
+Bioconductor, GitHub and GitLab. Packages installed from Bioconductor are
+intelligently checked against the version of Bioconductor you're using, and 
+these get a special message if they're more recent than they probably should be:
 
-{updateme} is not yet on CRAN, but you can install it from GitHub using {pak}:
-``` r
-# install.packages("pak")
-pak::pak("wurli/updateme")
-```
+![](https://raw.githubusercontent.com/wurli/updateme/main/readme-files/updateme-bioc-pkgs.gif)
 
-## Usage
+The tidyverse is a special case, which gets its own modified startup message:
 
-To use {updateme}, simply call `library(updateme)` before loading other 
-packages. You may find you'd like to have {updateme} available all the time;
-in this case, consider adding this snippet to your `.Rprofile`:
+![](https://raw.githubusercontent.com/wurli/updateme/main/readme-files/updateme-tidyverse-msg.gif)
 
-``` r
-# If {updateme} isn't installed...
-if (!requireNamespace("updateme", quietly = TRUE)) {
-
-  # If {pak} isn't installed...
-  if (!requireNamepsace("pak", quietly = TRUE)) {
-
-    # Install {pak} from CRAN
-    install.packages("pak")
-  }
-
-  # Use {pak} to install {updateme} from GitHub
-  pak::pak("wurli/updateme")
-}
+{updateme} is configurable using
+[`updateme_sources_set()`](https://wurli.github.io/updateme/reference/updateme_sources_set.html). If, for example, you're using the development version of {lubridate} but you'd 
+like to see which version is currently on CRAN, you can get this behaviour like 
+so:
 
-library(updateme)
-```
+![](https://raw.githubusercontent.com/wurli/updateme/main/readme-files/updateme-sources-set.gif)
 
-## Configuration
+By default, {updateme} will check for new versions of a given package from 
+wherever your version seems to have been installed from. 
 
-### Package sources
+## Use {updateme} by default
 
-By default, new versions of packages will be looked up from the location
-where they seem to have been installed from. If you installed from CRAN
-(e.g. using `install.packages()`), {updateme} will check CRAN for a newer
-version, and similarly with packages installed from Bioconductor, GitHub, and 
-GitLab.
+If you find you'd like to have {updateme} available all the time, consider 
+loading it at startup by adding this snippet to your `.Rprofile`:
+
+``` r
+if (interactive()) {
+  suppressMessages(require(updateme))
+}
+```
 
-Occasionally you may want more control over where {updateme} looks for new
-package versions. You can configure this behaviour, including turning {updateme}
-off for particular packages, using `updateme_sources_set()`. If you want to 
-temporarily disable {updateme} entirely you can do so using `updateme_off()`.
+If necessary, you can turn {updateme} off using 
+[`updateme_off()`](https://wurli.github.io/updateme/reference/updateme_on.html),
+and back on with 
+[`updateme_on()`](https://wurli.github.io/updateme/reference/updateme_on.html).
 
 ### Caching
 
 Some caching of downloads is used to make most calls to `library()` pretty
-quick. The cache resets every hour, but you can configure this like so:
+quick. The cache resets every hour, but you can configure this using 
+`options()`:
 
 ``` r
 # Set the cache expiry time to 30 minutes