The Bjolang manual

Getting started

Bjolang is only installed from source. There are no releases or packages: you clone the repository at github.com/bjoli/Bjolang and build it where it is.

It needs only two things: dotnet 10 and an f# compiler. The .NET 10 SDK comes with both. Once that is installed, clone the repository and build the runtime, the compiler and the standard library:

git clone https://github.com/bjoli/Bjolang
cd Bjolang
dotnet build BjolangRuntime/BjolangRuntime.csproj -c Release
dotnet build -c Release
./build_std.sh

If you want to make sure everything works, run ./run_tests.py and ./run_bjo_tests.py in the same directory. Then you can use the bjo executable in the bjo directory: ./bjo/bjo run hello.bjo. Personally I alias a shell command to the path of bjo, since there currently is no way to install it properly. Compiled programs find the standard library in the directory you built it in, so leave the checkout where it is.

To update, pull and build again:

git pull
./bjo/bjo rebjo
./build_std.sh

Your first bjolang program

Bjolang compiles to c#. Many of the design decisions behind bjolang stems from this limitation. The first one you will encounter is that a program needs a main function. like the one in c#, that returns an int. If execution ended correctly it should return 0 if the program executed successfully.

(: print-hello (-> string unit))
(defun (print-hello name)
  (println (str "Hello, " name "!")))

(defun (main args)
  (print-hello "User")
  0)

This can then be run using bjo run filename, and it should print Hello, User!.

What you can see here is that defun is the form for defining a function. main is special, it needs no type declaration. print-hello is a regular function, and thus has to declare its type. Everything at toplevel needs to do that. The form is (: name type). A function type is declared as (-> ArgType … Return-Type). print-hello takes a string argument and returns unit. unit is the name for nothing.

Declaring types

For most of your bjolang code, you will only declare types in the top level. Types within functions are inferred, so declaring types there is almost never necessary. A value type is declared just like a function, but without the function type declaration:

(: usermap (Map Keyword string))
(def usermap #map((:admin "Linus") (:moderator "Sunil") (:janitor "Björnstam")))

You can also declare your own types. Either aliases of other types, records of your own, or union types.

(type
  (: Suit (Union Hearts Diamonds Clubs Spades))
  (: Card (Struct (: rank byte) (: suit Suit)))
  (: User (Record (: name string)
                  (: age byte)
                  (: favourite-playing-card Card)))))

This can then be destructed using pattern matching.

(: print-user (-> User unit))
(defun (print-user u)
  (match u
    ;; Subpatterns: here we match name, age, the Card rank
    ;; but only succeed if the Suit is Hearts.
    ((User name age (Card rank (Suit Hearts)))
      (println "Oh my god, we got hearts!"))
    ((User (age 100))
      (println "I have no idea which card, but the user is old"))
    ((User name) (println "The user is called ${name}."))
    ;; pattern matching does it's best to do exhaustiveness checks.
    ;; and while it is usually pretty good at figuring out whether
    ;; patterns are exhaustive, sometimes it cannot. Then you will have to add
    ;; a match-all
    (_ (panic! "This should not happen."))))

Editor support

Bjolang was written in emacs, and emacs is currently the only editor with limited bjolang support through the file bjomode.el in the main github repository. It lacks any fancy things, but handles a modicum of indentation and syntax highlighting.

Values, types and signatures

These are the bjolang literals:

Then there are some special cases, like string interpolation:

(let ((an-int 5)
      (a-string "hej"))
  (println $"This is interpolated: ${an-int} ${a-string}")
  ;; Which is literally the same as:
  (println (str "This is interpolated: " (->str an-int) " " (->str a-string))))

Function types

A function takes any number of arguments and produces a value. The signature of a function in bjolang is denoted using the arrow ->:

(: double (-> int int))
(defun (double x)
  ;; the last expression in the body is the return value
  (* x 2))

