README
¶
go-fileutils
A collection of filesystem utilities for Go
Package fileutils is a collection of filename manipulation and filesystem
utilities including directory traversal with symlinks support, finding file and
folders with extended glob pattern, and atomic file operations.
To help support non-unix platforms, it also includes ad set of functions that are similar to those found in package "path/filepath", but but using '/' as path separator, and preserving trailing separator for directory filenames.
Installation
go get github.com/maargenton/go-fileutils
Key features
Filenames with consistent '/' separator
All unix platforms use '/' as path separator, and while windows recommends using
\\, it also accepts paths with regular forward slash as path separators. For
that reason, this package takes the stance of always using forward slash as path
separator. The immediate benefit is that all relative paths become platform
agnostic, freeing the cross-platform client code from having to deal with
special cases for windows.
The notion of absolute path remains different across platforms, but they can still be manipulated safely and consistently without having to deal with platform-specific special cases in most instances.
Atomic file operations
fileutils.Write()atomically creates or replaces the destination file with the content written into the io.Writer passed to the closure. This guaranties that readers of that file will never see an incomplete or partially updated content.fileutils.Read()reads the content of a file through the io.Reader passed to the closure.fileutils.OpenTemp()creates and opens a temporary file, in the same location and with the same extension as the target file. The resulting file is guarantied to not previously exists, and therefore never steps onto another file.
Filename manipulation
fileutils.RewriteFilename()is a single function that lets you transform a filename in many common ways, like replacing either the extension or the containing directory, or inserting a prefix or suffix onto the basename of the file.fileutils.ExpandPath()andfileutils.ExpandPathRelative()expand an relative or absolute path into an absolute path, handling~/and environment variable expansion, using ether$(pwd)or a givenbasepathas base path.fileutils.Clean(),fileutils.Rel()andfileutils.Join()are equivalent to theirfilepathcounterpart, but preserve any trailing path separator, commonly used to indicate a directory. In addition,fileutils.Join()properly handles the case where one of the elements is an absolute path, resulting in an absolute path with all preceding elements ignored.
Filesystem scanning and globing
dir.Walk() implements an enhanced version of filepath.WalkDir() that
follows symlinks safely and adds some flexibility in the way paths are reported.
dir.Glob() and dir.Scan() are convenient functions to locate and
enumerate files matching a particular pattern. The pattern is specified as an
extended glob pattern that can match deep subdirectories and alternative
patterns:
- Extended glob patterns always use
/as path separator and\as escape character, regardless of the OS native filename format. - Extended glob patterns are interpreted as a sequence of one or more path fragments. Each path fragment can be matched against a literal sequence of characters or a glob pattern.
*matches zero or more occurrences of any character within a path fragment?matches one occurrence of any character within a path fragment[<range>]: matches one occurrence of any listed character within a path fragment{foo,bar}matches one occurrence of eitherfooorbarwithin a path fragment**/allows the subsequent fragment to be matched anywhere within the directory tree. It should always be followed by another fragment matching expression.
Symbolic links are followed safely as needed, emitting an ErrRecursiveSymlink
each time a filesystem location is visited again.
Examples
src/**/*_test.{c,cc,cpp}: Fromsrc, find all files in any sub-directory with an_testsuffix and a.c,.ccor.cppextension.src/**_test.cppis that same assrc/*_test.cpp; the double star is interpreted as two consecutive matches of zero or more.
Sub-process execution
popen.Command is an additional layer of abstraction over exec.Command aimed at
simplifying common uses where the output of the process is captured or
redirected. Unlike exec.Command, all the details of the command to run and
what to do with its outputs are captured in public fields of the Command
structure. The output streams, stdout and stderr, can be returned as a string,
redirected to a file or stream-processed through an io.Reader. If the process
is executed successfully but returns a non-zero exit status, the returned error
is an exec.ExitError that contains the actual status code.
The behavior of stdout and stderr is controlled by 3 similar variables:
- When
WriteStdoutToFileis set to the path of a destination file for the content of the command stdout,DiscardStdoutis ignored and the returned stdout string is always empty. If needed, the output of the command can be read back from that file. - When
StdoutReaderis set, the raw output of the command is still captured and returned in the stdout string, unlessDiscardStdoutis set totrue. WriteStdoutToFileandStdoutReadercan both be set, in which case the output of the command is sent to both and the returned stdout string is empty.
Except for StdoutReader and StderrReader which are most likely stateful, the
command object is stateless and can potentially be Run() multiple times,
concurrently.
In addition, on unix platforms, popen.Command can handle graceful shutdown of
the child process when the context becomes done. When a ShutdownGracePeriod is
specified, a shutdown signal is sent to the child process (SIGINT by default),
and the process is forcibly killed only if it has not exited by the end of the
grace period. The child process is also assigned its own process group by
default, and signals are sent to the entire group, unless NoProcessGroup
options is specified -- this avoids waiting forever issues linked with a child
process exiting while its descendants remain alive because they didn't get the
signal.
Documentation
¶
Overview ¶
Package fileutils is a collection of filename manipulation and filesystem utilities including directory traversal with symlinks support, finding file and folders with extended glob pattern, and atomic file operations.
To help support non-unix platforms, it also includes ad set of functions that are similar to those found in package "path/filepath", but but using '/' as path separator, and preserving trailing separator for directory filenames.
Index ¶
- Variables
- func Abs(path string) (string, error)
- func Base(path string) string
- func Clean(input string) string
- func Dir(path string) string
- func EvalSymlinks(path string) (string, error)
- func Exists(path string) bool
- func ExpandPath(input string) (output string, err error)
- func ExpandPathRelative(input, basepath string) (output string, err error)
- func Ext(path string) string
- func IsAbs(path string) bool
- func IsDir(path string) bool
- func IsDirectoryName(path string) bool
- func IsFile(path string) bool
- func IsPathSeparator(c uint8) bool
- func Join(elem ...string) string
- func OpenTemp(filename, suffix string) (f *os.File, err error)
- func ReadFile(filename string, reader func(r io.Reader) error) error
- func Rel(basepath, targetpath string) (string, error)
- func RewriteFilename(input string, opts *RewriteOpts) string
- func Split(path string) (dir, base string)
- func ToNative(path string) string
- func ToSlash(path string) string
- func Touch(filenames ...string) (err error)
- func VolumeName(path string) string
- func WriteFile(filename string, writer func(w io.Writer) error) error
- type ReaderFunc
- type RewriteOpts
- type WalkFunc
- type WriterFunc
Constants ¶
This section is empty.
Variables ¶
var OSSeparator = os.PathSeparator
OSSeparator is the os specific path separator, usually either '/' on unix latforms or '\\` on windows.
var Separator = '/'
Separator is a fixed default path separator and is always '/'
Functions ¶
func Abs ¶ added in v0.6.1
Abs is equivalent to `filepath.Abs()`, but preserves any trailing path separator.
func Clean ¶
Clean returns a lexically equivalent path, using '/' as separator, removing any discardable '/' or "./", and collapsing any intermediate "../". It preserves a trailing separator for directory names.
func EvalSymlinks ¶ added in v0.6.1
EvalSymlinks is equivalent to `filepath.EvalSymlinks()`, but preserves any trailing path separator.
func ExpandPath ¶
ExpandPath is similar to ExpandPathRelative with an empty `basepath`; relative paths are expanded relative to `$(pwd)`.
func ExpandPathRelative ¶
ExpandPathRelative returns the absolute path for the given input, expanding environment variable and handling the special case `~/` referring to the current user home directory. If the resulting path after variable expansion is relative, it is expanded relative to `basepath`. If the resulting path is still relative, it is expanded relative to `$(pwd)`. The function returns and error if one of the underlying calls fails (getting user home or process working directory path).
func IsDirectoryName ¶ added in v0.6.1
IsDirectoryName returns true is the input can be inferred to be a directory based on its name only, without having to access the filesystem to check. This include paths with trailing separator, an empty path that resolved to "./", or paths the end with either a "." or ".." path fragment that are always directories.
func IsPathSeparator ¶ added in v0.6.1
IsPathSeparator returns true for runes that are either the default path separator or the os native path separator.
func Join ¶
Join joins multiple path fragments into a single path, preserving a trailing separator if any, and handling any intermediate absolute path as the new root of the resulting path.
func OpenTemp ¶
OpenTemp returns the name and handle to a newly created temporary file, guarantied to not previously exist, located in the same directory as the specified file.
func ReadFile ¶
ReadFile opens a file for reading ans passes if to the provided reader for loading. The file is closed when the function returns
func RewriteFilename ¶
func RewriteFilename(input string, opts *RewriteOpts) string
RewriteFilename transforms a filename according the the specified options and can change dirname, basename, extension or append / prepend a fragment to the basename.
func Split ¶ added in v0.6.1
Split splits the last path fragment of `path` from everything that precedes, so that path = dir+file.
func ToSlash ¶ added in v0.6.1
ToSlash converts path into a path using '/' as path separator, consistent with other functions in this package.
func Touch ¶
Touch create a new files or update files mtime at the specified locations. If the destination directory does not exist, it is created as well. An errors is returned if any destination directory does not exist and cannot be created, or any of the specified files cannot be opened.
func VolumeName ¶ added in v0.6.1
VolumeName returns the name of the volume if specified in path. The result is always empty on unix platforms.
Types ¶
type ReaderFunc ¶
ReaderFunc is a function type that implements io.Reader
type RewriteOpts ¶
type RewriteOpts struct {
Dirname string // Replace the path with the specified dirname
Extname string // Replace the file extension with the specified extname
Prefix string // Prefix to prepend on the basename
Suffix string // Suffix to append on the basename
}
RewriteOpts contains the options to apply to RewriteFilename to transform the input filename
type WalkFunc ¶ added in v0.6.1
type WalkFunc = fs.WalkDirFunc
WalkFunc is the type of the function called by Walk to visit each file or directory. Since all walk functions in this package are based on go 1.16 WalkDir(), it uses `fs.DirEntry` as second argument to capture the file information.
Source Files
Directories