keleusma 0.2.1

Total Functional Stream Processor with definitive WCET and WCMU verification, targeting no_std + alloc embedded scripting
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

# Chapter 14. Multiheaded Functions and Guards

> Part III, Shaping Data. Chapter 14 of 40.
> Previous: [Chapter 13, Pattern Matching in Depth](./13_pattern_matching.md).
> Next: [Chapter 15, The Three Function Categories](./15_three_function_categories.md).

## Goal

By the end of this chapter you will be able to write a function as
several heads, each handling a different case.

## A prepared response for each cue

A performer rehearses a prepared response for each cue the conductor
might give. The responses are written out separately, one per cue, rather
than as one tangled instruction. Keleusma allows a function to be written
the same way. A single function name may have several heads, each with
its own case, and the right head is chosen when the function is called.

## Heads that match a value

Here a function gives back the MIDI number of a fret on a guitar's high E
string. The open string, fret zero, is treated as its own case:

````
fn fret_note(0) -> Word { 64 }
fn fret_note(n: Word) -> Word { 64 + n }

fn main() -> Word {
    fret_note(5)
}
````

Run it with `keleusma run`. The output is `69`.

There are two heads for `fret_note`. The first head matches only the
exact argument `0`. The second head, with the binding `n`, matches any
argument. The heads are tried in the order written, and the first that
fits is the one used. The call `fret_note(5)` does not match `0`, so it
falls to the second head, which gives `64 + 5`, that is `69`, the MIDI
number of A4.

The order matters. The specific case, `0`, is written before the general
case, `n`. Written the other way round, the general head would catch
every call and the `0` head would never be reached.

## Heads with guards

A head may instead carry a `when` guard, the same guard seen on `match`
arms in Chapter 13. The head is used only when its guard is true:

````
fn tempo_class(bpm: Word) -> Word when bpm < 60 { 0 }
fn tempo_class(bpm: Word) -> Word when bpm < 120 { 1 }
fn tempo_class(bpm: Word) -> Word { 2 }

fn main() -> Word {
    tempo_class(90)
}
````

Run it. The output is `1`. The call `tempo_class(90)` tries the first
head, whose guard `90 < 60` is false, then the second, whose guard
`90 < 120` is true. The second head runs and gives `1`, the class for a
moderate tempo. The final head has no guard and catches everything that
reached it.

## Multiheaded functions or match

A multiheaded function and a `match` express related ideas. A `match`
chooses inside one function body. A multiheaded function chooses which
body to enter at all. Use a multiheaded function when the cases are
substantial enough to deserve separate definitions, and a `match` when
the choice is a small step within a single computation.

## What you now know

- A function name may have several heads, each handling one case.
- A head may match a literal argument or bind it with a name.
- A head may carry a `when` guard.
- Heads are tried in source order, and the first that fits is used, so
  specific cases come before general ones.

That completes Part III. You can now shape data as structs, enums,
tuples, and arrays, take it apart with `match`, and dispatch a function
across several heads. Part IV turns to the heart of the language: the
three kinds of function and the way a program talks to its host.