Merge pull request #46 from mrc-ide/mrc-4417

Interface harmonisation step 1, renaming most outpack functions

NAMESPACE

@@ -1,26 +1,32 @@
 # Generated by roxygen2: do not edit by hand
 
-S3method(format,outpack_query)
+S3method(format,orderly_query)
 export(orderly_artefact)
 export(orderly_cleanup)
 export(orderly_cleanup_status)
+export(orderly_copy_files)
 export(orderly_dependency)
 export(orderly_description)
 export(orderly_global_resource)
 export(orderly_init)
 export(orderly_interactive_set_search_options)
+export(orderly_log_read)
+export(orderly_metadata)
+export(orderly_metadata_extract)
+export(orderly_metadata_read)
 export(orderly_parameters)
 export(orderly_plugin_add_metadata)
 export(orderly_plugin_context)
 export(orderly_plugin_register)
+export(orderly_query)
+export(orderly_query_format)
 export(orderly_resource)
 export(orderly_run)
 export(orderly_run_info)
+export(orderly_search)
+export(orderly_search_options)
 export(orderly_strict_mode)
-export(outpack_checksum)
 export(outpack_config_set)
-export(outpack_copy_files)
-export(outpack_id)
 export(outpack_init)
 export(outpack_location_add)
 export(outpack_location_list)
@@ -29,25 +35,4 @@ export(outpack_location_pull_packet)
 export(outpack_location_push)
 export(outpack_location_remove)
 export(outpack_location_rename)
-export(outpack_log)
-export(outpack_log_debug)
-export(outpack_log_info)
-export(outpack_log_read)
-export(outpack_log_trace)
-export(outpack_metadata)
-export(outpack_metadata_extract)
-export(outpack_metadata_read)
-export(outpack_packet_add_custom)
-export(outpack_packet_cancel)
-export(outpack_packet_end)
-export(outpack_packet_file_list)
-export(outpack_packet_file_mark)
-export(outpack_packet_run)
-export(outpack_packet_start)
-export(outpack_packet_use_dependency)
-export(outpack_query)
-export(outpack_query_format)
-export(outpack_root_open)
-export(outpack_search)
-export(outpack_search_options)
 importFrom(R6,R6Class)

R/interactive.R

