Файл

Этот модуль содержит функции для работы с файлами.

Некоторые из этих функций являются низкоуровневыми, позволяя пользователю взаимодействовать с файлами или устройствами ввода/вывода, например, open/2, copy/3 и другие. Этот модуль также предоставляет функции более высокого уровня, которые работают с именами файлов и имеют имена, основанные на вариантах UNIX. Например, можно скопировать файл с помощью cp/3 и рекурсивно удалить файлы и каталоги с помощью rm_rf/1.

Пути, передаваемые функциям в этом модуле, могут быть относительными к текущей рабочей директории (как возвращается File.cwd/0), или абсолютными путями. Оболочки, такие как ~, не расширяются автоматически. Чтобы использовать пути, такие как ~/Downloads, можно использовать Path.expand/1 или Path.expand/2 для преобразования пути в абсолютный.

Кодировка

Для записи и чтения файлов необходимо использовать функции в модуле IO. По умолчанию файл открывается в двоичном режиме, который требует функций IO.binread/2 и IO.binwrite/2 для взаимодействия с файлом. Разработчик может передать :utf8 в качестве опции при открытии файла, тогда медленные функции IO.read/2 и IO.write/2 должны использоваться, так как они отвечают за правильные преобразования и предоставление надлежащих гарантий данных.

Обратите внимание, что имена файлов, заданные как списки символов в Elixir, всегда обрабатываются как UTF-8. В частности, мы ожидаем, что оболочка и операционная система настроены на использование кодировки UTF-8. Двоичные имена файлов считаются сырыми и передаются в ОС как есть.

API

Большинство функций в этом модуле возвращают :ok или {:ok, result} в случае успеха, {:error, reason} в противном случае. Эти функции также имеют вариант, который заканчивается !, который возвращает результат (вместо кортежа {:ok, result}) в случае успеха или вызывает исключение в случае неудачи. Например:

File.read("hello.txt")
#=> {:ok, "World"}

File.read("invalid.txt")
#=> {:error, :enoent}

File.read!("hello.txt")
#=> "World"

File.read!("invalid.txt")
#=> raises File.Error

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

Процессы и сырые файлы

Каждый раз при открытии файла Elixir запускает новый процесс. Запись в файл эквивалентна отправке сообщений процессу, который записывает в дескриптор файла.

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

Однако, вы не всегда захотите платить за эту абстракцию. В таких случаях файл можно открыть в :raw режиме. Опции :read_ahead и :delayed_write также полезны при работе с большими файлами или работе с файлами в тесных циклах.

См. :file.open/2 для получения дополнительной информации об этих опциях и других соображениях производительности.

Сводка

Функции

