fayl

package
v1.35.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 22, 2026 License: MIT Imports: 17 Imported by: 2

Documentation

Overview

fayl provides numerious utilities pertaining to the creation, destruction, serialization, and manipulation of files and their corresponding paths on the filesystem. The example below describes a marshalling of a single object given a constructed Path from its given folder, filename, and Suffix.

Example: 

import (

	"github.com/Polshkrev/gopolutils"
	"github.com/Polshkrev/gopolutils/fayl"

)

func main() {
	var settings *settings.Settings // Just an example object; no settings package exists within this package.
	var except *gopolutils.Except
	settings, except = fayl.ReadObject(fayl.PathFromParts("./settings", "settings", fayl.Json))
	if except != nil {
		panic(except)
	}
}

Or as a more succinct example: 

import (

	"github.com/Polshkrev/gopolutils"
	"github.com/Polshkrev/gopolutils/fayl"

)

func main() {
	var settings *settings.Settings = gopolutils.Must(fayl.ReadObject(fayl.PathFromParts("./settings", "settings", fayl.Json)))
}

Each of the file operations are concurrent, although not explicitly concurrent-safe.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Archive added in v1.28.0 

func Archive(destination *Path, files ...*Entry) *gopolutils.Exception

Archive a given variadic group of file Entry to a given destination Path. If the Suffix of the source Path can not be obtained, gopolutils.KeyError is returned. If the file can not be read, an gopolutils.IOError is returned. If the file can not be written, an gopolutils.IOError is returned.

func Extract added in v1.28.0 

func Extract(source, destination *Path) *gopolutils.Exception

Extract an either a `.tar`, `.tar.gz`, or `.zip` archive based on a given source Path. If the Suffix of the source Path can not be obtained, gopolutils.KeyError is returned. If the file can not be read, an gopolutils.IOError is returned. If the file can not be written, an gopolutils.IOError is returned.

func Gunzip added in v1.27.0 

func Gunzip(content []byte) ([]byte, *gopolutils.Exception)

Gzip a given slice of bytes. If a gzip.Reader can not be acquired, an gopolutils.IOError is returned with a nil data pointer. If the data can not be read, an gopolutils.IOError is returned with a nil data pointer.

func Gzip added in v1.27.0 

func Gzip(content []byte) ([]byte, *gopolutils.Exception)

Gzip a given slice of bytes. If the data can not be written, an gopolutils.IOError is returned with a nil data pointer. If the gzip.Writer can not be closed, an gopolutils.IOError is returned with a nil data pointer.

func Read added in v1.4.0 

func Read(filePath *Path) ([]byte, *gopolutils.Exception)

Read the raw contents of a file. Returns a byte slice representing the raw file content. If the file can not be read, an gopolutils.IOError is returned with a nil data pointer.

func ReadList added in v1.4.0 

func ReadList[Type any](filePath *Path) (collections.View[Type], *gopolutils.Exception)

Read a file as a view into a collection of objects. Returns a view into a collection of a file containing a list of data. If the file can not be read, an gopolutils.IOError is returned with a nil data pointer. If the data can not be marshalled, an gopolutils.IOError is returned with a nil data pointer. In addition, if the file type can not be evaluated, an gopolutils.Exception is returned with a nil data pointer.

func ReadObject added in v1.4.0 

func ReadObject[Type any](filePath *Path) (*Type, *gopolutils.Exception)

Read a file as an object. Returns a pointer to an object of data from a file. If the file can not be read, an gopolutils.IOError is returned with a nil data pointer. If the data can not be marshalled, an gopolutils.IOError is returned with a nil data pointer. In addition, if the file type can not be evaluated, an gopolutils.Exception is returned with a nil data pointer.

func StringFromSuffix added in v1.20.0 

func StringFromSuffix(suffix Suffix) (string, *gopolutils.Exception)

Obtain a string from a Suffix. Returns a string obtained from a mapping of suffixes to strings. If the path suffix is not defined in the mapping, a gopolutils.KeyError is returned with an empty string.

func TarFolder added in v1.28.0 

func TarFolder(destination *Path, files ...*Entry) *gopolutils.Exception

Zip a given variadic group of Entry into a destination tar Path. If the destination Path already exists, a gopolutils.FileExistsError is returned. If the file can not be created, an gopolutils.OSError is returned. If the tar header can not be created or written, an gopolutils.IOError is returned. If a handle to any of the given files can not be obtained, an gopolutils.OSError is returned. If any of the files can not be copied, an gopolutils.IOError is returned.

