This module implements a powerful and flexible file searching library, allowing developers to easily find files and directories based on various criteria such as name patterns, size, modification time, content patterns, and more.
The Finder type provides a fluent API for configuring search parameters, and the find iterator performs the actual search operation, yielding matching file paths.
Types
FileSizeUnit = enum Bytes = "Bytes", Kilobytes = "KB", Megabytes = "MB", Gigabytes = "GB", Terabytes = "TB"
Finder = ref object kind*: FinderSearchKind ## Specifies the type of file system entries ## to search for (e.g., files, directories, symbolic links). Default to `fkAny`, ## which includes all types roots*: seq[string] recursiveSearch*: bool = true namePatterns*: seq[string] nameRegexPatterns*: seq[Regex] ## A sequence of regular expression patterns to filter search ## results based on the file/directory name (basename) pathRegexPatterns*: seq[Regex] ## A sequence of regular expression patterns to filter search ## results based on the full file/directory path extensions*: seq[string] excludeBinary*: bool = true contentPatterns*: seq[string] contentRegexPatterns*: seq[Regex] notContentPatterns*: seq[string] notContentRegexPatterns*: seq[Regex]
- Represents the configuration for a file search operation, including search criteria and options.
FinderSearchKind = enum fkAny, fkFile, fkDir, fkLinkToFile, fkLinkToDir
- Represents the type of file system entry found during the search.
Procs
proc finder(kind: FinderSearchKind = fkFile): Finder {....raises: [], tags: [], forbids: [].}
- Creates a new Finder instance with the specified search kind and default configuration.
proc isVcsPath(path: string): bool {....raises: [], tags: [], forbids: [].}
- Returns true if the path matches any VCS pattern (directory or file)
proc largerThan(f: Finder; size: FSize): Finder {....raises: [], tags: [], forbids: [].}
proc modifiedAfter(f: Finder; t: Time): Finder {....raises: [], tags: [], forbids: [].}
proc modifiedBefore(f: Finder; t: Time): Finder {....raises: [], tags: [], forbids: [].}
proc namePattern(f: Finder; pattern: string): Finder {....raises: [RegexError], tags: [], forbids: [].}
- Adds a regex filter for the file/directory basename.
proc newFinder(kind: FinderSearchKind = fkFile): Finder {....raises: [], tags: [], forbids: [].}
- Creates a new Finder instance with the specified search kind and default configuration.
proc notContains(f: Finder; pattern: string): Finder {....raises: [RegexError], tags: [], forbids: [].}
- Adds a string or regex pattern to exclude files by content.
proc parseSize(raw: string): int64 {....raises: [ValueError], tags: [], forbids: [].}
proc smallerThan(f: Finder; size: FSize): Finder {....raises: [], tags: [], forbids: [].}
Iterators
iterator find(f: Finder): string {....raises: [], tags: [ReadDirEffect, ReadIOEffect], forbids: [].}
- Performs the file search based on the criteria specified in the Finder instance and yields matching file paths. The search is performed using a depth-first approach, and it handles both files and directories according to the specified search kind and filters.