file: fix missing documentation warnings
[nit.git] / lib / standard / file.nit
index 0d00cdd..d5c1fd1 100644 (file)
@@ -16,7 +16,7 @@
 module file
 
 intrude import stream
-intrude import string
+intrude import ropes
 import string_search
 import time
 
@@ -26,58 +26,30 @@ in "C Header" `{
        #include <sys/types.h>
        #include <sys/stat.h>
        #include <unistd.h>
+       #include <stdio.h>
 `}
 
-redef class Object
-# Simple I/O
-
-       # Print `objects` on the standard output (`stdout`).
-       protected fun printn(objects: Object...)
-       do
-               stdout.write(objects.to_s)
-       end
-
-       # Print an `object` on the standard output (`stdout`) and add a newline.
-       protected fun print(object: Object)
-       do
-               stdout.write(object.to_s)
-               stdout.write("\n")
-       end
-
-       # Read a character from the standard input (`stdin`).
-       protected fun getc: Char
-       do
-               return stdin.read_char.ascii
-       end
-
-       # Read a line from the standard input (`stdin`).
-       protected fun gets: String
-       do
-               return stdin.read_line
-       end
-
-       # Return the working (current) directory
-       protected fun getcwd: String do return file_getcwd.to_s
-       private fun file_getcwd: NativeString is extern "string_NativeString_NativeString_file_getcwd_0"
-end
-
 # File Abstract Stream
 abstract class FStream
        super IOS
        # The path of the file.
-       readable var _path: nullable String = null
+       var path: nullable String = null
 
        # The FILE *.
-       var _file: nullable NativeFile = null
+       private var file: nullable NativeFile = null
 
-       fun file_stat: FileStat
-       do return _file.file_stat end
+       # The status of a file. see POSIX stat(2).
+       fun file_stat: FileStat do return _file.file_stat
+
+       # File descriptor of this file
+       fun fd: Int do return _file.fileno
 end
 
 # File input stream
 class IFStream
        super FStream
        super BufferedIStream
+       super PollableIStream
        # Misc
 
        # Open the same file again.
@@ -85,8 +57,8 @@ class IFStream
        fun reopen
        do
                if not eof then close
-               _file = new NativeFile.io_open_read(_path.to_cstring)
-               _end_reached = false
+               _file = new NativeFile.io_open_read(path.to_cstring)
+               end_reached = false
                _buffer_pos = 0
                _buffer.clear
        end
@@ -94,34 +66,35 @@ class IFStream
        redef fun close
        do
                var i = _file.io_close
-               _end_reached = true
+               _buffer.clear
+               end_reached = true
        end
 
        redef fun fill_buffer
        do
-               var nb = _file.io_read(_buffer._items, _buffer._capacity)
+               var nb = _file.io_read(_buffer.items, _buffer.capacity)
                if nb <= 0 then
-                       _end_reached = true
+                       end_reached = true
                        nb = 0
                end
-               _buffer._length = nb
+               _buffer.length = nb
                _buffer_pos = 0
        end
        
        # End of file?
-       redef readable var _end_reached: Bool = false
+       redef var end_reached: Bool = false
 
        # Open the file at `path` for reading.
        init open(path: String)
        do
-               _path = path
+               self.path = path
                prepare_buffer(10)
-               _file = new NativeFile.io_open_read(_path.to_cstring)
-               assert cant_open_file: _file != null
+               _file = new NativeFile.io_open_read(path.to_cstring)
+               assert not _file.address_is_null else
+                       print "Error: Opening file at '{path}' failed with '{sys.errno.strerror}'"
+               end
        end
 
-       private init do end
-       private init without_file do end
 end
 
 # File output stream
@@ -131,25 +104,26 @@ class OFStream
        
        redef fun write(s)
        do
-               assert _writable
-               write_native(s.to_cstring, s.length)
+               assert _is_writable
+               if s isa FlatText then
+                       write_native(s.to_cstring, s.length)
+               else
+                       for i in s.substrings do write_native(i.to_cstring, i.length)
+               end
        end
 
-       redef fun is_writable do return _writable
-       
        redef fun close
        do
                var i = _file.io_close
-               _writable = false
+               _is_writable = false
        end
 
-       # Is the file open in write mode
-       var _writable: Bool
+       redef var is_writable = false
        
        # Write `len` bytes from `native`.
        private fun write_native(native: NativeString, len: Int)
        do