func Untar added in v1.28.0 

func Untar(source, destination *Path) *gopolutils.Exception

Unzip a tar file from a given source Path to a given destination Path. If the source Path does not exist, a gopolutils.FileNotFoundError is returned. If the destination Path already exists, a gopolutils.FileExistsError is returned. If the destination can not be created, an gopolutils.OSError is returned. If source file can not be opened, an gopolutils.OSError is returned. If the destination path is not valid, a gopolutils.ValueError is returned. If any of the files can not be opened, an gopolutils.IOError is returned. If any of the files can not be copied, an gopolutils.IOError is returned.

func Unzip added in v1.28.0 

func Unzip(source, destination *Path) *gopolutils.Exception

Unzip a folder from a given source Path to a given destination Path. If the source Path does not exist, a gopolutils.FileNotFoundError is returned. If the destination Path already exists, a gopolutils.FileExistsError is returned. If file can not be opened, a gopolutils.ValueError is returned. If the destination path is not valid, a gopolutils.ValueError is returned. If a handle to the any of the read files can not be obtained, an gopolutils.OSError is returned. If any of the files can not be opened, an gopolutils.IOError is returned. If any of the files can not be copied, an gopolutils.IOError is returned.

func Write added in v1.14.0 

func Write(filePath *Path, content []byte) *gopolutils.Exception

Write a slice of bytes to a file. If the file can not be written, an gopolutils.IOError is returned.

func WriteList added in v1.14.0 

func WriteList[Type any](filePath *Path, content collections.View[Type]) *gopolutils.Exception

Write a view of a type into a file. If the file can not be written, an gopolutils.IOError is returned. Alternatively, if the data can not be marshalled, an gopolutils.IOError is returned. In addition, if the file type can not be evaluated, an gopolutils.OSError is returned.

func WriteObject added in v1.14.0 

func WriteObject[Type any](filePath *Path, content *Type) *gopolutils.Exception

Write a file as an object. If the file can not be written, an gopolutils.IOError is returned. Alternatively, if the data can not be marshalled, an gopolutils.IOError is returned. In addition, if the file type can not be evaluated, an gopolutils.OSError is returned.

func ZipFolder added in v1.28.0 

func ZipFolder(destination *Path, files ...*Entry) *gopolutils.Exception

Zip a given variadic group of Entry to a given destination Path. If the given destination Path does not exist, a gopolutils.FileExistsError is returned. If the file can not be created, an gopolutils.OSError is returned. If a handle to any of the given files can not be obtained, an gopolutils.IOError is returned. If any of the files can not be added to the zip archive, an gopolutils.IOError is returned.

Types

type Directory added in v1.23.0 

type Directory struct {
	// contains filtered or unexported fields
}

Representation of a directory containing file entries.

func NewDirectory added in v1.26.0 

func NewDirectory(root *Path) *Directory

Construct a new directory from its given root Path. Returns a new Directory from its given root Path.

func (*Directory) Append added in v1.26.0 

func (directory *Directory) Append(entry *Entry)

Append a directory entry to the directory.

func (Directory) At added in v1.26.0 

func (directory Directory) At(index gopolutils.Size) (**Entry, *gopolutils.Exception)

Obtain a pointer to the Entry at a given gopolutils.Size index. Returns a pointer to the Entry at the given index. If the given index is greater than the size of the collection, an gopolutils.OutOfRangeError is returned with a nil data pointer.

func (Directory) ByteSize added in v1.33.0 

func (directory Directory) ByteSize() Size

Obtain the byte size of the directory. Returns a Size of each of the entries in the directory.

func (Directory) Collect added in v1.26.0 

func (directory Directory) Collect() []*Entry

Collect the directory's entries into a slice. Returns a slice of Entry.

func (Directory) Copy added in v1.26.0 

func (directory Directory) Copy(destination *Directory) *gopolutils.Exception

Copy each of the entries in the directory to a given destination directory. If the given destination is determined to be empty, the given directory is extended with the entries from the source directory. If the destination entry does not initially exist and subsequently can not be created, an gopolutils.IOError is returned.

func (Directory) Create added in v1.26.0 

func (directory Directory) Create() *gopolutils.Exception

