github.com/haraldrudell/parl@v0.4.176/pfs/result-entry.go (about)

     1  /*
     2  © 2023–present Harald Rudell <harald.rudell@gmail.com> (https://haraldrudell.github.io/haraldrudell/)
     3  ISC License
     4  */
     5  
     6  package pfs
     7  
     8  import (
     9  	"io/fs"
    10  
    11  	"github.com/haraldrudell/parl"
    12  	"github.com/haraldrudell/parl/perrors"
    13  )
    14  
    15  // ResultEntry is an existing file-system entry, traversal-end marker or an error-entry
    16  // during file-system traversal
    17  //   - non-error non-end file-system entries have been proven to exist
    18  //   - [ResultEntry.IsEnd] or Reason == REnd indicates end
    19  //   - Reson indicates why the ResultEntry was returned:
    20  //   - [REnd] [REntry] [RSkippable] [RDirBad] [RSymlinkBad] [RError]
    21  //   - —
    22  //   - ResultEntry is a value-container that as a local variable, function argument or result
    23  //     is a tuple not causing allocation by using temporary stack storage
    24  //   - taking the address of a &ResultEntry causes allocation
    25  type ResultEntry struct {
    26  	//	- always non-nil
    27  	//	- may be deferred-info executing [os.Lstat] every time, ie. only invoke Info once
    28  	//	- if Err is non-nil, Info may return error
    29  	fs.DirEntry
    30  	// path as provided that may be easier to read
    31  	//   - may be implicitly relative to current directory: “subdir/file.txt”
    32  	//   - may have no directory or extension part: “README.css” “z”
    33  	//   - may be relative: “../file.txt”
    34  	//   - may contain symlinks, unnecessary “.” and “..” or
    35  	//		multiple separators in sequence
    36  	//	- may be empty string for current working directory
    37  	ProvidedPath string
    38  	//	- equivalent of Path: absolute, symlink-free, clean
    39  	//	- if Err non-nil, may be empty
    40  	//	- if the entry is symbolic link:
    41  	//	- — ProvidedPath is the symbolic link location
    42  	//	- — Abs is what the symbolic link points to
    43  	Abs string
    44  	// function to skip descending into directory or following symlink
    45  	SkipEntry func(no uint64)
    46  	// skippable serial number
    47  	No uint64
    48  	// any error associated with this entry
    49  	Err error
    50  	// why this entry was provided
    51  	//	- REnd REntry RSkippable RDirBad RSymlinkBad RError
    52  	Reason ResultReason
    53  }
    54  
    55  // Skip marks the returned entry to be skipped
    56  //   - the entry is directory or symbolic link
    57  //   - can only be invoked when [ResultEntry.Reason] is [RSkippable]
    58  func (e ResultEntry) Skip() { e.SkipEntry(e.No) }
    59  
    60  // IsEnd indicates that this ResultEntry is an end of entries marker
    61  func (e ResultEntry) IsEnd() (isEnd bool) { return e.DirEntry == nil }
    62  
    63  // resultEntry path: "…" abs"/…" err ‘OK’ reason ‘non-symlink non-directory non-error entry’
    64  func (e ResultEntry) String() (s string) {
    65  	return parl.Sprintf("resultEntry path: %q abs%q err ‘%s’ reason ‘%s’",
    66  		e.ProvidedPath, e.Abs,
    67  		perrors.Short(e.Err),
    68  		e.Reason,
    69  	)
    70  }