doc: setup guidance updates, scripts formatted with the new style

Author: blindFS

CHANGELOG.md

@@ -0,0 +1,27 @@
+# Change Log
+
+All style related breaking changes will be documented in this file.
+
+### [eb107d7] (<https://github.com/blindFS/topiary-nushell/commit/eb107d753c687311ce1f09f68963d482c3d4335b>) feat(style)!: +1 indentation level for multiline pipelines in assignment-like expressions
+
+Related issue: [#43](https://github.com/blindFS/topiary-nushell/issues/43)
+
+#### Before the change
+
+```nushell
+let config: path = $config
+| default (
+  $toplevel
+  | path join .cargo nextest.toml
+)
+```
+
+#### After the change
+
+```nushell
+let config: path = $config
+  | default (
+    $toplevel
+    | path join .cargo nextest.toml
+  )
+```

README.md

@@ -10,15 +10,20 @@
 
 ## Status
 
-* Supposed to work well with all language features of nushell v0.108
+* Supposed to work well with all language features of nushell v0.109
   * Except for some known issues of `tree-sitter-nu`
 
 > [!NOTE]
 >
 > * There're corner cases where `tree-sitter-nu` would fail with parsing errors, if you encounter any, feel free to report [at the parser side](https://github.com/nushell/tree-sitter-nu/issues).
 > * If you encounter any style/format issue, please report in this repo.
+> * At this stage, the default style of nu-lang has no consensus yet, related breaking changes will be documented in [CHANGELOG.md](https://github.com/blindFS/topiary-nushell/blob/main/CHANGELOG.md).
 
-## Setup
+## Quick Setup
+
+> [!NOTE]
+> This section is for nushell users who have little experience with topiary.
+> If you are already an experienced topiary user, you can grab the necessary files in this repo and merge them into your topiary configuration in your own preferred way.
 
 1. Install topiary-cli using whatever package-manager on your system (0.7.0+ required)
 
@@ -29,17 +34,21 @@ cargo install topiary-cli
 
 2. Clone this repo somewhere
 
+`$env.XDG_CONFIG_HOME/topiary` is recommended for non-windows users.
+
 ```nushell
-# e.g. to `$env.XDG_CONFIG_HOME/topiary`
 git clone https://github.com/blindFS/topiary-nushell ($env.XDG_CONFIG_HOME | path join topiary)
 ```
 
 3. Setup environment variables (Optional)
 
 > [!WARNING]
-> This is required if you want to do the formatting via vanilla topiary-cli, like in the neovim/helix settings below.
+> This is required if:
+>
+> 1. on windows
+> 2. this repo is cloned to a place other than `$env.XDG_CONFIG_HOME/topiary`
 >
-> While the [`format.nu`](https://github.com/blindFS/topiary-nushell/blob/main/format.nu) script in this repo just wraps that for you.
+> Take the [`format.nu`](https://github.com/blindFS/topiary-nushell/blob/main/format.nu) script in this repo as an example.
 
 ```nushell
 # Set environment variables according to the path of the clone
@@ -76,8 +85,20 @@ $env.TOPIARY_LANGUAGE_DIR = ($env.XDG_CONFIG_HOME | path join topiary languages)
 ## Usage
 
 <details>
-  <summary>Using the <a href="https://github.com/blindFS/topiary-nushell/blob/main/format.nu">format.nu</a> wrapper </summary>
+  <summary>Using topiary-cli (recommended) </summary>
 
+```nushell
+# in-place formatting
+topiary format script.nu
+# stdin -> stdout
+cat foo.nu | topiary format --language nu
+```
+
+</details>
+
+<details>
+  <summary>Using the <a href="https://github.com/blindFS/topiary-nushell/blob/main/format.nu">format.nu</a> wrapper </summary>
+
 ```markdown
 Helper to run topiary with the correct environment variables for topiary-nushell
 
@@ -112,18 +133,6 @@ Examples:
 
 </details>
 
-<details>
-  <summary>Using topiary-cli </summary>
-  
-```nushell
-# in-place formatting
-topiary format script.nu
-# stdin -> stdout
-cat foo.nu | topiary format --language nu
-```
-
-</details>
-
 ### Locally Disable Formatting for Certain Expression
 
 If you don't like the formatted output of certain parts of your code,
@@ -192,7 +201,8 @@ formatter = { command = "topiary", args = ["format", "--language", "nu"] }
   "Nu": {
     "formatter": {
       "external": {
-        "command": "/path-to-the-clone/format.nu"
+        "command": "topiary",
+        "arguments": ["format", "--language", "nu"]
       }
     },
     "format_on_save": "on"

run_test.nu

@@ -8,15 +8,33 @@ let files = glob test/input_*.nu
 $env.TOPIARY_CONFIG_FILE = (pwd | path join languages.ncl)
 $env.TOPIARY_LANGUAGE_DIR = (pwd | path join languages)
 
-for f in $files {
-  print $"(ansi green)Testing: (ansi yellow)($f)(ansi reset)"
-  cp $f $temp_file
-  topiary format $temp_file
-  let expected_file = $f | str replace --regex '/input_' '/expected_'
-  try {
-    assert ((open $temp_file) == (open $expected_file))
-  } catch {
-    delta $temp_file $expected_file
+def main [
+  --update (-u) # force updating `expected_xxx` files
+] {
+  for f in $files {
+    print $"(ansi green)Testing: (ansi yellow)($f)(ansi reset)"
+    cp $f $temp_file
+    topiary format $temp_file
+    let expected_file = $f | str replace --regex '/input_' '/expected_'
+    try {
+      if ((which delta) | is-empty) {
+        assert ((open $temp_file) == (open $expected_file))
+      } else {
+        delta $temp_file $expected_file --paging never
+      }
+    } catch {
+      if $update and (
+        [yes no]
+        | input list --index --fuzzy $"Update expected results in file (
+          $expected_file
+          | path basename
+        )?"
+      ) == 0 {
+        cp $temp_file $expected_file
+      } else {
+        exit 1
+      }
+    }
+    rm $temp_file
   }
-  rm $temp_file
 }

toolkit.nu

@@ -46,27 +46,27 @@ export def test_format [
     return
   }
   let all_passed = 1..$len | par-each {|i|
-    let file = $files | get ($i - 1)
-    let target = $"(random uuid).nu"
-    if ($i mod 10) == 0 {
-      print -n $"(ansi -e '1000D')"
-      print_progress ($i / $len)
+      let file = $files | get ($i - 1)
+      let target = $"(random uuid).nu"
+      if ($i mod 10) == 0 {
+        print -n $"(ansi -e '1000D')"
+        print_progress ($i / $len)
+      }
+      let failed = try {
+        cp $file $target
+        let err_before = run_ide_check $target
+        topiary format $target
+        let err_after = run_ide_check $target
+        assert ($err_before == $err_after)
+        true
+      } catch {
+        print $"(ansi red)Error detected: (ansi yellow)($file)(ansi reset)"
+        false
+      }
+      rm $target
+      $failed
     }
-    let failed = try {
-      cp $file $target
-      let err_before = run_ide_check $target
-      topiary format $target
-      let err_after = run_ide_check $target
-      assert ($err_before == $err_after)
-      true
-    } catch {
-      print $"(ansi red)Error detected: (ansi yellow)($file)(ansi reset)"
-      false
-    }
-    rm $target
-    $failed
-  }
-  | all { $in }
+    | all { $in }
   if $all_passed {
     print -n $"(ansi -e '1000D')"
     print $"(ansi green)All nu scripts successfully passed the check, but style issues are still possible.(ansi reset)"