structfs

Documentation

Overview

Package structfs defines a data structure for a file system, similar to the fs package but based on structs instead of interfaces.

The entire tree structure and directory entry metadata is stored in memory. File content is represented with Blob, and may come from various sources.

Index

• func ValidName(name string) bool
• type Blob
  • func OSPathBlob(path string) (Blob, error)
• type Bytes
  • func (b Bytes) Open() (io.ReadCloser, error)
  • func (b Bytes) Size() int64
• type Node
  • func Dir(name string, children Tree, opts ...Option) *Node
  • func File(name string, content Blob, opts ...Option) *Node
• type Option
  • func WithModTime(t time.Time) Option
  • func WithPerm(perm fs.FileMode) Option
  • func WithSys(sys any) Option
• type Tree
  • func (t *Tree) Place(path string, node *Node) error
  • func (t *Tree) PlaceDir(path string, children Tree, opts ...Option) error
  • func (t *Tree) PlaceFile(path string, content Blob, opts ...Option) error
  • func (t Tree) Walk() iter.Seq2[string, *Node]

Functions

func ValidName

func ValidName(name string) bool

ValidName reports whether the given name is a valid node name.

The name must be UTF-8-encoded, must not be empty, "." or "..", and must not contain "/". These are the same rules as for a path element in fs.ValidPath.

Types

type Blob

type Blob interface {
	Open() (io.ReadCloser, error)
	Size() int64
}

Blob is a binary large object, a read-only sequence of bytes of a known size.

func OSPathBlob

func OSPathBlob(path string) (Blob, error)

OSPathBlob creates a Blob for an OS path.

type Bytes

type Bytes []byte

Bytes implements Blob for a byte slice.

func (Bytes) Open

func (b Bytes) Open() (io.ReadCloser, error)

func (Bytes) Size

func (b Bytes) Size() int64

type Node

type Node struct {
	// Name of this node, which must be valid according to [ValidName].
	Name string
	// Mode contains the file type and permissions.
	Mode fs.FileMode
	// ModTime is the modification time.
	ModTime time.Time
	// Content is the file content, must be set for regular files.
	Content Blob
	// Children of a directory, must be empty if this is not a directory.
	Children Tree
	// Sys contains any system-specific directory entry fields.
	//
	// It should be accessed using interface type assertions, to allow combining
	// information for multiple target systems with struct embedding.
	Sys any
}

Node is a node in a file system tree, which is either a file or directory.

func Dir

func Dir(name string, children Tree, opts ...Option) *Node

Dir creates a directory node with the given name and children.

Permission defaults to 755.

func File

func File(name string, content Blob, opts ...Option) *Node

File creates a regular file node with the given name and content.

Permission defaults to 644.

type Option

type Option func(*Node)

func WithModTime

func WithModTime(t time.Time) Option

WithModTime sets the ModTime of the Node.

func WithPerm

func WithPerm(perm fs.FileMode) Option

WithPerm sets the permission bits of the Node.

func WithSys

func WithSys(sys any) Option

WithSys sets the Sys field of the Node.

type Tree

type Tree []*Node

Tree represents a file system tree.

func (*Tree) Place

func (t *Tree) Place(path string, node *Node) error

Place creates directories if necessary and places the node in the directory at the path.

The special path "." indicates the root.

func (*Tree) PlaceDir

func (t *Tree) PlaceDir(path string, children Tree, opts ...Option) error

PlaceDir creates parent directories if necessary and places a directory with the given children at the path. It fails if path already exists.

func (*Tree) PlaceFile

func (t *Tree) PlaceFile(path string, content Blob, opts ...Option) error

PlaceFile creates parent directories if necessary and places a file with the given content at the path. It fails if path already exists.

func (Tree) Walk

func (t Tree) Walk() iter.Seq2[string, *Node]

Walk returns an iterator over all nodes in the tree in DFS pre-order. The key is the path of the node.

Entries with invalid name are skipped.