file: fix missing documentation warnings
[nit.git] / lib / standard / file.nit
index b797da1..d5c1fd1 100644 (file)
@@ -26,6 +26,7 @@ in "C Header" `{
        #include <sys/types.h>
        #include <sys/stat.h>
        #include <unistd.h>
+       #include <stdio.h>
 `}
 
 # File Abstract Stream
@@ -35,16 +36,20 @@ abstract class FStream
        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.
@@ -61,6 +66,7 @@ class IFStream
        redef fun close
        do
                var i = _file.io_close
+               _buffer.clear
                end_reached = true
        end
 
@@ -89,8 +95,6 @@ class IFStream
                end
        end
 
-       private init do end
-       private init without_file do end
 end
 
 # File output stream
@@ -100,7 +104,7 @@ class OFStream
        
        redef fun write(s)
        do
-               assert _writable
+               assert _is_writable
                if s isa FlatText then
                        write_native(s.to_cstring, s.length)
                else
@@ -108,21 +112,18 @@ class OFStream
                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
@@ -138,20 +139,17 @@ class OFStream
                        print "Error: Opening file at '{path}' failed with '{sys.errno.strerror}'"
                end
                self.path = path
-               _writable = true
+               _is_writable = true
        end
-       
-       private init do end
-       private init without_file do end
 end
 
 ###############################################################################
 
+# Standard input stream.
 class Stdin
        super IFStream
-       super PollableIStream
 
-       private init do
+       init do
                _file = new NativeFile.native_stdin
                path = "/dev/stdin"
                prepare_buffer(1)
@@ -160,21 +158,23 @@ class Stdin
        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
+               _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
+               _is_writable = true
        end
 end
 
@@ -306,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("/")
@@ -320,32 +321,135 @@ 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
@@ -364,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
@@ -447,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"
@@ -487,6 +616,7 @@ private extern class NativeFile `{ FILE* `}
        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"
@@ -498,13 +628,13 @@ end
 redef class Sys
 
        # Standard input
-       var stdin: PollableIStream protected writable = new Stdin
+       var stdin: PollableIStream = new Stdin is protected writable
 
        # Standard output
-       var stdout: OStream protected writable = new Stdout
+       var stdout: OStream = new Stdout is protected writable
 
        # Standard output for errors
-       var stderr: OStream protected writable = new Stderr
+       var stderr: OStream = new Stderr is protected writable
 
 end