Engee documentation

Reference

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

  • format"PNG": specifies a particular defined format

  • File{fmt} and Stream{fmt}: types of objects that declare that a resource has a particular format fmt

  • load([filename|stream]): read data in formatted file, inferring the format

  • load(File{format"PNG"}(filename)): specify the format manually

  • loadstreaming([filename|stream]): similar to load, except that it returns an object that can be read from

  • save(filename, data...) for similar operations involving saving data

  • savestreaming([filename|stream]): similar to save, except that it returns an object that can be written to

  • io = open(f::File, args...) opens a file

  • io = stream(s::Stream) returns the IOStream from the query object s

  • query([filename|stream]): attempt to infer the format of filename

  • unknown(q) returns true if a query can’t be resolved

  • skipmagic(io, fmt) sets the position of io to just after the magic bytes

  • magic(fmt) returns the magic bytes for format fmt

  • info(fmt) returns (magic, extensions) for format fmt

  • add_format(fmt, magic, extension, libraries...): register a new format

  • add_loader(fmt, :Package): indicate that Package supports loading files of type fmt

  • add_saver(fmt, :Package): indicate that Package supports saving files of type fmt

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

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

Compatibility

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

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.

Compatibility

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

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.

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.

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.

del_format(fmt::DataFormat) deletes fmt from the format registry.

file_extension(file) returns the file extension associated with File file.

file_extension(file) returns a nullable-string for the file extension associated with Stream stream.

filename(file) returns the filename associated with File file.

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

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

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.

magic(fmt) returns the magic bytes of format fmt

query(io, [filename]) returns a Stream object with information about the format inferred from the magic bytes.

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.

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

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.

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

stream(s) returns the stream associated with Stream s

unknown(f) returns true if the format of f is unknown.