dumpToString: improves on sugar.dump (#16841)

* dumpToString
* _
* fixup
* changelog
* address comment: removed the word "Deprecated"

changelog.md

@@ -104,6 +104,7 @@ with other backends. see #9125. Use `-d:nimLegacyJsRound` for previous behavior.
   `-d:nimLegacyParseQueryStrict`. `cgi.decodeData` which uses the same
   underlying code is also updated the same way.
 
+- Added `sugar.dumpToString` which improves on `sugar.dump`.
 
 
 

lib/pure/sugar.nim

@@ -156,16 +156,45 @@ macro dump*(x: untyped): untyped =
   ## It accepts any expression and prints a textual representation
   ## of the tree representing the expression - as it would appear in
   ## source code - together with the value of the expression.
+  ##
+  ## See also: `dumpToString` which is more convenient and useful since
+  ## it expands intermediate templates/macros, returns a string instead of
+  ## calling `echo`, and works with statements and expressions.
   runnableExamples:
     let
       x = 10
       y = 20
-    dump(x + y) # will print `x + y = 30`
+    if false: dump(x + y) # if true would print `x + y = 30`
 
   let s = x.toStrLit
-  let r = quote do:
+  result = quote do:
     debugEcho `s`, " = ", `x`
-  return r
+
+macro dumpToStringImpl(s: static string, x: typed): string =
+  let s2 = x.toStrLit
+  if x.typeKind == ntyVoid:
+    result = quote do:
+      `s` & ": " & `s2`
+  else:
+    result = quote do:
+      `s` & ": " & `s2` & " = " & $`x`
+
+macro dumpToString*(x: untyped): string =
+  ## Returns the content of a statement or expression `x` after semantic analysis,
+  ## useful for debugging.
+  runnableExamples:
+    const a = 1
+    let x = 10
+    doAssert dumpToString(a + 2) == "a + 2: 3 = 3"
+    doAssert dumpToString(a + x) == "a + x: 1 + x = 11"
+    template square(x): untyped = x * x
+    doAssert dumpToString(square(x)) == "square(x): x * x = 100"
+    doAssert not compiles dumpToString(1 + nonexistant)
+    import std/strutils
+    doAssert "failedAssertImpl" in dumpToString(doAssert true) # example with a statement
+  result = newCall(bindSym"dumpToStringImpl")
+  result.add newLit repr(x)
+  result.add x
 
 # TODO: consider exporting this in macros.nim
 proc freshIdentNodes(ast: NimNode): NimNode =

tests/stdlib/tsugar.nim

@@ -107,4 +107,14 @@ doAssert collect(for d in data.items: {d}) == data.toHashSet
 # bug #14332
 template foo =
   discard collect(newSeq, for i in 1..3: i)
-foo()
+foo()
+
+block: # dumpToString
+  template square(x): untyped = x * x
+  let x = 10
+  doAssert dumpToString(square(x)) == "square(x): x * x = 100"
+  let s = dumpToString(doAssert 1+1 == 2)
+  doAssert "failedAssertImpl" in s
+  let s2 = dumpToString:
+    doAssertRaises(AssertionDefect): doAssert false
+  doAssert "except AssertionDefect" in s2