essentials: Essential Functions not Included in Base R

setReadWriteArgsMethod

R Documentation

Create a Method for Reading/Writing Command-Line Arguments from/to a File

Description

Create a method for reading/writing command-line arguments from/to a file, typically by differing file extension.

Usage

has.ext(file, fileext, compression = FALSE, fixed = FALSE,
    ignore.case = TRUE)

scan2(...)

format4scan(x, sep = " ", quote = "\"'", comment.char = "",
    allowEscapes = FALSE, nlines.between.comment.and.args = 0,
    nlines.between.args = 2)

setReadWriteArgsMethod(name, condition, read, write, sealed = FALSE)

Arguments

`file`	character vector, the files to test for a file extension.
`fileext`	character string, the file extension to be matched. Should contain a `regular expression` or character string for `fixed = TRUE`.
`compression`	logical. Should compressed files be included in the pattern matching?
`fixed`	logical. If `TRUE`, `pattern` is a string to be matched as is. Unlike `grep()`, `fixed = TRUE` and `ignore.case = TRUE` may be used together.
`ignore.case`	logical. Should the case of `file` be ignored when matching against `fileext`?
`...`	arguments passed to `scan`.
`sep`	Empty character string, `NULL`, or a character string containing just one single-byte character.
`quote`	Character string or `NULL`, the set of quoting characters.
`comment.char`	character string containing a single character or an empty string. Use `""` to turn off the adding comments.
`allowEscapes`	logical. Should C-style escapes be processed?
`x`	any R object. If a list, each element will be turned into a character vector (in the same way as `withArgs` converts its arguments), otherwise will be turned into a character vector (same as `withArgs`). The arguments to be written.
`nlines.between.comment.and.args`	a non-negative integer specifying the number of empty lines between each set of comments and arguments.
`nlines.between.args`	a non-negative integer specifying the number of empty lines between each set of arguments. Only used for a list `x`.
`name`	A character string naming the method.
`condition`	a function accepting a single argument `file` (the file in which to read/write). Should return `TRUE` if the file is appropriate for reading/writing with this method, typically by examining the file extension.
`read`	a function accepting a single argument `file`. Should read the arguments from `file`.
`write`	a function accepting arguments `x`, `comments`, `nlines.between.comment.and.args`, `nlines.between.args`. Should turn `x` into a character vector of arguments to write to a file. This function does NOT have to make use of the other arguments.
`sealed`	`sealed` prevents the method being redefined.

Examples

# suppose you wanted to define your own method for
# reading/writing command-line arguments to a file. we'll
# say the file extension will be ".myargs". with this, we
# start by making 'condition'
condition <- function(file) {
    essentials::has.ext(file, ".myargs",
        compression = TRUE, fixed = TRUE)
}


# next, we will make a reading function. this will typically
# be some variation of 'scan2', but feel free to use
# anything else that works. for this example, we'll use
# "-" as the delimiter, "`" as the quoting character, and
# "/" as the comment character
read <- function(file) {
    essentials::scan2(file = file, sep = "-",
        quote = "`", comment.char = "/")
}


# next, we will make a writing function. this will typically
# be some variation of 'format4scan', but feel free to use
# anything else that works
write <- function(x, comments = TRUE,
    nlines.between.comment.and.args = 0,
    nlines.between.args = 2) {
    essentials::format4scan(x, sep = "-", quote = "`",
        comment.char = if (comments) "/" else "",
        nlines.between.comment.and.args = nlines.between.comment.and.args,
        nlines.between.args = nlines.between.args)
}


# now, combine it all together
essentials::setReadWriteArgsMethod(
    name      = "myargs",
    condition = condition,
    read      = read,
    write     = write
)


# try writing arguments with this new format
x <- letters
comment(x) <- "testing comments"
essentials::writeArgs(x, "", name = "myargs")


# confirm that writing and reading returns the same set of
# arguments
FILE <- essentials::writeArgs(x, fileext = ".myargs", at = FALSE)
y <- essentials::readArgs(FILE)
stopifnot(length(x) == length(y), x == y)

ArcadeAntics/essentials documentation built on Nov. 7, 2024, 4:33 p.m.