Исходный код Путь

Этот модуль предоставляет удобства для манипулирования или извлечения путей к файлам в файловой системе.

Функции в этом модуле могут принимать в качестве аргументов данные символов и всегда возвращают строку, закодированную в UTF-8. Данные символов — это строка или список символов и строк, см. IO.chardata/0. Если задан двоичный объект, независимо от кодировки, его кодировка сохранится.

Большинство функций в этом модуле не взаимодействуют с файловой системой, за исключением нескольких функций, которые требуют этого (например, wildcard/2 и expand/1).

Обзор

Типы

t(): Путь.

Функции

absname(path): Преобразует заданный путь в абсолютный.
absname(path, relative_to): Строит путь от relative_to до path.
basename(path): Возвращает последний компонент пути или сам путь, если он не содержит разделителей каталогов.
basename(path, extension): Возвращает последний компонент path с удаленным extension.
dirname(path): Возвращает компонент каталога path.
expand(path): Преобразует путь в абсолютный, расширяя все . и .. компоненты и ~ в начале.
expand(path, relative_to): Расширяет путь относительно пути, заданного во втором аргументе, расширяя все символы . и ...
extname(path): Возвращает расширение последнего компонента path.
join(list): Объединяет список путей.
join(left, right): Объединяет два пути.
relative(name): Преобразует путь в относительный.
relative_to(path, cwd, opts \\ []): Возвращает прямой относительный путь от path по отношению к cwd.
relative_to_cwd(path, opts \\ []): Удобный способ получить путь, относительный к текущей рабочей директории.
rootname(path): Возвращает path с удаленным extension.
rootname(path, extension): Возвращает path с удаленным extension.
safe_relative(path, cwd \\ File.cwd!()): Возвращает относительный путь, защищённый от атак на обход каталогов.
safe_relative_to(path, cwd) устаревший: Возвращает относительный путь, защищённый от атак на обход каталогов.
split(path): Разделяет путь на список по разделителю путей.
type(name): Возвращает тип пути.
wildcard(glob, opts \\ []): Перебирает пути в соответствии с заданным glob выражением и возвращает список совпадений.

Типы

t()Исходный код

@type t() :: IO.chardata()

Путь.

Функции

absname(path)Source

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

Преобразует заданный путь в абсолютный.

В отличие от expand/1, не производится попытка разрешить .., ., или ~.

Примеры

Операционные системы семейства Unix

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)Source

@spec absname(t(), t() | (-> t())) :: binary()

Создаёт путь от relative_to до path.

Если path уже является абсолютным путём, relative_to игнорируется. Смотрите также relative_to/3. relative_to — это либо путь, либо анонимная функция, которая вызывается только по необходимости и возвращает путь.

В отличие от expand/2, не производится попытка разрешить .., . или ~.

Примеры

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

iex> Path.absname("../x", "bar")
"bar/../x"

iex> Path.absname("foo", fn -> "lazy" end)
"lazy/foo"

basename(path)Source

@spec basename(t()) :: binary()

Возвращает последнюю составляющую пути или сам путь, если он не содержит разделителей каталогов.

Примеры

iex> Path.basename("foo")
"foo"

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

iex> Path.basename("lib/module/submodule.ex")
"submodule.ex"

iex> Path.basename("/")
""

basename(path, extension)Source

@spec basename(t(), t()) :: binary()

Возвращает последнюю составляющую пути path с удалённым extension.

Эта функция должна использоваться для удаления определённого расширения, которое может или не может быть.

Примеры

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)Source

@spec dirname(t()) :: binary()

Возвращает составляющую каталога пути path.

Примеры

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

expand(path)Source

@spec expand(t()) :: binary()

Преобразует путь в абсолютный, расширяя любые . и .. компоненты и ведущий ~.

Если предоставлен относительный путь, он расширяется относительно текущей рабочей директории.

Примеры

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

Path.expand("foo/bar/../baz")
#=> "$PWD/foo/baz"

expand(path, relative_to)Source

@spec expand(t(), t()) :: binary()

Расширяет путь относительно пути, указанного во втором аргументе, расширяя любые . и .. символы.

Если путь уже является абсолютным, relative_to игнорируется.

Обратите внимание, что эта функция обрабатывает path с ведущим ~ как абсолютный.

Второй аргумент сначала преобразуется в абсолютный путь.

Примеры

# 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)Source

@spec extname(t()) :: binary()

Возвращает расширение последней составляющей пути path.

