From 7cd67dd7f3ebf38a2a65c6756090936f9a1b3b03 Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Tue, 29 Oct 2024 14:36:49 -0400
Subject: Add file globbing

---
 docs/paths.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

(limited to 'docs/paths.md')

diff --git a/docs/paths.md b/docs/paths.md
index 8fb427b2..86ec2f26 100644
--- a/docs/paths.md
+++ b/docs/paths.md
@@ -288,6 +288,53 @@ A list of file paths.
 
 ---
 
+### `glob`
+
+**Description:**  
+Perform a globbing operation and return an array of matching paths. Some glob
+specific details:
+
+- The paths "." and ".." are *not* included in any globbing results.
+- Files or directories that begin with "." will not match `*`, but will match `.*`.
+- Globs do support `{a,b}` syntax for matching files that match any of several
+  choices of patterns.
+- The shell-style syntax `**` for matching subdirectories is not supported.
+
+**Signature:**  
+```tomo
+func glob(path: Path -> [Path])
+```
+
+**Parameters:**
+
+- `path`: The path of the directory which may contain special globbing characters
+  like `*`, `?`, or `{...}`
+
+**Returns:**  
+A list of file paths that match the glob.
+
+**Example:**  
+```tomo
+# Current directory includes: foo.txt, baz.txt, qux.jpg, .hidden
+>> (./*):glob()
+= [(./foo.txt), (./baz.txt), (./qux.jpg)]
+
+>> (./*.txt):glob()
+= [(./foo.txt), (./baz.txt)]
+
+>> (./*.{txt,jpg}):glob()
+= [(./foo.txt), (./baz.txt), (./qux.jpg)]
+
+>> (./.*):glob()
+= [(./.hidden)]
+
+# Globs with no matches return an empty array:
+>> (./*.xxx):glob()
+= []
+```
+
+---
+
 ### `is_directory`
 
 **Description:**  
-- 
cgit v1.2.3