Documentation
¶
Overview ¶
Package traverse_v2 is a rewrite of traverse aimed at maximum speed and correct hierarchical completion tracking.
Design summary:
- Each directory owns a dirNode "signing sheet" with atomic expected/done counters and a one-shot finished CAS. Completion bubbles up the parent chain; root completion closes Traverse.done.
- Two independent worker pools: one for directory reads (IO-bound), one for file callbacks (user code). Submit is non-blocking with overflow-goroutine fallback to prevent recursive-submission deadlocks.
- Directory entries are read via os.ReadDir + entry.Type(), which avoids the per-entry lstat syscall that os.DirEntry.Info() incurs.
Index ¶
- func GetAllPaths(dir string, opts ...Option) ([]string, error)
- type FileCountResult
- type FileListResult
- type Item
- type Option
- func WithDefaultExclude() Option
- func WithDepth(depth int) Option
- func WithDirWorkers(n int) Option
- func WithExcludeDir(dirs ...string) Option
- func WithExcludePrefix(prefixes ...string) Option
- func WithExcludeSuffix(suffixes ...string) Option
- func WithFileWorkers(n int) Option
- func WithMaxDepth(depth int) Option
- func WithOnComplete(fn func()) Option
- func WithOnDirComplete(fn func(*Item)) Option
- func WithOnlyDir() Option
- func WithQueueScale(n int) Option
- func WithSensibleDefaults() Option
- func WithSkipDotEntries() Option
- func WithSkipKnownBinaryFiles() Option
- func WithSkipKnownIgnoreDirs() Option
- func WithSyncFileOpMode() Option
- func WithSyncMode() Option
- func WithTargetExt(ext string) Option
- func WithWorkerCount(n int) Option
- type Traverse
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetAllPaths ¶ added in v0.0.13
GetAllPaths walks dir and returns the relative paths of every file (directories are not included). Paths use "/" as separator and are rooted at dir (e.g. "subdir/file.go", not "/abs/path/subdir/file.go").
All Option values are honored. Common usage:
paths, err := traverse_v2.GetAllPaths(root,
traverse_v2.WithSensibleDefaults(),
traverse_v2.WithTargetExt(".go"),
)
This is the v2 equivalent of v1 DirTraverse.GetAllPath.
Types ¶
type FileCountResult ¶ added in v0.0.13
type FileCountResult struct {
// Total file count after filtering (directories not counted, unlike
// v1 which over-counted by including dirs in Count).
Total int
// File count grouped by language name, keyed via lang_ext.CommonLanguageExt.
// Files with unrecognized extensions are counted in Total but not here.
ByLanguage map[string]int
}
FileCountResult is what GetFileCount returns. v2 equivalent of v1 traverse.FileCountRes, minus TargetCount (redundant — when TargetExt is set, Total already equals matching files) and minus the embedded option.
func GetFileCount ¶ added in v0.0.13
func GetFileCount(dir string, opts ...Option) (*FileCountResult, error)
GetFileCount walks dir and returns a count of files plus per-language breakdown. v2 equivalent of v1 traverse.GetFileCount.
type FileListResult ¶ added in v0.0.13
FileListResult bundles a file path slice with an O(1) lookup set. v2 equivalent of v1 traverse.FileListRes.
func GetFileList ¶ added in v0.0.13
func GetFileList(dir string, opts ...Option) (*FileListResult, error)
GetFileList walks dir and returns matching file paths (relative to dir, "/" separated) plus an O(1) lookup set. Combine with WithTargetExt to filter by extension.
Difference from v1: when TargetExt is NOT set, v2 includes ALL files (v1 returned an empty list — a bug in v1's callback that this fixes).
type Item ¶
type Item struct {
Path string // path relative to traverse root, "/" separated; empty for root
FullPath string // absolute filesystem path
Name string // basename
Ext string // extension including dot, empty if none
Mode fs.FileMode // from DirEntry.Type(); not equivalent to os.Stat's mode
IsDir bool
Depth int // 0 = root; root's direct children are 1
}
Item is what the user's callback receives. It is built from a DirEntry (no extra stat call), so Mode contains only what entry.Type() exposes (type bits + permission bits if the OS provided them in readdir).
type Option ¶
type Option func(*option)
func WithDefaultExclude ¶ added in v0.0.13
func WithDefaultExclude() Option
WithDefaultExclude is a v1 compatibility alias for WithSensibleDefaults.
func WithDirWorkers ¶
func WithExcludeDir ¶
WithExcludeDir matches directory names (basename) OR relative paths. e.g. "node_modules" matches anywhere; "src/generated" matches that path.
func WithExcludePrefix ¶
func WithExcludeSuffix ¶
func WithFileWorkers ¶
func WithMaxDepth ¶
WithMaxDepth limits traversal depth. 0 means unlimited.
func WithOnComplete ¶
func WithOnComplete(fn func()) Option
WithOnComplete registers a callback fired exactly once when the entire traversal has finished (after every item callback and every per-dir complete event). Fires before Done() unblocks and before Run() returns, so observers reading Done() see a fully-settled world.
func WithOnDirComplete ¶
WithOnDirComplete registers a callback fired exactly once per directory, the moment that directory's entire subtree (all sub-dirs + all files) has completed. Useful for per-dir aggregation or incremental output. The root directory also fires this event last.
func WithOnlyDir ¶
func WithOnlyDir() Option
func WithQueueScale ¶
WithQueueScale sets queue size = workers * scale for both pools. Default 16.
func WithSensibleDefaults ¶
func WithSensibleDefaults() Option
WithSensibleDefaults turns on all three common skip rules.
func WithSkipDotEntries ¶
func WithSkipDotEntries() Option
WithSkipDotEntries skips files and directories whose name begins with ".".
func WithSkipKnownBinaryFiles ¶
func WithSkipKnownBinaryFiles() Option
WithSkipKnownBinaryFiles skips files whose extension is in lang_ext.CommonExcludeFileExt (.exe, .so, .pyc, etc.).
func WithSkipKnownIgnoreDirs ¶
func WithSkipKnownIgnoreDirs() Option
WithSkipKnownIgnoreDirs skips directories in lang_ext.CommonExcludeDir (node_modules, vendor, dist, etc.).
func WithSyncFileOpMode ¶ added in v0.0.13
func WithSyncFileOpMode() Option
WithSyncFileOpMode runs file callbacks in a single worker. v1 compatibility alias for WithFileWorkers(1). Useful when the user callback is not goroutine-safe.
func WithSyncMode ¶ added in v0.0.13
func WithSyncMode() Option
WithSyncMode runs directory reads in a single worker. v1 compatibility alias for WithDirWorkers(1). Note: due to v2's overflow-on-full submit, this is "mostly single-threaded" — bursts may still spawn goroutines.
func WithTargetExt ¶
WithTargetExt filters to only files matching this extension (callback is not invoked for other files). Pass with leading dot, e.g. ".go".
func WithWorkerCount ¶ added in v0.0.13
WithWorkerCount sets both DirWorkers and FileWorkers to n. v1 compatibility shortcut; for separate tuning use WithDirWorkers and WithFileWorkers.
type Traverse ¶
type Traverse struct {
Path string
// contains filtered or unexported fields
}
func (*Traverse) Done ¶
func (t *Traverse) Done() <-chan struct{}
Done returns a channel that is closed when the entire traversal has finished — every item callback returned, every per-dir complete event fired, and the OnComplete callback (if any) finished. Safe to call before Run(); the channel is created at construction time.
Use it from a goroutine that does NOT call Run() itself, e.g.:
go trv.Run() <-trv.Done()
Source Files