Пакет filepath
Обзор
Пакет filepath реализует служебные функции для работы с путями к файлам, совместимыми с путями файлов, определёнными целевой операционной системой.
Пакет filepath использует либо слэши, либо обратные слэши в зависимости от операционной системы. Для обработки путей, таких как URL-адреса, которые всегда используют слэши независимо от операционной системы, см. пакет path.
Индекс
Файлы пакета
match.go path.go path_unix.go symlink.go symlink_unix.go
Константы
const (
Separator = os.PathSeparator
ListSeparator = os.PathListSeparator
) Переменные
ErrBadPattern указывает, что шаблон был неверно сформирован.
var ErrBadPattern = errors.New("syntax error in pattern") SkipAll используется в качестве возвращаемого значения из WalkFunc для указания на то, что все оставшиеся файлы и каталоги должны быть пропущены. Оно не возвращается как ошибка никакой функцией.
var SkipAll error = fs.SkipAll
SkipDir используется в качестве возвращаемого значения из WalkFunc для указания на то, что каталог, указанный в вызове, должен быть пропущен. Оно не возвращается как ошибка никакой функцией.
var SkipDir error = fs.SkipDir
функция Abs
func Abs(path string) (string, error)
Abs возвращает абсолютное представление пути. Если путь не абсолютный, он будет объединён с текущим рабочим каталогом, чтобы преобразовать его в абсолютный путь. Абсолютное имя пути для данного файла не гарантируется как уникальное. Abs вызывает Clean на результате.
функция Base
func Base(path string) string
Base возвращает последний элемент пути. Конечные разделители путей удаляются перед извлечением последнего элемента. Если путь пуст, Base возвращает «.» Если путь состоит только из разделителей, Base возвращает один разделитель.
Пример
Код:
fmt.Println("On Unix:")
fmt.Println(filepath.Base("/foo/bar/baz.js"))
fmt.Println(filepath.Base("/foo/bar/baz"))
fmt.Println(filepath.Base("/foo/bar/baz/"))
fmt.Println(filepath.Base("dev.txt"))
fmt.Println(filepath.Base("../todo.txt"))
fmt.Println(filepath.Base(".."))
fmt.Println(filepath.Base("."))
fmt.Println(filepath.Base("/"))
fmt.Println(filepath.Base(""))
Вывод:
On Unix: baz.js baz baz dev.txt todo.txt .. . / .
функция Clean
func Clean(path string) string
Clean возвращает самое короткое имя пути, эквивалентное пути, путём чисто лексической обработки. Она применяет следующие правила итеративно, пока дальнейшая обработка невозможна:
- Замените несколько элементов Separator на один.
- Удалите каждый элемент имени пути «.» (текущий каталог).
- Удалите каждый вложенный элемент имени пути «..» (родительский каталог) вместе с предшествующим ему элементом, не являющимся «..».
- Удалите элементы «..», которые начинаются с корневого пути: то есть, замените «/..» на «/» в начале пути, предполагая, что Separator — это «/».
Возвращаемый путь заканчивается слэшем только в том случае, если он представляет собой корневой каталог, например, «/» в Unix или `C:\` в Windows.
Наконец, все вхождения слэша заменяются на разделитель.
Если результатом этого процесса является пустая строка, Clean возвращает строку «.».
В Windows Clean не изменяет имя тома, кроме замены вхождений «/» на «\». Например, Clean("//host/share/../x") возвращает `\\host\share\x`.
См. также Роб Пайк, «Лексические имена файлов в Plan 9 или правильное обращение с точкой-точкой», https://9p.io/sys/doc/lexnames.html
функция Dir
func Dir(path string) string
Dir возвращает всё, кроме последнего элемента пути, обычно каталога пути. После удаления последнего элемента Dir вызывает Clean на пути, и trailing слэши удаляются. Если путь пуст, Dir возвращает «.» Если путь состоит только из разделителей, Dir возвращает один разделитель. Возвращаемый путь не заканчивается разделителем, если это не корневой каталог.
Пример
Код:
fmt.Println("On Unix:")
fmt.Println(filepath.Dir("/foo/bar/baz.js"))
fmt.Println(filepath.Dir("/foo/bar/baz"))
fmt.Println(filepath.Dir("/foo/bar/baz/"))
fmt.Println(filepath.Dir("/dirty//path///"))
fmt.Println(filepath.Dir("dev.txt"))
fmt.Println(filepath.Dir("../todo.txt"))
fmt.Println(filepath.Dir(".."))
fmt.Println(filepath.Dir("."))
fmt.Println(filepath.Dir("/"))
fmt.Println(filepath.Dir(""))
Вывод:
On Unix: /foo/bar /foo/bar /foo/bar/baz /dirty/path . .. . . / .
функция EvalSymlinks
func EvalSymlinks(path string) (string, error)
EvalSymlinks возвращает имя пути после оценки любых символических ссылок. Если путь относительный, результат будет относительным к текущему каталогу, за исключением случая, когда один из компонентов является абсолютной символической ссылкой. EvalSymlinks вызывает Clean на результате.
функция Ext
func Ext(path string) string
Ext возвращает расширение имени файла, используемое путём. Расширение — это суффикс, начинающийся с последней точки в последнем элементе пути; оно пусто, если нет точки.
Пример
Код:
fmt.Printf("No dots: %q\n", filepath.Ext("index"))
fmt.Printf("One dot: %q\n", filepath.Ext("index.js"))
fmt.Printf("Two dots: %q\n", filepath.Ext("main.test.js"))
Вывод:
No dots: "" One dot: ".js" Two dots: ".js"
функция FromSlash
func FromSlash(path string) string
FromSlash возвращает результат замены каждого символа слэша ('/') в пути символом разделителя. Несколько слэшей заменяются несколькими разделителями.
См. также функцию Localize, которая преобразует путь, разделённый слэшами, используемый пакетом io/fs, в путь операционной системы.
функция Glob
func Glob(pattern string) (matches []string, err error)
Glob возвращает имена всех файлов, соответствующих шаблону, или nil, если нет соответствующего файла. Синтаксис шаблонов такой же, как в Match. Шаблон может описывать иерархические имена, такие как /usr/*/bin/ed (предполагая, что Separator — это '/').
Glob игнорирует ошибки системы файлов, такие как ошибки ввода-вывода при чтении каталогов. Единственной возможной возвращаемой ошибкой является ErrBadPattern, когда шаблон имеет неправильный формат.
функция HasPrefix
func HasPrefix(p, prefix string) bool
HasPrefix существует для обратной совместимости и не должна использоваться.
Устарело: HasPrefix не соблюдает границы пути и не игнорирует регистр, когда это требуется.
функция IsAbs
func IsAbs(path string) bool
IsAbs сообщает, является ли путь абсолютным.
Пример
Код:
fmt.Println("On Unix:")
fmt.Println(filepath.IsAbs("/home/gopher"))
fmt.Println(filepath.IsAbs(".bashrc"))
fmt.Println(filepath.IsAbs(".."))
fmt.Println(filepath.IsAbs("."))
fmt.Println(filepath.IsAbs("/"))
fmt.Println(filepath.IsAbs(""))
Вывод:
On Unix: true false false false true false
функция IsLocal 1.20
func IsLocal(path string) bool
IsLocal сообщает, является ли путь, используя только лексический анализ, обладающим всеми этими свойствами:
- находится в поддереве, корнем которого является каталог, в котором оценивается путь
- не является абсолютным путём
- не пуст
- в Windows, не является зарезервированным именем, таким как «NUL»
Если IsLocal(path) возвращает true, то Join(base, path) всегда будет возвращать путь, содержащийся в base, а Clean(path) всегда будет возвращать некорневой путь без элементов «..» пути.
IsLocal — это чисто лексическая операция. В частности, она не учитывает влияние каких-либо символических ссылок, которые могут существовать в файловой системе.
функция Join
func Join(elem ...string) string
Join объединяет любое количество элементов пути в один путь, разделяя их разделителем OS Separator. Пустые элементы игнорируются. Результат очищается. Однако, если список аргументов пуст или все его элементы пустые, Join возвращает пустую строку. В Windows результат будет только UNC-путь, если первый непустой элемент — UNC-путь.
Пример
Код:
fmt.Println("On Unix:")
fmt.Println(filepath.Join("a", "b", "c"))
fmt.Println(filepath.Join("a", "b/c"))
fmt.Println(filepath.Join("a/b", "c"))
fmt.Println(filepath.Join("a/b", "/c"))
fmt.Println(filepath.Join("a/b", "../../../xyz"))
Вывод:
On Unix: a/b/c a/b/c a/b/c a/b/c ../xyz
функция Localize 1.23
func Localize(path string) (string, error)
Localize преобразует путь, разделённый слэшами, в путь операционной системы. Входной путь должен быть допустимым путём, как указано в io/fs.ValidPath.
Localize возвращает ошибку, если путь не может быть представлен операционной системой. Например, путь a\b отклоняется в Windows, где \ — символ разделителя и не может быть частью имени файла.
Путь, возвращаемый Localize, всегда будет локальным, как указано в IsLocal.
функция Match
func Match(pattern, name string) (matched bool, err error)
Match сообщает, соответствует ли имя шаблону имени файла оболочки. Синтаксис шаблона:
pattern:
{ term }
term:
'*' matches any sequence of non-Separator characters
'?' matches any single non-Separator character
'[' [ '^' ] { character-range } ']'
character class (must be non-empty)
c matches character c (c != '*', '?', '\\', '[')
'\\' c matches character c
character-range:
c matches character c (c != '\\', '-', ']')
'\\' c matches character c
lo '-' hi matches character c for lo <= c <= hi
Match требует, чтобы шаблон соответствовал всему имени, а не только подстроке. Единственной возможной возвращаемой ошибкой является ErrBadPattern, когда шаблон имеет неправильный формат.
В Windows экранирование отключено. Вместо этого, '\\' рассматривается как разделитель пути.
Пример
Код:
fmt.Println("On Unix:")
fmt.Println(filepath.Match("/home/catch/*", "/home/catch/foo"))
fmt.Println(filepath.Match("/home/catch/*", "/home/catch/foo/bar"))
fmt.Println(filepath.Match("/home/?opher", "/home/gopher"))
fmt.Println(filepath.Match("/home/\\*", "/home/*"))
Вывод:
On Unix: true <nil> false <nil> true <nil> true <nil>
функция Rel
func Rel(basepath, targpath string) (string, error)
Rel возвращает относительный путь, который лексически эквивалентен targpath при объединении с basepath с промежуточным разделителем. То есть, Join(basepath, Rel(basepath, targpath)) эквивалентно самому targpath. При успехе возвращаемый путь всегда будет относительным к basepath, даже если basepath и targpath не имеют общих элементов. Возвращается ошибка, если targpath не может быть сделан относительным к basepath, или если для его вычисления необходимо знать текущий рабочий каталог. Rel вызывает Clean на результате.
Пример
Код:
paths := []string{
"/a/b/c",
"/b/c",
"./b/c",
}
base := "/a"
fmt.Println("On Unix:")
for _, p := range paths {
rel, err := filepath.Rel(base, p)
fmt.Printf("%q: %q %v\n", p, rel, err)
}
Вывод:
On Unix: "/a/b/c": "b/c" <nil> "/b/c": "../b/c" <nil> "./b/c": "" Rel: can't make ./b/c relative to /a
функция Split
func Split(path string) (dir, file string)
Split разделяет путь, начиная с символа, следующего за последним разделителем, на две части: директорию и имя файла. Если в пути нет разделителя, Split возвращает пустую директорию и имя файла, равное path. Возвращаемые значения обладают свойством path = dir+file.
Пример
Код:
paths := []string{
"/home/arnie/amelia.jpg",
"/mnt/photos/",
"rabbit.jpg",
"/usr/local//go",
}
fmt.Println("On Unix:")
for _, p := range paths {
dir, file := filepath.Split(p)
fmt.Printf("input: %q\n\tdir: %q\n\tfile: %q\n", p, dir, file)
}
Вывод:
On Unix: input: "/home/arnie/amelia.jpg" dir: "/home/arnie/" file: "amelia.jpg" input: "/mnt/photos/" dir: "/mnt/photos/" file: "" input: "rabbit.jpg" dir: "" file: "rabbit.jpg" input: "/usr/local//go" dir: "/usr/local//" file: "go"
func SplitList
func SplitList(path string) []string
SplitList разделяет список путей, соединённых с помощью специфичного для ОС разделителя списка, обычно встречающегося в переменных окружения PATH или GOPATH. В отличие от strings.Split, SplitList возвращает пустой срез при передаче пустой строки.
Пример
Код:
fmt.Println("On Unix:", filepath.SplitList("/a/b/c:/usr/bin"))
Вывод:
On Unix: [/a/b/c /usr/bin]
func ToSlash
func ToSlash(path string) string
ToSlash возвращает результат замены каждого символа разделителя в пути символом слэша ('/'). Несколько разделителей заменяются несколькими слэшами.
func VolumeName
func VolumeName(path string) string
VolumeName возвращает имя тома в начале. Для "C:\foo\bar" на Windows возвращает "C:". Для "\\host\share\foo" возвращает "\\host\share". В других операционных системах возвращает "".
func Walk
func Walk(root string, fn WalkFunc) error
Walk обходит файловую структуру, начиная с корня root, вызывая функцию fn для каждого файла или директории в дереве, включая корень.
Все ошибки, возникающие при посещении файлов и директорий, отфильтровываются функцией fn: см. документацию по WalkFunc для подробностей.
Файлы обходятся в лексикографическом порядке, что делает вывод детерминированным, но требует, чтобы Walk прочитал весь каталог в память перед продолжением обхода этого каталога.
Walk не следует символическим ссылкам.
Walk менее эффективен, чем WalkDir, представленный в Go 1.16, который избегает вызова os.Lstat для каждого посещённого файла или директории.
Пример
Код:
package filepath_test
import (
"fmt"
"io/fs"
"os"
"path/filepath"
)
func prepareTestDirTree(tree string) (string, error) {
tmpDir, err := os.MkdirTemp("", "")
if err != nil {
return "", fmt.Errorf("error creating temp directory: %v\n", err)
}
err = os.MkdirAll(filepath.Join(tmpDir, tree), 0755)
if err != nil {
os.RemoveAll(tmpDir)
return "", err
}
return tmpDir, nil
}
func ExampleWalk() {
tmpDir, err := prepareTestDirTree("dir/to/walk/skip")
if err != nil {
fmt.Printf("unable to create test dir tree: %v\n", err)
return
}
defer os.RemoveAll(tmpDir)
os.Chdir(tmpDir)
subDirToSkip := "skip"
fmt.Println("On Unix:")
err = filepath.Walk(".", func(path string, info fs.FileInfo, err error) error {
if err != nil {
fmt.Printf("prevent panic by handling failure accessing a path %q: %v\n", path, err)
return err
}
if info.IsDir() && info.Name() == subDirToSkip {
fmt.Printf("skipping a dir without errors: %+v \n", info.Name())
return filepath.SkipDir
}
fmt.Printf("visited file or dir: %q\n", path)
return nil
})
if err != nil {
fmt.Printf("error walking the path %q: %v\n", tmpDir, err)
return
}
// Output:
// On Unix:
// visited file or dir: "."
// visited file or dir: "dir"
// visited file or dir: "dir/to"
// visited file or dir: "dir/to/walk"
// skipping a dir without errors: skip
}
func WalkDir 1.16
func WalkDir(root string, fn fs.WalkDirFunc) error
WalkDir обходит файловую структуру, начиная с корня root, вызывая функцию fn для каждого файла или директории в дереве, включая корень.
Все ошибки, возникающие при посещении файлов и директорий, отфильтровываются функцией fn: см. документацию по fs.WalkDirFunc для подробностей.
Файлы обходятся в лексикографическом порядке, что делает вывод детерминированным, но требует, чтобы WalkDir прочитал весь каталог в память перед продолжением обхода этого каталога.
WalkDir не следует символическим ссылкам.
WalkDir вызывает fn с путями, использующими символ разделителя, соответствующий операционной системе. Это отличается от io/fs.WalkDir, который всегда использует слэши для разделения путей.
тип WalkFunc
WalkFunc — тип функции, вызываемой Walk для посещения каждого файла или директории.
Аргумент path содержит аргумент Walk в качестве префикса. То есть, если Walk вызывается с аргументом root «dir» и находит файл с именем «a» в этом каталоге, функция walk будет вызвана с аргументом «dir/a».
Директория и файл объединяются с помощью Join, который может очистить имя директории: если Walk вызывается с аргументом root «x/../dir» и находит файл с именем «a» в этом каталоге, функция walk будет вызвана с аргументом «dir/a», а не «x/../dir/a».
Аргумент info — fs.FileInfo для указанного пути.
Возвращаемое значение ошибки функцией управляет дальнейшим выполнением Walk. Если функция возвращает специальное значение SkipDir, Walk пропускает текущую директорию (path, если info.IsDir() истинно, иначе родительскую директорию path). Если функция возвращает специальное значение SkipAll, Walk пропускает все оставшиеся файлы и директории. В противном случае, если функция возвращает ненулевую ошибку, Walk останавливается и возвращает эту ошибку.
Аргумент err сообщает об ошибке, связанной с путем, сигнализируя, что Walk не войдёт в эту директорию. Функция может решить, как обработать эту ошибку; как описано ранее, возвращение ошибки приведёт к остановке Walk от обхода всего дерева.
Walk вызывает функцию с ненулевым аргументом err в двух случаях.
Во-первых, если os.Lstat в корневом каталоге или любой директории или файле в дереве завершается неудачей, Walk вызывает функцию с path, установленным в путь этой директории или файла, info установленным в значение nil и err установленным в ошибку из os.Lstat.
Во-вторых, если метод Readdirnames директории завершается неудачей, Walk вызывает функцию с path, установленным в путь директории, info, установленным в fs.FileInfo, описывающем директорию, и err, установленным в ошибку из Readdirnames.
type WalkFunc func(path string, info fs.FileInfo, err error) error
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/path/filepath/