(:print-n-times (-> string int unit))
(defun (print-n-times what n)
  (loop (:for i (up-from 0 #:to n))
    (println what)))

;; call twice takes a function take takes an argument
;; of type %a and returns unit. 
(: call-twice (-> (-> %a unit) %a unit))
(defun (call-twice f val)
  (f val)
  (f val))

Bjolang also supports keyword arguments. The caller do not have to supply them, and if they are not supplied they are bound to a default expression that is evaluated in the function body.

(: n-times (-> int (#:what string) string))
(defun (n-times n #:what (string-append "place" "holder"))
  (def sb (stringbuilder-empty))
  (loop (:for i (up-from 0 #:to n))
    (stringbuilder-add-string! sb placeholder))
  (stringbuilder->string sb))

;; Calling it now returns:
(n-times 2) ;; -> "placeholderplaceholder"
(n-times 500 #:what "hej!\n") ;; -> "hej!\nhej!\nhej!\n..."

The default expression of the keyword argument is evaluated in the body of the function every time the function is called without a supplied argument. Keywords must also be in the same order in the signature and definition. A function with keywords yields two c# bodies, one with optional arguments and one with the default expressions, UNLESS the default arguments are c# literals. Then the function is a regular c# function with named arguments.

Inference

Everything at the toplevel needs a signature, even values. In a function body, nothing strictly needs a signature. Function bodies are inferred using Hindley Milner type inference. This is of course comfortable, but also has some limits. They type of an undeclared type is inferred at first usage.

;; pretend we are in a function body
(def a (transientmap-empty))
(add! a (:key . 5)) ;; transientmap is pinned to (Transientmap Keyword int).
(add! a (:key2 . "hej")) ;; fails

The example above is of course facile, but it matters more for generic functions with inlined traits. They are pinned to the first use, and any subsequent usage will raise an error. More on this in the trait section.

Naming conventions

Bjolang follows scheme’s naming conventiens. Predicates end with ?. Mutating functions end with !. Conversions are written using ->.

While the base types are lowercase (which is a design mishap), types should be capitalized. Record and struct fields are lower case.

Functions

As you have seen already, functions are declared using defun. Bjolang also has anonymous functions defined using fun:

(list-map (fun (x) (* x x)) (list 1 2 3 4)) ;; -> '(1 4 9 16).
;; there is also a lambda shorthand where argument are numbered
;; using &. & = &1.

(println  (#(+ & &2) 2 3)) ;; -> prints 5.
(println (#(+ &1 &3) 1 2 3)) ;; -> prints 4.

Functions can also be generic, to handle any kind of argument. This is useful if you have a function that does not need to inspect the values.

(: make-tuple (-> (List %a) %b (Tuple %a %b)))
(defun (make-tuple ls val)
  (match ls
    ((Cons car _) (Tuple car val))
    (_ (panic! "this did not work as expected."))))

Generics can also be constrained to work on Traits. For example this signature, for a function that can compare the first element of a tuple with the elements of a Vec.

(: (-> (Tuple %a %b) (Vec %a) bool) (where (Eq %a)))

Local functions and inline signatures

A local function defined inside another function looks like a top-level defun, but does not need a separate (: ...) type signature because local types are inferred automatically with Hindley-Milner type inference. In fact, local functions do not support separate (: ...) signatures at all.

When you want to document types explicitly or constrain inference, you can write the signature inline directly on the defun by annotating each parameter with (: param Type) and following the parameter list with : ReturnType:

(defun (process-numbers ls)
  (defun (clamp (: n int) (: max int)) : int
    (if (> n max) max n))
  (list-map #(clamp & 100) ls))

Parameters can use any type, including type variables for generic local functions:

(defun (pair-up val ls)
  (defun (wrap (: x %a)) : (Tuple %a %b)
    (Tuple x val))
  (list-map wrap ls))

Note that if you supply an inline signature, all parameters and the return type must be annotated together; partial inline annotations are not permitted. Trait constraints (where clauses) and keyword argument defaults cannot be written inline and require top-level signatures.

Bindings and control flow

binding forms

Variables are bound using, primarily, four forms def, def* let, let*. let and let* are the same as in scheme. let binds values in parallel. let* binds sequentially.

(def a 1)
(def b 2)

(let ((a 4) (b (+ a 1)))
  (println a) ;; -> 4
  (println b)) :: -> 5

(let* ((a 4) (b (+ a 1)))
  (println a) ;; 4
  (println b)) ;; 5

def* is a form that mostly just saves on key presses:

(def* (a 5)
      (b 6)
      (c (+ a b)))

conditional executions - if, cond, when, unless, and case

The base form for executing code conditionally is (if test-expr true-expr false-expr). The prelude defines the cond macro that allows for chaining tests:

(def weather (get-weather-symbol))
(if (= weather 'rain)
    (get-umbrella)
    (if (= weather 'windy)
        (get-jacket)
        (get-shorts)))
;; can be written as
(cond
  ((= weather 'rain) (get-umbrella))
  ((= weather 'windy) (get-jacket))
  (else (get-shorts)))

;; which can be written as

(case weather
  ('rain (get-umbrella))
  ('windy (get-jacket))
  (else (get-shorts)))

For the cases where code starts drifting rightward, there are two special clauses in the cond macro, :def and :do. This is taken from actual bjolang code.

(cond
  ((> depth json-max-depth) (Err (too-deep rd "array")))
  ;; this executes two things and binds the variable `mark` before continuing
  (:do
    (step! rd)
    (skip-space! rd))
  (:def mark (record-ref rd top))
  ((at-end? rd) (Err (at rd "the document ended inside an array")))
  ((char=? (peek rd) #\]) (step! rd) (Ok (JsonArr (harvest! rd mark))))
  (else ...))

The above is usually a code smell, but can be useful in managing the kind code drift that sometimes plagues lisp code.

with-return and bailing from failed bindings

Bjolang has 2 solutions to the problem that is sometimes solved by do-notation in functional languages. Thi (with-return ret body ... form binds an espace function to ret, which means code within it can return from the body (but not within local functions). This is often used with the destructuring of the def and def* forms.

Within a with-return you can use the bound label to directly return a value from the with-return block

(with-return ret
  (def a (read-line))
  (when (= "" a)
    (ret 0))
  (println "hej hopp hej hej")
  (string-count a))

The def forms have a particular thing that they do when they are usid with refutable patterns (patterns that can fail). Then they take one of four extra clauses:

(: do-things (-> (List int) (Result string string)))
(defun (do-things ls)
  ;; Try to match a list with 3 elements and return an Err if it fails
  (def (List a b c) ls :leave-with (Err "The string did not have 3 elements"))
  ;; Try get the key "a" from a map and leave with err
  (def (Some elem) (try-ref my-map a) :leave-with (Err "The map lacked a key"))
  ;; open the filename in `elem` and propagate any error. 
  (def (Ok port) (open-input-file elem) :propagate)
  (println "Here we know port is bound. ")
  (Ok "the file exists"))

The other clauses are :default expr that binds the variable to expr if the match fails. This only works with patterns that bind one variable. Then there is :leave which take the other pattern arms:

(def (Ok b) expr :leave ((Err "ojdå") (println "special swedish error encountered") expr)
                        ((Err b) expr))

Mutable bindings

Mutable bindings are defined with def/mutable. They can be mutated with the set! form. Generic local mutable variables generalize at the first set!, and top-level generic bindings are not allowed.

(defun (main args)
  (def/mutable b 0)
  (loop (:for a args)
        (:when (my-special-predicate? a))
        (set! b (+ b a)))
    b)

Your own types

A program without your own types are boring.

Aliases

A type alias is a different name for a type that already exists. It is declared with the type form.

(type (: Stringalias string))

Records and structs

Records and structs are direct mappings to c# records and immutable structs. The constructor is the type name, together with parenthesised fields. As follows.

(type
  (: Ripeness (Union Ripe Megaripe Rotten))
  (: Fruit (Record (: name string)
                   (: amount int)
                   (: ripeness Ripeness))))

(def banana (Fruit (name "banana") (amount 5) (ripeness Rotten)))

A field can be marked #:mutable, to make the record (not struct) mutable. This however makes using the record in places that requires hashing fail at runtime. The mutable fields can be updated with record-set!.

(type (: Reader (: pos integer #:mutable)
                (: port TextInputPort)))

...
(record-set! my-reader pos (+ 1 (record-get my-reader pos)))

Unions

A union is a type whose values are one of several cases. A case either carries nothing, and is then written as a bare name, or it carries a payload, and is then written like a record field: (: CaseName type ...).

(type
  ;; Four cases that carry nothing.
  (: Suit (Union Clubs Diamonds Hearts Spades))
  ;; A card's rank is either a number card, carrying its number, or a court card.
  (: Rank (Union (: Pip int) Jack Queen King Ace))
  ;; A case may carry more than one value.
  (: Shape (Union (: Circle double) (: Rect double double) Empty)))

A case is also its constructor. A case without a payload is a value, and a case with a payload is a function that builds one:

(def trump Hearts)                 ;; Suit
(def seven (Pip 7))                ;; Rank
(def square (Rect 2.0 2.0))        ;; Shape

;; Since (Pip ...) is a function, it can be passed around like one:
(list-map Pip (list 2 3 4))        ;; a (List Rank) of three number cards

You take a union apart with match, which gets its own section below. The short version is that every case gets a clause, and the payload is bound to names:

(: area (-> Shape double))
(defun (area s)
  (match s
    ((Circle r) (* 3.14159 (* r r)))
    ((Rect w h) (* w h))
    (Empty 0.0)))

(area (Rect 2.0 3.0))   ;; 6.0

The compiler checks that a match covers every case. If you add a Triangle to Shape, every match on a shape that does not handle it becomes a compile error, which is most of the reason to use a union in the first place.

Unions can be generic. The type variables go after the type name, just like for records:

(type (: (Maybe %a) (Union Nothing (: Just %a))))
(type (: (Either %l %r) (Union (: Left %l) (: Right %r))))

(: maybe-first (-> (List %a) (Maybe %a)))
(defun (maybe-first xs)
  (match xs
    (() Nothing)
    ((Cons x _) (Just x))))

You never have to write these two, since the prelude already has them under the names (Option %a), with the cases None and Some, and (Result %e %a), with the cases Err and Ok. They are ordinary unions, and they get a section of their own further down.

A few things to know about unions:

• Case names share a namespace with everything else in the module, so two unions in the same module cannot both have a case called Red.
• A union case cannot have a #:mutable field.
• println on a union value without a ->str implementation prints the generated C# name, something like Card { rank = Queen { }, suit = Hearts { } }. Implement ->str (see the traits section) for anything you intend to print.

Types that refer to themselves and each other

A type may mention itself. This is how you write trees, expression languages and anything else recursive:

(type (: (Tree %a) (Union Leaf (: Node (Tree %a) %a (Tree %a)))))

(: tree-insert (-> int (Tree int) (Tree int)))
(defun (tree-insert x t)
  (match t
    (Leaf (Node Leaf x Leaf))
    ((Node l v r)
     (cond ((< x v) (Node (tree-insert x l) v r))
           ((> x v) (Node l v (tree-insert x r)))
           (else t)))))

(: tree->list (-> (Tree %a) (List %a)))
(defun (tree->list t)
  (match t
    (Leaf '())
    ((Node l v r) (list-append (tree->list l) (Cons v (tree->list r))))))

(tree->list (list-foldl tree-insert Leaf (list 5 2 8 1 9 2)))  ;; '(1 2 5 8 9)

Types may also refer to each other. All the types of a module are known before any of them is checked, so the order they are declared in does not matter, and they do not even have to be in the same type form:

(type (: Expr (Union (: Num int)
                     (: Add Expr Expr)
                     (: Let Binding Expr)
                     (: Var string))))

(type (: Binding (Record (: name string) (: value Expr))))

Deriving equality and ordering

Every type can be compared with =. By default a record, struct or union is compared field by field. To use your type as a key in a hash map, or to sort it, it is better to say so explicitly with type/derive. It is written like type, with a list of traits in front:

(type/derive (Eq Ord)
  (: Suit (Union Clubs Diamonds Hearts Spades))
  (: Rank (Union (: Pip int) Jack Queen King Ace))
  (: Card (Struct (: rank Rank) (: suit Suit))))

Eq gives you = and a matching hash. Ord gives you an ordering, and with it compare, less?, list-sort, list-max and everything else that orders things. The derived order is the obvious one:

• A union orders by case first, in the order the cases are declared, so above Clubs is less than Spades and every Pip is less than Jack. Two values of the same case are ordered by their payload.
• A record or struct compares its fields in declaration order and stops at the first one that differs. Above, cards are ordered by rank first and by suit when the ranks are equal.

(list-sort (list (Card (rank Ace) (suit Spades))
                 (Card (rank (Pip 7)) (suit Hearts))
                 (Card (rank (Pip 10)) (suit Clubs))
                 (Card (rank (Pip 7)) (suit Clubs))))
;; 7♣ 7♥ 10♣ A♠

(less? (Card (rank (Pip 2)) (suit Spades))
       (Card (rank Jack) (suit Clubs)))     ;; #t: rank decides first

Note that < and > are not in that list. They are for numbers and characters only. For anything with an Ord, use less?, greater?, at-most? and at-least?, or compare, which returns a negative number, zero or a positive number.

When the derived order is not the one you want (for example if aces should sometimes be low), you write the implementation by hand. That is covered in the traits section.

The card game

The rest of this chapter uses a card game as a running example, so here are its types in one place. Put this at the top of a file and the examples in the following sections can be pasted below it.

(type/derive (Eq Ord)
  (: Suit (Union Clubs Diamonds Hearts Spades))
  (: Rank (Union (: Pip int) Jack Queen King Ace))
  (: Card (Struct (: rank Rank) (: suit Suit))))

(type (: Player (Record (: name string)
                        (: hand (Vec Card))
                        (: tricks int))))

;; How a card prints. Traits are explained later; for now it is enough
;; to know that this is what println and #"...${...}" use.
(impl (->str Suit)
  (defun (->str s)
    (match s (Clubs "♣") (Diamonds "♦") (Hearts "♥") (Spades "♠"))))

(impl (->str Rank)
  (defun (->str r)
    (match r
      ((Pip n) (int->string n))
      (Jack "J") (Queen "Q") (King "K") (Ace "A"))))

(impl (->str Card)
  (defun (->str c) #"${(record-ref c rank)}${(record-ref c suit)}"))

(println (Card (rank Queen) (suit Hearts)))   ;; Q♥

Card is a struct because it is two small values and is copied around a lot. Player is a record because it holds a whole hand. That is the usual rule of thumb: a struct for something small that behaves like a value, a record for everything else. A struct also cannot contain itself and cannot have mutable fields.

Records are updated by copying, with record-set:

(: won-trick (-> Player Player))
(defun (won-trick p)
  (record-set p (tricks (+ 1 (record-ref p tricks)))))

(def ada (Player (name "ada") (hand []) (tricks 0)))
(record-ref (won-trick (won-trick ada)) tricks)   ;; 2
(record-ref ada tricks)                           ;; still 0

Pattern matching

Pattern matching is how you take values apart in bjolang. There is no car/cdr style of programming on unions: you say what shape you expect and the compiler binds the parts for you, and checks that you did not forget a shape.

match

(match value clause ...) tries each clause in turn. A clause is a pattern followed by a body, and the first clause whose pattern fits is the one that runs. Its last expression is the value of the whole match.

The basic patterns are:

The difference between a binder and a constructor is the first letter. A lowercase name binds, a capitalised name is a case. This is also the source of one classic mistake: if you misspell a case, or forget to import it, it becomes a binder that matches everything. The compiler will usually tell you, because the clauses below it can then never run.

(: light (-> Keyword string))
(defun (light k)
  (match k
    (:red "stop")
    (#:green "go")          ;; :green and #:green are the same keyword
    (_ "wait")))

(: rank-points (-> Rank int))
(defun (rank-points r)
  (match r
    ((Pip n) n)
    (Ace 11)
    (_ 10)))

Patterns nest. A payload can itself be matched against a pattern:

(match (Some (Pip 10))
  ((Some (Pip 10)) "a ten")
  ((Some (Pip n)) #"the number ${n}")
  ((Some court) "a court card or an ace")
  (None "no card"))

Records and structs

A record or struct is matched by its type name followed by the fields you care about, each written (field pattern). Fields you leave out match anything, and the order does not matter. A field name on its own binds the field to a variable of the same name, which is by far the most common way to use it:

(: card-name (-> Card string))
(defun (card-name c)
  (match c
    ((Card (rank Ace) (suit Spades)) "the ace of spades")
    ((Card (rank (Pip 10))) "a ten")
    ;; `suit` alone binds the suit field to the name suit
    ((Card (rank (Pip n)) suit) #:when (< n 5) #"a low card (${n}${suit})")
    ((Card (rank (or Jack Queen King))) "a court card")
    ((Card rank) #"something else: ${rank}")))

(: player-line (-> Player string))
(defun (player-line p)
  (match p
    ((Player name (tricks 0)) #"${name} has not won anything")
    ((Player name tricks) #"${name} has won ${tricks} tricks")))

A bare type name, like Card, is a pattern that matches every card.

Lists, vecs, arrays and tuples

Collections have patterns too. ... after the last name binds the rest of the collection:

(: describe (-> (List int) string))
(defun (describe xs)
  (match xs
    (() "empty")
    ((List x) #"one: ${x}")
    ((List 0 rest ...) "starts with zero")
    ((List x y rest ...) #"${x}, ${y} and ${(list-length rest)} more")))

(describe (list 1 2 3 4))   ;; "1, 2 and 2 more"

(: header (-> (Vec string) string))
(defun (header v)
  (match v
    ([] "no columns")
    ([only] only)
    ([first rest ...] #"${first} (+${(vec-length rest)})")))

(: pair (-> (Tuple int string) string))
(defun (pair p)
  (match p
    ((0 . s) #"zero and ${s}")
    ((_ . "x") "an x")
    ((n . s) #"${n}/${s}")))

The rest of a vec pattern shares its structure with the original vec, so it is cheap. The rest of an array pattern is a copy.

Guards, or and and

A clause may have a guard, written #:when expr after the pattern. The clause only matches if the pattern fits and the guard is true, and the guard can use everything the pattern bound:

(match hand-size
  (0 "no cards")
  (n #:when (> n 10) "too many cards")
  (n #:when (even? n) "an even hand")
  (_ "an odd hand"))

(or p ...) matches if any of the alternatives match. The alternatives may not bind names, since there would be no way to know which of them did. (and p ...) matches if all of them match, which is mostly useful to bind a name to the whole value while also taking it apart:

(: red? (-> Suit bool))
(defun (red? s)
  (match s
    ((or Hearts Diamonds) #t)
    (_ #f)))

(match (Some 3)
  ((and (Some n) whole) #"${n} inside ${whole}")   ;; "3 inside (Some 3)"
  (None "none"))

Views, type tests and Has

(:view f pattern) calls f on the value and matches the result against pattern. That lets a match look at something that is not directly in the value, like whether a string parses as a number:

(: parse-int (-> string (Option int)))
(defun (parse-int s)
  (match (try (string->int s) #:catch (System.FormatException))
    ((Ok n) (Some n))
    ((Err _) None)))

(: classify (-> string string))
(defun (classify s)
  (match s
    ((:view parse-int (Some n)) #:when (even? n) "an even number")
    ((:view parse-int (Some n)) "an odd number")
    ((:view string-length 0) "nothing")
    (_ "text")))

(:is Type name) tests the .NET type of a value, and binds it with that type. It is mostly used to tell exceptions apart, and there is an example of that in the section on failure.

(Has key pattern) matches any collection you can look things up in (maps, vecs) that has key, and matches the value under it against pattern. Has* takes several key and pattern pairs:

(: port-of (-> (Map string int) int))
(defun (port-of settings)
  (match settings
    ((Has "port" p) p)
    (_ 8080)))

(: user-line (-> (Map string string) string))
(defun (user-line m)
  (match m
    ((Has* ("name" n) ("city" c)) #"${n} from ${c}")
    ((Has "name" n) n)
    (_ "anonymous")))

Exhaustiveness

Every match is checked, and a match that does not cover every value is a compile error. The error names a value that falls through:

(: red? (-> Suit bool))
(defun (red? s)
  (match s
    (Hearts #t)
    (Diamonds #t)
    (Clubs #f)))

Pattern Error at cards.bjo:8: this match does not cover every value. Spades reaches no clause.

The counterexample is a real value, and for nested patterns it tells you exactly which combination is missing:

(match c
  ((Card (rank (Pip n))) n)
  ((Card (rank (or Jack Queen King))) 10)
  ((Card (rank Ace) (suit Spades)) 50))

Pattern Error at cards.bjo:8: this match does not cover every value. (Card (rank Ace) (suit Clubs)) reaches no clause.

A clause that can never run, because the clauses above it already match everything it would, is also an error:

Pattern Error at cards.bjo:5: this clause can never run — the clauses above it already match everything it does.

The checker does not run your code, so a clause with a #:when guard, a :view or an :is covers nothing as far as it is concerned. A match that only has guarded clauses needs a final catch-all:

(match n
  (x #:when (< x 10) "small")
  (_ "large"))          ;; without this line:"_ reaches no clause"

case

case is a short form for the common match against literals. Each clause is a list of values, and else is the catch-all:

(: nth-name (-> int string))
(defun (nth-name n)
  (case n
    ((1) "first")
    ((2) "second")
    ((3) "third")
    (else #"${n}th")))

(case command
  (("quit" "exit") (stop))
  (("help") (show-help))
  (else (run command)))

The data in a clause must be literals: numbers, strings, characters, booleans, keywords or quoted symbols. A union case like Hearts is not allowed, since case could not tell it from a binder. For those, use match with or.

Patterns in def

Any pattern can also be used in def. You have already seen that in the section on with-return, where a pattern that may fail gets a failure part. A pattern that cannot fail needs none, and is simply a way to take something apart without indenting the rest of the function:

(def (Card rank suit) c)              ;; binds rank and suit
(def (who . points) (Tuple "ada" 3))  ;; binds who and points

A pattern that may fail needs one of the failure parts: :leave-with, :leave, :propagate or :default. They are all covered in the section on bailing out of failed bindings. Here is one of each of the two most common:

(: score-line (-> (Map string int) string string))
(defun (score-line scores who)
  ;; If the lookup fails, the function's value is the :leave-with value.
  (def (Some n) (map-try-ref scores who) :leave-with #"${who} has not played")
  #"${who}: ${n}")

(: total (-> (Map string int) string string (Option int)))
(defun (total scores a b)
  ;; If either lookup fails, the None is passed on as the function's value.
  (def* ((Some x) (map-try-ref scores a) :propagate)
        ((Some y) (map-try-ref scores b) :propagate))
  (Some (+ x y)))

Example: who wins the trick

In many card games, everyone plays one card, and the highest card in the suit that was led (the suit of the first card) wins. Here a trick is a list of who played what, in order:

(: trick-winner (-> (List (Tuple string Card)) (Option string)))
(defun (trick-winner trick)
  (match trick
    (() None)
    ((Cons (_ . lead) _)
     (def led-suit (record-ref lead suit))
     (def best
       (loop (:for (who . card) trick)
             (:when (= (record-ref card suit) led-suit))
             (:acc top (folding (Tuple "" lead)
                                (match top
                                  ((_ . top-card)
                                   (if (at-least? card top-card)
                                       (Tuple who card)
                                       top)))))
             => top))
     (def (winner . _) best)
     (Some winner))))

(trick-winner (list (Tuple "ada" (Card (rank (Pip 9)) (suit Hearts)))
                    (Tuple "bo"  (Card (rank Ace) (suit Spades)))
                    (Tuple "cy"  (Card (rank Queen) (suit Hearts)))
                    (Tuple "dee" (Card (rank (Pip 10)) (suit Hearts)))))
;; (Some "cy"): bo's ace is higher, but it is not a heart.

The loop is explained in its own section. What matters here is the patterns: (Cons (_ . lead) _) picks out the first card of a non-empty list in one go, (:for (who . card) trick) takes each pair apart as it walks the list, and at-least? works on cards because Card derives Ord.

Options, results and failure

Bjolang has no null. A value that may be missing is an Option, and a computation that may fail returns a Result. Both are ordinary unions from the prelude:

;; (Option %a) is either None or (Some value)
;; (Result %e %a) is either (Err error) or (Ok value)

Exceptions exist too, since everything in .NET throws them, but they are something you turn into a Result at the edge of your program rather than something you use for ordinary control flow.

Option

(: halve (-> int (Option int)))
(defun (halve n)
  (if (even? n) (Some (/ n 2)) None))

(match (halve 7)
  ((Some h) #"half is ${h}")
  (None "7 is odd"))

Matching is always possible, but the prelude has shorter ways to say the common things:

(option-value (halve 7) 0)                  ;; 0
(if-let (h (halve 12))
  (println #"half is ${h}")                 ;; prints "half is 6"
  (println "odd"))
(when-let (h (halve 3))
  (println "never printed"))

Result

A Result is an Option that says why it is empty. The error can be any type: a string for a quick script, your own union when the caller needs to act on what went wrong, or a .NET exception.

(: parse-int (-> string (Result string int)))
(defun (parse-int s)
  (match (try (string->int s) #:catch (System.FormatException))
    ((Ok n) (Ok n))
    ((Err e) (Err #"'${s}' is not a number"))))

(: positive (-> int (Result string int)))
(defun (positive n)
  (if (> n 0) (Ok n) (Err #"${n} is not positive")))

(ok? (parse-int "12"))                  ;; #t
(err? (parse-int "twelve"))             ;; #t
(result-map #(* & 2) (parse-int "21"))  ;; (Ok 42)

A Result must be used. In fact every value must be: a form in the middle of a body whose value is dropped is a compile error, unless it is void. For a Result that rule is what keeps a failure from disappearing silently. If you really do not care about a value, say so with (ignore expr):

Type Error at game.bjo:4: this value has type int and is discarded.
  It is a form in the middle of a body, so its value is dropped.
  Every value that is computed and then dropped has to say so: write `(ignore ...)` around it.

Chaining things that may fail

Most real code does several things in a row, each of which may fail, and stops at the first failure. Nesting matches for that drifts to the right very quickly. There are three ways to write it flat.

The first is def with :propagate. When the pattern does not match, the case that did not match is rebuilt and becomes the return value of the function. With an Option that is None, and with a Result it is the same Err:

(: parse-positive (-> string (Result string int)))
(defun (parse-positive s)
  (def (Ok n) (parse-int s) :propagate)
  (def (Ok p) (positive n) :propagate)
  (Ok (* p 10)))

(parse-positive "12")   ;; (Ok 120)
(parse-positive "-4")   ;; (Err "-4 is not positive")
(parse-positive "x")    ;; (Err "'x' is not a number")

The second is try->, a threading form that stops at the first Err. Each step gets what the previous one returned, unwrapped, in the & position. some-> is the same for Option:

(: parse-positive (-> string (Result string int)))
(defun (parse-positive s)
  (try-> s (parse-int &) (positive &)))

(: quarter (-> int (Option int)))
(defun (quarter n)
  (some-> n (halve &) (halve &)))

(quarter 12)   ;; (Some 3)
(quarter 6)    ;; None: 3 is odd

The third is with-return together with :leave-with, which was described earlier. Use it when the failures should turn into something that is not the same type, for example a default value or a log line.

Exceptions: try, :is and raise

.NET code reports failure by throwing. try turns exceptions of the types you list into an Err, and the value of a body that did not throw into an Ok. Anything you did not list keeps propagating as an exception:

(def divisor (string->int "0"))
(try (/ 10 divisor) #:catch (System.DivideByZeroException))
;; (Err <the exception>), of type (Result System.Exception int)

Put the try around the whole region that can fail rather than around each call, and you get a single Result out.

#:finally expr runs expr however the body ends. Without a #:catch nothing is caught, and the value is just the body’s value:

(try (render page)
  #:finally (println "done rendering"))

The Err of a try holds a System.Exception. To tell different exceptions apart, use the :is pattern, which tests the .NET type and binds the value with the more specific type so that you can read its properties. raise throws an exception again, for the cases that are not yours to handle:

(: slurp (-> string string))
(defun (slurp path)
  (match (try (file-read-text path)
           #:catch (System.IO.FileNotFoundException
                    System.IO.DirectoryNotFoundException))
    ((Ok text) text)
    ((Err (:is System.IO.FileNotFoundException e)) #"no such file: ${(.-FileName e)}")
    ((Err (:is System.IO.DirectoryNotFoundException)) "no such directory")
    ((Err e) (raise e))))

with-open

with-open binds something disposable, like a port, a stream or a database connection, runs the body, and disposes it however the body ends:

(: first-line (-> string (Result Exception string)))
(defun (first-line text)
  (try (with-open ((p (open-input-string text)))
         (read-line p))
    #:catch (System.IO.IOException)))

(first-line "first\nsecond")   ;; (Ok "first")

panic!

When something happens that should be impossible, (panic! "message") prints the message and exits the program. It can stand where any type is expected, which makes it useful as the last arm of a match that you know cannot be reached:

(match (map-try-ref deck-index card)
  ((Some i) i)
  (None (panic! "a card that is not in the deck")))

(panic! "config is broken" #:exit-code 2)

Collections

Bjolang’s collections are immutable by default. Adding to a vec or setting a key in a map gives you a new collection and leaves the old one untouched. That sounds expensive, but the new collection shares almost all of its structure with the old one, so an update costs about as much as it would in a mutable collection, and nobody ever has to wonder who else is holding on to the old version.

If you do not know which to use, use a Vec.

Lists

The list is the scheme list: a chain of Cons cells ending in Nil. It is cheap to add to and take from the front, and slow for everything else. Use it for things you build front to back and walk once.

(def xs (list 1 2 3))
(def ys (Cons 0 xs))       ;; '(0 1 2 3), and xs is still '(1 2 3)

(list-head ys)             ;; 0
(list-tail ys)             ;; '(1 2 3)
(list-length ys)           ;; 4, but it walks the list to find out
(list-map #(* & 10) xs)    ;; '(10 20 30)
(list-filter even? ys)     ;; '(0 2)
(list-foldl + 0 xs)        ;; 6
(list-reverse xs)          ;; '(3 2 1)
(list-append xs xs)        ;; '(1 2 3 1 2 3)

A quoted list is data: '(a b c) is a list of three symbols, not a call. Inside one, ,expr splices in the value of an expression:

(def n 5)
'(1 2 ,n)                  ;; '(1 2 5)

Vecs

Vec is the general-purpose collection. Indexing, updating at an index and adding at the end are all cheap, and it knows its own length.

(def v [10 20 30])
(def v2 (vec-add v 40))     ;; [10 20 30 40]
(def v3 (vec-set v2 0 99))  ;; [99 20 30 40]
v                           ;; still [10 20 30]

(vec-ref v3 0)              ;; 99
(vec-length v3)             ;; 4
(vec-filter #(> & 15) v3)   ;; [99 20 30 40]
(vec-slice v3 1 2)          ;; [20 30]: start at 1, take 2
(vec-map #(+ & 1) v)        ;; [11 21 31]
(vec-fold + 0 v)            ;; 60
(vec-merge v v)             ;; [10 20 30 10 20 30]

(list->vec xs) and (vec->list v) convert between the two.

Arrays

An Array is a plain .NET array: mutable, fixed in length, and exactly what C# code expects. Use them for performance-sensitive code, or when talking to .NET.

(def a #[1 2 3])
(array-set! a 0 42)        ;; changes a in place
(array-ref a 0)            ;; 42
(array-length a)           ;; 3
(def zeroes (make-array 10))

Every evaluation of an array literal makes a fresh array, so a function that returns #[0 0] returns a new one each time.

Maps

Map is an immutable hash map. The #map(...) literal takes entries written as (key value), [key value] or (key . value).

(def scores #map(("ada" 3) ("bo" 5)))
(def scores2 (map-set scores "cy" 1))   ;; scores still has two entries

(map-ref scores2 "cy")          ;; 1, and throws if the key is missing
(map-try-ref scores "cy")       ;; None
(map-ref-or scores "cy" 0)      ;; 0
(map-contains? scores2 "bo")    ;; #t
(map-length scores2)            ;; 3
(map-remove scores2 "ada")      ;; a map without ada

;; The callbacks of the map- functions get the key and the value as
;; two separate arguments.
(map-fold (fun (k v acc) (+ v acc)) 0 scores2)   ;; 9
(map-map-values #(* & 100) scores)                ;; ada 300 and bo 500
(map-filter (fun (k v) (> v 2)) scores2)          ;; ada and bo, not cy

Any type with an Eq can be a key. That includes your own types, which is one reason to derive Eq.

When a map is walked as a collection, for example in a loop or with fold, each element is a (Tuple key value) pair:

(loop (:for (name . score) scores)
      (:do (println #"${name}: ${score}")))

Sets and ordered collections

Sets and the sorted collections are libraries, so they have to be imported. Their functions are named like the map functions, with their own prefix:

(import (std set))
(import (std orderedmap))

(def s (list->set (list 3 1 4 1 5 9 2 6 5)))
(set-length s)                   ;; 7
(set-contains? s 4)              ;; #t
(set-contains? (set-add s 7) 7)  ;; #t

(def prices (orderedmap-set
              (orderedmap-set
                (orderedmap-set (orderedmap-empty) "pear" 3)
                "apple" 5)
              "fig" 1))
(seq->list (orderedmap-keys prices))   ;; '("apple" "fig" "pear"): always sorted
(orderedmap-min prices)                ;; (Some ("apple" . 5))

An ordered collection sorts its keys with their Ord, so a type that derives Ord can be a key in one. Strings are sorted by code unit, not by the rules of any language, so the order is the same on every machine.

Building collections quickly

Updating an immutable collection one element at a time is cheap, but not free. When you build a collection from scratch in a loop, use a builder, which is a mutable collection you fill and then freeze. There are builders for lists, vecs, strings, maps and sets:

(def vb (vecbuilder-empty))
(vecbuilder-add! vb "a")
(vecbuilder-add! vb "b")
(vecbuilder->vec vb)              ;; ["a" "b"]

(def lb (listbuilder-empty))
(listbuilder-add! lb 1)
(listbuilder-add! lb 2)
(listbuilder->list lb)            ;; '(1 2): builds front to back

A transient is the same thing for changing an existing map or set many times: it takes the collection, lets you mutate it, and gives you a new immutable collection back.

(def t (map->transientmap scores))
(transientmap-set! t "eve" 7)
(transientmap-remove! t "ada")
(def new-scores (transientmap->map t))   ;; bo and eve; scores is untouched

In practice you rarely write either of these directly, since the accumulators of loop (next section) use builders for you.

Generic operations

Many operations are traits, so they work on every collection that implements them:

(length [1 2 3])                        ;; 3
(ref [10 20 30] 1)                      ;; 20
(try-ref #map((:a 1)) :b)               ;; None
(add #map(("a" 1)) ("b" . 2))           ;; for a map, the element is a pair
(add-all (set-empty) [1 1 2 2 3])       ;; a set of three
(fold + 0 [1 2 3 4])                    ;; 10
(find #(> & 3) (list 1 5 7))            ;; (Some 5)

(def b (vecbuilder-empty))
(add-all! b (range 0 5))
(vecbuilder->vec b)                     ;; [0 1 2 3 4]

Mutable collections

For the rare cases where you really want a collection that is changed in place and shared, there are mutable versions under (std mutable ...): vec, map, set, deque and heap. The mutable vec is a .NET List<T>, and the mutable map is a .NET Dictionary.

(import (std mutable vec))

(def mv (mutablevec))
(mutablevec-add! mv 3)
(mutablevec-add! mv 1)
(mutablevec-add! mv 2)
(mutablevec-sort! mv)
(mutablevec-ref mv 0)      ;; 1

Reach for these only when you have measured that you need them, or when a .NET API wants one. A mutable collection cannot be a map key, and sharing one between fibers is your own problem.

Equality

Equality is structural. Two collections are equal when they hold equal elements, however they were built:

(= [1 2 3] (vec-add [1 2] 3))                     ;; #t
(= (list 1 2) (list 1 2))                         ;; #t
(= #map(("a" 1)) (map-set (map-empty) "a" 1))     ;; #t

eq? asks whether two things are the very same object. You almost never want it.

Example: a deck and a score table

A deck is a (Vec Card). Building it is a nested loop over suits and ranks (loops are the next section):

(: all-suits (Vec Suit))
(def all-suits [Clubs Diamonds Hearts Spades])

(: all-ranks (Vec Rank))
(def all-ranks [(Pip 2) (Pip 3) (Pip 4) (Pip 5) (Pip 6) (Pip 7) (Pip 8)
                (Pip 9) (Pip 10) Jack Queen King Ace])

(: full-deck (-> (Vec Card)))
(defun (full-deck)
  (loop (:for s all-suits)
        (:subloop)
        (:for r all-ranks)
        (:acc deck (vecing (Card (rank r) (suit s))))
        => deck))

(vec-length (full-deck))   ;; 52

The scores of a game are a map from player name to points. Since a map is immutable, a round of scoring is a function from the old table to a new one:

(: add-points (-> (Map string int) string int (Map string int)))
(defun (add-points table who points)
  (map-set table who (+ points (map-ref-or table who 0))))

(def start #map(("ada" 0) ("bo" 0)))
(def after (add-points (add-points start "ada" 5) "cy" 2))
(map-ref after "ada")    ;; 5
(map-ref after "cy")     ;; 2: a missing player starts at 0
(map-length start)       ;; still 2

Loops and sequences

There are three ways to repeat something in bjolang. A named let (or any tail-recursive function) is the scheme way, and was covered earlier. loop is the way you will use most of the time. seq and seql make lazy sequences, which produce their elements only when someone asks for them.

loop

A loop is a list of clauses that run in order, once per element. (:for x coll) walks anything that can be walked: lists, vecs, arrays, maps, strings, ranges and sequences. An accumulator collects a result, and => expr says what the loop returns:

(loop (:for x (list 1 2 3 4 5 6))
      (:when (even? x))
      (:acc out (listing (* x x)))
      => out)
;; '(4 16 36)

The clauses are:

Since :for takes a pattern, you can take elements apart as you go, like the tuples of a map or the pairs enumerate makes:

(loop (:for (i . s) (enumerate ["a" "b"]))
      (:acc out (listing #"${i}:${s}"))
      => out)
;; '("0:a" "1:b")

Accumulators

An accumulator names a collector and what to feed it:

folding is the general one: inside expr the accumulator’s own name is the value so far.

(def xs [3 9 2 7])

(loop (:for x xs) (:acc best (folding 0 (max best x))) => best)   ;; 9

(loop (:for c "hello") (:acc s (stringing (char-upcase c))) => s)   ;; "HELLO"

(loop (:for k (list "a" "b"))
      (:for v (list 1 2))
      (:acc m (mapping (k . v)))
      => m)                                     ;; a map from "a" to 1 and "b" to 2

An accumulator does not need a name. Without a =>, a loop returns its accumulators, and with several of them it returns a tuple of their values in order:

(loop (:for x xs) (:acc (summing x)) (:acc (counting x)))   ;; (21 . 4)

Several collections: lockstep and nesting

Two :for clauses in a row walk their collections side by side, and the loop ends when the shortest one runs out. To get every combination instead, put a (:subloop) between them. Everything after it runs once for every element of the inner collection, for every element of the outer one:

;; side by side
(loop (:for k (list "a" "b" "c"))
      (:for v (list 1 2 3))
      (:acc out (listing (k . v)))
      => out)                 ;; '(("a" . 1) ("b" . 2) ("c" . 3))

;; nested
(loop (:for x (list 1 2))
      (:subloop)
      (:for y (list 10 20))
      (:acc out (listing (+ x y)))
      => out)                 ;; '(11 21 12 22)

(:abandon test) in the inner loop ends it early, and the outer loop goes on with its next round. In the outer loop there is nothing to go on with, so there it is an error:

(loop (:for x (list 1 2 3))
      (:subloop)
      (:for y (list 1 2 3))
      (:abandon (> y x))
      (:acc out (listing (x . y)))
      => out)                 ;; '((1 . 1) (2 . 1) (2 . 2) (3 . 1) (3 . 2) (3 . 3))

A nested loop like this runs to the end of the round: the clauses after the inner :for belong to the inner loop. When the round should go on after the inner loop, with what it computed, write the inner loop as a :subloop form instead. It is a loop of its own inside the round, and its accumulators are there for the clauses after it, with their final values:

(loop (:for row (list (list 1 2) (list 3 4 5)))
      (:subloop (:for x row)
                (:acc sum (summing x))
                (:acc n (counting x)))
      (:acc out (listing (sum . n)))
      => out)                 ;; '((3 . 2) (12 . 3))

With => (name expr) at its end, only name is bound after the form, to expr:

(loop (:for row rows)
      (:subloop (:for x row)
                (:acc sum (summing x))
                (:acc n (counting x))
                => (avg (if (= n 0) 0 (/ sum n))))
      (:acc out (listing avg))
      => out)

The form’s accumulators start over every time it runs, and a form that runs zero times leaves them at their start values. Its own variables are never visible after it. Inside it, two clauses are about the form:

• (:finish-subloop test) ends the form here, and the round goes on after it with the accumulators as they are.
• (:abandon-subloop test) throws the form and the rest of the round away, and the outer loop goes on with its next round.

:when, :abandon, :while and :until inside the form are about the form’s own rounds. :finish still ends the whole loop.

A variable inside a loop cannot reuse the name of an accumulator, of a :with, or of a variable of an outer loop: (:for x xs) (:subloop) (:for x x) is an error. Pick another name.

State that carries over: :with

(:with name start update) is a variable that starts at start and is set to update after every round. All the :with updates of a round happen at once, so each of them sees the old values of the others:

(loop (:with a 0 b)
      (:with b 1 (+ a b))
      (:for i (range 0 10))
      (:acc out (listing a))
      => out)
;; '(0 1 1 2 3 5 8 13 21 34)

Stopping early

:finish leaves the loop before the rest of the round runs, and :final leaves it after. :when-let and :finish-let bind a pattern that may fail, and skip the round or leave the loop when it does. The names follow one rule: finish stops and goes on after the loop, abandon stops and goes up to the next round of the outer loop.

(loop (:for x (list 1 2 3 4 5)) (:finish (> x 3)) (:acc out (listing x)) => out)
;; '(1 2 3)

(loop (:for x (list 1 2 3 4 5)) (:final (> x 3)) (:acc out (listing x)) => out)
;; '(1 2 3 4)

;; Sum the strings that are numbers, and skip the rest.
(loop (:for s (list "1" "x" "3"))
      (:when-let (Ok n) (try (string->int s) #:catch (System.FormatException)))
      (:acc total (summing n))
      => total)
;; 4

;; Number the lines of a port until it is empty. up-from without a #:to
;; never stops on its own, so the :finish-let is what ends the loop.
(loop (:for line-number (up-from 1))
      (:finish-let (Some line) (read-line/opt port))
      (:do (println #"${line-number}: ${line}")))

(:finish test value) leaves the loop with value as its result, and the => expression is not run. The value has to have the same type as the => expression:

;; The sum, or -1 as soon as a negative number shows up.
(loop (:for x (list 1 2 -3 4))
      (:finish (< x 0) -1)
      (:acc total (summing x))
      => total)
;; -1

:break and :break-let are the old names of :finish and :finish-let. They still work, with a warning.

Looping while something holds: :while and :until

(:while test) keeps the loop going while test holds, and (:until test) until it does. Neither binds anything, so a loop that has no collection to walk can start with one:

(loop (:until (port-eof? port))
      (:let line (read-line port))
      (:do (println line)))

The test is checked before every round, the first one too, so the loop may run zero times. Next to a :for, the loop ends at whichever stops first, and the test can use the :for’s variable:

(loop (:for x (list 1 2 3 4 5))
      (:until (> x 3))
      (:acc out (listing x))
      => out)
;; '(1 2 3)

Since the test runs before the round, it cannot see what the round computes. To stop on that, put a :finish after it: (:let line (read-line/opt port)) (:finish (none? line)).

A loop has to start with a :for, a :with, a :while or an :until, since the other clauses belong to the round that it opens.

Counting and walking part of a collection

(:for x coll) walks all of coll from the front. These walk something else:

(loop (:for i (up-from 0 #:to 10 #:by 3)) (:acc out (listing i)) => out)  ;; '(0 3 6 9)
(loop (:for i (down-from 5 #:to 0)) (:acc out (listing i)) => out)        ;; '(5 4 3 2 1 0)
(loop (:for x (in-reverse-vec [1 2 3 4])) (:acc out (listing x)) => out)  ;; '(4 3 2 1)
(loop (:for x (in-vec [1 2 3 4] #:from 1 #:to 3)) (:acc out (listing x)) => out)  ;; '(2 3)

None of these allocate anything. The loop compiles to the same code you would have written by hand.

Named loops

A loop can be given a name, which is then bound to a function that continues with the next round. Calling it with keyword arguments overrides the value of an accumulator or a :with for the next round. It must be called in tail position:

(loop lp (:for x [1 2 3 4])
         (:acc total (summing x))
         (:do (if (= x 2)
                  (lp #:total 100)   ;; reset the sum to 100 after the 2
                  (lp)))
         => total)
;; 107

Comprehensions

A comprehension is a short way to write a loop with one accumulator. It is written in braces, with the collector first, then the expression to collect, then the clauses:

{listing (* a a) (:for a (range 0 5))}               ;; '(0 1 4 9 16)
{listing a :when (even? a) (:for a (range 0 10))}    ;; '(0 2 4 6 8)
{summing x (:for x [1 2 3])}                         ;; 6
{vecing (k . v) (:for k (list "a" "b")) (:for v (list 1 2))}
;; [("a" . 1) ("b" . 2)]

A loose :when right after the expression filters what is collected. Every loop clause works inside a comprehension, except :acc and =>.

Lazy sequences: seq and yield

A (Seq %a) is a sequence that computes its elements when they are asked for. You write one with seq, whose body calls yield for each element:

(: countdown (-> int (Seq int)))
(defun (countdown n)
  (seq
    (let loop ((i n))
      (when (> i 0)
        (yield i)
        (loop (- i 1))))
    (yield 0)))

(seq->list (countdown 3))   ;; '(3 2 1 0)

;; yield-from yields everything in another sequence.
(seq->list (seq (yield 100) (yield-from (countdown 2)) (yield 200)))
;; '(100 2 1 0 200)

Since nothing runs until it is asked for, a sequence can be endless, as long as you only ever take part of it:

(: naturals (-> (Seq int)))
(defun (naturals)
  (seq (let loop ((i 0)) (yield i) (loop (+ i 1)))))

(seq->list (seq-take (naturals) 5))                  ;; '(0 1 2 3 4)
(seq->list (seq-take (seq-filter even? (seq-map #(* & 3) (naturals))) 4))
;; '(0 6 12 18)

A sequence is re-run from the start every time it is walked. If computing the elements is expensive, turn it into a vec or list once with seq->vec or seq->list.

seql is loop made lazy. It takes the same clauses, with (:yield expr) instead of an accumulator:

(: fibs (-> (Seq int)))
(defun (fibs)
  (seql (:with a 0 b)
        (:with b 1 (+ a b))
        (:yield a)))

(seq->list (seq-take (fibs) 10))   ;; '(0 1 1 2 3 5 8 13 21 34)

The same thing as a comprehension is {seqing expr clause ...}.

map, filter and friends

The generic map, filter, take, drop, take-while, drop-while, enumerate and flat-map work on anything you can loop over, and all of them return a lazy Seq. Chains of them are fused by the compiler into a single pass. To get a concrete collection at the end, convert it:

(seq->list (map #(* & 2) (list 1 2 3)))   ;; '(2 4 6)
(seq->vec (filter even? [1 2 3 4]))       ;; [2 4]
(seq->list (take 3 (naturals)))           ;; '(0 1 2)

When you want a list or a vec out directly, the collection-specific functions (list-map, vec-filter and so on) are eager and return the same kind of collection they were given.

Example: dealing and counting

Dealing a deck to four players means giving player 0 the cards 0, 4, 8 and so on. That is a loop over players with a loop over the hand inside it:

(: deal (-> (Vec Card) int int (Vec (Vec Card))))
(defun (deal deck players per-hand)
  (loop (:for p (range 0 players))
        (:acc (vecing
                (loop (:for i (range 0 per-hand))
                      (:acc (vecing (vec-ref deck (+ p (* i players))))))))
        => hands))

(: points (-> Card int))
(defun (points c)
  (match c
    ((Card (rank (Pip n))) n)
    ((Card (rank Ace)) 11)
    (_ 10)))

(: hand-points (-> (Vec Card) int))
(defun (hand-points hand)
  {summing (points c) (:for c hand)})

(def hands (deal (full-deck) 4 5))
(vec-map hand-points hands)   ;; the points of each hand

Strings and text

Strings and characters

A string is a .NET string, which means it is stored as UTF-16. A char in bjolang is not a UTF-16 unit, though: it is a whole Unicode code point. An emoji is one char, even though it takes two units in the string. That leads to two different lengths:

(def s "Björn 😀 åt")
(string-length s)   ;; 11: storage units, O(1). Use it for sizing buffers.
(string-count s)    ;; 10: characters, O(n). This is "how long is the text".

For the same reason there is no string-ref that takes an index. Finding the n:th character of a UTF-16 string means walking it, so walking is what you do: with a loop, a fold, or a cursor.

(loop (:for c s) (:acc n (counting c)) => n)   ;; 10: loops go by character
(string->list "abc")                           ;; '(#\a #\b #\c)
(string-reverse "abc😀")                       ;; "😀cba", and the emoji survives

Characters are written #\a, #\space, #\newline. They can be compared with < and friends or char=?, converted with char->int and int->char, and classified with char-alphabetic?, char-numeric?, char-whitespace?, char-upper-case? and char-lower-case?.

Common operations

(string-append "ab" "cd")               ;; "abcd"
(str "a" "b" "c")                       ;; "abc": any number of strings
(string-upcase "björn")                 ;; "BJÖRN"
(string-trim "  hi  ")                  ;; "hi"
(string-pad-left "7" 3 #:with #\0)      ;; "007"
(string-split "a,b,,c" ",")             ;; ["a" "b" "" "c"]: a Vec
(string-join ["a" "b" "c"] ", ")        ;; "a, b, c"
(string-replace "banana" "an" "AN")     ;; "bANANa"
(string-contains? "banana" "nan")       ;; #t
(string-starts-with? "banana" "ban")    ;; #t
(string-empty? "")                      ;; #t

All of these compare strings ordinally, one storage unit at a time, and never according to the language settings of the machine. Upcasing and downcasing are the same everywhere too. To compare without caring about case, downcase both sides first.

Cursors

A cursor is a position in a string. It is as cheap as an int, but it always sits on a character boundary, and it can only be moved one character at a time, which is what makes it safe. Every cursor function takes the string as well as the cursor.

(: capitalise (-> string string))
(defun (capitalise s)
  (if (string-empty? s)
      s
      (let* ((start (string-cursor-start s))
             (rest (string-cursor-next s start)))
        (string-append (char->string (char-upcase (string-cursor-ref s start)))
                       (substring/cursors s rest (string-cursor-end s))))))

(capitalise "ölstuga")   ;; "Ölstuga"

;; string-index finds the first character matching a predicate, as a cursor.
(: first-word (-> string string))
(defun (first-word s)
  (match (string-index char-whitespace? s)
    ((Some c) (substring/cursors s (string-cursor-start s) c))
    (None s)))

(first-word "hello there world")   ;; "hello"

The folds walk a string for you, and are usually simpler than a cursor:

(: count-vowels (-> string int))
(defun (count-vowels s)
  (string-fold (fun (c n)
                 (if (string-contains? "aeiouy" (char->string (char-downcase c)))
                     (+ n 1)
                     n))
               0 s))

(count-vowels "Hello World")   ;; 3

Building strings

Appending strings in a loop copies the whole string every time. Use a string builder instead, or the stringing collector, which uses one for you:

(: join-words (-> (List string) string))
(defun (join-words words)
  (def sb (stringbuilder-empty))
  (loop (:for w words)
        (:do (when (> (stringbuilder-length sb) 0)
               (stringbuilder-add! sb #\space))
             (stringbuilder-add-string! sb w)))
  (stringbuilder->string sb))

Do not build strings by writing to a string port. Writing to a port is I/O as far as the compiler is concerned, and it will make every function that calls yours potentially asynchronous.

Converting to and from strings

->str turns anything into a string, and println and interpolation use it. It is a trait, so your own types can decide what they look like (the card game did that for Card). For the basic types there are also named conversions:

(int->string 42)         ;; "42"
(double->string 2.5)     ;; "2.5"
(->str 3.0)              ;; "3"
(string->int "42")       ;; 42, and throws on anything that is not a number
(string->double "1.5")   ;; 1.5
(char->string #\a)       ;; "a"
(string->symbol "hi")    ;; 'hi
(keyword->string :hi)    ;; "hi"

These all use the invariant culture: a number written on one machine reads back on any other, and 1.5 is never written as 1,5.

Formatting with (std fmt)

For output where the layout matters, (std fmt) has two layers. The simple one prints a vec of mixed values:

(import (std fmt))

(println* ["Hello, " 42 ", ok? " #t])   ;; Hello, 42, ok? #t

The other one is a small layout language. A layout is a (Vec Block), where a block is a string, a number, a character or one of the combinators, and show prints it:

(show ["[" (padded/left 6 ["foo"]) "]" nl])      ;; [   foo]
(show ["[" (padded/right 6 ["foo"]) "]" nl])     ;; [foo   ]
(show [(numeric/comma 1234567.891) nl])          ;; 1,234,567.891
(show [(numeric 3.14159 #:precision 2) nl])      ;; 3.14
(render->string [(trimmed/right 5 ["abcdefgh"])]) ;; "abcde"

(show [(joined/last (fun (s) (each [s]))
                    (fun (s) (each ["and " s]))
                    (list "a" "b" "c")
                    [", "])
       nl])                                      ;; a, b, and c

;; tabular takes columns, and sizes each to its content.
(show [(tabular [["name" nl "ada" nl "bo"]
                 ["score" nl 12 nl 7]]
                #:sep "  ")])
;; name  score
;; ada   12
;; bo    7

The full set of combinators, paragraphs and settings is described in the reference for (std fmt).

Regular expressions with (std rx)

Regular expressions are written as s-expressions with the #rx(...) hash macro, not as strings. There is no escaping, and a broken pattern is a compile error rather than a runtime one:

(import (std rx))

(def date-rx #rx(seq :bos
                     (=> :year (= 4 :ascii-digit))
                     "-" (=> :month (= 2 :ascii-digit))
                     "-" (=> :day (= 2 :ascii-digit))
                     :eos))
(def number-rx #rx((+ :ascii-digit)))

(rx-match? number-rx "123")                     ;; #t: the whole string
(rx-search? number-rx "abc 123")                ;; #t: anywhere
(rx-split #rx((+ :space)) "a  b   c")           ;; ["a" "b" "c"]
(rx-replace number-rx "a1b22c" "#")             ;; "a#b#c"
(vec-map rx-text (rx-matches number-rx "a1b22c333"))   ;; ["1" "22" "333"]

The most useful building blocks are (seq ...), (or ...), (* r), (+ r), (? r), (= n r), (** min max r), (=> :name r) to capture, :bos and :eos for the ends of the string, and character classes like :digit, :alpha, :space and (in "abc"). Note that :digit is every digit in Unicode; use :ascii-digit for 0 to 9.

The Rx and RxIn patterns use a regex inside a match. Rx matches the whole string and RxIn searches in it:

(: year-of (-> string string))
(defun (year-of s)
  (match s
    ((Rx date-rx (Some m)) (option-value (rx-group m :year) "?"))
    ((RxIn number-rx (Some m)) #"some number: ${(rx-text m)}")
    (_ "no date")))

(year-of "2026-09-30")   ;; "2026"
(year-of "room 101")     ;; "some number: 101"

Define patterns at the top level, as above, rather than writing #rx(...) inside a clause. Otherwise the regex is recompiled at every call, which will tank performance.

Traits

A trait is a set of functions that a type can implement. It is how bjolang does what other languages do with interfaces, type classes or overloading: = is a trait method, so is ->str, and so are length, fold and compare.

Declaring and implementing a trait

def/trait declares a trait. It names a type variable, the implementor, and gives the signatures of its methods. impl implements it for one type:

(def/trait (Describe %a)
  (: describe (-> %a string)))

(impl (Describe Suit)
  (defun (describe s)
    (match s
      (Clubs "clubs") (Diamonds "diamonds") (Hearts "hearts") (Spades "spades"))))

(impl (Describe Rank)
  (defun (describe r)
    (match r
      ((Pip n) (int->string n))
      (Jack "jack") (Queen "queen") (King "king") (Ace "ace"))))

(impl (Describe Card)
  (defun (describe c)
    ;; These two calls go to the Rank and the Suit implementations.
    #"the ${(describe (record-ref c rank))} of ${(describe (record-ref c suit))}"))

(describe (Card (rank Queen) (suit Hearts)))   ;; "the queen of hearts"

A method is called like any other function. Which implementation runs is decided by the type of the argument, at compile time when the type is known there.

Default methods

A trait may give a method a body. An implementation then gets that method for free, but may still write its own:

(def/trait (Describe %a)
  (: describe (-> %a string))
  (: shout (-> %a string))
  (defun (shout x) (string-upcase (describe x))))

(impl (Describe Suit)                    ;; shout comes from the trait
  (defun (describe s)
    (match s
      (Clubs "clubs") (Diamonds "diamonds") (Hearts "hearts") (Spades "spades"))))

(impl (Describe Card)                    ;; this one writes its own shout
  (defun (describe c)
    #"the ${(describe (record-ref c rank))} of ${(describe (record-ref c suit))}")
  (defun (shout c) "A CARD!"))

(shout Spades)                           ;; "SPADES"
(shout (Card (rank Queen) (suit Hearts)))   ;; "A CARD!"

Constraints

A generic function that calls a trait method has to say that its type variable implements the trait. That is written as a where clause at the end of the signature:

(: describe-all (-> (Vec %a) (Vec string)) (where (Describe %a)))
(defun (describe-all xs) (vec-map describe xs))

(describe-all [Ace (Pip 3)])     ;; ["ace" "3"]

(: highest (-> (List %a) (Option %a)) (where (Ord %a)))
(defun (highest xs) (list-max xs))

describe-all can now be called with a vec of anything that has a Describe, and calling it with anything else is a compile error at the call.

For Eq and ->str you may leave the where out: the compiler adds them by itself when a function uses = or ->str on a type variable.

Associated types

A trait has exactly one implementor type. When a method needs another type that depends on the implementor, such as the element type of a collection, the trait declares an associated type with (type %name), and each implementation says what it is:

(def/trait (Container %c)
  (type %item)
  (: first-item (-> %c (Option %item))))

(impl (Container (List %a))
  (type %item %a)
  (defun (first-item xs)
    (match xs
      (() None)
      ((Cons x _) (Some x)))))

(impl (Container string)
  (type %item char)
  (defun (first-item s)
    (if (string-empty? s)
        None
        (Some (string-cursor-ref s (string-cursor-start s))))))

(first-item (list 1 2))   ;; (Some 1)
(first-item "xyz")        ;; (Some #\x)

This is how the prelude’s own Iterable, Collection and Refable work, and why length and fold work on so many types.

Conditional and blanket implementations

An implementation for a generic type can require something of its type variables, with a where after the head. A list can be described if its elements can:

(impl (Describe (List %a))
  (where (Describe %a))
  (defun (describe xs)
    (string-join (list->vec (list-map describe xs)) ", ")))

(describe (list Clubs Hearts))   ;; "clubs, hearts"

A blanket implementation is one for a bare type variable. It applies to every type that has no implementation of its own, and a more specific implementation always wins over it. Only the module that declares a trait may write its blanket:

(def/trait (Weight %a)
  (: weight (-> %a int)))

(impl (Weight %a)                 ;; everything weighs 1 ...
  (defun (weight x) 1))

(impl (Weight string)             ;; ... except strings
  (defun (weight s) (string-count s)))

(weight 42)        ;; 1
(weight "hello")   ;; 5

Eq, Ord and ->str

Three traits from the prelude are worth knowing by heart, since the rest of the library leans on them.

Eq and Ord can be derived with type/derive, as shown earlier. When you write them by hand, they must be written in the module that declares the type, because they are compiled into the type itself: they become its .NET Equals, GetHashCode and CompareTo, which is why a .NET dictionary or a sorted collection agrees with = and compare. = and eq-hash must agree: two values that are equal must have the same hash. compare returns a negative number, zero or a positive number.

(impl (Eq Card)
  (defun (= a b)
    (and (= (record-ref a rank) (record-ref b rank))
         (= (record-ref a suit) (record-ref b suit))))
  (defun (eq-hash c)
    (hash-combine (eq-hash (record-ref c rank)) (eq-hash (record-ref c suit)))))

->str has a blanket implementation that uses .NET’s ToString, which is why printing one of your own types shows its C# name until you implement it.

Values of different types in one collection: dyn

A list holds values of one type. When you need a collection of different types that all implement the same trait, pack each value as a (dyn Trait):

(: render-all (-> (List (dyn ->str)) (List string)))
(defun (render-all xs) (list-map ->str xs))

(render-all (list (dyn ->str 1)
                  (dyn ->str "two")
                  (dyn ->str (Card (rank Queen) (suit Hearts)))))
;; '("1" "two" "Q♥")

Packing is always explicit, and a dyn cannot be turned back into the value it came from. It is the exception rather than the rule: most code is better served by a union.

Traits that are .NET interfaces

Some traits are not implemented in bjolang at all, but stand for a .NET interface, which the type either implements or does not. The numeric traits Num, Integral and Ordered are like that, and are described in the next section. Such a trait is declared with #:clr-constraint, and each method names the interface member it stands for:

(def/trait (Float %a)
  (#:clr-constraint (System.Numerics.IFloatingPointIeee754 %a))
  (: nan?    (-> %a bool) #:clr-member IsNaN)
  (: finite? (-> %a bool) #:clr-member IsFinite))

(nan? (/ 0.0 0.0))    ;; #t

You cannot write an impl of such a trait, and no type declared in bjolang can satisfy one.

Example: cards that sort

Deriving Ord sorts cards by rank, but by the order the cases are declared in. If you want a different order, for example suits in bridge order, spades highest, and aces low, you write compare yourself. Here the cards are compared by rank first, with ace as 1, and by suit when the ranks are equal:

(type (: Card (Struct (: rank Rank) (: suit Suit))))   ;; no type/derive this time

(: rank-value (-> Rank int))
(defun (rank-value r)
  (match r ((Pip n) n) (Ace 1) (Jack 11) (Queen 12) (King 13)))

(: suit-value (-> Suit int))
(defun (suit-value s)
  (match s (Clubs 0) (Diamonds 1) (Hearts 2) (Spades 3)))

(impl (Eq Card)
  (defun (= a b)
    (and (= (rank-value (record-ref a rank)) (rank-value (record-ref b rank)))
         (= (suit-value (record-ref a suit)) (suit-value (record-ref b suit)))))
  (defun (eq-hash c)
    (hash-combine (rank-value (record-ref c rank)) (suit-value (record-ref c suit)))))

(impl (Ord Card)
  (defun (compare a b)
    (def by-rank (compare (rank-value (record-ref a rank))
                          (rank-value (record-ref b rank))))
    (if (= by-rank 0)
        (compare (suit-value (record-ref a suit)) (suit-value (record-ref b suit)))
        by-rank)))

(list-sort (list (Card (rank Ace) (suit Clubs))
                 (Card (rank (Pip 7)) (suit Spades))
                 (Card (rank (Pip 7)) (suit Hearts))
                 (Card (rank King) (suit Diamonds))))
;; A♣ 7♥ 7♠ K♦

Nothing about list-sort knows about cards. It asks for (Ord %a), and now Card has one, so sorting, least, list-max, less? and ordered maps keyed by cards all work.

Numbers

The types

There are eight numeric types, each a .NET primitive:

There is no float and no decimal. A char is not a number: it can be compared and converted, but not added.

Writing numbers

A number with a suffix is of that type. A decimal point or an exponent makes it a double:

A number without a suffix has no type of its own. It takes the type of wherever it is used, and is an int only when nothing says otherwise:

(: doubled (-> ushort ushort))
(defun (doubled x) (* x 2))    ;; the 2 is a ushort

(doubled 21)                   ;; 42, and 21 is a ushort too

(let ((start 5))
  (+ start 3L))                ;; 8L: start was a long all along

A literal that does not fit the type it ends up with is a compile error. (doubled 99999) says that 99999 does not fit in a ushort.

Arithmetic

+ - * / % are the C# operators and do what they do in C#. With more than two arguments they fold, so (+ 1 2 3) is 6. (- x) negates.

(/ 7 2)       ;; 3: integer division truncates
(/ 7.0 2.0)   ;; 3.5
(% -7 2)      ;; -1: the remainder takes the sign of the dividend
(% 7 -2)      ;; 1

Integer arithmetic wraps around on overflow, silently, as it does in C#:

(: bump (-> int int))
(defun (bump n) (+ n 1))

(bump 2147483647)   ;; -2147483648

Integer division by zero throws System.DivideByZeroException. Dividing a double by zero gives infinity, and (/ 0.0 0.0) is NaN. The bit operations are bitwise-and, bitwise-or, bitwise-xor, shift-left, shift-right and shift-right-logical.

Converting

There is no automatic conversion between numeric types. Multiplying an int variable by 1.5 is a type error:

(: scale (-> int double))
(defun (scale n) (* n 1.5))
;; Type error: these types do not match.
;;   int
;;   double

cast converts, with the target written as a .NET type. It behaves like a C# cast: converting a double to an integer rounds toward zero, and narrowing an integer wraps.

(: scale (-> int double))
(defun (scale n) (* (cast System.Double n) 1.5))

(: average (-> (Vec int) double))
(defun (average xs)
  (/ (cast System.Double (fold + 0 xs))
     (cast System.Double (vec-length xs))))

(cast System.Int32 2.7)    ;; 2
(cast System.Int32 -2.7)   ;; -2
(cast System.Int64 5)      ;; 5L

Converting to and from strings was covered in the section on text. Remember that string->int throws on bad input, so input that is not yours should go through try:

(: parse (-> string (Result System.Exception int)))
(defun (parse s) (try (string->int s) #:catch (System.FormatException)))

Comparing

There are two ways to compare, and they are for different things:

• <, >, <=, >= are the C# operators. They work on numbers and characters, and nothing else.
• compare, and everything built on it (less?, greater?, at-most?, at-least?, least, greatest, list-sort, list-min, list-max), works on every type with an Ord: numbers, strings, booleans and your own types.

(compare 2.5 1.5)             ;; 1
(least "pear" "apple")        ;; "apple"
(list-sort (list 5 3 9))      ;; '(3 5 9)
(min 3 7)                     ;; 3, but only for numbers
(least 3 7)                   ;; 3, for anything with an Ord

Generic numeric code

A function that does arithmetic on a type variable needs a constraint that says the type is a number:

(: sum-all (-> (Vec %a) %a) (where (Num %a)))
(defun (sum-all xs) (fold + 0 xs))

(sum-all [1 2 3])       ;; 6
(sum-all [1.5 2.5])     ;; 4.0

(: low-bit (-> %a %a) (where (Integral %a) (Num %a)))
(defun (low-bit x) (bitwise-and x 1))

(low-bit 7)             ;; 1
(low-bit 8L)            ;; 0L

Unlike Eq, these constraints are never added for you. They are .NET interfaces, and no type you declare can ever implement them, so they say what a type is rather than what it can do, and bjolang wants that written down. The compiler tells you exactly what is missing, though:

Type Error at nums.bjo:2: 'low-bit' needs (Num %a), which its signature does not declare. [...] Write:
  (: low-bit ... (where (Integral %a) (Num %a)))

If a function only compares values, use (where (Ord %a)) instead. It works for strings and your own types too.

The maths functions

abs, sign, min, max, clamp, zero?, even?, odd? and sqrt are in the prelude. The rest of System.Math is in (std maths), and works on doubles:

(import (std maths))

(sqrt 9)            ;; 3.0: the int 9 widens to a double at the call
(pow 2.0 10.0)      ;; 1024.0
(floor -2.5)        ;; -3.0
(truncate -2.5)     ;; -2.0
(round 2.5)         ;; 2.0: banker's rounding, to the nearest even
(round 3.5)         ;; 4.0
(clamp 5 1 3)       ;; 3
(abs -5)            ;; 5

The logarithms are loge (natural), log2, log10 and (log-base x b). The name log is taken by the logging function of the prelude.

Writing programs

While the first part focused on the core language constructs in single files, this part covers the wider ecosystem: breaking programs into modules, managing project dependencies, handling I/O, concurrency with bjoroutines, .NET interop, macros, and testing.

Throughout this part we will continue building on the card game from Part 1, gradually turning it into a full project complete with a deck module, a persistent high-score file, concurrent players, and a custom #card(Q hearts) literal.

Modules

In Bjolang, every .bjo file is implicitly a module named after its file. There are no namespace declarations or enclosing module blocks; instead, a module simply exports whatever public API it wants other files to see, leaving everything else private by default.

Splitting the game into files

Here is the deck from the first part as a module of its own. Put it in deck.bjo:

(import (std random))

(export Suit Rank Card full-deck shuffle card-points)

(type/derive (Eq Ord)
  (: Suit (Union Clubs Diamonds Hearts Spades))
  (: Rank (Union (: Pip int) Jack Queen King Ace))
  (: Card (Struct (: rank Rank) (: suit Suit))))

(impl (->str Suit)
  (defun (->str s)
    (match s (Clubs "♣") (Diamonds "♦") (Hearts "♥") (Spades "♠"))))

(impl (->str Rank)
  (defun (->str r)
    (match r
      ((Pip n) (int->string n))
      (Jack "J") (Queen "Q") (King "K") (Ace "A"))))

(impl (->str Card)
  (defun (->str c) #"${(record-ref c rank)}${(record-ref c suit)}"))

;; Not exported: only this module needs them.
(def all-suits [Clubs Diamonds Hearts Spades])
(def all-ranks [(Pip 2) (Pip 3) (Pip 4) (Pip 5) (Pip 6) (Pip 7) (Pip 8)
                (Pip 9) (Pip 10) Jack Queen King Ace])

(: full-deck (-> (Vec Card)))
(defun (full-deck)
  (loop (:for s all-suits)
        (:subloop)
        (:for r all-ranks)
        (:acc deck (vecing (Card (rank r) (suit s))))
        => deck))

(: shuffle (-> (Vec Card) (Vec Card)))
(defun (shuffle deck) (shuffle-vec deck))

(: card-points (-> Card int))
(defun (card-points c)
  (match c
    ((Card (rank (Pip n))) n)
    ((Card (rank Ace)) 11)
    (_ 10)))