add docs and more tests for debug format strings (#14861)

* add debug format string

* remove try except

* add changelog

* add docs and more tests

* Update lib/pure/strformat.nim

Co-authored-by: Juan Carlos <juancarlospaco@gmail.com>

* minor

Co-authored-by: Juan Carlos <juancarlospaco@gmail.com>

1 files changed, 46 insertions, 1 deletions

diff --git a/lib/pure/strformat.nim b/lib/pure/strformat.nim
index 0ea784a43..c37b6b1c0 100644
--- a/lib/pure/strformat.nim
+++ b/lib/pure/strformat.nim
@@ -63,7 +63,6 @@ Formatting floats
 .. code-block:: nim
 
     import strformat
-
     doAssert fmt"{-12345:08}" == "-0012345"
     doAssert fmt"{-1:3}" == " -1"
     doAssert fmt"{-1:03}" == "-01"
@@ -81,6 +80,52 @@ Formatting floats
     doAssert fmt"{123.456:13e}" == " 1.234560e+02"
 
 
+Debugging strings
+=================
+
+``fmt"{expr=}"`` expands to ``fmt"expr={expr}"`` namely the text of the expression, 
+an equal sign and the results of evaluated expression.
+
+.. code-block:: nim
+
+    import strformat
+    doAssert fmt"{123.456=}" == "123.456=123.456"
+    doAssert fmt"{123.456=:>9.3f}" == "123.456=  123.456"
+
+    let x = "hello"
+    doAssert fmt"{x=}" == "x=hello" 
+    doAssert fmt"{x =}" == "x =hello"
+
+    let y = 3.1415926
+    doAssert fmt"{y=:.2f}" == fmt"y={y:.2f}"
+    doAssert fmt"{y=}" == fmt"y={y}"
+    doAssert fmt"{y = : <8}" == fmt"y = 3.14159 "
+
+    proc hello(a: string, b: float): int = 12
+    let a = "hello"
+    let b = 3.1415926
+    doAssert fmt"{hello(x, y) = }" == "hello(x, y) = 12"
+    doAssert fmt"{x.hello(y) = }" == "x.hello(y) = 12"
+    doAssert fmt"{hello x, y = }" == "hello x, y = 12"
+
+
+Note that it is space sensitive:
+
+.. code-block:: nim
+
+    import strformat
+    let x = "12"
+    doAssert fmt"{x=}" == "x=12"
+    doAssert fmt"{x =:}" == "x =12"
+    doAssert fmt"{x =}" == "x =12"
+    doAssert fmt"{x= :}" == "x= 12"
+    doAssert fmt"{x= }" == "x= 12"
+    doAssert fmt"{x = :}" == "x = 12"
+    doAssert fmt"{x = }" == "x = 12"
+    doAssert fmt"{x   =  :}" == "x   =  12"
+    doAssert fmt"{x   =  }" == "x   =  12"
+
+
 Implementation details
 ======================