🐉 CMRA User Guide

📑 Contents

• Installation
• Running Programs
• Fire Dragon syntax
• Shadow Dragon syntax
• Expressions & Types
• Direction Control
• Block Conditionals
• Writing Loops
• Common Pitfalls
• Example Programs
• Extending the Language

⚡ Installation

# From the project root, with your venv activated:
      pip install cmra

      # Development install from source (optional):
      pip install -e .

      # Then run any .cmra or .cmrash file:
cmra myprogram.cmra

.\cmra.ps1 "test cases\test.cmra"

# Add to PATH for this session so `cmra` works anywhere:
$env:PATH = "C:\path\to\CMRA;$env:PATH"
cmra test.cmra

# Via the installed package:
python -m cmra.cli myprogram.cmra

# Or the legacy single-file interpreters:
python cmra.py myprogram.cmra
python cmrash.py myprogram.cmrash

▶️ Running Programs

# Basic usage
cmra <filename>
    cmrash <filename>

# Examples
cmra "test cases\test.cmra"
cmra projects\calculator.cmra
    cmra projects\fizzbuzz.cmra
    cmrash "test cases cmrash\test.cmrash"

Extensions are only conventions — either interpreter can read any file.

🐲 Fire Dragon Syntax

Entry point: cmra.py / src/cmra/fire.py. Expressive, dragon-flavored keywords.

Example

x bind 3
name bind "Chimera"
roar name          murmur prints: Chimera
roar x * 4        murmur prints: 12.0

🌑 Shadow Dragon Syntax

Entry point: cmrash.py / src/cmra/shadow.py. Minimal syntax, same execution model.

x = 3
name = "Chimera"
print name         ; prints: Chimera

🔢 Expressions & Types

• Numbers are always floats: 2 → 2.0
• Strings use single or double quotes: "hello" 'world'
• Operators: + - * / and comparisons < > <= >= ==
• Precedence: * / bind tighter than + -, comparisons are lowest
• String + anything → string concatenation: "val: " + x → "val: 5.0"
• Variables are global and persist throughout execution

x bind 4
roar x * 3 + 1        murmur → 13.0
roar "val: " + x      murmur → "val: 4.0"
roar x == 4           murmur → 1 (true) or 0 (false)

🧭 Direction Control

CMRA's defining feature: a global direction controls how the interpreter steps through lines.

The program terminates when the instruction pointer goes past the first or last line.

Tip: Prefer soar/dive over reverse in loops — they are idempotent (calling twice is safe). reverse toggles, so calling it twice cancels out.

📦 Block Conditionals

A block groups multiple lines under a single condition:

sniff x < 5 :
{
  roar "x is small"
  roar x
}

Block entry rules

This means a soar inside a block takes effect immediately on the reverse pass — the key to building loops.

🔁 Writing Loops

CMRA has no native loop keyword. Use direction reversal + flag guards.

Pattern 1 — Inline flagged loop

murmur ── setup ─────────────────────────────────
i bind 0
flag bind 1

murmur ── top boundary: re-enter forward if done ─
sniff i < 10 : sniff flag == 0 : dive

murmur ── flag guard (0 = forward pass) ──────────
flag bind 0

murmur ── body: only runs on forward pass ─────────
sniff flag == 0 : roar i
sniff flag == 0 : i bind i + 1

murmur ── restore flag ───────────────────────────
flag bind 1

murmur ── bottom boundary: reverse if still looping
sniff i < 10 : sniff flag == 1 : soar

How it works step-by-step

1. Reaches bottom sniff → condition true → soar → direction = reverse
2. Re-traverses lines in reverse, skipping body (guarded by flag == 0)
3. Reaches top boundary → dive → direction = forward
4. Forward pass runs body, increments i, reaches bottom again
5. Repeats until i < 10 is false

Pattern 2 — Block loop

i bind 0
flag bind 0
sniff i < 10 :
{
  sniff flag == 1 : dive
  sniff i < 10 : flag bind 1
  sniff flag == 1 : roar i
  sniff flag == 1 : i bind i + 1
  sniff i < 10 : flag bind 0
  sniff flag == 0 : soar
}

Key rule: Always guard loop body lines with a flag variable so the reverse traversal doesn't re-execute them.

⚠️ Common Pitfalls

murmur BAD — prints twice per iteration!
roar i
i bind i + 1

murmur GOOD — only runs on forward pass
sniff flag == 0 : roar i
sniff flag == 0 : i bind i + 1

🎮 Example Programs

roar "Hello, Chimera!"

i bind 0
flag bind 1
sniff i <= 5 : sniff flag == 0 : dive
flag bind 0
sniff flag == 0 : roar i
sniff flag == 0 : i bind i + 1
flag bind 1
sniff i <= 5 : sniff flag == 1 : soar

cmra projects\calculator.cmra       # factorial, series, power
cmra projects\countdown.cmra        # reversible countdown
cmra projects\fizzbuzz.cmra         # fizzbuzz 1–15
cmra projects\story_adventure.cmra  # interactive text adventure

🛠️ Extending the Language

To add a new command to the Fire Dragon interpreter (src/cmra/fire.py):

1. Top-level dispatch — add a branch in execute_line() alongside roar, bind, sniff
2. Inline action support — add it to execute_inline_action() so it can appear after : in sniff chains
3. Test it — add a .cmra file to test cases\

Look at how roar, bind, dive, and soar are implemented — they follow the same two-step pattern.

📖 The full keyword mapping is in keybind.txt — Fire ↔ Shadow cheatsheet.