copySubstitute            package:Biobase            R Documentation

Copy Between Connections or Files with Configure-Like Name-Value Substitution

Description:

     Copy files, directory trees or between connections and replace all
     occurences of a symbol by the corresponding value.

Usage:

     copySubstitute(src, dest, symbolValues, symbolDelimiter="@", allowUnresolvedSymbols=FALSE, recursive = FALSE, removeExtension = "\\.in$")

Arguments:

     src: Source, either a character vector with filenames and/or
          directory names, or a connection object.

    dest: Destination, either a character vector of length 1 with the
          name of an existing, writable directory, or a connection
          object. The class of the 'dest' argument must match that of
          the 'src' argument.

symbolValues: A named list of character strings.

symbolDelimiter: A character string of length one with a single
          character in it.

allowUnresolvedSymbols: Logical. If 'FALSE', then the function will
          execute 'stop' if it comes across symbols that are not
          defined in 'symbolValues'.

recursive: Logical. If 'TRUE', the function works recursively down a
          directory tree (see details).

removeExtension: Character. Matches to this regular expression are
          removed from filenames and directory names.

Details:

     Symbol substitution: this is best explained with an example. If
     the list 'symbolValues' contains an element with name 'FOO' and
     value 'bar', and symbolDelimiter is '@', then any occurrence of
     '@FOO@' is replaced by 'bar'. This applies both the text contents
     of the files in 'src' as well as to the filenames. See examples.

     If 'recursive' is 'FALSE', both 'src' and 'dest' must be
     connection or a filenames. The text in 'src' is read through the
     function 'readLines', symbols are replaced by their values, and
     the result is written to 'dest' through the function 'writeLines'.

     If 'recursive' is 'TRUE', 'copySubstitute' works recursively down
     a directory tree (see details and example). 'src' must be a
     character vector with multiple filenames or directory names,
     'dest' a directory name.

     One use of this function is in 'createPackage' for the automatic
     generation of packages from a template package directory.

Value:

     None. The function is called for its side effect.

Author(s):

     Wolfgang Huber <URL: http://www.dkfz.de/mga/whuber>

Examples:

     ## create an example file
     infile  = tempfile()
     outfile = tempfile()

     writeLines(text=c("We will perform in @WHAT@:",
       "So, thanks to @WHOM@ at once and to each one,",
       "Whom we invite to see us crown'd at @WHERE@."),
       con = infile)

     ## create the symbol table
     z = list(WHAT="measure, time and place", WHOM="all", WHERE="Scone")

     ## run copySubstitute
     copySubstitute(infile, outfile, z)

     ## display the results
     readLines(outfile)


     ##--------------------------------------------------------------
     ## This is a slightly more complicated example that demonstrates
     ## how copySubstitute works on nested directories
     ##--------------------------------------------------------------
     d = tempdir()
     my.dir.create = function(x) {dir.create(x); return(x)}

     unlink(file.path(d, "src"), recursive=TRUE)
     unlink(file.path(d, "dest"), recursive=TRUE)

     ## create some directories and files:
     src  = my.dir.create(file.path(d, "src"))
     dest = file.path(d, "dest")
     d1   = my.dir.create(file.path(src, "dir1.in"))
     d2   = my.dir.create(file.path(src, "dir2@FOO@.in"))
     d3   = my.dir.create(file.path(d2, "dir3"))
     d4   = my.dir.create(file.path(d3, "dir4"))
     d5   = my.dir.create(file.path(d4, "dir5@BAR@"))
     writeLines(c("File1:", "FOO: @FOO@"),     file.path(d1, "file1.txt.in"))
     writeLines(c("File2:", "BAR: @BAR@"),     file.path(d2, "file2.txt.in"))
     writeLines(c("File3:", "SUN: @SUN@"),     file.path(d3, "file3.txt.in"))
     writeLines(c("File4:", "MOON: @MOON@"),   file.path(d4, "@SUN@.txt"))

     ## call copySubstitute
     copySubstitute(src, dest, recursive=TRUE,
                    symbolValues = list(FOO="thefoo", BAR="thebar",
                                        SUN="thesun", MOON="themoon"))

     ## view the result
     listsrc  = dir(src,  full.names=TRUE, recursive=TRUE)
     listdest = dir(dest, full.names=TRUE, recursive=TRUE)
     listsrc
     listdest

     cat(unlist(lapply(listsrc,  readLines)), sep="\n")
     cat(unlist(lapply(listdest, readLines)), sep="\n")

