Implement typed keyword argument stages and &key support

This commit introduces first-class keyword arguments into Coalton's
function type system and syntax.

Keyword arguments are all-optional. A keyword with a default has
visible binder type T. A keyword without a default has visible binder
type (Optional T). Omitted no-default keywords are treated as None,
making omission and explicit None equivalent for those keys.

Some amount of row polymphism is supported: calling a function that
has more keyword arguments than supplied (e.g., through high-order
gymnastics) will automatically eta-expand into a call with all
arguments supplied.

Type representation: add keyword-stage and entry nodes to parser and
typechecker type ASTs, with pretty-printer support and parser support
for keyword stages in declared types. Unification now understands
keyword stages via closed-row matching logic. Environment metadata and
related plumbing are extended so keyword parameters survive inference,
diagnostics, and documentation paths.

Syntax: add &key support for named definitions and anonymous fn
argument lists; add keyword argument parsing at call sites. Enforce
ordering and validity rules (keywords after positional arguments, no
duplicates, malformed pairs rejected). Add targeted diagnostics for
invalid placement, duplicate binders, malformed call syntax, unknown
keys, and declaration/definition keyword-stage mismatch.

Compilation strategy: preserve a simple runtime model by lowering
keyword stages to ordinary positional calls in canonical keyword
order. Defaulted visible binders are computed from hidden Optional
physical parameters (Some provided value, None uses default
expression). No-default binders flow as Optional directly. This keeps
runtime/codegen on standard lambdas and applications.

Tests: extend parser/type inference/runtime coverage for keyword
syntax and behavior, including nested keyword-lambda regression cases;
update user and internals docs with keyword-stage syntax/semantics and
lowering rationale. Verified with full test run (make test).

Author: stylewarning

.gitignore

@@ -13,3 +13,4 @@ coverage-report/
 benchmarks/benchmarks-game/pidigits
 
 bench.json
+system-index.txt

docs/internals/internals.md

@@ -63,12 +63,20 @@ Parsing of expressions also occurs in this file.
 
 Some constructions are de-sugared directly in parsing. For example, there is no `node-rec`; it is desugared into a `node-let` immediately.
 
+Keyword arguments are parsed here as explicit AST data:
+
+- function/`fn` parameters may include `&key` entries
+- call sites may include keyword argument pairs
+- parser-level validation handles malformed placement, missing values, and duplicates
+
 ### Intermediate representation for types
 
 File: `src/parser/types.lisp`
 
 The IR for types is a relatively straightforward data structure, which are substructures of `ty`. This file also contains the parser for said data structure
 
+Function types can include a keyword stage, represented as `(&key ...)` in type syntax.
+
 ### Transformations of the AST
 
 File: `src/parser/renamer.lisp`
@@ -110,6 +118,18 @@ Type checking relies mainly on:
 
 There are other modules to handle more specific things, but the bulk of the "type calculus" is defined above.
 
+Keyword arguments are represented in the typechecker by a dedicated keyword-stage type node (`keyword-stage-ty`) with keyword entries (`keyword-ty-entry`).
+
+Unification currently treats keyword rows as closed: key sets must match exactly, and corresponding entry types are unified by key name.
+
+During inference, keyword stages are lowered to ordinary positional arguments before codegen:
+
+- defaulted key `k : T` is passed physically as `(Optional T)` and defaulted in the callee
+- no-default key `k : Optional T` is passed physically as `(Optional T)` directly
+- omitted keys lower to `None`
+
+After this lowering, codegen sees only ordinary lambda/application shapes.
+
 ### Environment
 
 File: `src/typechecker/environment.lisp`

docs/intro-to-coalton.md

