Add Path:expand_home() as a publicly visible API and bugfix it

1 files changed, 25 insertions, 0 deletions

diff --git a/docs/paths.md b/docs/paths.md
index 14ec7832..cb4bb055 100644
--- a/docs/paths.md
+++ b/docs/paths.md
@@ -50,6 +50,7 @@ intended. Paths can be created from text with slashes using
 - [`func children(path: Path, include_hidden=no -> [Path])`](#children)
 - [`func create_directory(path: Path, permissions=0o755[32] -> Void)`](#create_directory)
 - [`func exists(path: Path -> Bool)`](#exists)
+- [`func expand_home(path: Path -> Path)`](#expand_home)
 - [`func extension(path: Path, full=yes -> Text)`](#extension)
 - [`func files(path: Path, include_hidden=no -> [Path])`](#files)
 - [`func from_components(components:[Text] -> Path)`](#from_components)
@@ -376,6 +377,30 @@ func exists(path: Path -> Bool)
 
 ---
 
+### `expand_home`
+For home-based paths (those starting with `~`), expand the path to replace the
+tilde with and absolute path to the user's `$HOME` directory.
+
+```tomo
+func expand_home(path: Path -> Path)
+```
+
+- `path`: The path to expand.
+
+**Returns:**  
+If the path does not start with a `~`, then return it unmodified. Otherwise,
+replace the `~` with an absolute path to the user's home directory.
+
+**Example:**  
+```tomo
+>> (~/foo):expand_home() # Assume current user is 'user'
+= /home/user/foo
+>> (/foo):expand_home() # No change
+= /foo
+```
+
+---
+
 ### `extension`
 Returns the file extension of the file at the specified path. Optionally returns the full extension.