IO
Functions handling IO.
Many functions in this module expects an IO device as 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 data encoded in UTF-8
and will do a conversion to string, via the String.Chars
protocol (as shown in typespecs).
The functions starting with bin* expects iodata as arguments,
i.e. iolists or binaries with no particular encoding.
Summary
| binread(device \\ group_leader, chars_or_line) | Reads |
| binstream(device, line_or_bytes) | Converts the io device into a Stream. The device is iterated line by line or by a number of bytes. This reads the IO as a raw binary |
| binwrite(device \\ group_leader(), item) | Writes the given argument to the given device as a binary, no unicode conversion happens |
| getn(prompt, count \\ 1) | Gets a number of bytes from the io device. If the
io device is a unicode device, |
| getn(device, prompt, count) | Gets a number of bytes from the io device. If the
io device is a unicode device, |
| gets(device \\ group_leader(), prompt) | Reads a line from the IO device. It returns: |
| inspect(item, opts \\ []) | Inspects and writes the given argument to the device followed by a newline. A set of options can be given |
| inspect(device, item, opts) | Inspects the item with options using the given device |
| puts(device \\ group_leader(), item) | Writes the argument to the device, similar to |
| read(device \\ group_leader, chars_or_line) | Reads |
| stream(device, line_or_codepoints) | Converts the io device into a Stream. The device is
iterated line by line if |
| write(device \\ group_leader(), item) | Writes the given argument to the given device. By default the device is the standard output. The argument is expected to be a chardata (i.e. a char list or an unicode binary) |
Functions
Specs:
Reads count bytes from the IO device or until
the end of the line if :line is given. 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 file system.
Specs:
- binstream(device, :line | pos_integer) :: Enumerable.t
Converts the io device into a Stream. The device is iterated line by line or by a number of bytes. This reads 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.
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.
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 file system.
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.
Specs:
Reads a line from the IO device. It returns:
data- The characters in the line terminated by a LF (or end of file).:eof- End of file was encountered.{:error, reason}- Other (rare) error condition, for instance{:error, :estale}if reading from an NFS file system.
Specs:
- inspect(term, Keyword.t) :: term
Inspects and writes the given argument to the device followed by a newline. A set of options can be given.
It sets by default pretty printing to true and the width to be the width of the device, with a minimum of 80 characters.
Examples
IO.inspect Process.list
Specs:
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.
Specs:
Reads count characters from the IO device or until
the end of the line if :line is given. 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 file system.
Specs:
- stream(device, :line | pos_integer) :: Enumerable.t
Converts the io device into a Stream. 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)
Specs:
Writes the given argument to the given device. By default the device is the standard output. The argument is expected to be a chardata (i.e. a char list or an unicode binary).
It returns :ok if it succeeds.
Examples
IO.write "sample"
#=> "sample"
IO.write :stderr, "error"
#=> "error"