Spec-Zone.ru › Elixir 1.3

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 \\ group_leader(), line_or_chars)

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

binstream(device, line_or_bytes)

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

binwrite(device \\ group_leader(), item)

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

chardata_to_string(string)

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

getn(prompt, count \\ 1)

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

getn(device, prompt, count)

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

gets(device \\ group_leader(), prompt)

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

inspect(item, opts \\ [])

Выводит инспекцию заданного item на устройство

inspect(device, item, opts)

Выводит инспекцию item в соответствии с заданными параметрами с использованием устройства IO device

iodata_length(item)

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

iodata_to_binary(item)

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

puts(device \\ group_leader(), item)

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

read(device \\ group_leader(), line_or_chars)

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

stream(device, line_or_codepoints)

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

warn(message)

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

warn(message, stacktrace)

Записывает message в stderr вместе с заданным stacktrace

write(device \\ group_leader(), item)

Записывает item в заданное device

Типы

chardata() 

chardata() :: :unicode.chardata

device() 

device() :: atom | pid

nodata() 

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

Функции

binread(device \\ group_leader(), line_or_chars) 

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

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

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

Возвращает:

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

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

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

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

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

binstream(device, line_or_bytes) 

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

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

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

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

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

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

binwrite(device \\ group_leader(), item) 

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

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

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

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

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 – устройство Юникода, count означает количество точек кодирования Юникода для извлечения. Иначе count означает количество байтов для извлечения.

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

getn(device, prompt, count) 

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

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

Если устройство ввода/вывода device – устройство Юникода, count означает количество точек кодирования Юникода для извлечения. Иначе count означает количество байтов для извлечения.

Возвращает:

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

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

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

gets(device \\ group_leader(), 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?

«

inspect(item, opts \\ []) 

inspect(item, Keyword.t) :: item when item: var

Выводит инспекцию заданного item на устройство.

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

См. Inspect.Opts для полного списка параметров.

Примеры 

IO.inspect Process.list, width: 40

inspect(device, item, opts) 

inspect(device, item, Keyword.t) :: item when item: var

Просматривает item в соответствии с заданными параметрами с использованием ввода-вывода device.

Полный список параметров см. в Inspect.Opts.

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 (список целых чисел, представляющих байты, списки и двоичные данные) в двоичные данные. Операция не поддерживает Unicode.

Обратите внимание, что эта функция обрабатывает списки целых чисел как сырые байты и не выполняет никаких преобразований кодировки. Если вам нужно преобразовать список символов в строку (кодировку 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 \\ group_leader(), item) 

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

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

read(device \\ group_leader(), line_or_chars) 

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

Читает из ввода-вывода device.

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

Возвращает:

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

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

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

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

stream(device, line_or_codepoints) 

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

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

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

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

Это чтение из ввода-вывода в формате utf-8. Обратитесь к IO.binstream/2 для обработки ввода-вывода как сырых двоичных данных.

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

Примеры

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

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 \\ group_leader(), item) 

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

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

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

Примеры 

IO.write "sample"
#=> sample

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

© 2012 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.3.4/IO.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API