Документация Engee

Справка по API

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.

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

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

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

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

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

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.

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 произвольными способами.

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

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

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

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

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

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

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

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

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

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

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

  • load(filename) загружает содержимое форматированного файла, пытаясь вывести формат из filename и (или) магических байтов в файле (см. описание функции query).

  • load(strm) загружает данные из IOStream или аналогичного объекта. В данном случае расширения имени файла нет, поэтому формат распознается на основе магических байтов.

  • load(File{format"PNG"}(filename)) задает формат напрямую; формат из query игнорируется.

  • load(Stream{format"PNG"}(io)) задает формат напрямую; формат из query игнорируется.

  • load(f; options...) передает именованные аргументы в метод загрузки.

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

  • loadstreaming(filename) загружает содержимое форматированного файла, пытаясь вывести формат из filename и (или) магических байтов в файле. Возвращает тип потока, из которого можно считывать данные по частям, а не загружать все содержимое сразу.

  • loadstreaming(strm) загружает поток из IOStream или аналогичного объекта. В данном случае расширения имени файла нет, поэтому формат распознается на основе магических байтов.

  • loadstreaming(File{format"WAV"}(filename)) задает формат напрямую; формат из query игнорируется.

  • loadstreaming(Stream{format"WAV"}(io)) задает формат напрямую; формат из query игнорируется.

  • loadstreaming(f; options...) передает именованные аргументы в метод загрузки.

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

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

query(filename; checkfile=true)

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

  • save(filename, data...) сохраняет содержимое форматированного файла, пытаясь вывести формат из filename.

  • save(Stream{format"PNG"}(io), data...) задает формат напрямую; формат из query игнорируется.

  • save(File{format"PNG"}(filename), data...) задает формат напрямую; формат из query игнорируется.

  • save(f, data...; options...) передает именованные аргументы в метод сохранения.

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

  • savestreaming(filename, data...) сохраняет содержимое форматированного файла, пытаясь вывести формат из filename.

  • savestreaming(File{format"WAV"}(filename)) задает формат напрямую; формат из query игнорируется.

  • savestreaming(Stream{format"WAV"}(io)) задает формат напрямую; формат из query игнорируется.

  • savestreaming(f, data...; options...) передает именованные аргументы в метод сохранения.

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

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

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