sanitize: Create portable file or directory names

In pfn: Create Portable File Names

Description

Rename files or directories to generate portable names. Names of directories passed to this function cause them to be traversed recursively.

Usage

  sanitize(paths = getwd(), lower = FALSE,
    directories = TRUE, enforce = 0L)

Arguments

paths	Either character vector with names of files or directories, or data frame as generate by a previous call of this function.
lower	Logical vector of length 1 that indicates whether file and directory names should also be converted to lowercase characters. Has only an effect if paths is a character vector. If TRUE, this causes all file names to be assessed and runs of underscores, dots or hyphens in all file names be replaced by a single such character. If FALSE, file names that contain only portable characters will be skipped.
directories	Logical vector of length 1 that indicates whether directory names should also be modified when not portable. Has only an effect if paths is a character vector. If FALSE, only files are checked and potentially renamed. Directories, if any, are nevertheless traversed recursively.
enforce	Numeric vector of length 1 that indicates under which circumstances renaming of files should be attempted. Has only an effect if paths is a data frame. Possible values are: -1 Do not rename anything, only conduct the checks. 0 Rename files unless the target is duplicated in the ‘To’ column of the paths data frame or already exists in the file system. 1 Rename files; overwrite existing files, if any, but take care of duplicates in the ‘To’ column of the paths data frame. That is, do not rename files if the target occurs a second time. 2 Rename files; overwrite existing files and overwrite duplicates in the ‘To’ column of the paths data frame, if any. This may cause loss of data and should only be applied if the lost files are superfluous.

Details

When applied to a vector of path names this function does not actually rename anything but generates a data frame that indicates which files or directories should be renamed to what. This data frame can be inspected by the user prior to doing anything dangerous. Rows can be removed or set to a non-empty value in the ‘Problem’ column, which will cause them to be skipped when passed to the function again. Sorting the data frame in a different way is strongly discouraged, however.

When applied to a data frame as generated by a previous call of this function, it will conduct the renaming of files and directories as proposed in this data frame, subject to the conditions controlled by the enforce argument. The returned data frame will indicate in the ‘Problem’ column whether renaming was attempted and, if so, whether it was successful.

Here ‘Portable Filename’ is used as defined by the Open Group (see ‘References’ section), i.e. only ASCII letters, numbers, period, hyphen-minus and underscore are permitted. To create portable but reasonably informative names, an attempt is made to replace non-Latin characters by their Latin counterparts and these by their ASCII counterparts. Some modifications from the sanity.pl script (see ‘References’ section) are also applied. All remaining special characters get removed by underscores. For further details see the code.

Value

Data frame with three columns ‘From’, ‘To’ and ‘Problem’, which contain character vectors.

Note

Renaming files or directories may fail for various reasons. See the documentation of file.rename for details.

Author(s)

Markus Goeker, with contributions by Heike Freese and Johannes Sikorski

References

http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html

https://en.wikipedia.org/wiki/ASCII

https://github.com/splitbrain/sanity/blob/master/sanity.pl

See Also

base::file.rename

Examples

## call 1: generate data frame but never rename
tasks <- sanitize()
head(tasks) # it may well be that nothing was found

## call 2: use data frame for renaming (if enforce >= 0)
result <- sanitize(paths = tasks, enforce = -1)
head(result) # additional problems may now be listed

## Not run: 

  ## immediately rename a single file
  sanitize(sanitize("mydir/file with spaces.txt"))

  ## immediately rename two entire directories
  sanitize(sanitize(c("ugly directory", "../bad folder")))

## End(Not run)

pfn documentation built on May 2, 2019, 4:59 p.m.