Persist each of the entries on the filesystem. If the entry already exists on the filesystem, a gopolutils.FileExistsError is returned. If the entry can not be created, an gopolutils.IOError is returned.

func (Directory) Delete added in v1.26.0 

func (directory Directory) Delete() *gopolutils.Exception

Delete each of the entries within the directory. If the entry does not exist on the filesystem, a gopolutils.FileNotFoundError is returned. If the os.FileInfo of the entry can not be obtained, an gopolutils.IOError is returned. If the entry is a file and the file can not be removed, an gopolutils.IOError is returned. If the entry is a directory and the directory can not be removed, an gopolutils.IOError is returned.

func (*Directory) Extend added in v1.26.0 

func (directory *Directory) Extend(entries collections.View[*Entry])

Append a collections.View of Entry to the directory.

func (Directory) IsEmpty added in v1.26.0 

func (directory Directory) IsEmpty() bool

Determine if the directory is empty. Returns true if the directory's size is equal to zero or if the underlying data is nil, else false.

func (Directory) Items added in v1.26.0 

func (directory Directory) Items() *[]*Entry

Access a pointer to a slice of the entries within the directory. Returns a mutable pointer to the underlying entries within the directory.

func (*Directory) Read added in v1.26.0 

func (directory *Directory) Read() *gopolutils.Exception

Recursively append each of the child entry paths to the directory. If the entries can not be obtained, an gopolutils.OSError is returned.

func (*Directory) Remove added in v1.26.0 

func (directory *Directory) Remove(index gopolutils.Size) *gopolutils.Exception

Remove an Entry at the given gopolutils.Size index. If the given index is greater than the size of the collection, an gopolutils.OutOfRangeError is returned.

func (Directory) Root added in v1.26.0 

func (directory Directory) Root() *Path

Obtain the root of the directory. Returns the root of the directory.

func (Directory) Size added in v1.26.0 

func (directory Directory) Size() gopolutils.Size

Obtain the size of the directory. Returns a gopolutils.Size of the directory.

func (Directory) String added in v1.32.0 

func (directory Directory) String() string

Represent the directory as a string. Returns a representation of the directory as a string.

type Entry added in v1.23.0 

type Entry struct {
	// contains filtered or unexported fields
}

Representation of a file on the filesystem.

func NewEntry added in v1.23.0 

func NewEntry(path *Path) *Entry

Construct a new file entry based on a given Path. The path and therefore corresponding entry may be ephemeral. Returns a pointer to a new entry with a given path.

func (Entry) ByteSize added in v1.33.0 

func (entry Entry) ByteSize() Size

Obtain the byte size of the entry. Returns a Size of the entry. If os.Stat fails, the method panics.

func (Entry) Content added in v1.25.0 

func (entry Entry) Content() safe.Collection[byte]

Obtain the contents of the file. This method does not open a file. Returns the byte content stored in the file entry.

func (Entry) Copy added in v1.23.0 

func (entry Entry) Copy(destination *Entry) *gopolutils.Exception

Copy an entry into a given destination. After the copy has been completed on the filesystem, the given internal content of the destination entry is set to the internal content of the original entry. If the destination entry does not initially exist and subsequently can not be created, an gopolutils.IOError is returned.

func (Entry) Create added in v1.23.0 

func (entry Entry) Create() *gopolutils.Exception

Generic dispatch creation method. If the entry already exists on the filesystem, a gopolutils.FileExistsError is returned. If the entry can not be created, an gopolutils.IOError is returned.

func (Entry) Is added in v1.23.0 

func (entry Entry) Is(kind EntryType) bool

Determine if the entry is of a given type. Returns true if the entry is of the given type, else false.

func (Entry) IsEmpty added in v1.32.0 

func (entry Entry) IsEmpty() bool

Determine if the entry is empty. Returns true if the internal content of the entry is empty, else false.

func (Entry) MakeDirectory added in v1.23.0 

func (entry Entry) MakeDirectory() *gopolutils.Exception

Create a directory on the filesystem. If the entry already exists on the filesystem, a gopolutils.FileExistsError is returned. If the directory can not be created, an gopolutils.IOError is returned.

func (Entry) Path added in v1.23.0 

func (entry Entry) Path() *Path

Obtain the Path location of the file entry. Returns a mutable pointer to the internal path location of the file entry.

func (*Entry) Read added in v1.23.0 

func (entry *Entry) Read() *gopolutils.Exception

