package filepath

import "path/filepath"

Package filepath 实现了以与目标操作系统定义的文件路径 相兼容的方式操作文件名路径的实用例程。

filepath 包使用正斜杠或反斜杠, 具体取决于操作系统。要处理诸如 URL 这类 无论操作系统如何都始终使用正斜杠的路径, 请参见 path 包。

Index

Examples

Constants

const (
	Separator     = os.PathSeparator
	ListSeparator = os.PathListSeparator
)

Variables

var ErrBadPattern = errors.New("syntax error in pattern")

ErrBadPattern 表示模式格式错误。

var SkipAll error = fs.SkipAll

SkipAll 用作 WalkFunc 的返回值,以指示 所有剩余的文件和目录都应被跳过。它不会 被任何函数作为错误返回。

var SkipDir error = fs.SkipDir

SkipDir 用作 WalkFunc 的返回值,以指示 调用中指定的目录应被跳过。它不会 被任何函数作为错误返回。

Functions

func Abs

func Abs(path string) (string, error)

Abs 返回 path 的绝对表示。 如果 path 不是绝对路径,它将与当前工作目录 连接以转换为绝对路径。给定文件的绝对 路径名不保证唯一。 Abs 会对结果调用 Clean。

func Base

func Base(path string) string

Base 返回 path 的最后一个元素。 在提取最后一个元素之前会移除尾部路径分隔符。 如果 path 为空,Base 返回 "."。 如果 path 完全由分隔符组成,Base 返回单个分隔符。

Example
package main

import (
	"fmt"
	"path/filepath"
)

func main() {
	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(""))

}

Output:

On Unix:
baz.js
baz
baz
dev.txt
todo.txt
..
.
/
.

func Clean

func Clean(path string) string

Clean 通过纯粹的词法处理返回与 path 等价的最短路径名。 它迭代地应用以下规则,直到无法再做进一步处理:

  1. 将多个 Separator 元素替换为单个元素。
  2. 消除每个 . 路径名元素(当前目录)。
  3. 消除每个内部的 .. 路径名元素(父目录) 以及位于它前面的非 .. 元素。
  4. 消除位于有根路径开头的 .. 元素: 即,假设 Separator 为 '/',将路径开头的 "/.." 替换为 "/"。

