Skip to the content
Diaspar

06 / 10

Enums and variants

A value that is one of several shapes, and a match that knows the whole list.

An enum lists the shapes a value may take. Each shape is a variant. A variant with fields is built by name, like a record, and a pattern takes it apart the same way.

shapes.dias
(defenum Shape
  (Circle [r])
  (Rect [w h]))

(defn area [shape]
  (match shape
    (Shape.Circle r:) (* 3.14159 r r)
    (Shape.Rect w: h:) (* w h)))

(defn main [args]
  (for [shape #[(Shape.Circle r: 1) (Shape.Rect w: 2 h: 3)]]
    (print f"{shape} has area {(area shape)}")))
Runs in your browser

Try it: Add a variant (Square [side]) to Shape, and a square to the vector in main, without touching area. Diaspar tells you what area forgot.

A variant with fields is constructed with labels, (Shape.Circle r: 1), and it prints the same way. A pattern looks like the construction: (Shape.Circle r:) matches a circle and binds its r.

A variant is reached through its enum

It is Shape.Circle, not Circle. A reader never has to know which enums a module defines, and two enums of one module can each have a variant named Error.

bare.dias
(defenum Shape
  (Circle [r])
  (Rect [w h]))

(defn main [args]
  (print (Circle r: 1)))
Runs in your browser

Try it: Write Shape.Circle, as the report says.

A variant is a value

A variant is a value like a record. A dot reads its fields. Two variants are equal when they are the same shape with the same fields. And it can be an element of a set or a key of a map, like any other value.

values.dias
(defenum Shape
  (Circle [r])
  (Rect [w h]))

(def sizes #{(Shape.Circle r: 1) "small" (Shape.Rect w: 20 h: 30) "large"})

(defn main [args]
  (let [dot (Shape.Circle r: 1)]
    ;; A dot reads a field, as with a record.
    (print dot.r)

    ;; Two variants are equal when they are the same shape with the same fields.
    (print (= dot (Shape.Circle r: 1)))
    (print (= dot (Shape.Circle r: 2)))
    (print (= dot (Shape.Rect w: 1 h: 1)))

    ;; A variant is a value like any other: here it is the key of a map.
    (print (get sizes dot))

    ;; assoc gives a new one.
    (print (assoc dot :r 10))))
Runs in your browser

Try it: Read a field the variant does not have: dot.w. A circle has no width, and the report says which fields it has.

match knows the whole list

The variants of an enum are a closed set, so match can tell when one is missing. It warns, names the variant, and says what to write. Add a variant to an enum, and every match that forgot it shows up.

missing.dias
(defenum Shape
  (Circle [r])
  (Rect [w h])
  (Triangle [base height]))

(defn area [shape]
  (match shape
    (Shape.Circle r:) (* 3.14159 r r)
    (Shape.Rect w: h:) (* w h)))

(defn main [args]
  (print (area (Shape.Rect w: 2 h: 3))))
Runs in your browser

Try it: Add the clause (Shape.Triangle base: height:) (/ (* base height) 2), or a last clause _ 0 for everything else. The warning goes away either way.

The warning comes before the program runs, and the program still runs: it only fails if a triangle arrives.

Variants inside variants

A field of a variant can hold another value of the same enum. That is how a tree is written: a sum of two expressions is an expression. Two short functions walk it, each with one clause for each variant.

tree.dias
;; A variant may hold other variants: here, an expression holds expressions.
(defenum Expr
  (Num [value])
  (Add [left right])
  (Mul [left right]))

(defn evaluate [expr]
  (match expr
    (Expr.Num value:) value
    (Expr.Add left: right:) (+ (evaluate left) (evaluate right))
    (Expr.Mul left: right:) (* (evaluate left) (evaluate right))))

(defn show [expr]
  (match expr
    (Expr.Num value:) (str value)
    (Expr.Add left: right:) f"({(show left)} + {(show right)})"
    (Expr.Mul left: right:) f"{(show left)} * {(show right)}"))

(def sum
  (Expr.Mul
    left: (Expr.Add left: (Expr.Num 1) right: (Expr.Num 2))
    right: (Expr.Num 7)))

(defn main [args]
  (print (show sum) "=" (evaluate sum)))
Runs in your browser

Try it: Add a variant (Neg [value]) for a negated expression, and follow the warnings until both functions handle it.

Variants are for a closed set of cases: states, kinds of errors, the nodes of a syntax tree. For open data, where anyone may add a case, a keyword such as :fast is still the right tool.

Variants without fields

A variant does not need fields. (defenum Mode Fast Slow) is an enum of two plain cases. How such a variant is written is changing this month: Mode.Fast becomes a value by itself, as nil and true are, where it used to be a call, (Mode.Fast). The tour will show them when the new form is in the language that runs on this page. Until then, every variant here has a field.

Next: everything a pattern can say.