Package R.utils

Description

Utility functions useful when programming and developing R packages.

Warning: The Application Programming Interface (API) of the classes and methods in this package may change. Classes and methods are considered either to be stable, or to be in beta or alpha (pre-beta) stage. See list below for details.

The main reason for publishing this package on CRAN although it lacks a stable API, is that its methods and classes are used internally by other packages on CRAN that the author has published.

For package history, see showHistory(R.utils).

Requirements

This package requires the R.oo package [1].

Installation and updates

To install this package do:

install.packages("R.utils")

To get started

Arguments

[alpha] Methods for common argument processing.

Assert

[alpha] Methods for assertion of values and states.

GString

[alpha] A character string class with methods for simple substitution.

Java

[beta] Reads and writes Java streams.

Options

[alpha] Tree-structured options queried in a file-system like manner.

Settings

[alpha] An Options class for reading and writing package settings.

ProgressBar

[beta] Text-based progress bar.

FileProgressBar

[beta] A ProgressBar that reports progress as file size.

System

[alpha] Methods for access to system.

Verbose

[alpha] A class for verbose and log output. Utilized by the VComments and LComments classes.

SmartComments, VComments, LComments

[alpha] Methods for preprocessing source code comments of certain formats into R code.

In addition to the above, there is a large set of function for file handling such as support for reading/following Windows Shortcut links, but also other standalone utility functions. See package index for a list of these. These should also be considered to be in alpha or beta stage.

How to cite this package

Whenever using this package, please cite [1] as

Bengtsson, H. The R.oo package - Object-Oriented Programming with References Using
Standard R Code, Proceedings of the 3rd International Workshop on Distributed
Statistical Computing (DSC 2003), ISSN 1609-395X, Hornik, K.; Leisch, F. & Zeileis,
A. (ed.), 2003

Wishlist

Here is a list of features that would be useful, but which I have too little time to add myself. Contributions are appreciated.

• Write a TclTkProgressBar class.

• Improve/stabilize the GString class.

• Mature the SmartComments classes. Also add AComments and PComments for assertion and progress/status comments.

If you consider implement some of the above, make sure it is not already implemented by downloading the latest "devel" version!

License

The releases of this package is licensed under LGPL version 2.1 or newer.

The development code of the packages is under a private licence (where applicable) and patches sent to the author fall under the latter license, but will be, if incorporated, released under the "release" license above.

References

[1] H. Bengtsson, The R.oo package - Object-Oriented Programming with References Using Standard R Code, In Kurt Hornik, Friedrich Leisch and Achim Zeileis, editors, Proceedings of the 3rd International Workshop on Distributed Statistical Computing (DSC 2003), March 20-22, Vienna, Austria. https://www.r-project.org/conferences/DSC-2003/Proceedings/

Author(s)

Henrik Bengtsson

Undo changed done by this package when detached

Description

Undo changed done by this package when detached. Reverts .Last() to the function that existed before this package was attached.

Usage

.Last.lib(libpath)

Arguments

Value

Returns nothing.

Author(s)

Henrik Bengtsson

Static class to validate and process arguments

Description

Package: R.utils
Class Arguments

Object
~~|
~~+--Arguments

Directly known subclasses:

public static class Arguments
extends Object

Fields and Methods

Methods:

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, save

Author(s)

Henrik Bengtsson

Coerces to a character vector and validates

Description

Coerces to a character vector and validates.

Usage

## Static method (use this):
## Arguments$getCharacters(s, length=NULL, trim=FALSE, nchar=NULL, useNames=TRUE,
##   asGString=getOption("Arguments$getCharacters/args/asGString", TRUE), .name=NULL,
##   ...)

## Don't use the below:
## S3 method for class 'Arguments'
getCharacters(static, s, length=NULL, trim=FALSE, nchar=NULL, useNames=TRUE,
  asGString=getOption("Arguments$getCharacters/args/asGString", TRUE), .name=NULL, ...)

Arguments

Value

Returns a character vector, if it is valid. Otherwise an exception is thrown.

Missing values

If s contains missing values, and nchar is not NULL, then an exception is thrown.

Author(s)

Henrik Bengtsson

See Also

For more information see Arguments.

Coerces to a double vector and validates

Description

Coerces to a double vector and validates.

Usage

## Static method (use this):
## Arguments$getDoubles(..., disallow=c("NA", "NaN"))

## Don't use the below:
## S3 method for class 'Arguments'
getDoubles(static, ..., disallow=c("NA", "NaN"))

Arguments

Value

Returns a double vector.

Author(s)

Henrik Bengtsson

See Also

For more information see Arguments.

Gets an existing environment

Description

Gets an existing environment.

Usage

## Static method (use this):
## Arguments$getEnvironment(envir=NULL, .name=NULL, ...)

## Don't use the below:
## S3 method for class 'Arguments'
getEnvironment(static, envir=NULL, .name=NULL, ...)

Arguments

Value

Returns an environment.

Author(s)

Henrik Bengtsson

See Also

For more information see Arguments.

Gets and validates a filename

Description

Gets and validates a filename.

Usage

## Static method (use this):
## Arguments$getFilename(filename, nchar=c(1, 128), class=c("safe"), .name=NULL,
##   .type="filename", ...)

## Don't use the below:
## S3 method for class 'Arguments'
getFilename(static, filename, nchar=c(1, 128), class=c("safe"), .name=NULL,
  .type="filename", ...)

Arguments

Details