返回的路径只有在表示根目录时才以斜杠结尾, 例如 Unix 上的 "/" 或 Windows 上的 `C:\`。

最后,所有出现的斜杠都被替换为 Separator。

如果此过程的结果是空字符串,Clean 返回字符串 "."。

在 Windows 上,Clean 除了将出现的 "/" 替换为 `\` 之外, 不会修改卷名。 例如,Clean("//host/share/../x") 返回 `\\host\share\x`。

另见 Rob Pike, “Lexical File Names in Plan 9 or Getting Dot-Dot Right,” https://9p.io/sys/doc/lexnames.html

func Dir

func Dir(path string) string

Dir 返回 path 中除最后一个元素外的所有部分,通常就是 path 的目录。 去掉最后一个元素后,Dir 会对 path 调用 Clean 并 移除尾部斜杠。 如果 path 为空,Dir 返回 "."。 如果 path 完全由分隔符组成,Dir 返回单个分隔符。 返回的路径不以分隔符结尾,除非它是根目录。

Example
package main

import (
	"fmt"
	"path/filepath"
)

func main() {
	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(""))

}

Output:

On Unix:
/foo/bar
/foo/bar
/foo/bar/baz
/dirty/path
.
..
.
.
/
.
func EvalSymlinks(path string) (string, error)

EvalSymlinks 返回对任何符号链接求值之后的路径名。 如果 path 是相对路径,结果将相对于当前目录, 除非其中一个组件是绝对符号链接。 EvalSymlinks 会对结果调用 Clean。

func Ext

func Ext(path string) string

Ext 返回 path 所使用的文件名扩展名。 扩展名是从 path 最后一个元素中最后一个点 开始的后缀;如果没有点, 则为空。

Example
package main

import (
	"fmt"
	"path/filepath"
)

func main() {
	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"))
}

Output:

No dots: ""
One dot: ".js"
Two dots: ".js"

func FromSlash

func FromSlash(path string) string

FromSlash 返回将 path 中每个斜杠('/')字符 替换为分隔符字符后的结果。多个斜杠会被替换 为多个分隔符。

另见 Localize 函数,它将 io/fs 包所使用的 以斜杠分隔的路径转换为操作系统路径。

func Glob

func Glob(pattern string) (matches []string, err error)

Glob 返回所有匹配 pattern 的文件名,如果没有匹配的文件 则返回 nil。模式的语法与 Match 中相同。 模式可以描述层级名称,例如 /usr/*/bin/ed(假设 Separator 为 '/')。

Glob 忽略文件系统错误,例如读取目录时的 I/O 错误。 唯一可能返回的错误是 ErrBadPattern,当 pattern 格式错误时。

func HasPrefix deprecated

func HasPrefix(p, prefix string) bool

HasPrefix 的存在是为了历史兼容性,不应使用。

Deprecated: HasPrefix 不遵守路径边界, 并且在需要时不会忽略大小写。

func IsAbs

func IsAbs(path string) bool

IsAbs 报告 path 是否为绝对路径。

Example
package main

import (
	"fmt"
	"path/filepath"
)

func main() {
	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(""))

}

Output:

On Unix:
true
false
false
false
true
false

func IsLocal

func IsLocal(path string) bool

IsLocal 报告 path 仅使用词法分析是否具有以下所有性质:

如果 IsLocal(path) 返回 true,那么 Join(base, path) 将始终产生一个包含在 base 内的路径,并且 Clean(path) 将始终产生一个没有 ".." 路径元素的无根路径。

IsLocal 是纯粹的词法操作。 特别地,它不考虑文件系统中可能存在的 任何符号链接的影响。

func Join

func Join(elem ...string) string

Join 将任意数量的路径元素连接为单个路径, 用操作系统特定的 Separator 分隔它们。空元素 会被忽略。结果会被 Clean。然而,如果参数 列表为空或其所有元素都为空,Join 返回 空字符串。 在 Windows 上,仅当第一个非空元素是 UNC 路径时, 结果才会是 UNC 路径。

Example
package main

import (
	"fmt"
	"path/filepath"
)

func main() {
	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"))

}

Output:

On Unix:
a/b/c
a/b/c
a/b/c
a/b/c
../xyz

func Localize

func Localize(path string) (string, error)

Localize 将以斜杠分隔的路径转换为操作系统路径。 输入路径必须是 io/fs.ValidPath 所报告的有效路径。

如果路径无法被操作系统表示,Localize 返回错误。 例如,路径 a\b 在 Windows 上会被拒绝,因为在 Windows 上 \ 是分隔符 字符,不能作为文件名的一部分。

Localize 返回的路径将始终是本地路径,如 IsLocal 所报告的那样。

func Match

func Match(pattern, name string) (matched bool, err error)

Match 报告 name 是否匹配 shell 文件名模式。 模式语法为:

pattern:
	{ term }
term:
	'*'         匹配任意非 Separator 字符序列
	'?'         匹配任意单个非 Separator 字符
	'[' [ '^' ] { character-range } ']'
	            字符类(必须非空)
	c           匹配字符 c (c != '*', '?', '\\', '[')
	'\\' c      匹配字符 c (Windows 上除外)

character-range:
	c           匹配字符 c (c != '\\', '-', ']')
	'\\' c      匹配字符 c (Windows 上除外)
	lo '-' hi   对于 lo <= c <= hi 匹配字符 c

模式中的路径段必须用 Separator 分隔。

Match 要求 pattern 匹配整个 name,而不仅仅是子串。 唯一可能返回的错误是 ErrBadPattern,当 pattern 格式错误时。

在 Windows 上,转义被禁用。取而代之的是,'\\' 被视为 路径分隔符。

Example
package main

import (
	"fmt"
	"path/filepath"
)

func main() {
	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/*"))

}

Output:

On Unix:
true <nil>
false <nil>
true <nil>
true <nil>

func Rel

func Rel(basePath, targPath string) (string, error)

Rel 返回一个相对路径,当它与 basePath 以分隔符连接时, 在词法上等价于 targPath。也就是说, Join(basePath, Rel(basePath, targPath)) 等价于 targPath 本身。

返回的路径将始终相对于 basePath,即使 basePath 和 targPath 没有共享任何元素。Rel 会对结果调用 Clean。

如果 targPath 无法相对于 basePath 表示, 或者计算它需要知道当前工作目录,则返回错误。

Example
package main

import (
	"fmt"
	"path/filepath"
)

func main() {
	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)
	}

}

Output:

On Unix:
"/a/b/c": "b/c" <nil>
"/b/c": "../b/c" <nil>
"./b/c": "" Rel: can't make ./b/c relative to /a

func Split

func Split(path string) (dir, file string)

Split 在最后一个 Separator 之后立即拆分 path, 将其分为目录和文件名两部分。 如果 path 中没有 Separator,Split 返回空 dir 并将 file 设为 path。 返回值具有 path = dir+file 的性质。

Example
package main

import (
	"fmt"
	"path/filepath"
)

func main() {
	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)
	}
}

Output:

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 拆分由操作系统特定的 ListSeparator 连接的路径列表, 通常见于 PATH 或 GOPATH 环境变量中。 与 strings.Split 不同,SplitList 在传入空字符串时 返回空切片。

Example
package main

import (
	"fmt"
	"path/filepath"
)

func main() {
	fmt.Println("On Unix:", filepath.SplitList("/a/b/c:/usr/bin"))
}

Output:

On Unix: [/a/b/c /usr/bin]

func ToSlash

func ToSlash(path string) string

ToSlash 返回将 path 中每个分隔符字符 替换为斜杠('/')字符后的结果。多个分隔符 会被替换为多个斜杠。

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,包括 root。

访问文件和目录时产生的所有错误都由 fn 过滤: 详情参见 WalkFunc 文档。

文件按字典序遍历,这使输出具有确定性, 但要求 Walk 在开始遍历该目录之前 将整个目录读入内存。

Walk 不跟随符号链接。

Walk 的效率低于 Go 1.16 引入的 WalkDir, 后者避免对每个访问的文件或目录调用 os.Lstat。

Example
//go:build !windows && !plan9

package main

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 main() {
	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

func WalkDir(root string, fn fs.WalkDirFunc) error

WalkDir 遍历以 root 为根的文件树,为树中的每个文件或目录 调用 fn,包括 root。

访问文件和目录时产生的所有错误都由 fn 过滤: 详情参见 fs.WalkDirFunc 文档。

文件按字典序遍历,这使输出具有确定性, 但要求 WalkDir 在开始遍历该目录之前 将整个目录读入内存。

WalkDir 不跟随符号链接。

WalkDir 调用 fn 时使用的路径采用适合操作系统 的分隔符字符。这与 io/fs.WalkDir 不同,后者始终 使用以斜杠分隔的路径。

Types

type WalkFunc

type WalkFunc func(path string, info fs.FileInfo, err error) error

WalkFunc 是 Walk 为访问每个文件或目录 而调用的函数类型。

path 参数包含作为 Walk 参数的路径作为前缀。 也就是说,如果 Walk 以根参数 "dir" 调用,并在该目录中 找到一个名为 "a" 的文件,则 walk 函数将以 参数 "dir/a" 被调用。

目录和文件通过 Join 连接,这可能会清理 目录名:如果 Walk 以根参数 "x/../dir" 调用, 并在该目录中找到一个名为 "a" 的文件,则 walk 函数 将以参数 "dir/a" 被调用,而不是 "x/../dir/a"。

info 参数是命名路径的 fs.FileInfo。

函数返回的错误结果控制 Walk 如何继续。 如果函数返回特殊值 SkipDir,Walk 会跳过 当前目录(若 info.IsDir() 为 true 则为 path, 否则为 path 的父目录)。如果函数返回特殊值 SkipAll, Walk 会跳过所有剩余的文件和目录。否则,如果函数 返回非 nil 错误,Walk 会完全停止并返回该错误。

err 参数报告与 path 相关的错误,表明 Walk 不会进入该目录。函数可以决定如何 处理该错误;如前所述,返回该错误将 导致 Walk 停止遍历整棵树。

Walk 在两种情况下会以非 nil 的 err 参数调用该函数。

首先,如果对根目录或树中的任何目录或文件 执行 os.Lstat 失败,Walk 会以 path 设为该 目录或文件的路径、info 设为 nil、err 设为 os.Lstat 返回的错误来调用该函数。

其次,如果某个目录的 Readdirnames 方法失败,Walk 会 以 path 设为该目录的路径、info 设为描述该目录的 fs.FileInfo、err 设为 Readdirnames 返回的错误 来调用该函数。