-               assert _writable
+               assert _is_writable
                var err = _file.io_write(native, len)
                if err != len then
                        # Big problem
@@ -161,45 +135,46 @@ class OFStream
        init open(path: String)
        do
                _file = new NativeFile.io_open_write(path.to_cstring)
-               assert cant_open_file: _file != null
-               _path = path
-               _writable = true
+               assert not _file.address_is_null else
+                       print "Error: Opening file at '{path}' failed with '{sys.errno.strerror}'"
+               end
+               self.path = path
+               _is_writable = true
        end
-       
-       private init do end
-       private init without_file do end
 end
 
 ###############################################################################
 
+# Standard input stream.
 class Stdin
        super IFStream
-       private init do
+
+       init do
                _file = new NativeFile.native_stdin
-               _path = "/dev/stdin"
+               path = "/dev/stdin"
                prepare_buffer(1)
        end
 
-       # Is these something to read? (non blocking)
-       # FIXME: should be generalized
-       fun poll_in: Bool is extern "file_stdin_poll_in"
+       redef fun poll_in: Bool is extern "file_stdin_poll_in"
 end
 
+# Standard output stream.
 class Stdout
        super OFStream
-       private init do
+       init do
                _file = new NativeFile.native_stdout
-               _path = "/dev/stdout"
-               _writable = true
+               path = "/dev/stdout"
+               _is_writable = true
        end
 end
 
+# Standard error stream.
 class Stderr
        super OFStream
-       private init do
+       init do
                _file = new NativeFile.native_stderr
-               _path = "/dev/stderr"
-               _writable = true
+               path = "/dev/stderr"
+               _is_writable = true
        end
 end
 
@@ -274,10 +249,10 @@ redef class String
        #     assert "".basename("")                            == ""
        fun basename(ext: String): String
        do
-               var l = _length - 1 # Index of the last char
+               var l = length - 1 # Index of the last char
                while l > 0 and self.chars[l] == '/' do l -= 1 # remove all trailing `/`
                if l == 0 then return "/"
-               var pos = last_index_of_from('/', l)
+               var pos = chars.last_index_of_from('/', l)
                var n = self
                if pos >= 0 then
                        n = substring(pos+1, l-pos)
@@ -297,9 +272,9 @@ redef class String
        #     assert "".dirname                            == "."
        fun dirname: String
        do
-               var l = _length - 1 # Index of the last char
+               var l = length - 1 # Index of the last char
                while l > 0 and self.chars[l] == '/' do l -= 1 # remove all trailing `/`
-               var pos = last_index_of_from('/', l)
+               var pos = chars.last_index_of_from('/', l)
                if pos > 0 then
                        return substring(0, pos)
                else if pos == 0 then
@@ -331,6 +306,7 @@ redef class String
        #     assert "dir/../../".simplify_path        ==  ".."
        #     assert "dir/..".simplify_path            ==  "."
        #     assert "//absolute//path/".simplify_path ==  "/absolute/path"
+       #     assert "//absolute//../".simplify_path   ==  "/"
        fun simplify_path: String
        do
                var a = self.split_with("/")
@@ -345,37 +321,140 @@ redef class String
                        a2.push(x)
                end
                if a2.is_empty then return "."
+               if a2.length == 1 and a2.first == "" then return "/"
                return a2.join("/")
        end
 
        # Correctly join two path using the directory separator.
        #
-       # Using a standard "{self}/{path}" does not work when `self` is the empty string.
-       # This method ensure that the join is valid.
+       # Using a standard "{self}/{path}" does not work in the following cases:
+       #
+       # * `self` is empty.
+       # * `path` ends with `'/'`.
+       # * `path` starts with `'/'`.
        #
-       #     assert "hello".join_path("world")      ==  "hello/world"
-       #     assert "hel/lo".join_path("wor/ld")      ==  "hel/lo/wor/ld"
-       #     assert "".join_path("world")      ==  "world"
-       #     assert "/hello".join_path("/world")      ==  "/world"
+       # This method ensures that the join is valid.
        #
-       # Note: you may want to use `simplify_path` on the result
+       #     assert "hello".join_path("world")   == "hello/world"
+       #     assert "hel/lo".join_path("wor/ld") == "hel/lo/wor/ld"
+       #     assert "".join_path("world")        == "world"
+       #     assert "hello".join_path("/world")  == "/world"
+       #     assert "hello/".join_path("world")  == "hello/world"
+       #     assert "hello/".join_path("/world") == "/world"
        #
