packages /

glob 0.1.0

Glob patterns for file paths: *, ?, [...], ** and {a,b}.

glob

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, .env and 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): bool
  • compile(pattern: str): Glob and matches(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 under dir whose path relative to dir matches. Results are relative to dir, 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). walk opens only directories that could still match, so src/*.auk never reads docs/, and ** never descends into hidden directories. It follows symlinks, down to at most MAX_DEPTH (64) levels, because fs can't detect symlink cycles. It fails if dir can't be listed.
  • find(pattern: str): [str]! uses fs: a pattern that carries its own base directory. find("src/**/*.auk") walks src and returns src/... paths, while find("/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 only s.
  • is_pattern(s: str): bool: tells whether s contains 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.
  • walk and find return directories too when they match (walk(d, "*") lists both files and directories). Filter with fs.is_dir if you only want files.
  • Brace expansion multiplies: {a,b}{c,d}{e,f} makes 8 patterns. Keep alternatives reasonable.
  • * and ? match / in neither matches nor walk. If you want a pattern without / to match a file name at any depth, as in .gitignore, write **/name.