fs

package module
v0.0.0-...-7765c9e Latest Latest
Warning

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

 Go to latest Published: Apr 11, 2025 License: MIT Imports: 17 Imported by: 1

README 

= fs
Matt Nicholls <transientvariable@protonmail.com>
:keywords: golang,file system,fs
:experimental: true
:icons: font
:iconfont-cdn: //cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@6.1.1/css/fontawesome.min.css
:imagesdir: docs/image
:sectanchors: true
:source-highlighter: prettify
:toc: left
:toclevels: 3
:toc-title: Contents

ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

== Overview

Reusable file system components for Go.

== Installation

.Prerequisites
* The link:https://golang.org/dl/[Golang Runtime], version 1.24.x or later

[source%nowrap,bash]
----
❯ go get -u github.com/transientvariable/fs-go
----

== License
This project is licensed under the link:LICENSE[MIT License].

Documentation

Index

Constants

View Source 
const (
	ErrCtimeMismatch    = fsError("modification time occurs before creation time")
	ErrIsDir            = fsError("is a directory")
	ErrInvalidEntryType = fsError("entry type is invalid")
	ErrMtimeMismatch    = fsError("modification time is invalid")
	ErrNotDir           = fsError("not a directory")
	ErrNotFile          = fsError("not a file")
	ErrTooLarge         = fsError("too large")
)

Enumeration of errors that may be returned by file system operations.

View Source 
const (
	O_RDONLY = os.O_RDONLY
	O_WRONLY = os.O_WRONLY
	O_RDWR   = os.O_RDWR
	O_APPEND = os.O_APPEND
	O_CREATE = os.O_CREATE
	O_TRUNC  = os.O_TRUNC

	// MaxContentLen defines the maximum size in bytes for a File.
	MaxContentLen = int(^uint(0) >> 1)
)

Variables

This section is empty.

Functions

func CleanPath 

func CleanPath(fsys FS, p string) (string, error)

CleanPath cleans the path p returns a lexically valid path.

func EndsWithDot 

func EndsWithDot(fsys FS, path string) bool

EndsWithDot reports whether the final component of the path is ".".

func FileMetadata 

func FileMetadata(fsys FS, entry *Entry) (*cadre.File, error)

FileMetadata converts a file system entry and produces a cadre.File.

func Glob 

func Glob(pattern string) ([]string, error)

Glob ...

func Mkdir 

func Mkdir(name string, perm gofs.FileMode) error

Mkdir ...

func MkdirAll 

func MkdirAll(path string, perm gofs.FileMode) error

MkdirAll ...

func Open 

func Open(name string) (gofs.File, error)

Open ...

func ReadDir 

func ReadDir(name string) ([]gofs.DirEntry, error)

ReadDir ...

func ReadFile 

func ReadFile(name string) ([]byte, error)

ReadFile ...

func Remove 

func Remove(name string) error

Remove ...

func RemoveAll 

func RemoveAll(path string) error

RemoveAll ...

func Rename 

func Rename(oldpath string, newpath string) error

Rename ...

func Root 

func Root() (string, error)

Root ...

func SetDefault 

func SetDefault(fs FS) error

SetDefault sets the default file system backend.

func SplitPath 

func SplitPath(fsys FS, p string) ([]string, error)

SplitPath splits a path using the path separator from the provided file system.

The returned slice will have empty substrings removed.

func Stat 

func Stat(name string) (gofs.FileInfo, error)

Stat ...

func Sub 

func Sub(dir string) (gofs.FS, error)

Sub ...

func WithAttributes 

func WithAttributes(attrs *Attribute) func(*Entry)

WithAttributes sets the Attribute for an Entry.

func WithCtime 

func WithCtime(ctime time.Time) func(*Attribute)

WithCtime ...

func WithGID 

func WithGID(gid uint32) func(*Attribute)

WithGID ...

func WithGroup 

func WithGroup(group string) func(*Attribute)

WithGroup ...

func WithInode 

func WithInode(inode uint64) func(*Attribute)

WithInode ...

func WithMimeType 

func WithMimeType(mimeType string) func(*Attribute)

WithMimeType ...

func WithMode 

func WithMode(mode uint32) func(*Attribute)

WithMode ...

func WithMtime 

