IO

Функции, обрабатывающие ввод/вывод (IO).

Многие функции в этом модуле ожидают устройство ввода/вывода в качестве аргумента. Устройство ввода/вывода должно быть PID или атом, представляющий процесс. Для удобства Elixir предоставляет :stdio и :stderr в качестве сокращений для :standard_io и :standard_error Erlang.

Большинство функций ожидают chardata, т. е. строки или списки символов и строк. В случае, если указан другой тип, функции преобразуют его в строку с помощью протокола String.Chars (как показано в описании типов).

Функции, начинающиеся с bin, ожидают iodata в качестве аргумента, т. е. двоичные данные или списки байтов и двоичных данных.

Устройства ввода/вывода

Устройство ввода/вывода может быть атомом или PID. В случае, если это атом, атом должен быть именем зарегистрированного процесса. Кроме того, Elixir предоставляет два сокращения:

• :stdio - сокращение для :standard_io, которое сопоставляется с текущим Process.group_leader/0 в Erlang

• :stderr - сокращение для именованного процесса :standard_error, предоставленного в Erlang

Устройства ввода/вывода сохраняют свою позицию, что означает, что последующие вызовы любых функций чтения или записи будут начинаться с места, где устройство было в последний раз обработано. Позицию файлов можно изменить, используя функцию :file.position/2.

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

Типы

chardata()

device()

nodata()

Функции

binread(device \\ :stdio, line_or_chars)

Считывает данные из устройства ввода/вывода device. Операция не безопасна для Unicode.

binstream(device, line_or_bytes)

Преобразует устройство ввода/вывода device в IO.Stream. Операция не безопасна для Unicode.

binwrite(device \\ :stdio, item)

Записывает item в виде двоичных данных в указанное устройство device. Преобразования Unicode не происходит. Операция не безопасна для Unicode.

chardata_to_string(string)

Преобразует chardata (список целых чисел, представляющих кодовые точки, списки и строки) в строку.

getn(prompt, count \\ 1)

Считывает заданное количество байтов с устройства ввода/вывода :stdio.

getn(device, prompt, count)

Считывает заданное количество байтов с устройства ввода/вывода device.

gets(device \\ :stdio, prompt)

Считывает строку с устройства ввода/вывода device.

inspect(item, opts \\ [])

Выводит информацию о заданном item на устройство.

inspect(device, item, opts)

Выводит информацию о item на устройство ввода/вывода device в соответствии с заданными параметрами.

iodata_length(item)

Возвращает размер iodata.

iodata_to_binary(item)

Преобразует iodata (список целых чисел, представляющих байты, списки и двоичные данные) в двоичные данные. Операция не безопасна для Unicode.

puts(device \\ :stdio, item)

Записывает item в заданное устройство device, аналогично write/2, но добавляет символ новой строки в конце.

read(device \\ :stdio, line_or_chars)

Считывает данные с устройства ввода/вывода device.

stream(device, line_or_codepoints)

Преобразует устройство ввода/вывода device в IO.Stream.

warn(message)

Записывает message в stderr вместе с текущим стеком вызовов.

warn(message, stacktrace)

Записывает message в stderr вместе с указанным stacktrace.

write(device \\ :stdio, item)

Записывает item в заданное устройство device.

Типы

chardata()

chardata() :: :unicode.chardata()

device()

device() :: atom() | pid()

nodata()

nodata() :: {:error, term()} | :eof

Функции

binread(device \\ :stdio, line_or_chars)

binread(device(), :all | :line | non_neg_integer()) :: iodata() | nodata()

Считывает данные с устройства ввода/вывода device. Операция не безопасна для Unicode.

Итерация device осуществляется по заданному количеству байтов или построчно, если задан параметр :line. В качестве альтернативы, если задан :all, то возвращается вся device.

Возвращает:

• data - выходные байты

• :eof - достигнут конец файла

• {:error, reason} - другая (редкая) ошибка; например, {:error, :estale} при чтении с NFS-тома

Если задан :all, то :eof никогда не возвращается, а вместо этого — пустая строка, если устройство достигло конца файла.

Примечание: не используйте эту функцию с устройствами ввода/вывода в режиме Unicode, так как она вернёт неверный результат.

binstream(device, line_or_bytes)

