Merge: Newstreams

[nit.git] / lib / standard / stream.nit

diff --git a/lib/standard/stream.nit b/lib/standard/stream.nit
index f928fac..933523a 100644 (file)
--- a/lib/standard/stream.nit
+++ b/lib/standard/stream.nit
@@ -61,6 +61,30 @@ abstract class IStream
        end
 
        # Read a string until the end of the line.
+       #
+       # The line terminator '\n', if any, is preserved in each line.
+       # Use the method `Text::chomp` to safely remove it.
+       #
+       # ~~~
+       # var txt = "Hello\n\nWorld\n"
+       # var i = new StringIStream(txt)
+       # assert i.read_line == "Hello\n"
+       # assert i.read_line == "\n"
+       # assert i.read_line == "World\n"
+       # assert i.eof
+       # ~~~
+       #
+       # If `\n` is not present at the end of the result, it means that
+       # a non-eol terminated last line was returned.
+       #
+       # ~~~
+       # var i2 = new StringIStream("hello")
+       # assert not i2.eof
+       # assert i2.read_line == "hello"
+       # assert i2.eof
+       # ~~~
+       #
+       # NOTE: Only LINE FEED (`\n`) is considered to delimit the end of lines.
        fun read_line: String
        do
                if last_error != null then return ""
@@ -70,6 +94,29 @@ abstract class IStream
                return s.to_s
        end
 
+       # Read all the lines until the eof.
+       #
+       # The line terminator '\n' is removed in each line,
+       #
+       # ~~~
+       # var txt = "Hello\n\nWorld\n"
+       # var i = new StringIStream(txt)
+       # assert i.read_lines == ["Hello", "", "World"]
+       # ~~~
+       #
+       # This method is more efficient that splitting
+       # the result of `read_all`.
+       #
+       # NOTE: Only LINE FEED (`\n`) is considered to delimit the end of lines.
+       fun read_lines: Array[String]
+       do
+               var res = new Array[String]
+               while not eof do
+                       res.add read_line.chomp
+               end
+               return res
+       end
+
        # Read all the stream until the eof.
        fun read_all: String
        do
@@ -83,6 +130,8 @@ abstract class IStream
        end
 
        # Read a string until the end of the line and append it to `s`.
+       #
+       # SEE: `read_line` for details.
        fun append_line_to(s: Buffer)
        do
                if last_error != null then return
@@ -263,6 +312,7 @@ abstract class BufferedIStream
        end
 end
 
+# An Input/Output Stream
 abstract class IOStream
        super IStream
        super OStream
@@ -283,7 +333,9 @@ class StringOStream
                content.add(str.to_s)
        end
 
+       # Is the stream closed?
        protected var closed = false
+
        redef fun close do closed = true
 end