Reference

FileIO.FileIOModule

FileIO API (brief summary, see individual functions for more detail):

source
FileIO.DataFormatType
DataFormat{sym}()

Indicates a known binary or text format of kind sym, where sym is always a symbol. For example, a .csv file might have DataFormat{:CSV}().

An easy way to write DataFormat{:CSV} is format"CSV".

source
FileIO.FileType
File{fmt}(filename)

Indicates that filename is a file of known DataFormat fmt. For example, File{format"PNG"}(filename) would indicate a PNG file.

Compat

File{fmt}(filename) requires FileIO 1.6 or higher. The deprecated syntax File(fmt, filename) works on all FileIO 1.x releases.

source
FileIO.StreamType
Stream{fmt}(io, filename=nothing)

Indicates that the stream io is written in known format DataFormat fmt. For example, Stream{format"PNG"}(io) would indicate PNG format. If known, the optional filename argument can be used to improve error messages, etc.

Compat

Stream{fmt}(io, ...) requires FileIO 1.6 or higher. The deprecated syntax Stream(fmt, io, ...) works on all FileIO 1.x releases.

source
FileIO.add_formatMethod
add_format(fmt, magic, extension)

registers a new DataFormat.

For example:

add_format(format"TIFF", (UInt8[0x4d,0x4d,0x00,0x2b], UInt8[0x49,0x49,0x2a,0x00]), [".tiff", ".tif"])
add_format(format"PNG", [0x89,0x50,0x4e,0x47,0x0d,0x0a,0x1a,0x0a], ".png")
add_format(format"NRRD", "NRRD", [".nrrd",".nhdr"])

Note that extensions, magic numbers, and format-identifiers are case-sensitive.

You can also specify particular packages that support the format with add_format(fmt, magic, extension, pkgspecifiers...), where example pkgspecifiers are:

add_format(fmt, magic, extension, [:PkgA=>UUID(...)])                     # only PkgA supports the format (load & save)
add_format(fmt, magic, extension, [:PkgA=>uuidA], [:PkgB=>uuidB])         # try PkgA first, but if it fails try PkgB
add_format(fmt, magic, extension, [:PkgA=>uuidA, LOAD], [:PkgB=>uuidB])   # try PkgA first for `load`, otherwise use PkgB
add_format(fmt, magic, extension, [:PkgA=>uuidA, OSX], [:PkgB=>uuidB])    # use PkgA on OSX, and PkgB otherwise

The uuids are all of type UUID and can be obtained from the package's Project.toml file.

You can combine LOAD, SAVE, OSX, Unix, Windows and Linux arbitrarily to narrow pkgspecifiers.

source
FileIO.add_loaderFunction
add_loader(fmt, :Package=>uuid)
add_loader(fmt, [:Package=>uuid, specifiers...])

Declare that format fmt can be loaded with package :Package. Specifiers include OSX, Unix, Windows and Linux to restrict usage to particular operating systems.

See also add_format which can combine package support with the format declaration.

source
FileIO.add_saverFunction
add_saver(fmt, :Package=>uuid)
add_saver(fmt, [:Package=>uuid, specifiers...])

Declare that format fmt can be saved with package :Package. Specifiers include OSX, Unix, Windows and Linux to restrict usage to particular operating systems.

See also add_format which can combine package support with the format declaration.

source
FileIO.filenameMethod
filename(stream)

Returns a string of the filename associated with Stream stream, or nothing if there is no file associated.

source
FileIO.loadFunction
  • load(filename) loads the contents of a formatted file, trying to infer the format from filename and/or magic bytes in the file (see query).
  • load(strm) loads from an IOStream or similar object. In this case, there is no filename extension, so we rely on the magic bytes for format identification.
  • load(File{format"PNG"}(filename)) specifies the format directly, and bypasses the format query.
  • load(Stream{format"PNG"}(io)) specifies the format directly, and bypasses the format query.
  • load(f; options...) passes keyword arguments on to the loader.
source
FileIO.loadstreamingFunction

Some packages may implement a streaming API, where the contents of the file can be read in chunks and processed, rather than all at once. Reading from these higher-level streams should return a formatted object, like an image or chunk of video or audio.

  • loadstreaming(filename) loads the contents of a formatted file, trying to infer the format from filename and/or magic bytes in the file. It returns a streaming type that can be read from in chunks, rather than loading the whole contents all at once.
  • loadstreaming(strm) loads the stream from an IOStream or similar object. In this case, there is no filename extension, so we rely on the magic bytes for format identification.
  • loadstreaming(File{format"WAV"}(filename)) specifies the format directly, and bypasses the format query.
  • loadstreaming(Stream{format"WAV"}(io)) specifies the format directly, and bypasses the format query.
  • loadstreaming(f; options...) passes keyword arguments on to the loader.
source
FileIO.queryFunction
query(io, [filename])

Returns a Stream object with information about the format inferred from the magic bytes.

source
FileIO.queryMethod
query(filename; checkfile=true)

Return a File object with information about the format inferred from the file's extension and/or magic bytes. If filename already exists, the file's magic bytes will take priority unless checkfile is false.

source
FileIO.saveFunction
  • save(filename, data...) saves the contents of a formatted file, trying to infer the format from filename.
  • save(Stream{format"PNG"}(io), data...) specifies the format directly, and bypasses the format query.
  • save(File{format"PNG"}(filename), data...) specifies the format directly, and bypasses the format query.
  • save(f, data...; options...) passes keyword arguments on to the saver.
source
FileIO.savestreamingFunction

Some packages may implement a streaming API, where the contents of the file can be written in chunks, rather than all at once. These higher-level streams should accept formatted objects, like an image or chunk of video or audio.

  • savestreaming(filename, data...) saves the contents of a formatted file, trying to infer the format from filename.
  • savestreaming(File{format"WAV"}(filename)) specifies the format directly, and bypasses the format query.
  • savestreaming(Stream{format"WAV"}(io)) specifies the format directly, and bypasses the format query.
  • savestreaming(f, data...; options...) passes keyword arguments on to the saver.
source
FileIO.skipmagicMethod
skipmagic(s::Stream)

Sets the position of s to be just after the magic bytes. For a plain IO object, you can use skipmagic(io, fmt).

source
FileIO.infoFunction
info(fmt)

Returns the magic bytes/extension information for fmt.

source