Documentation
¶
Overview ¶
filepathパッケージは、ファイル名パスを操作するためのユーティリティ関数を実装しています。 これは、対象のオペレーティングシステムで定義されたファイルパスと互換性のある方法で行います。
filepathパッケージは、オペレーティングシステムに応じてスラッシュまたはバックスラッシュを使用します。 オペレーティングシステムに関係なく常にスラッシュを使用するURLのようなパスを処理するには、[path]パッケージを参照してください。
Index ¶
- Constants
- Variables
- func Abs(path string) (string, error)
- func Base(path string) string
- func Clean(path string) string
- func Dir(path string) string
- func EvalSymlinks(path string) (string, error)
- func Ext(path string) string
- func FromSlash(path string) string
- func Glob(pattern string) (matches []string, err error)
- func HasPrefix(p, prefix string) booldeprecated
- func IsAbs(path string) bool
- func IsLocal(path string) bool
- func Join(elem ...string) string
- func Localize(path string) (string, error)
- func Match(pattern, name string) (matched bool, err error)
- func Rel(basePath, targPath string) (string, error)
- func Split(path string) (dir, file string)
- func SplitList(path string) []string
- func ToSlash(path string) string
- func VolumeName(path string) string
- func Walk(root string, fn WalkFunc) error
- func WalkDir(root string, fn fs.WalkDirFunc) error
- type WalkFunc
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 ¶
Absはパスの絶対表現を返します。 パスが絶対でない場合、現在の作業ディレクトリと結合して絶対パスに変換されます。 特定のファイルの絶対パス名が一意であることは保証されません。 Absは結果に Clean を呼び出します。
func Base ¶
Baseはパスの最後の要素を返します。 パスの末尾のセパレーターは、最後の要素を抽出する前に削除されます。 パスが空の場合、Baseは「.」を返します。 パスが完全にセパレーターで構成されている場合、Baseは単一のセパレーターを返します。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/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 ¶
Cleanは、純粋な字句解析によってパスに相当する最短のパス名を返します。 次の規則を適用し、処理できなくなるまで反復的に行います。
- 複数の Separator 要素を単一の要素に置き換える。
- 各「.」パス名要素（カレントディレクトリ）を削除する。
- 各内部の「..」パス名要素（親ディレクトリ）を削除し、それに続く非「..」要素も削除する。
- ルートパスで始まる「..」要素を削除する： つまり、パスの先頭で "/.." を "/" に置き換える（セパレータが '/' であると仮定）。
返されるパスは、ルートディレクトリを表す場合のみスラッシュで終わります。 例：Unixでは "/"、Windowsでは `C:\` などです。
最後に、スラッシュの出現箇所はセパレータに置き換えられます。
この処理の結果が空の文字列の場合、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 ¶
Dirはパスの最後の要素以外のすべてを返します。通常はパスのディレクトリです。 最後の要素を除いた後、Dirはパスに Clean を呼び出し、末尾のスラッシュは除去されます。 パスが空の場合、Dirは「.」を返します。 パスがセパレーターだけで構成されている場合、Dirは単一のセパレーターを返します。 返されるパスは、ルートディレクトリでない限り、セパレーターで終了しません。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/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 ¶
EvalSymlinksは、シンボリックリンクの評価後のパス名を返します。 pathが相対パスの場合、結果は現在のディレクトリを基準にし、 絶対シンボリックリンクを持つコンポーネントが存在する場合を除きます。 EvalSymlinksは結果に対して Clean を呼び出します。
func Ext ¶
Extはpathで使用されるファイル名の拡張子を返します。 拡張子とは、pathの最後の要素の最後のドットから始まる接尾辞であり、 ドットがない場合は空です。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/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 ¶
FromSlashは、パス内の各スラッシュ('/')文字をセパレータ文字に置き換えた結果を返します。 複数のスラッシュは複数のセパレータに置き換えられます。
io/fsパッケージで使用されるスラッシュ区切りのパスをオペレーティングシステムのパスに変換する Localize関数も参照してください。
func Glob ¶
Globは、パターンに一致するすべてのファイルの名前を返します。一致するファイルがない場合はnilを返します。パターンの構文はMatchと同じです。パターンには、/usr/*/bin/ed（Separator が '/'と仮定）などの階層的な名前を記述することができます。 Globは、ディレクトリを読み込む際のI/Oエラーなどのファイルシステムのエラーを無視します。返される唯一の可能性のあるエラーは、パターンが不正な場合の ErrBadPattern です。
func IsAbs ¶
IsAbsはパスが絶対パスかどうかを報告します。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/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 ¶ added in v1.20.0
IsLocalは、パスが次の条件をすべて満たすかどうかを報告します。 - パスが評価されるディレクトリをルートとするサブツリー内にある - 絶対パスではない - 空ではない - Windowsの場合、"NUL"のような予約済みの名前ではない IsLocal(path)がtrueを返す場合、 Join(base, path)は常にbase内に含まれるパスを生成し、 Clean(path)は常に".."パス要素を持たないルート付きのパスを生成します。 IsLocalは純粋に文字解析の操作です。 特に、ファイルシステムに存在する可能性のあるシンボリックリンクの影響は考慮されません。
func Join ¶
Joinは、パスの要素をいくつでも指定して、OS固有の Separator で区切って1つのパスに結合します。空の要素は無視されます。結果はクリーニングされます。ただし、引数リストが空であるか、そのすべての要素が空の場合、Joinは空の文字列を返します。 Windowsでは、最初の非空要素がUNCパスである場合にのみ結果はUNCパスになります。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/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 ¶ added in v1.23.0
Localizeは、スラッシュ区切りのパスをオペレーティングシステムのパスに変換します。 入力パスは、io/fs.ValidPath によって報告される有効なパスでなければなりません。
Localizeは、パスがオペレーティングシステムによって表現できない場合にエラーを返します。 例えば、Windowsではパスa\bは拒否されます。これは、\がセパレータ文字であり、 ファイル名の一部にはなり得ないからです。
Localizeによって返されるパスは、IsLocalによって報告されるように、常にローカルになります。
func Match ¶
Matchは、名前がシェルのファイル名パターンと一致するかどうかを報告します。 パターンの構文は次の通りです:
pattern:
{ term }
term:
'*' 任意の非区切り文字のシーケンスに一致します
'?' 任意の単一の非区切り文字に一致します
'[' [ '^' ] { character-range } ']'
文字クラス（空でない必要があります）
c 文字 c に一致します (c != '*', '?', '\', '[')
'\' c 文字 c に一致します（Windowsを除く）
character-range:
c 文字 c に一致します (c != '\', '-', ']')
'\\' c 文字 c に一致します（Windowsを除く）
lo '-' hi lo <= c <= hi の範囲の文字 c に一致します
パターン内のパスセグメントは Separator で区切られている必要があります。
Matchはパターンがnameのすべてに一致することを要求し、部分文字列だけではありません。 返される可能性のある唯一のエラーは、パターンが不正な場合の ErrBadPattern です。
Windowsでは、エスケープは無効になっています。代わりに'\\'はパスセパレータとして扱われます。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/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 ¶
Relは、basePathに区切り文字を挟んで結合されたときに、 targPathと文法的に同等な相対パスを返します。つまり、 Join(basePath, Rel(basePath, targPath)) は targPath そのものと同等です。
返されるパスは常にbasePathに対する相対パスになります。 basePathとtargPathが共通の要素を持たない場合でも同様です。Relは結果に対して Clean を呼び出します。
targPathをbasePathに対して相対的にできない場合や、 それを計算するために現在の作業ディレクトリを知る必要がある場合はエラーが返されます。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/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 ¶
Splitは最後の Separator の直後にあるパスを分割し、ディレクトリとファイル名の要素に分けます。 パスにSeparatorがない場合、Splitは空のディレクトリとファイルを返します。 返される値は path = dir + file という性質を持ちます。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/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 ¶
SplitListは、OS固有の ListSeparator で結合されたパスのリストを分割します。 通常、 PATHまたはGOPATH環境変数で見つかることがあります。 strings.Splitとは異なり、SplitListは空のスライスを返します。 空の文字列が渡された場合。
Example ¶
package main
import (
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/path/filepath"
)
func main() {
fmt.Println("On Unix:", filepath.SplitList("/a/b/c:/usr/bin"))
}
Output: On Unix: [/a/b/c /usr/bin]
func VolumeName ¶
VolumeNameは先頭のボリューム名を返します。 Windowsの場合、"C:\foo\bar"に対しては"C:"を返します。 "\\host\share\foo"に対しては"\\host\share"を返します。 他のプラットフォームでは、空文字列を返します。
func Walk ¶
Walkはルートとなるファイルツリーを辿り、各ファイルまたはディレクトリに対してfnを呼び出します。 これにはルートも含まれます。
ファイルとディレクトリの訪問時に発生するエラーは、すべてfnによってフィルタリングされます。 詳細については WalkFunc のドキュメントを参照してください。
ファイルはレキシカルオーダーで走査されますが、これにより出力は決定論的になります。 ただし、走査するディレクトリの前にディレクトリ全体をメモリに読み込む必要があります。
Walkはシンボリックリンクを辿りません。
WalkはGo 1.16で導入された WalkDir よりも効率が低下します。 WalkDirでは、訪問するファイルまたはディレクトリごとにos.Lstatを呼び出すのを避けています。
Example ¶
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 ¶ added in v1.16.0
func WalkDir(root string, fn fs.WalkDirFunc) error
WalkDirは、ルートにあるファイルツリーを走査し、各ファイルやディレクトリに対してfnを呼び出します。 ツリー内のルートも含まれます。
ファイルやディレクトリの訪問中に発生するすべてのエラーは、fnによってフィルタリングされます： 詳細については、fs.WalkDirFunc のドキュメントを参照してください。
ファイルは辞書順で走査されるため、出力が確定論的になりますが、WalkDirは そのディレクトリの走査に進む前にディレクトリ全体をメモリに読み込む必要があります。
WalkDirはシンボリックリンクを辿りません。
WalkDirは、オペレーティングシステムに適切な区切り文字を使用するパスを fnに渡して呼び出します。これは、[io/fs.WalkDir]とは異なり、常にスラッシュで区切られたパスを使用します。
Types ¶
type WalkFunc ¶
WalkFuncは、Walk によって呼び出される関数の型です。この関数は、各ファイルやディレクトリを訪れるために呼び出されます。
path引数には、Walkの引数がプレフィックスとして含まれています。 つまり、root引数が「dir」として呼び出され、そのディレクトリに「a」という名前のファイルが見つかった場合、 ウォーク関数は引数「dir/a」で呼び出されます。
ディレクトリとファイルはJoinで結合され、ディレクトリ名がクリーンアップされるかもしれません。 たとえば、root引数が「x/../dir」として呼び出され、そのディレクトリに「a」という名前のファイルが見つかった場合、 ウォーク関数は引数「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は、2つの場合に、非nilのerr引数を持つ関数を呼び出します。
第1に、ルートディレクトリまたはツリー内の任意のディレクトリまたはファイルの os.Lstat が失敗した場合、 Walkは関数を呼び出し、パスをそのディレクトリまたはファイルのパスに設定し、infoをnilに設定し、errをos.Lstatからのエラーに設定します。
第2に、ディレクトリのReaddirnamesメソッドが失敗した場合、 Walkは関数を呼び出し、パスをディレクトリのパスに設定し、infoをディレクトリを説明する fs.FileInfo に設定し、errをReaddirnamesからのエラーに設定します。
Source Files