Исходный код Файл

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

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

Поиск внутри файла

Вы также можете использовать любые функции из модуля :file для взаимодействия с файлами, возвращаемыми Elixir. Например, для чтения из определенной позиции в файле используйте :file.pread/3:

File.write!("example.txt", "Eats, Shoots & Leaves")
file = File.open!("example.txt")
:file.pread(file, 15, 6)
#=> {:ok, "Leaves"}

В качестве альтернативы, если вам нужно отслеживать текущую позицию, используйте :file.position/2 и :file.read/2:

:file.position(file, 6)
#=> {:ok, 6}
:file.read(file, 6)
#=> {:ok, "Shoots"}
:file.position(file, {:cur, -12})
#=> {:ok, 0}
:file.read(file, 4)
#=> {:ok, "Eats"}

Краткое описание

Функции

cd(path): Устанавливает текущий рабочий каталог.
cd!(path): То же, что и cd/1, но вызывает исключение File.Error, если операция не удалась.
cd!(path, function): Изменяет текущий каталог на указанный path, выполняет заданную функцию, а затем возвращает предыдущий путь независимо от возникновения исключения.
chgrp(path, gid): Изменяет группу, заданную идентификатором группы gid для указанного file. Возвращает :ok при успехе или {:error, reason} при неудаче.
chgrp!(path, gid): Аналогично chgrp/2, но вызывает исключение File.Error в случае неудачи. В противном случае :ok.
chmod(path, mode): Изменяет mode для указанного file.
chmod!(path, mode): Аналогично chmod/2, но вызывает исключение File.Error в случае неудачи. В противном случае :ok.
chown(path, uid): Изменяет владельца, заданного идентификатором пользователя uid для указанного file. Возвращает :ok при успехе или {:error, reason} при неудаче.
chown!(path, uid): Аналогично chown/2, но вызывает исключение File.Error в случае неудачи. В противном случае :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_file, destination_file, options \\ []): Копирует содержимое source_file в destination_file, сохраняя его режимы.
cp!(source_file, destination_file, options \\ []): То же, что и cp/3, но вызывает исключение File.CopyError в случае неудачи. В противном случае возвращает :ok.
cp_r(source, destination, options \\ []): Рекурсивно копирует содержимое source в destination, сохраняя структуру каталогов и режимы источника.
cp_r!(source, destination, options \\ []): То же, что и cp_r/3, но вызывает исключение File.CopyError в случае неудачи. В противном случае возвращает список скопированных файлов.
cwd(): Получает текущий рабочий каталог.
cwd!(): То же, что и cwd/0, но вызывает исключение File.Error в случае неудачи.
dir?(path, opts \\ []): Возвращает true если указанный путь является каталогом.
exists?(path, opts \\ []): Возвращает true если указанный путь существует.
ln(existing, new): Создаёт жёсткую ссылку new на файл existing.
ln!(existing, new): Аналогично ln/2, но вызывает исключение File.LinkError в случае неудачи. Возвращает :ok в противном случае.
ln_s(existing, new): Создаёт символическую ссылку new на файл или каталог existing.
ln_s!(existing, new): Аналогично ln_s/2, но вызывает исключение File.LinkError в случае неудачи. Возвращает :ok в противном случае.
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, но вызывает исключение File.Error в случае неудачи. В противном случае :ok.
mkdir_p(path): Попытка создать каталог path.
mkdir_p!(path): Аналогично mkdir_p/1, но вызывает исключение File.Error в случае неудачи. В противном случае :ok.
open(path, modes_or_function \\ []): Открывает указанный path.
open(path, modes, function): Аналогично open/2, но в качестве последнего аргумента ожидает функцию.
open!(path, modes_or_function \\ []): Аналогично open/2, но вызывает исключение File.Error, если файл не удалось открыть. В противном случае возвращает устройство ввода-вывода.
open!(path, modes, function): Аналогично open/3, но вызывает исключение File.Error, если файл не удалось открыть.

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, opts \\ []): Возвращает true, если путь является обычным файлом.
rename(source, destination): Переименовывает файл source в файл destination. Можно использовать для перемещения файлов (и каталогов) между директориями. При перемещении файла необходимо указать полное имя файла, недостаточно указать только директорию.
rename!(source, destination): Аналогично rename/2, но вызывает исключение File.RenameError в случае ошибки. В противном случае возвращает :ok.
rm(path): Попытка удалить файл path.
rm!(path): Аналогично rm/1, но вызывает исключение File.Error в случае неудачи. В противном случае возвращает :ok.
rm_rf(path): Рекурсивно удаляет файлы и каталоги по заданному path. Символьные ссылки не отслеживаются, а просто удаляются, не существующие файлы игнорируются (т.е. не вызывают ошибку).
rm_rf!(path): Аналогично rm_rf/1, но вызывает исключение File.Error в случае ошибок, в противном случае возвращает список удалённых файлов или каталогов.
rmdir(path): Попытка удалить каталог по адресу path.
rmdir!(path): Аналогично rmdir/1, но вызывает исключение File.Error в случае ошибки. Иначе :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, line_or_bytes_modes \\ []): Сокращённая запись для File.stream!/3.
stream!(path, line_or_bytes, modes): Возвращает File.Stream для данного path с заданными modes.
touch(path, time \\ System.os_time(:second)): Обновляет время модификации (mtime) и время доступа (atime) данного файла.
touch!(path, time \\ System.os_time(:second)): Аналогично touch/2, но вызывает исключение File.Error в случае ошибки. В противном случае возвращает :ok.
write(path, content, modes \\ []): Записывает content в файл path.
write!(path, content, modes \\ []): Аналогично write/3, но вызывает исключение File.Error в случае ошибки. Возвращает :ok в противном случае.
write_stat(path, stat, opts \\ []): Записывает заданную File.Stat обратно в файловую систему по заданному пути. Возвращает :ok или {:error, reason}.
write_stat!(path, stat, opts \\ []): Аналогично write_stat/3, но вызывает исключение File.Error в случае ошибки. В противном случае возвращает :ok.

