fsutil

README

This repository contains utilities around Go's io/fs package:

• UnionFS, which is a copy of the unionFS type implemented in golang.org/x/website/cmd/golangorg/server.go, slightly extended to allow access to the underlying file system of Files and DirEntrys

• NameSpace, a wrapper around UnionFS that provides method Bind, similar to Plan 9's bind command. It has been created to be able to use a functionality like Godoc's vfs.NameSpace, but based on io/fs.

• PrefixFS creates a filesystem by adding a prefix in front of another, already existing FS; it is used by Namespace.

Documentation

Overview

Package fsutil provides utilities around package io/fs, mainly a namespace feature built upen a union file system.

Index

• func OSName(name string, fsys fs.FS) (string, error)
• func PrefixFS(pathPrefix string, fsys fs.FS, option ...PrefixFSOption) fs.FS
• func Value(fsys fs.FS, key interface{}) interface{}
• type BindOption
  • func BindBefore() BindOption
  • func WithNewOSDir(dirname string) BindOption
  • func WithValue(key, value interface{}) BindOption
• type Item
• type NameSpace
  • func (nsp *NameSpace) Bind(old string, newfs fs.FS, options ...BindOption) error
• type PrefixFSOption
  • func WithModTime(t time.Time) PrefixFSOption
  • func WithPerm(perm fs.FileMode) PrefixFSOption
• type UnionFS

Functions

func OSName

func OSName(name string, fsys fs.FS) (string, error)

OSName translates the given file or directory name relative to the OS file system tree root, where the file or directory actually resides. OSName is able to return the corresponding OS file name only if the file system has been bound to a NameSpace with option WithNewOSDir previously.

func PrefixFS

func PrefixFS(pathPrefix string, fsys fs.FS, option ...PrefixFSOption) fs.FS

PrefixFS returns a file system with a pathPrefix added in front of each file and directory of the provided file system fsys. Options allow to specify a modification time and permissions for the path elements of the prefix, with current time and 0755 used as defaults.

func Value

func Value(fsys fs.FS, key interface{}) interface{}

Types

type BindOption

type BindOption func(*bindAction)

func BindBefore

func BindBefore() BindOption

func WithNewOSDir

func WithNewOSDir(dirname string) BindOption

func WithValue

func WithValue(key, value interface{}) BindOption

type Item

type Item interface {
	// FS returns the item's file system.
	FS() fs.FS
}

Item constitutes an interface to the file system an item belongs to. Item is implemented by Files and DirEntries provides by a UnionFS.

type NameSpace

type NameSpace struct {
	UnionFS
}

Namespace is a wrapper around UnionFS that provides a functionality basically similar to Plan 9's bind command

func (*NameSpace) Bind

func (nsp *NameSpace) Bind(old string, newfs fs.FS, options ...BindOption) error

Bind adds file system newfs at mount point `old`. If option BindBefore is provided, newfs' contents appear first in the union, otherwise after possibly existing files within `old`.

type PrefixFSOption

type PrefixFSOption func(*prefixFS)

func WithModTime

func WithModTime(t time.Time) PrefixFSOption

WithModTime sets the modification time of prefix path elements.

func WithPerm

func WithPerm(perm fs.FileMode) PrefixFSOption

WithPerm sets the permissions of prefix path elements to perm.

type UnionFS

type UnionFS = golangorg.UnionFS

A UnionFS is an FS presenting the union of the file systems in a slice. If multiple file systems provide a particular file, Open uses the FS listed earlier in the slice. If multiple file systems provide a particular directory, ReadDir presents the concatenation of all the directories listed in the slice (with duplicates removed).