fileutil

README

(yet another) fileutil (package)

DEPRECATED: md0.org/fileutil is deprecated in favor of md0.org/filex. This was only a name change, but fileutil will receive no future updates and may eventually be deleted.

Small Go library of functions to deal with files:

• does something exist at this path
• does this path represent a file
• does this path represent a directory
• is this an empty directory
• etc. (actually right now I think that's about it!)

It's a very thin wrapper around standard library functions that are just slightly cumbersome to deal with or to keep their usage straight after not using them for a while.

Lighter weight option

If you only need, eg, IsFile, you can easily pull it out as:

// combined IsExist and IsFile from md0.org/fileutil
func isFile(path string) bool {
    if _, err := os.Stat(path); err != nil {
        if os.IsNotExist(err) {
            return false
        }
    }
    info, _ := os.Stat(path)
    return info.Mode().IsRegular()
}

Same obviously applies to all functions in the package.

License

MIT

Documentation

Overview

Package fileutil wraps standard library functions to get info about files and directories that is otherwise a little convoluted to work out every time it's needed.

In the future the package may add functions to help manipulate files and directories.

Index

• Variables
• func BaseNoext(name string) string
• func CopyDir(src, dstGrandparent string) error
• func CopyFile(src, dst string) error
• func CreateWithAncestors(path string) error
• func DetectContentType(rs io.ReadSeeker) (string, error)
• func DiffDirSimple(left, right string) (bool, []string, error)
• func FileDetectContentType(path string) (string, error)
• func FindFiles(base string) ([]string, error)
• func IsDir(p string) bool
• func IsEmpty(p string) bool
• func IsExist(p string) bool
• func IsFile(p string) bool
• func LastInDir(dir string) (string, error)
• func MD5(path string) (string, error)
• func ReadFileLines(p string) ([]string, error)
• func ReadFileLinesDie(p string) []string
• func ReadFileNonBlankNonCommentLines(p string) ([]string, error)
• func ReadFileNonBlankNonCommentLinesDie(p string) []string
• func ReadFileSingleLine(p string) (string, error)
• func ReadFileSingleLineDie(p string) string
• func Touch(path string) error
• func WriteLinesToFile(name string, lines []string) error

Variables

var (
	ErrNotDirectory    = errors.New("not a directory")
	ErrDirectoryExists = errors.New("directory exists")
	ErrMultipleLines   = errors.New("multiple lines when one expected")
	ErrNotFound        = errors.New("not found")
)

Functions

func BaseNoext

func BaseNoext(name string) string

BaseNoext returns the basename of path (ie, the filename without the preceding path components) without the extension (what *I* sometimes erroneously think of as the "basename").

NB: uses package path, so meant to work on slash-separated paths.

func CopyDir

func CopyDir(src, dstGrandparent string) error

CopyDir copies src (must be a directory) into dstGrandparent (which also must be an existing directory).

It's an error if a directory already exists that is called:

filepath.Join(dstGrandparent, filepath.Base(src))

func CopyFile

func CopyFile(src, dst string) error

Stolen from Russ Cox "Error Handling — Problem Overview" https://go.googlesource.com/proposal/+/master/design/go2draft-error-handling-overview.md

But also cf. CopyFile from Dave Cheney's github.com/pkg/fileutils

func CreateWithAncestors

func CreateWithAncestors(path string) error

CreateWithAncestors will make all the non-existent directories in path so that os.Create can be called on path without an error.

This seems like a need that arises often enough to warrant a function.

I'm putting this on hold. It's easy enough to do "manually" when needed..

func DetectContentType

func DetectContentType(rs io.ReadSeeker) (string, error)

Detect content-type without having the whole file in memory.

comment from reference: At most the first 512 bytes of data are used: https://golang.org/src/net/http/sniff.go?s=646:688#L11

ref: https://gist.github.com/rayrutjes/db9b9ea8e02255d62ce2 https://archive.is/iGqI9

func DiffDirSimple

func DiffDirSimple(left, right string) (bool, []string, error)

DiffDirSimple reports whether the directories left and right differ. The second return value is a list of messages consisting of:

- xyz only in left - xyz only in right - files left/xyz and right/xyz differ (without further detail)

Comparison of difference is done strictly based on md5 checksums of the file contents, with all the caveats that entails.

NB / MAYBE-BUG: This is so simple that empty directories are ignored (since the whole thing is file-based).

Hence: *THIS IS NOT A REPLACEMENT FOR `diff -r`!*

TODO add tests! (I wrote cmd/simpledirdiff/simpledirdiff.go to "test" the function, but...)

func FileDetectContentType

func FileDetectContentType(path string) (string, error)

FileDetectContentType is a helper wrapping DetectContentType so the file doesn't need to be opened by the user.

func FindFiles

func FindFiles(base string) ([]string, error)

FindFiles recursively finds (or lists) all files under base. Directories are ignored. It's like `find base type -f`. NOTE: This *will* return "hidden" files (files starting with a dot). I'm not sure if that's desireable, but for now the caller is responsible for filtering those out if they aren't wanted.

func IsDir

func IsDir(p string) bool

IsDir returns true if p is a path to an existing directory.

func IsEmpty

func IsEmpty(p string) bool

IsEmpty returns true if p is a dir and contains no files.

func IsExist

func IsExist(p string) bool

IsExist returns true if p is a path to an existing file or directory.

func IsFile

func IsFile(p string) bool

IsFile returns true if p is a path to an existing regular file.

func LastInDir

func LastInDir(dir string) (string, error)

LastInDir returns the lexicographically last file in dir, joined to dir.

Useful in this situation: you have files in dir named like DATE-data.csv and you want your program to use the lexicographically last one of them to ensure it's using the latest file.

func MD5

func MD5(path string) (string, error)

func ReadFileLines

func ReadFileLines(p string) ([]string, error)

ReadFileLines is an error-returning version of ReadFileLinesDie. See description of ReadFileLinesDie for details.

func ReadFileLinesDie

func ReadFileLinesDie(p string) []string

ReadFileLinesDie wraps os.ReadFile with the additions of returning the lines of the file p as a string slice, and it takes care of getting rid of the final "" element caused by the final newline in the file. And, it dies if it encounters an error. This is obviously only for situations where that's appropriate, like solving puzzles.

func ReadFileNonBlankNonCommentLines

func ReadFileNonBlankNonCommentLines(p string) ([]string, error)

ReadFileNonBlankNonCommentLines is like the above ReadFileLines functions, but ignores blank lines and lines starting with "#" and "//".

func ReadFileNonBlankNonCommentLinesDie

func ReadFileNonBlankNonCommentLinesDie(p string) []string

ReadFileNonBlankNonCommentLinesDie is a panicing version of ReadFileNonBlankNonCommentLines.

func ReadFileSingleLine

func ReadFileSingleLine(p string) (string, error)

ReadFileSingleLine reads a single line file. If p is not a single line file (or empty), an error is returned.

Given an empty file, an empty string is returned.

func ReadFileSingleLineDie

func ReadFileSingleLineDie(p string) string

ReadFileSingleLineDie is ReadFileLinesDie with a guarantee that only one line is read. It's perhaps mostly useful for Advent of Code.

func Touch

func Touch(path string) error

Touch is equivalent to the simplest use of the unix command "touch".

TODO/Q: Is there an issue with not specifying a timezone for time.Now()? (I'm guessing the answer is, "probably".)

For a deeper look into atime/mtime than is probably warranted (go only makes it "easy" to read a file's mtime, even though Chtimes updates the atime also; that's what led me to these resources):

Ctime Mtime Atime | GOLang code https://ispycode.com/GO/Files-And-Directories/Ctime-Mtime-Atime

djherbis/times: #golang file times (atime, mtime, ctime, btime) https://github.com/djherbis/times

djherbis/atime: Access Times for files #golang https://github.com/djherbis/atime

go - Is there a way to set `mtime` while preserving `atime` with the `os` module? https://stackoverflow.com/questions/55408866/

func WriteLinesToFile

func WriteLinesToFile(name string, lines []string) error

WriteLinesToFile is a wrapper around os.WriteFile that takes a slice of string (lines) instead of a []byte. It also always uses permissions 0644. It writes a final newline to the file being written (which strings.Join(lines, "\n") on its own (obviously) won't do).