Типы

encoding_mode()Source

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

erlang_time()Source

@type erlang_time() ::
  {{year :: non_neg_integer(), month :: 1..12, day :: 1..31},
   {hour :: 0..23, minute :: 0..59, second :: 0..59}}

io_device()Source

@type io_device() :: :file.io_device()

mode()Source

@type 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()

on_conflict_callback()Source

@type on_conflict_callback() :: (Path.t(), Path.t() -> boolean())

posix()Source

@type posix() :: :file.posix()

posix_time()Source

@type posix_time() :: integer()

read_offset_mode()Source

@type read_offset_mode() :: {:read_offset, non_neg_integer()}

stat_options()Source

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

stream_mode()Source

@type stream_mode() ::
  encoding_mode()
  | read_offset_mode()
  | :append
  | :compressed
  | :delayed_write
  | :trim_bom
  | {:read_ahead, pos_integer() | false}
  | {:delayed_write, non_neg_integer(), non_neg_integer()}

END_OF_DOCUMENT_MARKER

Функции

cd(path)Source

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

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

Текущий рабочий каталог устанавливается для BEAM глобально. Это может привести к проблемам гонки, если несколько процессов одновременно изменяют текущий рабочий каталог. Чтобы запустить внешнюю команду в заданном каталоге без изменения глобального текущего рабочего каталога, используйте опцию :cd функции System.cmd/3 и Port.open/2.

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

cd!(path)Source

@spec cd!(Path.t()) :: :ok

То же, что и cd/1, но генерирует исключение File.Error при неудаче.

cd!(path, function)Source

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

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

Текущий рабочий каталог временно устанавливается для BEAM глобально. Это может привести к проблемам гонки, если несколько процессов одновременно изменяют текущий рабочий каталог. Чтобы запустить внешнюю команду в заданном каталоге без изменения глобального текущего рабочего каталога, используйте опцию :cd функции System.cmd/3 и Port.open/2.

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

chgrp(path, gid)Source

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

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

chgrp!(path, gid)Source

@spec chgrp!(Path.t(), non_neg_integer()) :: :ok

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

chmod(path, mode)Source

@spec 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)Source

@spec chmod!(Path.t(), non_neg_integer()) :: :ok

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

chown(path, uid)Source

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

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

chown!(path, uid)Source

@spec chown!(Path.t(), non_neg_integer()) :: :ok

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

close(io_device)Source

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

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

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

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

@spec 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)Source

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

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

cp(source_file, destination_file, options \\ [])Source

@spec cp(Path.t(), Path.t(), [{:on_conflict, on_conflict_callback()}]) ::
  :ok | {:error, posix()}

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

source_file должен быть файлом или символической ссылкой на него. destination_file должен быть путем к несуществующему файлу. Если любой из них является каталогом, возвращается {:error, :eisdir}.

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

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

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

Опции

:on_conflict - (с версии v1.14.0) Вызывается, когда файл уже существует в месте назначения. Функция получает аргументы для source_file и destination_file. Она должна вернуть true если существующий файл должен быть перезаписан, false в противном случае. По умолчанию коллбек возвращает true. В предыдущих версиях этот коллбек можно было передать в качестве третьего аргумента, но такое поведение устарело.

