From a57d9d723a5ed8fa11ab1d81f02d8734e75cfe36 Mon Sep 17 00:00:00 2001
From: Antoine Stevan <44101798+amtoine@users.noreply.github.com>
Date: Sat, 25 Mar 2023 17:03:21 +0100
Subject: [PATCH] SPEC: add some thoughts about a config file and sensible (?)
 defaults (#6)

* add some thoughts about a config file and sensible (?) defaults

* add a warning for paths on windows

* fix the NOTE in the "defaults" section

* add a newline in the Note and in the Warning
---
 docs/specification.md | 102 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 101 insertions(+), 1 deletion(-)

diff --git a/docs/specification.md b/docs/specification.md
index ed2363a..d253844 100644
--- a/docs/specification.md
+++ b/docs/specification.md
@@ -20,6 +20,106 @@ There should be a `--limit` parameter to limit to the number of characters per l
 
 There should be a `--lines-before` and `--lines-after` parameter to set the number of empty lines before and after a custom command.
 
+## Config file
+
+As `rustfmt` does it with a `TOML` file, `nufmt` could have a config file, alongside the command line flags above to set options in stone.
+We have identified the NUON format as a suitable data format for this project: after it's THE data format for `nushell`!
+
+With the values above, it could look something like:
+```nuon
+{
+    CRLF: false,
+    indent: 4,
+    limit: 100,
+    lines: {
+        after: 1,
+        before: 1
+    }
+}
+```
+
+## Sensible (?) default and features
+
+- :one: do not always add newlines when it can help understand the central point of a command call
+```nushell
+http get ({
+    scheme: https,
+    host: api.github.com,
+    path: /users/nushell/repos,
+    params: {
+        sort: updated,
+        per_page: 100
+        page: 1
+    }
+} | url join)
+```
+to put the emphasis on the url structure
+> **Note**  
+> the  `({ ... } | url join)`
+
+- :two: put `|` at the start of the lines for readability, creating a "wall of pipes"
+```nushell
+def "apply to" [
+    file: path
+    modification: closure
+] {
+    $file
+    | path expand
+    | open --raw
+    | from toml
+    | do $modification
+    | save --force $file
+}
+```
+
+- :three: ternary-like conditions when conditions and the two branches are short
+```nushell
+let sign = if $value < 0 { -1 } else { 1 }
+```
+instead of
+```nushell
+let sign = (
+    if $value < 0 {
+        -1
+    } else {
+        1
+    }
+)
+```
+
+- :four: a newline before a block of comments
+```nushell
+some command
+
+# a comment to explain
+another comment
+
+# a block
+# of comment
+# for this
+last command
+```
+
+:five: two spaces before and one space after a comment on the same line as a command
+```nushell
+my-command  # and some explaination
+```
+or in command arguments as well
+```nushell
+def foo [
+    a: int  # my integer argument
+    b: string  # my string integer
+] {}
+```
+
+- :six: 4 spaces as the default indentation
+
+- :seven: remove trailing whitespaces
+
+- :eight: single quotes for single characters and double quotes for strings => that behaviour might change with string interpolation and paths.
+> **Warning**  
+> one should use single quotes (') or backticks (\`) to quote paths on Windows
+
 ## Supported Commands
 
 This is the list of the supported commands and their idiomatic formatting. Indentation will be covered by the `--indent` flag but for these examples, 2 spaces will be used.
@@ -42,4 +142,4 @@ if condition {
 for var in 0..100 {
   # do something here
 }
-```
\ No newline at end of file
+```