Merge pull request #486 from gradha/pr_idetools_docs

Adds idetools docs

tests/caas/absurd_nesting.nim

@@ -0,0 +1,29 @@
+# Tries to test the full ownership path generated by idetools.
+
+proc lev1(t1: string) =
+  var temp = t1
+  for i in 0..len(temp)-1:
+    temp[i] = chr(int(temp[i]) + 1)
+
+  proc lev2(t2: string) =
+    var temp = t2
+    for i in 0..len(temp)-1:
+      temp[i] = chr(int(temp[i]) + 1)
+
+    proc lev3(t3: string) =
+      var temp = t3
+      for i in 0..len(temp)-1:
+        temp[i] = chr(int(temp[i]) + 1)
+
+      proc lev4(t4: string) =
+        var temp = t4
+        for i in 0..len(temp)-1:
+          temp[i] = chr(int(temp[i]) + 1)
+
+        echo temp & "(lev4)"
+      lev4(temp & "(lev3)")
+    lev3(temp & "(lev2)")
+  lev2(temp & "(lev1)")
+
+when isMainModule:
+  lev1("abcd")

tests/caas/absurd_nesting.txt

@@ -0,0 +1,29 @@
+absurd_nesting.nim
+
+> c --verbosity:0 --hints:on
+SuccessX
+
+> idetools --track:$TESTNIM,6,6 --def $SILENT
+skVar\tabsurd_nesting.lev1.temp\tstring
+
+> idetools --track:$TESTNIM,21,13 --def $SILENT
+skVar\tabsurd_nesting.lev1.lev2.lev3.lev4.temp\tstring
+
+> idetools --track:$TESTNIM,6,27 --def $SILENT
+skForVar\tabsurd_nesting.lev1.i\tint
+
+> idetools --track:$TESTNIM,21,33 --def $SILENT
+skForVar\tabsurd_nesting.lev1.lev1.lev3.lev4.i\tint
+
+> idetools --track:$TESTNIM,24,8 --def $SILENT
+skProc\tabsurd_nesting.lev1.lev1.lev3.lev4\tproc \(string\)
+
+> idetools --track:$TESTNIM,4,13 --def $SILENT
+skParam\tabsurd_nesting.lev1.t1\tstring
+
+> idetools --track:$TESTNIM,4,13 --def $SILENT
+skParam\tabsurd_nesting.lev1.t1\tstring
+
+> idetools --track:$TESTNIM,19,19 --def $SILENT
+skParam\tabsurd_nesting.lev1.lev2.lev3.lev4.t4\tstring
+

tests/caas/basic-recompile.txt

@@ -1,10 +1,10 @@
 main.nim
-> c
+> c --verbosity:0 --hints:on
 SuccessX
-> c
 # The "Processing" string will be found always in proc mode since each
 # compilation command will generate it. We need to test it only in Caas mode to
 # verify the server is not recompiling again the file.
+CaasRun > c --verbosity:0 --hints:on
 CaasRun ! Processing
-SuccessX
+CaasRun SuccessX
 

tests/caas/compile-suggest.txt

@@ -1,7 +1,7 @@
 main.nim
-> c
+> c --verbosity:0 --hints:on
 SuccessX
-> idetools --trackDirty:main_dirty.nim,$TESTNIM,12,7 --suggest
+> idetools --trackDirty:main_dirty.nim,$TESTNIM,12,7 --suggest $SILENT
 skField\tx
 skField\ty
 

tests/caas/compile-then-def.txt

@@ -1,9 +1,11 @@
 main.nim
-> c
+> c --verbosity:0 --hints:on
 SuccessX
-> idetools --track:$TESTNIM,5,18 --def
+
+> idetools --track:$TESTNIM,5,18 --def --verbosity:0 --hints:on
 strutils.toUpper
 ! SuccessX
