Utilities for managing file names.

Description

filenamer provides a S3 class to represent file names, which is inter-convertible with character.

Details

Users either construct a filename object with the filename constructor or convert an existing file name from character to filename using as.filename. Then, users can manage the tags and extensions of the filename object with insert.

The functions set_fpath, set_fext, set_fdate, and set_ftime can be used on both character or filename to modify file names.

Use tag to quickly add or replace a tag on a file name (as a character or filename and coerce into a character.

See Also

Useful links:

• https://bitbucket.org/djhshih/filenamer

• Report bugs at https://bitbucket.org/djhshih/filenamer/issues

Coerce a character to a filename

Description

This function coerces a filename into a character.

Usage

## S3 method for class 'filename'
as.character(x, tag.char = NULL, simplify = FALSE, sanitize = TRUE, ...)

Arguments

Value

a character vector

Examples

x <- "data_post_2011-01-02.txt"
fn <- as.filename(x)
print(as.character(fn))

Coerce to a filename

Description

This function coerces an object into a filename, if possible.

Usage

as.filename(x, ...)

## S3 method for class 'filename'
as.filename(x, ...)

## S3 method for class 'character'
as.filename(x, tag.char = NULL, ...)

Arguments

Value

a filename object

Examples

fn <- as.filename("data_raw_2011-01-01.txt")
str(fn)

Create a filename.

Description

This function creates a filename object with a file path, tags, extensions, date stamp or date-time stamp.

Usage

filename(
  x,
  path = NULL,
  tag = NULL,
  ext = NULL,
  date = NULL,
  time = NULL,
  subdir = TRUE
)

Arguments

Details

The date and time parameters can be specified as character vectors or date/time objects. If time is given as a POSIXct, it will override date. If these parameters are both NULL, automated date and time stamping may be done and is controlled by getOption("filenamer.timestamp"). If this option is NULL, 0, or less, no date or time stamping will be done; if it is 1, only date stamping will be done; if it is 2 or greater, date-time stamping will be done (default). Set date or time to NA to suppress date or time stamping for a particular filename. Stamps are shown in ISO 8601 date format ( ( platforms and are thus omitted; hyphens are omitted from date-time stamps for brevity.

By default, a date stamped subdirectory is appended to the file path. To disable this behaviour, set subdir to FALSE or disable path stamping globally by options(filenamer.path.timestamp = 0). This option is similar to filenamer.timestamp above.

Value

a filename object

Examples

# file name is date-time stamped and put in subdirectory by default
fn <- filename("data", tag="qc", ext="txt")
print(as.character(fn))

# disable date-time stamping and subdirectory insertion
fn2 <- filename("data", tag="qc", date=NA, time=NA, subdir=FALSE)
print(as.character(fn2))

# creating a new file name from an existing one yields a new time stamp
fn3 <- filename(fn)
print(as.character(fn3))

Insert tag or extension into a file name

Description

This function inserts a tag or extension into a file name. It can also replace an element of a file name.

Usage

insert(x, ...)

## S3 method for class 'filename'
insert(
  x,
  tag = NULL,
  tag.pos = NULL,
  ext = NULL,
  ext.pos = NULL,
  replace = FALSE,
  ...
)

## S3 method for class 'character'
insert(x, ...)

Arguments

Details

By default, tags are inserted at the ultimate position and extensions at the penultimate position, if possible. (That is, the final file extension will not change, unless the insertion position is specified otherwise or the original file name had no extension.) If replace is TRUE, the tag at the indicated position is replaced by the new tag instead.

Value

modified object of the original type

Examples

f <- as.filename("data_expr_2014-05-01.tsv")

# new file name with inserted tags for saving normalized data
g <- insert(f, tag=c("mod", "norm"))
print(as.character(g))

# new file name with inserted extension for saving sorted data
h <- insert(f, ext="sorted")
print(as.character(h))

# new file name with different extension for saving in different format
i <- insert(f, ext="csv", replace=TRUE)
print(as.character(i))

# insert another tag
j <- insert(g, tag="qc", tag.pos=2)
print(as.character(j))

Type checking for filename

Description

This function returns TRUE if its argument is a filename and FALSE otherwise.

Usage

is.filename(x)

Arguments

Value

a logical value

Create directory structure for a file path

Description

This function creates directories recursively (as necessary) to the specified file.

Usage

make_path(x, ...)

## S3 method for class 'filename'
make_path(x, showWarnings = FALSE, recursive = TRUE, ...)

## S3 method for class 'character'
make_path(x, ...)

Arguments

Examples

## Not run: 
# CRAN policy forbids package example to write to current directory,
# even inside \dontrun because the user may copy-and-paste and 
# polute his/her current directory;
# in real-world setting, the `tempdir` path prefix is unnecessary
x <- file.path(tempdir(), "path/to/file.txt")

fn <- as.filename(x)
make_path(fn)

## End(Not run)

Set date stamp in a file name

Description

This function sets the date stamp in a file name.

Usage

set_fdate(x, date)

Arguments

Value

modified object of the original type

Examples

x <- "data_norm_2011-01-03.txt"
print(set_fdate(x, "2011-01-05"))

Set file extension

Description

This function sets the extension in a file name.

Usage

set_fext(x, ext, all)

Arguments

Value

modified object of the original type

Examples

x <- "data_norm_2011-01-03.txt"
print(set_fext(x, "csv"))

Set path in a file name

Description

This function sets the path in a file name.

Usage

set_fpath(x, path)

Arguments

Value

modified object of the original type

Examples

x <- "path/data_norm.txt"
print(set_fpath(x, "new_path"))

Set time stamp in a file name

Description

This function sets the time stamp in a file name.

Usage

set_ftime(x, time)

Arguments

Value

modified object of the original type

Examples

x <- "data_norm_20110103T093015.txt"
# change the time to 30 seconds past 2:45 p.m. 
print(set_ftime(x, "144530"))
# to change the date, time must be specified as well
print(set_ftime(x, "20110505T101500"))

Insert tag or extension and coerce to character

Description

This function inserts a tag or extension into a file name and returns a charcter vector.

Usage

tag(x, ...)

Arguments

Value

a character vector

Examples

x <- "data.txt"
y <- tag(x, "qc")
print(y)
f <- as.filename(x)
g <- tag(f, "qc")
print(g)

Trim extensions from a file name

Description

This function trims extensions from a file name.

Usage

trim_ext(x, n)

Arguments

Value

modified object of the original type

Examples

x <- "path/data.txt.gz"
print(trim_ext(x))