Merge pull request #1098 from alco/path-expand-doc

Fix behavior of Path.expand/2. Improve docstrings

Author: José Valim

CHANGELOG.md

@@ -23,10 +23,11 @@
   * [ExUnit] Handle exit messages from in ExUnit
   * [ExUnit] Failures on ExUnit's setup_all now invalidates all tests
   * [Kernel] Ensure we don't splice keyword args unecessarily
-  * [Kernel] Private functions used by private macros no longer emit an unused warning 
+  * [Kernel] Private functions used by private macros no longer emit an unused warning
   * [Kernel] Ensure Elixir won't trip on empty receive blocks
   * [Kernel] `String.slice` now returns an empty string when out of range by 1
   * [Mix] Generate manifest files after compilation to avoid depending on directory timestamps and to remove unused .beam files
+  * [Path] `Path.expand/2` now correctly expands `~` in the second argument
   * [Regex] Fix badmatch with `Regex.captures(%r/(.)/g, "cat")`
   * [URI] Downcase host and scheme and URIs
 

lib/elixir/lib/path.ex

@@ -1,15 +1,15 @@
 defmodule Path do
   @moduledoc """
   This module provides conveniences for manipulating or
-  retrieving filesystem paths.
+  retrieving file system paths.
 
-  The functions on this module may receive a char list or
-  a binary as argument and will return the given type.
+  The functions in this module may receive a char list or
+  a binary as argument and will return a value of the same
+  type.
 
   The majority of the functions in this module do not
-  interact with the file system, unless some few functions
-  that needs to query the filesystem to retrieve paths
-  (like `Path.wildcard` and `Path.expand`).
+  interact with the file system, except for a few functions
+  that require it (like `Path.wildcard` and `Path.expand`).
   """
 
   alias :filename, as: FN
@@ -18,9 +18,8 @@ defmodule Path do
   @type r :: char_list | binary
 
   @doc """
-  Converts the given filename and returns an absolute name.
-  Differently from `Path.expand/1`, no attempt is made to
-  resolve `..`, `.` or `~`.
+  Converts the given path to an absolute one. Differently from
+  `Path.expand/1`, no attempt is made to resolve `..`, `.` or `~`.
 
   ## Unix examples
 
@@ -43,9 +42,8 @@ defmodule Path do
   end
 
   @doc """
-  Converts the given filename and returns an absolute name
-  relative to the given location. If the path is already
-  an absolute path, the relative path is ignored.
+  Builds a path from `relative_to` to `path`. If `path` is already
+  an absolute path, `relative_to` is ignored. See also `Path.relative/2`.
 
   Differently from `Path.expand/2`, no attempt is made to
   resolve `..`, `.` or `~`.
@@ -64,8 +62,8 @@ defmodule Path do
   end
 
   @doc """
-  Expands the path by returning its absolute name and expanding
-  any `.` and `..` characters.
+  Converts the path to an absolute one and expands
+  any `.` and `..` characters and a leading `~`.
 
   ## Examples
 
@@ -78,20 +76,29 @@ defmodule Path do
   end
 
   @doc """
-  Expands the path to the relative location and expanding
-  any `.` and `..` characters. If the path is already an
-  absolute path, the relative location is ignored.
+  Expands the path relative to the path given as the second argument
+  expanding any `.` and `..` characters. If the path is already an
+  absolute path, `relative_to` is ignored.
+
+  Note, that this function treats `path` with leading `~` as
+  an absolute one.
+
+  The second argument is first expanded to an absolute path.
 
   ## Examples
 
+      # Assuming that the absolute path to baz is /quux/baz
+      Path.expand("foo/bar/../bar", "baz")
+      #=> "/quux/baz/foo/bar"
+
       iex> Path.expand("foo/bar/../bar", "/baz")
       "/baz/foo/bar"
       iex> Path.expand("/foo/bar/../bar", "/baz")
       "/foo/bar"
 
   """
   def expand(path, relative_to) do
-    normalize FN.absname(FN.absname(expand_home(path), relative_to), get_cwd(path))
+    normalize FN.absname(FN.absname(expand_home(path), expand_home(relative_to)), get_cwd(path))
   end
 
   @doc """
