let form has surprising scope

[sabjohnso]

The let form in coalton has mutually recursive binding semantics, which I believe will be surprising to most new users as the name is typically associated with sequential and parallel binding, while letrec see greater use for mutually recursive binding. I think adopting more common naming convention would be advantageous.

tl;dr: Below should illustrate my expectations.
The inline documentation for let forms does not give sufficient information to understand the scoping rules for the form:

(cl:describe 'let)

produces the output

COALTON:LET
  [symbol]

LET names a macro:
  Lambda-list: (BINDINGS &BODY FORM)
  Documentation:
    A lexical LET binding.
  Source file: /home/sbj/Sandbox/coalton/src/faux-macros.lisp

which does not specify whether it is sequential or parallel binding. Prodding with some code reveals a probable bug:

(coalton
 (let ((x 3)
       (y (+ x 4)))
   (+ x y)))

leads to the following error:

The variable X-1488 is unbound.
   [Condition of type COMMON-LISP:UNBOUND-VARIABLE]

Further prodding leads to more information, but the unexpected result that scoping rules are neither the anticipated parallel or sequential bind but the mutual recursive binding:

(coalton-toplevel
  (define (my-fun x)
    (let ((x (1+ x))
          (y (* 2 x)))
      (+ x y))))

produces the following error:

error: Invalid recursive bindings
  --> <macroexpansion>:3:11
   |
 3 |      (LET ((X (1+ X)) (Y (* 2 X)))
   |             ^ invalid recursive variable bindings
   [Condition of type COALTON-IMPL/TYPECHECKER/BASE:TC-ERROR]

Namely, the following code would be more suitable to understand the scope:

(coalton
 (let ((even (fn (n)
                (match n
                  (0  True)
                  (n (odd (1- n))))))
       (odd (fn (n)
              (match n
                (0 False)
                (n (even (1- n)))))))
   (odd 3)))

This binding bears more in common with CL's labels, Scheme or Racket's letrec or OCamls
let rec and ought to named accordingly.

Finally, better documentation of the the form is provided by the ast node node-let, which states:

 "Introduction of local mutually-recursive bindings (let ((x 2)) (+ x x))"

but that is not very accessible for coalton users.

[stylewarning]

I agree fully this is surprising behavior and ought to either be much better documented or changed altogether.