# Elixir v1.10.3 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

## Types

t()

## 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`.

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.

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.

extname(path)

Returns the extension of the last component of `path`.

join(list)

Joins a list of paths.

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.

relative_to_cwd(path)

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

rootname(path)

Returns the `path` with the `extension` stripped.

rootname(path, extension)

Returns the `path` with the `extension` stripped.

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.

# Link to this section Types

Link to this type

# t()

View Source

## Specs

    t() :: IO.chardata()

# Link to this section Functions

Link to this function

# absname(path)

View Source

## Specs

    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

## Specs

    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"

Link to this function

# basename(path)

View Source

## Specs

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

Link to this function

# basename(path, extension)

View Source

## Specs

    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"

Link to this function

# dirname(path)

View Source

## Specs

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

Link to this function

# expand(path)

View Source

## Specs

    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"

Link to this function

# expand(path, relative_to)

View Source

## Specs

    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"

Link to this function

# extname(path)

View Source

## Specs

    extname(t()) :: binary()

Returns the extension of the last component of `path`.

## Examples

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

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

Link to this function

# join(list)

View Source

## Specs

    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.

## Examples

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

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

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

Link to this function

# join(left, right)

View Source

## Specs

    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"

Link to this function

# relative(name)

View Source

## Specs

    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"

Link to this function

# relative_to(path, from)

View Source

## Specs

    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"

Link to this function

# relative_to_cwd(path)

View Source

## Specs

    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`.

Link to this function

# rootname(path)

View Source

## Specs

    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

## Specs

    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

# split(path)

View Source

## Specs

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

Link to this function

# type(name)

View Source

## Specs

    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

## Specs

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