binstream(device(), :line | pos_integer()) :: Enumerable.t()

Преобразует устройство ввода/вывода device в IO.Stream. Операция не безопасна для Unicode.

A IO.Stream implements both Enumerable and Collectable, позволяя использовать его для чтения и записи.

Итерация device выполняется по заданному количеству байтов или построчно, если задан параметр :line. Это считывает данные с устройства ввода/вывода как сырые двоичные данные.

Обратите внимание, что поток ввода/вывода имеет побочные эффекты, и каждый раз при прохождении по потоку вы можете получать разные результаты.

Наконец, не используйте эту функцию с устройствами ввода/вывода в режиме Unicode, так как она вернёт неверный результат.

binwrite(device \\ :stdio, item)

binwrite(device(), iodata()) :: :ok | {:error, term()}

Записывает item в виде двоичных данных в указанное устройство device. Преобразования Unicode не происходит. Операция не безопасна для Unicode.

См. write/2 для получения дополнительной информации.

Примечание: не используйте эту функцию с устройствами ввода/вывода в режиме Unicode, так как она вернёт неверный результат.

chardata_to_string(string)

chardata_to_string(chardata()) :: String.t() | no_return()

Преобразует chardata (список целых чисел, представляющих кодовые точки, списки и строки) в строку.

В случае неудачного преобразования генерируется исключение UnicodeConversionError. Если указана строка, возвращается сама строка.

Примеры

iex> IO.chardata_to_string([0x00E6, 0x00DF])
"æß"

iex> IO.chardata_to_string([0x0061, "bc"])
"abc"

iex> IO.chardata_to_string("string")
"string"

getn(prompt, count \\ 1)

getn(device(), chardata() | String.Chars.t()) :: chardata() | nodata()

getn(chardata() | String.Chars.t(), pos_integer()) :: chardata() | nodata()

Считывает заданное количество байтов с устройства ввода/вывода :stdio.

Если :stdio — устройство Unicode, count означает количество кодовых точек Unicode для получения. В противном случае, count — количество байтов для получения.

См. IO.getn/3 для описания значений возврата.

getn(device, prompt, count)

getn(device(), chardata() | String.Chars.t(), pos_integer()) ::
  chardata() | nodata()

Считывает заданное количество байтов с устройства ввода/вывода device.

Если устройство ввода/вывода device — устройство Unicode, count означает количество кодовых точек Unicode для получения. В противном случае, count — количество байтов для получения.

Возвращает:

• data - входные символы

• :eof - достигнут конец файла

• {:error, reason} - другая (редкая) ошибка; например, {:error, :estale} при чтении с NFS-тома

gets(device \\ :stdio, prompt)

gets(device(), chardata() | String.Chars.t()) :: chardata() | nodata()

Считывает строку с устройства ввода/вывода device.

Возвращает:

• data - символы в строке, завершённые символом новой строки (LF) или концом файла (EOF)

• :eof - достигнут конец файла

• {:error, reason} - другая (редкая) ошибка; например, {:error, :estale} при чтении с NFS-тома

Примеры

Для отображения «Каково ваше имя?» в качестве подсказки и ожидания ввода пользователя:

IO.gets "What is your name?\n"

inspect(item, opts \\ [])

inspect(item, keyword()) :: item when item: var

Выводит информацию о заданном item на устройство.

Важно отметить, что возвращает исходное значение item неизменным. Это позволяет «отслеживать» значения, вставляя вызов IO.inspect/2 почти в любом месте кода, например, посреди цепочки.

Включает красивую печать по умолчанию с шириной 80 символов. Ширину можно изменить, явно передав параметр :width.

Вывод можно оформить меткой, указав опцию :label для лёгкого отличия от других вызовов IO.inspect/2. Метка будет напечатана перед проверяемым item.

Полный список оставшихся опций форматирования см. в Inspect.Opts.

Примеры

IO.inspect <<0, 1, 2>>, width: 40

Выводит:

<<0, 1, 2>>

Можно использовать опцию :label для оформления вывода:

IO.inspect 1..100, label: "a wonderful range"

Выводит:

a wonderful range: 1..100

Опция :label особенно полезна в конвейерах:

[1, 2, 3]
|> IO.inspect(label: "before")
|> Enum.map(&(&1 * 2))
|> IO.inspect(label: "after")
|> Enum.sum

