nat (version 1.8.25)

fileformats: Set or return list of registered file formats that we can read

Description

fileformats returns format names, a format definition list or a table of information about the formats that match the given filter conditions.

registerformat registers a format in the io registry

getformatreader gets the function to read a file

getformatwriter gets the function to write a file

Usage

fileformats(
  format = NULL,
  ext = NULL,
  read = NULL,
  write = NULL,
  class = NULL,
  rval = c("names", "info", "all")
)
registerformat(
  format = NULL,
  ext = format,
  read = NULL,
  write = NULL,
  magic = NULL,
  magiclen = NA_integer_,
  class = NULL
)
getformatreader(file, class = NULL)
getformatwriter(format = NULL, file = NULL, ext = NULL, class = NULL)

Value

• fileformats returns a character vector, matrix or list according to the value of rval.

• getformatreader returns a list. The reader can be accessed with $read and the format can be accessed by $format.

• getformatwriter returns a list. The writer can be accessed with $write.

Arguments

format

Character vector naming the format

ext

Character vector of file extensions (including periods)

read, write

Functions to read and write this format

class

The S3 class for the format (character vector e.g. 'neuron')

rval

Character vector choosing what kind of return value fileformats will give.

magic

Function to test whether a file is of this format

magiclen

Optional integer specifying maximum number of bytes required from file header to determine file's type.

file

Path to a file

getformatwriter output file

If getformatwriter is passed a file argument, it will be processed based on the registered fileformats information and the ext argument to give a final output path in the $file element of the returned list.

If ext='.someext' getformatwriter will use the specified extension to overwrite the default value returned by fileformats.

If ext=NULL, the default, and file='somefilename.someext' then file will be untouched and ext will be set to 'someext' (overriding the value returned by fileformats).

If file='somefile_without_extension' then the suppplied or calculated extension will be appended to file.

If ext=NA then the input file name will not be touched (even if it has no extension at all).

Note that if ext=NULL or ext=NA, then only the specified format or, failing that, the file extension will be used to query the fileformats database for a match.

See write.neuron for code to make this discussion more concrete.

Details

if a format argument is passed to fileformats it will be matched with partial string matching and if a unique match exists that will be returned.

getformatreader starts by reading a set number of bytes from the start off the current file and then checks using file extension and magic functions to see if it can identify the file. Presently formats are in a queue in alphabetical order, dispatching on the first match.

See Also

write.neuron

Examples

# information about the currently registered file formats
fileformats(rval='info')
if (FALSE) {
registerformat("swc",read=read.swc,write=read.swc,magic=is.swc,magiclen=10,
  class='neuron')
}
swc=tempfile(fileext = '.swc')
write.neuron(Cell07PNs[[1]], swc)
stopifnot(isTRUE(getformatreader(swc)$format=='swc'))
unlink(swc)