Elixir v1.2.6 Path

This module provides conveniences for manipulating or retrieving file system paths.

The functions in this module may receive a char data 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/1 and expand/1.

Summary

Functions

absname(path)

Converts the given path to an absolute one. Unlike expand/1, no attempt is made to resolve .., . or ~

absname(path, relative_to)

Builds a path from relative_to to path. If path is already an absolute path, relative_to is ignored. See also relative_to/2

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 path with the extension stripped. This function should be used to remove a specific extension which may, or may not, be there

dirname(path)

Returns the directory component of path

expand(path)

Converts the path to an absolute one and expands any . and .. characters and a leading ~

expand(path, relative_to)

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

extname(path)

Returns the extension of the last component of path

join(list)

Joins a list of strings

join(left, right)

Joins two paths

relative(name)

Forces the path to be a relative path

relative_to(path, from)

Returns the given path relative to the given from path. In other words, it tries to strip the from prefix from path

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 path with the extension stripped

rootname(path, extension)

Returns the path with the extension stripped. This function should be used to remove a specific extension which might, or might not, be there

split(path)

Splits the path into a list at the path separator

type(name)

Returns the path type

wildcard(glob, opts \\ [])

Traverses paths according to the given glob expression, and returns a list of matches

Types

t()

t() :: :unicode.chardata

Functions

absname(path)

absname(t) :: binary

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"

absname(path, relative_to)

absname(t, t) :: binary

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"

basename(path)

basename(t) :: binary

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("/")
""

basename(path, extension)

basename(t, t) :: binary

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"

dirname(path)

dirname(t) :: binary

Returns the directory component of path.

Examples

Path.dirname("/foo/bar.ex")
#=> "/foo"
Path.dirname("/foo/bar/baz.ex")
#=> "/foo/bar"

expand(path)

expand(t) :: binary

Converts the path to an absolute one and expands any . and .. characters and a leading ~.

Examples

Path.expand("/foo/bar/../bar")
"/foo/bar"

expand(path, relative_to)

expand(t, t) :: binary

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"

extname(path)

extname(t) :: binary

Returns the extension of the last component of path.

Examples

iex> Path.extname("foo.erl")
".erl"

iex> Path.extname("~/foo/bar")
""

join(list)

join([t]) :: binary

Joins a list of strings.

This function should be used to convert a list of strings to a path. Note that any trailing slash is removed on join.

Examples

iex> Path.join(["~", "foo"])
"~/foo"

iex> Path.join(["foo"])
"foo"

iex> Path.join(["/", "foo", "bar/"])
"/foo/bar"

join(left, right)

join(t, t) :: binary

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"

relative(name)

relative(t) :: binary

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"

relative_to(path, from)

relative_to(t, t) :: binary

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"

relative_to_cwd(path)

relative_to_cwd(t) :: binary

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)

rootname(t) :: binary

Returns the path with the extension stripped.

Examples

iex> Path.rootname("/foo/bar")
"/foo/bar"

iex> Path.rootname("/foo/bar.ex")
"/foo/bar"

rootname(path, extension)

rootname(t, t) :: binary

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"

split(path)

split(t) :: [binary]

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"]

type(name)

type(t) :: :absolute | :relative | :volumerelative

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

wildcard(glob, opts \\ [])

wildcard(t, Keyword.t) :: [binary]

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
{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”.

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}")