Elixir v1.4.5 IO View Source
Functions handling input/output (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 chardata, i.e. strings or
lists of characters and strings. In case another type is given,
functions will convert 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 shortcuts:
:stdio
- a shortcut for:standard_io
, which maps to the currentProcess.group_leader/0
in Erlang:stderr
- a shortcut for the named process:standard_error
provided in Erlang
IO devices maintain their position, that means subsequent calls to any
reading or writing functions will start from the place when the device
was last accessed. Position of files can be changed using the
:file.position/2
function.
Link to this section Summary
Functions
Reads from the IO device
. The operation is Unicode unsafe
Converts the IO device
into an IO.Stream
. The operation is Unicode unsafe
Writes item
as a binary to the given device
.
No Unicode conversion happens.
The operation is Unicode unsafe
Converts chardata (a list of integers representing codepoints, lists and strings) into a string
Gets a number of bytes from IO device :stdio
Gets a number of bytes from the IO device
Reads a line from the IO device
Inspects and writes the given item
to the device
Inspects item
according to the given options using the IO device
Returns the size of an iodata
Converts iodata (a list of integers representing bytes, lists and binaries) into a binary. The operation is Unicode unsafe
Writes item
to the given device
, similar to write/2
,
but adds a newline at the end
Reads from the IO device
Converts the IO device
into an IO.Stream
Writes a message
to stderr, along with the current stacktrace
Writes a message
to stderr, along with the given stacktrace
Writes item
to the given device
Link to this section Types
Link to this section Functions
Reads from the IO device
. The operation is Unicode unsafe.
The device
is iterated by the given number of bytes or line by line if
:line
is given.
Alternatively, if :all
is given, then whole device
is returned.
It returns:
data
- the output bytes: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 | pos_integer) :: Enumerable.t
Converts the IO device
into an IO.Stream
. The operation is Unicode unsafe.
An IO.Stream
implements both Enumerable
and
Collectable
, allowing it to be used for both read
and write.
The device
is iterated by the given number of bytes or line by line if
:line
is given.
This reads from 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, iodata) :: :ok | {:error, term}
Writes item
as a binary to the given device
.
No Unicode conversion happens.
The operation is Unicode unsafe.
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 an UnicodeConversionError
.
If a string is given, it returns the string itself.
Examples
iex> IO.chardata_to_string([0x00E6, 0x00DF])
"æß"
iex> IO.chardata_to_string([0x0061, "bc"])
"abc"
iex> IO.chardata_to_string("string")
"string"
getn(chardata | String.Chars.t, pos_integer) :: chardata | nodata
getn(device, chardata | String.Chars.t) :: chardata | nodata
Gets a number of bytes from IO device :stdio
.
If :stdio
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.
See IO.getn/3
for a description of return values.
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.
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
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 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
Examples
To display “What is your name?” as a prompt and await user input:
IO.gets "What is your name?\n"
inspect(item, Keyword.t) :: item when item: var
Inspects and writes the given item
to the device.
It’s important to note that it returns the given item
unchanged.
This makes it possible to “spy” on values by inserting an
IO.inspect/2
call almost anywhere in your code, for example,
in the middle of a pipeline.
It enables pretty printing by default with width of
80 characters. The width can be changed by explicitly
passing the :width
option.
The output can be decorated with a label, by providing the :label
option to easily distinguish it from other IO.inspect/2
calls.
The label will be printed before the inspected item
.
See Inspect.Opts
for a full list of remaining formatting options.
Examples
IO.inspect <<0, 1, 2>>, width: 40
Prints:
<<0, 1, 2>>
We can use the :label
option to decorate the output:
IO.inspect 1..100, label: "a wonderful range"
Prints:
a wonderful range: 1..100
The :label
option is especially useful with pipelines:
[1, 2, 3]
|> IO.inspect(label: "before")
|> Enum.map(&(&1 * 2))
|> IO.inspect(label: "after")
|> Enum.sum
Prints:
before: [1, 2, 3]
after: [2, 4, 6]
Inspects item
according to the given options using the IO device
.
See inspect/2
for a full list of options.
Returns the size of an iodata.
Inlined by the compiler.
Examples
iex> IO.iodata_length([1, 2 | <<3, 4>>])
4
Converts iodata (a list of integers representing bytes, lists and binaries) into a binary. The operation is Unicode unsafe.
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 charlist 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, chardata | String.Chars.t) :: :ok
Writes item
to the given device
, similar to write/2
,
but adds a newline at the end.
Reads from the IO device
.
The device
is iterated by the given number of characters or line by line if
:line
is given.
Alternatively, if :all
is given, then whole device
is returned.
It returns:
data
- the output 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 | pos_integer) :: Enumerable.t
Converts the IO device
into an IO.Stream
.
An IO.Stream
implements both Enumerable
and
Collectable
, allowing it to be used for both read
and write.
The device
is iterated by the given number of characters or line by line if
:line
is given.
This reads from 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)
Writes a message
to stderr, along with the current stacktrace.
It returns :ok
if it succeeds.
Examples
IO.warn "variable bar is unused"
#=> warning: variable bar is unused
#=> (iex) evaluator.ex:108: IEx.Evaluator.eval/4
warn(chardata | String.Chars.t, Exception.stacktrace) :: :ok
Writes a message
to stderr, along with the given stacktrace
.
This function also notifies the compiler a warning was printed
(in case —warnings-as-errors was enabled). It returns :ok
if it succeeds.
An empty list can be passed to avoid stacktrace printing.
Examples
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, chardata | String.Chars.t) :: :ok
Writes item
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