Выводит:

before: [1, 2, 3]
after: [2, 4, 6]

inspect(device, item, opts)

inspect(device(), item, keyword()) :: item when item: var

Проверяет item в соответствии с заданными параметрами с помощью IO device.

Полный список опций см. в inspect/2.

iodata_length(item)

iodata_length(iodata()) :: non_neg_integer()

Возвращает размер iodata.

Встроенная компилятором.

Примеры

iex> IO.iodata_length([1, 2 | <<3, 4>>])
4

iodata_to_binary(item)

iodata_to_binary(iodata()) :: binary()

Преобразует iodata (список целых чисел, представляющих байты, списки и бинарные данные) в бинарный тип. Операция не безопасна для Юникода.

Обратите внимание, что эта функция обрабатывает списки целых чисел как сырые байты и не выполняет никакого преобразования кодировки. Если вы хотите преобразовать список символов в строку (кодировка UTF-8), используйте chardata_to_string/1.

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

Встроенная компилятором.

Примеры

iex> bin1 = <<1, 2, 3>>
iex> bin2 = <<4, 5>>
iex> bin3 = <<6>>
iex> IO.iodata_to_binary([bin1, 1, [2, 3, bin2], 4 | bin3])
<<1, 2, 3, 1, 2, 3, 4, 5, 4, 6>>

iex> bin = <<1, 2, 3>>
iex> IO.iodata_to_binary(bin)
<<1, 2, 3>>

puts(device \\ :stdio, item)

puts(device(), chardata() | String.Chars.t()) :: :ok

Записывает item в указанный device, аналогично write/2, но добавляет символ новой строки в конце.

По умолчанию device — стандартный вывод. Возвращает :ok в случае успеха.

Примеры

IO.puts "Hello World!"
#=> Hello World!

IO.puts :stderr, "error"
#=> error

read(device \\ :stdio, line_or_chars)

read(device(), :all | :line | non_neg_integer()) :: chardata() | nodata()

Читает из IO device.

device итерируется по заданному количеству символов или строкам по строкам, если указано :line. В качестве альтернативы, если указано :all, то возвращается весь device.

Возвращает:

• data — символы вывода

• :eof — достигнут конец файла

• {:error, reason} — другая (редкая) ошибка; например, {:error, :estale} при чтении из NFS-тома

Если задано :all, :eof никогда не возвращается, а возвращается пустая строка в случае достижения EOF устройством.

stream(device, line_or_codepoints)

stream(device(), :line | pos_integer()) :: Enumerable.t()

Преобразует IO device в IO.Stream.

IO.Stream реализует как Enumerable, так и Collectable, что позволяет использовать его как для чтения, так и для записи.

device итерируется по заданному количеству символов или строкам по строкам, если указано :line.

Читает из IO в формате UTF-8. Обратитесь к IO.binstream/2, чтобы обработать IO как сырой бинарный тип.

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

Примеры

Вот пример того, как имитировать эхо-сервер из командной строки:

Enum.each IO.stream(:stdio, :line), &IO.write(&1)

warn(message)

warn(chardata() | String.Chars.t()) :: :ok

Записывает message в stderr вместе со текущим трассировкой стека.

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

Примеры

IO.warn "variable bar is unused"
#=> warning: variable bar is unused
#=>   (iex) evaluator.ex:108: IEx.Evaluator.eval/4

warn(message, stacktrace)

warn(chardata() | String.Chars.t(), Exception.stacktrace()) :: :ok

Записывает message в stderr вместе с указанной stacktrace.

Эта функция также сообщает компилятору, что было выведено предупреждение (в случае включения —warnings-as-errors). Возвращает :ok в случае успеха.

Для предотвращения вывода трассировки стека можно передать пустой список.

Примеры

stacktrace = [{MyApp, :main, 1, [file: 'my_app.ex', line: 4]}]
IO.warn "variable bar is unused", stacktrace
#=> warning: variable bar is unused
#=>   my_app.ex:4: MyApp.main/1

write(device \\ :stdio, item)

write(device(), chardata() | String.Chars.t()) :: :ok

Записывает item в указанный device.

По умолчанию device — стандартный вывод.

Примеры

IO.write "sample"
#=> sample

IO.write :stderr, "error"
#=> error