Для имён файлов, начинающихся с точки и не имеющих расширения, возвращает пустую строку.

См. basename/1 и rootname/1 для связанных функций извлечения информации из путей.

Примеры

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

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

iex> Path.extname(".gitignore")
""

join(list)Source

@spec join([t(), ...]) :: binary()

Объединяет список путей.

Эта функция должна использоваться для преобразования списка путей в один путь. Заметьте, что любой заключительный слэш удаляется при объединении.

Возбуждает ошибку, если предоставленный список путей пуст.

Примеры

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

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

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

join(left, right)Source

@spec join(t(), t()) :: binary()

Объединяет два пути.

Правый путь всегда будет преобразован в относительный формат, и любой заключительный слэш будет удалён при объединении.

Примеры

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

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

Функции в этом модуле поддерживают chardata, поэтому предоставление списка будет обрабатывать его как единое целое:

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

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

Используйте join/1, если вам нужно объединить список путей.

relative(name)Source

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

Преобразует путь в относительный.

Если задан абсолютный путь, его корневой компонент удаляется.

Примеры

Операционные системы семейства Unix

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"

relative_to(path, cwd, opts \\ [])Source

@spec relative_to(t(), t(), keyword()) :: binary()

Возвращает относительный путь от path по отношению к cwd.

Другими словами, эта функция пытается вернуть путь, такой что Path.expand(result, cwd) указывает на path Эта функция стремится вернуть относительный путь, но это не гарантируется:

Если оба пути относительные, всегда возвращается относительный путь
Если оба пути абсолютные, может быть возвращён относительный путь, если у них есть общий префикс. Вы можете передать опцию :force для принудительного перемещения вверх по пути, но даже тогда относительный путь не гарантируется (например, если абсолютные пути относятся к разным дискам в Windows)
Если даны смешанные пути, результат всегда соответствует заданному path (первому аргументу)

Эта функция расширяет . и .. записи без обхода файловой системы, поэтому предполагает отсутствие символических ссылок между путями. См. safe_relative_to/2 для более безопасной альтернативы.

Опции

:force - (булево с версии 1.16.0) если true принуждает к возврату относительного пути, перемещаясь вверх по пути. За исключением случаев, когда пути находятся на разных томах в Windows. По умолчанию false.

Примеры

С относительной рабочей директорией

Если оба пути относительные, вычисляется минимальный путь:

Path.relative_to("tmp/foo/bar", "tmp")      #=> "foo/bar"
Path.relative_to("tmp/foo/bar", "tmp/foo")  #=> "bar"
Path.relative_to("tmp/foo/bar", "tmp/bat")  #=> "../foo/bar"

Если абсолютный путь задан с относительной рабочей директорией, он возвращается как:

Path.relative_to("/usr/foo/bar", "tmp/bat")  #=> "/usr/foo/bar"

С абсолютной рабочей директорией

Если оба пути абсолютные, вычисляется относительный путь, если возможно, без перемещения вверх:

Path.relative_to("/usr/local/foo", "/usr/local")      #=> "foo"
Path.relative_to("/usr/local/foo", "/")               #=> "usr/local/foo"
Path.relative_to("/usr/local/foo", "/etc")            #=> "/usr/local/foo"
Path.relative_to("/usr/local/foo", "/usr/local/foo")  #=> "."
Path.relative_to("/usr/local/../foo", "/usr/foo")     #=> "."
Path.relative_to("/usr/local/../foo/bar", "/usr/foo") #=> "bar"

Если :force установлено в true пути перемещаются вверх:

Path.relative_to("/usr", "/usr/local", force: true)          #=> ".."
Path.relative_to("/usr/foo", "/usr/local", force: true)      #=> "../foo"
Path.relative_to("/usr/../foo/bar", "/etc/foo", force: true) #=> "../../foo/bar"

Если задан относительный путь, предполагается, что он относится к заданному пути, поэтому путь возвращается с "." и ".." расширенными:

Path.relative_to(".", "/usr/local")          #=> "."
Path.relative_to("foo", "/usr/local")        #=> "foo"
Path.relative_to("foo/../bar", "/usr/local") #=> "bar"
Path.relative_to("foo/..", "/usr/local")     #=> "."
Path.relative_to("../foo", "/usr/local")     #=> "../foo"

relative_to_cwd(path, opts \\ [])Source

@spec relative_to_cwd(
  t(),
  keyword()
) :: binary()

Удобная функция для получения пути, относительного к текущей рабочей директории.