func WithMtime(mtime time.Time) func(*Attribute)

WithMtime ...

func WithOwner 

func WithOwner(owner string) func(*Attribute)

WithOwner ...

func WithPathValidator 

func WithPathValidator(v func(string) bool) func(*Entry)

WithPathValidator sets the function used for validating paths for the Entry.

func WithSize 

func WithSize(size uint64) func(*Attribute)

WithSize ...

func WithUID 

func WithUID(uid uint32) func(*Attribute)

WithUID ...

func WriteFile 

func WriteFile(name string, data []byte, perm gofs.FileMode) error

WriteFile ...

Types

type Attribute 

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

Attribute ...

func NewAttributes 

func NewAttributes(attributes ...func(*Attribute)) (*Attribute, error)

NewAttributes ..

func (*Attribute) Copy 

func (a *Attribute) Copy() *Attribute

Copy returns a copy of the Attribute.

func (*Attribute) Ctime 

func (a *Attribute) Ctime() time.Time

Ctime ...

func (*Attribute) GID 

func (a *Attribute) GID() int32

GID ...

func (*Attribute) Group 

func (a *Attribute) Group() string

Group ...

func (*Attribute) Inode 

func (a *Attribute) Inode() int64

Inode ...

func (*Attribute) MimeType 

func (a *Attribute) MimeType() string

MimeType ...

func (*Attribute) Mode 

func (a *Attribute) Mode() gofs.FileMode

Mode ...

func (*Attribute) Mtime 

func (a *Attribute) Mtime() time.Time

Mtime ...

func (*Attribute) Owner 

func (a *Attribute) Owner() string

Owner ...

func (*Attribute) Size 

func (a *Attribute) Size() int64

Size ...

func (*Attribute) String 

func (a *Attribute) String() string

String returns a string representation of the Attribute properties.

func (*Attribute) ToMap 

func (a *Attribute) ToMap() (map[string]any, error)

ToMap returns a map representation of the Attribute properties.

func (*Attribute) UID 

func (a *Attribute) UID() int32

UID ...

type DirIterator 

type DirIterator interface {
	hold.Iterator[*Entry]

	// NextN returns a slice containing the next n directory list. Dot list "." are skipped.
	//
	// The error io.EOF is returned if there are no remaining list left to iterate.
	NextN(n int) ([]*Entry, error)
}

DirIterator defines the behavior for iterating over entries in a directory.

type Entry 

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

Entry is a container for file and directory metadata.

func NewEntry 

func NewEntry(path string, options ...func(*Entry)) (*Entry, error)

NewEntry creates a new Entry.

func (*Entry) Attributes 

func (e *Entry) Attributes() *Attribute

Attributes returns the attributes for the Entry.

func (*Entry) Copy 

func (e *Entry) Copy() *Entry

Copy returns a copy of the Entry.

func (*Entry) Dir 

func (e *Entry) Dir() string

Dir returns the path for the Entry with the last element truncated.

func (*Entry) Info 

func (e *Entry) Info() (gofs.FileInfo, error)

Info ...

func (*Entry) IsDir 

func (e *Entry) IsDir() bool

IsDir returns whether the Entry represents a directory.

func (*Entry) ModTime 

func (e *Entry) ModTime() time.Time

ModTime returns the modification time for the Entry.

func (*Entry) Mode 

func (e *Entry) Mode() gofs.FileMode

Mode returns mode bits for the Entry.

func (*Entry) Name 

func (e *Entry) Name() string

Name returns the Entry name.

func (*Entry) Path 

func (e *Entry) Path() string

Path returns the full path for the Entry.

func (*Entry) SetModTime 

func (e *Entry) SetModTime(t time.Time) error

SetModTime sets the modification time for the Entry.

func (*Entry) SetPath 

func (e *Entry) SetPath(p string) error

SetPath sets the path for the Entry.

func (*Entry) SetSize 

func (e *Entry) SetSize(s uint64)

SetSize sets the size for the Entry if it represents a regular file.

func (*Entry) Size 

func (e *Entry) Size() int64

Size returns the length in bytes if an Entry represents a regular file.

func (*Entry) String 

func (e *Entry) String() string

String returns a string representation of the Entry.

func (*Entry) Sys 

func (e *Entry) Sys() any

