Справка по API

# FileIO.FileIO — Module

FileIO API (краткое описание, более подробную информацию см. в отдельных функциях):

format"PNG": указывает определенный формат.
File{fmt} и Stream{fmt}: типы объектов, объявляющие, что ресурс имеет определенный формат fmt.
load([filename|stream]): считывает данные из форматированного файла с выводом его формата.
load(File{format"PNG"}(filename)): указание формата вручную.
loadstreaming([filename|stream]): аналогично load, но возвращает объект, из которого можно считывать данные.
save(filename, data...): для аналогичных операций, связанных с сохранением данных.
savestreaming([filename|stream]): аналогично save, но возвращает объект, в который можно записывать данные.
io = open(f::File, args...): открывает файл.
io = stream(s::Stream): возвращает IOStream из объекта запроса s.
query([filename|stream]): пытается вывести формат файла filename.
unknown(q): возвращает true, если разрешить запрос не удается.
skipmagic(io, fmt): устанавливает позицию в io сразу после магических байтов.
magic(fmt): возвращает магические байты для формата fmt.
info(fmt): возвращает (magic, extensions) для формата fmt.
add_format(fmt, magic, extension, libraries...): регистрирует новый формат.
add_loader(fmt, :Package): указывает, что Package поддерживает загрузку файлов типа fmt.
add_saver(fmt, :Package): указывает, что Package поддерживает сохранение файлов типа fmt.

# FileIO.DataFormat — Type

DataFormat{sym}(): указывает известный двоичный или текстовый формат типа sym, где sym — это всегда символ. Например, файл CSV может иметь формат DataFormat{:CSV}().

Простой способ записи DataFormat{:CSV} — format"CSV".

# FileIO.File — Type

File{fmt}(filename) указывает, что filename — это файл известного формата DataFormat fmt. Например, File{format"PNG"}(filename) означает файл PNG.

Совместимость

Для File{fmt}(filename) требуется версия не ниже FileIO 1.6. Устаревший синтаксис File(fmt, filename) работает во всех выпусках FileIO 1.x.

# FileIO.Stream — Type

Stream{fmt}(io, filename=nothing) указывает, что поток io записывается в известном формате DataFormat fmt. Например, Stream{format"PNG"}(io) означает формат PNG. С помощью необязательного аргумента filename, если его значение известно, можно улучшать сообщения об ошибках и т. д.

Совместимость

Для Stream{fmt}(io, ...) требуется версия не ниже FileIO 1.6. Устаревший синтаксис Stream(fmt, io, ...) работает во всех выпусках FileIO 1.x.

# FileIO.add_format — Method

add_format(fmt, magic, extension) регистрирует новый формат DataFormat. Пример:

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"])

Имейте в виду, что в расширениях, магических числах и идентификаторах форматов учитывается регистр.

Указать пакеты, которые поддерживают формат, можно также с помощью вызова add_format(fmt, magic, extension, pkgspecifiers...), например, с такими значениями pkgspecifiers:

add_format(fmt, magic, extension, [:PkgA=>UUID(...)])                     # формат поддерживается только пакетом PkgA (загрузка и сохранение)
add_format(fmt, magic, extension, [:PkgA=>uuidA], [:PkgB=>uuidB])         # сначала пробуем использовать PkgA, но если не получается, пробуем PkgB
add_format(fmt, magic, extension, [:PkgA=>uuidA, LOAD], [:PkgB=>uuidB])   # сначала пробуем использовать PkgA для операции `load`; если не получается, используем PkgB
add_format(fmt, magic, extension, [:PkgA=>uuidA, OSX], [:PkgB=>uuidB])    # используем PkgA в OSX и PkgB в остальных случаях

Все значения uuid имеют тип UUID и могут быть получены из файла Project.toml пакета.

Для сужения pkgspecifiers можно сочетать LOAD, SAVE, OSX, Unix, Windows и Linux произвольными способами.

# FileIO.add_loader — Function

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

Объявляет, что формат fmt может быть загружен с помощью пакета :Package. Спецификаторы (OSX, Unix, Windows и Linux) ограничивают применимость определенными операционными системами.

См. также описание метода add_format, который позволяет одновременно и объявлять формат, и указывать поддерживаемые пакеты.