Если по какой-либо причине текущая рабочая директория не может быть получена, эта функция возвращает заданный path.

Проверьте relative_to/3 для поддерживаемых опций.

rootname(path)Source

@spec rootname(t()) :: binary()

Возвращает path с удалённым extension.

Примеры

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

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

rootname(path, extension)Source

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

Возвращает path с удалённым extension.

Эта функция должна использоваться для удаления конкретного расширения, которое может быть или отсутствовать.

Примеры

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

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

safe_relative(path, cwd \\ File.cwd!())Source

@spec safe_relative(t(), t()) :: {:ok, binary()} | :error

Возвращает относительный путь, защищённый от атак перехода каталогов.

Указанный относительный путь очищается путём удаления .. и . компонентов.

Эта функция проверяет, что после расширения этих компонентов путь всё ещё «безопасен». Пути считаются небезопасными, если выполняется хотя бы одно из этих условий:

Путь не относительный, например, "/foo/bar".
Компонент .. мог бы привести к тому, что путь перейдёт выше корня relative_to.
Символическая ссылка в пути указывает на элемент выше корня cwd.

Примеры

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

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

iex> Path.safe_relative("deps/my_dep/./build/../app.beam", File.cwd!())
{:ok, "deps/my_dep/app.beam"}

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

iex> Path.safe_relative("/usr/local", File.cwd!())
:error

safe_relative_to(path, cwd)Source

Эта функция устарела. Используйте safe_relative/2 вместо неё.

@spec safe_relative_to(t(), t()) :: {:ok, binary()} | :error

Возвращает относительный путь, защищённый от атак перехода каталогов.

См. safe_relative/2 для не устаревшей версии этого API.

split(path)Source

@spec split(t()) :: [binary()]

Разделяет путь на список по разделителю пути.

Если задана пустая строка, возвращает пустой список.

В Windows путь разделяется как по "\", так и по "/" разделителям, а буква диска, если она есть, всегда возвращается в нижнем регистре.

Примеры

iex> Path.split("")
[]

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

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

type(name)Source

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

Возвращает тип пути.

Примеры

Операционные системы семейства Unix

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

wildcard(glob, opts \\ [])Source

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

Проходит по путям в соответствии с заданным выражением glob и возвращает список совпадений.

Маска похожа на обычный путь, за исключением того, что следующие «символы подстановки» интерпретируются особым образом:

? - соответствует одному символу.
* - соответствует любому количеству символов до конца имени файла, следующей точки или следующего слэша.
** - два соседних * в качестве одного шаблона соответствуют всем файлам и нулю или более каталогам и подкаталогам.
[char1,char2,...] - соответствует любому из перечисленных символов; два символа, разделенные дефисом, соответствуют диапазону символов. Не добавляйте пробелы перед и после запятой, иначе это будет соответствовать путям, содержащим сам пробел.
{item1,item2,...} - соответствует одному из альтернатив. Не добавляйте пробелы перед и после запятой, иначе это будет соответствовать путям, содержащим сам пробел.

Другие символы представляют сами себя. Совпадению соответствуют только пути, имеющие точно такой же символ в том же положении. Обратите внимание, что сопоставление регистрозависимое: "a" не будет соответствовать "A".

Разделители каталогов всегда должны записываться как /, даже в Windows. Вы можете вызвать Path.expand/1 для нормализации пути перед вызовом этой функции.

Символ, предваряемый \\, теряет своё специальное значение. Обратите внимание, что \\ должен быть записан как \\\\ в строковой литерале. Например, "\\\\?*" будет соответствовать любому имени файла, начинающемуся с ?..

По умолчанию шаблоны * и ? не соответствуют файлам, начинающимся с точки .. См. опцию :match_dot в разделе «Опции» ниже.

Опции

:match_dot - (логическое значение) если false, специальные символы подстановки * и ? не будут соответствовать файлам, начинающимся с точки (.). Если true, файлы, начинающиеся с . не будут обрабатываться особым образом. По умолчанию false.

Примеры

Представьте, что у вас есть каталог с именем projects с тремя проектами Elixir внутри: elixir, ex_doc, и plug. Вы можете найти все .beam файлы внутри каталога ebin каждого проекта следующим образом:

Path.wildcard("projects/*/ebin/**/*.beam")

Если вы хотите искать как .beam, так и .app файлы, вы можете сделать это следующим образом:

Path.wildcard("projects/*/ebin/**/*.{beam,app}")