Файл

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

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

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

Типы

encoding_mode()

encoding_mode() ::
  :utf8
  | {:encoding,
     :latin1
     | :unicode
     | :utf8
     | :utf16
     | :utf32
     | {:utf16, :big | :little}
     | {:utf32, :big | :little}}

io_device()

io_device() :: :file.io_device()

mode()

mode() ::
  :append
  | :binary
  | :charlist
  | :compressed
  | :delayed_write
  | :exclusive
  | :raw
  | :read
  | :read_ahead
  | :sync
  | :write
  | {:read_ahead, pos_integer()}
  | {:delayed_write, non_neg_integer(), non_neg_integer()}
  | encoding_mode()

posix()

posix() :: :file.posix()

stat_options()

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

stream_mode()

stream_mode() ::
  encoding_mode()
  | :trim_bom
  | {:read_ahead, pos_integer() | false}
  | {:delayed_write, non_neg_integer(), non_neg_integer()}

Функции

cd!(path)

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

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

cd!(path, function)

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

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

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

cd(path)

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

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

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

chgrp!(path, gid)

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

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

chgrp(path, gid)

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

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

chmod!(path, mode)

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

То же, что и chmod/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 предоставляет разрешение на запись, чтение и выполнение владельцу, а также разрешение на чтение и выполнение группе и другим.

chown!(path, uid)

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

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

chown(path, uid)

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

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

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) ::
  non_neg_integer() | no_return()

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

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.

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(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 существующим каталогом или нет. Мы выбрали явное запрещение этого поведения. Если destination — это каталог, будет возвращена ошибка.

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 в случае ошибки. В противном случае возвращает список скопированных файлов.

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.

Если source — это файл, он копирует source в destination. Если source — это каталог, он копирует содержимое внутри 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

cwd!()

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

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

cwd()

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

Возвращает текущую рабочую директорию.

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

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) (since 1.5.0)

ln!(Path.t(), Path.t()) :: :ok | no_return()

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

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

ln(existing, new) (since 1.5.0)

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

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

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

ln_s!(existing, new)

ln_s!(Path.t(), Path.t()) :: :ok | no_return()

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

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

ln_s(existing, new) (since 1.5.0)

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

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

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

ls!(path \\ ".")

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

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

ls(path \\ ".")

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

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

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

lstat!(path, opts \\ [])

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

То же, что и lstat/2, но возвращает структуру File.Stat напрямую или выводит 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 - возвращает время в виде целого числа, количество секунд, прошедших с эпохи

mkdir!(path)

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

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

mkdir(path)

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

Пытается создать директорию path.

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

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

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

mkdir_p!(path)

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

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

mkdir_p(path)

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

Пытается создать директорию path.

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

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

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

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.

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 — открывает файл в двоичном режиме, отключая специальную обработку последовательностей юникода (по умолчанию).
:read — файл, который должен существовать, открывается для чтения.
:write — файл открывается для записи. Он создается, если не существует.

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

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

read!(path)

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

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

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_link!(path) (с версии 1.5.0)

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

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

read_link(path) (с версии 1.5.0)

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

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

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

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

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

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

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. Может использоваться для перемещения файлов (и директорий) между директориями. При перемещении файла необходимо полностью указать имя файла, недостаточно указать только его директорию.

Возвращает :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 | no_return()

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

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_rf!(path)

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

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

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, []}

rmdir!(path)

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

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

rmdir(path)

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

Пытается удалить директорию по пути path.

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

Примеры

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

File.rmdir("non_empty_dir")
#=> {:error, :eexist}

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

stat!(path, opts \\ [])

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

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

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 — возвращает время как целое число секунд с эпохи

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

stream!(Path.t(), stream_mode(), :line | pos_integer()) :: File.Stream.t()

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

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

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

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

Необработанные файлы

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

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

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

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

Обратите внимание, что эта функция не пытается определить кодировку файла на основе BOM.

Примеры

# 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 | no_return()

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

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

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

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

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

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

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

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

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

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_stat!(path, stat, opts \\ [])

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

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

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

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

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