Elixir v1.0.5 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 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*
expects iodata as 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. However, there are three exceptions for this rule:
:standard_io
- when the:standard_io
atom is given, it is treated as a shortcut forProcess.group_leader
:stdio
- is a shortcut for:standard_io
:stderr
- is a shortcut for:standard_error
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
Functions
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.
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.
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.
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"
Specs
getn(chardata | String.Chars.t, pos_integer) ::
chardata |
nodata
getn(device, chardata | String.Chars.t) ::
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.
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
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.
Specs
gets(device, chardata | String.Chars.t) ::
chardata |
nodata
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 volume
Specs
inspect(term, Keyword.t) :: term
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.
Examples
IO.inspect Process.list, width: 40
Inspects the item with options using the given device.
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
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>>
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.
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.
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)
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"