View Source Path (Elixir v1.14.0-rc.0)

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

The functions in this module may receive chardata as arguments and will always return a string encoded in UTF-8. Chardata is a string or a list of characters and strings, see IO.chardata/0. If a binary is given, in whatever encoding, its encoding will be kept.

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

Types

t()

A path.

Functions

Converts the given path to an absolute one.

Builds a path from relative_to to path.

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.

Returns the directory component of path.

Converts the path to an absolute one, expanding any . and .. components and a leading ~.

Expands the path relative to the path given as the second argument expanding any . and .. characters.

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.

Convenience to get the path relative to the current working directory.

Returns the path with the extension stripped.

Returns the path with the extension stripped.

Returns a path relative to the current working directory that is protected from directory-traversal attacks.

Returns a relative path that is protected from directory-traversal attacks.

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

@spec absname(t()) :: binary()

Converts the given path to an absolute one.

Unlike expand/1, no attempt is made to resolve .., ., or ~.

Examples

Unix-like operating systems

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"
Link to this function

absname(path, relative_to)

View Source
@spec 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"
@spec 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("lib/module/submodule.ex")
"submodule.ex"

iex> Path.basename("/")
""
Link to this function

basename(path, extension)

View Source
@spec 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"
@spec dirname(t()) :: binary()

Returns the directory component of path.

Examples

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

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

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

iex> Path.dirname("bar.ex")
"."
@spec expand(t()) :: binary()

Converts the path to an absolute one, expanding any . and .. components and a leading ~.

Examples

Path.expand("/foo/bar/../baz")
#=> "/foo/baz"
Link to this function

expand(path, relative_to)

View Source
@spec 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 a 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"
@spec extname(t()) :: binary()

Returns the extension of the last component of path.

The behaviour of this function changed in Erlang/OTP 24 for filenames starting with a dot and without an extension. For example, for a file named .gitignore, extname/1 now returns an empty string, while it would return ".gitignore" in previous Erlang/OTP versions. This was done to match the behaviour of rootname/1, which would return ".gitignore" as its name (and therefore it cannot also be an extension).

See basename/1 and rootname/1 for related functions to extract information from paths.

Examples

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

iex> Path.extname("~/foo/bar")
""
@spec join([t(), ...]) :: binary()

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.

Raises an error if the given list of paths is empty.

Examples

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

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

iex> Path.join(["/", "foo", "bar/"])
"/foo/bar"
@spec join(t(), t()) :: binary()

Joins two paths.

The right path will always be expanded to its relative format and any trailing slash will be removed when joining.

Examples

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

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

The functions in this module support chardata, so giving a list will treat it as a single entity:

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

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

Use join/1 if you need to join a list of paths instead.

@spec relative(t()) :: binary()

Forces the path to be a relative path.

Examples

Unix-like operating systems

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

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"
@spec relative_to(t(), t()) :: binary()

Returns the given path relative to the given from path.

In other words, this function 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"

iex> Path.relative_to("/usr/local/foo", "/usr/local/foo")
"."
@spec 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, this function returns the given path.

@spec 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"
Link to this function

rootname(path, extension)

View Source
@spec rootname(t(), t()) :: binary()

Returns the 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.rootname("/foo/bar.erl", ".erl")
"/foo/bar"

iex> Path.rootname("/foo/bar.erl", ".ex")
"/foo/bar.erl"
Link to this function

safe_relative(path)

View Source (since 1.14.0)
@spec safe_relative(t()) :: {:ok, binary()} | :error

Returns a path relative to the current working directory that is protected from directory-traversal attacks.

Same as safe_relative_to/2 with the current working directory as the second argument. If there is an issue retrieving the current working directory, this function raises an error.

Examples

iex> Path.safe_relative("foo")
{:ok, "foo"}

iex> Path.safe_relative("foo/../bar")
{:ok, "bar"}

iex> Path.safe_relative("foo/../..")
:error

iex> Path.safe_relative("/usr/local")
:error
Link to this function

safe_relative_to(path, relative_to)

View Source (since 1.14.0)
@spec safe_relative_to(t(), t()) :: {:ok, binary()} | :error

Returns a relative path that is protected from directory-traversal attacks.

The given relative path is sanitized by eliminating .. and . components.

This function checks that, after expanding those components, the path is still "safe". Paths are considered unsafe if either of these is true:

  • The path is not relative, such as "/foo/bar".

  • A .. component would make it so that the path would travers up above the root of relative_to.

  • A symbolic link in the path points to something above the root of relative_to.

Examples

iex> Path.safe_relative_to("deps/my_dep/app.beam", "deps")
{:ok, "deps/my_dep/app.beam"}

iex> Path.safe_relative_to("deps/my_dep/./build/../app.beam", "deps")
{:ok, "deps/my_dep/app.beam"}

iex> Path.safe_relative_to("my_dep/../..", "deps")
:error

iex> Path.safe_relative_to("/usr/local", ".")
:error
@spec 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"]
@spec type(t()) :: :absolute | :relative | :volumerelative

Returns the path type.

Examples

Unix-like operating systems

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

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
Link to this function

wildcard(glob, opts \\ [])

View Source
@spec wildcard(
  t(),
  keyword()
) :: [binary()]

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

The wildcard looks like an ordinary path, except that the following "wildcard characters" are interpreted in a special way:

  • ? - 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: "a" will not match "A".

Directory separators must always be written as /, even on Windows. You may call Path.expand/1 to normalize the path before invoking this function.

By default, the patterns * and ? do not match files starting with a dot .. See the :match_dot option in the "Options" section below.

Options

  • :match_dot - (boolean) if false, the special wildcard characters * and ? will not match files starting with a dot (.). If true, files starting with a . will not be treated specially. Defaults to false.

Examples

Imagine you have a directory called projects with three Elixir projects inside of it: elixir, ex_doc, and plug. 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}")