Read a file on the filesystem into the internal content of the entry. If the entry does not exist on the filesystem, a gopolutils.FileNotFoundError is returned.

func (Entry) Remove added in v1.23.0 

func (entry Entry) Remove() *gopolutils.Exception

Generic dispatch removal method. If the entry does not exist on the filesystem, a gopolutils.FileNotFoundError is returned. If the os.FileInfo of the entry can not be obtained, an gopolutils.IOError is returned. If the entry is a file and the file can not be removed, an gopolutils.IOError is returned. If the entry is a directory and the directory can not be removed, an gopolutils.IOError is returned.

func (Entry) RemoveDirectory added in v1.23.0 

func (entry Entry) RemoveDirectory() *gopolutils.Exception

Remove a directory on the filesystem. If the entry does not exist on the filesystem, a gopolutils.FileNotFoundError is returned. If the directory is not a directory, a gopolutils.NotADirectoryError is returned. If the directory can not be removed, an gopolutils.IOError is returned.

func (Entry) RemoveFile added in v1.23.0 

func (entry Entry) RemoveFile() *gopolutils.Exception

Remove a file on the filesystem. If the entry does not exist, a gopolutils.FileNotFoundError is returned. If the entry is not a file, an gopolutils.IsADirectoryError is returned. If the file can not be removed, an gopolutils.IOError is returned.

func (*Entry) SetContent added in v1.23.0 

func (entry *Entry) SetContent(content safe.Collection[byte])

Set the content of the file entry.

func (*Entry) SetPath added in v1.23.0 

func (entry *Entry) SetPath(path *Path)

Set the path of the file entry.

func (*Entry) SetType added in v1.23.0 

func (entry *Entry) SetType(kind EntryType)

Set the type of the file entry.

func (Entry) Size added in v1.32.0 

func (entry Entry) Size() gopolutils.Size

Obtain the size of the entry. Returns a gopolutils.Size of the entry.

func (Entry) String added in v1.32.0 

func (entry Entry) String() string

Represent an entry as a string. Returns a string representation of the entry.

func (Entry) Touch added in v1.23.0 

func (entry Entry) Touch() *gopolutils.Exception

Create a file on the filesystem. If the entry already exists, a gopolutils.FileExistsError is returned. If the entry is not a file, an gopolutils.IsADirectoryError is returned. If the file can not be created, an gopolutils.IOError is returned.

func (Entry) Type added in v1.23.0 

func (entry Entry) Type() EntryType

Obtain the type of the file entry. Returns the EntryType of the file entry.

type EntryType added in v1.23.0 

type EntryType gopolutils.StringEnum

Representation of the different finite types of files. 

const (
	DirectoryType EntryType = "Directory"
	FileType      EntryType = "File"
)

type OperatingSystem added in v1.32.0 

type OperatingSystem gopolutils.StringEnum

Finite — incomplete — operating system values. 

const (
	// Windows operating system.
	Windows OperatingSystem = "windows"
	// Mac operating system.
	Mac OperatingSystem = "darwin"
	// Linux operating system.
	Linux OperatingSystem = "linux"
	// Android operating system.
	Android OperatingSystem = "android"
	// FreeBSD operating system.
	Freebsd OperatingSystem = "freebsd"
	// Representation of Apple's IOS.
	Ios OperatingSystem = "ios"
	// NetBSD operating system.
	Netbsd OperatingSystem = "netbsd"
	// OpenBSD operating system.
	Openbsd OperatingSystem = "openbsd"
)

type Path added in v1.7.0 

type Path struct {
	// contains filtered or unexported fields
}

Representation of a filesystem path.

func NewPath added in v1.7.0 

func NewPath() *Path

Construct a new filesystem path. Returns a pointer to a new path containing the current working directory. If the current working directory can not be obtained, an gopolutils.OSError is printed to standard error and the programme exits.

func PathFrom added in v1.7.0 

func PathFrom(path string) *Path

Construct a new filesystem path from a given path string. Returns a new filesystem path containing the given path.

func PathFromParts added in v1.7.0 

func PathFromParts(folderName, fileName string, fileType Suffix) *Path

Construct a new filesystem path from its given parts. The fileType parametre is the file extension without the preceding dot. Returns a new filesystem path containing the absolute path composed of the given parts. If the path suffix is not defined in `suffixToString`, a gopolutils.KeyError is printed to standard error and the programme exits.

