letUtils.nim

## A collection of small templates and macros that aid in limiting the scope of mutable `var`\iables
## as much as practical.

import std/macros
when (NimMajor, NimMinor) >= (1, 2):
  import std/with

func unreachable {.noReturn, inline.} = discard

template scope*(body: untyped): untyped =
  ##[
    Open a new lexical scope (variables declared in the body are not accessible outside). Similar
    to the built-in `block` `language construct`_ but does not interfere with `break`. All credits
    for the implementation go to **@markspanbroek**.

    Unlabeled `break` inside a `block` has been deprecated in Nim 2.0; `see details and rationale
    <https://github.com/nim-lang/Nim/pull/20785>`_.

    .. _language construct: https://nim-lang.org/docs/manual.html#statements-and-expressions-block-expression
  ]##
  if true:
    body
  else:
    discard # Required to work around a bug in the compiler.
    unreachable()

template asLet*(val, name, body: untyped): untyped =
  ##[
    Equivalent to:

    .. code-block:: nim
      let name = val
      body
      name

    **Example:**

    .. code-block:: nim
      processObj:
        getObj().asLet obj:
          obj.field = 1
  ]##
  scope:
    let name = val
    body
    name

when declared with:
  template asLet*(val, body: untyped): untyped =
    ##[
      Equivalent to:

      .. code-block:: nim
        let tmp = val
        with tmp:
          body
        tmp

      **Example:**

      .. code-block:: nim
        processObj:
          getObj().asLet:
            field = 1

      **Since:** Nim 1.2.

      **See also:**
      * `std/with <https://nim-lang.org/docs/with.html>`_
    ]##
    scope:
      let tmp = val
      with tmp:
        body
      tmp

template asVar*(val, name, body: untyped): untyped =
  ##[
    Equivalent to:

    .. code-block:: nim
      var name = val
      body
      name

    **Example:**

    .. code-block:: nim
      from std/strbasics import strip

      processStr:
        getStr().asVar s:
          s.strip
  ]##
  scope:
    var name = val
    body
    name

when declared with:
  template asVar*(val, body: untyped): untyped =
    ##[
      Equivalent to:

      .. code-block:: nim
        var tmp = val
        with tmp:
          body
        tmp

      **Example:**

      .. code-block:: nim
        from std/strbasics import strip

        assert " test\n".asVar(strip) == "test"

      **Since:** Nim 1.2.

      **See also:**
      * `std/with <https://nim-lang.org/docs/with.html>`_
    ]##
    scope:
      var tmp = val
      with tmp:
        body
      tmp

template viaVar*[T](t: type[T]; name, body: untyped): T =
  ##[
    Equivalent to:

    .. code-block:: nim
      var name: T
      body
      name

    **Example:**

    .. code-block:: nim
      processSeq:
        seq[string].viaVar data:
          for i in 0 ..< 5:
            data &= $i

    **See also:**
    * `std/sugar: collect <https://nim-lang.org/docs/sugar.html#collect.m%2Cuntyped>`_
    * `iterrr <https://github.com/hamidb80/iterrr>`_
  ]##
  scope:
    var name: T
    body
    name

when declared with:
  template viaVar*[T](t: type[T]; body: untyped): T =
    ##[
      Equivalent to:

      .. code-block:: nim
        var tmp: T
        with tmp:
          body
        tmp

      **Example:**

      .. code-block:: nim
        run:
          Config.viaVar:
            logFile = "prog.log"
            verbosity = 1
            merge loadFromFile "config.kdl"

      **Since:** Nim 1.2.

      **See also:**
      * `std/with <https://nim-lang.org/docs/with.html>`_
    ]##
    scope:
      var tmp: T
      with tmp:
        body
      tmp

macro freezeVars*(body: untyped): untyped =
  ##[
    Create a `let` binding for each top-level `var` in `body`; make other declarations inaccessible
    from outside.

    **Example:**

    .. code-block:: nim
      freezeVars:
        var fib = @[0, 1]
        for i in 2 ..< 13:
          fib &= fib[^1] + fib[^2]
      # From now on, you cannot modify `fib`.
      echo fib
      assert not compiles (fib[0] = 123)

    **Example:**

    .. code-block:: nim
      proc process(id: int): bool =
        freezeVars:
          var thing = findById id
          if thing == nil:
            if id < 0:
              return false
            thing = insert id

        validate thing
  ]##
  let letTuple = nnkVarTuple.newNimNode # To be assigned outside `body`.
  let varTupleConstr = nnkTupleConstr.newNimNode # Forwarded from inside.

  func recurse(body: NimNode) =
    for node in body:
      case node.kind:
        of nnkVarSection:
          for defs in node:
            for i in 0 ..< defs.len - 2:
              let varIdent = defs[i]
              letTuple.add varIdent
              varTupleConstr.add varIdent
        of nnkStmtList: # `body` can have nested statement lists if was generated by a macro.
          node.recurse
        else:
          discard

  body.expectKind nnkStmtList
  body.recurse
  if letTuple.len == 0:
    body
  else:
    nnkLetSection.newNimNode.add letTuple.add(
      newEmptyNode(),
      bindSym"scope".newCall body.add varTupleConstr,
    )