multi-methods need to be explicitly enabled (#10856)

* multi-methods need to be explicitly enabled

* update changelog, manual and tutorial

8 files changed, 36 insertions, 7 deletions

diff --git a/changelog.md b/changelog.md
index 4cfc9f490..2fb80dfc5 100644
--- a/changelog.md
+++ b/changelog.md
@@ -21,24 +21,35 @@
   your previous annotations with `parallel for`.
 
 - The `unchecked` pragma was removed, instead use `system.UncheckedArray`.
+
 - The undocumented ``#? strongSpaces`` parsing mode has been removed.
+
 - The `not` operator is now always a unary operator, this means that code like
   ``assert not isFalse(3)`` compiles.
+
 - `getImpl` on a `var` or `let` symbol will now return the full `IdentDefs`
   tree from the symbol declaration instead of just the initializer portion.
 
+- To use multi-methods, explicit `--multimethods:on` is now needed.
+
 
 #### Breaking changes in the standard library
 
 - `osproc.execProcess` now also takes a `workingDir` parameter.
 
-- `options.UnpackError` is no longer a ref type and inherits from `system.Defect` instead of `system.ValueError`.
+- `options.UnpackError` is no longer a ref type and inherits from `system.Defect`
+  instead of `system.ValueError`.
 
 - `system.ValueError` now inherits from `system.CatchableError` instead of `system.Defect`.
 
-- The procs `parseutils.parseBiggsetInt`, `parseutils.parseInt`, `parseutils.parseBiggestUInt` and `parseutils.parseUInt` now raise a `ValueError` when the parsed integer is outside of the valid range. Previously they sometimes raised a `OverflowError` and sometimes returned `0`.
+- The procs `parseutils.parseBiggsetInt`, `parseutils.parseInt`,
+  `parseutils.parseBiggestUInt` and `parseutils.parseUInt` now raise a
+  `ValueError` when the parsed integer is outside of the valid range.
+  Previously they sometimes raised a `OverflowError` and sometimes returned `0`.
 
-- `streams.StreamObject` now restricts its fields to only raise `system.Defect`, `system.IOError` and `system.OSError`. This change only affects custom stream implementations.
+- `streams.StreamObject` now restricts its fields to only raise `system.Defect`,
+  `system.IOError` and `system.OSError`.
+  This change only affects custom stream implementations.
 
 - nre's `RegexMatch.{captureBounds,captures}[]`  no longer return `Option` or
   `nil`/`""`, respectivly. Use the newly added `n in p.captures` method to
@@ -61,7 +72,10 @@
 
 - splitFile now correctly handles edge cases, see #10047
 
-- `isNil` is no longer false for undefined in the JavaScript backend: now it's true for both nil and undefined. Use `isNull` or `isUndefined` if you need exact equallity: `isNil` is consistent with `===`, `isNull` and `isUndefined` with `==`.
+- `isNil` is no longer false for undefined in the JavaScript backend:
+  now it's true for both nil and undefined.
+  Use `isNull` or `isUndefined` if you need exact equallity:
+  `isNil` is consistent with `===`, `isNull` and `isUndefined` with `==`.
 
 - several deprecated modules were removed: `ssl`, `matchers`, `httpserver`,
   `unsigned`, `actors`, `parseurl`
@@ -132,6 +146,7 @@ proc enumToString*(enums: openArray[enum]): string =
 
 - Added `system.default`.
 
+
 ### Library changes
 
 - The string output of `macros.lispRepr` proc has been tweaked
diff --git a/compiler/cgmeth.nim b/compiler/cgmeth.nim
index 3c329ca05..c97b1b1aa 100644
--- a/compiler/cgmeth.nim
+++ b/compiler/cgmeth.nim
@@ -290,6 +290,9 @@ proc generateMethodDispatchers*(g: ModuleGraph): PNode =
     var relevantCols = initIntSet()
     for col in countup(1, sonsLen(g.methods[bucket].methods[0].typ) - 1):
       if relevantCol(g.methods[bucket].methods, col): incl(relevantCols, col)
+      if optMultiMethods notin g.config.globalOptions:
+        # if multi-methods are not enabled, we are interested only in the first field
+        break
     sortBucket(g.methods[bucket].methods, relevantCols)
     addSon(result,
            newSymNode(genDispatcher(g, g.methods[bucket].methods, relevantCols)))
diff --git a/compiler/commands.nim b/compiler/commands.nim
index ee16702a2..2bccc4d81 100644
--- a/compiler/commands.nim
+++ b/compiler/commands.nim
@@ -758,6 +758,8 @@ proc processSwitch*(switch, arg: string, pass: TCmdLinePass, info: TLineInfo;
     defineSymbol(conf.symbols, "cppCompileToNamespace", conf.cppCustomNamespace)
   of "docinternal":
     processOnOffSwitchG(conf, {optDocInternal}, arg, pass, info)
+  of "multimethods":
+    processOnOffSwitchG(conf, {optMultiMethods}, arg, pass, info)
   else:
     if strutils.find(switch, '.') >= 0: options.setConfigVar(conf, switch, arg)
     else: invalidCmdLineOption(conf, pass, switch, info)
diff --git a/compiler/options.nim b/compiler/options.nim
index d031da089..cf89e3488 100644
--- a/compiler/options.nim
+++ b/compiler/options.nim
@@ -83,6 +83,7 @@ type                          # please make sure we have under 32 options
     optHotCodeReloading
     optDynlibOverrideAll
     optNimV2
+    optMultiMethods
 
   TGlobalOptions* = set[TGlobalOption]
 
diff --git a/doc/advopt.txt b/doc/advopt.txt
index 4dd710107..46b9a12a6 100644
--- a/doc/advopt.txt
+++ b/doc/advopt.txt
@@ -13,7 +13,7 @@ Advanced commands:
   //genDepend               generate a DOT file containing the
                           module dependency graph
   //dump                    dump all defined conditionals and search paths
-                            see also: --dump.format:json (useful with: ` | jq`)
+                          see also: --dump.format:json (useful with: ` | jq`)
   //check                   checks the project for syntax and semantic
 
 Runtime checks (see -x):
@@ -78,7 +78,8 @@ Advanced options:
   --tlsEmulation:on|off     turn thread local storage emulation on|off
   --taintMode:on|off        turn taint mode on|off
   --implicitStatic:on|off   turn implicit compile time evaluation on|off
-  --patterns:on|off         turn pattern matching on|off
+  --patterns:on|off         turn term rewriting macros on|off
+  --multimethods:on|off     turn multi-methods on|off
   --memTracker:on|off       turn memory tracker on|off
   --hotCodeReloading:on|off
                             turn support for hot code reloading on|off
diff --git a/doc/manual.rst b/doc/manual.rst
index 09daf4a95..7ed7900e9 100644
--- a/doc/manual.rst
+++ b/doc/manual.rst
@@ -3716,6 +3716,9 @@ The ``[]`` subscript operator for arrays/openarrays/sequences can be overloaded.
 Multi-methods
 =============
 
+**Note:** Starting from Nim 0.20, to use multi-methods one must explicitly pass
+``--multimethods:on`` when compiling.
+
 Procedures always use static dispatch. Multi-methods use dynamic
 dispatch. For dynamic dispatch to work on an object it should be a reference
 type as well.
@@ -6222,7 +6225,7 @@ Predicate                Meaning
 ===================      =====================================================
 
 Predicates that share their name with a keyword have to be escaped with
-backticks: `` `const` ``.
+backticks.
 The ``alias`` and ``noalias`` predicates refer not only to the matching AST,
 but also to every other bound parameter; syntactically they need to occur after
 the ordinary AST predicates:
diff --git a/doc/tut2.rst b/doc/tut2.rst
index 4c1ec5747..5856b9fde 100644
--- a/doc/tut2.rst
+++ b/doc/tut2.rst
@@ -308,6 +308,9 @@ Note that in the example the constructors ``newLit`` and ``newPlus`` are procs
 because it makes more sense for them to use static binding, but ``eval`` is a
 method because it requires dynamic binding.
 
+**Note:** Starting from Nim 0.20, to use multi-methods one must explicitly pass
+``--multimethods:on`` when compiling.
+
 In a multi-method all parameters that have an object type are used for the
 dispatching:
 
diff --git a/tests/method/nim.cfg b/tests/method/nim.cfg
new file mode 100644
index 000000000..57698b028
--- /dev/null
+++ b/tests/method/nim.cfg
@@ -0,0 +1 @@
+multimethods:on