# FileIO.add_saver — Function

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

Объявляет, что формат fmt может быть сохранен с помощью пакета :Package. Спецификаторы (OSX, Unix, Windows и Linux) ограничивают применимость определенными операционными системами.

# FileIO.del_format — Method

del_format(fmt::DataFormat) удаляет fmt из реестра форматов.

# FileIO.file_extension — Method

file_extension(file) возвращает расширение файла, ассоциированное с File file.

# FileIO.file_extension — Method

file_extension(file) возвращает строку (в том числе нулевую) для расширения файла, ассоциированного с Stream stream.

# FileIO.filename — Method

filename(file) возвращает имя файла, ассоциированное с File file.

# FileIO.filename — Method

filename(stream) возвращает строку с именем файла, связанного с Stream stream, или nothing, если связанного файла нет.

# FileIO.load — Function

load(filename) загружает содержимое форматированного файла, пытаясь вывести формат из filename и (или) магических байтов в файле (см. описание функции query).
load(strm) загружает данные из IOStream или аналогичного объекта. В данном случае расширения имени файла нет, поэтому формат распознается на основе магических байтов.
load(File{format"PNG"}(filename)) задает формат напрямую; формат из query игнорируется.
load(Stream{format"PNG"}(io)) задает формат напрямую; формат из query игнорируется.
load(f; options...) передает именованные аргументы в метод загрузки.

# FileIO.loadstreaming — Function

Некоторые пакеты могут реализовывать API потоковой передачи, позволяющий записывать и обрабатывать содержимое файла по частям, а не сразу. При считывании из таких высокоуровневых потоков должен возвращаться форматированный объект, например изображение либо фрагмент видео или аудио.

loadstreaming(filename) загружает содержимое форматированного файла, пытаясь вывести формат из filename и (или) магических байтов в файле. Возвращает тип потока, из которого можно считывать данные по частям, а не загружать все содержимое сразу.
loadstreaming(strm) загружает поток из IOStream или аналогичного объекта. В данном случае расширения имени файла нет, поэтому формат распознается на основе магических байтов.
loadstreaming(File{format"WAV"}(filename)) задает формат напрямую; формат из query игнорируется.
loadstreaming(Stream{format"WAV"}(io)) задает формат напрямую; формат из query игнорируется.
loadstreaming(f; options...) передает именованные аргументы в метод загрузки.

# FileIO.magic — Method

magic(fmt): возвращает магические байты формата fmt.

# FileIO.query — Function

query(io, [filename]) возвращает объект Stream с информацией о формате, выведенном на основе магических байтов.

# FileIO.query — Method

query(filename; checkfile=true)

Возвращает объект File с информацией о формате, выведенном на основе расширения имени файла и (или) магических байтов. Если filename уже существует, магические байты файла имеют приоритет, кроме случая, когда аргумент checkfile имеет значение false.

# FileIO.save — Function

save(filename, data...) сохраняет содержимое форматированного файла, пытаясь вывести формат из filename.
save(Stream{format"PNG"}(io), data...) задает формат напрямую; формат из query игнорируется.
save(File{format"PNG"}(filename), data...) задает формат напрямую; формат из query игнорируется.
save(f, data...; options...) передает именованные аргументы в метод сохранения.

# FileIO.savestreaming — Function

Некоторые пакеты могут реализовывать API потоковой передачи, позволяющий записывать содержимое файла по частям, а не сразу. Такие высокоуровневые потоки должны принимать форматированные объекты, например изображение либо фрагмент видео или аудио.

savestreaming(filename, data...) сохраняет содержимое форматированного файла, пытаясь вывести формат из filename.
savestreaming(File{format"WAV"}(filename)) задает формат напрямую; формат из query игнорируется.
savestreaming(Stream{format"WAV"}(io)) задает формат напрямую; формат из query игнорируется.
savestreaming(f, data...; options...) передает именованные аргументы в метод сохранения.

# FileIO.skipmagic — Method

skipmagic(s::Stream): устанавливает позицию в s сразу после магических байтов. Для обычного объекта IO можно использовать skipmagic(io, fmt).

# FileIO.stream — Method

stream(s) возвращает поток, связанный с объектом Stream s.

# FileIO.unknown — Method

unknown(f) возвращает true, если формат f неизвестен.