-       # Note: I you want to join a great number of path, you can write
+       # Note: You may want to use `simplify_path` on the result.
        #
-       #     [p1, p2, p3, p4].join("/")
+       # Note: This method works only with POSIX paths.
        fun join_path(path: String): String
        do
                if path.is_empty then return self
                if self.is_empty then return path
                if path.chars[0] == '/' then return path
+               if self.last == '/' then return "{self}{path}"
                return "{self}/{path}"
        end
 
+       # Convert the path (`self`) to a program name.
+       #
+       # Ensure the path (`self`) will be treated as-is by POSIX shells when it is
+       # used as a program name. In order to do that, prepend `./` if needed.
+       #
+       #     assert "foo".to_program_name == "./foo"
+       #     assert "/foo".to_program_name == "/foo"
+       #     assert "".to_program_name == "./" # At least, your shell will detect the error.
+       fun to_program_name: String do
+               if self.has_prefix("/") then
+                       return self
+               else
+                       return "./{self}"
+               end
+       end
+
+       # Alias for `join_path`
+       #
+       #     assert "hello" / "world"      ==  "hello/world"
+       #     assert "hel/lo" / "wor/ld"    ==  "hel/lo/wor/ld"
+       #     assert "" / "world"           ==  "world"
+       #     assert "/hello" / "/world"    ==  "/world"
+       #
+       # This operator is quite useful for chaining changes of path.
+       # The next one being relative to the previous one.
+       #
+       #     var a = "foo"
+       #     var b = "/bar"
+       #     var c = "baz/foobar"
+       #     assert a/b/c == "/bar/baz/foobar"
+       fun /(path: String): String do return join_path(path)
+
+       # Returns the relative path needed to go from `self` to `dest`.
+       #
+       #     assert "/foo/bar".relpath("/foo/baz") == "../baz"
+       #     assert "/foo/bar".relpath("/baz/bar") == "../../baz/bar"
+       #
+       # If `self` or `dest` is relative, they are considered relatively to `getcwd`.
+       #
+       # In some cases, the result is still independent of the current directory:
+       #
+       #     assert "foo/bar".relpath("..") == "../../.."
+       #
+       # In other cases, parts of the current directory may be exhibited:
+       #
+       #     var p = "../foo/bar".relpath("baz")
+       #     var c = getcwd.basename("")
+       #     assert p == "../../{c}/baz"
+       #
+       # For path resolution independent of the current directory (eg. for paths in URL),
+       # or to use an other starting directory than the current directory,
+       # just force absolute paths:
+       #
+       #     var start = "/a/b/c/d"
+       #     var p2 = (start/"../foo/bar").relpath(start/"baz")
+       #     assert p2 == "../../d/baz"
+       #
+       #
+       # Neither `self` or `dest` has to be real paths or to exist in directories since
+       # the resolution is only done with string manipulations and without any access to
+       # the underlying file system.
+       #
+       # If `self` and `dest` are the same directory, the empty string is returned:
+       #
+       #     assert "foo".relpath("foo") == ""
+       #     assert "foo/../bar".relpath("bar") == ""
+       #
+       # The empty string and "." designate both the current directory:
+       #
+       #     assert "".relpath("foo/bar")  == "foo/bar"
+       #     assert ".".relpath("foo/bar") == "foo/bar"
+       #     assert "foo/bar".relpath("")  == "../.."
+       #     assert "/" + "/".relpath(".") == getcwd
+       fun relpath(dest: String): String
+       do
+               var cwd = getcwd
+               var from = (cwd/self).simplify_path.split("/")
+               if from.last.is_empty then from.pop # case for the root directory
+               var to = (cwd/dest).simplify_path.split("/")
+               if to.last.is_empty then to.pop # case for the root directory
+
+               # Remove common prefixes
+               while not from.is_empty and not to.is_empty and from.first == to.first do
+                       from.shift
+                       to.shift
+               end
+
+               # Result is going up in `from` with ".." then going down following `to`
+               var from_len = from.length
+               if from_len == 0 then return to.join("/")
+               var up = "../"*(from_len-1) + ".."
+               if to.is_empty then return up
+               var res = up + "/" + to.join("/")
+               return res
+       end
+
        # Create a directory (and all intermediate directories if needed)
        fun mkdir
        do
                var dirs = self.split_with("/")