cd(path): Устанавливает текущую рабочую директорию
cd!(path): То же самое, что и cd/1, но вызывает исключение, если операция неуспешна
cd!(path, function): Изменяет текущую директорию на заданную path, выполняет заданную функцию и затем возвращает предыдущий путь независимо от того, было ли исключение
chgrp(path, gid): Изменяет группу, заданную идентификатором группы gid для заданного file. Возвращает :ok при успехе или {:error, reason} при неудаче
chgrp!(path, gid): То же самое, что и chgrp/2, но вызывает исключение в случае неудачи. В противном случае :ok
chmod(path, mode): Изменяет mode для заданного file
chmod!(path, mode): То же самое, что и chmod/2, но вызывает исключение в случае неудачи. В противном случае :ok
chown(path, uid): Изменяет владельца, заданного идентификатором пользователя uid для заданного file. Возвращает :ok при успехе или {:error, reason} при неудаче
chown!(path, uid): То же самое, что и chown/2, но вызывает исключение в случае неудачи. В противном случае :ok
close(io_device): Закрывает файл, на который ссылается io_device. В основном возвращает :ok, за исключением некоторых серьезных ошибок, таких как недостаток памяти
copy(source, destination, bytes_count \\ :infinity): Копирует содержимое source в destination
copy!(source, destination, bytes_count \\ :infinity): То же самое, что и copy/3, но вызывает исключение File.CopyError в случае неудачи. В противном случае возвращает bytes_copied
cp(source, destination, callback \\ fn _, _ -> true end): Копирует содержимое в source в destination, сохраняя его режим
cp!(source, destination, callback \\ fn _, _ -> true end): То же самое, что и cp/3, но вызывает исключение File.CopyError в случае неудачи. В противном случае возвращает :ok
cp_r(source, destination, callback \\ fn _, _ -> true end): Копирует содержимое в исходном месте в место назначения
cp_r!(source, destination, callback \\ fn _, _ -> true end): То же самое, что и cp_r/3, но вызывает исключение File.CopyError в случае неудачи. В противном случае возвращает список скопированных файлов
cwd(): Получает текущую рабочую директорию
cwd!(): То же самое, что и cwd/0, но вызывает исключение в случае неудачи
dir?(path): Возвращает true если заданный путь является директорией
exists?(path): Возвращает true если заданный путь существует
ln(existing, new): Создаёт жёсткую ссылку new на файл existing
ln!(existing, new): То же самое, что и ln/2, но вызывает исключение в случае неудачи
ln_s(existing, new): Создаёт символическую ссылку new на файл или директорию existing
ln_s!(existing, new): То же самое, что и ln_s/2, но вызывает исключение в случае неудачи
ls(path \\ "."): Возвращает список файлов в заданной директории
ls!(path \\ "."): То же самое, что и ls/1, но вызывает исключение File.Error в случае ошибки
lstat(path, opts \\ []): Возвращает информацию о path. Если файл является символической ссылкой, устанавливает type на :symlink и возвращает структуру File.Stat для ссылки. Для любого другого файла возвращает точно такие же значения, как stat/2
lstat!(path, opts \\ []): То же самое, что и lstat/2, но возвращает структуру File.Stat напрямую или выбрасывает File.Error если возвращена ошибка
mkdir(path): Пытается создать директорию path
mkdir!(path): То же самое, что и mkdir/1, но вызывает исключение в случае неудачи. В противном случае :ok
mkdir_p(path): Пытается создать директорию path
mkdir_p!(path): То же самое, что и mkdir_p/1, но вызывает исключение в случае неудачи. В противном случае :ok
open(path, modes_or_function \\ []): Открывает заданный path
open(path, modes, function): Аналогично open/2, но принимает функцию в качестве последнего аргумента
open!(path, modes_or_function \\ []): Аналогично open/2, но вызывает ошибку, если файл не может быть открыт
open!(path, modes, function): Аналогично open/3, но вызывает ошибку, если файл не может быть открыт
read(path): Возвращает {:ok, binary}, где binary — объект двоичных данных, содержащий содержимое path, или {:error, reason} если произошла ошибка
read!(path): Возвращает двоичные данные с содержимым заданного файла или вызывает File.Error в случае ошибки
read_link(path): Читает символическую ссылку по адресу path
read_link!(path): То же самое, что и read_link/1, но возвращает целевой объект напрямую или выбрасывает File.Error при возникновении ошибки
regular?(path): Возвращает true если путь является обычным файлом
rename(source, destination): Переименовывает файл source в файл destination. Можно использовать для перемещения файлов (и директорий) между директориями. При перемещении файла необходимо полностью указать destination имя файла, недостаточно просто указать директорию
rm(path): Пытается удалить файл path
rm!(path): То же самое, что и rm/1, но вызывает исключение в случае неудачи. В противном случае :ok
rm_rf(path): Рекурсивно удаляет файлы и директории по заданному path. Символические ссылки не отслеживаются, а просто удаляются, несуществующие файлы просто игнорируются (т.е. эта функция не терпит неудач)
rm_rf!(path): То же самое, что и rm_rf/1, но вызывает File.Error в случае ошибок, в противном случае список удалённых файлов или директорий
rmdir(path): Пытается удалить директорию по адресу path. Возвращает :ok при успехе или {:error, reason} при возникновении ошибки
rmdir!(path)

То же самое, что и rmdir/1, но при неудаче генерирует исключение. В противном случае :ok
stat(path, opts \\ []): Возвращает информацию о path. Если она существует, возвращает кортеж {:ok, info}, где info — структура File.Stat. Возвращает {:error, reason} по тем же причинам, что и read/1, при возникновении ошибки
stat!(path, opts \\ []): То же самое, что и stat/2, но возвращает File.Stat напрямую или вызывает File.Error, если произошла ошибка
stream!(path, modes \\ [], line_or_bytes \\ :line): Возвращает File.Stream для указанного path с указанными modes
touch(path, time \\ :calendar.universal_time()): Обновляет время изменения (mtime) и время доступа (atime) указанного файла
touch!(path, time \\ :calendar.universal_time()): То же самое, что и touch/2, но генерирует исключение при ошибке
write(path, content, modes \\ []): Записывает content в файл path
write!(path, content, modes \\ []): То же самое, что и write/3, но генерирует исключение при ошибке, в противном случае возвращает :ok
write_stat(path, stat, opts \\ []): Записывает заданную File.Stat обратно в файловую систему по указанному пути. Возвращает :ok или {:error, reason}
write_stat!(path, stat, opts \\ []): То же самое, что и write_stat/3, но генерирует исключение при ошибке. В противном случае возвращает :ok