When argument class="safe", the following 86 ASCII characters are allowed in filenames:

     #$
    @ABCDEFGHIJKLMNOPQRSTUVWXYZ[]^_  (31)
    `abcdefghijklmnopqrstuvwxyz{|}~  (31)
  

This class of filenames has been extensively tested on for cross-platform support on Microsoft Windows, macOS, and various Unix flavors.

Value

Returns a character string if filename is valid, otherwise an exception is thrown.

Missing values

If filename is a missing value, then an exception is thrown.

Author(s)

Henrik Bengtsson

References

[1] Microsoft, Naming Files, Paths, and Namespaces, 2018. https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file.

See Also

For more information see Arguments.

Coerces to a integer vector and validates

Description

Coerces to a integer vector and validates.

Usage

## Static method (use this):
## Arguments$getIndices(x, ..., max=Inf, range=c(1 * (max > 0L), max), .name=NULL)

## Don't use the below:
## S3 method for class 'Arguments'
getIndices(static, x, ..., max=Inf, range=c(1 * (max > 0L), max), .name=NULL)

Arguments

Value

Returns an integer vector.

Author(s)

Henrik Bengtsson

See Also

For more information see Arguments.

Gets an instance of the object that is of a particular class

Description

Gets an instance of the object that is of a particular class.

Usage

## Static method (use this):
## Arguments$getInstanceOf(object, class, coerce=FALSE, ..., .name=NULL)

## Don't use the below:
## S3 method for class 'Arguments'
getInstanceOf(static, object, class, coerce=FALSE, ..., .name=NULL)

Arguments

Value

Returns an object inheriting from class class.

Author(s)

Henrik Bengtsson

See Also

For more information see Arguments.

Coerces to a integer vector and validates

Description

Coerces to a integer vector and validates.

Usage

## Static method (use this):
## Arguments$getIntegers(..., disallow=c("NA", "NaN"))

## Don't use the below:
## S3 method for class 'Arguments'
getIntegers(static, ..., disallow=c("NA", "NaN"))

Arguments

Value

Returns a integer vector.

Author(s)

Henrik Bengtsson

See Also

For more information see Arguments.

Coerces to a logical vector and validates

Description

Coerces to a logical vector and validates.

Usage

## Static method (use this):
## Arguments$getLogicals(x, ..., disallow=c("NA", "NaN"), coerce=FALSE, .name=NULL)

## Don't use the below:
## S3 method for class 'Arguments'
getLogicals(static, x, ..., disallow=c("NA", "NaN"), coerce=FALSE, .name=NULL)

Arguments

Value

Returns a numeric vector.

Author(s)

Henrik Bengtsson

See Also

For more information see Arguments.

Coerces to a numeric vector and validates

Description

Coerces to a numeric vector and validates.

Usage

## Static method (use this):
## Arguments$getNumerics(x, range=NULL, asMode=NULL, disallow=NULL, ..., .name=NULL)

## Don't use the below:
## S3 method for class 'Arguments'
getNumerics(static, x, range=NULL, asMode=NULL, disallow=NULL, ..., .name=NULL)

Arguments

Value

Returns a numeric vector.

Author(s)

Henrik Bengtsson

See Also

For more information see Arguments.

Gets a readable pathname

Description

Gets a readable pathname.

Usage

## Static method (use this):
## Arguments$getReadablePathname(file=NULL, path=NULL, mustExist=TRUE, absolute=FALSE,
##   adjust=c("none", "url"), ...)

## Don't use the below:
## S3 method for class 'Arguments'
getReadablePathname(static, file=NULL, path=NULL, mustExist=TRUE, absolute=FALSE,
  adjust=c("none", "url"), ...)

Arguments

Value

Returns a character string of the absolute pathname of the file.

Missing values

If file or path is NA and mustExist is FALSE, then (character) NA is returned, otherwise an exception is thrown.

Windows

If a too long pathname is detected on Windows, an informative warning is given. The maximum number of symbols in a Windows pathname is 256, including file separators '/' or '\', but excluding the drive letter, and initial file separator (e.g. 'C:/'), and the string terminator ('\0'), cf. 'MSDN - Naming a File or Directory', Microsoft. In R, the limit is one symbol less, i.e. 255.

Author(s)

Henrik Bengtsson

See Also

*getWritablePathname() filePath. For more information see Arguments.

Gets a readable pathname

Description

Gets a readable pathname.

Usage

## Static method (use this):
## Arguments$getReadablePathnames(files=NULL, paths=NULL, ...)

## Don't use the below:
## S3 method for class 'Arguments'
getReadablePathnames(static, files=NULL, paths=NULL, ...)

Arguments

Value

Returns a character vector of the pathnames for the files.

Author(s)

Henrik Bengtsson

See Also

*getReadablePathname() filePath. For more information see Arguments.

Gets a valid regular expression pattern

Description

Gets a valid regular expression pattern.

Usage

## Static method (use this):
## Arguments$getRegularExpression(pattern=NULL, ..., .name=NULL)

## Don't use the below:
## S3 method for class 'Arguments'
getRegularExpression(static, pattern=NULL, ..., .name=NULL)

Arguments

Value

Returns a character string.

Author(s)

Henrik Bengtsson

See Also

grep(). For more information see Arguments.

Validates a vector

Description

Validates a vector by checking its length (number of elements).

Usage

## Static method (use this):
## Arguments$getVector(x, length=NULL, .name=NULL, ...)

## Don't use the below:
## S3 method for class 'Arguments'
getVector(static, x, length=NULL, .name=NULL, ...)

Arguments

Value

Returns the same vector, if it is valid. Otherwise an exception is thrown.

Author(s)

Henrik Bengtsson

See Also

For more information see Arguments.

Coerces to Verbose object

Description

Coerces to Verbose object.

Usage

## Static method (use this):
## Arguments$getVerbose(verbose, defaultThreshold=-1, useNullVerbose=TRUE, ...,
##   .name=NULL)

## Don't use the below:
## S3 method for class 'Arguments'
getVerbose(static, verbose, defaultThreshold=-1, useNullVerbose=TRUE, ..., .name=NULL)

Arguments

Value

Returns a Verbose (or a NullVerbose) object.

Author(s)

Henrik Bengtsson

See Also

For more information see Arguments.

Gets a writable pathname

Description

Gets a writable pathname.

Usage

## Static method (use this):
## Arguments$getWritablePathname(..., mustExist=FALSE, mustNotExist=FALSE, mkdirs=TRUE,
##   maxTries=5L)

## Don't use the below:
## S3 method for class 'Arguments'
getWritablePathname(static, ..., mustExist=FALSE, mustNotExist=FALSE, mkdirs=TRUE,
  maxTries=5L)

Arguments

Value

Returns a character string of the pathname of the file. If the argument was invalid an Exception is thrown.

Missing values

If any argument in ... is NA, an exception is thrown.

Author(s)

Henrik Bengtsson

See Also

*getReadablePathname(). filePath. mkdirs. For more information see Arguments.

The Assert class

Description

Package: R.utils
Class Assert

Object
~~|
~~+--Assert

Directly known subclasses:

public static class Assert
extends Object

Usage

Assert(...)

Arguments

Fields and Methods

Methods:

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, save

Author(s)

Henrik Bengtsson

Static method asserting that a generic condition is true

Description

Static method asserting that a generic condition is true.

Usage

## Static method (use this):
## Assert$check(condition, message=NULL, ...)

## Don't use the below:
## S3 method for class 'Assert'
check(static, condition, message=NULL, ...)

Arguments

Value

Returns (invisibly) TRUE, or throws an exception.

Author(s)

Henrik Bengtsson

See Also

For more information see Assert.

Static method asserting that an object inherits from of a certain class

Description

Static method asserting that an object inherits from of a certain class.

Usage

## Static method (use this):
## Assert$inheritsFrom(object, class, ...)

## Don't use the below:
## S3 method for class 'Assert'
inheritsFrom(static, object, class, ...)

Arguments

Value

Returns (invisibly) TRUE, or throws an exception.

Author(s)

Henrik Bengtsson

See Also

For more information see Assert.

Static method asserting that an object is a matrix

Description

Static method asserting that an object is a matrix.

Usage

## Static method (use this):
## Assert$isMatrix(x, nrow=NULL, ncol=NULL, ...)

## Don't use the below:
## S3 method for class 'Assert'
isMatrix(static, x, nrow=NULL, ncol=NULL, ...)

Arguments

Value

Returns (invisibly) TRUE, or throws an exception.

Author(s)

Henrik Bengtsson

See Also

For more information see Assert.

Static method asserting that an object is a single value

Description

Static method asserting that an object is a single value.

Usage

## Static method (use this):
## Assert$isScalar(x, ...)

## Don't use the below:
## S3 method for class 'Assert'
isScalar(static, x, ...)

Arguments

Value

Returns (invisibly) TRUE, or throws an exception.

Author(s)

Henrik Bengtsson

See Also

For more information see Assert.

Static method asserting that an object is a vector

Description

Static method asserting that an object is a vector.

Usage

## Static method (use this):
## Assert$isVector(x, length=NULL, ...)

## Don't use the below:
## S3 method for class 'Assert'
isVector(static, x, length=NULL, ...)

Arguments

Value

Returns (invisibly) TRUE, or throws an exception.

Author(s)

Henrik Bengtsson

See Also

For more information see Assert.

A progress bar that sets the size of a file accordingly

Description

Package: R.utils
Class FileProgressBar

Object
~~|
~~+--ProgressBar
~~~~~~~|
~~~~~~~+--FileProgressBar

Directly known subclasses:

public static class FileProgressBar
extends ProgressBar

Usage

FileProgressBar(pathname=NULL, ...)

Arguments

Details

A progress bar that sets the size of a file accordingly. This class useful to check the progress of a batch job by just querying the size of a file, for instance, via ftp.

Fields and Methods

Methods:

Methods inherited from ProgressBar:
as.character, getBarString, increase, isDone, reset, setMaxValue, setProgress, setStepLength, setTicks, setValue, update

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, save

Author(s)

Henrik Bengtsson

Examples

  ## Not run: 
  
# Creates a progress bar (of length 100) that displays it self as a file.

pb <- FileProgressBar(file.path(tempdir(), "progress.simulation"), max = 10L)
reset(pb)
while (!isDone(pb)) {
  x <- rnorm(3e4)
  increase(pb)
  # Emulate a slow process
  if (interactive()) Sys.sleep(0.1)
  cat(sprintf("File size: %d bytes\n", file.info(pb$pathname)$size))
  Sys.sleep(0.01)
}

  
## End(Not run)
 

Character string with advanced substitutions

Description

Package: R.utils
Class GString

character
~~|
~~+--GString

Directly known subclasses:

public static class GString
extends character

Usage

GString(..., sep="")

Arguments

Fields and Methods

Methods:

Methods inherited from character:
Ops,nonStructure,vector-method, Ops,structure,vector-method, Ops,vector,nonStructure-method, Ops,vector,structure-method, all.equal, as.Date, as.POSIXlt, as.data.frame, as.raster, coerce,ANY,character-method, coerce,character,SuperClassMethod-method, coerce,character,signature-method, coerce<-,ObjectsWithPackage,character-method, coerce<-,signature,character-method, downloadFile, formula, getDLLRegisteredRoutines, glyphJust, isOpen, toAsciiRegExprPattern, toFileListTree, uses

Author(s)

Henrik Bengtsson

See Also

For convenience, see functions gstring() and gcat().

Examples

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# First example
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
who <- "world"

# Compare this...
cat(as.character(GString("Hello ${who}\n")))

# ...to this.
cat(GString("Hello ${who}\n"))

# Escaping
cat(as.character(GString("Hello \\${who}\n")))


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Looping over vectors
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
x <- 1:5
y <- c("hello", "world")
cat(as.character(GString("(x,y)=(${x},${y})")), sep=", ")
cat("\n")

cat(as.character(GString("(x,y)=(${x},$[capitalize]{y})")), sep=", ")
cat("\n")


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Predefined ("builtin") variables
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cat(as.character(GString("Hello ${username} on host ${hostname} running ",
"R v${rversion} in process #${pid} on ${os}. R is installed in ${rhome}.")))


# Other built-in variables/functions...
cat(as.character(GString("Current date: ${date}\n")))
cat(as.character(GString("Current date: $[format='%d/%m/%y']{date}\n")))
cat(as.character(GString("Current time: ${time}\n")))


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Evaluating inline R code
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cat(as.character(GString("Simple calculation: 1+1=${`1+1`}\n")))
cat(as.character(GString("Alternative current date: ${`date()`}\n")))


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Function values
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Call function rnorm with arguments n=1, i.e. rnorm(n=1)
cat(as.character(GString("Random normal number: $[n=1]{rnorm}\n")))


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Global search-replace feature
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Replace all '-' with '.'
cat(as.character(GString("Current date: ${date/-/.}\n")))
# Another example
cat(as.character(GString("Escaped string: 12*12=${`12*12`/1/}\n")))


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Defining new "builtin" function values
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Define your own builtin variables (functions)
setMethodS3("getBuiltinAletter", "GString", function(object, ...) {
  base::letters[runif(1, min=1, max=length(base::letters))]
})

cat(as.character(GString("A letter: ${aletter}\n")))
cat(as.character(GString("Another letter: ${aletter}\n")))


# Another example
setMethodS3("getBuiltinGstring", "GString", function(object, ...) {
  # Return another GString.
  GString("${date} ${time}")
})

cat(as.character(GString("Advanced example: ${gstring}\n")))


# Advanced example
setMethodS3("getBuiltinRunif", "GString", function(object, n=1, min=0, max=1, ...) {
  formatC(runif(n=n, min=min, max=max), ...)
})

cat(as.character(GString("A random number: ${runif}\n")))
n <- 5
cat(as.character(GString("${n} random numbers: ")))
cat(as.character(GString("$[n=n, format='f']{runif}")))
cat("\n")


# Advanced options.
# Options are parsed as if they are elements in a list, e.g.
#   list(n=runif(n=1,min=1,max=5), format='f')
cat(as.character(GString("$Random number of numbers: ")))
cat(as.character(GString("$[n=runif(n=1,min=1,max=5), format='f']{runif}")))
cat("\n")

Gets the current date

Description

Gets the current date.

Usage

## Static method (use this):
## GString$getBuiltinDate(format="%Y-%m-%d", ...)

## Don't use the below:
## S3 method for class 'GString'
getBuiltinDate(static, format="%Y-%m-%d", ...)

Arguments

Value

Returns a character string.

Author(s)

Henrik Bengtsson

See Also

For more information see GString.

Gets the current date and time

Description

Gets the current date and time.

Usage

## Static method (use this):
## GString$getBuiltinDatetime(format=NULL, ...)

## Don't use the below:
## S3 method for class 'GString'
getBuiltinDatetime(static, format=NULL, ...)

Arguments

Value

Returns a character string.

Author(s)

Henrik Bengtsson

See Also

For more information see GString.

Gets the hostname of the system running R

Description

Gets the hostname of the system running R.

Usage

## Static method (use this):
## GString$getBuiltinHostname(...)

## Don't use the below:
## S3 method for class 'GString'
getBuiltinHostname(static, ...)

Arguments

Value

Returns a character string.

Author(s)

Henrik Bengtsson

See Also

For more information see GString.

Gets the operating system of the running machine

Description

Gets the operating system of the running machine.

Usage

## Static method (use this):
## GString$getBuiltinOs(...)

## Don't use the below:
## S3 method for class 'GString'
getBuiltinOs(static, ...)

Arguments

Value

Returns a character string.

Author(s)

Henrik Bengtsson

See Also

For more information see GString.

Gets the process id of the current R session

Description

Gets the process id of the current R session.

Usage

## Static method (use this):
## GString$getBuiltinPid(...)

## Don't use the below:
## S3 method for class 'GString'
getBuiltinPid(static, ...)

Arguments

Value

Returns an integer.

Author(s)

Henrik Bengtsson

See Also

For more information see GString.

Gets the path where R is installed

Description

Gets the path where R is installed.

Usage

## Static method (use this):
## GString$getBuiltinRhome(...)

## Don't use the below:
## S3 method for class 'GString'
getBuiltinRhome(static, ...)

Arguments

Value

Returns a character string.

Author(s)

Henrik Bengtsson

See Also

For more information see GString.

Gets the current R version

Description

Gets the current R version.

Usage

## Static method (use this):
## GString$getBuiltinRversion(...)

## Don't use the below:
## S3 method for class 'GString'
getBuiltinRversion(static, ...)

Arguments

Value

Returns a character string.

Author(s)

Henrik Bengtsson

See Also

For more information see GString.

Gets the current time

Description

Gets the current time.

Usage

## Static method (use this):
## GString$getBuiltinTime(format="%H:%M:%S", ...)

## Don't use the below:
## S3 method for class 'GString'
getBuiltinTime(static, format="%H:%M:%S", ...)

Arguments

Value

Returns a character string.

Author(s)

Henrik Bengtsson

See Also

For more information see GString.

Gets the username of the user running R

Description

Gets the username of the user running R.

Usage

## Static method (use this):
## GString$getBuiltinUsername(...)

## Don't use the below:
## S3 method for class 'GString'
getBuiltinUsername(static, ...)

Arguments

Value

Returns a character string.

Author(s)

Henrik Bengtsson

See Also

For more information see GString.

Gets a variable value given a name and attributes

Description

Gets a variable value given a name and attributes.

Usage

## Static method (use this):
## GString$getVariableValue(name, attributes="", where=c("builtin", "envir",
##   "parent", "Sys.getenv", "getOption"), envir=parent.frame(), inherits=TRUE,
##   missingValue=NA, ...)

## Don't use the below:
## S3 method for class 'GString'
getVariableValue(static, name, attributes="", where=c("builtin", "envir",
  "parent", "Sys.getenv", "getOption"), envir=parent.frame(), inherits=TRUE,
  missingValue=NA, ...)

Arguments

Value

Returns a (vector of) objects.

Author(s)

Henrik Bengtsson

See Also

For more information see GString.

Static class for Java related methods

Description

Package: R.utils
Class Java

Object
~~|
~~+--Java

Directly known subclasses:

public static class Java
extends Object

Static class that provides methods for reading and writing Java data types. Currently the following data types are supported: byte, short and int. R character strings can be written as UTF-8 formatted strings, which can be read by Java. Currently on Java String's that contain ASCII characters can be imported into R. The reason for this is that other characters are translated into non-eight bits data, e.g. 16- and 24-bits, which the readChar() method currently does not support.

Furthermore, the Java class defines some static constants describing the minimum and maximum value of some of the common Java data types: BYTE.MIN, BYTE.MAX SHORT.MIN, SHORT.MAX INT.MIN, INT.MAX LONG.MIN, and LONG.MAX.

Usage

Java()

Fields and Methods

Methods:

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, save

Author(s)

Henrik Bengtsson

Examples

pathname <- tempfile()

# Open the temporary file for writing
out <- file(pathname, open="wb")
b <- -128:127
Java$writeByte(out, b)
s <- -32768:32767
Java$writeShort(out, s)
i <- c(-2147483648, -2147483647, -1, 0, +1, 2147483646, 2147483647);
Java$writeInt(out, i)
str <- c("This R string was written (using the UTF-8 format) using",
         "the static methods of the Java class in the R.io package.")
str <- paste(str, collapse="\n")
Java$writeUTF(out, str)
close(out)

# Open the temporary file for reading
inn <- file(pathname, open="rb")

bfr <- Java$readByte(inn, n=length(b))
cat("Read ", length(bfr), " bytes.\n", sep="")
if (!identical(bfr, b))
  throw("Failed to read the same data that was written.")

bfr <- Java$readShort(inn, n=length(s))
cat("Read ", length(bfr), " shorts.\n", sep="")
if (!identical(bfr, s))
  throw("Failed to read the same data that was written.")

bfr <- Java$readInt(inn, n=length(i))
cat("Read ", length(bfr), " ints.\n", sep="")
if (!identical(bfr, i))
  throw("Failed to read the same data that was written.")

bfr <- Java$readUTF(inn)
cat("Read ", nchar(bfr), " UTF characters:\n", "'", bfr, "'\n", sep="")

close(inn)

file.remove(pathname)

Converts a numeric to a Java byte

Description

Converts a numeric to a Java byte.

Usage

## Static method (use this):
## Java$asByte(x, ...)

## Don't use the below:
## S3 method for class 'Java'
asByte(static, x, ...)

Arguments

Value

Returns an integer vector.

Author(s)

Henrik Bengtsson

See Also

For more information see Java.

Converts an numeric to a Java integer

Description

Converts an numeric to a Java integer.

Usage

## Static method (use this):
## Java$asInt(x, ...)

## Don't use the below:
## S3 method for class 'Java'
asInt(static, x, ...)

Arguments

Value

Returns an integer vector.

Author(s)

Henrik Bengtsson

See Also

For more information see Java.

Converts a numeric to a Java long

Description

Converts a numeric to a Java long.

Usage

## Static method (use this):
## Java$asLong(x, ...)

## Don't use the below:
## S3 method for class 'Java'
asLong(static, x, ...)

Arguments

Value

Returns an integer vector.

Author(s)

Henrik Bengtsson

See Also

For more information see Java.

Converts a numeric to a Java short

Description

Converts a numeric to a Java short.

Usage

## Static method (use this):
## Java$asShort(x, ...)

## Don't use the below:
## S3 method for class 'Java'
asShort(static, x, ...)

Arguments

Value

Returns an integer vector.

Author(s)

Henrik Bengtsson

See Also

For more information see Java.

Reads a Java formatted byte (8 bits) from a connection

Description

Reads one or several Java formatted byte's (8 bits) from a connection. All data types in Java are signed, i.e. a byte can hold a value in the range [-128,127].

Usage

## Static method (use this):
## Java$readByte(con, n=1, ...)

## Don't use the below:
## S3 method for class 'Java'
readByte(static, con, n=1, ...)

Arguments

Details

This method is included for consistency reasons only.

Value

Returns an integer vector.

Author(s)

Henrik Bengtsson

See Also

readBin(). For more information see Java.

Reads a Java formatted int (32 bits) from a connection

Description

Reads one or several Java formatted int's (32 bits) from a connection. All data types in Java are signed, i.e. a byte can hold a value in the range [-2147483648,2147483647].

Usage

## Static method (use this):
## Java$readInt(con, n=1, ...)

## Don't use the below:
## S3 method for class 'Java'
readInt(static, con, n=1, ...)

Arguments

Value

Returns a vector of doubles. Note that R integers gives NA is as.integer(-2147483648), which is the smallest Java int available.

Author(s)

Henrik Bengtsson

See Also

readBin(). For more information see Java.

Reads a Java formatted short (16 bits) from a connection

Description

Reads one or several Java formatted short's (16 bits) from a connection. All data types in Java are signed, i.e. a byte can hold a value in the range [-32768,32767].

Usage

## Static method (use this):
## Java$readShort(con, n=1, ...)

## Don't use the below:
## S3 method for class 'Java'
readShort(static, con, n=1, ...)

Arguments

Value

Returns an integer vector.

Author(s)

Henrik Bengtsson

See Also

readBin(). For more information see Java.

Reads a Java (UTF-8) formatted string from a connection

Description

Reads a Java (UTF-8) formatted string from a connection.

Usage

## Static method (use this):
## Java$readUTF(con, as.character=TRUE, ...)

## Don't use the below:
## S3 method for class 'Java'
readUTF(static, con, as.character=TRUE, ...)

Arguments

Details

Currently only 8-bit UTF-8 byte sequences are supported, i.e. plain ASCII sequences, i.e. characters that take up more than one byte are read incorrectly without any warnings.

Value

Returns a character string or an integer vector.

Author(s)

Henrik Bengtsson

See Also

readBin(). For more information see Java.

Writes a byte (8 bits) to a connection in Java format

Description

Writes one or several byte's (8 bits) to a connection in Java format so they will be readable by Java. All data types in Java are signed, i.e. a byte can hold a value in the range [-128,127]. Trying to write a value outside this range will automatically be truncated without a warning.

Usage

## Static method (use this):
## Java$writeByte(con, b, ...)

## Don't use the below:
## S3 method for class 'Java'
writeByte(static, con, b, ...)

Arguments

Details

This method is included for consistency reasons only.

Author(s)

Henrik Bengtsson

See Also

For more information see Java.

Writes a integer (32 bits) to a connection in Java format

Description

Writes one or several integer's (32 bits) to a connection in Java format so they will be readable by Java. All data types in Java are signed, i.e. a byte can hold a value in the range [-2147483648,2147483647]. Trying to write a value outside this range will automatically be truncated without a warning.

Usage

## Static method (use this):
## Java$writeInt(con, i, ...)

## Don't use the below:
## S3 method for class 'Java'
writeInt(static, con, i, ...)

Arguments

Author(s)

Henrik Bengtsson

See Also

For more information see Java.

Writes a short (16 bits) to a connection in Java format

Description

Writes one or several short's (16 bits) to a connection in Java format so they will be readable by Java. All data types in Java are signed, i.e. a byte can hold a value in the range [-32768,32767]. Trying to write a value outside this range will automatically be truncated without a warning.

Usage

## Static method (use this):
## Java$writeShort(con, s, ...)

## Don't use the below:
## S3 method for class 'Java'
writeShort(static, con, s, ...)

Arguments

Author(s)

Henrik Bengtsson

See Also

For more information see Java.

Writes a string to a connection in Java format (UTF-8)

Description

Writes a string to a connection in Java format (UTF-8) so it will be readable by Java. At the beginning of each UTF-8 sequence there is a short integer telling how many bytes (characters?) follows.

Usage

## Static method (use this):
## Java$writeUTF(con, str, ...)

## Don't use the below:
## S3 method for class 'Java'
writeUTF(static, con, str, ...)

Arguments

Author(s)

Henrik Bengtsson

See Also

For more information see Java.

The LComments class

Description

Package: R.utils
Class LComments

Object
~~|
~~+--SmartComments
~~~~~~~|
~~~~~~~+--VComments
~~~~~~~~~~~~|
~~~~~~~~~~~~+--LComments

Directly known subclasses:

public static class LComments
extends VComments

The LComments class.

This class, is almost identical to the super class, except that the constructor has different defaults.

Usage

LComments(letter="L", verboseName="log", ...)

Arguments

Fields and Methods

Methods:
No methods defined.

Methods inherited from VComments:
convertComment, reset, validate

Methods inherited from SmartComments:
compile, convertComment, parse, reset, validate

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, save

Author(s)

Henrik Bengtsson

A Verbose class ignoring everything

Description

Package: R.utils
Class MultiVerbose

Object
~~|
~~+--Verbose
~~~~~~~|
~~~~~~~+--MultiVerbose

Directly known subclasses:

public static class MultiVerbose
extends Verbose

A Verbose class ignoring everything.

This is a trial class.

Usage

MultiVerbose(verboseList=NULL, ...)

Arguments

Fields and Methods

Methods:

Methods inherited from Verbose:
as.character, as.double, as.logical, capture, cat, enter, enterf, equals, evaluate, exit, getThreshold, getTimestampFormat, header, isOn, isVisible, less, more, newline, off, on, popState, print, printWarnings, printf, pushState, ruler, setDefaultLevel, setThreshold, setTimestampFormat, str, summary, timestamp, timestampOff, timestampOn, writeRaw

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, save

Author(s)

Henrik Bengtsson

Examples

# Output to both standard output and to log file
stdoutLog <- Verbose(threshold=-1)
fileLog <- Verbose(file.path(tempdir(), "foo.log"), threshold=-1)
verbose <- MultiVerbose(list(stdoutLog, fileLog), threshold=-1)


header(verbose, "A verbose writer example", padding=0)

enter(verbose, "Analysis A")
for (kk in 1:10) {
  printf(verbose, "step %d\n", kk)
  if (kk == 2) {
    cat(verbose, "Turning ON automatic timestamps")
    timestampOn(verbose)
  } else if (kk == 4) {
    timestampOff(verbose)
    cat(verbose, "Turned OFF automatic timestamps")
    cat(verbose, "Turning OFF verbose messages for steps ", kk, "-6")
    off(verbose)
  } else if (kk == 6) {
    on(verbose)
    cat(verbose, "Turned ON verbose messages just before step ", kk+1)
  }

  if (kk %in% c(5,8)) {
    enter(verbose, "Sub analysis ", kk)
    for (jj in c("i", "ii", "iii")) {
      cat(verbose, "part ", jj)
    }
    exit(verbose)
  }
}
cat(verbose, "All steps completed!")
exit(verbose)

ruler(verbose)
cat(verbose, "Demo of some other methods:")
str(verbose, c(a=1, b=2, c=3))
print(verbose, c(a=1, b=2, c=3))
summary(verbose, c(a=1, b=2, c=3))
evaluate(verbose, rnorm, n=3, mean=2, sd=3)

ruler(verbose)
newline(verbose)

Non-documented objects

Description

This page contains aliases for all "non-documented" objects that R CMD check detects in this package.

Almost all of them are generic functions that have specific document for the corresponding method coupled to a specific class. Other functions are re-defined by setMethodS3() to default methods. Neither of these two classes are non-documented in reality. The rest are deprecated methods.

Author(s)

Henrik Bengtsson

A Verbose class ignoring everything

Description

Package: R.utils
Class NullVerbose

Object
~~|
~~+--Verbose
~~~~~~~|
~~~~~~~+--NullVerbose

Directly known subclasses:

public static class NullVerbose
extends Verbose

A Verbose class ignoring everything.

Usage

NullVerbose(...)

Arguments

Fields and Methods

Methods:

Methods inherited from Verbose:
as.character, as.double, as.logical, capture, cat, enter, enterf, equals, evaluate, exit, getThreshold, getTimestampFormat, header, isOn, isVisible, less, more, newline, off, on, popState, print, printWarnings, printf, pushState, ruler, setDefaultLevel, setThreshold, setTimestampFormat, str, summary, timestamp, timestampOff, timestampOn, writeRaw

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, save

Author(s)

Henrik Bengtsson

Examples

verbose <- Verbose()
cat(verbose, "A verbose messages")

verbose <- NullVerbose()
cat(verbose, "A verbose messages")   # Ignored

The Options class

Description

Package: R.utils
Class Options

Object
~~|
~~+--Options

Directly known subclasses:
Settings

public static class Options
extends Object

A class to set and get either options stored in a list tree structure.

Each option has a pathname. The format of a pathname is similar to a (Unix) filesystem pathname, e.g. "graphics/cex". See examples for more details.

Usage

Options(options=list(), ...)

Arguments

Details

Note, this class and its methods do not operate on the global options structure defined in R (options).

Value

The constructor returns an Options object.

Fields and Methods

Methods:

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, save

Author(s)

Henrik Bengtsson

Examples

local <- Options()

# Query a missing option
cex <- getOption(local, "graphics/cex")
cat("graphics/cex =", cex, "\n")  # Returns NULL

# Query a missing option with default value
cex <- getOption(local, "graphics/cex", defaultValue=1)
cat("graphics/cex =", cex, "\n")  # Returns NULL

# Set option and get previous value
oldCex <- setOption(local, "graphics/cex", 2)
cat("previous graphics/cex =", oldCex, "\n")  # Returns NULL

# Set option again and get previous value
oldCex <- setOption(local, "graphics/cex", 3)
cat("previous graphics/cex =", oldCex, "\n")  # Returns 2

# Query a missing option with default value, which is ignored
cex <- getOption(local, "graphics/cex", defaultValue=1)
cat("graphics/cex =", cex, "\n")  # Returns 3

# Query multiple options with multiple default values
multi <- getOption(local, c("graphics/cex", "graphics/pch"), c(1,2))
print(multi)

# Check existance of multiple options
has <- hasOption(local, c("graphics/cex", "graphics/pch"))
print(has)

# Get a subtree of options
graphics <- getOption(local, "graphics")
print(graphics)

# Get the complete tree of options
all <- getOption(local)
print(all)

Provides text based counting progress bar

Description

Package: R.utils
Class ProgressBar

Object
~~|
~~+--ProgressBar

Directly known subclasses:
FileProgressBar

public static class ProgressBar
extends Object

Usage

ProgressBar(max=100, ticks=10, stepLength=1, newlineWhenDone=TRUE)

Arguments

Fields and Methods

Methods:

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, save

Author(s)

Henrik Bengtsson

Examples

# A progress bar with default step length one.
pb <- ProgressBar(max=42)
reset(pb)
while (!isDone(pb)) {
  x <- rnorm(3e4)
  increase(pb)
  # Emulate a slow process
  if (interactive()) Sys.sleep(0.02)
}
cat("\n")

# A "faster" progress bar with default step length 1.4.
pb <- ProgressBar(max=42, stepLength=1.4)
reset(pb)
while (!isDone(pb)) {
  x <- rnorm(3e4)
  increase(pb)
  # Emulate a slow process
  if (interactive()) Sys.sleep(0.02)
}

cat("\n")

Class for applicational settings

Description

Package: R.utils
Class Settings

Object
~~|
~~+--Options
~~~~~~~|
~~~~~~~+--Settings

Directly known subclasses:

public static class Settings
extends Options

Class for applicational settings.

Usage

Settings(basename=NULL, ...)

Arguments

Fields and Methods

Methods:

Methods inherited from Options:
as.character, as.list, equals, getLeaves, getOption, hasOption, names, nbrOfOptions, setOption, str

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, save

Load settings with package and save on exit

Here is a generic .First.lib() function for loading settings with package. It also (almost) assures that the package is detached when R finishes. See onSessionExit() why it is not guaranteed!

The almost generic .Last.lib() function, which will prompt user to save settings, is called when a package is detached.

It is custom to put these functions in a file named zzz.R.

.First.lib():

  .First.lib <- function(libname, pkgname) {
    # Write a welcome message when package is loaded
    pkg <- Package(pkgname)
    assign(pkgname, pkg, pos=getPosition(pkg))

    # Read settings file ".<pkgname>Settings" and store it in package
    # variable '<pkgname>Settings'.
    varname <- paste(pkgname, "Settings")
    basename <- paste(".", varname, sep="")
    settings <- Settings$loadAnywhere(basename, verbose=TRUE)
    if (is.null(settings))
      settings <- Settings(basename)
    assign(varname, settings, pos=getPosition(pkg))

    # Detach package when R finishes, which will save package settings too.
    onSessionExit(function(...) detachPackage(pkgname))

    packageStartupMessage(getName(pkg), " v", getVersion(pkg),
        " (", getDate(pkg), ") successfully loaded. See ?", pkgname,
        " for help.\n", sep="")
  } # .First.lib()
 

.Last.lib():

  .Last.lib <- function(libpath) {
    pkgname <- "<package name>"

    # Prompt and save package settings when package is detached.
    varname <- paste(pkgname, "Settings", sep="")
    if (exists(varname)) {
      settings <- get(varname)
      if (inherits(settings, "Settings"))
        promptAndSave(settings)
    }
  } # .Last.lib()
 

Author(s)

Henrik Bengtsson

Examples

# Load settings from file, or create default settings
basename <- "some.settings"
settings <- Settings$loadAnywhere(basename)
if (is.null(settings))
  settings <- Settings(basename)

# Set default options, if missing.
setOption(settings, "graphics/verbose", TRUE, overwrite=FALSE)
setOption(settings, "io/verbose", Verbose(threshold=-1), overwrite=FALSE)

# Save and reload settings
path <- tempdir()
saveAnywhere(settings, path=path)
settings2 <- Settings$loadAnywhere(basename, paths=path)

# Clean up
file.remove(getLoadedPathname(settings2))

# Assert correctness
stopifnot(equals(settings, settings2))

Searches for the settings file in one or several directories

Description

Searches for the settings file in one or several directories.

Usage

## Static method (use this):
## Settings$findSettings(basename, paths=c(".", "~"), ...)

## Don't use the below:
## S3 method for class 'Settings'
findSettings(static, basename, paths=c(".", "~"), ...)

Arguments

Value

Returns the absolute pathname (character string) of the first settings file found, otherwise NULL.

Author(s)

Henrik Bengtsson

See Also

For more information see Settings.

Abstract class SmartComments

Description

Package: R.utils
Class SmartComments

Object
~~|
~~+--SmartComments

Directly known subclasses:
LComments, VComments

public abstract static class SmartComments
extends Object

Abstract class SmartComments.

Usage

SmartComments(letter=NA, ...)

Arguments

Details

A "smart" source-code comment is an R comment, which start with a '#', but is followed by a single letter, then a single symbol and a second '#' and then an option character string, and there must not be any code before the comment on the same line. In summary, a smart comment line has format: <white spaces>#<letter><symbol># <some text>.

Example code with two smart comments (VComments):

   x <- 2
   #V1# threshold=-1
   #Vc# A v-comment log message
   cat("Hello world")
 

which after compilation becomes

   x <- 2
   verbose <- Verbose(threshold=-1)
   if (verbose) { cat(verbose, "A v-comment log message"); }
   cat("Hello world")
 

Fields and Methods

Methods:

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, save

Author(s)

Henrik Bengtsson

See Also

VComments.

Read File Symbolic Links (also on Windows)

Description

Read File Symbolic Links (also on Windows) and returns the target of each link. This implementation is fully compatible with the Sys.readlink() implementation in the base package.

Usage

Sys.readlink2(paths, what=c("asis", "corrected"))

Arguments

Value

A character vector of the the same length as paths.

Author(s)

Henrik Bengtsson

Static class to query information about the system

Description

Package: R.utils
Class System

Object
~~|
~~+--System

Directly known subclasses:

public static class System
extends Object

The System class contains several useful class fields and methods. It cannot be instantiated.

Fields and Methods

Methods:

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, save

Author(s)

Henrik Bengtsson

Get the current time in milliseconds

Description

Get the current time in milliseconds.

Usage

## Static method (use this):
## System$currentTimeMillis(...)

## Don't use the below:
## S3 method for class 'System'
currentTimeMillis(this, ...)

Value

Returns an integer.

Author(s)

Henrik Bengtsson

See Also

Sys.time(). proc.time(). For more information see System.

Searches for a Ghostview executable on the current system

Description

Searches for a Ghostview executable on the current system.

Usage

## Static method (use this):
## System$findGhostscript(updateRGSCMD=TRUE, firstOnly=TRUE, force=FALSE, ...)

## Don't use the below:
## S3 method for class 'System'
findGhostscript(static, updateRGSCMD=TRUE, firstOnly=TRUE, force=FALSE, ...)

Arguments

Value

Returns a character vector of full and normalized pathnames where Ghostscript executables are found.

Author(s)

Henrik Bengtsson

References

[1] How to use Ghostscript, Ghostscript, 2022 https://ghostscript.com/docs/9.55.0/Use.htm
[2] Environment variable, Wikipedia, 2013. https://en.wikipedia.org/wiki/Environment_variable
[3] Environment.SpecialFolder Enumeration, Microsoft, 2013. https://learn.microsoft.com/en-us/dotnet/api/system.environment.specialfolder

See Also

For more information see System.

Examples

## Not run: 
  print(System$findGhostscript())

## End(Not run)

Searches for a working PNG device

Description

Searches for a working PNG device.

On Unix, the png device requires that X11 is available, which it is not when running batch scripts or running R remotely. In such cases, an alternative is to use the bitmap() device, which generates an EPS file and the uses Ghostscript to transform it to a PNG file.

Moreover, if identical looking bitmap and vector graphics (EPS) files are wanted for the same figures, in practice, bitmap() has to be used.

By default, this method tests a list of potential graphical devices and returns the first that successfully creates an image file. By default, it tries to create a PNG image file via the built-in png() device.

Usage

## Static method (use this):
## System$findGraphicsDevice(devices=list(png), maxCount=100, sleepInterval=0.1,
##   findGhostscript=TRUE, ...)

## Don't use the below:
## S3 method for class 'System'
findGraphicsDevice(static, devices=list(png), maxCount=100, sleepInterval=0.1,
  findGhostscript=TRUE, ...)

Arguments

Value

Returns a function that generates images, or NULL.

Author(s)

Henrik Bengtsson

See Also

For supported graphical devices, see capabilities(). png, bitmap() and dev2bitmap. *findGhostscript(). For more information see System.

Examples

  fcn <- System$findGraphicsDevice()
  if (identical(fcn, png)) {
    cat("PNG device found: png()")
  } else if (identical(fcn, bitmap)) {
    cat("PNG device found: bitmap()")
  } else {
    cat("PNG device not found.")
  }

Retrieves the computer name of the current host

Description

Retrieves the computer name of the current host.

Usage

## Static method (use this):
## System$getHostname(...)

## Don't use the below:
## S3 method for class 'System'
getHostname(static, ...)

Details

First, this function checks the system environment variables HOST, HOSTNAME, and COMPUTERNAME. Second, it checks Sys.info()["nodename"] for host name details. Finally, it tries to query the system command uname -n.

Value

Returns a character string.

See Also

*getUsername().

Retrieves the name of the user running R

Description

Retrieves the name of the user running R.

Usage

## Static method (use this):
## System$getUsername(...)

## Don't use the below:
## S3 method for class 'System'
getUsername(static, ...)

Details

First, this function checks the system environment variables USER, and USERNAME. Second, it checks Sys.info()["user"] for user name details. Finally, it tries to query the system command whoami.

Value

Returns a character string.

See Also

*getHostname().

Opens an HTML document using the OS default HTML browser

Description

Opens an HTML document using the OS default HTML browser. Note that this call is dependent on the operating system (currently only Windows and Unix are supported). The document given by query can either be a local file or a web page. If the query was given as non-url string, i.e. as a standard file pathname, the method will automatically check if the file exists and conform the query to a correct url starting with file:. The used url will be returned as a string.

Any suggestion how implement this on Apple system are welcome!

Usage

## Static method (use this):
## System$openBrowser(query, ...)

## Don't use the below:
## S3 method for class 'System'
openBrowser(this, query, ...)

Arguments

Details

It is hard to create a good cross-platform openBrowser() method, but here is one try.

In the following text <browser> is the value returned by getOption("browser") and <url> is the URL conformed query, which starts with either file: or http:.

On a Windows system, if <browser> is not NULL, first

shell.exec(<browser> <url>)

is tried. If this fails, then

shell.exec(<url>)

is tried. Using this latter approach will not guarantee that an HTML browser will open the url, e.g. depending on the Windows file associations, a *.txt file might be opened by NotePad. However, it will most likely open something. If <browser> contains spaces, make sure it is quoted.

On Unix systems, system() will be used to call:

<browser> -remote "openURL(<url>)" 2> /dev/null || <browser> <url> &

Value

Returns the url of the query.

Author(s)

Henrik Bengtsson

See Also

For more information see System.

Examples

## Not run: 
  System$openBrowser("https://www.r-project.org/")

## End(Not run)

Parses a string, file or connection for Debian formatted parameters

Description

Parses a text, file or a connection for Debian formatted parameters. A file in Debian format contains rows with parameters of the form KEY=VALUE. It is allowed to have duplicated keys.

Usage

## Static method (use this):
## System$parseDebian(text=NULL, file=NULL, keys=NULL, ...)

## Don't use the below:
## S3 method for class 'System'
parseDebian(this, text=NULL, file=NULL, keys=NULL, ...)

Arguments

Either, text or file must be given.

Value

Returns a named list of parameter values.

Author(s)

Henrik Bengtsson

See Also

For more information see System.

Examples

 file <- file.path(Package("R.utils")$path, "DESCRIPTION")
 l <- System$parseDebian(file=file)
 print(l)

A status bar at the R prompt that can be updated

Description

Package: R.utils
Class TextStatusBar

Object
~~|
~~+--TextStatusBar

Directly known subclasses:

public static class TextStatusBar
extends Object

A status bar at the R prompt that can be updated.

Usage

TextStatusBar(fmt=paste("%-", getOption("width") - 1, "s", sep = ""), ...)

Arguments

Details

A label with name hfill can be used for automatic horizontal filling. It must be numeric and be immediate before a string label such that a hfill label and the following string label together specifies an sprintf format such as "%*-s". The value of hfill will be set such that the resulting status bar has width equal to getOption("width")-1 (the reason for the -1 is to prevent the text status bar from writing into the next line). If more than one hfill label is used their widths will be uniformly distributed. Left over spaces will be distributed between hfill labels with initial values of one.

Fields and Methods

Methods:

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, save

Author(s)

Henrik Bengtsson

Examples

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Read all HTML files in the base package
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
path <- system.file(package="base")
files <- list.files(path, recursive=TRUE, full.names=TRUE)
files <- files[sapply(files, FUN=isFile)]
nfiles <- length(files)

cat(sprintf("Reading %d files in %s:\n", nfiles, path))

# Create a status bar with four labels
sb <- TextStatusBar("File: %-*s [%3.0f%% %7.0f bytes %-8s]",
                hfill=1, file="", progress=0, nbytes=0L, time="")

nbytes <- 0L
for (kk in seq_len(nfiles)) {
  file <- files[kk]

  # Update the status bar
  if (sb) {
    setLabel(sb, "progress", 100*kk/nfiles)
    if (kk %% 10 == 1 || kk == nfiles)
      setLabel(sb, "file", substr(basename(file), 1, 44))

    size <- file.info(file)$size
    # popMessage() calls update() too
    popMessage(sb, sprintf("Processing %s (%.2fkB)",
                                       basename(file), size/1024))
    flush(sb)
  }

  # Read the file
  bfr <- readBin(file, what="raw", n=size)
  nbytes <- nbytes + size

  # Emulate a slow process
  if (interactive()) Sys.sleep(rexp(1, rate=60))

  # Update the status bar
  if (sb) {
    setLabel(sb, "nbytes", nbytes)
    setLabel(sb, "time", format(Sys.time(), "%H:%M:%S"))
    update(sb)
  }
}
setLabel(sb, "file", "<done>")
update(sb)
cat("\n")

TimeoutException represents timeout errors

Description

Package: R.utils
Class TimeoutException

Object
~~|
~~+--try-error
~~~~~~~|
~~~~~~~+--condition
~~~~~~~~~~~~|
~~~~~~~~~~~~+--error
~~~~~~~~~~~~~~~~~|
~~~~~~~~~~~~~~~~~+--simpleError
~~~~~~~~~~~~~~~~~~~~~~|
~~~~~~~~~~~~~~~~~~~~~~+--Exception
~~~~~~~~~~~~~~~~~~~~~~~~~~~|
~~~~~~~~~~~~~~~~~~~~~~~~~~~+--TimeoutException

Directly known subclasses:

public static class TimeoutException
extends Exception

TimeoutException represents timeout errors occurring when a set of R expressions executed did not finish in time.

Usage

TimeoutException(..., cpu=NA, elapsed=NA)

Arguments

.

Fields and Methods

Methods:

Methods inherited from Exception:
as.character, getCall, getCalls, getLastException, getMessage, getStackTrace, getWhen, print, printStackTrace, throw

Methods inherited from error:
as.character, throw

Methods inherited from condition:
abort, as.character, conditionCall, conditionMessage, print

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, save

Author(s)

Henrik Bengtsson

See Also

For detailed information about exceptions see Exception.

The VComments class

Description

Package: R.utils
Class VComments

Object
~~|
~~+--SmartComments
~~~~~~~|
~~~~~~~+--VComments

Directly known subclasses:
LComments

public static class VComments
extends SmartComments

The VComments class.

Usage

VComments(letter="V", verboseName="verbose", ...)

Arguments

Details

The 'v' in VComments stands for 'verbose', because of its relationship to the Verbose class.

Here is a list of VComments and the R code that replaces each of them by the compiler:

Constructors

#V0#

[<args>] - NullVerbose(<args>)

#V1#

[<args>] - Verbose(<args>)

Controls

#V=#

[<variable>] - Sets the name of the <verbose> object. Default is 'verbose'.

#V^#

<threshold> - setThreshold(<verbose>, <threshold>)

#V?#

<expression> - if (isVisible(<verbose>)) { <expression> }

#V@#

<level> - setDefaultLevel(<verbose>, <level>)

#Vm#

<method> <args> - <method>(<verbose>, <args>)

Enters and exits

#V+#

[<message>] - enter(<verbose>, <message>)

#V-#

[<message>] - exit(<verbose>, <message>)

#V!#

[<message>] - pushState(<verbose>)
on.exit(popState(<verbose>))
If <message>, enter(<verbose>, <message>)

Simple output

#Vn#

<ignored> - newline(<verbose>)

#Vr#

<ignored> - ruler(<verbose>)

#Vt#

<ignored> - timestamp(<verbose>)

#Vw#

[<title>] - warnings(<verbose>, <title>)

Output messages

#Vc#

[<message>] - cat(<verbose>, <message>)

#Ve#

<expression> - eval(<verbose>, <expression>)

#Vh#

<message> - header(<verbose>, <message>)

#Vp#

<object> - print(<verbose>, <object>)

#Vs#

<object> - summary(<verbose>, <object>)

#Vz#

<object> - str(<verbose>, <object>)

Fields and Methods

Methods:

Methods inherited from SmartComments:
compile, convertComment, parse, reset, validate

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, save

Author(s)

Henrik Bengtsson

Examples

filename <- system.file("data-ex/exampleVComments.R", package="R.utils")
lines <- readLines(filename)

cat("Code before preprocessing:\n")
displayCode(code=lines, pager="console")

lines <- VComments$compile(lines)

cat("Code after preprocessing:\n")
displayCode(code=lines, pager="console")

Class to writing verbose messages to a connection or file

Description

Package: R.utils
Class Verbose

Object
~~|
~~+--Verbose

Directly known subclasses:
MultiVerbose, NullVerbose

public static class Verbose
extends Object

Class to writing verbose messages to a connection or file.

Usage

Verbose(con=stderr(), on=TRUE, threshold=0, asGString=TRUE, timestamp=FALSE,
  removeFile=TRUE, core=TRUE, ...)

Arguments

Fields and Methods

Methods:

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, save

Output levels

As a guideline, use the following levels when outputting verbose/debug message using the Verbose class. For a message to be shown, the output level must be greater than (not equal to) current threshold. Thus, the lower the threshold is set, the more messages will be seen.

<= -100

Only for debug messages, i.e. messages containing all necessary information for debugging purposes and to find bugs in the code. Normally these messages are so detailed so they will be a pain for the regular user, but very useful for bug reporting and bug tracking by the developer.

-99 – -11

Detailed verbose messages. These will typically be useful for the user to understand what is going on and do some simple debugging fixing problems typically due to themselves and not due to bugs in the code.

-10 – -1

Verbose messages. For example, these will typically report the name of the file to be read, the current step in a sequence of analysis steps and so on. These message are not very useful for debugging.

0

Default level in all output methods and default threshold. Thus, by default, messages at level 0 are not shown.

>= +1

Message that are always outputted (if threshold is kept at 0). We recommend not to output message at this level, because methods should be quiet by default (at the default threshold 0).

A compatibility trick and a speed-up trick

If you want to include calls to Verbose in a package of yours in order to debug code, but not use it otherwise, you might not want to load R.utils all the time, but only for debugging. To achieve this, the value of a reference variable to a Verbose class is always set to TRUE, cf. typically an Object reference has value NA. This makes it possible to use the reference variable as a first test before calling Verbose methods. Example:

    foo <- function(..., verbose=FALSE) {
      # enter() will never be called if verbose==FALSE, thus no error.
      verbose && enter(verbose, "Loading")
    }
  

Thus, R.utils is not required for foo(), but for foo(verbose==Verbose(level=-1)) it is.

Moreover, if using the NullVerbose class for ignoring all verbose messages, the above trick will indeed speed up the code, because the value of a NullVerbose reference variable is always FALSE.

Extending the Verbose class

If extending this class, make sure to output messages via *writeRaw() or one of the other output methods (which in turn all call the former). This guarantees that *writeRaw() has full control of the output, e.g. this makes it possible to split output to standard output and to file.

Author(s)

Henrik Bengtsson

See Also

NullVerbose.

Examples

verbose <- Verbose(threshold=-1)

header(verbose, "A verbose writer example", padding=0)

enter(verbose, "Analysis A")
for (kk in 1:10) {
  printf(verbose, "step %d\n", kk)
  if (kk == 2) {
    cat(verbose, "Turning ON automatic timestamps")
    timestampOn(verbose)
  } else if (kk == 4) {
    timestampOff(verbose)
    cat(verbose, "Turned OFF automatic timestamps")
    cat(verbose, "Turning OFF verbose messages for steps ", kk, "-6")
    off(verbose)
  } else if (kk == 6) {
    on(verbose)
    cat(verbose, "Turned ON verbose messages just before step ", kk+1)
  }

  if (kk %in% c(5,8)) {
    enterf(verbose, "Sub analysis #%d", kk)
    for (jj in c("i", "ii", "iii")) {
      cat(verbose, "part ", jj)
    }
    exit(verbose)
  }
}
cat(verbose, "All steps completed!")
exit(verbose)

ruler(verbose)
cat(verbose, "Demo of some other methods:")
str(verbose, c(a=1, b=2, c=3))
print(verbose, c(a=1, b=2, c=3))
summary(verbose, c(a=1, b=2, c=3))
evaluate(verbose, rnorm, n=3, mean=2, sd=3)

ruler(verbose)
newline(verbose)

Modifies .Last() to call 'finalizeSession()

Description

Modifies .Last() to call 'finalizeSession() before calling the default .Last() function.

Note that .Last() is not guaranteed to be called when the R session finished. For instance, the user may quit R by calling quit(runLast=FALSE) or run R in batch mode.

Note that this function is called when the R.utils package is loaded.

Usage

## Default S3 method:
addFinalizerToLast(...)

Arguments

Value

Returns (invisibly) TRUE if .Last() was modified, otherwise FALSE.

Author(s)

Henrik Bengtsson

See Also

onSessionExit().

Gets the processed character string

Description

Gets the processed character string.

Usage

## S3 method for class 'GString'
as.character(x, envir=parent.frame(), ...)

Arguments

Value

Returns a character string.

Author(s)

Henrik Bengtsson

See Also

For more information see GString.

Returns a character string version of this object

Description

Returns a character string version of this object.

Usage

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

Arguments

Value

Returns a character string.

Author(s)

Henrik Bengtsson

See Also

For more information see Options.

Gets a string description of the progress bar

Description

Gets a string description of the progress bar.

Usage

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

Arguments

Value

Returns a character string.

Author(s)

Henrik Bengtsson

See Also

For more information see ProgressBar.

Returns a character string version of this object

Description

Returns a character string version of this object.

Usage

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

Arguments

Value

Returns a character string.

Author(s)

Henrik Bengtsson

See Also

For more information see Verbose.

Gets a numeric value of this object

Description

Gets a numeric value of this object. Returns what *getThreshold() returns.

Usage

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

Arguments

Value

Returns a numeric value.

Author(s)

Henrik Bengtsson

See Also

*getThreshold() and *getThreshold(). For more information see Verbose.

Gets a list of Verbose objects

Description

Gets a list of Verbose objects.

Usage

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

Arguments

Value

Returns a list of Verbose objects.

Author(s)

Henrik Bengtsson

See Also

For more information see MultiVerbose.

Gets a list representation of the options

Description

Gets a list representation of the options.

Usage

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

Arguments

Value

Returns a tree list structure.

Author(s)

Henrik Bengtsson

See Also

For more information see Options.

Gets a logical value of this object

Description

Gets a logical value of this object. Returns isVisible(this, level=this$defaultLevel).

Usage

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

Arguments

Value

Returns a logical value.

Author(s)

Henrik Bengtsson

See Also

*isVisible(). For more information see Verbose.

Assigns an objects elements locally

Description

Assigns an objects elements locally.

Usage

## S3 method for class 'list'
attachLocally(object, fields=NULL, excludeFields=NULL, overwrite=TRUE,
  envir=parent.frame(), ...)

Arguments

Value

Returns (invisibly) a character vector of the fields copied.

Author(s)

Henrik Bengtsson

See Also

attachLocally() of class Object. attach().

Examples

foo <- function(object) {
  cat("Local objects in foo():\n")
  print(ls())

  attachLocally(object)

  cat("\nLocal objects in foo():\n")
  print(ls())

  for (name in ls()) {
    cat("\nObject '", name, "':\n", sep="")
    print(get(name, inherits=FALSE))
  }
}

a <- "A string"
l <- list(a=1:10, msg="Hello world", df=data.frame(a=NA, b=2))
foo(l)
print(a)

Call hook functions by hook name

Description

Call hook functions by hook name.

Usage

## Default S3 method:
callHooks(hookName, ..., removeCalledHooks=FALSE)

Arguments

Value

Returns (invisibly) whatever callHooks.list() returns.

Author(s)

Henrik Bengtsson

See Also

Internally, after retrieving hook functions, callHooks.list() is called.

Examples

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Example 1
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# First, clean up if called more than once
setHook("myFunction.onEnter", NULL, action="replace")
setHook("myFunction.onExit", NULL, action="replace")

runConference <- function(...) {
  callHooks("myFunction.onEnter")
  cat("Speaker A: Hello there...\n")
  callHooks("myFunction.onExit")
}

setHook("myFunction.onEnter", function(...) {
  cat("Chair: Welcome to our conference.\n")
})

setHook("myFunction.onEnter", function(...) {
  cat("Chair: Please welcome Speaker A!\n")
})

setHook("myFunction.onExit", function(...) {
  cat("Chair: Please thanks Speaker A!\n")
})

runConference()


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Example 2
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
setHook("randomNumber", NULL, action="replace")
setHook("randomNumber", rnorm)      # By function
setHook("randomNumber", "rexp")     # By name
setHook("randomNumber", "runiff")   # Non-existing name
setHook("randomNumber", .GlobalEnv) # Not a function

res <- callHooks("randomNumber", n=1)
str(res)
cat("Number of hooks: ", length(res), "\n")
isErroneous <- unlist(lapply(res, FUN=function(x) !is.null(x$exception)))
cat("Erroneous hooks: ", sum(isErroneous), "\n")

Call hook functions

Description

Call hook functions.

Usage

## S3 method for class 'function'
callHooks(hooks, ...)

Arguments

Value

Returns (invisibly) a list that is named with hook names, if possible. Each element in the list is in turn a list with three element: fcn is the hook function called, result is its return value, and exception is the exception caught or NULL.

Author(s)

Henrik Bengtsson

See Also

See callHooks() to call hook function by name.

Capitalizes/decapitalizes each character string in a vector

Description

Capitalizes/decapitalized (making the first letter upper/lower case) of each character string in a vector.

Usage

  ## Default S3 method:
capitalize(str, ...)
  ## Default S3 method:
decapitalize(str, ...)

Arguments

Value

Returns a vector of character strings of the same length as the input vector.

Author(s)

Henrik Bengtsson

See Also

toCamelCase.

Examples

words <- strsplit("Hello wOrld", " ")[[1]]
cat(paste(toupper(words), collapse=" "), "\n")      # "HELLO WORLD"
cat(paste(tolower(words), collapse=" "), "\n")      # "hello world"
cat(paste(capitalize(words), collapse=" "), "\n")   # "Hello WOrld"
cat(paste(decapitalize(words), collapse=" "), "\n") # "hello wOrld"

# Sanity checks
stopifnot(paste(toupper(words), collapse=" ") == "HELLO WORLD")
stopifnot(paste(tolower(words), collapse=" ") == "hello world")
stopifnot(paste(capitalize(words), collapse=" ") == "Hello WOrld")
stopifnot(paste(decapitalize(words), collapse=" ") == "hello wOrld")

Captures output of a function

Description

Captures output of a function. Evaluates its arguments with the output being verbosed.

Usage

## S3 method for class 'Verbose'
capture(this, ..., level=this$defaultLevel)

Arguments

Value

Returns a vector of character string.

Author(s)

Henrik Bengtsson

See Also

For more information see Verbose.

Evaluate an R expression and captures the output

Description

Evaluate an R expression and captures the output.

Usage

captureOutput(expr, file=NULL, append=FALSE, collapse=NULL, envir=parent.frame())

Arguments

Details

This method imitates capture.output with the major difference that it captures strings via a raw connection rather than via internal strings. The latter becomes exponentially slow for large outputs [1,2].

Value

Returns captured output as a character vector.

Author(s)

Henrik Bengtsson

References

[1] R-devel thread 'capture.output(): Using a rawConnection() [linear] instead of textConnection() [exponential]?', 2014-02-04. https://stat.ethz.ch/pipermail/r-devel/2014-February/068349.html [2] JottR blog post 'PERFORMANCE: captureOutput() is much faster than capture.output()', 2015-05-26. https://www.jottr.org/2014/05/26/captureoutput/

See Also

Internally, eval() is used to evaluate the expression. and capture.output to capture the output.

Examples

# captureOutput() is much faster than capture.output()
# for large outputs when capturing to a string.
for (n in c(10e3, 20e3, 30e3, 40e3)) {
  printf("n=%d\n", n)

  x <- rnorm(n)

  t0 <- system.time({
    bfr0 <- capture.output(print(x))
  })
  print(t0)

  t1 <- system.time({
    bfr <- captureOutput(print(x))
  })
  print(t1)
  print(t1/t0)

  bfr2n <- captureOutput(print(x), collapse="\n")
  bfr2r <- captureOutput(print(x), collapse="\r")

  stopifnot(identical(bfr, bfr0))
} # for (n ...)

Concatenates and prints objects if above threshold

Description

Concatenates and prints objects if above threshold. The output is indented according to *enter()/*exit() calls.

Usage

## S3 method for class 'Verbose'
cat(this, ..., sep="", newline=TRUE, level=this$defaultLevel, timestamp=this$.timestamp)

Arguments

Value

Returns nothing.

Author(s)

Henrik Bengtsson

See Also

*timestampOn() and timestampOff(). For more information see Verbose.

Removes the progress file for a file progress bar

Description

Removes the progress file for a file progress bar.

Usage

## S3 method for class 'FileProgressBar'
cleanup(object, ...)

Arguments

Value

Returns (invisibly) TRUE, if there is no progress file afterwards. Otherwise, FALSE is returned.

Author(s)

Henrik Bengtsson

See Also

For more information see FileProgressBar.

Simple access to parsed command-line arguments

Description

Simple access to parsed command-line arguments.

Usage

  cmdArgs(args=NULL, names=NULL, unique=TRUE, ..., .args=NULL)
  cmdArg(...)

Arguments

Value

cmdArgs() returns a named list with command-line arguments. cmdArg() return the value of the requested command-line argument.

Coercing to non-character data types

The value of each command-line argument is returned as a character string, unless an argument share name with ditto in the (optional) arguments always and default in case the retrieved value is coerced to that of the latter. Finally, remaining character string command-line arguments are coerced to numerics (via as.numeric()), if possible, that is unless the coerced value becomes NA.

Author(s)

Henrik Bengtsson

See Also

Internally, commandArgs() is used.

Examples

args <- cmdArgs()
cat("User command-line arguments used when invoking R:\n")
str(args)

# Retrieve command line argument 'n', e.g. '-n 13' or '--n=13'
n <- cmdArg("n", 42L)
printf("Argument n=%d\n", n)

# Short version doing the same
n <- cmdArg(n=42L)
printf("Argument n=%d\n", n)

Calls an R function passing command-line arguments

Description

Calls an R function passing command-line arguments.

Usage

cmdArgsCall(..., args=cmdArgs(unique = FALSE), .ignoreUnusedArgs=FALSE,
  envir=parent.frame())

Arguments

Value

Returns whatever the called function returns.

Author(s)

Henrik Bengtsson

See Also

Internally, cmdArgs() and doCall() is used.

Examples

## Not run: 
  Rscript -e R.utils::cmdArgsCall(rnorm) n=4

## End(Not run)

Creates a vector of column classes used for tabular reading

Description

Creates a vector of column classes used for tabular reading based on a compact format string.

Usage

## Default S3 method:
colClasses(fmt, ...)

Arguments

Value

Returns a vector of character strings.

Author(s)

Henrik Bengtsson

See Also

read.table.

Examples

# All predefined types
print(colClasses("-?cdfilnrzDP"))
## [1] "NULL"      "NA"        "character" "double"
## [5] "factor"    "integer"   "logical"   "numeric"
## [9] "raw"       "complex"   "Date"      "POSIXct"

# A string in column 1, integers in column 4 and 5, rest skipped
print(colClasses("c--ii----"))
## [1] "character" "NULL"      "NULL"      "integer"
## [5] "integer"   "NULL"      "NULL"      "NULL"
## [9] "NULL"

# Repeats and custom column classes
c1 <- colClasses("3c{MyClass}3{foo}")
print(c1)
## [1] "character" "character" "character" "MyClass"
## [5] "foo"       "foo"       "foo"

# Passing repeats and class names using sprintf() syntax
c2 <- colClasses("%dc{%s}%d{foo}", 3, "MyClass", 3)
stopifnot(identical(c1, c2))

# Repeats of a vector of column classes
c3 <- colClasses("3{MyClass,c}")
print(c3)
## [1] "MyClass"   "character" "MyClass"   "character"
## [4] "MyClass"   "character"

# Large number repeats
c4 <- colClasses("321{MyClass,c,i,d}")
c5 <- rep(c("MyClass", "character", "integer", "double"), times=321)
stopifnot(identical(c4, c5))

Extract command-line arguments

Description

Provides access to a copy of the command-line arguments supplied when this R session was invoked. This function is backward compatible with commandArgs() of the base package, but adds more features.

Usage

commandArgs(trailingOnly=FALSE, asValues=FALSE, defaults=NULL, always=NULL, adhoc=FALSE,
  unique=FALSE, excludeReserved=FALSE, excludeEnvVars=FALSE, os=NULL, .args=NULL, ...)

Arguments

Value

If asValue is FALSE, a character vector is returned, which contains the name of the executable and the non-parsed user-supplied arguments.

If asValue is TRUE, a named list containing is returned, which contains the the executable and the parsed user-supplied arguments.

The first returned element is the name of the executable by which R was invoked. As far as I am aware, the exact form of this element is platform dependent. It may be the fully qualified name, or simply the last component (or basename) of the application. The returned attribute isReserved is a logical vector specifying if the corresponding command-line argument is a reserved R argument or not.

Backward compatibility

This function should be fully backward compatible with the same function in the base package, except when littler is used (see below).

Compatibility with littler

The littler package provides the r binary, which parses user command-line options and assigns them to character vector argv in the global environment. The commandArgs() of this package recognizes argv arguments as well.

Coercing to non-character data types

When asValues is TRUE, the command-line arguments are returned as a named list. By default, the values of these arguments are character strings. However, any command-line argument that share name with one of the 'always' or 'default' arguments, then its value is coerced to the corresponding data type (via as). This provides a mechanism for specifying data types other than character strings.

Furthermore, when asValues and adhoc are TRUE, any remaining character string command-line arguments are coerced to more specific data types (via type.convert), if possible.

Author(s)

Henrik Bengtsson

See Also

For a more user friendly solution, see cmdArgs(). Internally commandArgs() is used.

Examples

######################################################################
# Non-parsed command-line arguments
######################################################################
# Display how this instance of R was invoked.
cmd <- paste(commandArgs(), collapse=" ")
cat("How R was invoked:\n");
cat(cmd, "\n")

# Get all arguments
args <- commandArgs()
print(args)

# Get only "private" arguments and not the name of the R executable.
args <- commandArgs(excludeReserved=TRUE)[-1]
print(args)

# Assert backward compatibility
args0 <- base::commandArgs()
args <- commandArgs()
stopifnot(all.equal(args, args0, check.attributes=FALSE))


######################################################################
# Parsed command-line arguments
######################################################################
# Get all arguments as a named list, e.g. if R is started as:
#
#   R DATAPATH=../data --args --root="do da" --foo bar --details --a=2
#
# then 'args' below will equal
#
#   list(R=NA, DATAPATH="../data" args=TRUE, root="do da",
#        foo="bar", details=TRUE, a="2")
args <- commandArgs(asValues=TRUE)
str(args)

# Turn arguments into R variables
args <- commandArgs(asValues=TRUE, excludeReserved=TRUE)[-1]
keys <- attachLocally(args)
cat("Command-line arguments attached to global environment:\n");
print(keys);
str(mget(keys, envir=globalenv()))

Preprocess a vector of code lines

Description

Preprocess a vector of code lines.

Usage

## S3 method for class 'SmartComments'
compile(this, lines, trim=TRUE, excludeComments=FALSE, ...)

Arguments

Details

When called, the compiler is reset.

Just before trimming is done, the validate() method is called. In the current class, this does nothing, but can be overridden in subclasses.

Value

Returns a character vector.

Author(s)

Henrik Bengtsson

See Also

For more information see SmartComments.

Compressing and decompressing files

Description

Compressing and decompressing files such as gzip:ed and bzip2:ed files.

NOTE: The default (remove=TRUE) behavior is that the input file is removed after that the output file is fully created and closed.

Usage

 ## Default S3 method:
compressFile(filename, destname=sprintf("%s.%s", filename, ext), ext, FUN,
  temporary=FALSE, skip=FALSE, overwrite=FALSE, remove=TRUE, BFR.SIZE=1e+07, ...)
 ## Default S3 method:
decompressFile(filename, destname=gsub(sprintf("[.]%s$", ext), "", filename,
  ignore.case = TRUE), ext, FUN, temporary=FALSE, skip=FALSE, overwrite=FALSE,
  remove=TRUE, BFR.SIZE=1e+07, ...)
 ## Default S3 method:
isCompressedFile(filename, method=c("extension", "content"), ext, fileClass, ...)
 ## Default S3 method:
bzip2(filename, ..., ext="bz2", FUN=bzfile)
 ## Default S3 method:
bunzip2(filename, ..., ext="bz2", FUN=bzfile)
 ## Default S3 method:
gzip(filename, ..., ext="gz", FUN=gzfile)
 ## Default S3 method:
gunzip(filename, ..., ext="gz", FUN=gzfile)

Arguments

Details

Internally bzfile() and gzfile() (see connections) are used to read (write) files. If the process is interrupted before completed, the partially written output file is automatically removed.

Value

Returns the pathname of the output file. The number of bytes processed is returned as an attribute.

isCompressedFile(), isGzipped() and isBzipped() return a logical. Note that with method = "extension" (default), only the filename extension is used to infer whether the file is compressed or not. Specifically, it does not matter whether the file actually exists or not.

Author(s)

Henrik Bengtsson

Examples

  ## bzip2
  cat(file="foo.txt", "Hello world!")
  print(isBzipped("foo.txt"))
  print(isBzipped("foo.txt.bz2"))

  bzip2("foo.txt")
  print(file.info("foo.txt.bz2"))
  print(isBzipped("foo.txt"))
  print(isBzipped("foo.txt.bz2"))

  bunzip2("foo.txt.bz2")
  print(file.info("foo.txt"))

  ## gzip
  cat(file="foo.txt", "Hello world!")
  print(isGzipped("foo.txt"))
  print(isGzipped("foo.txt.gz"))

  gzip("foo.txt")
  print(file.info("foo.txt.gz"))
  print(isGzipped("foo.txt"))
  print(isGzipped("foo.txt.gz"))

  gunzip("foo.txt.gz")
  print(file.info("foo.txt"))

  ## Cleanup
  file.remove("foo.txt")

Compresses a PDF (into a new PDF)

Description

Compresses a PDF (into a new PDF).

Usage

## Default S3 method:
compressPDF(filename, path=NULL, outFilename=basename(pathname),
  outPath="compressedPDFs", skip=FALSE, overwrite=FALSE, compression="gs(ebook)+qpdf",
  ...)

Arguments

Value

Returns the pathname of the generated PDF.

Author(s)

Henrik Bengtsson

See Also

Internally compactPDF is utilized.

Examples

## Not run: 
  pathnameZ <- compressPDF("report.pdf")

## End(Not run)

Converts a single smart comment to R code

Description

Converts a single smart comment to R code.

Usage

## S3 method for class 'SmartComments'
convertComment(...)

Arguments

Value

Should return single character of valid R code.

Author(s)

Henrik Bengtsson

See Also

For more information see SmartComments.

Converts a verbose comment to R code

Description

Converts a verbose comment to R code.

Usage

## S3 method for class 'VComments'
convertComment(this, vcomment, .currLine=NA, .line=NA, ...)

Arguments

Value

Returns one character string of R code.

Author(s)

Henrik Bengtsson

See Also

For more information see VComments.

Copies a directory

Description

Copies a directory.

Usage

## Default S3 method:
copyDirectory(from, to=".", ..., private=TRUE, recursive=TRUE)

Arguments

Details

Note that this method does not use copyFile() to copy the files, but file.copy().

Value

Returns (invisibly) a character vector of pathnames copied.

Author(s)

Henrik Bengtsson

Copies a file atomically

Description

Copies a file atomically, by first copying to a temporary file and then renaming that file.

Usage

## Default S3 method:
copyFile(srcPathname, destPathname, skip=FALSE, overwrite=FALSE, ..., validate=TRUE,
  verbose=FALSE)

Arguments

Details

If the source file does not exists (or is not a file), then an informative exception is thrown.

If the source and destination pathnames are the same, it is not safe to copy (which can lead to either corrupt or lost files) and an informative exception is thrown.

If (and only if) the file is successfully copied and argument validate is TRUE, then this method also asserts that the file size of the destination matches that of the source, otherwise an informative exception is thrown.

Value

Returns a logical indicating whether a successful file copy was completed or not, or equivalently. In other words, TRUE is returned if the file was successfully copied, and FALSE if not. If an error occurs, an informative exception is thrown. If the error occurs while renaming the temporary file to the final name, the temporary file will remain in the destination directory.

Author(s)

Henrik Bengtsson

See Also

file.copy().

Counts the number of lines in a text file

Description

Counts the number of lines in a text file by counting the number of occurrences of platform-independent newlines (CR, LF, and CR+LF [1]), including a last line with neither. An empty file has zero lines.

Usage

## Default S3 method:
countLines(file, chunkSize=5e+07, ...)

Arguments

Details

Both compressed and non-compressed files are supported.

Value

Returns an non-negative integer.

Author(s)

Henrik Bengtsson

References

[1] Page Newline, Wikipedia, July 2008. https://en.wikipedia.org/wiki/Newline

Examples

pathname <- system.file("NEWS.md", package="R.utils");
n <- countLines(pathname);
n2 <- length(readLines(pathname));
stopifnot(n == n2);

Creates a file atomically

Description

Creates a file atomically by first creating and writing to a temporary file which is then renamed.

Usage

## Default S3 method:
createFileAtomically(filename, path=NULL, FUN, ..., skip=FALSE, overwrite=FALSE,
  backup=TRUE, verbose=FALSE)

Arguments

Value

Returns (invisibly) the pathname.

Author(s)

Henrik Bengtsson

See Also

Internally, pushTemporaryFile() and popTemporaryFile() are used for working toward a temporary file, and pushBackupFile() and popBackupFile() are used for backing up and restoring already existing file.

Examples

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Create a file atomically
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
n <- 10
pathname <- createFileAtomically("foobar.txt", path=tempdir(), FUN=function(pathname) {
  cat(file=pathname, "This file was created atomically.\n")
  cat(file=pathname, "Timestamp: ", as.character(Sys.time()), "\n", sep="")
  for (kk in 1:n) {
    cat(file=pathname, kk, "\n", append=TRUE)
    # Emulate a slow process
    if (interactive()) Sys.sleep(0.1)
  }
  cat(file=pathname, "END OF FILE\n", append=TRUE)
}, overwrite=TRUE)

bfr <- readLines(pathname)
cat(bfr, sep="\n")


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Overwrite the file atomically (emulate write failure)
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
tryCatch({
  pathname <- createFileAtomically("foobar.txt", path=tempdir(), FUN=function(pathname) {
    cat(file=pathname, "Trying to create a new file.\n")
    cat(file=pathname, "Writing a bit, but then an error...\n", append=TRUE)
    # Emulate write error
    stop("An error occured while writing to the new file.")
    cat(file=pathname, "END OF FILE\n", append=TRUE)
  }, overwrite=TRUE)
}, error = function(ex) {
  print(ex$message)
})

# The original file was never overwritten
bfr2 <- readLines(pathname)
cat(bfr2, sep="\n")
stopifnot(identical(bfr2, bfr))

# The partially temporary file remains
pathnameT <- sprintf("%s.tmp", pathname)
stopifnot(isFile(pathnameT))
bfr3 <- readLines(pathnameT)
cat(bfr3, sep="\n")

file.remove(pathnameT)
file.remove(pathname)

Creates a link to a file or a directory

Description

Creates a link to a file or a directory. This method tries to create a link to a file/directory on the file system, e.g. a symbolic link and Windows Shortcut links. It depends on operating and file system (and argument settings), which type of link is finally created, but all this is hidden internally so that links can be created the same way regardless of system.

Usage

## Default S3 method:
createLink(link=".", target, skip=!overwrite, overwrite=FALSE,
  methods=getOption("createLink/args/methods", c("unix-symlink", "windows-ntfs-symlink",
  "windows-shortcut")), ...)

Arguments

Value

Returns (invisibly) the path or pathname to the link. If no link was created, NULL is returned.

Required privileges on Windows

In order for method="unix-symlink" (utilizing file.symlink()), method="windows-ntfs-symlink" (utilizing executable mklink), and/or method="windows-shortcut" (utilizing createWindowsShortcut()) to succeed on Windows, the client/R session must run with sufficient privileges (it has been reported that Administrative rights are necessary).

Author(s)

Henrik Bengtsson

References

Ben Garrett, Windows File Junctions, Symbolic Links and Hard Links, September 2009 [https://devtidbits.com/2009/09/07/windows-file-junctions-symbolic-links-and-hard-links/]

See Also

createWindowsShortcut() and file.symlink()

Creates a Microsoft Windows Shortcut (.lnk file)

Description

Creates a Microsoft Windows Shortcut (.lnk file).

Usage

## Default S3 method:
createWindowsShortcut(pathname, target, overwrite=FALSE, mustWork=FALSE, ...)

Arguments

Value

Returns (invisibly) the pathname.

Required privileges on Windows

In order for this method, which utilizes Windows Script Host a VBScript, to succeed on Windows, the client/R session must run with sufficient privileges (it has been reported that Administrative rights are necessary).

Author(s)

Henrik Bengtsson

References

[1] Create a windows shortcut (.LNK file), SS64.com, https://ss64.com/nt/shortcut.html

See Also

readWindowsShortcut()

Examples

# Create Windows Shortcut links to a directory and a file
targets <- list(
  system.file(package="R.utils"),
  system.file("DESCRIPTION", package="R.utils")
)

for (kk in seq_along(targets)) {
  cat("Link #", kk, "\n", sep="")

  target <- targets[[kk]]
  cat("Target: ", target, "\n", sep="")

  # Name of *.lnk file
  pathname <- sprintf("%s.LNK", tempfile())

  tryCatch({
    # Will only work on Windows systems with support for VB scripting
    createWindowsShortcut(pathname, target=target)
  }, error = function(ex) {
    print(ex)
  })

  # Was it created?
  if (isFile(pathname)) {
    cat("Created link file: ", pathname, "\n", sep="")

    # Validate that it points to the correct target
    dest <- filePath(pathname, expandLinks="any")
    cat("Available target: ", dest, "\n", sep="")

    res <- all.equal(tolower(dest), tolower(target))
    if (!isTRUE(res)) {
      msg <- sprintf("Link target does not match expected target: %s != %s", dest, target)
      cat(msg, "\n")
      warning(msg)
    }

    # Cleanup
    file.remove(pathname)
  }
}

Allocates a data frame with given column classes

Description

Allocates a data frame with given column classes.

Usage

## Default S3 method:
dataFrame(colClasses, nrow=1, ...)

Arguments

Value

Returns an NxK data.frame where N equals nrow and K equals length(colClasses).

See Also

data.frame.

Examples

  df <- dataFrame(colClasses=c(a="integer", b="double"), nrow=10)
  df[,1] <- sample(1:nrow(df))
  df[,2] <- rnorm(nrow(df))
  print(df)

Detaches packages by name

Description

Detaches packages by name, if loaded.

Usage

## Default S3 method:
detachPackage(pkgname, ...)

Arguments

Value

Returns (invisibly) a named logical vector indicating whether each package was detached or not.

Author(s)

Henrik Bengtsson

See Also

detach().

Sets the dimension of an object with the option to infer one dimension automatically

Description

Sets the dimension of an object with the option to infer one dimension automatically. If one of the elements in the dimension vector is NA, then its value is inferred from the length of the object and the other elements in the dimension vector. If the inferred dimension is not an integer, an error is thrown.

Usage

## Default S3 replacement method:
dimNA(x) <- value

Arguments

Value

Returns (invisibly) what dim<-() returns (see dim() for more details).

Author(s)

Henrik Bengtsson

See Also

dim().

Examples

  x <- 1:12
  dimNA(x) <- c(2,NA,3)
  stopifnot(dim(x) == as.integer(c(2,2,3)))

Displays the contents of a text file with line numbers and more

Description

Displays the contents of a text file with line numbers and more.

Usage

## Default S3 method:
displayCode(con=NULL, code=NULL, numerate=TRUE, lines=-1, wrap=79, highlight=NULL,
  pager=getOption("pager"), ...)

Arguments

Value

Returns (invisibly) the formatted code as a character string.

Author(s)

Henrik Bengtsson

See Also

file.show().

Examples

file <- system.file("DESCRIPTION", package="R.utils")
cat("Displaying: ", file, ":\n", sep="")
displayCode(file)

file <- system.file("NEWS.md", package="R.utils")
cat("Displaying: ", file, ":\n", sep="")
displayCode(file, numerate=FALSE, lines=100:110, wrap=65)

file <- system.file("NEWS.md", package="R.utils")
cat("Displaying: ", file, ":\n", sep="")
displayCode(file, lines=100:110, wrap=65, highlight=c(101,104:108))

Executes a function call with option to ignore unused arguments

Description

Executes a function call with option to ignore unused arguments.

Usage

## Default S3 method:
doCall(.fcn, ..., args=NULL, alwaysArgs=NULL, .functions=list(.fcn),
  .ignoreUnusedArgs=TRUE, envir=parent.frame())

Arguments

Author(s)

Henrik Bengtsson

See Also

do.call().

Examples

  doCall("plot", x=1:10, y=sin(1:10), col="red", dummyArg=54,
         alwaysArgs=list(xlab="x", ylab="y"),
         .functions=c("plot", "plot.xy"))

Downloads a file

Description

Downloads a file.

Usage

## S3 method for class 'character'
downloadFile(url, filename=basename(url), path=NULL, skip=TRUE, overwrite=!skip, ...,
  username=NULL, password=NULL, binary=TRUE, dropEmpty=TRUE, verbose=FALSE)

Arguments

Details

Currently arguments username and password are only used for downloads via URL protocol 'https'. The 'https' protocol requires that either of 'curl' or 'wget' are available on the system.

Value

Returns the local pathname to the downloaded filename, or NULL if no file was downloaded.

Author(s)

Henrik Bengtsson

See Also

Internally download.file is used. That function may generate an empty file if the URL is not available.

Examples

## Not run: 
 pathname <- downloadFile("https://www.r-project.org/index.html", path="www.r-project.org/")
 print(pathname)

## End(Not run)

Draws a density curve

Description

Draws a density curve along one of the sides of the current plotting region.

Usage

## S3 method for class 'density'
draw(object, side=1, height=0.2, offset=0, scale=c("absolute", "relative"), xtrim=NULL,
  xpd=TRUE, ...)

Arguments

Value

Returns the drawn 'density' object (with the 'x' and 'y' coordinates as plotted).

Author(s)

Henrik Bengtsson

See Also

See density for estimating densities. Internally *swapXY() may be used.

Gets a variable by name

Description

Gets a variable by name. If non-existing, the default value is returned.

Usage

eget(..., coerce=TRUE, envir=parent.frame(), inherits=FALSE, mode="default",
  cmdArg=FALSE)

Arguments

Details

ecget(...) is short for eget(..., cmdArg=TRUE).

Value

Returns an object.

Author(s)

Henrik Bengtsson

See Also

To retrieve command-line arguments, see cmdArg. See also mget().

Examples

# Get variable 'a' if it exists, otherwise return the default value.
value <- eget("a", default=42L)
print(value) # 42L

# Short version doing the same
value <- eget(a=42L)
print(value) # 42L

# Same, but look for the variable in 'envir' (here a list)
value <- eget("a", default=42L, envir=list(a=1))
print(value) # 1L

# Get variable 'n', which defaults to command-line argument
# 'n' ('-n' or '--n'), which in turn defaults to 42L.
value <- eget(n=cmdArg(n=42L))
print(value)

# Equivalently.
value <- ecget(n=42L)
print(value)

Global substitute of expression using regular expressions

Description

Global substitute of expression using regular expressions.

Usage

egsub(pattern, replacement, x, ..., value=TRUE, envir=parent.frame(), inherits=TRUE)

Arguments

Value

Returns an expression.

Author(s)

Henrik Bengtsson

Examples

# Original expression
expr <- substitute({
  res <- foo.bar.yaa(2)
  print(res)
  R.utils::use("R.oo")
  x <- .b.
})

# Some predefined objects
foo.bar.yaa <- function(x) str(x)
a <- 2
b <- a

# Substitute with variable name
expr2 <- egsub("^[.]([a-zA-Z0-9_.]+)[.]$", "\\1", expr, value=FALSE)
print(expr2)
## {
##     res <- foo.bar.yaa(2)
##     print(res)
##     R.utils::use("R.oo")
##     x <- b
## }

# Substitute with variable value
expr3 <- egsub("^[.]([a-zA-Z0-9_.]+)[.]$", "\\1", expr, value=TRUE)
print(expr3)
## {
##     res <- foo.bar.yaa(2)
##     print(res)
##     R.utils::use("R.oo")
##     x <- 2
## }
# Substitute the body of a function
warnifnot <- egsub("stop", "warning", stopifnot, value=FALSE)
print(warnifnot)
warnifnot(pi == 3.14)

Writes a message and indents the following output

Description

Writes a message and indents the following output. The output is indented according to *enter()/*exit() calls.

Usage

  ## S3 method for class 'Verbose'
enter(this, ..., indent=this$indentStep, sep="", suffix="...", level=this$defaultLevel)
  ## S3 method for class 'Verbose'
enterf(this, fmtstr, ..., indent=this$indentStep, sep="", suffix="...",
  level=this$defaultLevel)

Arguments

Value

Returns nothing.

Author(s)

Henrik Bengtsson

See Also

For more information see Verbose.

Creates a new environment, evaluates an expression therein, and returns the environment

Description

Creates a new environment, evaluates an expression therein, and returns the environment.

Usage

env(..., hash=FALSE, parent=parent.frame(), size=29L)

Arguments

Value

Returns an environment.

Author(s)

Henrik Bengtsson

References

[1] R-devel thread 'Create an environment and assign objects to it in one go?' on March 9-10, 2011.

See Also

Internally new.env() and evalq() are used.

Examples

x <- list();

x$case1 <- env({
 # Cut'n'pasted from elsewhere
 a <- 1;
 b <- 2;
});

x$case2 <- env({
 # Cut'n'pasted from elsewhere
 foo <- function(x) x^2;
 a <- foo(2);
 b <- 1;
 rm(foo); # Not needed anymore
});

# Turn into a list of lists
x <- lapply(x, FUN=as.list);

str(x);

Checks if this object is equal to another Options object

Description

Checks if this object is equal to another Options object.

Usage

## S3 method for class 'Options'
equals(this, other, ...)

Arguments

Value

Returns TRUE if they are equal, otherwise FALSE.

Author(s)

Henrik Bengtsson

See Also

For more information see Options.

Checks if this object is equal to another

Description

Checks if this object is equal to another.

Usage

## S3 method for class 'Verbose'
equals(this, other, ...)

Arguments

Value

Returns TRUE if they are equal, otherwise FALSE.

Author(s)

Henrik Bengtsson

See Also

For more information see Verbose.

Parses and evaluates a GString

Description

Parses and evaluates a GString.

Usage

## S3 method for class 'GString'
evaluate(object, envir=parent.frame(), ...)

Arguments

Value

Returns a character string.

Author(s)

Henrik Bengtsson

See Also

For more information see GString.

Evaluates a function and prints its results if above threshold

Description

Evaluates a function and prints its results if above threshold. The output is not indented.

Usage

## S3 method for class 'Verbose'
evaluate(this, fun, ..., level=this$defaultLevel)

Arguments

Value

Returns nothing.

Author(s)

Henrik Bengtsson

See Also

For more information see Verbose.

Writes a message and unindents the following output

Description

Writes a message and unindents the following output. The output is indented according to *enter()/*exit() calls.

Usage

## S3 method for class 'Verbose'
exit(this, ..., indent=-this$indentStep, sep="", suffix="...done", level=NULL)

Arguments

Value

Returns nothing.

Author(s)

Henrik Bengtsson

See Also

For more information see Verbose.

Extract a subset of an array, matrix or a vector with unknown dimensions

Description

Extract a subset of an array, matrix or a vector with unknown dimensions.

This method is useful when you do not know the number of dimensions of the object your wish to extract values from, cf. example.

Usage

## S3 method for class 'array'
extract(x, ..., indices=list(...), dims=names(indices), drop=FALSE)

Arguments

Value

Returns an array.

Author(s)

Henrik Bengtsson

See Also

slice.index()

Examples

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Example using an array with a random number of dimensions
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
maxdim <- 4
dim <- sample(3:maxdim, size=sample(2:maxdim, size=1), replace=TRUE)
ndim <- length(dim)
dimnames <- list()
for (kk in 1:ndim)
  dimnames[[kk]] <- sprintf("%s%d", letters[kk], 1:dim[kk])
x <- 1:prod(dim)
x <- array(x, dim=dim, dimnames=dimnames)

cat("\nArray 'x':\n")
print(x)


cat("\nExtract 'x[2:3,...]':\n")
print(extract(x, "1"=2:3))

cat("\nExtract 'x[3,2:3,...]':\n")
print(extract(x, "1"=3,"2"=2:3))

cat("\nExtract 'x[...,2:3]':\n")
print(extract(x, indices=2:3, dims=length(dim(x))))



# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Assertions
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
y <- array(1:24, dim=c(2,3,4))
yA <- y[,,2:3]
yB <- extract(y, indices=list(2:3), dims=length(dim(y)))
stopifnot(identical(yB, yA))

yA <- y[,2:3,2]
yB <- extract(y, indices=list(2:3,2), dims=c(2,3), drop=TRUE)
stopifnot(identical(yB, yA))

Extract File Information (acknowledging symbolic file links also on Windows)

Description

Extract File Information (acknowledging symbolic file links also on Windows).

Usage

file.info2(...)

Arguments

Value

A data.frame. See file.info() for details.

Author(s)

Henrik Bengtsson

See Also

Internally, file.info() is used, which does not respect symbolic links on Windows. Instead, on Windows, Sys.readlink2() is used for such link to identify the target file and retrieve the file information on that instead.

Checks the permission of a file or a directory

Description

Checks the permission of a file or a directory.

Usage

## Default S3 method:
fileAccess(pathname, mode=0, safe=TRUE, ...)

Arguments

Details

In R there is file.access() for checking whether the permission of a file. Unfortunately, that function cannot be 100% trusted depending on platform used and file system queried, cf. [1].

Value

Returns an integer; 0 if the permission exists, -1 if not.

Symbolic links

This function follows symbolic links (also on Windows) and returns a value based on the link target (rather than the link itself).

Author(s)

Henrik Bengtsson

References

[1] R-devel thread file.access() on network (mounted) drive on Windows Vista? on Nov 26, 2008. https://stat.ethz.ch/pipermail/r-devel/2008-December/051461.html
[2] Filesystem permissions, Wikipedia, 2010. https://en.wikipedia.org/wiki/Filesystem_permissions

See Also

file.access()

Examples

# - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Current directory
# - - - - - - - - - - - - - - - - - - - - - - - - - - - -
path <- "."

# Test for existence
print(fileAccess(path, mode=0))
# Test for execute permission
print(fileAccess(path, mode=1))
# Test for write permission
print(fileAccess(path, mode=2))
# Test for read permission
print(fileAccess(path, mode=4))


# - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# A temporary file
# - - - - - - - - - - - - - - - - - - - - - - - - - - - -
pathname <- tempfile()
cat(file=pathname, "Hello world!")

# Test for existence
print(fileAccess(pathname, mode=0))
# Test for execute permission
print(fileAccess(pathname, mode=1))
# Test for write permission
print(fileAccess(pathname, mode=2))
# Test for read permission
print(fileAccess(pathname, mode=4))

file.remove(pathname)


# - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# The 'base' package directory
# - - - - - - - - - - - - - - - - - - - - - - - - - - - -
path <- system.file(package="base")

# Test for existence
print(fileAccess(path, mode=0))
# Test for execute permission
print(fileAccess(path, mode=1))
# Test for write permission
print(fileAccess(path, mode=2))
# Test for read permission
print(fileAccess(path, mode=4))


# - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# The 'base' package DESCRIPTION file
# - - - - - - - - - - - - - - - - - - - - - - - - - - - -
pathname <- system.file("DESCRIPTION", package="base")

# Test for existence
print(fileAccess(pathname, mode=0))
# Test for execute permission
print(fileAccess(pathname, mode=1))
# Test for write permission
print(fileAccess(pathname, mode=2))
# Test for read permission
print(fileAccess(pathname, mode=4))

Construct the path to a file from components and expands Windows Shortcuts along the pathname from root to leaf

Description

Construct the path to a file from components and expands Windows Shortcuts along the pathname from root to leaf. This function is backward compatible with file.path() when argument removeUps=FALSE and expandLinks="none", except that a (character) NA is return if any argument is NA.

This function exists on all platforms, not only Windows systems.

Usage

## Default S3 method:
filePath(..., fsep=.Platform$file.sep, removeUps=TRUE,
  expandLinks=c("none", "any", "local", "relative", "network"), unmap=FALSE,
  mustExist=FALSE, verbose=FALSE)

Arguments