# Control Flow

Control flow in Cagire's Forth comes in two families. The first is compiled syntax — `if/then` and `case` — which the compiler handles directly as branch instructions. The second is quotation words — `?`, `!?`, `ifelse`, `select`, `apply` — which pop `( ... )` quotations from the stack and decide whether to run them. Probability and periodic execution (`chance`, `every`, `bjork`) are covered in the Randomness tutorial.

## Branching with if / else / then

Push a condition, then `if`. Everything between `if` and `then` runs only when the condition is truthy:

```forth
;; degrade sound if true
coin if
  7 crush
then
sine sound
c4 note
1 decay
.
```

The crush is applied on half the hits. The sound always plays. Add `else` for a two-way split:

```forth
coin if
  c5 note
else
  c3 note
then
saw sound
0.3 verb
0.5 decay
0.6 gain
.
```

These are compiled directly into branch instructions — they will not appear in the dictionary. This is a "low level" way to use conditionals in Cagire.

## Matching with case

For matching a value against several options. Cleaner than a chain of `if`s when you have more than two branches:

```forth
1 8 rand 4 mod case
  0 of c3 note endof
  1 of e3 note endof
  2 of g3 note endof
  3 of a3 note endof
endcase
tri s
2 fm 0.99 fmh
0.6 gain 0.2 chorus
1 decay
800 lpf
.
```

A different root note each time the pattern loops. The last line before `endcase` is the default — it runs when no `of` matched:

```forth
iter 3 mod case
  0 of 0.9 gain endof
  0.4 gain
endcase
saw s
.5 decay
c4 note
.
```

Like `if/then`, `case` is compiled syntax and does not appear in the dictionary.

## Quotation Words

The remaining control flow words operate on quotations — `( ... )` blocks sitting on the stack. Each word pops one or more quotations and decides whether or how to execute them.

### ? and !?

`?` executes a quotation if the condition is truthy:

```forth
( 0.4 verb 6 crush ) coin ?
tri sound 2 fm 0.5 fmh
c3 note 0.5 gain 2 decay
.
```

Reverb on half the hits. `!?` is the opposite — executes when falsy:

```forth
( 0.5 delay 0.9 delayfeedback ) coin !?
saw sound
c4 note
500 lpf
0.5 decay
0.5 gain
.
```

Quiet on half the hits. These pair well with `chance` and `fill` from the Randomness tutorial.

### ifelse

Two quotations, one condition. The true branch comes first:

```forth
( c3 note ) ( c5 note ) coin ifelse
saw sound 0.3 verb
0.5 decay 0.6 gain
.
```

Reads naturally: "c3 or c5, depending on the coin."

```forth
( 0.8 gain ) ( 0.3 gain ) fill ifelse
tri s c4 note 0.2 decay .
```

Loud during fills, quiet otherwise.

### select

Choose the nth quotation from a list. The index is 0-based:

```forth
( c4 ) ( e4 ) ( g4 ) ( b4 ) 0 3 rand select
note sine s 0.5 decay .
```

Four notes of a major seventh chord picked randomly. Note that this is unnecessarily complex :)

### apply

When you have a quotation and want to execute it unconditionally:

```forth
( dup + ) apply
```

Pops the quotation and runs it. Simpler than `?` when there is no condition to check.

## More!

For probability gates, periodic execution, and euclidean rhythms, see the Randomness tutorial. For generators and ranges, see the Generators tutorial.