Reference
FileIO.FileIO
— ModuleFileIO
API (brief summary, see individual functions for more detail):
format"PNG"
: specifies a particular defined formatFile{fmt}
andStream{fmt}
: types of objects that declare that a resource has a particular formatfmt
load([filename|stream])
: read data in formatted file, inferring the formatload(File{format"PNG"}(filename))
: specify the format manuallyloadstreaming([filename|stream])
: similar toload
, except that it returns an object that can be read fromsave(filename, data...)
for similar operations involving saving datasavestreaming([filename|stream])
: similar tosave
, except that it returns an object that can be written toio = open(f::File, args...)
opens a fileio = stream(s::Stream)
returns the IOStream from the query objects
query([filename|stream])
: attempt to infer the format offilename
unknown(q)
returns true if a query can't be resolvedskipmagic(io, fmt)
sets the position ofio
to just after the magic bytesmagic(fmt)
returns the magic bytes for formatfmt
info(fmt)
returns(magic, extensions)
for formatfmt
add_format(fmt, magic, extension, libraries...)
: register a new formatadd_loader(fmt, :Package)
: indicate thatPackage
supports loading files of typefmt
add_saver(fmt, :Package)
: indicate thatPackage
supports saving files of typefmt
FileIO.DataFormat
— TypeDataFormat{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"
.
FileIO.File
— TypeFile{fmt}(filename)
Indicates that filename
is a file of known DataFormat
fmt
. For example, File{format"PNG"}(filename)
would indicate a PNG file.
File{fmt}(filename)
requires FileIO 1.6 or higher. The deprecated syntax File(fmt, filename)
works on all FileIO 1.x releases.
FileIO.Stream
— TypeStream{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.
Stream{fmt}(io, ...)
requires FileIO 1.6 or higher. The deprecated syntax Stream(fmt, io, ...)
works on all FileIO 1.x releases.
FileIO.add_format
— Methodadd_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 uuid
s 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
.
FileIO.add_loader
— Functionadd_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.
FileIO.add_saver
— Functionadd_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.
FileIO.del_format
— Methoddel_format(fmt::DataFormat)
deletes fmt
from the format registry.
FileIO.file_extension
— Methodfile_extension(file)
Returns the file extension associated with File
file
.
FileIO.file_extension
— Methodfile_extension(file)
Returns a nullable-string for the file extension associated with Stream
stream
.
FileIO.filename
— Methodfilename(file)
Returns the filename associated with File
file
.
FileIO.filename
— Methodfilename(stream)
Returns a string of the filename associated with Stream
stream
, or nothing if there is no file associated.
FileIO.load
— Functionload(filename)
loads the contents of a formatted file, trying to infer the format fromfilename
and/or magic bytes in the file (seequery
).load(strm)
loads from anIOStream
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 formatquery
.load(Stream{format"PNG"}(io))
specifies the format directly, and bypasses the formatquery
.load(f; options...)
passes keyword arguments on to the loader.
FileIO.loadstreaming
— FunctionSome 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 fromfilename
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 anIOStream
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 formatquery
.loadstreaming(Stream{format"WAV"}(io))
specifies the format directly, and bypasses the formatquery
.loadstreaming(f; options...)
passes keyword arguments on to the loader.
FileIO.magic
— Methodmagic(fmt)
Returns the magic bytes of format fmt
FileIO.query
— Functionquery(io, [filename])
Returns a Stream
object with information about the format inferred from the magic bytes.
FileIO.query
— Methodquery(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.
FileIO.save
— Functionsave(filename, data...)
saves the contents of a formatted file, trying to infer the format fromfilename
.save(Stream{format"PNG"}(io), data...)
specifies the format directly, and bypasses the formatquery
.save(File{format"PNG"}(filename), data...)
specifies the format directly, and bypasses the formatquery
.save(f, data...; options...)
passes keyword arguments on to the saver.
FileIO.savestreaming
— FunctionSome 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 fromfilename
.savestreaming(File{format"WAV"}(filename))
specifies the format directly, and bypasses the formatquery
.savestreaming(Stream{format"WAV"}(io))
specifies the format directly, and bypasses the formatquery
.savestreaming(f, data...; options...)
passes keyword arguments on to the saver.
FileIO.skipmagic
— Methodskipmagic(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)
.
FileIO.stream
— Methodstream(s)
Returns the stream associated with Stream
s
.
FileIO.unknown
— Methodunknown(f)
Returns true if the format of f
is unknown.
FileIO.info
— Functioninfo(fmt)
Returns the magic bytes/extension information for fmt
.