Add Path.sibling()

3 files changed, 69 insertions, 3 deletions

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.
@@ -3312,6 +3312,28 @@ follow_symlinks | `Bool` | Whether to follow symbolic links.  | `yes`
 (./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
 
 ```tomo
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.
@@ -791,6 +791,28 @@ follow_symlinks | `Bool` | Whether to follow symbolic links.  | `yes`
 (./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
 
 ```tomo
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