-> idetools --track:$TESTNIM,5,18 --def
+
+> idetools --track:$TESTNIM,5,18 --def --verbosity:0 --hints:on
 strutils.toUpper
 ! SuccessX

tests/caas/def-def-compile.txt

@@ -1,10 +1,12 @@
 main.nim
-> idetools --track:$TESTNIM,5,18 --def
+> idetools --track:$TESTNIM,5,18 --def --verbosity:0 --hints:on
 strutils.toUpper
 ! SuccessX
-> idetools --track:$TESTNIM,5,18 --def
+
+> idetools --track:$TESTNIM,5,18 --def --verbosity:0 --hints:on
 strutils.toUpper
 ! SuccessX
-> c
+
+> c --verbosity:0 --hints:on
 SuccessX
 

tests/caas/def-then-compile.txt

@@ -1,7 +1,8 @@
 main.nim
-> idetools --track:$TESTNIM,5,18 --def
+> idetools --track:$TESTNIM,5,18 --def --verbosity:0 --hints:on
 strutils.toUpper
 ! SuccessX
-> c
+
+> c --verbosity:0 --hints:on
 SuccessX
 

tests/caas/forward_declarations.nim

@@ -0,0 +1,15 @@
+# This example shows that idetools returns an empty signature for a forward
+# declared proc in proc/symproc runs, but correctly returns the full signature
+# in caas mode.
+
+proc echoHello(text: string)
+
+proc testForward() =
+  echo "T"
+  echoHello("T")
+
+proc echoHello(text: string) =
+  echo "Hello Mr." & text
+
+when isMainModule:
+  testForward()

tests/caas/forward_declarations.txt

@@ -0,0 +1,9 @@
+forward_declarations.nim
+
+> idetools --track:$TESTNIM,9,5 --def $SILENT
+skProc
+proc \(string\)
+
+> idetools --track:$TESTNIM,5,9 --def $SILENT
+skProc
+proc \(string\)

tests/caas/forward_usages.txt

@@ -0,0 +1,17 @@
+forward_declarations.nim
+
+> c --verbosity:0 --hints:on
+SuccessX
+
+# None of the following return three instances of the echoHello proc, the first
+# being the forward declaration, the second being the usage inside testForward,
+# and the third being the actual implementation.
+
+> idetools --track:$TESTNIM,5,5 --usages $SILENT
+skProc.*\n.*skProc.*\n.*skProc
+
+> idetools --track:$TESTNIM,9,5 --usages $SILENT
+skProc.*\n.*skProc.*\n.*skProc
+
+> idetools --track:$TESTNIM,11,5 --usages $SILENT
+skProc.*\n.*skProc.*\n.*skProc

tests/caas/idetools_api.txt

@@ -1,44 +1,44 @@
 idetools_api.nim
-> c
+> c --verbosity:0 --hints:on
 SuccessX
-> idetools --track:$TESTNIM,4,11 --def
+> idetools --track:$TESTNIM,4,11 --def $SILENT
 def\tskType\tsystem.TFile\tTFile
-> idetools --track:$TESTNIM,5,7 --def
+> idetools --track:$TESTNIM,5,7 --def $SILENT
 def\tskProc\tsystem.Open\tproc \(var TFile, string, TFileMode, int\): bool
-> idetools --track:$TESTNIM,5,21 --def
+> idetools --track:$TESTNIM,5,21 --def $SILENT
 def\tskProc\tsystem.\&\tproc \(string, string\): string\{.noSideEffect.\}
-> idetools --track:$TESTNIM,5,38 --def
+> idetools --track:$TESTNIM,5,38 --def $SILENT
 def\tskEnumField\tsystem.TFileMode.fmWrite\tTFileMode
-> idetools --track:$TESTNIM,7,6 --def
+> idetools --track:$TESTNIM,7,6 --def $SILENT
 def\tskProc\tsystem.Close\tproc \(TFile\)
-> idetools --track:$TESTNIM,12,23 --def
+> idetools --track:$TESTNIM,12,23 --def $SILENT
 def\tskIterator\tunicode.runes\titerator \(string\): TRune