Типы

io_device()

io_device() :: :file.io_device()

mode()

mode() ::
  :append
  | :binary
  | :charlist
  | :compressed
  | :delayed_write
  | :exclusive
  | :raw
  | :read
  | :read_ahead
  | :sync
  | :utf8
  | :write
  | {:encoding,
     :latin1
     | :unicode
     | :utf8
     | :utf16
     | :utf32
     | {:utf16, :big | :little}
     | {:utf32, :big | :little}}
  | {:read_ahead, pos_integer()}
  | {:delayed_write, non_neg_integer(), non_neg_integer()}

posix()

posix() :: :file.posix()

stat_options()

stat_options() :: [{:time, :local | :universal | :posix}]

Функции

cd(path)

cd(Path.t()) :: :ok | {:error, posix()}

Устанавливает текущую рабочую директорию.

Возвращает :ok при успехе, {:error, reason} в противном случае.

cd!(path)

cd!(Path.t()) :: :ok | no_return()

То же самое, что и cd/1, но генерирует исключение при ошибке.

cd!(path, function)

cd!(Path.t(), (() -> res)) :: res when res: var

Изменяет текущую директорию на заданную path, выполняет заданную функцию и затем возвращает к предыдущему пути независимо от того, возникло ли исключение.

Генерирует ошибку, если получение или изменение текущей директории завершилось неудачей.

chgrp(path, gid)

chgrp(Path.t(), non_neg_integer()) :: :ok | {:error, posix()}

Изменяет группу, заданную идентификатором группы gid для указанного file. Возвращает :ok при успехе или {:error, reason} при ошибке.

chgrp!(path, gid)

chgrp!(Path.t(), non_neg_integer()) :: :ok | no_return()

То же самое, что и chgrp/2, но генерирует исключение в случае ошибки. В противном случае :ok.

chmod(path, mode)

chmod(Path.t(), non_neg_integer()) :: :ok | {:error, posix()}

Изменяет mode для указанного file.

Возвращает :ok при успехе или {:error, reason} при ошибке.

Разрешения

Разрешения файлов задаются путем сложения следующих восьмеричных флагов:

0o400 - право чтения: владелец
0o200 - право записи: владелец
0o100 - право выполнения: владелец
0o040 - право чтения: группа
0o020 - право записи: группа
0o010 - право выполнения: группа
0o004 - право чтения: другие
0o002 - право записи: другие
0o001 - право выполнения: другие

Например, установка режима 0o755 предоставляет право записи, чтения и выполнения владельцу, а также право чтения и выполнения группе и другим.

chmod!(path, mode)

chmod!(Path.t(), non_neg_integer()) :: :ok | no_return()

То же самое, что и chmod/2, но генерирует исключение при ошибке. В противном случае :ok.

chown(path, uid)

chown(Path.t(), non_neg_integer()) :: :ok | {:error, posix()}

Изменяет владельца, заданного идентификатором пользователя uid для указанного file. Возвращает :ok при успехе или {:error, reason} при ошибке.

chown!(path, uid)

chown!(Path.t(), non_neg_integer()) :: :ok | no_return()

То же самое, что и chown/2, но генерирует исключение при ошибке. В противном случае :ok.

close(io_device)

close(io_device()) :: :ok | {:error, posix() | :badarg | :terminated}

Закрывает файл, на который ссылается io_device. В основном возвращает :ok, за исключением некоторых серьезных ошибок, таких как недостаток памяти.

Обратите внимание, что если при открытии файла был использован параметр :delayed_write, close/1 может вернуть старую ошибку записи и даже не попытаться закрыть файл. Подробнее см. open/2.

copy(source, destination, bytes_count \\ :infinity)

copy(Path.t() | io_device(), Path.t() | io_device(), pos_integer() | :infinity) ::
  {:ok, non_neg_integer()} | {:error, posix()}

Копирует содержимое source в destination.

Оба параметра могут быть именем файла или устройством ввода-вывода, открытым с помощью open/2. bytes_count задает количество копируемых байтов, по умолчанию — :infinity.

Если файл destination уже существует, он перезаписывается содержимым из source.

Возвращает {:ok, bytes_copied} при успехе, {:error, reason} в противном случае.

По сравнению с cp/3, эта функция более низкого уровня, позволяя копировать данные из устройства в устройство, ограниченное числом байтов. С другой стороны, cp/3 выполняет более тщательную проверку источника и места назначения, а также сохраняет режим файла после копирования.

Типичные причины ошибок такие же, как и в open/2, read/1 и write/3.

copy!(source, destination, bytes_count \\ :infinity)

copy!(Path.t() | io_device(), Path.t() | io_device(), pos_integer() | :infinity) ::
  non_neg_integer() | no_return()

То же самое, что и copy/3, но генерирует File.CopyError при ошибке. Возвращает bytes_copied в противном случае.

cp(source, destination, callback \\ fn _, _ -> true end)

cp(Path.t(), Path.t(), (Path.t(), Path.t() -> boolean())) ::
  :ok | {:error, posix()}

Копирует содержимое source в destination, сохраняя его режим.

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

Функция возвращает :ok в случае успеха, возвращает {:error, reason} в противном случае.

Если необходимо скопировать содержимое из устройства ввода-вывода в другое устройство или выполнить прямую копию из источника в место назначения без сохранения режимов, используйте copy/3.

Примечание: Команда cp в системах Unix ведет себя по-разному в зависимости от того, является ли destination существующей директорией или нет. Мы выбрали явное запрещение такого поведения. Если место назначения является директорией, будет возвращена ошибка.

cp!(source, destination, callback \\ fn _, _ -> true end)

cp!(Path.t(), Path.t(), (Path.t(), Path.t() -> boolean())) :: :ok | no_return()

То же самое, что и cp/3, но генерирует File.CopyError при ошибке. Возвращает :ok в противном случае.

cp_r(source, destination, callback \\ fn _, _ -> true end)

cp_r(Path.t(), Path.t(), (Path.t(), Path.t() -> boolean())) ::
  {:ok, [binary()]} | {:error, posix(), binary()}

Копирует содержимое из источника в место назначения.

Если источник — файл, он копирует source в destination Если источник — директория, он копирует содержимое внутри источника в место назначения.

Если файл уже существует в месте назначения, вызывается callback. callback должен быть функцией, принимающей два аргумента: source и destination. Обратный вызов должен вернуть true для перезаписи существующего файла и false в противном случае.

Если директория уже существует в месте назначения, где должен находиться файл (или наоборот), эта функция завершится неудачей.

Эта функция может завершиться неудачей при копировании файлов, в таких случаях она оставит директорию назначения в необработанном состоянии, где файлы, которые уже были скопированы, не будут удалены.

Функция возвращает {:ok, files_and_directories} в случае успеха, files_and_directories список всех скопированных файлов и каталогов в произвольном порядке. В противном случае она возвращает {:error, reason, file}.

Примечание: Команда cp в системах Unix ведет себя по-разному в зависимости от того, является ли destination существующим каталогом или нет. Мы выбрали явное запрещение этого поведения.

Примеры

# Copies file "a.txt" to "b.txt"
File.cp_r "a.txt", "b.txt"

# Copies all files in "samples" to "tmp"
File.cp_r "samples", "tmp"

# Same as before, but asks the user how to proceed in case of conflicts
File.cp_r "samples", "tmp", fn source, destination ->
  IO.gets("Overwriting #{destination} by #{source}. Type y to confirm. ") == "y\n"
end

cp_r!(source, destination, callback \\ fn _, _ -> true end)

cp_r!(Path.t(), Path.t(), (Path.t(), Path.t() -> boolean())) ::
  [binary()] | no_return()

То же, что и cp_r/3, но вызывает File.CopyError, если произошла ошибка. В противном случае возвращает список скопированных файлов.

cwd()

cwd() :: {:ok, binary()} | {:error, posix()}

Получает текущий рабочий каталог.

В редких случаях эта функция может завершиться ошибкой в системах Unix. Это может произойти, если для родительских каталогов текущего каталога отсутствуют права на чтение. По этой причине, в случае успеха возвращает {:ok, cwd}, а в случае ошибки - {:error, reason}.

cwd!()

cwd!() :: binary() | no_return()

То же, что и cwd/0, но вызывает исключение в случае ошибки.

dir?(path)

dir?(Path.t()) :: boolean()

Возвращает true , если заданный путь является каталогом.

Эта функция следует за символическими ссылками, поэтому если символическая ссылка указывает на каталог, возвращается true.

Примеры

File.dir?("./test")
#=> true

File.dir?("test")
#=> true

File.dir?("/usr/bin")
#=> true

File.dir?("~/Downloads")
#=> false

"~/Downloads" |> Path.expand |> File.dir?
#=> true

exists?(path)

exists?(Path.t()) :: boolean()

Возвращает true , если заданный путь существует.