@@ -21,7 +21,7 @@ detect_orderly_interactive_path <- function(path = getwd()) {
 
 ##' Set search options for interactive use of orderly; see
 ##' [orderly2::orderly_dependency] and [orderly2::orderly_run] for
-##' details. This may be either an [orderly2::outpack_search_options]
+##' details. This may be either an [orderly2::orderly_search_options]
 ##' object, or a list that will be coerced into one at the point of
 ##' use (or `NULL`). This applies only for the current session, but
 ##' applies to all interactive uses of orderly functions that might

R/metadata.R

@@ -243,8 +243,8 @@ static_orderly_artefact <- function(args) {
 ##'
 ##' @param use Files to use from the packet found by `query`, usually
 ##'   as a named character vector with string interpolation in the
-##'   names; see [orderly2::outpack_packet_use_dependency]'s `file`
-##'   argument for details.
+##'   names; see [orderly2::orderly_copy_files]' `file` argument for
+##'   details.
 ##'
 ##' @return Undefined
 ##' @export
@@ -254,19 +254,19 @@ orderly_dependency <- function(name, query, use) {
 
   ctx <- orderly_context()
   subquery <- NULL
-  query <- outpack_query(query, name = name, subquery = subquery)
-  search_options <- as_outpack_search_options(ctx$search_options)
+  query <- orderly_query(query, name = name, subquery = subquery)
+  search_options <- as_orderly_search_options(ctx$search_options)
   if (ctx$is_active) {
     outpack_packet_use_dependency(ctx$packet, query, use,
                                   search_options = search_options,
                                   envir = ctx$env,
                                   overwrite = TRUE)
   } else {
-    id <- outpack_search(query, parameters = ctx$parameters,
+    id <- orderly_search(query, parameters = ctx$parameters,
                          envir = ctx$env,
                          options = search_options,
                          root = ctx$root)
-    outpack_copy_files(id, use, ctx$path,
+    orderly_copy_files(id, use, ctx$path,
                        allow_remote = search_options$allow_remote,
                        overwrite = TRUE,
                        envir = ctx$env,

R/outpack_checksum.R

@@ -1,21 +1,6 @@
-##' Compute a checksum over all known packet metadata. This can be
-##' used to check whether a cache of all metadata needs refreshing (or
-##' agrees between two roots) without having to read a lot of data. It
-##' is unlikely that most users will call this function.
-##'
-##' This function matches the behaviour (and hash) of the outpack
-##' server. We may expand the behaviour or either or both of these to
-##' include a similar checksum that includes location data.
-##'
-##' @title Compute packet metadata checksum
-##'
-##' @param hash_algorithm The hash algorithm to use, defaulting to the
-##'   root's hash algorithm.
-##'
-##' @inheritParams outpack_search
-##'
-##' @return A hash string
-##' @export
+## TODO: I am not sure we need to keep this; it's not used anywhere at
+## present. It might have been intended for the R-backed server, now
+## defunct?
 outpack_checksum <- function(hash_algorithm = NULL, root = NULL) {
   root <- outpack_root_open(root, locate = TRUE)
   hash_algorithm <- hash_algorithm %||% root$config$core$hash_algorithm

R/outpack_helpers.R

@@ -1,8 +1,8 @@
 ##' Copy files from a packet to anywhere. Similar to
-##' [orderly2::outpack_packet_use_dependency] except that this is not
-##' used in an active packet context. You can use this function to
-##' pull files from an outpack root to a directory outside of the
-##' control of outpack, for example.
+##' [orderly2::orderly_dependency] except that this is not used in an
+##' active packet context. You can use this function to pull files
+##' from an outpack root to a directory outside of the control of
+##' outpack, for example.
 ##'
 ##' There are different ways that this might fail (or recover from
 ##' failure):
@@ -27,7 +27,36 @@
 ##'
 ##' @title Copy files from a packet
 ##'
-##' @inheritParams outpack_packet_use_dependency
+##' @param id Id of the packet to copy from (will become a query, see
+##'   mrc-4418)
+##'
+##' @param files Files to copy from the other packet. This can be (1)
+##'   a character vector, in which case files are copied over without
+##'   changing their names, (2) a **named** character vector, in which
+##'   case the name will be used as the destination name, or (3) a
+##'   [data.frame] (including `tbl_df`, or `data.frame` objects)
+##'   containing columns `from` and `to`, in which case the files
+##'   `from` will be copied with names `to`.
+##'
+##' In all cases, if you want to import a directory of files from a
+##'   packet, you must refer to the source with a trailing slash
+##'   (e.g., `c(here = "there/")`), which will create the local
+##'   directory `here/...` with files from the upstream packet
+##'   directory `there/`. If you omit the slash then an error will be
+##'   thrown suggesting that you add a slash if this is what you
+##'   intended.
+##'
+##' You can use a limited form of string interpolation in the names of
+##'   this argument; using `${variable}` will pick up values from
+##'   `envir` and substitute them into your string.  This is similar
+##'   to the interpolation you might be familiar with from
+##'   `glue::glue` or similar, but much simpler with no concatenation
+##'   or other fancy features supported.
+##'
+##' Note that there is an unfortunate, but (to us) avoidable
+##'   inconsistency here; interpolation of values from your
+##'   environment in the query is done by using `environment:x` and in
+##'   the destination filename by doing `${x}`.
 ##'
 ##' @param dest The directory to copy into
 ##'
@@ -39,17 +68,24 @@
 ##'   though associated with no packet so that it is subject to
 ##'   garbage collection (once we write support for that).
 ##'
+##' @param overwrite Overwrite files at the destination; this is
+##'   typically what you want, but set to `FALSE` if you would prefer
+##'   that an error be thrown if the destination file already exists.
+##'
 ##' @param envir An environment into which string interpolation may
-##'   happen (see [orderly2::outpack_packet_use_dependency] for
-##'   details on the string interpolation).  The default here is to
-##'   use the calling environment, which is typically reasonable, but
-##'   may need changing in programmatic use.
+##'   happen (see the `files` argument for details on the string
+##'   interpolation).  The default here is to use the calling
+##'   environment, which is typically reasonable, but may need
+##'   changing in programmatic use.
+##'
+##' @param root The outpack root. Will be searched for from the
+##'   current directory if not given.
 ##'
 ##' @return Nothing, invisibly. Primarily called for its side effect
 ##'   of copying files from a packet into the directory `dest`
 ##'
 ##' @export
-outpack_copy_files <- function(id, files, dest, allow_remote = FALSE,
+orderly_copy_files <- function(id, files, dest, allow_remote = FALSE,
                                overwrite = TRUE, envir = parent.frame(),
                                root = NULL) {
   root <- outpack_root_open(root, locate = TRUE)

R/outpack_location.R

@@ -248,7 +248,7 @@ outpack_location_pull_metadata <- function(location = NULL, root = NULL) {
 
 ##' Pull a packet (all files) from a location into this archive. This
 ##' will make files available for use as dependencies (e.g., with
-##' [orderly2::outpack_packet_use_dependency])
+##' [orderly2::orderly_dependency])
 ##'
 ##' The behaviour of this function will vary depending on whether or
 ##' not the destination outpack repository (i.e., `root`) uses a file

R/outpack_logging.R

@@ -29,7 +29,7 @@
 ##'   package name here.
 ##'
 ##' @return Nothing, this is called for its side effects
-##' @export
+##' @noRd
 outpack_log <- function(object, log_level, topic, detail, caller) {
   if (inherits(object, "outpack_packet") || inherits(object, "outpack_root")) {
     logger <- object$logger
@@ -52,22 +52,16 @@ outpack_log <- function(object, log_level, topic, detail, caller) {
 }
 
 
-##' @export
-##' @rdname outpack_log
 outpack_log_info <- function(object, topic, detail, caller) {
   outpack_log(object, "info", topic, detail, caller)
 }
 
 
-##' @export
-##' @rdname outpack_log
 outpack_log_debug <- function(object, topic, detail, caller) {
   outpack_log(object, "debug", topic, detail, caller)
 }
 
 
-##' @export
-##' @rdname outpack_log
 outpack_log_trace <- function(object, topic, detail, caller) {
   outpack_log(object, "trace", topic, detail, caller)
 }
@@ -85,12 +79,12 @@ outpack_log_trace <- function(object, topic, detail, caller) {
 ##'
 ##' @param id The identifier of the packet to read logs for
 ##'
-##' @inheritParams outpack_search
+##' @inheritParams orderly_search
 ##'
 ##' @return A [data.frame] of log information
 ##'
 ##' @export
-outpack_log_read <- function(id, root = NULL) {
+orderly_log_read <- function(id, root = NULL) {
   root <- outpack_root_open(root, locate = TRUE)
   meta <- root$metadata(id)
   hash <- meta$files$hash[meta$files$path == "log.json"]

R/outpack_metadata.R

@@ -1,5 +1,5 @@
 ##' Read metadata for a particular id. You may want to use
-##' [orderly2::outpack_search] to find an id corresponding to a
+##' [orderly2::orderly_search] to find an id corresponding to a
 ##' particular query.
 ##'
 ##' @title Read outpack metadata
@@ -15,7 +15,7 @@
 ##'   (https://github.com/mrc-ide/outpack)
 ##'
 ##' @export
-outpack_metadata <- function(id, root = NULL) {
+orderly_metadata <- function(id, root = NULL) {
   validate_outpack_id(id)
   root <- outpack_root_open(root, locate = TRUE)
   root$metadata(id, full = TRUE)
@@ -26,8 +26,7 @@ outpack_metadata <- function(id, root = NULL) {
 ##' function can be used to directly read a metadata json file without
 ##' reference to a root which contains it. It may be useful in the
 ##' context of reading a metadata file written out as part of a failed
-##' run (see the `insert = FALSE` argument to
-##' [orderly2::outpack_packet_end()])
+##' run.
 ##'
 ##' @title Read outpack metadata json file
 ##'
@@ -39,7 +38,7 @@ outpack_metadata <- function(id, root = NULL) {
 ##'   scalar and length-one vectors into the expected types.
 ##'
 ##' @export
-outpack_metadata_read <- function(path) {
+orderly_metadata_read <- function(path) {
   assert_file_exists(path)
   outpack_metadata_load(path)
 }

R/outpack_misc.R

@@ -6,13 +6,6 @@ location_types <- c(local, orphan, "path", "http", "custom")
 re_id <- "^([0-9]{8}-[0-9]{6}-[[:xdigit:]]{8})$"
 
 
-##' Generate a new outpack id
-##'
-##' @title Generate outpack id
-##'
-##' @return A new outpack id (a string)
-##'
-##' @export
 outpack_id <- function() {
   time <- Sys.time()
   sprintf("%s-%s%s",