fs

README

File System Utilities in Go 1.18+

Documentation

Index

• Variables
• func DupPerms(orig, clone string) error
• func Exists(path string) bool
• func ExtractEmbed(it embed.FS, root, target string) error
• func HereOrAbove(name string) (string, error)
• func IsDir(path string) bool
• func IsDirFS(fsys _fs.FS, path string) bool
• func ModTime(path string) time.Time
• func NotExists(path string) bool
• func Tilde2Home(dir string) string

Examples

• Exists
• ExtractEmbed
• ExtractEmbed (Confirm_Default_Read)
• HereOrAbove (Above)
• HereOrAbove (Here)
• ModTime
• NotExists

Variables

var (
	ExtractFilePerms = _fs.FileMode(0600)
	ExtractDirPerms  = _fs.FileMode(0700)
)

Functions

func DupPerms

func DupPerms(orig, clone string) error

DupPerms duplicates the perms of one file or directory onto the second.

func Exists

func Exists(path string) bool

Exists returns true if the given path was absolutely found to exist on the system. A false return value means either the file does not exists or it was not able to determine if it exists or not. Use NotExists instead.

WARNING: do not use this function if a definitive check for the non-existence of a file is required since the possible indeterminate error state is a possibility. These checks are also not atomic on many file systems so avoid this usage for pseudo-semaphore designs and depend on file locks.

Example

package main

import (
	"fmt"

	"github.com/rwxrob/fs"
)

func main() {
	fmt.Println(fs.Exists("testdata/file")) // use NotExists instead of !
}

Output:

false

func ExtractEmbed

func ExtractEmbed(it embed.FS, root, target string) error

ExtractEmbed walks the embedded file system and duplicates its structure into the target directory beginning with root. Since embed.FS drops all permissions information from the original files all files and directories are written as read/write (0600) for the current effective user (0600 for file, 0700 for directories). This default can be changed by setting the package variables ExtractFilePerms and ExtractDirPerms. Note that each embedded file is full buffered into memory before writing.

Example

package main

import (
	"embed"
	"fmt"
	"os"
	"path/filepath"

	"github.com/rwxrob/fs"
)

//go:embed all:testdata/testfs
var testfs embed.FS

func main() {

	// go:embed all:testdata/testfs
	// var testfs embed.FS
	defer os.RemoveAll("testdata/testfsout")

	if err := fs.ExtractEmbed(testfs,
		"testdata/testfs", "testdata/testfsout"); err != nil {
		fmt.Println(err)
	}

	stuff := []string{
		`foo`,
		`_notignored`,
		`.secret`,
		`dir`,
		`dir/README.md`,
	}

	for _, i := range stuff {
		f, err := os.Stat(filepath.Join("testdata/testfsout", i))
		if err != nil {
			fmt.Println(err)
			continue
		}
		fmt.Printf("%v %v\n", i, f.Mode())
	}

}

Output:

foo -rw-------
_notignored -rw-------
.secret -rw-------
dir drwx------
dir/README.md -rw-------

Example (Confirm_Default_Read)

package main

import (
	"embed"
	"fmt"
)

//go:embed all:testdata/testfs
var testfs embed.FS

func main() {

	// go:embed all:testdata/testfs
	// var testfs embed.FS

	foo, err := testfs.Open("testdata/testfs/foo")
	if err != nil {
		fmt.Println(err)
	}
	info, err := foo.Stat()
	if err != nil {
		fmt.Println(err)
	}
	fmt.Println(info.Mode())

}

Output:

-r--r--r--

func HereOrAbove

func HereOrAbove(name string) (string, error)

HereOrAbove returns the full path to the file or directory if it is found in the current working directory, or if not exists in any parent directory recursively.

Example (Above)

package main

import (
	"fmt"
	"os"
	"path/filepath"
	"strings"

	"github.com/rwxrob/fs"
)

func main() {
	dir, _ := os.Getwd()
	defer func() { os.Chdir(dir) }()
	os.Chdir("testdata/adir")

	path, err := fs.HereOrAbove("anotherfile")
	if err != nil {
		fmt.Println(err)
	}
	d := strings.Split(path, string(filepath.Separator))
	fmt.Println(d[len(d)-2:])

}

Output:

[testdata anotherfile]

Example (Here)

package main

import (
	"fmt"
	"os"
	"path/filepath"
	"strings"

	"github.com/rwxrob/fs"
)

func main() {
	dir, _ := os.Getwd()
	defer func() { os.Chdir(dir) }()
	os.Chdir("testdata/adir")

	path, err := fs.HereOrAbove("afile")
	if err != nil {
		fmt.Println(err)
	}
	d := strings.Split(path, string(filepath.Separator))
	fmt.Println(d[len(d)-2:])

}

Output:

[adir afile]

func IsDir

func IsDir(path string) bool

IsDir returns true if the indicated path is a directory. Returns false and logs if unable to determine.

func IsDirFS

func IsDirFS(fsys _fs.FS, path string) bool

IsDirFS simply a shortcut for fs.Stat().IsDir(). Only returns true if the path is a directory. If not a directory (or an error prevented confirming it is a directory) then returns false.

func ModTime

func ModTime(path string) time.Time

ModTime returns the FileInfo.ModTime() from Stat() as a convenience or returns a zero time if not. See time.IsZero.

Example

package main

import (
	"fmt"

	"github.com/rwxrob/fs"
)

func main() {
	fmt.Println(fs.ModTime("testdata/file").IsZero())
	fmt.Println(fs.ModTime("testdata/none"))
}

Output:

true
0001-01-01 00:00:00 +0000 UTC

func NotExists

func NotExists(path string) bool

NotExists definitively returns true if the given path does not exist. See Exists as well.

Example

package main

import (
	"fmt"

	"github.com/rwxrob/fs"
)

func main() {
	fmt.Println(fs.NotExists("testdata/nope")) // use Exists instead of !
}

Output:

true

func Tilde2Home

func Tilde2Home(dir string) string

Tilde2Home expands a Tilde (~) prefix into a proper os.UserHomeDir path. If it cannot find os.UserHomeDir simple returns unchanged path. Will not expand for specific users (~username).