pfs

package
v0.4.112 Latest Latest
Warning

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

 Go to latest Published: Oct 12, 2023 License: ISC Imports: 18 Imported by: 3

Documentation

Index

Constants

View Source 
const (
	// AllModeBits is all known github.com/fsnotify/fsevents.EventFlags
	AllModeBits fs.FileMode = fs.ModeDir | fs.ModeAppend | fs.ModeExclusive |
		fs.ModeTemporary | fs.ModeSymlink | fs.ModeDevice | fs.ModeNamedPipe |
		fs.ModeSocket | fs.ModeSetuid | fs.ModeSetgid | fs.ModeCharDevice |
		fs.ModeSticky | fs.ModeIrregular
)
View Source 
const (
	DropPathsNotValues = true
)
View Source 
const (
	RetainSymlinks = false
)

Variables

View Source 
var ErrEndListing = errors.New("endListing")
View Source 
var St = parl.Debug

Functions

func Abs added in v0.4.23 

func Abs(dir string) (out string)

Abs ensures a file system path is fully qualified. Abs is single-return-value and panics on troubles

func AbsEval 

func AbsEval(path string, retainSymlinks ...bool) (absPath string, err error)

AbsEval returns an absolute path with resolved symlinks

  • use of current directory to make path absolute
  • “.” is returned for empty string
  • if retainSymlinks is RetainSymlinks, symlinks are returned
  • correct multiple Separators, eliminate “.”, eliminate inner and inappropriate “..”, ensure platform Separator

func Dirs 

func Dirs(dir string, callback ...func(dir string) (err error)) (dirs []string, err error)

Dirs retrieves absolute paths to all directories, while following symlinks, from initial dir argument. callback: cb is 6–58% faster than slice, results are found faster, and it can be canceled midway. if callback blocks, not good…

func Elems added in v0.4.26 

func Elems(path string) (dirs []string, file string)

Elems splits a path into a list of directory names and base filename part. if path is absolute, dirs[0] is "/". if there is no separator in path, dirs is empty. if path is empty string, dirs is empty and file is empty string.

func EnsureDirectory 

func EnsureDirectory(directory string, dirMode fs.FileMode)

use 0 for default file mode owner rwx

func Exists 

func Exists(path string) (fileInfo fs.FileInfo)

Exists determines if a path exists If the path exists, fileInfo is non-nil if the path does not exist, fileInfo is nil panic on troubles

func GetModeBitValues 

func GetModeBitValues() (s string)

func IsDirectory 

func IsDirectory(path string, flags IsDirectoryArg) (isDirectory bool, err error)

func IsEmptyDirectory 

func IsEmptyDirectory(path string, ignoreENOENT ...bool) (isEmpty bool)

IsEmptyDirectory checks if a directory is empty. ignoreENOENT if true, a non-exiting directory is ignored. pamnic on troubles

func MoveOrMerge 

func MoveOrMerge(src, dest string, outConsumer func(string)) (err error)

func Mv 

func Mv(src, dest string, outConsumer func(string)) (err error)

Mv moves a file or directory structure using system command. Mv uses -n for --n-clobber. Mv does not indicate if moive was aborted due to no-clobber. outConsumer can be nil but receiver command output if any. mv typically has no output.

func NewContextReader 

func NewContextReader(ctx context.Context, reader io.Reader) io.Reader

NewContextReader instantiates ContextReader

func Stat 

func Stat(path string) (fileInfo fs.FileInfo, err error)

func TestElemsX added in v0.4.26 

func TestElemsX(t *testing.T)

func Walk 

func Walk(rootPath string, walkFn filepath.WalkFunc) (err error)

Walk pfs.Walk traverses a directory hierarchy following any symlinks

  • every entry in the hierarchy is provided exactly once to walkFn
  • to identify circular symlinks, the hierarchy is first completely scanned
  • — this builds an in-memory representation of all files and directories
  • — a complete scan is required toresolve nesting among symlinks
  • the Go standard library filepath.Walk does not follow symlinks
  • walkFn receives each entry with paths beginning similar to the path provided to Walk
  • — WalkFn is: func(path string, info fs.FileInfo, err error) error
  • — path may be implicitly relative to current directory: “subdir/file.txt”
  • — may have no directory part: “README.css”
  • — may be relative: “../file.txt”
  • — may contain symlinks, unnecessary “.” and “..”, and other problems
  • — pfs.AbsEval returns an absolute, clean, symlink or non-symlink path
  • — walkFn may receive an error if encountered while scanning a path
  • — if walkFn receives an error, info may be nil walkFn can choose to ignore, skip or return the error
  • walkFn may return filepath.SkipDir to skip entering a certain directory
  • walkFn may return filepath.SkipAll to end file system scanning
  • Walk does not return filepath.SkipDir or filepath.SkipAll errors

Types

type ContextReader 

type ContextReader struct {
	io.Reader
	// contains filtered or unexported fields
}

