Elixir v1.1.0 IO

Functions handling IO.

Many functions in this module expect an IO device as an argument. An IO device must be a pid or an atom representing a process. For convenience, Elixir provides :stdio and :stderr as shortcuts to Erlang’s :standard_io and :standard_error.

The majority of the functions expect char data, i.e. strings or lists of characters and strings. In case another type is given, it will do a conversion to string via the String.Chars protocol (as shown in typespecs).

The functions starting with bin* expect iodata as an argument, i.e. binaries or lists of bytes and binaries.

IO devices

An IO device may be an atom or a pid. In case it is an atom, the atom must be the name of a registered process. In addition, Elixir provides two shorcuts:

  • :stdio - a shortcut for :standard_io, which maps to the current Process.group_leader/0 in Erlang

  • :stderr - a shortcut for the named process :standard_error provided in Erlang

Summary

Functions

Reads count characters from the IO device, a whole :line or the whole device with :all

Converts the IO device into a IO.Stream

Writes the given argument to the given device as a binary, no unicode conversion happens

Converts chardata (a list of integers representing codepoints, lists and strings) into a string

Gets a number of bytes from the io device. If the io device is a unicode device, count implies the number of unicode codepoints to be retrieved. Otherwise, count is the number of raw bytes to be retrieved. It returns

Gets a number of bytes from the io device. If the io device is a unicode device, count implies the number of unicode codepoints to be retrieved. Otherwise, count is the number of raw bytes to be retrieved

Reads a line from the IO device. It returns

Inspects and writes the given argument to the device

Inspects the item with options using the given device

Returns the size of an iodata

Converts iodata (a list of integers representing bytes, lists and binaries) into a binary

Writes the argument to the device, similar to write/2, but adds a newline at the end. The argument is expected to be a chardata

Reads count characters from the IO device, a whole :line or the whole device with :all

Converts the io device into a IO.Stream

Writes the given argument to the given device

Types

chardata :: :unicode.chardata
device :: atom | pid
nodata :: {:error, term} | :eof

Functions

binread(device \\ group_leader, chars_or_line)

Specs

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

Reads count characters from the IO device, a whole :line or the whole device with :all.

It returns:

  • data - the input characters

  • :eof - end of file was encountered

  • {:error, reason} - other (rare) error condition; for instance, {:error, :estale} if reading from an NFS volume

If :all is given, :eof is never returned, but an empty string in case the device has reached EOF.

Note: do not use this function on IO devices in unicode mode as it will return the wrong result.

binstream(device, line_or_bytes)

Specs

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

Converts the IO device into a IO.Stream.

An IO.Stream implements both Enumerable and Collectable, allowing it to be used for both read and write.

The device is iterated line by line or by a number of bytes. This reads the IO device as a raw binary.

Note that an IO stream has side effects and every time you go over the stream you may get different results.

Finally, do not use this function on IO devices in unicode mode as it will return the wrong result.

binwrite(device \\ group_leader(), item)

Specs

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

Writes the given argument to the given device as a binary, no unicode conversion happens.

Check write/2 for more information.

Note: do not use this function on IO devices in unicode mode as it will return the wrong result.

chardata_to_string(string)

Specs

chardata_to_string(chardata) :: String.t | no_return

Converts chardata (a list of integers representing codepoints, lists and strings) into a string.

In case the conversion fails, it raises a UnicodeConversionError. If a string is given, returns the string itself.

Examples

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

iex> IO.chardata_to_string([0x0061, "bc"])
"abc"
getn(prompt, count \\ 1)

Specs

Gets a number of bytes from the io device. If the io device is a unicode device, count implies the number of unicode codepoints to be retrieved. Otherwise, count is the number of raw bytes to be retrieved. It returns:

  • data - the input characters

  • :eof - end of file was encountered

  • {:error, reason} - other (rare) error condition; for instance, {:error, :estale} if reading from an NFS volume
getn(device, prompt, count)

Specs

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

Gets a number of bytes from the io device. If the io device is a unicode device, count implies the number of unicode codepoints to be retrieved. Otherwise, count is the number of raw bytes to be retrieved.

gets(device \\ group_leader(), prompt)

Reads a line from the IO device. It returns:

  • data - the characters in the line terminated by a line-feed (LF) or end of file (EOF)

  • :eof - end of file was encountered

  • {:error, reason} - other (rare) error condition; for instance, {:error, :estale} if reading from an NFS volume
inspect(item, opts \\ [])

Specs

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

Inspects and writes the given argument to the device.

It enables pretty printing by default with width of 80 characters. The width can be changed by explicitly passing the :width option.

See Inspect.Opts for a full list of options.

Examples

IO.inspect Process.list, width: 40
inspect(device, item, opts)

Specs

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

Inspects the item with options using the given device.

See Inspect.Opts for a full list of options.

iodata_length(item)

Specs

iodata_length(iodata) :: non_neg_integer

Returns the size of an iodata.

Inlined by the compiler.

Examples

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

Specs

iodata_to_binary(iodata) :: binary

Converts iodata (a list of integers representing bytes, lists and binaries) into a binary.

Notice that this function treats lists of integers as raw bytes and does not perform any kind of encoding conversion. If you want to convert from a char list to a string (UTF-8 encoded), please use chardata_to_string/1 instead.

If this function receives a binary, the same binary is returned.

Inlined by the compiler.

Examples

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)

Specs

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

Writes the argument to the device, similar to write/2, but adds a newline at the end. The argument is expected to be a chardata.

read(device \\ group_leader, chars_or_line)

Specs

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

Reads count characters from the IO device, a whole :line or the whole device with :all.

It returns:

  • data - the input characters

  • :eof - end of file was encountered

  • {:error, reason} - other (rare) error condition; for instance, {:error, :estale} if reading from an NFS volume

If :all is given, :eof is never returned, but an empty string in case the device has reached EOF.

stream(device, line_or_codepoints)

Specs

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

Converts the io device into a IO.Stream.

An IO.Stream implements both Enumerable and Collectable, allowing it to be used for both read and write.

The device is iterated line by line if :line is given or by a given number of codepoints.

This reads the IO as utf-8. Check out IO.binstream/2 to handle the IO as a raw binary.

Note that an IO stream has side effects and every time you go over the stream you may get different results.

Examples

Here is an example on how we mimic an echo server from the command line:

Enum.each IO.stream(:stdio, :line), &IO.write(&1)
write(device \\ group_leader(), item)

Specs

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

Writes the given argument to the given device.

By default the device is the standard output. It returns :ok if it succeeds.

Examples

IO.write "sample"
#=> "sample"

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