@@ -102,6 +109,7 @@ defmodule Path do
       Path.type("/usr/local/bin")   #=> :absolute
       Path.type("usr/local/bin")    #=> :relative
       Path.type("../usr/local/bin") #=> :relative
+      Path.type("~/file")           #=> :relative
 
   ## Windows examples
 
@@ -185,8 +193,9 @@ defmodule Path do
 
   @doc """
   Returns the given `path` relative to the given `from` path.
+  In other words, it tries to strip the `from` prefix from `path`.
 
-  This function does not query the filesystem, so it assumes
+  This function does not query the file system, so it assumes
   no symlinks in between the paths.
 
   In case a direct relative path cannot be found, it returns
@@ -267,20 +276,22 @@ defmodule Path do
   end
 
   @doc """
-  Return the `directory` component of `path`.
+  Returns the directory component of `path`.
 
   ## Examples
 
       Path.dirname("/foo/bar.ex")
-      #=> "foo"
+      #=> "/foo"
+      Path.dirname("/foo/bar/baz.ex")
+      #=> "/foo/bar"
 
   """
   def dirname(path) do
     FN.dirname(path)
   end
 
   @doc """
-  Return the `extension` of the last component of `path`.
+  Returns the extension of the last component of `path`.
 
   ## Examples
 
@@ -326,8 +337,8 @@ defmodule Path do
   end
 
   @doc """
-  Returns a string with one or more paths components joint by the path separator.
-  This function should be used to convert a list of strings in a path.
+  Returns a string with one or more path components joined by the path separator.
+  This function should be used to convert a list of strings to a path.
 
   ## Examples
 
@@ -409,8 +420,8 @@ defmodule Path do
     :lists.reverse(name)
 
   @doc """
-  Returns a list with the path splitted by the path separator.
-  If an empty string is given, then it returns the root path.
+  Returns a list with the path split by the path separator.
+  If an empty string is given, returns the root path.
 
   ## Examples
 
@@ -450,7 +461,7 @@ defmodule Path do
 
   Imagine you have a directory called `projects` with three Elixir projects
   inside of it: `elixir`, `ex_doc` and `dynamo`. You can find all `.beam` files
-  inside their ebin directories all projects as follows:
+  inside the ebin directory of each project as follows:
 
       Path.wildcard("projects/*/ebin/**/*.beam")
 
@@ -520,4 +531,4 @@ defmodule Path do
   defp normalize([], acc) do
     join Enum.reverse(acc)
   end
-end
+end

lib/elixir/test/elixir/path_test.exs

@@ -98,11 +98,18 @@ defmodule PathTest do
   end
 
   test :expand_path_with_user_home do
-    assert System.user_home! == Path.expand("~")
+    home = System.user_home!
+
+    assert home == Path.expand("~")
     assert is_binary Path.expand("~/foo")
 
-    assert (System.user_home! |> :unicode.characters_to_list) == Path.expand('~')
+    assert (home |> :unicode.characters_to_list) == Path.expand('~')
     assert is_list Path.expand('~/foo')
+
+    assert Path.expand("~/file") == Path.join(home, "file")
+    assert Path.expand("~/file", "whatever") == Path.join(home, "file")
+    assert Path.expand("file", Path.expand("~")) == Path.expand("~/file")
+    assert Path.expand("file", "~") == Path.join(home, "file")
   end
 
   test :expand_path_with_binary do
@@ -171,6 +178,7 @@ defmodule PathTest do
 
   test :dirname_with_binary do
     assert Path.dirname("/foo/bar.ex") == "/foo"
+    assert Path.dirname("foo/bar.ex") == "foo"
     assert Path.dirname("~/foo/bar.ex") == "~/foo"
     assert Path.dirname("/foo/bar/baz/") == "/foo/bar/baz"
   end
@@ -240,4 +248,4 @@ defmodule PathTest do
     assert Path.split('foo') == ['foo']
     assert Path.split('/foo/bar') == ['/', 'foo', 'bar']
   end
-end
+end