ContextReader reader terminated by context

func (*ContextReader) Read 

func (cr *ContextReader) Read(p []byte) (n int, err error)

type DLEntry 

type DLEntry struct {
	RelDir      string // directory name that may begin with '.'
	AbsDir      string // absolute directory name
	FqPath      string // fully qualified path to entry
	fs.DirEntry        // .Name() .IsDir() .Type() .Info()
	Info        fs.FileInfo
	Stat        *syscall.Stat_t
}

func GetEntry 

func GetEntry(rel, abs string, entry fs.DirEntry, info fs.FileInfo, stat *syscall.Stat_t) (e *DLEntry)

type Directory 

type Directory struct {
	Entry
	Children []FSEntry
}

Directory is a file system entry with children

func NewDirectory 

func NewDirectory(entryImpl *Entry) (d *Directory)

NewDirectory instantiates FSEntry that can have children

func (*Directory) FetchChildren added in v0.4.108 

func (d *Directory) FetchChildren(path string) (children []FSEntry, paths []string, err error)

FetchChildren reads the directory and populates the Children field

  • errors are stored using SetError

type DirectoryLister 

type DirectoryLister struct {
	Path    string // may begin with ., may be .
	Abs     string
	Results chan *EntryResult
	// contains filtered or unexported fields
}

func NewDirStream 

func NewDirStream(path string, chanSize int) (dir *DirectoryLister)

func (*DirectoryLister) Shutdown 

func (dir *DirectoryLister) Shutdown()

type Entry 

type Entry struct {

	// info.Name() has basename, os.FileInfo: interface
	//	- may be nil
	//	- Name() Size() Mode() ModTime() IsDir() Sys()
	os.FileInfo
	// contains filtered or unexported fields
}

Entry is a file system entry that is not a directory

  • can be part of directory, symlink or other

func NewEntry 

func NewEntry(base string) (entry *Entry)

NewEntry returns Entry or Directory

  • path is absolute path to this file

func (*Entry) FetchFileInfo added in v0.4.108 

func (e *Entry) FetchFileInfo(path string) (err error)
func (e *Entry) IsSymlink() (isSymlink bool)

func (*Entry) Name added in v0.4.108 

func (e *Entry) Name() (base string)

Name gets filepath.Base() in a safe way

  • Name() fails if FileInfo si not available

func (*Entry) SetError added in v0.4.108 

func (e *Entry) SetError(err error)

SetError stores an error encountered during scan for symlinks

  • it is provided to filepath.WalkFunc during the walk phase

func (*Entry) Walks added in v0.4.108 

func (e *Entry) Walks() (info fs.FileInfo, err error)

Walk traverses which for a file is only the file itself

type EntryResult 

type EntryResult struct {
	*DLEntry
	Err error
}

func GetErrorResult 

func GetErrorResult(err error) (result *EntryResult)

type EntryScanner added in v0.4.108 

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

EntryScanner scans file-system entries and their children

func NewEntryScanner added in v0.4.108 

func NewEntryScanner(
	rootEntry FSEntry, abs, path string,
	symlinkCb func(abs string),
	pFSEntryCount *atomic.Uint64,
) (scanner *EntryScanner)

func (*EntryScanner) Scan added in v0.4.108 

func (s *EntryScanner) Scan() (err error)

Scan scans the file system for this root

  • files and directories that are symlinks are stored via symlinkCb
  • sub-directories have deferred processing using a linked list

type FSEntry 

type FSEntry interface {
	// Name is basename from fs.FileInfo “file.txt”
	Name() (base string)
	// IsDir returns whether the file-system entry is a directory containing files
	// as opposed to a file
	IsDir() (isDir bool)
	// IsSymlink returns whether the file-system entry is a symbolic link
	// that may create a new root
	//	- a symlink is not a directory, but may point to a directory that
	//		may become a new root
	IsSymlink() (isSymlink bool)
	// Walks returns data required for invoking filepath.WalkFunc
	Walks() (info fs.FileInfo, err error)
	// SetError stores an error encountered during scan for symlinks
	//	- it is provided to filepath.WalkFunc during the walk phase
	SetError(err error)
}

FSEntry represents a branch in a file system hierarchy. May be:

  • an Entry, ie. a file and not a directory
  • a Directory containing additional file-system entries
  • a Root representing a file-system traversal entry point

func GetFSEntry added in v0.4.108 

func GetFSEntry(path string, base string) (entry FSEntry, err error)

GetFSEntry returns an FSentry corresponding to path

  • the returned FSEntry may be a directory or a file-type entry
  • path is provided path, possibly relative
  • base is basename in case fileInfo cannot be retrieved
  • sym receives a callback if the FSEntry is a symbolic link

type FileMode 

type FileMode struct {
	fs.FileMode
}

func (FileMode) Ch 

func (fm FileMode) Ch() (s string)

func (FileMode) Check 

func (fm FileMode) Check() (str string)

Check returns hex string of unknown bits, empty string if no unknown bits

