linkTo: Create a symbolic link to a repository element.
In jefferys/DataRepo: Manage a large data file repository

Description Usage Arguments Value

Creates a symbolic link pointing to a target in the repository. The target must exist, and if any validation information is included, the target must match. What to do if the link to be created has the same name as an existing file system object depends on duplicateOk and onExists. By default failure will be returned unless the file system object is already a link to the target, or if it is an exact copy of the duplicate. Successful linking is reported as a vector of empty strings. Problems are reported with one or more non-empty elements.

1
2
3

linkTo(file, repo = getwd(), entry = NULL, asFile = basename(file),
  fileSize = NULL, checksum = NULL, checksumFunc = "tools::md5sum",
  onExists = "error", duplicateOk = TRUE)

`file`	The symbolic link to create. Assuming all optional elements are specified, the target of this link in the repository will be `<repo>\<entry>\<asFile>`. If a file object matching the link name already exists, `duplicateOk` and `onExists` control what happens.
`repo`	The base directory for the file to be linked to. By default will use the current directory if not specified.
`entry`	A subdirectory or subdirectory tree in the repo where the target file is expected to be found. By default this is NULL, indicating the root `repo` directory is used.
`asFile`	The base name of the target file in the repository. By default this is the base name of `file`. This target file must exist and be a real file, not a link.
`fileSize`	The expected size of the target file, in bytes. By default this is `NULL`, meaning file size will not be checked. If a positive value is supplied it will be checked against the size of the source file on the file system. If it does not match then failure is reported and the checksum is not checked.
`checksum`	The expected checksum of the target file. By default this is `NULL`, meaning no checksum is generated. If given it will be checked agains the value provided by the `checksumFunc`.
`checksumFunc`	The function or function name (as a string) that will be used when calculating checksums. The calculated target file checksum will be verified against any provided checksums before linking, and this may also be used if `onExists` requires it. String function names may be qualified with a `SomePackage::` prefix as the function named is retrieved using `getSomewhere`. By default the function used is '`'tools::md5sum'`. The specified function should have one parameter, a file path. The returned checksum value should be an (atomic) vector type but can not be `NULL` or a missing value. When `checksumFunc` is called, `path` has already been verified and is known to exist on the file system as a real file (not a directory or link).
`onExists`	What to do if the link name already exists on the file system. May not be applied if the existing file is a duplicate of the target, as defined by `duplicateOk`. `itemized` `item"error"` - Return failure result. `item"replaceFile"` - Delete existing file and replace with link. Generates a warning. If this is a link or a directory, this will fail with error. `item"replaceAny"` - Delete existing file system entry and replace with a link. Deletes recursively if the existing object is a directory. You probably don't want to do this. Generates a warning. `item"backupFile"` - Renames an existing file adding `.bak`, generating a warning. Multiple `.bak` may be added if needed to create unique filenames. Replaces the original with the link. If the original was a directory or a link, returns with error status. `item"backupAny"` - Renames the existing file system entry adding `.bak`, generating a warning. Multiple `.bak` may be added if needed to create unique filenames. Replaces the original with the link. This is done even if the original was a directory or a link. `item"skip"` - Leave as is. Generates a warning.
`duplicateOk`	By default `onExists` applies only if the file exists and is not a duplicate. Set `FALSE` if `onExists` should always be applied. Duplicate means is a real file and matches the target by size and checksum, or is a link to the target. Links to an identical file that is not in the repository is not a duplicate. Real duplicate files will be deleted and replaced with links. If the existing file is a links to the target, nothing needs to be done.

A named vector of validation results. Each element is named for a check performed, and will be the empty string if the check succeeded, a failure string if the check failed, and a missing value if the check was not performed (i.e. was not wanted or previous checks failed making further checking irrelevant.) Can be summarized with checkSummary. The elements are named 'checkParam_file', 'checkParam_repo', 'checkParam_entry', 'checkParam_asFile', 'checkParam_checksumFunc', 'checkParam_onExists', 'checkParam_duplicateOk', 'checkTarget', 'checkExists', 'createLink', 'unexpectedError', in order.

jefferys/DataRepo documentation built on May 19, 2019, 3:58 a.m.