added operateOn to sugar.nim to give Nim the chaining mechanism it de… (#13092)

* implemented the with stdlib module as specified in https://github.com/nim-lang/RFCs/issues/193
* change sugar.outplace to sugar.dup according to https://github.com/nim-lang/RFCs/issues/193
* changelog update

lib/std/private/underscored_calls.nim

@@ -0,0 +1,38 @@
+
+#
+#
+#            Nim's Runtime Library
+#        (c) Copyright 2020 Andreas Rumpf
+#
+#    See the file "copying.txt", included in this
+#    distribution, for details about the copyright.
+#
+
+## This is an internal helper module. Do not use.
+
+import macros
+
+proc underscoredCall*(n, arg0: NimNode): NimNode =
+  proc underscorePos(n: NimNode): int =
+    for i in 1 ..< n.len:
+      if n[i].eqIdent("_"): return i
+    return -1
+
+  if n.kind in nnkCallKinds:
+    result = copyNimNode(n)
+    result.add n[0]
+
+    let u = underscorePos(n)
+    if u < 0:
+      result.add arg0
+      for i in 1..n.len-1: result.add n[i]
+    else:
+      for i in 1..u-1: result.add n[i]
+      result.add arg0
+      for i in u+1..n.len-1: result.add n[i]
+  else:
+    # handle e.g. 'x.dup(sort)'
+    result = newNimNode(nnkCall, n)
+    result.add n
+    result.add arg0
+

lib/std/with.nim

@@ -0,0 +1,58 @@
+#
+#
+#            Nim's Runtime Library
+#        (c) Copyright 2020 Andreas Rumpf
+#
+#    See the file "copying.txt", included in this
+#    distribution, for details about the copyright.
+#
+
+## This module implements the ``with`` macro for easy
+## function chaining. See https://github.com/nim-lang/RFCs/issues/193
+## and https://github.com/nim-lang/RFCs/issues/192 for details leading to this
+## particular design.
+##
+## **Since** version 1.2.
+
+import macros, private / underscored_calls
+
+macro with*(arg: typed; calls: varargs[untyped]): untyped =
+  ## This macro provides the `chaining`:idx: of function calls.
+  ## It does so by patching every call in `calls` to
+  ## use `arg` as the first argument.
+  ## **This evaluates `arg` multiple times!**
+  runnableExamples:
+    var x = "yay"
+    with x:
+      add "abc"
+      add "efg"
+    doAssert x == "yayabcefg"
+
+    var a = 44
+    with a:
+      += 4
+      -= 5
+    doAssert a == 43
+
+  result = newNimNode(nnkStmtList, arg)
+  expectKind calls, nnkArgList
+  let body =
+    if calls.len == 1 and calls[0].kind in {nnkStmtList, nnkStmtListExpr}:
+      calls[0]
+    else:
+      calls
+  for call in body:
+    result.add underscoredCall(call, arg)
+
+when isMainModule:
+  type
+    Foo = object
+      col, pos: string
+
+  proc setColor(f: var Foo; r, g, b: int) = f.col = $(r, g, b)
+  proc setPosition(f: var Foo; x, y: float) = f.pos = $(x, y)
+
+  var f: Foo
+  with(f, setColor(2, 3, 4), setPosition(0.0, 1.0))
+  echo f
+