Elixir v1.4.5 Path View Source
This module provides conveniences for manipulating or retrieving file system paths.
The functions in this module may receive a chardata as argument (i.e. a string or a list of characters / string) and will always return a string (encoded in UTF-8).
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/2
and expand/1
).
Link to this section Summary
Functions
Converts the given path to an absolute one. Unlike
expand/1
, no attempt is made to resolve ..
, .
or ~
Builds a path from relative_to
to path
. If path
is already
an absolute path, relative_to
is ignored. See also relative_to/2
Returns the last component of the path or the path itself if it does not contain any directory separators
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
Returns the directory component of path
Converts the path to an absolute one and expands
any .
and ..
characters and a leading ~
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
Returns the extension of the last component of path
Joins a list of paths
Joins two paths
Forces the path to be a relative path
Returns the given path
relative to the given from
path.
In other words, it tries to strip the from
prefix from 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
Returns the path
with the extension
stripped
Returns the path
with the extension
stripped. This function should be used to
remove a specific extension which might, or might not, be there
Splits the path into a list at the path separator
Returns the path type
Traverses paths according to the given glob
expression, and returns a
list of matches
Link to this section Types
Link to this section 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
iex> Path.dirname("/foo/bar.ex")
"/foo"
iex> 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")
""
Joins a list of paths.
This function should be used to convert a list of paths to a path. Note that any trailing slash is removed when joining.
Examples
iex> Path.join(["~", "foo"])
"~/foo"
iex> Path.join(["foo"])
"foo"
iex> Path.join(["/", "foo", "bar/"])
"/foo/bar"
Joins two paths.
The right path will always be expanded to its relative format and any trailing slash is removed on join.
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 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"
Splits the path into a list at the path separator.
If an empty string is given, returns an empty list.
On Windows, path is split on both “\” and “/“ separators and the driver letter, if there is one, is always returned in lowercase.
Examples
iex> Path.split("")
[]
iex> Path.split("foo")
["foo"]
iex> Path.split("/foo/bar")
["/", "foo", "bar"]
Returns the path type.
Unix examples
Path.type("/") #=> :absolute
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, and returns a
list of matches.
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. Do not add spaces before and after the comma as it would then match paths containing the space character itself.{item1,item2,...}
- matches one of the alternatives Do not add spaces before and after the comma as it would then match paths containing the space character itself.
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”.
By default, the patterns *
and ?
do not match files starting
with a dot .
unless match_dot: true
is given in opts
.
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}")