package filepath

Import Path
	path/filepath (on golang.org and go.dev)

Dependency Relation
	imports 8 packages, and imported by 11 packages

Involved Source Files

	      match.go
	   d➜ path.go
		Package filepath implements utility routines for manipulating filename paths
		in a way compatible with the target operating system-defined file paths.

		The filepath package uses either forward slashes or backslashes,
		depending on the operating system. To process paths such as URLs
		that always use forward slashes regardless of the operating
		system, see the path package.

	      path_unix.go
	      symlink.go
	      symlink_unix.go
Code Examples

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


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


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


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


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


	Match
		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/*"))
		
		}


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


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


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


	Walk
		// +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
			}
		}


Package-Level Type Names (total 3, in which 1 are exported)

	/* sort exporteds by: alphabet | popularity */
	 type WalkFunc (func)
		WalkFunc is the type of the function called by Walk to visit each each
		file or directory.

		The path argument contains the argument to Walk as a prefix.
		That is, if Walk is called with root argument "dir" and finds a file
		named "a" in that directory, the walk function will be called with
		argument "dir/a".

		The directory and file are joined with Join, which may clean the
		directory name: if Walk is called with the root argument "x/../dir"
		and finds a file named "a" in that directory, the walk function will
		be called with argument "dir/a", not "x/../dir/a".

		The info argument is the fs.FileInfo for the named path.

		The error result returned by the function controls how Walk continues.
		If the function returns the special value SkipDir, Walk skips the
		current directory (path if info.IsDir() is true, otherwise path's
		parent directory). Otherwise, if the function returns a non-nil error,
		Walk stops entirely and returns that error.

		The err argument reports an error related to path, signaling that Walk
		will not walk into that directory. The function can decide how to
		handle that error; as described earlier, returning the error will
		cause Walk to stop walking the entire tree.

		Walk calls the function with a non-nil err argument in two cases.

		First, if an os.Lstat on the root directory or any directory or file
		in the tree fails, Walk calls the function with path set to that
		directory or file's path, info set to nil, and err set to the error
		from os.Lstat.

		Second, if a directory's Readdirnames method fails, Walk calls the
		function with path set to the directory's path, info, set to an
		fs.FileInfo describing the directory, and err set to the error from
		Readdirnames.

		As Inputs Of (at least 5, in which 3 are exported)
			func Walk(root string, fn WalkFunc) error
			func github.com/spf13/afero.Walk(fs afero.Fs, root string, walkFn WalkFunc) error
			func github.com/spf13/afero.Afero.Walk(root string, walkFn WalkFunc) error
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			func walk(path string, info fs.FileInfo, walkFn WalkFunc) error
			func github.com/spf13/afero.walk(fs afero.Fs, path string, info os.FileInfo, walkFn WalkFunc) error

	/* 2 unexporteds ... *//* 2 unexporteds: */
	 type lazybuf (struct)
		A lazybuf is a lazily constructed path buffer.
		It supports append, reading previously appended bytes,
		and retrieving the final string. It does not allocate a buffer
		to hold the output until that output diverges from s.

		Fields (total 5, none are exported)
			/* 5 unexporteds ... *//* 5 unexporteds: */
			buf []byte
			path string
			volAndPath string
			volLen int
			w int
		Methods (total 3, none are exported)
			/* 3 unexporteds ... *//* 3 unexporteds: */
			(*T) append(c byte)
			(*T) index(i int) byte
			(*T) string() string

	 type statDirEntry (struct)

		Fields (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			info fs.FileInfo
		Methods (total 4, all are exported)
			(*T) Info() (fs.FileInfo, error)
			(*T) IsDir() bool
			(*T) Name() string
			(*T) Type() fs.FileMode
		Implements (at least one exported)
			*T : io/fs.DirEntry


Package-Level Functions (total 38, in which 19 are exported)

	 func Abs(path string) (string, error)
		Abs returns an absolute representation of path.
		If the path is not absolute it will be joined with the current
		working directory to turn it into an absolute path. The absolute
		path name for a given file is not guaranteed to be unique.
		Abs calls Clean on the result.

	 func Base(path string) string
		Base returns the last element of path.
		Trailing path separators are removed before extracting the last element.
		If the path is empty, Base returns ".".
		If the path consists entirely of separators, Base returns a single separator.

	 func Clean(path string) string
		Clean returns the shortest path name equivalent to path
		by purely lexical processing. It applies the following rules
		iteratively until no further processing can be done:

			1. Replace multiple Separator elements with a single one.
			2. Eliminate each . path name element (the current directory).
			3. Eliminate each inner .. path name element (the parent directory)
			   along with the non-.. element that precedes it.
			4. Eliminate .. elements that begin a rooted path:
			   that is, replace "/.." by "/" at the beginning of a path,
			   assuming Separator is '/'.

		The returned path ends in a slash only if it represents a root directory,
		such as "/" on Unix or `C:\` on Windows.

		Finally, any occurrences of slash are replaced by Separator.

		If the result of this process is an empty string, Clean
		returns the string ".".

		See also Rob Pike, ``Lexical File Names in Plan 9 or
		Getting Dot-Dot Right,''
		https://9p.io/sys/doc/lexnames.html

	 func Dir(path string) string
		Dir returns all but the last element of path, typically the path's directory.
		After dropping the final element, Dir calls Clean on the path and trailing
		slashes are removed.
		If the path is empty, Dir returns ".".
		If the path consists entirely of separators, Dir returns a single separator.
		The returned path does not end in a separator unless it is the root directory.

	 func EvalSymlinks(path string) (string, error)
		EvalSymlinks returns the path name after the evaluation of any symbolic
		links.
		If path is relative the result will be relative to the current directory,
		unless one of the components is an absolute symbolic link.
		EvalSymlinks calls Clean on the result.

	 func Ext(path string) string
		Ext returns the file name extension used by path.
		The extension is the suffix beginning at the final dot
		in the final element of path; it is empty if there is
		no dot.

	 func FromSlash(path string) string
		FromSlash returns the result of replacing each slash ('/') character
		in path with a separator character. Multiple slashes are replaced
		by multiple separators.

	 func Glob(pattern string) (matches []string, err error)
		Glob returns the names of all files matching pattern or nil
		if there is no matching file. The syntax of patterns is the same
		as in Match. The pattern may describe hierarchical names such as
		/usr/*/bin/ed (assuming the Separator is '/').

		Glob ignores file system errors such as I/O errors reading directories.
		The only possible returned error is ErrBadPattern, when pattern
		is malformed.

	 func HasPrefix(p, prefix string) bool
		HasPrefix exists for historical compatibility and should not be used.

		Deprecated: HasPrefix does not respect path boundaries and
		does not ignore case when required.

	 func IsAbs(path string) bool
		IsAbs reports whether the path is absolute.

	 func Join(elem ...string) string
		Join joins any number of path elements into a single path,
		separating them with an OS specific Separator. Empty elements
		are ignored. The result is Cleaned. However, if the argument
		list is empty or all its elements are empty, Join returns
		an empty string.
		On Windows, the result will only be a UNC path if the first
		non-empty element is a UNC path.

	 func Match(pattern, name string) (matched bool, err error)
		Match reports whether name matches the shell file name pattern.
		The pattern syntax is:

			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 requires pattern to match all of name, not just a substring.
		The only possible returned error is ErrBadPattern, when pattern
		is malformed.

		On Windows, escaping is disabled. Instead, '\\' is treated as
		path separator.

	 func Rel(basepath, targpath string) (string, error)
		Rel returns a relative path that is lexically equivalent to targpath when
		joined to basepath with an intervening separator. That is,
		Join(basepath, Rel(basepath, targpath)) is equivalent to targpath itself.
		On success, the returned path will always be relative to basepath,
		even if basepath and targpath share no elements.
		An error is returned if targpath can't be made relative to basepath or if
		knowing the current working directory would be necessary to compute it.
		Rel calls Clean on the result.

	 func Split(path string) (dir, file string)
		Split splits path immediately following the final Separator,
		separating it into a directory and file name component.
		If there is no Separator in path, Split returns an empty dir
		and file set to path.
		The returned values have the property that path = dir+file.

	 func SplitList(path string) []string
		SplitList splits a list of paths joined by the OS-specific ListSeparator,
		usually found in PATH or GOPATH environment variables.
		Unlike strings.Split, SplitList returns an empty slice when passed an empty
		string.

	 func ToSlash(path string) string
		ToSlash returns the result of replacing each separator character
		in path with a slash ('/') character. Multiple separators are
		replaced by multiple slashes.

	 func VolumeName(path string) string
		VolumeName returns leading volume name.
		Given "C:\foo\bar" it returns "C:" on Windows.
		Given "\\host\share\foo" it returns "\\host\share".
		On other platforms it returns "".

	 func Walk(root string, fn WalkFunc) error
		Walk walks the file tree rooted at root, calling fn for each file or
		directory in the tree, including root.

		All errors that arise visiting files and directories are filtered by fn:
		see the WalkFunc documentation for details.

		The files are walked in lexical order, which makes the output deterministic
		but requires Walk to read an entire directory into memory before proceeding
		to walk that directory.

		Walk does not follow symbolic links.

		Walk is less efficient than WalkDir, introduced in Go 1.16,
		which avoids calling os.Lstat on every visited file or directory.

	 func WalkDir(root string, fn fs.WalkDirFunc) error
		WalkDir walks the file tree rooted at root, calling fn for each file or
		directory in the tree, including root.

		All errors that arise visiting files and directories are filtered by fn:
		see the fs.WalkDirFunc documentation for details.

		The files are walked in lexical order, which makes the output deterministic
		but requires WalkDir to read an entire directory into memory before proceeding
		to walk that directory.

		WalkDir does not follow symbolic links.

	/* 19 unexporteds ... *//* 19 unexporteds: */
	 func abs(path string) (string, error)
	 func cleanGlobPath(path string) string
		cleanGlobPath prepares path for glob matching.

	 func cleanGlobPathWindows(path string) (prefixLen int, cleaned string)
		cleanGlobPathWindows is windows version of cleanGlobPath.

	 func evalSymlinks(path string) (string, error)
	 func getEsc(chunk string) (r rune, nchunk string, err error)
		getEsc gets a possibly-escaped character from chunk, for a character class.

	 func glob(dir, pattern string, matches []string) (m []string, e error)
		glob searches for files matching pattern in the directory dir
		and appends them to matches. If the directory cannot be
		opened, it returns the existing matches. New matches are
		added in lexicographical order.

	 func hasMeta(path string) bool
		hasMeta reports whether path contains any of the magic characters
		recognized by Match.

	 func join(elem []string) string
	 func matchChunk(chunk, s string) (rest string, ok bool, err error)
		matchChunk checks whether chunk matches the beginning of s.
		If so, it returns the remainder of s (after the match).
		Chunk is all single-character operators: literals, char classes, and ?.

	 func readDir(dirname string) ([]fs.DirEntry, error)
		readDir reads the directory named by dirname and returns
		a sorted list of directory entries.

	 func readDirNames(dirname string) ([]string, error)
		readDirNames reads the directory named by dirname and returns
		a sorted list of directory entry names.

	 func sameWord(a, b string) bool
	 func scanChunk(pattern string) (star bool, chunk, rest string)
		scanChunk gets the next segment of pattern, which is a non-star string
		possibly preceded by a star.

	 func splitList(path string) []string
	 func unixAbs(path string) (string, error)
	 func volumeNameLen(path string) int
		volumeNameLen returns length of the leading volume name on Windows.
		It returns 0 elsewhere.

	 func walk(path string, info fs.FileInfo, walkFn WalkFunc) error
		walk recursively descends path, calling walkFn.

	 func walkDir(path string, d fs.DirEntry, walkDirFn fs.WalkDirFunc) error
		walkDir recursively descends path, calling walkDirFn.

	 func walkSymlinks(path string) (string, error)
Package-Level Variables (total 3, in which 2 are exported)

	  var ErrBadPattern error
		ErrBadPattern indicates a pattern was malformed.

	  var SkipDir error
		SkipDir is used as a return value from WalkFuncs to indicate that
		the directory named in the call is to be skipped. It is not returned
		as an error by any function.

	/* one unexported ... *//* one unexported: */
	  var lstat func(name string) (fs.FileInfo, error) // for testing
Package-Level Constants (total 2, both are exported)

	const ListSeparator = 58
	const Separator = 47

The pages are generated with Golds v0.3.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds.