# OrbaLang Exercise Books

A hands-on workbook series for **v0.3-alpha**. Each book builds on the previous one.
There is no online playground — you write `.orba` files locally and verify with the CLI.

**Prerequisites:** Node.js 18+, `npm install` in the repo root.

**Companion material:** [USER-GUIDE.md](../USER-GUIDE.md) · [examples/](../../examples/)

---

## How to work through the series

1. Read the book’s **Concept recap** (one page).
2. Copy a **starter file** from `starters/` or create a new file under `exercises/work/` (gitignored locally — create the folder yourself).
3. Complete each exercise; run the **Verify** commands.
4. Compare with `solutions/` only after you have a passing transpile or lint.
5. Optional stretch goals are marked **Challenge**.

Recommended verify commands:

```powershell
npm run orba -- exercises/work/my_file.orba --target python
npm run orba -- exercises/work/my_file.orba --target python-rule
npm run orba -- exercises/work/my_file.orba --lint
npm run orba -- exercises/work/my_file.orba --target markdown
```

---

## The books

| Book | Title | You will learn |
| ---- | ----- | -------------- |
| [01](book-01-functions-basics.md) | **Functions — First steps** | `input` / `output` / `steps` / `return`, audit, first transpile |
| [02](book-02-conditionals-and-logic.md) | **Conditionals & Boolean logic** | `if` / `else` / `end`, nesting, comparisons, `and` / `or` |
| [03](book-03-stdlib-dates-and-text.md) | **Stdlib, dates & text** | `round`, `min`, `max`, `length`, `coalesce`, date helpers |
| [04](book-04-governance-and-externals.md) | **Governance & externals** | Inline `govern`, `external:` hooks, rule blocks |
| [05](book-05-top-level-rules.md) | **Top-level rules** | `when` / `then` / `audit`, approval, deny, escalate |
| [06](book-06-transpilation-workshop.md) | **Transpilation workshop** | Multi-target emit, JSON/Markdown, lint, rule validators |
| [07](book-07-reverse-translation.md) | **Reverse translation** | `--lift` from JSON and python-rule |

**Estimated time:** 2–4 hours per book (books 01–06); book 07 ~1 hour.

---

## File layout

```
docs/exercises/
  README.md                 ← this index
  book-01-….md … book-06-….md
  starters/                 ← incomplete files for fill-in exercises
  solutions/                ← reference answers (+ SOLUTIONS.md walkthrough)
```

Create your own working directory (not committed):

```
exercises/work/             ← your attempts (add to .gitignore if you like)
```

---

## Progress checklist

- [ ] Book 01 — at least exercises 1–3 transpile to `python`
- [ ] Book 02 — nested `if` exercise passes `--lint`
- [ ] Book 03 — one function uses `round` and one uses `coalesce`
- [ ] Book 04 — one function with `govern` and one with `external`
- [ ] Book 05 — three rule types: approval, deny, escalate
- [ ] Book 06 — own rule exported to `python-rule`, `json`, and `markdown`

When all boxes are checked, you are ready to author production-style OrbaLang policies and functions.