fix #16993, #18054, #17835 runnableExamples now works with templates and nested templates (#18082)

2026-04-19 14:00:35 +00:00 · 2021-06-02 09:02:14 -07:00
parent 4ee6eddad4
commit 0de3d4292f
8 changed files with 108 additions and 46 deletions
--- a/compiler/evaltempl.nim
+++ b/compiler/evaltempl.nim
@@ -83,10 +83,14 @@ proc evalTemplateAux(templ, actual: PNode, c: var TemplCtx, result: PNode) =
        not c.isDeclarative:
      c.isDeclarative = true
      isDeclarative = true
-    var res = copyNode(c, templ, actual)
-    for i in 0..<templ.len:
-      evalTemplateAux(templ[i], actual, c, res)
-    result.add res
+    if (not c.isDeclarative) and templ.kind in nkCallKinds and isRunnableExamples(templ[0]):
+      # fixes bug #16993, bug #18054
+      discard
+    else:
+      var res = copyNode(c, templ, actual)
+      for i in 0..<templ.len:
+        evalTemplateAux(templ[i], actual, c, res)
+      result.add res
    if isDeclarative: c.isDeclarative = false

 const
--- a/lib/system/assertions.nim
+++ b/lib/system/assertions.nim
@@ -3,35 +3,6 @@
 ## **Note:** This module is reexported by `system` and thus does not need to be
 ## imported directly (with `system/assertions`).

-runnableExamples:
-  # assert
-  assert 1 == 1
-
-  # onFailedAssert
-  block:
-    type MyError = object of CatchableError
-      lineinfo: tuple[filename: string, line: int, column: int]
-
-    # block-wide policy to change the failed assert
-    # exception type in order to include a lineinfo
-    onFailedAssert(msg):
-      var e = new(MyError)
-      e.msg = msg
-      e.lineinfo = instantiationInfo(-2)
-      raise e
-
-  # doAssert
-  doAssert 1 == 1 # generates code even when built with `-d:danger` or `--assertions:off`
-
-  # doAssertRaises
-  doAssertRaises(ValueError):
-    raise newException(ValueError, "Hello World")
-
-runnableExamples("--assertions:off"):
-  assert 1 == 2 # no code generated
-
-# xxx pending bug #16993: move runnableExamples to respective templates
-
 when not declared(sysFatal):
  include "system/fatal"

@@ -86,21 +57,39 @@ template assert*(cond: untyped, msg = "") =
  ##
  ## No code will be generated for `assert` when passing `-d:danger` (implied by `--assertions:off`).
  ## See `command line switches <nimc.html#compiler-usage-commandminusline-switches>`_.
+  runnableExamples: assert 1 == 1
+  runnableExamples("--assertions:off"):
+    assert 1 == 2 # no code generated, no failure here
+  runnableExamples("-d:danger"): assert 1 == 2 # ditto
  assertImpl(cond, msg, astToStr(cond), compileOption("assertions"))

 template doAssert*(cond: untyped, msg = "") =
  ## Similar to `assert <#assert.t,untyped,string>`_ but is always turned on regardless of `--assertions`.
+  runnableExamples:
+    doAssert 1 == 1 # generates code even when built with `-d:danger` or `--assertions:off`
  assertImpl(cond, msg, astToStr(cond), true)

 template onFailedAssert*(msg, code: untyped): untyped {.dirty.} =
  ## Sets an assertion failure handler that will intercept any assert
  ## statements following `onFailedAssert` in the current scope.
+  runnableExamples:
+    type MyError = object of CatchableError
+      lineinfo: tuple[filename: string, line: int, column: int]
+    # block-wide policy to change the failed assert exception type in order to
+    # include a lineinfo
+    onFailedAssert(msg):
+      raise (ref MyError)(msg: msg, lineinfo: instantiationInfo(-2))
+    doAssertRaises(MyError): doAssert false
  template failedAssertImpl(msgIMPL: string): untyped {.dirty.} =
    let msg = msgIMPL
    code

 template doAssertRaises*(exception: typedesc, code: untyped) =
  ## Raises `AssertionDefect` if specified `code` does not raise `exception`.