Это может быть обычный файл, каталог, сокет, символическая ссылка, именованная труба или устройство. Возвращает false для символических ссылок, указывающих на несуществующие цели.

Примеры

File.exists?("test/")
#=> true

File.exists?("missing.txt")
#=> false

File.exists?("/dev/null")
#=> true

ln(existing, new)

Создает жесткую ссылку new на файл existing.

Возвращает :ok при успехе, {:error, reason} в противном случае. Если операционная система не поддерживает жесткие ссылки, возвращает {:error, :enotsup}.

ln!(existing, new)

Аналогично ln/2, но вызывает исключение в случае ошибки.

Возвращает :ok в противном случае

ln_s(existing, new)

Создает символическую ссылку new на файл или каталог existing.

Возвращает :ok при успехе, {:error, reason} в противном случае. Если операционная система не поддерживает символические ссылки, возвращает {:error, :enotsup}.

ln_s!(existing, new)

Аналогично ln_s/2, но вызывает исключение при ошибке.

Возвращает :ok в противном случае

ls(path \\ ".")

ls(Path.t()) :: {:ok, [binary()]} | {:error, posix()}

Возвращает список файлов в указанном каталоге.

Возвращает {:ok, files} в случае успеха, {:error, reason} в противном случае.

ls!(path \\ ".")

ls!(Path.t()) :: [binary()] | no_return()

То же, что и ls/1, но вызывает File.Error в случае ошибки.

lstat(path, opts \\ [])

lstat(Path.t(), stat_options()) :: {:ok, File.Stat.t()} | {:error, posix()}

Возвращает информацию об path. Если файл является символической ссылкой, устанавливает type в :symlink и возвращает структуру File.Stat для ссылки. Для любого другого файла возвращает точно такие же значения, как и stat/2.

Для более подробной информации см. :file.read_link_info/2.

Параметры

Доступные параметры:

:time - настраивает, как возвращаются временные метки файлов

Значения для :time могут быть:

:universal - возвращает кортеж {date, time} в формате UTC (по умолчанию)
:local - возвращает кортеж {date, time}, используя системное время
:posix - возвращает время в виде целого числа секунд с эпохи

lstat!(path, opts \\ [])

lstat!(Path.t(), stat_options()) :: File.Stat.t() | no_return()

Аналогично lstat/2, но возвращает структуру File.Stat напрямую или генерирует исключение File.Error в случае ошибки.

mkdir(path)

mkdir(Path.t()) :: :ok | {:error, posix()}

Попытка создать каталог path.

Отсутствующие родительские каталоги не создаются. Возвращает :ok при успехе или {:error, reason} при ошибке.

Типичные причины ошибок:

:eacces - отсутствуют права на поиск или запись для родительских каталогов path
:eexist - файл или каталог с именем path уже существует
:enoent - компонент path не существует
:enospc - на устройстве закончилось место
:enotdir - компонент path не является каталогом; в некоторых системах возвращается :enoent

mkdir!(path)

mkdir!(Path.t()) :: :ok | no_return()

Аналогично mkdir/1, но вызывает исключение в случае ошибки. В противном случае :ok.

mkdir_p(path)

mkdir_p(Path.t()) :: :ok | {:error, posix()}

Попытка создать каталог path.

Отсутствующие родительские каталоги создаются. Возвращает :ok при успехе или {:error, reason} при ошибке.

Типичные причины ошибок:

:eacces - отсутствуют права на поиск или запись для родительских каталогов path
:enospc - на устройстве закончилось место
:enotdir - компонент path не является каталогом

mkdir_p!(path)

mkdir_p!(Path.t()) :: :ok | no_return()

Аналогично mkdir_p/1, но вызывает исключение в случае ошибки. В противном случае :ok.

open(path, modes_or_function \\ [])

open(Path.t(), (io_device() -> res)) :: {:ok, res} | {:error, posix()}
when res: var

open(Path.t(), [mode() | :ram]) :: {:ok, io_device()} | {:error, posix()}

Открывает указанный path.

Для чтения и записи файлов необходимо использовать функции модуля IO. По умолчанию файл открывается в режиме :binary, что требует использования функций IO.binread/2 и IO.binwrite/2 для работы с файлом. Разработчик может передать :utf8 в качестве параметра при открытии файла, и тогда все остальные функции из модуля IO будут доступны, поскольку они работают напрямую с данными Unicode.

modes_or_function может быть списком режимов или функцией. Если это список, он рассматривается как список режимов (документированных ниже). Если это функция, она эквивалентна вызову open(path, [], modes_or_function). Более подробная информация об этой функции приведена в документации к open/3.