-> idetools --track:$TESTNIM,12,15 --def
+> idetools --track:$TESTNIM,12,15 --def $SILENT
 def\tskTemplate\tsequtils.toSeq\tproc \(expr\): expr
-> idetools --track:$TESTNIM,15,7 --def
+> idetools --track:$TESTNIM,15,7 --def $SILENT
 
 # ProcRun mode will fail the next line, because the type is returned empty.
 def\tskConst\t$MODULE.SOME_SEQUENCE\tseq\[int\]\t
-> idetools --track:$TESTNIM,15,23 --def
+> idetools --track:$TESTNIM,15,23 --def $SILENT
 def\tskProc\tsystem.@\tproc \(array\[IDX, T\]\): seq\[T\]\{.noSideEffect.\}
-> idetools --track:$TESTNIM,17,3 --def
+> idetools --track:$TESTNIM,17,3 --def $SILENT
 
 # ProcRun mode will fail the next line, because the type is returned empty.
 def\tskType\t$MODULE.bad_string\tbad_string\t
-> idetools --track:$TESTNIM,11,24 --def
+> idetools --track:$TESTNIM,11,24 --def $SILENT
 def\tskParam\t$MODULE.test_iterators.filename\tstring
-> idetools --track:$TESTNIM,6,5 --def
+> idetools --track:$TESTNIM,6,5 --def $SILENT
 def\tskVar\t$MODULE.test_enums.o\tTFile
-> idetools --track:$TESTNIM,12,34 --def
+> idetools --track:$TESTNIM,12,34 --def $SILENT
 def\tskLet\t$MODULE.test_iterators.input\tTaintedString
-> idetools --track:$TESTNIM,13,35 --def
+> idetools --track:$TESTNIM,13,35 --def $SILENT
 def\tskForVar\t$MODULE.test_iterators.letter\tTRune
-> idetools --track:$TESTNIM,23,3 --def
+> idetools --track:$TESTNIM,23,3 --def $SILENT
 def\tskResult\t$MODULE.adder.result\tint
-> idetools --track:$TESTNIM,19,6 --def
+> idetools --track:$TESTNIM,19,6 --def $SILENT
 
 # ProcRun mode will fail the next line, because the type is returned empty.
 def\tskField\t$MODULE.TPerson.name\tbad_string\t
 
-> idetools --track:$TESTNIM,43,7 --def
+> idetools --track:$TESTNIM,43,7 --def $SILENT
 def\tskMethod\t$MODULE.eval\tproc \(PPlusExpr\): int\t

tests/caas/issue_416_template_shift.txt

@@ -1,14 +1,14 @@
 issue_416_template_shift.nim
-> c
+> c --verbosity:0 --hints:on
 SuccessX
-> idetools --track:$TESTNIM,12,28 --def
+> idetools --track:$TESTNIM,12,28 --def $SILENT
 def\tskType\tsystem.string\tstring
-> idetools --track:$TESTNIM,12,35 --def
+> idetools --track:$TESTNIM,12,35 --def $SILENT
 def\tskLet\t$MODULE.failtest.input\tTaintedString
 
 # The following fail because they seem shifted one colum to the right.
-> idetools --track:$TESTNIM,12,16 --def
+> idetools --track:$TESTNIM,12,16 --def $SILENT
 def\tskTemplate\tsequtils.toSeq\tproc \(expr\): expr
-> idetools --track:$TESTNIM,12,22 --def
+> idetools --track:$TESTNIM,12,22 --def $SILENT
 def\tskIterator\tunicode.runes\titerator \(string\): TRune
 

tests/caas/issue_452_export_shift.txt

@@ -1,11 +1,11 @@
 issue_452_export_shift.nim
-> c
+> c --verbosity:0 --hints:on
 SuccessX