func (Path) Absolute added in v1.7.0 

func (path Path) Absolute() (*Path, *gopolutils.Exception)

Obtain the absolute path. Returns a pointer to a new path containing the absolute filesystem path. If the absolute path can not be obtained, an gopolutils.OSError is returned with a nil data pointer.

func (*Path) Append added in v1.7.0 

func (path *Path) Append(other *Path)

Append a filesystem path to another.

func (*Path) AppendAs added in v1.7.0 

func (path *Path) AppendAs(item string)

Append a filesystem path as a string to a path object.

func (Path) Exists added in v1.7.0 

func (path Path) Exists() bool

Determine if the filesystem path exists. Returns true if the filesystem path is evaluated to exist, else false.

func (Path) Join added in v1.31.0 

func (path Path) Join(other Path) *Path

Non-destructively join a path to another. Returns a new path constucted from the original path and the operand.

func (Path) JoinAs added in v1.31.0 

func (path Path) JoinAs(other string) *Path

Non-destructively join a a path string to a path. Returns a new path constucted from the original path and the operand.

func (Path) Parent added in v1.7.0 

func (path Path) Parent() (*Path, *gopolutils.Exception)

Obtain the parent directory of the filesystem path. Returns a pointer to a new path containing the parent directory of the path. If the parent can not be obtained, an gopolutils.OSError is returned with a nil data pointer. If the path is the root of the filesystem, an gopolutils.OSError is returned with a nil data pointer.

func (Path) Root added in v1.7.0 

func (path Path) Root() (*Path, *gopolutils.Exception)

Obtain the root of the filesystem as a path. Returns a pointer to the path of the root of the filesystem. If the absolute path can not be obtained, an gopolutils.OSError is returned with a nil data pointer. If the root of the filesystem can not be obtained, an gopolutils.OSError is returned with a nil data pointer.

func (Path) String added in v1.32.0 

func (path Path) String() string

Represent a filesystem path as a string. Returns a string representation of the filesystem path.

func (Path) Suffix added in v1.7.0 

func (path Path) Suffix() (Suffix, *gopolutils.Exception)

Obtain the suffix of the filesystem path. If the string representation of the suffix is not found within the global map, a gopolutils.KeyError is returned with a None suffix value.

type Size added in v1.33.0 

type Size struct {
	// contains filtered or unexported fields
}

Representation of a file size.

func NewSize added in v1.33.0 

func NewSize(size gopolutils.Size, unit gopolutils.ByteSize) *Size

Construct a new Size based on a gopolutils.Size and a given unit. Returns a new Size based on a gopolutils.Size and a given gopolutils.ByteSize.

func SizeFromBytes added in v1.33.0 

func SizeFromBytes(size gopolutils.Size) *Size

Construct a new Size from the size in bytes. Returns a new Size based on a given size in bytes.

func (Size) IsEmpty added in v1.33.0 

func (size Size) IsEmpty() bool

Determine if the size is empty. Returns true if the size of the size is equal to zero.

func (Size) Size added in v1.33.0 

func (size Size) Size() gopolutils.Size

Obtain the size property of the size. Returns the size property of the size.

func (Size) String added in v1.33.0 

func (size Size) String() string

Represent the size as a string. Returns a string representation of the size.

func (Size) Unit added in v1.33.0 

func (size Size) Unit() gopolutils.ByteSize

Obtain the unit of the size. Returns a gopolutils.ByteSize unit of the size.

type Suffix added in v1.18.0 

type Suffix gopolutils.Enum

Representation of a file suffix i.e. ".go", ".c", ".h", et cetera. 

const (
	A Suffix = iota
	Asm
	Bat
	C
	Class
	Cpp
	Cs
	Css
	Csv
	Db
	Dll
	Exe
	Go
	Gz
	Header
	Html
	Jar
	Java
	Js
	Json
	Lib
	Log
	Md
	None
	O
	Py
	Rs
	Sh
	So
	Sql
	Tar
	Tex
	Toml
	Txt
	Xml
	Yaml
	Zip
)

func SuffixFromString added in v1.20.0 

func SuffixFromString(suffix string) (Suffix, *gopolutils.Exception)

Obtain a Suffix from a raw string. Returns a path suffix obtained from a mapping of strings to suffixes. If the path suffix is not defined in the mapping, a gopolutils.KeyError is returned with the None suffix value.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.