Допустимые режимы:

:binary - открывает файл в двоичном режиме, отключая специальную обработку последовательностей Unicode (режим по умолчанию).
:read - файл, который должен существовать, открывается для чтения.
:write - файл открывается для записи. Он создается, если не существует.

Если файл существует и запись не сочетается с чтением, файл будет обнулен.
:append - файл будет открыт для записи и будет создан, если он не существует. Каждая операция записи в файл, открытый с использованием дописывания, будет выполняться в конце файла.
:exclusive - файл при открытии для записи создается, если он не существует. Если файл существует, open вернет {:error, :eexist}.
:charlist - при передаче этого параметра операции чтения из файла будут возвращать списки символов, а не двоичные данные.
:compressed - позволяет читать или записывать сжатые gzip файлы.

Параметр сжатия должен быть объединен либо с чтением, либо с записью, но не с обоими. Обратите внимание, что размер файла, полученный с помощью stat/1, скорее всего, не будет совпадать с количеством байтов, которые можно прочитать из сжатого файла.
:utf8 - этот параметр определяет, как данные фактически хранятся в файле на диске и обеспечивает автоматическое преобразование символов в UTF-8 и обратно.

Если данные отправляются в файл в формате, который не может быть преобразован в UTF-8, или если данные считываются функцией, которая возвращает данные в формате, который не поддерживает диапазон символов данных, возникает ошибка, и файл будет закрыт.
:delayed_write, :raw, :ram, :read_ahead, :sync, {:encoding, ...}, {:read_ahead, pos_integer}, {:delayed_write, non_neg_integer, non_neg_integer} - для получения дополнительной информации об этих параметрах см. :file.open/2.

Функция возвращает:

{:ok, io_device} - файл был открыт в запрошенном режиме.

io_device фактически является PID процесса, который обрабатывает файл. Этот процесс связан с процессом, который изначально открыл файл. Если любой процесс, к которому io_device привязан, завершится, файл будет закрыт, а сам процесс будет завершен.

Возвращаемое значение io_device из этого вызова может быть использовано в качестве аргумента для функций модуля IO.
{:error, reason} - файл не удалось открыть.

Примеры

{:ok, file} = File.open("foo.tar.gz", [:read, :compressed])
IO.read(file, :line)
File.close(file)

open(path, modes, function)

open(Path.t(), [mode() | :ram], (io_device() -> res)) ::
  {:ok, res} | {:error, posix()}
when res: var

Аналогично open/2, но ожидает функцию в качестве последнего аргумента.

Файл открывается, передаётся функции в качестве аргумента и автоматически закрывается после возврата функции, независимо от того, произошла ли ошибка при выполнении функции.

Возвращает {:ok, function_result} в случае успеха, {:error, reason} в противном случае.

Эта функция ожидает успешного закрытия файла, что обычно происходит, если не задан параметр :delayed_write. По этой причине мы не рекомендуем передавать :delayed_write в эту функцию.

Примеры

File.open("file.txt", [:read, :write], fn(file) ->
  IO.read(file, :line)
end)

См. open/2 для списка доступных modes.

open!(path, modes_or_function \\ [])

open!(Path.t(), (io_device() -> res)) :: res | no_return() when res: var

open!(Path.t(), [mode() | :ram]) :: io_device() | no_return()

Аналогично open/2, но генерирует ошибку, если файл не удалось открыть.

В противном случае возвращает устройство ввода-вывода.

См. open/2 для списка доступных режимов.

open!(path, modes, function)

open!(Path.t(), [mode() | :ram], (io_device() -> res)) :: res | no_return()
when res: var

Аналогично open/3, но генерирует ошибку, если файл не удалось открыть.

Если файл успешно открыт, возвращает результат function на устройстве ввода-вывода.

См. open/2 для списка доступных modes.

read(path)

read(Path.t()) :: {:ok, binary()} | {:error, posix()}

Возвращает {:ok, binary}, где binary — это объект двоичных данных, содержащий содержимое path, или {:error, reason} в случае ошибки.

Типичные причины ошибок:

:enoent - файл не существует
:eacces - недостаточно прав для чтения файла или поиска одной из родительских директорий
:eisdir - указанный файл является директорией
:enotdir - компонент имени файла не является директорией; на некоторых платформах вместо :enoent возвращается :enoent
:enomem - недостаточно памяти для содержимого файла

Вы можете использовать :file.format_error/1 для получения описательной строки ошибки.

read!(path)

read!(Path.t()) :: binary() | no_return()

