Файлы

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

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

Кодировка

Для записи и чтения файлов необходимо использовать функции в модуле 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_s(existing, new): Создаёт символическую ссылку new на файл или директорию existing
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. Отсутствующие родительские директории не создаются. Возвращает :ok при успехе или {:error, reason} при возникновении ошибки
mkdir!(path): То же самое, что и mkdir/1, но вызывает исключение в случае ошибки. В противном случае :ok
mkdir_p(path): Попытка создать директорию path. Отсутствующие родительские директории создаются. Возвращает :ok при успехе или {:error, reason} при возникновении ошибки
mkdir_p!(path): То же самое, что и mkdir_p/1, но вызывает исключение в случае ошибки. В противном случае :ok
open(path, modes \\ []): Открывает заданный path в соответствии с заданным списком modes
open(path, modes, function): Аналогично open/2, но ожидает функцию в качестве последнего аргумента
open!(path, modes \\ []): То же самое, что и open/2, но вызывает ошибку, если файл не может быть открыт
open!(path, modes, function): То же самое, что и open/3, но вызывает ошибку, если файл не может быть открыт
read(path): Возвращает {:ok, binary}, где binary это двоичный объект данных, содержащий содержимое path, или {:error, reason} в случае ошибки
read!(path): Возвращает двоичные данные с содержимым заданного файла или вызывает 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 | no_return 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. Если источник — каталог, он копирует содержимое внутри источника в пункт назначения.

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

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

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

Примеры

# 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 если путь является каталогом.

exists?(path)

exists?(Path.t) :: boolean

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

Примеры

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

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

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

ln_s(existing, new)

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

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

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 \\ [])

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

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

Открывает заданный path в соответствии с заданным списком modes.

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

Разрешённые режимы:

: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 фактически является идентификатором процесса, который обрабатывает файл. Этот процесс связан с процессом, который изначально открыл файл. Если любой процесс, к которому относится 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!(path, modes \\ [])

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

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

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

open!(path, modes, function)

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

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

В противном случае возвращает результат функции.

read(path)

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

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

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

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

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

read!(path)

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

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

regular?(path)

regular?(Path.t) :: boolean

Возвращает 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
: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_byte настраивает способ чтения файла при потоковой передаче, по :line (по умолчанию) или по заданному количеству байтов.

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

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

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

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

Примеры

# 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} при возникновении ошибки.

Предупреждение: Каждый раз, когда вызывается эта функция, открывается дескриптор файла и создается новый процесс для записи в файл. По этой причине, если вы выполняете несколько записей в цикле, открытие файла с помощью 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 в противном случае.