func (FileMode) Hex 

func (fm FileMode) Hex() (s string)

func (FileMode) Hex8 

func (fm FileMode) Hex8() (s string)

func (FileMode) Or 

func (fm FileMode) Or() (s string)

func (FileMode) String 

func (fm FileMode) String() (s string)

type IsDirectoryArg 

type IsDirectoryArg byte
const (
	IsDirectoryNonExistentIsError IsDirectoryArg = 1 << iota
	IsDirectoryNotDirIsError
)

type PathRegistry added in v0.4.108 

type PathRegistry[V any] struct {
	// contains filtered or unexported fields
}

PathRegistry stores values that are accessible by index or by absolute path

func NewPathRegistry added in v0.4.108 

func NewPathRegistry[V any]() (registry *PathRegistry[V])

NewPathRegistry returns a regustry of values by absolute path

func (*PathRegistry[V]) Add added in v0.4.108 

func (r *PathRegistry[V]) Add(abs string, value *V)

Add adds a value to the registry

func (*PathRegistry[V]) DeleteByIndex added in v0.4.108 

func (r *PathRegistry[V]) DeleteByIndex(index int)

func (*PathRegistry[V]) Drop added in v0.4.108 

func (r *PathRegistry[V]) Drop(onlyPaths ...bool)

func (*PathRegistry[V]) GetNext added in v0.4.108 

func (r *PathRegistry[V]) GetNext() (value *V)

GetNext gets the next value and removes it from the registry

func (*PathRegistry[V]) GetValue added in v0.4.108 

func (r *PathRegistry[V]) GetValue(index int) (value *V)

GetValue retrieves value by index

  • if index is less than 0 or too large or for a removed value, nil is returned

func (*PathRegistry[V]) HasAbs added in v0.4.108 

func (r *PathRegistry[V]) HasAbs(abs string) (hasAbs bool)

HasAbs check whether an absolute path is stored in the registry as a key to a value

func (*PathRegistry[V]) ListLength added in v0.4.108 

func (r *PathRegistry[V]) ListLength() (length int)

ListLength returns the length of the value slice

  • a value can still be nil for a discarded root

func (*PathRegistry[V]) MapLength added in v0.4.108 

func (r *PathRegistry[V]) MapLength() (length int)

MapLength returns the number of stored values

type PendingEntry added in v0.4.108 

type PendingEntry struct {
	Next      *PendingEntry
	Abs, Path string
	Entry     FSEntry
}

func NewPendingEntry added in v0.4.108 

func NewPendingEntry(abs, path string, entry FSEntry) (pending *PendingEntry)

type Root 

type Root struct {
	// path as provided that may be easier to read
	//   - — may be implicitly relative to current directory: “subdir/file.txt”
	//   - — may have no directory part: “README.css”
	//   - — may be relative: “../file.txt”
	//   - — may contain symlinks and unnecessary “.” and “..”
	ProvidedPath string

	// FSEntry represents the file-system location of this root
	//	- Directory or Entry
	//	- SafeName() IsDir()
	FSEntry
	// contains filtered or unexported fields
}

Root is a file system hierarchy

func NewRoot 

func NewRoot(path string) (root *Root)

NewRoot returns a file-system starting point for traversal

  • path may be absolute or relative path

func (*Root) Abs added in v0.4.108 

func (r *Root) Abs() (abs string)

func (*Root) Init added in v0.4.108 

func (r *Root) Init() (absPath string, rootEntry FSEntry, err error)

type Sha256 

type Sha256 []byte

Sha256 contains sha-256 hash

func Sha256Context 

func Sha256Context(ctx context.Context, filename string) (s2 Sha256, err error)

Sha256Context get sha256 of a file with context

func (Sha256) String 

func (s2 Sha256) String() string

func (*Sha256) Valid 

func (s2 *Sha256) Valid() bool

Valid determines if hash is present 

type SymlinkList struct {
	// contains filtered or unexported fields
}
func NewSymlinkList() (list *SymlinkList)

type Tree 

type Tree struct {
	FSEntryCount *atomic.Uint64
	// contains filtered or unexported fields
}

Tree represents a file system scan originating at a single absolute or relative path

  • additional roots may appear if the original path contains symlinks that point outside the original directory tree
  • each such root is a separate starting path in the overall file system

func NewTree 

func NewTree(walkFunc filepath.WalkFunc) (tree *Tree)

NewTree returns a file-system scan object

func (*Tree) ScanRoots added in v0.4.108 

func (t *Tree) ScanRoots(rootPath string) (err error)

ScanRoots scans rootpath and all additional encountered roots

  • rootPath is as provided to the Walk function, ie. may be relative and unclean

func (*Tree) SetCounter added in v0.4.109 

func (t *Tree) SetCounter(FSEntryCount *atomic.Uint64)

func (*Tree) Walk 

func (t *Tree) Walk() (err error)

Walk traverses the built tree

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.