IOException: The IOException heierarchy.

In jefferys/Exception: Classed exception object hierarchy

Description

IOExceptions and their sub-classes are Exceptions that describe problems encoutered reading or writting to a file, network socket, console, connection, etc. Subclasses extended the specificity of the IOException and can include data elements. See Exception. These exceptions are intended to be signaled, i.e. with stop and exist both to provide pre-defined error messages and so that handlers in try/catch blocks have latitude to choose what granularity of exception to catch.

Usage

IOException(message = "*", call = NULL, package = packageName(), ...)

FileSystemException(message = "*", call = NULL, package = packageName(),
  ...)

PathException(path, message = "*", call = NULL, package = packageName(),
  ...)

FileException(path, message = "*", call = NULL, package = packageName(),
  ...)

DirectoryException(path, message = "*", call = NULL,
  package = packageName(), ...)

LinkException(path, target, message = "*", call = NULL,
  package = packageName(), ...)

NoSuchLinkTargetException(path, target, message = "*", call = NULL,
  package = packageName(), ...)

NoSuchFileException(path, message = "*", call = NULL,
  package = packageName(), ...)

NoSuchDirectoryException(path, message = "*", call = NULL,
  package = packageName(), ...)

NoSuchLinkException(path, target = NA, message = "*", call = NULL,
  package = packageName(), ...)

FileExistsException(path, message = "*", call = NULL,
  package = packageName(), ...)

DirectoryExistsException(path, message = "*", call = NULL,
  package = packageName(), ...)

LinkExistsException(path, target, message = "*", call = NULL,
  package = packageName(), ...)

Arguments

message	The message associated with the exception, for reading by humans. The default message is usually good enough, but can be overriden through this parameter if needed. When constructed inside packages, the message displayed will have the name of the package prepended as '[package] message' due to conditionMessage being over-ridden for Exception subclasses.
call	The call or call stack associated with the exception. By default this is NULL as IOExceptions are usually environment problems. Can be overriden to provide the sys.calls call stack or a single sys.call.
package	The package where this exception is generated. May be NULL when exceptions are generated and signaled from interactive or script level code and not from a package. Attempts to guess the package by default. Will usually include the package in the dispalyed message.
...	Additional arguments defining arg= value data to include in the Exception (accessible as list elements, but preferably by S3 accessor functions).
path	The path associated with an exception, as a one element character vector This is required for a PathException or sub-class, but may be NULL or NA. Accessible via the the exceptionPath S3 accessor.
target	The target associated with a problematic file system link. This is required for a LinkException or sub-class, but may be NULL or NA. Accessible via the the exceptionTarget S3 accessor

Value

An IOException or descendant describing some problematic event involving a file system, a network socket, etc. Always has or extends class c( "IOException", "Exception", "condition" ).

Functions

• IOException: This exception and sub-classes are Exceptions that describe problems encoutered reading or writting to a file, network socket, console, connection, etc.

  • message: "[package] An IOException occurred.

  • class: c( "IOException", "Exception", "condition" )

  • data: None

• FileSystemException: This exception and sub-classes are Exceptions that describe problems encoutered reading or writting to a file system, disk, etc.

  • message: "[package] A FileSystemException occurred."

  • class: c( "FileSystemException", "IOException", "Exception", "condition" )

  • data: None

• PathException: This exception and sub-classes are FileSystemExceptions that describe problems encoutered in the context of an operation on a file system path. Always includes a "path" data element, accessible with exceptionPath.

  • message: '[package] A PathException occurred involving path: "path". (Running in: "getwd()").'

  • class: c( "PathException", "FileSystemException", "IOException", "Exception", "condition" )

  • data: path - see exceptionPath.

• FileException: This exception and sub-classes are PathExceptions that describe problems reading, writing, creating, or deleting a file (not a directory). Always includes a "path" data element, accessible with exceptionPath. Issues with the contents of a file are not IOExceptions, those are likely DataFormatExceptions or DataValueExceptions. The path may be a valid link to a file, or a nested series of links, but this should be transparent. The code generating the exception should identify LinkExceptions separately.

  • message: '[package] A FileException occurred involving file: "path". (Running in: "getwd()").'

  • class: c( "FileException", "PathException", "FileSystemException", "IOException", "Exception", "condition" )

  • data: path - see exceptionPath.