-> idetools --track:$TESTNIM,2,2 --def
+> idetools --track:$TESTNIM,2,2 --def $SILENT
 def\tskConst\t$MODULE.VERSION_STR1\tstring
-> idetools --track:$TESTNIM,3,2 --def
+> idetools --track:$TESTNIM,3,2 --def $SILENT
 def\tskConst\t$MODULE.VERSION_STR2\tstring
-> idetools --track:$TESTNIM,7,5 --def
+> idetools --track:$TESTNIM,7,5 --def $SILENT
 def\tskProc\t$MODULE.forward1\tproc \(\): string\t
-> idetools --track:$TESTNIM,8,5 --def
+> idetools --track:$TESTNIM,8,5 --def $SILENT
 def\tskProc\t$MODULE.forward2\tproc \(\): string\t

tests/caas/issue_477_dynamic_dispatch.txt

@@ -1,5 +1,5 @@
 issue_477_dynamic_dispatch.nim
 > c --run
 SuccessX
-> idetools --track:issue_477_dynamic_dispatch.nim,19,5 --def
+> idetools --track:issue_477_dynamic_dispatch.nim,19,5 --def $SILENT
 def\tskMethod\tissue_477_dynamic_dispatch.collide\tproc \(TUnit, TThing\)\{.inline.\}

tests/caas/its_full_of_procs.nim

@@ -0,0 +1,29 @@
+import unicode, sequtils
+
+# This example shows that idetools returns proc as signature for everything
+# which can be called. While a clever person would use the second column to
+# differentiate betwen procs, methods and others, why does the output contain
+# incorrect information?
+
+type
+  TThing = object of TObject
+  TUnit = object of TThing
+    x: int
+
+method collide(a, b: TThing) {.inline.} =
+  quit "to override!"
+
+method collide(a: TThing, b: TUnit) {.inline.} =
+  echo "1"
+
+method collide(a: TUnit, b: TThing) {.inline.} =
+  echo "2"
+
+var
+  a, b: TUnit
+
+let
+  input = readFile("its_full_of_procs.nim")
+  letters = toSeq(runes(string(input)))
+
+collide(a, b) # output: 2

tests/caas/its_full_of_procs.txt

@@ -0,0 +1,20 @@
+its_full_of_procs.nim
+
+> idetools --track:$TESTNIM,26,15 --def $SILENT
+skProc
+proc \(
+
+> idetools --track:$TESTNIM,27,21 --def $SILENT
+skIterator
+iterator \(
+!proc \(
+
+> idetools --track:$TESTNIM,29,0 --def $SILENT
+skMethod
+method \(
+!proc \(
+
+> idetools --track:$TESTNIM,27,15 --def $SILENT
+skTemplate
+template \(
+!proc \(

tests/caas/suggest-compile.txt

@@ -1,7 +1,7 @@
 main.nim
-> idetools --trackDirty:main_dirty.nim,$TESTNIM,12,7 --suggest
+> idetools --trackDirty:main_dirty.nim,$TESTNIM,12,7 --suggest $SILENT
 skField\tx
 skField\ty
-> c
+> c --verbosity:0 --hints:on
 SuccessX
 

tests/caasdriver.nim

@@ -59,6 +59,8 @@ const
   modes = [CaasRun, ProcRun, SymbolProcRun]
   filenameReplaceVar = "$TESTNIM"
   moduleReplaceVar = "$MODULE"
+  silentReplaceVar = "$SILENT"
+  silentReplaceText = "--verbosity:0 --hints:off"
 
 var
   TesterDir = getAppDir()
@@ -67,6 +69,7 @@ var
 proc replaceVars(session: var TNimrodSession, text: string): string =
   result = text.replace(filenameReplaceVar, session.filename)
   result = result.replace(moduleReplaceVar, session.modname)
+  result = result.replace(silentReplaceVar, silentReplaceText)
 
 proc startNimrodSession(project, script: string, mode: TRunMode):
                         TNimrodSession =