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

In natverse/nat: NeuroAnatomy Toolbox for Analysis of 3D Image Data

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)

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

Details

if a format argument is passed to fileformats it will be matched with partial string matching and iif 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.

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.

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 supplied 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.

See Also

write.neuron

Examples

# information about the currently registered file formats
fileformats(rval='info')
## Not run: 
registerformat("swc",read=read.swc,write=read.swc,magic=is.swc,magiclen=10,
  class='neuron')

## End(Not run)
swc=tempfile(fileext = '.swc')
write.neuron(Cell07PNs[[1]], swc)
stopifnot(isTRUE(getformatreader(swc)$format=='swc'))
unlink(swc)

natverse/nat documentation built on Feb. 19, 2024, 7:19 a.m.