From 8febea9aebe05644731bb68c297d3d13649a8dcb Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Sat, 17 May 2025 16:04:05 -0400
Subject: Add Path.sibling()

---
 api/api.md     | 24 +++++++++++++++++++++++-
 api/paths.md   | 24 +++++++++++++++++++++++-
 api/paths.yaml | 24 +++++++++++++++++++++++-
 3 files changed, 69 insertions(+), 3 deletions(-)

(limited to 'api')

diff --git a/api/api.md b/api/api.md
index 434dcd55..cbaa7a54 100644
--- a/api/api.md
+++ b/api/api.md
@@ -2746,7 +2746,7 @@ follow_symlinks | `Bool` | Whether to follow symbolic links.  | `yes`
 ## Path.child
 
 ```tomo
-Path.child : func(path: Path, child: Text -> [Path])
+Path.child : func(path: Path, child: Text -> Path)
 ```
 
 Return a path that is a child of another path.
@@ -3311,6 +3311,28 @@ follow_symlinks | `Bool` | Whether to follow symbolic links.  | `yes`
 ```tomo
 (./file.txt).set_owner(owner="root", group="wheel")
 
+```
+## Path.sibling
+
+```tomo
+Path.sibling : func(path: Path, name: Text -> Path)
+```
+
+Return a path that is a sibling of another path (i.e. has the same parent, but a different name). This is equivalent to `.parent().child(name)`
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+path | `Path` | A path.  | -
+name | `Text` | The name of a sibling file or directory.  | -
+
+**Return:** A new path representing the sibling.
+
+
+**Example:**
+```tomo
+>> (/foo/baz).sibling("doop")
+= (/foo/doop)
+
 ```
 ## Path.subdirectories
 
diff --git a/api/paths.md b/api/paths.md
index 7929e71f..ad6b894b 100644
--- a/api/paths.md
+++ b/api/paths.md
@@ -225,7 +225,7 @@ follow_symlinks | `Bool` | Whether to follow symbolic links.  | `yes`
 ## Path.child
 
 ```tomo
-Path.child : func(path: Path, child: Text -> [Path])
+Path.child : func(path: Path, child: Text -> Path)
 ```
 
 Return a path that is a child of another path.
@@ -790,6 +790,28 @@ follow_symlinks | `Bool` | Whether to follow symbolic links.  | `yes`
 ```tomo
 (./file.txt).set_owner(owner="root", group="wheel")
 
+```
+## Path.sibling
+
+```tomo
+Path.sibling : func(path: Path, name: Text -> Path)
+```
+
+Return a path that is a sibling of another path (i.e. has the same parent, but a different name). This is equivalent to `.parent().child(name)`
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+path | `Path` | A path.  | -
+name | `Text` | The name of a sibling file or directory.  | -
+
+**Return:** A new path representing the sibling.
+
+
+**Example:**
+```tomo
+>> (/foo/baz).sibling("doop")
+= (/foo/doop)
+
 ```
 ## Path.subdirectories
 
diff --git a/api/paths.yaml b/api/paths.yaml
index 5efae599..40813129 100644
--- a/api/paths.yaml
+++ b/api/paths.yaml
@@ -215,7 +215,7 @@ Path.child:
   description: >
     Return a path that is a child of another path.
   return:
-    type: '[Path]'
+    type: 'Path'
     description: >
       A new path representing the child.
   args:
@@ -761,6 +761,28 @@ Path.set_owner:
         Whether to follow symbolic links.
   example: |
     (./file.txt).set_owner(owner="root", group="wheel")
+
+Path.sibling:
+  short: get another path in the same directory
+  description: >
+    Return a path that is a sibling of another path (i.e. has the same parent,
+    but a different name). This is equivalent to `.parent().child(name)`
+  return:
+    type: 'Path'
+    description: >
+      A new path representing the sibling.
+  args:
+    path:
+      type: 'Path'
+      description: >
+        A path.
+    name:
+      type: 'Text'
+      description: >
+        The name of a sibling file or directory.
+  example: |
+    >> (/foo/baz).sibling("doop")
+    = (/foo/doop)
     
 Path.subdirectories:
   short: get subdirectories
-- 
cgit v1.2.3