README
¶
FS VTILS
Basics
This package tries to simplify file IO with golang and is heavily inspired by Bash/Linux commands like cp, mv, mkdir etc.
It provides a Path type to give additional type safety over strings. The defined methods follow the pattern:
sourcePath.Cmd(targetPath, flags...)
e.g.
fileA.Cp(fileB, 'f')
which copies the file from path fileA to fileB. The f flag (force) tells the command to remove anything existing at fileB, if needed.
Full documentation is available on godoc.org
Disclaimer
The author of this software is not responsible for any disadvantages arising from its usage. The author cannot be obligated to control usage of this software, i.e. for criminal activities or accidental damage caused by the use of this software on any system.
Troubleshooting
In the case you encounter an error or any unexpected behaviour, feel free to open an issue or send me a message.
Roadmap
- Further testing (current status: 85% of commands successfully tested)
- Improve this README
Documentation
¶
Overview ¶
Package fsv aims to simplify file IO and interaction with the file system. It revolves around the main type declared, which is fsv.Path and offers a lot of methods, to easily retrieve information or do manipulations on the fs. The names of methods are largely inspired by bash/Linux commands, such as cp, mv or mkdir. Furthermore, some methods are slightly overloaded in the sense that their behaviour can be modified by passing flags.
Index ¶
- Variables
- func IsFSVErr(e error) bool
- func ResetBufferSize()
- func SetBufferSize(n uint)
- type Error
- type ErrorList
- type Path
- func (p Path) AppendBytes(bytes []byte) error
- func (p Path) AppendLines(lines []string) error
- func (p Path) AppendRunes(runes []rune) error
- func (p Path) AppendString(contents string) error
- func (p Path) Atime() (time.Time, error)
- func (p Path) Base() Path
- func (p Path) BaseStr() string
- func (p Path) Btime() (time.Time, error)
- func (p Path) Chmod(mode os.FileMode) error
- func (p Path) Chown(uid, gid int) error
- func (p Path) CountLines() (int, error)
- func (p Path) CountRunes() (int, error)
- func (p Path) Cp(target Path, flags ...rune) error
- func (p Path) Ctime() (time.Time, error)
- func (p Path) Dir() Path
- func (p Path) DirStr() string
- func (p Path) Dissect() []Path
- func (p Path) DissectStr() []string
- func (p Path) Exists() bool
- func (p Path) Extend(x Path) Path
- func (p Path) ExtendStr(x string) Path
- func (p Path) Follow() (Path, error)
- func (p Path) HasHash(h hash.Hash64) (bool, error)
- func (p Path) Hash() (hash.Hash64, error)
- func (p Path) Info() (os.FileInfo, error)
- func (p Path) IsDir() (bool, error)
- func (p Path) IsFile() (bool, error)
- func (p Path) IsHidden() bool
- func (p Path) IsOsFile() bool
- func (p Path) IsSymlink() (bool, error)
- func (p Path) IsVisible() bool
- func (p Path) Ln(target Path, flags ...rune) error
- func (p Path) Ls() (PathList, error)
- func (p Path) MkDir(flags ...rune) error
- func (p Path) MkFile(perm os.FileMode, flags ...rune) error
- func (p Path) MkWatch() (*fsnotify.Watcher, error)
- func (p Path) Mode() (os.FileMode, error)
- func (p Path) Mtime() (time.Time, error)
- func (p Path) Mv(target Path, flags ...rune) error
- func (p Path) Owner(os.FileMode) (*user.User, error)
- func (p Path) ReadBytes() ([]byte, error)
- func (p Path) ReadLines() ([]string, error)
- func (p Path) ReadRunes() ([]rune, error)
- func (p Path) ReadString() (string, error)
- func (p Path) RelativeTo(dir Path) (Path, error)
- func (p Path) RelativeToStr(dir string) (Path, error)
- func (p Path) Rm(flags ...rune) error
- func (p1 Path) SameContentsAs(p2 Path) (bool, error)
- func (p1 Path) SameHashAs(p2 Path) (bool, error)
- func (p1 Path) SameInfoAs(p2 Path) (bool, error)
- func (p Path) SinceAccess() (time.Duration, error)
- func (p Path) SinceBirth() (time.Duration, error)
- func (p Path) SinceChange() (time.Duration, error)
- func (p Path) SinceMod() (time.Duration, error)
- func (p Path) Size() (int64, error)
- func (p Path) Split() (dir, base Path)
- func (p Path) SplitStr() (dir, base string)
- func (p Path) Target() (Path, error)
- func (p Path) Times() (atime, ctime, mtime, btime time.Time, err error)
- func (p Path) Walk(walkFn filepath.WalkFunc) error
- func (p Path) WriteBytes(bytes []byte) error
- func (p Path) WriteLines(lines []string) error
- func (p Path) WriteRunes(runes []rune) error
- func (p Path) WriteString(contents string) error
- type PathList
- func (ps PathList) Common() Path
- func (ps PathList) Dir() (Path, error)
- func (ps PathList) Dirs() []Path
- func (ps PathList) Each(fn func(Path) error) error
- func (ps PathList) Filter(pred func(Path) bool) PathList
- func (ps PathList) Infos() ([]os.FileInfo, error)
- func (ps PathList) Names() []string
- func (ps PathList) String() string
Constants ¶
This section is empty.
Variables ¶
var ( FILE_OPERATION = Error{no_FILE_OPERATION, _PATH_EMPTY, _FLAG_EMPTY} INVALID_FLAG = Error{no_INVALID_FLAG, _PATH_EMPTY, _FLAG_EMPTY} MISSING_OS_SUPPORT = Error{no_MISSING_OS_SUPPORT, _PATH_EMPTY, _FLAG_EMPTY} MISSING_REC_FLAG = Error{no_MISSING_REC_FLAG, _PATH_EMPTY, _FLAG_EMPTY} MISSING_TARGETDIR = Error{no_MISSING_TARGETDIR, _PATH_EMPTY, _FLAG_EMPTY} NO_COMMON_DIR = Error{no_NO_COMMON_DIR, _PATH_EMPTY, _FLAG_EMPTY} OCCUPIED_PATH = Error{no_OCCUPIED_PATH, _PATH_EMPTY, _FLAG_EMPTY} UNKNOWN_ERR = Error{no_UNKNOWN_ERR, _PATH_EMPTY, _FLAG_EMPTY} )
These are the error prototypes
Functions ¶
func ResetBufferSize ¶
func ResetBufferSize()
ResetBufferSize restores a buffersize of 65536 bytes (64KiB)
func SetBufferSize ¶
func SetBufferSize(n uint)
SetBufferSize sets the buffersize for operations like reading, writing and copying.
Types ¶
type Error ¶
Error is the type for any error generated by this package. If an error returned by functions from this package are not of type fsv.Error, it has been fast-forwarded.
type ErrorList ¶
type ErrorList []error
ErrorList is a specific kind of error for the PathList.Each() method. If it does not encounter an error, it returns nil. Otherwise it return a slice of errors, matching with the indices of the Paths in PathList.
type Path ¶
type Path string
Path is the main type of this package. It provides additional type safety over the usage of strings as paths and anything revolving around paths and files (inodes) can be defined as a method on the new type.
func (Path) AppendBytes ¶
AppendBytes appends a []rune to the file located at p.
func (Path) AppendLines ¶
AppendLines appends a []string to the file located at p.
func (Path) AppendRunes ¶
AppendString appends a []byte to the file located at p.
func (Path) AppendString ¶
AppendString appends a string to the file located at p.
func (Path) Atime ¶
Atime returns the access time of a file. The access time of a file is updated when a file is opened.
func (Path) Base ¶
Base returns only the last part of a string, e.g.:
- Path("/Users/admin/Documents").Base() == Path("Documents")
func (Path) Btime ¶
Btime returns the birth time of a file. Birth time of a file is never updated. Supported only on Windows, NetBSD, FreeBSD and Darwin (macOS).
func (Path) CountLines ¶
CountLines returns the amount of Newline-Characters ('\n') found in a file. This involves reading the file and ranging over its contents. Performance might be suboptimal.
func (Path) CountRunes ¶
CountRunes returns the length the file contents converted to a rune-slice. This involves opening the file and converting its contents to an intermittent string. Performance might be suboptimal.
func (Path) Cp ¶
Cp creates a file at target and writes the contents of p to it. Allowed flags:
- d (dereference): Copies the contents of a symlinks target instead of the link itself. Dereferencing happens recursively until a non-symlink is found for copying.
- f (force): Removes existing files/directories at target.
- p (parent): Creates any dirs necessary to accomodate target.
- r (recursive): Copies directories, including any files, subdirectories etc.
Failed attempts of writing to the target will trigger deletion of the target. If deletion fails, a panic will occur. Be aware that the combination of the d and r flags may lead to a circular structure, eventually causing a stack and/or drive overflow!
func (Path) Ctime ¶
Ctime returns the change time of a file. The change time of a file is updated when the file is modified, including metadata e.g. permissions, owner etc. Not supported on Plan9 or Windows version older than (and including) XP.
func (Path) Dir ¶
Dir returns all parts of a string except the base:
- Path("/Users/admin/Documents").Base() == Path("/Users/admin")
func (Path) DissectStr ¶
DissectStr is like Dissect, but returns a []string.
func (Path) Follow ¶
Follow tries to read the path that a symlink residing at p points to. If the symlink at p is linked to a relative path (instead of an absolute one), the returned Path will also be relative and methods called on it will fail, unless your program executes in the same directory where p is located.
func (Path) Hash ¶
Hash returns a hash.Hash64 after FNV-1a algorithm for the contents of the file located at p.
func (Path) IsFile ¶
IsFile returns wether the file sitting at p is a regular file. (i.e. not a link, directory etc.)
func (Path) IsOsFile ¶
IsOsFile checks the basename of p to determine wether the file located at p is generated by the operating system or not. Filenames that lead to a true return value:
- .DS_Store
- __MACOSX
- desktop.ini
- Thumbs.db
- thumbs.db
func (Path) Ln ¶
Ln creates a symlink at target, pointing to p. Allowed flags:
- f (force): Removes existing files/directories at target.
- h (hardlink): Creates a hardlink instead of a symlink.
- p (parent): Creates any dirs necessary to accomodate target.
func (Path) MkDir ¶
MkDir creates a directory at p. Allowed flags:
- f (force): Removes existing files/directories at p.
- p (parent): Creates any dirs necessary to accomodate target.
func (Path) MkFile ¶
MkFile creates a (regular) file at p. Allowed flags:
- f (force) : Removes existing files/directories at p.
- p (parent): Creates any dirs necessary to accomodate target.
func (Path) MkWatch ¶
MkWatch returns a Watch from the fsnotify Package, which can be used to efficiently receive notifications for any events occuring on the specified file or directory. For further information refer to the fsnotify documentation.
func (Path) Mtime ¶
Mtime returns the mod time of a file. The mod time of a file is updated when the file is modified, excluding metadata. (Contents modification only)
func (Path) Mv ¶
Mv moves (renames) the file at p to target. Allowed flags:
- f (force): Removes existing files/directories at target.
- p (parent): Creates any dirs necessary to accomodate target.
- r (recursive): Moves directories, including any files, subdirectories etc.
func (Path) ReadLines ¶
ReadLines reads the contents of the file at p and returns them as a []string.
func (Path) ReadString ¶
ReadString reads the contents of the file at p and returns them as a string.
func (Path) RelativeTo ¶
RelativeTo returns the Path that p has relative to dir.
func (Path) RelativeToStr ¶
RelativeToStr is like RelativeTo, but takes a string as argument instead of a Path.
func (Path) Rm ¶
Rm removes the file located at p. Allowed flags:
- r (recursive): Deletes directories, including any files, subdirectories etc.
- w (wipe): Before deleting, the underlying inode is overwritten with an empty byte-slice
func (Path) SameContentsAs ¶
SameContentsAs checks wether two file have the same content, going byte-by-byte and returning early if possible.
func (Path) SameHashAs ¶
SameHashAs checks wether p1 and p2 bath have the same.
func (Path) SameInfoAs ¶
SameInfoAs compares the files located at p1 and p2 by their os.FileInfo.
Attention: Windows compares by path in this case, so two files pointing at the same inode may erroneously be reported as not the same file.
func (Path) SinceAccess ¶
SinceAccess return the time.Duration since the access time has changed.
func (Path) SinceBirth ¶
SinceBirth return the time.Duration since the birth time has changed.
func (Path) SinceChange ¶
SinceChange return the time.Duration since the change time has changed.
func (Path) Target ¶
Target tries to recursviely follow a symlink until a non-symlink is found. The same restrictions on relative symlinks as mentioned in the documentation for Follow apply.
func (Path) Times ¶
Times returns access, change, modification and birth time (in this order) of the file at p. On Plan9 or Windows versions older than and including XP change times cannot be retrieved. Birth times can only be retrieved on Windows, FreeBSD, NetBSD and Darwin (macOS). If a time cannot be retrieved, this method will return Epoch (1970-01-01) for that value.
func (Path) WriteBytes ¶
WriteBytes (over)writes the contents of the file located at p with a []byte.
func (Path) WriteLines ¶
WriteLines (over)writes the contents of the file located at p with a []string. This includes a trailing newline character.
func (Path) WriteRunes ¶
WriteRunes (over)writes the contents of the file located at p with a []rune.
func (Path) WriteString ¶
WriteString (over)writes the contents of the file located at p with a string.
type PathList ¶
type PathList []Path
PathList is a collection of paths, typically retrieved via Path.Ls().
func (PathList) Each ¶
Each applies a function to each Path in a PathList. Encountered errors accumulate and do not abort subsequent actions.
func (PathList) Filter ¶
Filter removes all Paths from a PathList, that do not satisfy the given predicate.
Source Files