cp!(source_file, destination_file, options \\ [])Source

@spec cp!(Path.t(), Path.t(), [{:on_conflict, on_conflict_callback()}]) :: :ok

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

END_OF_DOCUMENT_MARKER

cp_r(source, destination, options \\ [])Source

@spec cp_r(Path.t(), Path.t(),
  on_conflict: on_conflict_callback(),
  dereference_symlinks: boolean()
) ::
  {:ok, [binary()]} | {:error, posix(), binary()}

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

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

Если source является каталогом или символической ссылкой на него, то destination должно быть существующим directory или символической ссылкой на него, или путем к несуществующему каталогу.

Если исходный объект является файлом, он копирует source в destination. Если исходный объект является каталогом, он копирует содержимое внутри исходного каталога в destination каталог.

Если файл уже существует в пункте назначения, вызывается необязательный on_conflict обратный вызов, заданный в качестве параметра. Смотрите "Параметры" для получения дополнительной информации.

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

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

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

Параметры

:on_conflict - (с версии v1.14.0) Вызывается, когда файл уже существует в пункте назначения. Функция получает аргументы для source и destination. Она должна вернуть true если существующий файл должен быть перезаписан, false в противном случае. По умолчанию обратный вызов возвращает true. В более ранних версиях этот обратный вызов можно было указать как третий аргумент, но такое поведение сейчас устарело.
:dereference_symlinks - (с версии v1.14.0) По умолчанию эта функция будет копировать символические ссылки, создавая символические ссылки, указывающие на то же местоположение. Этот параметр принудительно дезактивирует символические ссылки и копирует их содержимое вместо этого, если он установлен в значение true. Если дезактивированные файлы не существуют, операция завершается ошибкой. По умолчанию значение false.

Примеры

# 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", on_conflict: fn source, destination ->
  IO.gets("Overwriting #{destination} by #{source}. Type y to confirm. ") == "y\n"
end)

cp_r!(source, destination, options \\ [])Source

@spec cp_r!(Path.t(), Path.t(),
  on_conflict: on_conflict_callback(),
  dereference_symlinks: boolean()
) ::
  [binary()]

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

cwd()Source

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

Возвращает текущий рабочий каталог.

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

cwd!()Source

@spec cwd!() :: binary()

То же, что и cwd/0, но при ошибке генерирует исключение File.Error.

dir?(path, opts \\ [])Source

@spec dir?(Path.t(), [dir_option]) :: boolean() when dir_option: :raw

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

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

Параметры

Поддерживаемые параметры:

:raw - одно атомное значение, чтобы обойти файловый сервер и проверить существование файла только локально

Примеры

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

@spec exists?(Path.t(), [exists_option]) :: boolean() when exists_option: :raw

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

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

Параметры

Поддерживаемые параметры:

:raw - одно атомное значение, чтобы обойти файловый сервер и проверить существование файла только локально

Примеры

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

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

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

ln(existing, new)Source

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

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

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

ln!(existing, new)Source

@spec ln!(Path.t(), Path.t()) :: :ok

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

ln_s(existing, new)Source

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

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

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

ln_s!(existing, new)Source

@spec ln_s!(Path.t(), Path.t()) :: :ok

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

ls(path \\ ".")Source

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

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

Скрытые файлы не игнорируются, и результаты не сортируются.

Так как каталоги рассматриваются файловой системой как файлы, они также включаются в возвращаемое значение.

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

ls!(path \\ ".")Source

@spec ls!(Path.t()) :: [binary()]

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

lstat(path, opts \\ [])Source

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

Примечание: Поскольку временные метки файлов хранятся в формате POSIX в большинстве операционных систем, быстрее получать информацию о файлах с помощью параметра time: :posix.

lstat!(path, opts \\ [])Source

@spec lstat!(Path.t(), stat_options()) :: File.Stat.t()

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