Sys returns the underlying data source for the Entry (can return nil).

func (*Entry) ToMap 

func (e *Entry) ToMap() (map[string]any, error)

ToMap returns a map representation of the Entry properties.

func (*Entry) Type 

func (e *Entry) Type() gofs.FileMode

Type returns the type bits for the Entry.

The type bits are a subset of the usual FileMode bits, those returned by the FileMode.Type method.

type FS 

type FS interface {
	Readable
	Writable

	// PathSeparator ...
	PathSeparator() string

	// Provider ...
	Provider() string

	// Root ...
	Root() (string, error)

	// Close ...
	Close() error
}

FS defines the basic behavior for providing access to a hierarchical file system.

func Default 

func Default() FS

Default returns the current default for the file system backend.

type File 

type File interface {
	gofs.File
	gofs.ReadDirFile
	io.ReaderAt
	io.ReaderFrom
	io.Seeker
	io.Writer
}

File defines the behavior for providing access to a single file. This interface is an extension of the fs.Name interface and defines additional behavior for read/write operations.

func Create 

func Create(name string) (File, error)

Create ...

func OpenFile 

func OpenFile(name string, flag int, perm gofs.FileMode) (File, error)

OpenFile ...

type OSFS 

type OSFS struct{}

OSFS os/platform file system provider that implements FS.

func New 

func New() (*OSFS, error)

New creates a new OSFS.

func (*OSFS) Close 

func (o *OSFS) Close() error

func (*OSFS) Create 

func (o *OSFS) Create(name string) (File, error)

func (*OSFS) Glob 

func (o *OSFS) Glob(pattern string) ([]string, error)

func (*OSFS) Mkdir 

func (o *OSFS) Mkdir(name string, perm gofs.FileMode) error

func (*OSFS) MkdirAll 

func (o *OSFS) MkdirAll(path string, perm gofs.FileMode) error

func (*OSFS) Open 

func (o *OSFS) Open(name string) (gofs.File, error)

func (*OSFS) OpenFile 

func (o *OSFS) OpenFile(name string, flag int, perm gofs.FileMode) (File, error)

func (*OSFS) PathSeparator 

func (o *OSFS) PathSeparator() string

func (*OSFS) Provider 

func (o *OSFS) Provider() string

func (*OSFS) ReadDir 

func (o *OSFS) ReadDir(name string) ([]gofs.DirEntry, error)

func (*OSFS) ReadFile 

func (o *OSFS) ReadFile(name string) ([]byte, error)

func (*OSFS) Remove 

func (o *OSFS) Remove(name string) error

func (*OSFS) RemoveAll 

func (o *OSFS) RemoveAll(path string) error

func (*OSFS) Rename 

func (o *OSFS) Rename(oldpath string, newpath string) error

func (*OSFS) Root 

func (o *OSFS) Root() (string, error)

func (*OSFS) Stat 

func (o *OSFS) Stat(name string) (gofs.FileInfo, error)

func (*OSFS) Sub 

func (o *OSFS) Sub(dir string) (gofs.FS, error)

func (*OSFS) WriteFile 

func (o *OSFS) WriteFile(name string, data []byte, perm gofs.FileMode) error

type PathValidator 

type PathValidator func(string) bool

type Readable 

type Readable interface {
	gofs.FS
	gofs.GlobFS
	gofs.ReadFileFS
	gofs.ReadDirFS
	gofs.StatFS
	gofs.SubFS
}

Readable defines the behavior for providing read access to a hierarchical file system.

type Writable 

type Writable interface {
	// Create ...
	Create(name string) (File, error)

	// Mkdir ...
	Mkdir(name string, perm gofs.FileMode) error

	// MkdirAll ...
	MkdirAll(path string, perm gofs.FileMode) error

	// OpenFile ...
	OpenFile(name string, flag int, perm gofs.FileMode) (File, error)

	// Remove ...
	Remove(name string) error

	// RemoveAll ...
	RemoveAll(path string) error

	// Rename ...
	Rename(oldpath string, newpath string) error

	// WriteFile ...
	WriteFile(name string, data []byte, perm gofs.FileMode) error
}

Writable defines the behavior for providing write access to a hierarchical file system.

Source Files

View all Source files

Directories

Path Synopsis

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.