@@ -197,6 +197,47 @@ Here is an example of using a curried function to transform a list.
   (map (+ 2) nums)) ;; 4 5 6 7
 ```
 
+### Keyword Arguments
+
+Coalton also supports keyword argument stages on functions.
+
+```lisp
+(coalton-toplevel
+  (define (run-job x &key (timeout 1000) tag)
+    (match tag
+      ((Some _) (+ x timeout))
+      ((None) x))))
+```
+
+Rules:
+
+- Keyword arguments must come after positional arguments at call sites.
+- All keyword arguments are omittable.
+- A keyword with a default (for example, `(timeout 1000)`) has binder type `T`.
+- A keyword without a default (for example, `tag`) has binder type `(Optional T)`.
+- Omitting a no-default key is equivalent to passing `None`.
+
+Example calls:
+
+```lisp
+(coalton-toplevel
+  (define a (run-job 10))
+  (define b (run-job 10 :timeout 2000))
+  (define c (run-job 10 :tag (Some "prod"))))
+```
+
+Keyword information is also expressible in explicit types:
+
+```lisp
+(coalton-toplevel
+  (declare run-job
+    (Integer -> (&key :timeout Integer
+                      :tag (Optional String))
+             -> Integer)))
+```
+
+Currying still applies to positional arguments. Once a call reaches a keyword stage, that stage is consumed immediately (using provided keys and defaults/omissions). If you want to intentionally produce a keyword-taking closure after fixing positionals, use eta-expansion with `fn`.
+
 ### Pipelining Syntax and Function Composition
 
 There are convenient syntaxes for composing functions with the `pipe` and `nest` macros.

src/codegen/typecheck-node.lisp

@@ -11,6 +11,36 @@
 
 (in-package #:coalton-impl/codegen/typecheck-node)
 
+(defun erase-keyword-stages (type)
+  "Convert keyword stages in TYPE into physical Optional-arrow form."
+  (declare (type tc:ty type)
+           (values tc:ty &optional))
+  (typecase type
+    (tc:keyword-stage-ty
+      (loop :with out := (erase-keyword-stages (tc:keyword-stage-ty-to type))
+            :for entry :in (reverse (tc:keyword-stage-ty-entries type))
+            :do (setf out
+                      (tc:make-function-type
+                       (erase-keyword-stages
+                        (tc:keyword-entry-physical-type
+                         (tc:keyword-ty-entry-type entry)))
+                       out))
+            :finally (return out)))
+    (tc:tapp
+      (tc:make-tapp
+       :from (erase-keyword-stages (tc:tapp-from type))
+       :to (erase-keyword-stages (tc:tapp-to type))))
+    (t
+      type)))
+
+(defun codegen-unify (subs type1 type2)
+  (declare (type tc:substitution-list subs)
+           (type tc:ty type1 type2)
+           (values tc:substitution-list &optional))
+  (tc:unify subs
+            (erase-keyword-stages type1)
+            (erase-keyword-stages type2)))
+
 (defgeneric typecheck-node (expr env)
   (:documentation "Check that EXPR is valid. Currently only verifies
   that applied functions match their arguments.")
@@ -37,8 +67,8 @@
       (loop :for arg :in (node-application-rands expr)
             :for arg-ty := (typecheck-node arg env) :do
               (progn
-                (setf subs (tc:unify subs (tc:function-type-from type) arg-ty))
-                (setf subs (tc:unify subs arg-ty (tc:function-type-from type)))
+                (setf subs (codegen-unify subs (tc:function-type-from type) arg-ty))
+                (setf subs (codegen-unify subs arg-ty (tc:function-type-from type)))
                 (setf type (tc:function-type-to type))))
       (node-type expr)))
 
@@ -53,8 +83,8 @@
       (loop :for arg :in (node-direct-application-rands expr)
             :for arg-ty := (typecheck-node arg env) :do
               (progn
-                (setf subs (tc:unify subs (tc:function-type-from type) arg-ty))
-                (setf subs (tc:unify subs arg-ty (tc:function-type-from type)))
+                (setf subs (codegen-unify subs (tc:function-type-from type) arg-ty))
+                (setf subs (codegen-unify subs arg-ty (tc:function-type-from type)))
                 (setf type (tc:function-type-to type))))
       (node-type expr)))
 
@@ -71,8 +101,8 @@
           (setf type (tc:function-type-to type))))
 
       (let ((subexpr-ty (typecheck-node (node-abstraction-subexpr expr) env)))
-        (setf subs (tc:unify subs type subexpr-ty))
-        (setf subs (tc:unify subs subexpr-ty type))
+        (setf subs (codegen-unify subs type subexpr-ty))
+        (setf subs (codegen-unify subs subexpr-ty type))
         (node-type expr))))
 
   (:method ((expr node-let) env)
@@ -84,17 +114,17 @@
     (let ((subexpr-ty (typecheck-node (node-let-subexpr expr) env))
 
           (subs nil))
-      (setf subs (tc:unify subs subexpr-ty (node-type expr)))
-      (setf subs (tc:unify subs (node-type expr) subexpr-ty))
+      (setf subs (codegen-unify subs subexpr-ty (node-type expr)))
+      (setf subs (codegen-unify subs (node-type expr) subexpr-ty))
       subexpr-ty))
 
   (:method ((expr node-locally) env)
     (declare (type tc:environment env)
              (values tc:ty))
     (let ((subexpr-ty (typecheck-node (node-locally-subexpr expr) env))
           (subs nil))
-      (setf subs (tc:unify subs subexpr-ty (node-type expr)))
-      (setf subs (tc:unify subs (node-type expr) subexpr-ty))
+      (setf subs (codegen-unify subs subexpr-ty (node-type expr)))
+      (setf subs (codegen-unify subs (node-type expr) subexpr-ty))
       subexpr-ty))
 
   (:method ((expr node-lisp) env)
@@ -123,8 +153,8 @@
       (loop :for branch :in (node-match-branches expr)
             :for subexpr-ty := (typecheck-node branch env) :do
               (progn
-                (setf subs (tc:unify subs type subexpr-ty))
-                (setf subs (tc:unify subs subexpr-ty type))))
+                (setf subs (codegen-unify subs type subexpr-ty))
+                (setf subs (codegen-unify subs subexpr-ty type))))
       type))
 
   (:method ((expr catch-branch) env)
@@ -142,8 +172,8 @@
       (loop :for branch :in (node-catch-branches expr)
             :for subexpr-ty := (typecheck-node branch env) :do
               (progn
-                (setf subs (tc:unify subs type subexpr-ty))
-                (setf subs (tc:unify subs subexpr-ty type))))
+                (setf subs (codegen-unify subs type subexpr-ty))
+                (setf subs (codegen-unify subs subexpr-ty type))))
       type))
 
   (:method ((expr node-resumable) env)
@@ -156,8 +186,8 @@
       (loop :for branch :in (node-resumable-branches expr)
             :for subexpr-ty := (typecheck-node branch env) :do
               (progn
-                (setf subs (tc:unify subs type subexpr-ty))
-                (setf subs (tc:unify subs subexpr-ty type))))
+                (setf subs (codegen-unify subs type subexpr-ty))
+                (setf subs (codegen-unify subs subexpr-ty type))))
       type))
 
   (:method ((expr resumable-branch) env)
@@ -205,8 +235,8 @@
     (let ((last-node (car (last (node-seq-nodes expr))))
 
           (subs nil))
-      (setf subs (tc:unify subs (node-type expr) (node-type last-node)))
-      (setf subs (tc:unify subs (node-type last-node) (node-type expr)))
+      (setf subs (codegen-unify subs (node-type expr) (node-type last-node)))
+      (setf subs (codegen-unify subs (node-type last-node) (node-type expr)))
       (node-type last-node)))
 
   (:method ((expr node-return-from) env)
@@ -230,7 +260,7 @@
   (:method ((expr node-block) env)
     (declare (type tc:environment env)
              (values tc:ty))
-    (tc:unify
+    (codegen-unify
      nil
      (node-type expr)
      (typecheck-node (node-block-body expr) env))
@@ -246,7 +276,7 @@
     (declare (type tc:environment env)
              (values tc:ty))
     (typecheck-node (node-dynamic-extent-node expr) env)
-    (tc:unify
+    (codegen-unify
      nil
      (node-type expr)
      (typecheck-node (node-dynamic-extent-body expr) env))
@@ -256,7 +286,7 @@
     (declare (type tc:environment env)
              (values tc:ty))
     (typecheck-node (node-bind-expr expr) env)
-    (tc:unify
+    (codegen-unify
      nil
      (node-type expr)
      (typecheck-node (node-bind-body expr) env))
@@ -274,14 +304,14 @@
                           (length (node-values-nodes expr))))
       (loop :for subnode :in (node-values-nodes expr)
             :for comp-ty :in components
-            :do (tc:unify nil (typecheck-node subnode env) comp-ty))
+            :do (codegen-unify nil (typecheck-node subnode env) comp-ty))
       (node-type expr)))
 
   (:method ((expr node-mv-call) env)
     (declare (type tc:environment env)
              (values tc:ty))
     (let ((sub-ty (typecheck-node (node-mv-call-expr expr) env)))
-      (tc:unify nil (node-type expr) sub-ty)
+      (codegen-unify nil (node-type expr) sub-ty)
       (node-type expr)))
 
   (:method ((expr node-values-bind) env)
@@ -296,7 +326,7 @@
                           (length components)
                           (length (node-values-bind-vars expr))))
       (typecheck-node (node-values-bind-expr expr) env)
-      (tc:unify nil (node-type expr) (typecheck-node (node-values-bind-body expr) env))
+      (codegen-unify nil (node-type expr) (typecheck-node (node-values-bind-body expr) env))
       (node-type expr)))
 
   (:method ((expr node-values-match) env)
@@ -308,6 +338,6 @@
       (loop :for branch :in (node-values-match-branches expr)
             :for subexpr-ty := (typecheck-node branch env) :do
               (progn
-                (setf subs (tc:unify subs type subexpr-ty))
-                (setf subs (tc:unify subs subexpr-ty type))))
+                (setf subs (codegen-unify subs type subexpr-ty))
+                (setf subs (codegen-unify subs subexpr-ty type))))
       type)))

src/doc/markdown.lisp

@@ -240,21 +240,42 @@
                 (object-aname ty)
                 (html-entities:encode-entities (object-name ty))))))
 
+(defun write-keyword-stage-head (stream stage)
+  (declare (type tc:keyword-stage-ty stage)
+           (values null &optional))
+  (write-string "(&key" stream)
+  (dolist (entry (tc:keyword-stage-ty-entries stage))
+    (write-string " " stream)
+    (write-string (html-entities:encode-entities
+                   (format nil "~S" (tc:keyword-ty-entry-keyword entry)))
+                  stream)
+    (write-string " " stream)
+    (write-string (to-markdown (tc:keyword-ty-entry-type entry)) stream))
+  (write-string ")" stream)
+  nil)
+
 (defmethod to-markdown ((ty tc:tapp))
   (with-output-to-string (stream)
     (cond
       ((tc:function-type-p ty) ;; Print function types
        (write-string "(" stream)
        (write-string (to-markdown (tc:tapp-to (tc:tapp-from ty))) stream)
-       (write-string (html-entities:encode-entities " → ") stream)
-       ;; Avoid printing extra parentheses on curried functions
-       (labels ((print-subfunction (to)
+       ;; Avoid printing extra parentheses on curried functions.
+       ;; A function tail may be a keyword stage, not only a tapp.
+       (labels ((write-arrow ()
+                  (write-string (html-entities:encode-entities " → ") stream))
+                (print-subfunction (to)
                   (cond
-                    ((tc:function-type-p to)
+                    ((typep to 'tc:keyword-stage-ty)
+                     (write-arrow)
+                     (write-keyword-stage-head stream to)
+                     (print-subfunction (tc:keyword-stage-ty-to to)))
+                    ((and (typep to 'tc:tapp) (tc:function-type-p to))
+                     (write-arrow)
                      (write-string (to-markdown (tc:tapp-to (tc:tapp-from to))) stream)
-                     (write-string (html-entities:encode-entities " → ") stream)
                      (print-subfunction (tc:tapp-to to)))
                     (t
+                     (write-arrow)
                      (write-string (to-markdown to) stream)))))
          (print-subfunction (tc:tapp-to ty)))
        (write-string ")" stream))
@@ -277,12 +298,20 @@
               (write-string (to-markdown arg) stream))
             (write-string ")" stream))
            (t
-            (write-string "(" stream)
-            (write-string (to-markdown (tc:tapp-from ty)) stream)
-            (write-string " " stream)
+           (write-string "(" stream)
+           (write-string (to-markdown (tc:tapp-from ty)) stream)
+           (write-string " " stream)
             (write-string (to-markdown (tc:tapp-to ty)) stream)
             (write-string ")" stream))))))))
 
+(defmethod to-markdown ((ty tc:keyword-stage-ty))
+  (with-output-to-string (stream)
+    (write-string "(" stream)
+    (write-keyword-stage-head stream ty)
+    (write-string (html-entities:encode-entities " → ") stream)
+    (write-string (to-markdown (tc:keyword-stage-ty-to ty)) stream)
+    (write-string ")" stream)))
+
 (defmethod to-markdown ((object tc:qualified-ty))
   (let ((preds (tc:qualified-ty-predicates object))
         (qual-type (tc:qualified-ty-type object)))