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

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

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.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL