sink parameter inference for types that have destructors (#13544)

* ensure capitalize doesn't take an inferred sink parameter

* sink parameter inference: first version, for now disabled. Changed that sink parameters can be consumed multiple times in order to adhere to our spec.

* sink inference can now be disabled with .nosinks; sometimes for proc type interop this is required

* fixes yet another critical DFA bug

* better implementation that also understands if expressions etc

* document sink parameter inference and allow for global disabling

doc/advopt.txt

@@ -49,7 +49,7 @@ Advanced options:
   --import:PATH             add an automatically imported module
   --include:PATH            add an automatically included module
   --nimcache:PATH           set the path used for generated files
-                            see also https://nim-lang.org/docs/nimc.html#compiler-usage-generated-c-code-directory 
+                            see also https://nim-lang.org/docs/nimc.html#compiler-usage-generated-c-code-directory
   -c, --compileOnly:on|off  compile Nim files only; do not assemble or link
   --noLinking:on|off        compile Nim and generated files but do not link
   --noMain:on|off           do not generate a main procedure
@@ -145,3 +145,4 @@ Advanced options:
                             works better with `--stackTrace:on`
                             see also https://nim-lang.github.io/Nim/estp.html
   --benchmarkVM:on|off      enable benchmarking of VM code with cpuTime()
+  --sinkInference:on|off    en-/disable sink parameter inference (default: on)

doc/destructors.rst

@@ -256,6 +256,23 @@ An implementation is allowed, but not required to implement even more move
 optimizations (and the current implementation does not).
 
 
+Sink parameter inference
+========================
+
+The current implementation does a limited form of sink parameter
+inference. The `.nosinks`:idx: pragma can be used to disable this inference
+for a single routine:
+
+.. code-block:: nim
+
+  proc addX(x: T; child: T) {.nosinks.} =
+    x.s.add child
+
+To disable it for a section of code, one can
+use `{.push sinkInference: off.}`...`{.pop.}`.
+
+The details of the inference algorithm are currently undocumented.
+
 
 Rewrite rules
 =============