map_files: Map files or file names
In pkgutils: Utilities for Creating R Packages

Description Usage Arguments Details Value See Also Examples

Read lines from a file, modify the lines using a given function, and write the lines back to the input file unless the result of applying the function is identical to the lines read. Alternatively, map (sets of) input file names to (sets of) output file names and check for duplicates.

  map_files(x, ...)

  ## S3 method for class 'character'
 map_files(x, mapfun, ...,
    .attr = ".filename", .encoding = "", .sep = NULL,
    .warn = FALSE)

  map_filenames(x, ...)

  ## S3 method for class 'character'
 map_filenames(x, out.ext,
    append = "", out.dir = ".", groups = 1L,
    assort = c("lst", "rlst", "ext", "rext", "grp", "rgrp"),
    normalize = TRUE, ...)

  clean_filenames(x, ...)

  ## S3 method for class 'character'
 clean_filenames(x,
    overwrite = FALSE, demo = FALSE,
    empty.tmpl = "__EMPTY__%05i__", ...)

`x`	Character vector of input (and potentially output) file names. Names of directories are not supported.
`mapfun`	Mapping function, receives character vector with the lines per file as first argument, with the name of the file added as attribute with the name given using `.attr`.
`...`	Optional additional arguments passed to `fun` (in the case of `map_files`) or between other methods.
`.attr`	Character scalar. See description to `mapfun`.
`.encoding`	Passed to `readLines` as ‘encoding’ argument.
`.sep`	`NULL` or character scalar. If empty, ignored. Otherwise used as output line separator, causing output files to always be written unless `mapfun` returns `NULL`. Can be used to just change line breaks if `mapfun` is `identity`.
`.warn`	Logical scalar passed as `warn` argument to `readLines`.
`out.ext`	Character vector with one to several output file extensions. Recycled if necessary.
`append`	Character vector appended after the base name of the input file name (separated from it with an underscore) but before the output file extension. Recycled if necessary but ignored where equal the empty string.
`out.dir`	Character vector with one to several names of output directories. Recycled if necessary.
`groups`	Integer scalar indicating the number of input file names to be assumed in one group. Used in conjunction with the next argument unless `groups` is negative. If so, `assort` is ignored and all pairs of names found in `x` are generated.
`assort`	Character scalar indicating how to assort input file names. lst All files of the first kind first, then all of the second kind, etc., sorted increasingly. rlst All files of the first kind first, then all of the second kind, etc., sorted decreasingly. ext Assort according to the file extensions, assume increasing order. rext Assort according to the file extensions, assume decreasing order. grp Assume one set of file after each other, each sorted increasingly. rgrp Assume one set of file after each other, each sorted decreasingly.
`normalize`	Logical scalar indicating whether `normalizePath` from the base package shall be applied. Eases the recognition of duplicate file names.
`overwrite`	Logical scalar. Overwrite already existing files, and do not care for duplicate names created by cleaning the file names?
`empty.tmpl`	Character scalar. The template to use for file names that become empty after cleaning. Should include an integer placeholder to enable incrementing an index for creating unique file names. (Empty file names should occur rarely anyway.)
`demo`	Logical scalar. For `clean_filenames`, `TRUE` means to not rename files but just return the usual result indicating the renaming actions that would be attempted? (Note that this does not indicate whether the renaming would also by successful.)

These function are mainly of use in non-interactive scripts.

If mapfun returns NULL, it is ignored by map_files. Otherwise is it an error if mapfun does not return a character vector. If this vector is identical to the lines read from the file, it is not printed to this file unless .sep is non-empty. Otherwise the file is attempted to be overwritten with the result of mapfun.

The purpose of map_filenames is to ease the generation of output file names from input file names and to assort these input file names. This in turn helps converting sets of input file names to sets of output file names.

map_files returns a logical vector using x as names, with TRUE indicating a successfully modified file, FALSE a file that yielded no errors but needed not to be modified, and NA a file name that caused an error. An attribute ‘errors’ is provided, containing a character vector with error messages (empty strings if no error occurred).

map_filenames returns a matrix of mode character. Each row contains a set of one to several input file names and its associated set of one to several output file names constructed from these input file names and the arguments out.ext, append and out.dir.

clean_filenames yields a character vector, its names corresponding to the renamed old files, values corresponding to the novel names, returned invisibly.

base::readLines base::writeLines base::identity

clean_filenames modifies file names by removing anything else then word characters, dashes, and dots. Also remove trailing and leading dashes and underscores (per part of a file name, with dots separating these parts) and reduce adjacent dashes and underscores to a single one. Note that directory parts within the file names, if any, are not affected.

Other character-functions: sections,

## map_files

tmpfile <- tempfile()
write(letters, file = tmpfile)
(x <- map_files(tmpfile, identity))
stopifnot(!x)
# now enforce other output line separator
(x <- map_files(tmpfile, identity, .sep = "\n"))
stopifnot(x)
(x <- map_files(tmpfile, toupper))
stopifnot(x)
x <- readLines(tmpfile)
stopifnot(x == LETTERS)
(x <- map_files(tmpfile, as.null))
stopifnot(!x)

## clean_filenames

# Example with temporary files
(x <- tempfile(pattern = "cb& ahi+ si--")) # bad file name
write("test", x)
stopifnot(file.exists(x))
(y <- clean_filenames(x)) # file renamed
stopifnot(!file.exists(x), file.exists(y))
unlink(y) # tidy up

## map_filenames
(x <- map_filenames(letters, out.ext = c("txt", "csv"),
  normalize = FALSE))
stopifnot(is.matrix(x), dim(x) == c(26, 3))
(x <- map_filenames(letters, out.ext = c("txt", "csv"),
  out.dir = LETTERS, normalize = FALSE))
stopifnot(is.matrix(x), dim(x) == c(26, 3))

# Several sets of input files
infiles <- paste0(letters, c(".txt", ".csv"))
(x <- map_filenames(infiles, "tmp", normalize = FALSE,
  groups = 2, assort = "ext"))
stopifnot(is.matrix(x), dim(x) == c(13, 3), grepl("csv", x[, 1]),
  grepl("txt", x[, 2]))