Rename path replace-extension to path with-extension, add with-stem and with-parent (#1011)

Extends #1002. Renames `path replace-extension` to `path
with-extension`, in following with other languages
([Rust](https://doc.rust-lang.org/std/path/struct.Path.html#method.with_extension),
[Python](https://docs.python.org/3/library/pathlib.html#pathlib.PurePath.with_suffix)),
and adds `path with-stem` and `path with-parent`. Also moves the `path`
module into `std-rfc` so it can be used like `use std-rfc/path`.

Adds a private helper function, `with-field`, that `with-extension`,
`with-stem`, and `with-parent` can use. These can each be dead simple
functions, while giving users more options for path manipulation.

The motivation for separate `with-extension`, `with-stem`, and
`with-parent` functions, rather than a more general function like `path
with` is the following:
- `with-extension` has special behavior for stripping periods
- you can tab-complete `path with<TAB>` to immediately see all the
possible options
- you can't accidentally pass an invalid field to `path with` 
- there can be separate examples for `with-extension`, `with-stem`,
`with-parent` for only the relevant functionality

stdlib-candidate/path/mod.nu

@@ -1,30 +0,0 @@
-# Replace extension of input file paths.
-#
-# Note that it doesn't change the file name locally.
-#
-# # Example
-# - setting path ext to `rs`
-# ```nushell
-# > "ab.txt" | path replace-extension "rs"
-# ab.rs
-# > "ab.txt" | path replace-extension ".rs"
-# ab.rs
-#
-# - setting a list of input path ext to `rs`
-# > ["ab.txt", "cd.exe"] | path replace-extension "rs"
-# ╭───┬──────────╮
-# │ 0 │ ab.rs    │
-# │ 1 │ cd.rs    │
-# ╰───┴──────────╯
-# ``` 
-export def replace-extension [
-    ext: string
-] {
-    let path_parsed = $in | path parse
-    if ($ext | str starts-with ".") {
-        $path_parsed | update extension ($ext | str substring 1..) | path join
-    } else {
-        $path_parsed | update extension $ext | path join
-    }
-}
-

stdlib-candidate/std-rfc/path/mod.nu

@@ -0,0 +1,71 @@
+# Helper function for `path with` commands
+def with-field [field: string, value: string] {
+  path parse
+  | update $field $value
+  | path join
+}
+
+# Replace extension of input file paths.
+#
+# Note that it doesn't change the file name locally.
+#
+# # Example
+# - setting path ext to `rs`
+# ```nushell
+# > "ab.txt" | path with-extension "rs"
+# ab.rs
+# > "ab.txt" | path with-extension ".rs"
+# ab.rs
+#
+# - setting a list of input path ext to `rs`
+# > ["ab.txt", "cd.exe"] | path with-extension "rs"
+# ╭───┬──────────╮
+# │ 0 │ ab.rs    │
+# │ 1 │ cd.rs    │
+# ╰───┴──────────╯
+# ```
+export def with-extension [ext: string] {
+  let path = $in
+  let ext_trim = if $ext starts-with "." {
+    $ext | str substring 1..
+  } else {
+    $ext
+  }
+  $path | with-field extension $ext_trim
+}
+
+# Replace stem of input file paths.
+#
+# Note that it doesn't change the file name locally.
+#
+# # Example
+# - replace stem with "share"
+# ```nushell
+# > "/usr/bin" | path with-stem "share"
+# /usr/share
+#
+# - replace stem with "nushell"
+# > ["/home/alice/", "/home/bob/secret.txt"] | path with-stem "nushell"
+# ╭───┬───────────────────────╮
+# │ 0 │ /home/nushell         │
+# │ 1 │ /home/bob/nushell.txt │
+# ╰───┴───────────────────────╯
+# ```
+export def with-stem [stem: string] { with-field stem $stem }
+
+# Replace parent field of input file paths.
+#
+# # Example
+# - replace parent path with `/usr/share`
+# ```nushell
+# > "/etc/foobar" | path with-parent "/usr/share/"
+# /usr/share/foobar
+#
+# - replace parent path with `/root/` for all filenames in list
+# > ["/home/rose/meow", "/home/fdncred/"] | path with-parent "/root/"
+# ╭───┬────────────╮
+# │ 0 │ /root/meow │
+# │ 1 │ /root/spam │
+# ╰───┴────────────╯
+# ```
+export def with-parent [parent: string] { with-field parent $parent }

stdlib-candidate/tests/path.nu

@@ -1,21 +1,39 @@
-use path
+use std-rfc/path
 use std/assert
 
 #[test]
-def path_replace_extension [] {
-    let new_path = "ab.txt" | path replace-extension "rs"
+def path_with_extension [] {
+    let new_path = "ab.txt" | path with-extension "rs"
     assert equal $new_path "ab.rs"
 
-    let new_path = "ab.txt" | path replace-extension ".rs"
+    let new_path = "ab.txt" | path with-extension ".rs"
     assert equal $new_path "ab.rs"
 }
 
 #[test]
-def path_replace_extension_for_list [] {
-    let new_path = ["ab.txt", "cd.exe"] | path replace-extension "rs"
+def path_with_extension_for_list [] {
+    let new_path = ["ab.txt", "cd.exe"] | path with-extension "rs"
     assert equal $new_path ["ab.rs", "cd.rs"]
 
 
-    let new_path = ["ab.txt", "cd.exe"] | path replace-extension ".rs"
+    let new_path = ["ab.txt", "cd.exe"] | path with-extension ".rs"
     assert equal $new_path ["ab.rs", "cd.rs"]
 }
+
+#[test]
+def path_with_stem [] {
+    let new_path = "/usr/bin" | path with-stem "share"
+    assert equal $new_path "/usr/share"
+
+    let new_path = ["/home/alice/", "/home/bob/secret.txt"] | path with-stem "nushell"
+    assert equal $new_path ["/home/nushell", "/home/bob/nushell.txt"]
+}
+
+#[test]
+def path_with_parent [] {
+    let new_path = "/etc/foobar" | path with-parent "/usr/share/"
+    assert equal $new_path "/usr/share/foobar"
+
+    let new_path = ["/home/rose/meow", "/home/fdncred/"] | path with-parent "/root/"
+    assert equal $new_path ["/root/meow", "/root/fdncred"]
+}