Возвращает двоичные данные с содержимым указанного файла или генерирует File.Error в случае ошибки.

read_link(path)

read_link(Path.t()) :: {:ok, binary()} | {:error, posix()}

Считывает символическую ссылку по пути path.

Если path существует и является символической ссылкой, возвращает {:ok, target}, в противном случае возвращает {:error, reason}.

Для получения более подробной информации см. :file.read_link/1.

Типичные причины ошибок:

:einval - путь не является символической ссылкой
:enoent - путь не существует
:enotsup - символические ссылки не поддерживаются на текущей платформе

read_link!(path)

read_link!(Path.t()) :: binary() | no_return()

То же, что и read_link/1, но возвращает целевой путь напрямую или генерирует File.Error в случае ошибки.

regular?(path)

regular?(Path.t()) :: boolean()

Возвращает true , если путь является обычным файлом.

Эта функция следует за символическими ссылками, поэтому, если символическая ссылка указывает на обычный файл, возвращается true.

Примеры

File.regular? __ENV__.file #=> true

rename(source, destination)

rename(Path.t(), Path.t()) :: :ok | {:error, posix()}

Переименовывает файл source в файл destination. Может использоваться для перемещения файлов (и директорий) между директориями. При перемещении файла вы должны полностью указать имя destination файла, недостаточно указать только его директорию.

Возвращает :ok в случае успеха, {:error, reason} в противном случае.

Примечание: Команда mv в системах Unix ведет себя по-разному, в зависимости от того, является ли source файлом и является ли destination существующей директорией. Мы решили явно запретить такое поведение.

Примеры

# Rename file "a.txt" to "b.txt"
File.rename "a.txt", "b.txt"

# Rename directory "samples" to "tmp"
File.rename "samples", "tmp"

rm(path)

rm(Path.t()) :: :ok | {:error, posix()}

Пытается удалить файл path.

Возвращает :ok при успехе или {:error, reason} при возникновении ошибки.

Обратите внимание, что файл удаляется даже в режиме только для чтения.

Типичные причины ошибок:

:enoent - файла не существует
:eacces - недостаточно прав для файла или одной из его родительских директорий
:eperm - файл является директорией, а пользователь не суперпользователь
:enotdir - компонент имени файла не является директорией; на некоторых платформах вместо :enoent возвращается :enoent
:einval - имя файла имело неправильный тип, например, кортеж

Примеры

File.rm("file.txt")
#=> :ok

File.rm("tmp_dir/")
#=> {:error, :eperm}

rm!(path)

rm!(Path.t()) :: :ok | no_return()

Аналогично rm/1, но генерирует исключение в случае неудачи. В противном случае :ok.

rm_rf(path)

rm_rf(Path.t()) :: {:ok, [binary()]} | {:error, posix(), binary()}

Рекурсивно удаляет файлы и директории по указанному path. Символические ссылки не отслеживаются, а просто удаляются. Несуществующие файлы игнорируются (то есть не вызывают ошибку).

Возвращает {:ok, files_and_directories} со всеми удаленными файлами и директориями в произвольном порядке, {:error, reason, file} в противном случае.

Примеры

File.rm_rf "samples"
#=> {:ok, ["samples", "samples/1.txt"]}

File.rm_rf "unknown"
#=> {:ok, []}

rm_rf!(path)

rm_rf!(Path.t()) :: [binary()] | no_return()

То же, что и rm_rf/1, но генерирует File.Error в случае неудачи, в противном случае список удаленных файлов или директорий.

rmdir(path)

rmdir(Path.t()) :: :ok | {:error, posix()}

Пытается удалить директорию по пути path. Возвращает :ok при успехе или {:error, reason} при возникновении ошибки.

Примеры

File.rmdir('tmp_dir')
#=> :ok

File.rmdir('file.txt')
#=> {:error, :enotdir}

rmdir!(path)

rmdir!(Path.t()) :: :ok | {:error, posix()}

Аналогично rmdir/1, но генерирует исключение в случае неудачи. В противном случае :ok.

stat(path, opts \\ [])

stat(Path.t(), stat_options()) :: {:ok, File.Stat.t()} | {:error, posix()}

Возвращает информацию о path. Если он существует, возвращает кортеж {:ok, info}, где info — это структура File.Stat. Возвращает {:error, reason} по тем же причинам, что и read/1, если произошла ошибка.

Параметры

Доступные параметры:

:time - настраивает, как возвращаются временные метки файла

Значения для :time могут быть:

:universal - возвращает кортеж {date, time} в UTC (по умолчанию)
:local - возвращает кортеж {date, time}, используя часовой пояс машины
:posix - возвращает время как целые секунды с эпохи

