Coalton Language Documentation

The examples/ directory contains several Coalton projects designed to demonstrate language features and serve as real-world test cases. You can explore these projects to understand different application patterns:

• small-coalton-programs: A collection of small, illustrative programs useful for educational purposes.
• quil-coalton: A monadic parser for Quil implemented in Coalton.
• thih: An implementation of Typing Haskell in Haskell using Coalton.
• fractal: A Mandelbrot viewer demonstrating integration between Coalton, Common Lisp, and SDL2.

The mine TUI has a fixed layout with several key panes:

• Open Files Pane: Lists currently open files. It collapses automatically during editing. Use Ctrl+t to switch to it. Within this pane, use Enter to switch files, c to close, and s to save.
• Project Tree: Displays the file structure of your current .asd project. You can open files directly from here.
• Editor Pane: The primary area for code editing. Switch to it with Ctrl+e.
• REPL Pane: The interactive environment for running code. Switch to it with Ctrl+r.
• Status Line: Located at the bottom, showing recent actions and context-sensitive program information.

All elements are accessible via mouse clicks or keyboard shortcuts.

Packages located in the coalton/experimental directory provide useful functionality that is currently in an experimental stage. These features may undergo significant redesigns, syntax changes, or be moved to a lower-level implementation (such as being integrated directly into the compiler) in future versions.

Use these packages if you need specific functionality that is not yet part of the stable Coalton core, but be aware that your code may require updates if the underlying implementation or syntax changes.

Type checking in Coalton is built upon several core calculus operations defined in the src/typechecker/ directory:

• Unification: Performed via mgu and unify (defined in src/typechecker/unify.lisp).
• Substitution: Performed via apply-substitution (defined in src/typechecker/substitutions.lisp and src/typechecker/expression.lisp).
• Inference: Performed via infer-expression-type (defined in src/typechecker/define.lisp).

The type checker uses a specific traversal logic based on a traverse-block struct, which contains a mapping of how every AST node should be transformed during traversal. All discovered type information is stored within an environment structure (src/typechecker/environment.lisp).

Interfacing Coalton with Lisp is similar to a Foreign Function Interface (FFI). Because Lisp is dynamically typed, it is easy to introduce type errors that Coalton cannot catch at compile time.

Recommendations:

• Be cautious with return types: Always verify that Lisp functions return exactly what you specify in the (lisp (-> ...)) block. Watch out for numerical contagion, nil returns, or unexpected error conditions.
• Use assertions: Be liberal with check-type and other assertions when passing values from Lisp into Coalton-managed code to ensure they adhere to the expected types.

The progn expression allows sequencing multiple expressions, returning the value of the last one.

Flat let syntax: Inside a progn, you can use a special flat let syntax for variable binding and pattern matching. Note that these flat let expressions are not recursive and do not support polymorphism. If you need a polymorphic let, use the standard let syntax wrapping the progn block.

Function definitions implicitly contain a progn block.

;; Using progn with flat let
(define (f x y)
  (progn
    (let x_ = (into x))
    (let y_ = (into y))
    (<> x_ y_)))

;; Pattern matching in flat let
(define (f t)
  (let (Tuple fst snd) = t)
  (+ fst snd))

;; Standard let for polymorphism (required if flat let fails)
(let ((id (fn (x) x)))
  (progn
    (id Unit)
    (id "hello")))

In Coalton, all source functions are fixed-arity.

• Multi-argument functions: A type like A * B -> C represents a single function taking two arguments.
• Currying: To represent curried functions, you use nested arrows. A type like A -> B -> C denotes a function that takes one argument and returns another function. This is the standard way to represent user-written currying in Coalton.

The specialize directive allows you to register a specialized implementation for a generic function. When a call site has matching known types at compile-time, Coalton may rewrite the call to use the specialized function instead of the generic one. This happens automatically during monomorphization.

Important Safety Note: Specialization is not guaranteed. You must ensure that the specialized implementation behaves identically to the original generic definition.

(specialize ⟨generic-fun⟩ ⟨specialized-fun⟩ ⟨specialized-ty⟩)

When a constrained function (a function requiring typeclass dictionaries) is treated as a first-class value, the compiler captures the resolved hidden dictionaries in a closure.

This closure's Common Lisp lambda list matches the remaining visible positional and keyword interface. This allows Common Lisp to perform standard runtime arity and keyword checks on the captured function object.

The pipe macro is a convenience tool for threading a value through a sequence of functions from left to right. Instead of nesting function calls like (h (g (f x))), you can use pipe to list the initial expression followed by the transformations in the order they should be executed.

Key characteristics:

• Execution Order: The first argument is the data, and subsequent arguments are functions applied to the result of the previous step.
• Macro Behavior: Because pipe is a macro, it performs syntactic transformation rather than acting as a standard higher-order function.

(pipe xs
      reverse
      sort
      show)