🐉 CMRA (Chimera)

🧪 Why an esolang?

• Experimental control flow: A single global DIRECTION walks the program forwards or backwards.
• Concept-first design: Meant for learning, puzzling, and play — not for production.
• Minimal surface area: Just variables, expressions, prints, and directional checks/blocks.
• Readable flair: Dragon-flavored aliases make intent obvious and fun.

⚡ Quick start

Option 1 — pip install (recommended)

Install from PyPI to get the cmra command inside your virtual environment:

# 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 "test cases\test.cmra"
cmra projects\fizzbuzz.cmra
cmrash "test cases cmrash\test.cmrash"

Option 2 — PowerShell wrapper (no install needed)

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

Option 3 — Python directly

# Fire Dragon
python -m cmra.cli "test cases\test.cmra"
python .\cmra.py "test cases\test.cmra"

# Shadow Dragon
python .\cmrash.py "test cases cmrash\test.cmrash"

# Also works with `py` instead of `python`
py cmra.py "test cases\test_strings.cmra"

Option 4 — CMRA Esoteric Language Extension

For the best developer experience, install the official extension:

• Marketplace: Install directly from the VS Code Marketplace or Open VSX Registry.
• Manual Install: Download the latest .vsix from the GitHub Releases.

Run command: Extension execution defaults to python -m cmra "<file>", with optional override via cmra.executablePath.

Diagnostics: `.cmra` shows themed randomized messages; `.cmrash` shows concise technical messages focused on = syntax.

Diagnostic message examples

• Fire Dragon: Line 4: 'x' is but a myth in this realm. (Hint: bind before use)
• Fire Dragon: Line 5: Fire Dragon rejects '=' in this chant. (Hint: use bind)
• Shadow Dragon: Line 4: Undefined variable 'x'. (Hint: initialize with =)
• Shadow Dragon: Line 5: Unexpected 'bind' in .cmrash. (Hint: use =)

Full diagnostics catalog: cmra-vscode-extension/ERROR_MESSAGES.md.

Option 5 — Standalone Executable (Windows)

Don't have Python? Download the standalone cmra.exe from the GitHub Releases to run programs natively!

📖 See GUIDE.md for the full user guide including loop patterns and tips.

🐲 Languages

🧭 Execution model

• Programs step line-by-line with a global DIRECTION: 1 = forwards, -1 = reverse.
• CMRA: dive sets forwards; soar sets reverse. Simplified: reverse toggles.
• Block sniff/check returns into the block (first/last line) so a reverse inside takes effect immediately.
• Numbers are floats; strings use single/double quotes. + concatenates if either side is a string.
• Precedence: *, / > +, - > comparisons.

Block entry ritual

• True + forward → jump to the first line inside the block
• True + reverse → jump to the last line inside the block
• False → skip past the entire block

🌀 Reusable loop patterns

Flagged loop (inline)

flag bind 1
sniff cond : sniff flag == 0 : dive
flag bind 0
sniff flag == 0 : ;;; body
sniff flag == 0 : ;;; step
flag bind 1
sniff cond : sniff flag == 1 : soar

Block loop (brace style)

flag bind 0
sniff cond :
{
  sniff flag == 1 : dive
  sniff cond : flag bind 1
  sniff flag == 1 : ;;; body
  sniff flag == 1 : ;;; step
  sniff cond : flag bind 0
  sniff flag == 0 : soar
}

Tip: Guard body/step with flag so reverse traversal doesn’t repeat the body. Apply the same pattern to nested loops.

🗺️ Keyword mapping

Note: The simplified language has only reverse. CMRA splits direction control into dive (forward) and soar (reverse).

🧩 Examples

Inline check (CMRA)

sniff x <= 10 : roar x

Block check (CMRA)

sniff x < 5 : {
  roar "inside"
}

Simplified reverse with nested checks

check x < 5 : {
  print x + 5
  check flag == 1 : reverse
}

🎮 Tests & projects

All tests live in test cases/:

• test.cmra — Hello + loop using sniff/dive/soar
• test_strings.cmra — String literals and concatenation
• test_arith.cmra — Arithmetic precedence (expected: 7, 9)
• test_cond.cmra — Inline conditions (expected: ok, then 3)
• test_block.cmra — Block-style sniff (expected: inside, then after)

Cool projects

• projects/story_adventure.cmra — Interactive text adventure
• projects/calculator.cmra — Factorial, series sum, power (both loop styles)
• projects/countdown.cmra — Countdown and reversible counters
• projects/fizzbuzz.cmra — FizzBuzz with counter-based modulo
• projects/bouncing_ball.cmra — Frame-by-frame bouncing ball effect (no terminal control required)

Run them

# Test cases
    cmra "test cases\test_block.cmra"
    cmra "test cases\test_strings.cmra"

    # Projects
    cmra projects\calculator.cmra
    cmra projects\countdown.cmra
    cmra projects\fizzbuzz.cmra
    cmra projects\story_adventure.cmra

    # Legacy single-file interpreter (optional)
    python .\cmra.py "test cases\test_block.cmra"

⚠️ Dragon's wisdom (pitfalls & tips)

📬 Reach Out

If you build something cool with CMRA or want to collaborate, feel free to connect:

• GitHub (@Chimera418)
• Discord (gamingchimera)

📦 File inventory

• cmra.py — Fire Dragon interpreter (alias keywords, inline + block sniff)
• cmrash.py — Shadow Dragon interpreter (check, print, reverse, braces)
• prototype.py — Compact baseline with inline sniff
• keybind.txt — Keyword mapping cheatsheet
• index.html + styles.css — This site
• projects/ — Showcase programs
• test cases/ — Examples and regression tests

🛠️ Extending the language

Want to add new commands? Follow this pattern:

1. Top-level dispatch — Add your command alongside roar/print.
2. Inline action executor — Enable it in nested sniff/check statements.

Study how roar, bind, dive, and soar are implemented in both interpreters.