lib/file: add some doc and nitunits

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

diff --git a/lib/standard/file.nit b/lib/standard/file.nit
index 2009a50..8af3c70 100644 (file)
--- a/lib/standard/file.nit
+++ b/lib/standard/file.nit
@@ -47,6 +47,21 @@ abstract class FileStream
        # File descriptor of this file
        fun fd: Int do return _file.fileno
 
+       redef fun close
+       do
+               if _file == null then return
+               if _file.address_is_null then
+                       if last_error != null then return
+                       last_error = new IOError("Cannot close unopened file")
+                       return
+               end
+               var i = _file.io_close
+               if i != 0 then
+                       last_error = new IOError("Close failed due to error {sys.errno.strerror}")
+               end
+               _file = null
+       end
+
        # Sets the buffering mode for the current FileStream
        #
        # If the buf_size is <= 0, its value will be 512 by default
@@ -72,6 +87,11 @@ class FileReader
 
        # Open the same file again.
        # The original path is reused, therefore the reopened file can be a different file.
+       #
+       #     var f = new FileReader.open("/etc/issue")
+       #     var l = f.read_line
+       #     f.reopen
+       #     assert l == f.read_line
        fun reopen
        do
                if not eof and not _file.address_is_null then close
@@ -89,11 +109,9 @@ class FileReader
 
        redef fun close
        do
-               if _file == null or _file.address_is_null then return
-               var i = _file.io_close
+               super
                _buffer.clear
                end_reached = true
-               _file = null
        end
 
        redef fun fill_buffer
@@ -111,6 +129,16 @@ class FileReader
        redef var end_reached: Bool = false
 
        # Open the file at `path` for reading.
+       #
+       #     var f = new FileReader.open("/etc/issue")
+       #     assert not f.end_reached
+       #     f.close
+       #
+       # In case of error, `last_error` is set
+       #
+       #     f = new FileReader.open("/fail/does not/exist")
+       #     assert f.end_reached
+       #     assert f.last_error != null
        init open(path: String)
        do
                self.path = path
@@ -122,6 +150,9 @@ class FileReader
                end
        end
 
+       # Creates a new File stream from a file descriptor
+       #
+       # This is a low-level method.
        init from_fd(fd: Int) do
                self.path = ""
                prepare_buffer(1)
@@ -150,24 +181,12 @@ class FileWriter
                else
                        for i in s.substrings do write_native(i.to_cstring, i.length)
                end
-               _file.flush
        end
 
        redef fun close
        do
-               if _file == null then return
-               if _file.address_is_null then
-                       if last_error != null then return
-                       last_error = new IOError("Cannot close unopened write stream")
-                       _is_writable = false
-                       return
-               end
-               var i = _file.io_close
-               if i != 0 then
-                       last_error = new IOError("Close failed due to error {sys.errno.strerror}")
-               end
+               super
                _is_writable = false
-               _file = null
        end
        redef var is_writable = false
 
@@ -235,6 +254,8 @@ private fun wipe_write: NativeString do return "w".to_cstring
 ###############################################################################
 
 # Standard input stream.
+#
+# The class of the default value of `sys.stdin`.
 class Stdin
        super FileReader
 
@@ -248,16 +269,21 @@ class Stdin
 end
 
 # Standard output stream.
+#
+# The class of the default value of `sys.stdout`.
 class Stdout
        super FileWriter
        init do
                _file = new NativeFile.native_stdout
                path = "/dev/stdout"
                _is_writable = true
+               set_buffering_mode(256, sys.buffer_mode_line)
        end
 end
 
 # Standard error stream.
+#
+# The class of the default value of `sys.stderr`.
 class Stderr
        super FileWriter
        init do
@@ -330,8 +356,6 @@ class Path
        end
 
        # Delete a file from the file system, return `true` on success
-       #
-       # Require: `exists`
        fun delete: Bool do return path.to_cstring.file_delete
 
        # Copy content of file at `path` to `dest`
@@ -675,11 +699,12 @@ redef class String
        end
 
        # Simplify a file path by remove useless ".", removing "//", and resolving ".."
-       # ".." are not resolved if they start the path
-       # starting "/" is not removed
-       # trainling "/" is removed
        #
-       # Note that the method only wonrk on the string:
+       # * ".." are not resolved if they start the path
+       # * starting "/" is not removed
+       # * trailing "/" is removed
+       #
+       # Note that the method only work on the string:
        #
        #  * no I/O access is performed
        #  * the validity of the path is not checked
@@ -715,7 +740,6 @@ redef class String
        # Using a standard "{self}/{path}" does not work in the following cases:
        #
        # * `self` is empty.
-       # * `path` ends with `'/'`.
        # * `path` starts with `'/'`.
        #
        # This method ensures that the join is valid.
@@ -998,18 +1022,14 @@ end
 
 redef class Sys
 
-       init do
-               if stdout isa FileStream then stdout.as(FileStream).set_buffering_mode(256, buffer_mode_line)
-       end
-
        # Standard input
-       var stdin: PollableReader = new Stdin is protected writable
+       var stdin: PollableReader = new Stdin is protected writable, lazy
 
        # Standard output
-       var stdout: Writer = new Stdout is protected writable
+       var stdout: Writer = new Stdout is protected writable, lazy
 
        # Standard output for errors
-       var stderr: Writer = new Stderr is protected writable
+       var stderr: Writer = new Stderr is protected writable, lazy
 
        # Enumeration for buffer mode full (flushes when buffer is full)
        fun buffer_mode_full: Int is extern "file_Sys_Sys_buffer_mode_full_0"