Glob patterns for file paths: *, ?, [...], ** and {a,b}. Matching is a pure function of two strings. walk and find list directories to return the paths that match.
Effects: fs, and only walk and find need it. matches, compile, escape and is_pattern are pure.
fn main(): int! uses fs {
assert glob.matches("src/**/*.auk", "src/net/tcp.auk")
assert glob.matches(r"*.{md,toml}", "raft.toml") // r"…": `{` in a normal string interpolates
assert !glob.matches("*", ".env") // wildcards skip hidden files
for path in glob.walk("src", "**/*.auk")? { print(path) } // lib.auk, net/tcp.auk, ...
let docs = glob.find("docs/*.md")? // ["docs/guide.md", ...]
let g = glob.compile(r"**/*.{png,jpg}") // compile once, match many
let images = docs.filter(p => glob.matches(g, p))
print(glob.escape("report[1].txt")) // report\[1\].txt
0
}Pattern syntax#
| pattern | matches |
|---|---|
? |
any one char except / |
* |
any run of chars (possibly empty) except / |
[abc] [a-z0-9_] |
one char from the set. A ] first in the set is literal, as is a - first or last |
[!a-c] [^a-c] |
one char not in the set (never /) |
** |
as a whole segment: zero or more segments. src/**/*.auk matches src/a.auk and src/x/y/a.auk, and a/** matches a itself. Inside a longer segment (a**b) it is just * |
{a,b,c} |
any of the alternatives. They may nest, may be empty (file{,.bak}) and may contain / and wildcards |
\x |
x literally |
- Hidden files: a segment that starts with
.matches only a pattern segment that starts with a literal.. So*and**skip.git,.envand the like, while.*,.git/**and**/.cache/*still reach them. - Paths: segments are split on
/. Empty segments, a leading./and a trailing/are ignored. A pattern that starts with/matches only absolute paths, and the other way round. Matching is case-sensitive and compares chars (code points). - Never an error: an unclosed
[, or a{without a top-level,and a closing}, matches literally, as in bash. So every string is a valid pattern.
API#
matches(pattern: str, path: str): boolcompile(pattern: str): Globandmatches(g: Glob, path: str): bool: expand and tokenize the pattern once, then match it against many paths.walk(dir: str, pattern: str): [str]! uses fs: returns every file and directory underdirwhose path relative todirmatches. Results are relative todir, joined with/, in walk order (each directory's entries sorted by name, with a directory's contents right after it; call.sort()if you want plain lexicographic order).walkopens only directories that could still match, sosrc/*.auknever readsdocs/, and**never descends into hidden directories. It follows symlinks, down to at mostMAX_DEPTH(64) levels, becausefscan't detect symlink cycles. It fails ifdircan't be listed.find(pattern: str): [str]! uses fs: a pattern that carries its own base directory.find("src/**/*.auk")walkssrcand returnssrc/...paths, whilefind("/etc/*.conf")returns absolute paths. A pattern without glob syntax returns[pattern]if that path exists, otherwise[].escape(s: str): str: backslash-escapes* ? [ ] { } , \, so the result matches onlys.is_pattern(s: str): bool: tells whetherscontains any of* ? [ { \.
Notes#
- In Auk source,
{inside a normal string starts interpolation. Write brace patterns as raw strings (r"*.{md,toml}") or double the braces ("*.{{md,toml}}"). Patterns read at run time (from arguments or config files) need nothing special. walkandfindreturn directories too when they match (walk(d, "*")lists both files and directories). Filter withfs.is_dirif you only want files.- Brace expansion multiplies:
{a,b}{c,d}{e,f}makes 8 patterns. Keep alternatives reasonable. *and?match/in neithermatchesnorwalk. If you want a pattern without/to match a file name at any depth, as in.gitignore, write**/name.