• DirectoryException: This exception and sub-classes are PathExceptions that describe problems reading, writing, creating, or deleting a directory. Always includes a "path" data element, accessible with exceptionPath. The path may be a valid link to a directory, or a nested series of links, but this should be transparent. The code generating the exception should identify LinkExceptions separately.

  • message: '[package] A DirectoryException occurred involving directory: "path". (Running in: "getwd()").'

  • class: c( "DirectoryException", "PathException", "FileSystemException", "IOException", "Exception", "condition" )

  • data: path - see exceptionPath.

• LinkException: This exception and sub-classes are PathExceptions that describe problems creating, deleating, or using a hard or soft/symbolic link to a file system object. Always includes a "path" data element, accessible with exceptionPath and a "target" data element, accessible with exceptionTarget. Problems with the target (so long as it exists) are not a problem with the link but a problem with the target only. The fact that the path is a link should be ignored in this case and the exception should be based on the target object (file, directory, or possibly a link.)

  • message: '[package] A LinkException occurred involving link: "path" with target: "target". (Running in: "getwd()").'

  • class: c( "LinkException", "PathException", "FileSystemException", "IOException", "Exception", "condition" )

  • data: path - see exceptionPath.

  • data: target - see exceptionTarget.

• NoSuchLinkTargetException: If a link's target is invalid

  • message: '[package] The link target does not exist; link: "path" with target: "target". (Running in: "getwd()").'

  • class: c( "NoSuchLinkTargetException", "LinkException", "PathException", "FileSystemException", "IOException", "Exception", "condition" )

  • data: path - see exceptionPath.

  • data: target - see exceptionTarget.

• NoSuchFileException: The specified file was not found on the file system.

  • message: '[package] No such file: "path". (Running in: "getwd()").'

  • class: c( "NoSuchFileException", "FileException", "PathException", "FileSystemException", "IOException", "Exception", "condition" )

  • data: path - see exceptionPath.

• NoSuchDirectoryException: The specified directory was not be found on the file system.

  • message: '[package] No such directory: "path". (Running in: "getwd()").'

  • class: c( "NoSuchDirectoryException", "DirectoryException", "PathException", "FileSystemException", "IOException", "Exception", "condition" )

  • data: path - see exceptionPath.

• NoSuchLinkException: The specified link was not be found on the file system. Should only be used when the path is expected by the user to be a link. Usually a link is used transparently to identify a file or directory, in which case a NoSuchFileException or NoSuchDirectoryException should be used.

  • message: '[package] No such link: "path". (Running in: "getwd()").'

  • class: c( "NoSuchLinkException", "LinkException", "PathException", "FileSystemException", "IOException", "Exception", "condition" )

  • data: path - see exceptionPath.

  • data: target - see exceptionTarget.

• FileExistsException: The specified file already exists on the file system.

  • message: '[package] File already exists: "path". (Running in: "getwd()").'

  • class: c( "FileExistsException", "FileException", "PathException", "FileSystemException", "IOException", "Exception", "condition" )

  • data: path - see exceptionPath.

• DirectoryExistsException: The specified directory already existins on the file system.

  • message: '[package] Directory already exists: "path". (Running in: "getwd()").'

  • class: c( "DirectoryExistsException", "DirectoryException", "PathException", "FileSystemException", "IOException", "Exception", "condition" )

  • data: path - see exceptionPath.

• LinkExistsException: The specified link already exists on the file system. Should only be used when the path is expected by the user to be a link. Usually a link is used transparently to identify a file or directory, in which case a FileExistsException or DirectoryExistsException should be used.

  • message: '[package] Link already exists: "path". (Running in: "getwd()").'

  • class: c( "LinkExistsException", "LinkException", "PathException", "FileSystemException", "IOException", "Exception", "condition" )

  • data: path - see exceptionPath.

  • data: target - see exceptionTarget.

See Also

condition, conditionMessage(), conditionCall, Exception, exceptionPackage

Examples

ioEx <- IOException()
conditionMessage(ioEx)
conditionCall(ioEx)
exceptionPackage(ioEx)

ioEx <- IOException( "Including the call stack", call=sys.calls() )
ioEx <- IOException( "Lying about the package", package="NotMine" )
ioEx <- IOException( "Extra data included", x=1, y=list(A=1, B="two"), path="../" )
x <- ioEx$x
y <- ioEx$y
path <- exceptionPath(ioEx)
path == ioEx$path

pEx <- PathException( "/some/path" )
thePath <- exceptionPath(pEx)

## Not run: 
  wantToCreate <- "theFile"
  if ( file.exists( wantToCreate )) {
     if (is.dir) { stop( DirectoryExists( wantToCreate )) }
     else { stop( FileExists( wantToCreate )) }
  }

## End(Not run)

jefferys/Exception documentation built on May 19, 2019, 3:59 a.m.