END_OF_DOCUMENT_MARKER ```

mkdir(path)Source

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

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

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

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

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

mkdir!(path)Source

@spec mkdir!(Path.t()) :: :ok

То же, что и mkdir/1, но в случае неудачи генерирует исключение File.Error. В противном случае :ok.

mkdir_p(path)Source

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

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

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

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

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

mkdir_p!(path)Source

@spec mkdir_p!(Path.t()) :: :ok

То же, что и mkdir_p/1, но в случае неудачи генерирует исключение File.Error. В противном случае :ok.

open(path, modes_or_function \\ [])Source

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

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

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

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

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

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

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

Если файл существует, и запись не сочетается с чтением, файл будет обнулен.
:append - файл откроется для записи, и будет создан, если не существует. Если файл существует, функция 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)Source

@spec 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)

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

open!(path, modes_or_function \\ [])Source

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

@spec open!(Path.t(), (io_device() -> res)) :: res when res: var

Аналогично open/2, но генерирует исключение File.Error, если файл не удалось открыть. В противном случае возвращает устройство ввода-вывода.

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

open!(path, modes, function)Source

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

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

При успехе возвращает результат function на устройстве ввода-вывода.

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

read(path)Source

@spec 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)Source

@spec read!(Path.t()) :: binary()

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

END_OF_DOCUMENT_MARKER

read_link(path)Source

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

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

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

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

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

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

read_link!(path)Source

@spec read_link!(Path.t()) :: binary()

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

regular?(path, opts \\ [])Source

@spec regular?(Path.t(), [regular_option]) :: boolean() when regular_option: :raw

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

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

Параметры

Поддерживаемые параметры:

:raw - один атом для обхода файлового сервера и проверки файла только локально

Примеры

File.regular?(__ENV__.file)
#=> true

rename(source, destination)Source

@spec 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")

rename!(source, destination)Source

@spec rename!(Path.t(), Path.t()) :: :ok

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

rm(path)Source

@spec 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)Source

@spec rm!(Path.t()) :: :ok

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

rm_rf(path)Source

@spec 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)Source

@spec rm_rf!(Path.t()) :: [binary()]

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

rmdir(path)Source

@spec 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}

rmdir!(path)Source

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

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

stat(path, opts \\ [])Source

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

Примечание: Поскольку временные метки файлов хранятся в формате POSIX времени на большинстве операционных систем, использование параметра time: :posix ускоряет получение информации о файле.

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

@spec stat!(Path.t(), stat_options()) :: File.Stat.t()

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

stream!(path, line_or_bytes_modes \\ [])Source

@spec stream!(Path.t(), :line | pos_integer() | [stream_mode()]) :: File.Stream.t()

Сокращение для File.stream!/3.

stream!(path, line_or_bytes, modes)Source

@spec stream!(Path.t(), :line | pos_integer(), [stream_mode()]) :: File.Stream.t()

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

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

Аргумент line_or_bytes определяет способ чтения файла при потоковой передаче, по строкам (по умолчанию) или по заданному количеству байтов. При использовании параметра :line, переводы строк CRLF ("\r\n") нормализуются до LF ("\n").

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

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

Маркеры порядка байтов и смещение чтения

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

Обратите внимание, что эта функция не пытается определить кодировку файла на основе BOM. С Elixir v1.16.0 вы также можете передать :read_offset, который пропускается при перечислении потока (если переданы и :read_offset, и :trim_bom, смещение пропускается после BOM).

Примеры

# Read a utf8 text file which may include BOM
File.stream!("./test/test.txt", [:trim_bom, encoding: :utf8])

# Read in 2048 byte chunks rather than lines
File.stream!("./test/test.data", 2048)

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

touch(path, time \\ System.os_time(:second))Source

@spec touch(Path.t(), erlang_time() | posix_time()) :: :ok | {:error, posix()}

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

Файл создается, если он не существует. Требуется дата и время в UTC (как возвращает :erlang.universaltime()) или целое число, представляющее временную метку POSIX (как возвращает System.os_time(:second)).

В системах Unix изменение времени изменения может потребовать, чтобы вы были либо root , либо владельцем файла. Доступ для записи может быть недостаточно. В этих случаях прикосновение к файлу в первый раз (для его создания) будет успешным, но прикосновение к существующему файлу завершится ошибкой с {:error, :eperm}.

Примеры

File.touch("/tmp/a.txt", {{2018, 1, 30}, {13, 59, 59}})
#=> :ok
File.touch("/fakedir/b.txt", {{2018, 1, 30}, {13, 59, 59}})
{:error, :enoent}

File.touch("/tmp/a.txt", 1544519753)
#=> :ok

touch!(path, time \\ System.os_time(:second))Source

@spec touch!(Path.t(), erlang_time() | posix_time()) :: :ok

Аналогично touch/2, но если произойдет ошибка, выбрасывается исключение File.Error. В противном случае возвращается :ok.

Примеры

File.touch!("/tmp/a.txt", {{2018, 1, 30}, {13, 59, 59}})
#=> :ok
File.touch!("/fakedir/b.txt", {{2018, 1, 30}, {13, 59, 59}})
** (File.Error) could not touch "/fakedir/b.txt": no such file or directory

File.touch!("/tmp/a.txt", 1544519753)

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

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

@spec write!(Path.t(), iodata(), [mode()]) :: :ok

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

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

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

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

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

@spec write_stat!(Path.t(), File.Stat.t(), stat_options()) :: :ok

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