Add typespecs and to_string conversion to some IO APIs

Author: José Valim

lib/elixir/lib/io.ex

@@ -7,29 +7,26 @@ end
 
 defmodule IO do
   @moduledoc """
-  Module responsible for doing IO. Many functions in this
-  module expects an IO device and an io data encoded in UTF-8.
-  Use the bin* functions if the data is binary, useful when
-  working with raw bytes or when no unicode conversion should
-  be performed.
+  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`.
 
-  An io data can be:
+  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).
 
-  * A list of integers representing a string. Any unicode
-    character must be represented with one entry in the list,
-    this entry being an integer with the codepoint value;
-
-  * A binary in which unicode characters are represented
-    with many bytes (Elixir's default representation);
-
-  * A list of binaries or a list of char lists (as described above);
+  The functions starting with `bin*` expects iodata as arguments,
+  i.e. iolists or binaries with no particular encoding.
 
   """
 
+  @type device   :: atom | pid
+  @type chardata :: char_list | String.Chars.t
+  @type nodata :: { :error, term } | :eof
+
   import :erlang, only: [group_leader: 0]
 
   defmacrop is_iolist(data) do
@@ -50,6 +47,7 @@ defmodule IO do
     for instance `{:error, :estale}` if reading from an
     NFS file system.
   """
+  @spec read(device, :line | non_neg_integer) :: chardata | nodata
   def read(device // group_leader, chars_or_line)
 
   def read(device, :line) do
@@ -72,6 +70,7 @@ defmodule IO do
     for instance `{:error, :estale}` if reading from an
     NFS file system.
   """
