Tutorial
Cure Tutorial
A guided tour of Cure for newcomers. Fourteen short chapters take you from an
empty directory to a working project that uses dependent types, deep
destructuring, binary parsing, FSMs, a typed supervision tree, a full OTP
application, the REPL, the type checker as a writing tool, and finally a
browsable documentation site produced from your own
.cure
sources.
-
Hello, Cure
Install Cure (from the repo root):
mix deps.get
mix compile
mix escript.build
Now you have a
cure
binary in the project root. Add it to your PATH and run:
cure version
Create a project:
cure new hello
cd hello
cure run lib/main.cure
You should see the project's hello message.
-
The compilation pipeline
Cure compiles
.cure
source through a single dependent pipeline:
elaborate
(surface syntax to
Cure.Core
),
kernel-check
(
Cure.Core.Kernel
validates
the Core term),
erase
(quantitative erasure removes compile-time-only
evidence), and
emit
(BEAM bytecode). There is no unchecked fallback path:
the former classic
lex -> parse -> type check -> optimise -> codegen
pipeline
was deleted and is not available in any mode.
Every stage emits structured events you can subscribe to from Elixir for tooling work.
Run
cure check lib/main.cure
to type-check without producing BEAM output. Use
it in your editor; you will see this command run on every save once you turn on
cure watch lib/ --action check
.
-
Functions, records, ADTs
mod MyApp.Math
type Sign = Positive | Negative | Zero
fn classify(x: Int) -> Sign
| x when x > 0 -> Positive
| x when x < 0 -> Negative
| _ -> Zero
rec Point
x: Int
y: Int
-
fndefines a function. Multiple clauses use|. -
typedefines an ADT (sum type). -
recdefines a record (named product type).
-
Destructuring in
match
match
Cure matches on structure, not just tags. Any combination of tuples, lists, maps, records, and constructors can appear in a pattern and is decomposed on the way in:
mod MatchExamples
type Value = Number(Int) | Person(String)
fn example(value: Value) -> Int =
match value
Number(value) -> value
Person(_name) -> 0
Key shortcuts:
-
Point{x, y}field punning — equivalent toPoint{x: x, y: y}. -
^targetpin operator — compare against a previously-bound value instead of binding fresh. -
Repeated variable names on the same pattern imply equality:
%[x, x]matches only when both slots are equal.
Cons is single-head, so
[a, b | rest]
is not supported directly. Use nested
matches or
Std.Match.first_two/2
. See
Patterns
for the
complete reference.
-
The REPL
cure repl
Try:
cure(1)> 1 + 1
=> 2
cure(2)> :t 42
42 : Int
cure(3)> :effects println("hi")
println("hi") :: ! Io
cure(4)> :load examples/recursion.cure
loaded examples/recursion.cure -> Cure.Recursion
Type
:help
for the full meta-command list. History is persisted to
~/.cure_history
.
-
Refinement types (removed)
Refinement types (predicate-constrained base types such as
{x: Int | x != 0}
)
and their stdlib aliases have been removed for now, pending SMTCoq-style proof
reconstruction. Until they return, use a plain base type and enforce the
invariant with a guard or a runtime check.
-
Path-sensitive refinement (removed)
Path-sensitive refinement (narrowing a variable's type along an
if
/
match
branch) was part of the same removed feature; see section 6.
-
Sigma types
A Sigma type pairs a value with a type that may depend on it:
rec Sized
length: Nat
values: List(Int)
Use Sigma when a piece of data must carry the index it parametrises. The type
checker keeps
n
connected to the vector length through the rest of the
program.
-
Pi types and dependent return
use Std.List
fn append(xs: List(Int), ys: List(Int)) -> List(Int) =
xs <> ys
The return type references the parameter names. At the call site, Cure
substitutes the actual values, normalises the resulting Core term, and compares
it by definitional equality. This means
append(threeVec, threeVec)
is checked
against
Vector(T, 6)
.
-
Holes and totality
While writing a function you don't yet know how to finish, leave a hole:
fn safe_head({t: Type}, xs: List(t)) -> t = ?body
Compile, and Cure tells you the goal type and the local context.
Add
@total true
above a function to require totality:
@total true
fn double(n: Nat) -> Nat
| Z() -> Z()
| S(k) -> S(S(double(k)))
The totality checker classifies functions by coverage and structural recursion.
double
is total because every recursive call shrinks its structural argument
(
S(k)
->
k
).
11. Binary parsing
Cure supports full Erlang-style binary pattern matching in
match
arms,
multi-clause function heads, and
let
bindings. Every segment is
value [:: specifier_chain]
; the specifier chain is hyphen-joined and covers
integer
,
float
,
utf8
/
utf16
/
utf32
,
binary
/
bytes
/
bitstring
/
bits
,
signedness, endianness,
size(expr)
, and
unit(n)
.
fn first_byte(buf: Bitstring) -> Int =
match buf
<<b, _rest::binary>> -> b
<<>> -> 0
The dependent coverage checker reports
E031
when a set of arms does not cover
every inhabitant of the scrutinee. A match with at least one wildcard, or with
both an empty-binary arm (
<<>>
) and an open-ended tail arm
(
<<_, _rest::binary>>
), is exhaustive.
let
bindings accept the same binary patterns:
fn parse_header(buf: Bitstring) -> Int =
let <<tag, _rest::binary>> = buf
tag
A non-exhaustive
let
emits
E034
as a warning; the binding still compiles and
Erlang's
=
raises at runtime on a failed match.
12. FSMs
fsm
is an auto-preluded macro that creates a transparent lifted
gen_statem
module:
fsm Turnstile
state Int
events
Coin -> :keep_state_and_data
Each event branch is checked as an
FsmAction
(
Keep
,
Next
, or
Stop
).
Transition tables are a library-level macro over the same generated
gen_statem
substrate rather than compiler syntax.
13. Documenting your modules
cure doc
produces a browsable, ExDoc-like documentation site from your
.cure
sources. The layout has a persistent left sidebar with every module (optionally
grouped) and any orphan pages you want to ship, and a right pane that renders
the selected page with a local table of contents plus anchored entries for every
public function, type, and protocol.
##
doc comments
##
comments on the line above a
mod
,
fn
,
type
,
rec
, or
interface
definition attach as its docstring. Consecutive
##
blocks separated by blank
lines are merged into a single paragraph-separated body, so you can write a
docstring the way you would write regular prose:
mod Std.List
## Eager, persistent, singly-linked lists.
##
## Every operation recurses over cons cells; there are no runtime
## arrays underneath.
## Examples
blocks
Convention: end a module-level (or important function-level) docstring with an
## Examples
section containing fenced
cure
code. The Markdown renderer
syntax-highlights the block via Makeup, and the examples themselves round-trip
through
mix cure.compile_stdlib
— something the Cure stdlib under
lib/std/
now enforces across every shipped module.
mod MyApp.Math
## Right-to-left function composition.
## `compose(f, g)(x)` is `f(g(x))`.
##
## ## Examples
##
##
cure