-               var path = new Buffer
+               var path = new FlatBuffer
                if dirs.is_empty then return
                if dirs[0].is_empty then
                        # it was a starting /
@@ -389,6 +468,30 @@ redef class String
                end
        end
 
+       # Delete a directory and all of its content, return `true` on success
+       #
+       # Does not go through symbolic links and may get stuck in a cycle if there
+       # is a cycle in the filesystem.
+       fun rmdir: Bool
+       do
+               var ok = true
+               for file in self.files do
+                       var file_path = self.join_path(file)
+                       var stat = file_path.file_lstat
+                       if stat.is_dir then
+                               ok = file_path.rmdir and ok
+                       else
+                               ok = file_path.file_delete and ok
+                       end
+                       stat.free
+               end
+
+               # Delete the directory itself
+               if ok then to_cstring.rmdir
+
+               return ok
+       end
+
        # Change the current working directory
        #
        #     "/etc".chdir
@@ -419,7 +522,7 @@ redef class String
        #     assert ".file".file_extension         == null
        fun file_extension: nullable String
        do
-               var last_slash = last_index_of('.')
+               var last_slash = chars.last_index_of('.')
                if last_slash > 0 then
                        return substring( last_slash+1, length )
                else
@@ -472,6 +575,7 @@ redef class NativeString
                return stat_element;
        `}
        private fun file_mkdir: Bool is extern "string_NativeString_NativeString_file_mkdir_0"
+       private fun rmdir: Bool `{ return rmdir(recv); `}
        private fun file_delete: Bool is extern "string_NativeString_NativeString_file_delete_0"
        private fun file_chdir is extern "string_NativeString_NativeString_file_chdir_0"
        private fun file_realpath: NativeString is extern "file_NativeString_realpath"
@@ -507,11 +611,12 @@ extern class FileStat `{ struct stat * `}
 end
 
 # Instance of this class are standard FILE * pointers
-private extern NativeFile `{ FILE* `}
+private extern class NativeFile `{ FILE* `}
        fun io_read(buf: NativeString, len: Int): Int is extern "file_NativeFile_NativeFile_io_read_2"
        fun io_write(buf: NativeString, len: Int): Int is extern "file_NativeFile_NativeFile_io_write_2"
        fun io_close: Int is extern "file_NativeFile_NativeFile_io_close_0"
        fun file_stat: FileStat is extern "file_NativeFile_NativeFile_file_stat_0"
+       fun fileno: Int `{ return fileno(recv); `}
 
        new io_open_read(path: NativeString) is extern "file_NativeFileCapable_NativeFileCapable_io_open_read_1"
        new io_open_write(path: NativeString) is extern "file_NativeFileCapable_NativeFileCapable_io_open_write_1"
@@ -520,11 +625,44 @@ private extern NativeFile `{ FILE* `}
        new native_stderr is extern "file_NativeFileCapable_NativeFileCapable_native_stderr_0"
 end
 
-# Standard input.
-fun stdin: Stdin do return once new Stdin
+redef class Sys
+
+       # Standard input
+       var stdin: PollableIStream = new Stdin is protected writable
+
+       # Standard output
+       var stdout: OStream = new Stdout is protected writable
+
+       # Standard output for errors
+       var stderr: OStream = new Stderr is protected writable
 
-# Standard output.
-fun stdout: OFStream do return once new Stdout
+end
+
+# Print `objects` on the standard output (`stdout`).
+protected fun printn(objects: Object...)
+do
+       sys.stdout.write(objects.to_s)
+end
+
+# Print an `object` on the standard output (`stdout`) and add a newline.
+protected fun print(object: Object)
+do
+       sys.stdout.write(object.to_s)
+       sys.stdout.write("\n")
+end
+
+# Read a character from the standard input (`stdin`).
+protected fun getc: Char
+do
+       return sys.stdin.read_char.ascii
+end
+
+# Read a line from the standard input (`stdin`).
+protected fun gets: String
+do
+       return sys.stdin.read_line
+end
 
-# Standard output for error.
-fun stderr: OFStream do return once new Stderr
+# Return the working (current) directory
+protected fun getcwd: String do return file_getcwd.to_s
+private fun file_getcwd: NativeString is extern "string_NativeString_NativeString_file_getcwd_0"