+  runnableExamples:
+    doAssertRaises(ValueError): raise newException(ValueError, "Hello World")
+    doAssertRaises(CatchableError): raise newException(ValueError, "Hello World")
+    doAssertRaises(AssertionDefect): doAssert false
  var wrong = false
  const begin = "expected raising '" & astToStr(exception) & "', instead"
  const msgEnd = " by: " & astToStr(code)
--- a/nimdoc/testproject/expected/subdir/subdir_b/utils.html
+++ b/nimdoc/testproject/expected/subdir/subdir_b/utils.html
@@ -206,9 +206,9 @@ constructor.
 <dt><pre><span class="Keyword">template</span> <a href="#fromUtilsGen.t"><span class="Identifier">fromUtilsGen</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">untyped</span></pre></dt>
 <dd>

-this should be shown in utils.html
+should be shown in utils.html only
 <p><strong class="examples_text">Example:</strong></p>
-<pre class="listing"><span class="Identifier">assert</span> <span class="DecNumber">3</span><span class="Operator">*</span><span class="DecNumber">2</span> <span class="Operator">==</span> <span class="DecNumber">6</span></pre>ditto
+<pre class="listing"><span class="Keyword">discard</span> <span class="StringLit">&quot;should be in utils.html only, not in module that calls fromUtilsGen&quot;</span></pre>ditto

 </dd>

--- a/nimdoc/testproject/expected/testproject.html
+++ b/nimdoc/testproject/expected/testproject.html
@@ -431,10 +431,7 @@ window.addEventListener('DOMContentLoaded', main);
 <span class="Keyword">discard</span> <span class="StringLit">&quot;in top2&quot;</span></pre>top2 after
 <p><strong class="examples_text">Example:</strong></p>
 <pre class="listing"><span class="Keyword">import</span> <span class="Identifier">testproject</span>
-<span class="Keyword">discard</span> <span class="StringLit">&quot;in top3&quot;</span></pre>top3 after
-<p><strong class="examples_text">Example:</strong></p>
-<pre class="listing"><span class="Keyword">import</span> <span class="Identifier">testproject</span>
-<span class="Identifier">assert</span> <span class="DecNumber">3</span><span class="Operator">*</span><span class="DecNumber">2</span> <span class="Operator">==</span> <span class="DecNumber">6</span></pre></p>
+<span class="Keyword">discard</span> <span class="StringLit">&quot;in top3&quot;</span></pre>top3 after</p>
  <div class="section" id="6">
 <h1><a class="toc-backref" href="#6">Imports</a></h1>
 <dl class="item">
@@ -574,7 +571,8 @@ My someFunc. Stuff in <tt class="docutils literal"><span class="pre"><span class

 came form utils but should be shown where <tt class="docutils literal"><span class="pre"><span class="Identifier">fromUtilsGen</span></span></tt> is called
 <p><strong class="examples_text">Example:</strong></p>
-<pre class="listing"><span class="Keyword">discard</span> <span class="DecNumber">1</span></pre>
+<pre class="listing"><span class="Keyword">discard</span> <span class="LongStringLit">&quot;&quot;&quot;should be shown as examples for fromUtils3
+       in module calling fromUtilsGen&quot;&quot;&quot;</span></pre>

 </dd>
 <a id="isValid,T"></a>
@@ -957,6 +955,9 @@ cz18
 <dd>

 ok3
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Keyword">discard</span> <span class="LongStringLit">&quot;&quot;&quot;should be shown as examples for fromUtils2
+       in module calling fromUtilsGen&quot;&quot;&quot;</span></pre>

 </dd>
 <a id="z6t.t"></a>
--- a/nimdoc/testproject/subdir/subdir_b/utils.nim
+++ b/nimdoc/testproject/subdir/subdir_b/utils.nim
@@ -50,9 +50,9 @@ template bEnum*(): untyped =
    discard

 template fromUtilsGen*(): untyped =
-  ## this should be shown in utils.html
+  ## should be shown in utils.html only
  runnableExamples:
-    assert 3*2 == 6
+    discard "should be in utils.html only, not in module that calls fromUtilsGen"
  ## ditto

  iterator fromUtils1*(): int =