+  @spec binread(device, :line | non_neg_integer) :: iodata | nodata
   def binread(device // group_leader, chars_or_line)
 
   def binread(device, :line) do
@@ -105,8 +104,9 @@ defmodule IO do
       #=> "error"
 
   """
-  def write(device // group_leader(), item) when is_iolist(item) do
-    :io.put_chars map_dev(device), item
+  @spec write(device, chardata) :: :ok
+  def write(device // group_leader(), item) do
+    :io.put_chars map_dev(device), to_chardata(item)
   end
 
   @doc """
@@ -115,6 +115,7 @@ defmodule IO do
 
   Check `write/2` for more information.
   """
+  @spec binwrite(device, iodata) :: :ok | { :error, term }
   def binwrite(device // group_leader(), item) when is_iolist(item) do
     :file.write map_dev(device), item
   end
@@ -124,9 +125,10 @@ defmodule IO do
   but adds a newline at the end. The argument is expected
   to be a chardata.
   """
-  def puts(device // group_leader(), item) when is_iolist(item) do
+  @spec puts(device, chardata) :: :ok
+  def puts(device // group_leader(), item) do
     erl_dev = map_dev(device)
-    :io.put_chars erl_dev, [item, ?\n]
+    :io.put_chars erl_dev, [to_chardata(item), ?\n]
   end
 
   @doc """
@@ -142,13 +144,15 @@ defmodule IO do
       IO.inspect Process.list
 
   """
+  @spec inspect(term, Keyword.t) :: term
   def inspect(item, opts // []) do
     inspect group_leader(), item, opts
   end
 
   @doc """
   Inspects the item with options using the given device.
   """
+  @spec inspect(device, term, Keyword.t) :: term
   def inspect(device, item, opts) when is_list(opts) do
     opts = Keyword.put_new(opts, :pretty, true)
 
@@ -178,6 +182,8 @@ defmodule IO do
     for instance `{:error, :estale}` if reading from an
     NFS file system.
   """
+  @spec getn(chardata, pos_integer) :: chardata | nodata
+  @spec getn(device, chardata) :: chardata | nodata
   def getn(prompt, count // 1)
 
   def getn(prompt, count) when is_integer(count) do
@@ -194,8 +200,9 @@ defmodule IO do
   the number of unicode codepoints to be retrieved.
   Otherwise, `count` is the number of raw bytes to be retrieved.
   """
+  @spec getn(device, chardata, pos_integer) :: chardata | nodata
   def getn(device, prompt, count) do
-    :io.get_chars(map_dev(device), prompt, count)
+    :io.get_chars(map_dev(device), to_chardata(prompt), count)
   end
 
   @doc """
@@ -210,8 +217,9 @@ defmodule IO do
     for instance `{:error, :estale}` if reading from an
     NFS file system.
   """
+  @spec gets(device, chardata) :: chardata | nodata
   def gets(device // group_leader(), prompt) do
-    :io.get_line(map_dev(device), prompt)
+    :io.get_line(map_dev(device), to_chardata(prompt))
   end
 
   @doc """
@@ -230,8 +238,9 @@ defmodule IO do
       Enum.each IO.stream(:stdio, :line), &IO.write(&1)
 
   """
-  def stream(device, line_or_bytes) do
-    fn(acc, f) -> stream(map_dev(device), line_or_bytes, acc, f) end
+  @spec stream(device, :line | pos_integer) :: Enumerable.t
+  def stream(device, line_or_codepoints) do
+    fn(acc, f) -> stream(map_dev(device), line_or_codepoints, acc, f) end
   end
 
   @doc """
@@ -240,6 +249,7 @@ defmodule IO do
 
   This reads the io as a raw binary.
   """
+  @spec binstream(device, :line | pos_integer) :: Enumerable.t
   def binstream(device, line_or_bytes) do
     fn(acc, f) -> binstream(map_dev(device), line_or_bytes, acc, f) end
   end
@@ -272,4 +282,7 @@ defmodule IO do
   defp map_dev(:stdio),  do: :standard_io
   defp map_dev(:stderr), do: :standard_error
   defp map_dev(other),   do: other
+
+  defp to_chardata(list) when is_list(list), do: list
+  defp to_chardata(other), do: to_string(other)
 end

lib/elixir/test/elixir/io_test.exs

@@ -2,6 +2,7 @@ Code.require_file "test_helper.exs", __DIR__
 
 defmodule IOTest do
   use ExUnit.Case, async: true
+  import ExUnit.CaptureIO
 
   test :read_with_count do
     { :ok, file } = File.open(Path.expand('../fixtures/file.txt', __FILE__), [:charlist])
@@ -77,4 +78,32 @@ defmodule IOTest do
     assert "日\n" == IO.binread(file, :line)
     assert File.close(file) == :ok
   end
+
+  test :puts_with_chardata do
+    assert capture_io(fn -> IO.puts("hello") end) == "hello\n"
+    assert capture_io(fn -> IO.puts('hello') end) == "hello\n"
+    assert capture_io(fn -> IO.puts(:hello) end) == "hello\n"
+    assert capture_io(fn -> IO.puts(13) end) == "13\n"
+  end
+
+  test :write_with_chardata do
+    assert capture_io(fn -> IO.write("hello") end) == "hello"
+    assert capture_io(fn -> IO.write('hello') end) == "hello"
+    assert capture_io(fn -> IO.write(:hello) end) == "hello"
+    assert capture_io(fn -> IO.write(13) end) == "13"
+  end
+
+  test :gets_with_chardata do
+    assert capture_io("foo\n", fn -> IO.gets("hello") end) == "hello"
+    assert capture_io("foo\n", fn -> IO.gets('hello') end) == "hello"
+    assert capture_io("foo\n", fn -> IO.gets(:hello) end) == "hello"
+    assert capture_io("foo\n", fn -> IO.gets(13) end) == "13"
+  end
+
+  test :getn_with_chardata do
+    assert capture_io("foo\n", fn -> IO.getn("hello", 3) end) == "hello"
+    assert capture_io("foo\n", fn -> IO.getn('hello', 3) end) == "hello"
+    assert capture_io("foo\n", fn -> IO.getn(:hello, 3) end) == "hello"
+    assert capture_io("foo\n", fn -> IO.getn(13, 3) end) == "13"
+  end
 end