stat!(path, opts \\ [])

stat!(Path.t(), stat_options()) :: File.Stat.t() | no_return()

То же, что и stat/2, но возвращает структуру File.Stat напрямую или генерирует File.Error в случае ошибки.

stream!(path, modes \\ [], line_or_bytes \\ :line)

Возвращает File.Stream для данного path с заданными modes.

Поток реализует протоколы Enumerable и Collectable, что означает, что он может использоваться как для чтения, так и для записи.

Аргумент line_or_bytes настраивает способ чтения файла при потоковой передаче, по :line (по умолчанию) или по заданному числу байтов.

Работа с потоком может завершиться ошибкой при открытии по тем же причинам, что и в File.open!/2. Обратите внимание, что файл автоматически открывается каждый раз при начале потоковой передачи. Нет необходимости передавать параметры :read и :write, поскольку они автоматически устанавливаются Elixir.

Сырые файлы

Поскольку Elixir управляет временем открытия потокового файла, то подлежащее устройство не может быть разделено, и поэтому для повышения производительности удобно открыть файл в режиме raw. Поэтому Elixir будет открывать потоки в :raw режиме с опцией :read_ahead , если не указано кодирование. Это означает, что любые данные, передаваемые в файл потоком, должны быть преобразованы в тип iodata/0. Если вы передадите [:utf8] в параметре modes, то подлежащий поток будет использовать IO.write/2 и протокол String.Chars для преобразования данных. См. IO.binwrite/2 и IO.write/2.

Также можно рассмотреть передачу опции :delayed_write , если поток предназначен для записи в цикле.

Маркеры порядка байтов

Если вы передадите :trim_bom в параметре modes, поток обрежет маркеры порядка байтов UTF-8, UTF-16 и UTF-32 при чтении из файла.

Примеры

# Read in 2048 byte chunks rather than lines
File.stream!("./test/test.data", [], 2048)
#=> %File.Stream{line_or_bytes: 2048, modes: [:raw, :read_ahead, :binary],
#=>   path: "./test/test.data", raw: true}

См. Stream.run/1 для примера потоковой записи в файл.

touch(path, time \\ :calendar.universal_time())

touch(Path.t(), :calendar.datetime()) :: :ok | {:error, posix()}

Обновляет время изменения (mtime) и время доступа (atime) указанного файла.

Файл создается, если он не существует. Требуется дата и время в UTC.

touch!(path, time \\ :calendar.universal_time())

touch!(Path.t(), :calendar.datetime()) :: :ok | no_return()

То же, что и touch/2, но вызывает исключение, если произошла ошибка.

В противном случае возвращает :ok. Требуется дата и время в UTC.

write(path, content, modes \\ [])

write(Path.t(), iodata(), [mode()]) :: :ok | {:error, posix()}

Записывает content в файл path.

Файл создается, если он не существует. Если он существует, предыдущее содержимое перезаписывается. Возвращает :ok при успехе или {:error, reason} при возникновении ошибки.

content должно быть iodata (списком байтов или двоичным). Установка кодирования для этой функции не оказывает влияния.

Предупреждение: Каждый раз, когда вызывается эта функция, открывается дескриптор файла и запускается новый процесс для записи в файл. Поэтому, если вы выполняете несколько записей в цикле, открытие файла с помощью File.open/2 и использование функций в IO для записи в файл обеспечит гораздо лучшую производительность, чем многократное вызов этой функции.

Типичные причины ошибок:

:enoent - компонент имени файла не существует
:enotdir - компонент имени файла не является каталогом; на некоторых платформах вместо этого возвращается :enoent
:enospc - на устройстве закончилось место
:eacces - отсутствует разрешение на запись файла или поиск одного из родительских каталогов
:eisdir - указанное имя файла является каталогом

См. File.open/2 для других доступных опций.

write!(path, content, modes \\ [])

write!(Path.t(), iodata(), [mode()]) :: :ok | no_return()

То же, что и write/3, но вызывает исключение при ошибке, в противном случае возвращает :ok.

write_stat(path, stat, opts \\ [])

write_stat(Path.t(), File.Stat.t(), stat_options()) :: :ok | {:error, posix()}

Записывает заданный File.Stat обратно в файловую систему по указанному пути. Возвращает :ok или {:error, reason}.

write_stat!(path, stat, opts \\ [])

write_stat!(Path.t(), File.Stat.t(), stat_options()) :: :ok | no_return()

То же, что и write_stat/3, но вызывает исключение при ошибке. В противном случае возвращает :ok.