Path
This module provides conveniences for manipulating or retrieving file system paths.
The functions in this module may receive a char list or a binary as an 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, except for a few functions
that require it (like wildcard/1 and expand/1).
Summary
| absname(path) | Converts the given path to an absolute one. Unlike
|
| absname(path, relative_to) | Builds a path from |
| basename(path) | Returns the last component of the path or the path itself if it does not contain any directory separators |
| basename(path, extension) | Returns the last component of |
| dirname(path) | Returns the directory component of |
| expand(path) | Converts the path to an absolute one and expands
any |
| expand(path, relative_to) | Expands the path relative to the path given as the second argument
expanding any |
| extname(path) | Returns the extension of the last component of |
| join(list1) | 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 |
| join(left, right) | Joins two paths |
| relative(name) | Forces the path to be a relative path |
| relative_to(path, from) | Returns the given |
| relative_to_cwd(path) | Convenience to get the path relative to the current working directory. If, for some reason, the current working directory cannot be retrieved, returns the full path |
| rootname(path) | Returns the |
| rootname(path, extension) | Returns the |
| split(path) | Returns a list with the path split by the path separator. If an empty string is given, returns the root path |
| type(name) | Returns the path type |
| wildcard(glob) | Traverses paths according to the given |
Functions
Converts the given path to an absolute one. Unlike
expand/1, no attempt is made to resolve .., . or ~.
Unix examples
Path.absname("foo")
#=> "/usr/local/foo"
Path.absname("../x")
#=> "/usr/local/../x"
Windows
Path.absname("foo").
"D:/usr/local/foo"
Path.absname("../x").
"D:/usr/local/../x"
Builds a path from relative_to to path. If path is already
an absolute path, relative_to is ignored. See also relative_to/2.
Unlike expand/2, no attempt is made to
resolve .., . or ~.
Examples
iex> Path.absname("foo", "bar")
"bar/foo"
iex> Path.absname("../x", "bar")
"bar/../x"
Returns the last component of the path or the path itself if it does not contain any directory separators.
Examples
iex> Path.basename("foo")
"foo"
iex> Path.basename("foo/bar")
"bar"
iex> Path.basename("/")
""
Returns the last component of path with the extension
stripped. This function should be used to remove a specific
extension which may, or may not, be there.
Examples
iex> Path.basename("~/foo/bar.ex", ".ex")
"bar"
iex> Path.basename("~/foo/bar.exs", ".ex")
"bar.exs"
iex> Path.basename("~/foo/bar.old.ex", ".ex")
"bar.old"
Returns the directory component of path.
Examples
Path.dirname("/foo/bar.ex")
#=> "/foo"
Path.dirname("/foo/bar/baz.ex")
#=> "/foo/bar"
Converts the path to an absolute one and expands
any . and .. characters and a leading ~.
Examples
Path.expand("/foo/bar/../bar")
"/foo/bar"
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 a 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"
Path.expand("foo/bar/../bar", "/baz")
"/baz/foo/bar"
Path.expand("/foo/bar/../bar", "/baz")
"/foo/bar"
Returns the extension of the last component of path.
Examples
iex> Path.extname("foo.erl")
".erl"
iex> Path.extname("~/foo/bar")
""
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
iex> Path.join(["~", "foo"])
"~/foo"
iex> Path.join(["foo"])
"foo"
iex> Path.join(["/", "foo", "bar"])
"/foo/bar"
Joins two paths.
Examples
iex> Path.join("foo", "bar")
"foo/bar"
Forces the path to be a relative path.
Unix examples
Path.relative("/usr/local/bin") #=> "usr/local/bin"
Path.relative("usr/local/bin") #=> "usr/local/bin"
Path.relative("../usr/local/bin") #=> "../usr/local/bin"
Windows examples
Path.relative("D:/usr/local/bin") #=> "usr/local/bin"
Path.relative("usr/local/bin") #=> "usr/local/bin"
Path.relative("D:bar.ex") #=> "bar.ex"
Path.relative("/bar/foo.ex") #=> "bar/foo.ex"
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 file system, so it assumes no symlinks in between the paths.
In case a direct relative path cannot be found, it returns the original path.
Examples
iex> Path.relative_to("/usr/local/foo", "/usr/local")
"foo"
iex> Path.relative_to("/usr/local/foo", "/")
"usr/local/foo"
iex> Path.relative_to("/usr/local/foo", "/etc")
"/usr/local/foo"
Convenience to get the path relative to the current working directory. If, for some reason, the current working directory cannot be retrieved, returns the full path.
Returns the path with the extension stripped.
Examples
iex> Path.rootname("/foo/bar")
"/foo/bar"
iex> Path.rootname("/foo/bar.ex")
"/foo/bar"
Returns the path with the extension stripped. This function should be used to
remove a specific extension which might, or might not, be there.
Examples
iex> Path.rootname("/foo/bar.erl", ".erl")
"/foo/bar"
iex> Path.rootname("/foo/bar.erl", ".ex")
"/foo/bar.erl"
Returns a list with the path split by the path separator. If an empty string is given, returns the root path.
Examples
iex> Path.split("")
[]
iex> Path.split("foo")
["foo"]
iex> Path.split("/foo/bar")
["/", "foo", "bar"]
Returns the path type.
Unix examples
Path.type("/usr/local/bin") #=> :absolute
Path.type("usr/local/bin") #=> :relative
Path.type("../usr/local/bin") #=> :relative
Path.type("~/file") #=> :relative
Windows examples
Path.type("D:/usr/local/bin") #=> :absolute
Path.type("usr/local/bin") #=> :relative
Path.type("D:bar.ex") #=> :volumerelative
Path.type("/bar/foo.ex") #=> :volumerelative
Traverses paths according to the given glob expression.
The wildcard looks like an ordinary path, except that certain "wildcard characters" are interpreted in a special way. The following characters are special:
?- Matches one character.*- Matches any number of characters up to the end of the filename, the next dot, or the next slash.**- Two adjacent* 's used as a single pattern will match all files and zero or more directories and subdirectories.[char1,char2,...]- Matches any of the characters listed. Two characters separated by a hyphen will match a range of characters.{item1,item2,...}- Matches one of the alternatives.
Other characters represent themselves. Only paths that have exactly the same character in the same position will match. Note that matching is case-sensitive; i.e. "a" will not match "A".
Examples
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 the ebin directory of each project as follows:
Path.wildcard("projects/*/ebin/**/*.beam")
If you want to search for both .beam and .app files, you could do:
Path.wildcard("projects/*/ebin/**/*.{beam,app}")