From d4daa6d0a9c2efb44ecc2d60b0698b2d7abdd5a5 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 12 Apr 2026 11:39:12 +0000
Subject: [PATCH] docs: enum type + new CLI flags in the language guide

Documents the \`enum Name { Variant, ... }\` syntax and adds
\`--dump-ir\` and \`--use-ast\` to the CLI flag table. Also adds
an integration test covering enum-variant-as-condition and variant
assignment through the full compile pipeline.

https://claude.ai/code/session_01W6eQFStA66EuMKHUFo2rx3
---
 docs/language-guide.md    | 36 +++++++++++++++++++++++++++++++-----
 tests/integration_test.rs | 21 +++++++++++++++++++++
 2 files changed, 52 insertions(+), 5 deletions(-)

diff --git a/docs/language-guide.md b/docs/language-guide.md
index f542e13..deee623 100644
--- a/docs/language-guide.md
+++ b/docs/language-guide.md
@@ -132,6 +132,29 @@ const SPEED: u8 = 3
 const SIN_TABLE: u8[8] = [0, 49, 90, 117, 127, 117, 90, 49]
 ```
 
+### Enums
+
+Enums declare a named set of `u8` constants. Each variant is assigned an
+index starting at 0 in declaration order:
+
+```
+enum Direction { Up, Down, Left, Right }
+// Up=0, Down=1, Left=2, Right=3
+
+var player_dir: u8 = Up
+
+on frame {
+    if button.left  { player_dir = Left }
+    if button.right { player_dir = Right }
+    if player_dir == Down { /* ... */ }
+}
+```
+
+Variant names are global — they are flattened into the top-level symbol
+table, so a variant cannot share its name with any other constant,
+variable, or function (E0501). An enum cannot have more than 256
+variants because each is stored as a `u8`.
+
 ### Memory Placement Hints
 
 The NES has 256 bytes of zero-page RAM with faster access. You can hint where variables should be placed:
@@ -784,13 +807,16 @@ nescript build game.ne
 nescript build game.ne --output my_game.nes
 nescript build game.ne --debug
 nescript build game.ne --asm-dump
+nescript build game.ne --dump-ir
 ```
 
-| Flag          | Description                                    |
-|---------------|------------------------------------------------|
-| `--output`    | Set output ROM file path (default: input.nes)  |
-| `--debug`     | Enable debug mode with runtime checks          |
-| `--asm-dump`  | Dump generated 6502 assembly to stdout         |
+| Flag          | Description                                                    |
+|---------------|----------------------------------------------------------------|
+| `--output`    | Set output ROM file path (default: input.nes)                  |
+| `--debug`     | Enable debug mode with runtime checks                          |
+| `--asm-dump`  | Dump generated 6502 assembly to stdout                         |
+| `--dump-ir`   | Dump the lowered IR program (after optimization) to stdout     |
+| `--use-ast`   | Use the legacy AST-based codegen (default is the IR codegen)   |
 
 ### Check
 
diff --git a/tests/integration_test.rs b/tests/integration_test.rs
index dd298a1..525b5de 100644
--- a/tests/integration_test.rs
+++ b/tests/integration_test.rs
@@ -141,6 +141,27 @@ fn program_with_functions() {
     rom::validate_ines(&rom_data).expect("should be valid iNES");
 }
 
+#[test]
+fn program_with_enums() {
+    let source = r#"
+        game "Enums" { mapper: NROM }
+        enum Direction { Up, Down, Left, Right }
+        enum Mode { Idle, Running, Jumping }
+
+        var dir: u8 = 0
+        var mode: u8 = 0
+
+        on frame {
+            if button.right { dir = Right }
+            if button.left { dir = Left }
+            if dir == Right { mode = Running }
+        }
+        start Main
+    "#;
+    let rom_data = compile(source);
+    rom::validate_ines(&rom_data).expect("should be valid iNES");
+}
+
 #[test]
 fn program_with_inline_asm() {
     let source = r#"