@@ -64,7 +64,11 @@ template fromUtilsGen*(): untyped =

  template fromUtils2*() =
    ## ok3
+    runnableExamples:
+      discard """should be shown as examples for fromUtils2
+       in module calling fromUtilsGen"""

  proc fromUtils3*() =
    ## came form utils but should be shown where `fromUtilsGen` is called
-    runnableExamples: discard 1
+    runnableExamples: discard """should be shown as examples for fromUtils3
+       in module calling fromUtilsGen"""
--- a/tests/js/tstdlib_various.nim
+++ b/tests/js/tstdlib_various.nim
@@ -153,7 +153,7 @@ block tsplit2:
  var errored = false
  try:
    discard "hello".split("")
-  except AssertionError:
+  except AssertionDefect:
    errored = true
  doAssert errored

--- a/tests/nimdoc/trunnableexamples.nim
+++ b/tests/nimdoc/trunnableexamples.nim
@@ -1,6 +1,7 @@
 discard """
-cmd: "nim doc --doccmd:-d:testFooExternal --hints:off $file"
+cmd: "nim doc --doccmd:--hints:off --hints:off $file"
 action: "compile"
+nimoutFull: true
 nimout: '''
 foo1
 foo2
@@ -8,12 +9,23 @@ foo3
 foo5
 foo6
 foo7
+in examplesInTemplate1
+doc in outer
+doc in inner1
+doc in inner2
 foo8
 foo9
 '''
 joinable: false
 """

+#[
+pending bug #18077, use instead:
+cmd: "nim doc --doccmd:'-d:testFooExternal --hints:off' --hints:off $file"
+and merge trunnableexamples2 back here
+]#
+{.define(testFooExternal).}
+
 proc fun*() =
  runnableExamples:
    block: # `defer` only allowed inside a block
@@ -109,6 +121,47 @@ when true: # runnableExamples with rdoccmd
    # passing seq (to run with multiple compilation options)
    runnableExamples(@["-b:cpp", "-b:js"]): discard

+when true: # bug #16993
+  template examplesInTemplate1*(cond: untyped) =
+    ## in examplesInTemplate1
+    runnableExamples:
+      echo "in examplesInTemplate1"
+    discard
+  examplesInTemplate1 true
+  examplesInTemplate1 true
+  examplesInTemplate1 true
+
+when true: # bug #18054
+  template outer*(body: untyped) =
+    ## outer template doc string.
+    runnableExamples:
+      echo "doc in outer"
+    ##
+    template inner1*() =
+      ## inner1 template doc string.
+      runnableExamples:
+        echo "doc in inner1"
+      ##
+
+    template inner2*() =
+      ## inner2 template doc string.
+      runnableExamples:
+        echo "doc in inner2"
+    body
+  outer:
+    inner1()
+    inner2()
+
+when true: # bug #17835
+  template anyItFake*(s, pred: untyped): bool =
+    ## Foo
+    runnableExamples: discard
+    true
+
+  proc anyItFakeMain*(n: seq[int]): bool =
+    result = anyItFake(n, it == 0)
+      # this was giving: Error: runnableExamples must appear before the first non-comment statement
+
 runnableExamples:
  block: # bug #17279
    when int.sizeof == 8:
@@ -118,7 +171,7 @@ runnableExamples:
  # bug #13491
  block:
    proc fun(): int = doAssert false
-    doAssertRaises(AssertionError, (discard fun()))
+    doAssertRaises(AssertionDefect, (discard fun()))

  block:
    template foo(body) = discard
--- a/tests/nimdoc/trunnableexamples2.nim
+++ b/tests/nimdoc/trunnableexamples2.nim
@@ -0,0 +1,11 @@
+discard """
+cmd: "nim doc --doccmd:-d:testFooExternal --hints:off $file"
+action: "compile"
+joinable: false
+"""
+
+# pending bug #18077, merge back inside trunnableexamples.nim
+when true: # runnableExamples with rdoccmd
+  runnableExamples "-d:testFoo -d:testBar":
+    doAssert defined(testFoo) and defined(testBar)
+    doAssert defined(testFooExternal)