ufs

func Copy ¶

func Copy(srcFS fs.FS, srcFilename string, destFS FS, destFilename string) error

Copy copies the single file at srcFilename in srcFS to destFilename in destFS. The parent directory of destFilename must already exist. The destination file is created (or truncated) via [FS.Create].

ctx := context.Background()
src, _ := New(ctx, "memory://")
dst, _ := New(ctx, "memory://")
defer src.Close()
defer dst.Close()

f, _ := src.Create("hello.txt")
f.WriteString("hello")
f.Close()

if err := Copy(src, "hello.txt", dst, "copy.txt"); err != nil {
	log.Fatal(err)
}

data, _ := dst.ReadFile("copy.txt")
fmt.Println(string(data))

Output:
hello

func CreateURI ¶

func CreateURI(name string, nested map[string]string) (string, error)

CreateURI constructs a URI understood by New that layers additional file systems at specific mount paths inside the base file system. The nested map maps mount-point paths (e.g. "cache", "data/scratch") to the URI of the file system to mount there. Paths follow fs.ValidPath conventions.

Pass the returned URI directly to New:

 ctx := context.Background()
	uri, _ := ufs.CreateURI("file:///srv/data", map[string]string{
	    "tmp": "memory://",
	})
	fsys, _ := ufs.New(ctx, uri)

Returns an error if name or any nested URI cannot be parsed.

ctx := context.Background()
// A memory FS with no nested mounts.
uri, err := CreateURI("memory://", nil)
if err != nil {
	log.Fatal(err)
}
fmt.Println(uri)

// Open it — New accepts URIs produced by CreateURI.
fsys, err := New(ctx, uri)
if err != nil {
	log.Fatal(err)
}
defer fsys.Close()
fmt.Println(fsys.String())

Output:
memory:
nestFS(memory://)

func ForEachFileInfo ¶

func ForEachFileInfo(fsys fs.FS, dir string, f func(fs.FileInfo) error) error

ForEachFileInfo calls f for each file (not directory) under dir, providing its fs.FileInfo. It is the typed companion to ForEachFilename and prefers a native ForEachFileInfoIter implementation when available, falling back to fs.WalkDir. The walk stops and returns the first non-nil error from f.

func ForEachFilename ¶

func ForEachFilename(fsys fs.FS, dir string, f func(string) error) error

ForEachFilename calls f for each file path (not directory) under dir, streaming results without building an intermediate slice. If fsys implements ForEachFilenameIter, its native implementation is used directly; otherwise the paths are collected via fs.WalkDir and iterated. f receives paths relative to dir. The walk stops and returns the first non-nil error from f.

ctx := context.Background()
fsys, _ := New(ctx, "memory://")
defer fsys.Close()

for _, name := range []string{"a.txt", "b.txt"} {
	f, _ := fsys.Create(name)
	f.Close()
}

ForEachFilename(fsys, ".", func(name string) error {
	fmt.Println(name)
	return nil
})

Output:
a.txt
b.txt

func List ¶

func List(fsys fs.FS, dir string) ([]string, error)

List returns all paths (both files and directories) under dir in lexical order. The root directory "." is never included in the result. For files-only, prefer ListFiles.

ctx := context.Background()
fsys, _ := New(ctx, "memory://")
defer fsys.Close()

fsys.MkdirAll("subdir", fs.ModePerm)
f, _ := fsys.Create("subdir/c.txt")
f.Close()

entries, _ := List(fsys, ".")
for _, p := range entries {
	fmt.Println(p)
}

Output:
subdir
subdir/c.txt

func ListFiles ¶

func ListFiles(fsys fs.FS, dir string) ([]string, error)

ListFiles returns the paths of all files (excluding directories) under dir in lexical order. If fsys implements ListFilenames, its native implementation is used to avoid building intermediate fs.FileInfo values.

This method may take a long time since it may traverse a large file system and build a large slice of paths in memory.

ctx := context.Background()
fsys, _ := New(ctx, "memory://")
defer fsys.Close()

fsys.MkdirAll("subdir", fs.ModePerm)
for _, name := range []string{"a.txt", "b.txt", "subdir/c.txt"} {
	f, _ := fsys.Create(name)
	f.Close()
}

files, _ := ListFiles(fsys, ".")
for _, p := range files {
	fmt.Println(p)
}

Output:
a.txt
b.txt
subdir/c.txt

func Remove ¶ added in v0.6.0

func Remove(fsys fs.FS, name string) error

Remove removes the file or empty directory at name in fsys. If fsys implements Remover, its Remove method is used directly. Otherwise Remove returns fs.ErrPermission wrapped in an fs.PathError.

func RemoveAll ¶ added in v0.6.0

func RemoveAll(fsys fs.FS, name string) error

RemoveAll removes name and everything beneath it in fsys. If fsys implements Remover, its RemoveAll method is used directly. Otherwise RemoveAll returns fs.ErrPermission wrapped in an fs.PathError.

func Rsync ¶

func Rsync(srcFS fs.FS, destFS FS, dir string) error

Rsync copies all files under dir from srcFS into destFS, preserving the relative path structure. Parent directories in destFS are created with fs.ModePerm as needed. Existing files in destFS are overwritten. The copy is not atomic: if an error occurs mid-walk, destFS may be partially written.

dir must satisfy fs.ValidPath; use "." to copy the entire file system.

ctx := context.Background()
src, _ := New(ctx, "memory://")
dst, _ := New(ctx, "memory://")
defer src.Close()
defer dst.Close()

src.MkdirAll("subdir", fs.ModePerm)
for _, name := range []string{"a.txt", "subdir/b.txt"} {
	f, _ := src.Create(name)
	f.WriteString("content")
	f.Close()
}

if err := Rsync(src, dst, "."); err != nil {
	log.Fatal(err)
}

files, _ := ListFiles(dst, ".")
for _, p := range files {
	fmt.Println(p)
}

Output:
a.txt
subdir/b.txt

func Walk ¶ added in v0.6.0

func Walk(fsys fs.FS, dir string, args WalkArgs, f func(string) error) error

Walk walks dir in fsys, calling f for each file whose ancestor directories pass the filters in args. It differs from ForEachFilename in two ways: virtual archive-mount directories (e.g. "data.zip.d") are skipped by default (set [WalkArgs.IncludeMountedArchive] to descend into them), and directories whose base names match any [WalkArgs.ExcludeDirectory] glob are skipped entirely. The walk stops and returns the first non-nil error from f.