Copy files from a packet — orderly_copy

Copy files from a packet to anywhere. Similar to 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. Note that all arguments need must be provided by name, not position, with the exception of the id or query.

Usage

orderly_copy_files(
  ...,
  files,
  dest,
  overwrite = TRUE,
  envir = parent.frame(),
  options = NULL,
  root = NULL,
  locate = TRUE
)

Arguments

...

Arguments passed through to orderly_query, perhaps just a query expression

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}.

dest

The directory to copy into

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.

envir

Optionally, an environment to substitute into the query (using the environment: prefix). The default here is to use the calling environment, but you can explicitly pass this in if you want to control where this lookup happens.

options

Optionally, a orderly_search_options object for controlling how the search is performed, and which packets should be considered in scope. If not provided, default options are used (i.e., orderly2::orderly_search_options())

root

The path to the root directory, or NULL (the default) to search for one from the current working directory if locate is TRUE. This function does not require that the directory is configured for orderly, and can be any outpack root (see orderly_init for details).

locate

Logical, indicating if the root should be searched for. If TRUE, then we looks in the directory given for root (or the working directory if NULL) and then up through its parents until it finds an .outpack directory or orderly_config.yml

Value

Nothing, invisibly. Primarily called for its side effect of copying files from a packet into the directory dest

Details

You can call this function with an id as a string, in which case we do not search for the packet and proceed regardless of whether or not this id is present. If called with any other arguments (e.g., a string that does not match the id format, or a named argument name, subquery or parameters) then we interpret the arguments as a query and orderly_search to find the id. It is an error if this query does not return exactly one packet id, so you probably want to use latest().

There are different ways that this might fail (or recover from failure):

if id is not known in the metadata store (not known because it's not unpacked but also not known to be present in some other remote) then this will fail because it's impossible to resolve the files. Consider refreshing the metadata with orderly_location_pull_metadata to refresh this.
if the id is not unpacked and no local copy of the files referred to can be found, we error by default (but see the next option). However, sometimes the file you refer to might also be present because you have downloaded a packet that depended on it, or because the content of the file is unchanged because from some other packet version you have locally.
if the id is not unpacked, there is no local copy of the file and if allow_remote is TRUE we will try and request the file from whatever remote would be selected by orderly_location_pull_packet for this packet.

Note that empty directories might be created on failure.