1 files changed, 222 insertions, 0 deletions
diff --git a/awk/scheme/scheme/docs/scheme-compilation-examples.md b/awk/scheme/scheme/docs/scheme-compilation-examples.md
new file mode 100644
index 0000000..43bae3a
--- /dev/null
+++ b/awk/scheme/scheme/docs/scheme-compilation-examples.md
@@ -0,0 +1,222 @@
+# Scheme to VM Instruction Examples
+
+## Basic Arithmetic
+
+### Simple Addition
+```scheme
+(+ 1 2)
+```
+```awk
+# VM Instructions
+0 PUSH_CONST N:1
+1 PUSH_CONST N:2
+2 ADD
+```
+
+### Nested Arithmetic
+```scheme
+(+ (* 3 4) (- 10 5))
+```
+```awk
+# VM Instructions
+0 PUSH_CONST N:3
+1 PUSH_CONST N:4
+2 MUL           # Stack now has 12
+3 PUSH_CONST N:10
+4 PUSH_CONST N:5
+5 SUB           # Stack now has 5
+6 ADD           # Final result 17
+```
+
+## Variable Binding and Use
+
+### Let Expression
+```scheme
+(let ((x 5))
+  (+ x 1))
+```
+```awk
+# VM Instructions
+0 MAKE_ENV 1        # Create environment with 1 slot
+1 PUSH_CONST N:5    # Push initial value
+2 STORE_LOCAL 0     # Store into x's slot
+3 LOAD_LOCAL 0      # Load x
+4 PUSH_CONST N:1
+5 ADD
+```
+
+### Nested Let
+```scheme
+(let ((x 5))
+  (let ((y (+ x 1)))
+    (* x y)))
+```
+```awk
+# VM Instructions
+0 MAKE_ENV 1        # Environment for x
+1 PUSH_CONST N:5
+2 STORE_LOCAL 0     # Store x
+3 MAKE_ENV 1        # Environment for y
+4 LOAD_LOCAL 0      # Load x
+5 PUSH_CONST N:1
+6 ADD
+7 STORE_LOCAL 0     # Store y
+8 LOAD_LOCAL 1      # Load x (from outer env)
+9 LOAD_LOCAL 0      # Load y
+10 MUL
+```
+
+## Function Definition and Call
+
+### Simple Function
+```scheme
+(define (add1 x)
+  (+ x 1))
+```
+```awk
+# VM Instructions
+0 MAKE_FUNCTION 2   # Create function pointing to instruction 2
+1 STORE_GLOBAL 0    # Store in global env slot for add1
+2 MAKE_ENV 1        # Function body starts here
+3 LOAD_LOCAL 0      # Load parameter x
+4 PUSH_CONST N:1
+5 ADD
+6 RETURN
+```
+
+### Function Call
+```scheme
+(add1 5)
+```
+```awk
+# VM Instructions
+0 PUSH_CONST N:5    # Push argument
+1 LOAD_GLOBAL 0     # Load add1 function
+2 CALL 1            # Call with 1 argument
+```
+
+## List Operations
+
+### List Construction
+```scheme
+(cons 1 (cons 2 '()))
+```
+```awk
+# VM Instructions
+0 PUSH_CONST N:1
+1 PUSH_CONST N:2
+2 PUSH_CONST NIL:
+3 CONS            # Creates (2 . nil)
+4 CONS            # Creates (1 . (2 . nil))
+```
+
+### List Operations
+```scheme
+(car (cons 1 2))
+```
+```awk
+# VM Instructions
+0 PUSH_CONST N:1
+1 PUSH_CONST N:2
+2 CONS
+3 CAR
+```
+
+## Conditionals
+
+### If Expression
+```scheme
+(if (< x 0)
+    (- 0 x)
+    x)
+```
+```awk
+# VM Instructions
+0 LOAD_LOCAL 0      # Load x
+1 PUSH_CONST N:0
+2 NUM_LT           # Compare x < 0
+3 JUMP_IF_FALSE 7  # Skip to else branch if false
+4 PUSH_CONST N:0
+5 LOAD_LOCAL 0     # Load x again
+6 SUB             # Compute 0 - x
+7 JUMP 9          # Skip else branch
+8 LOAD_LOCAL 0    # Else branch: just load x
+9 NOP             # Continue here
+```
+
+## Closures
+
+### Create Closure
+```scheme
+(let ((x 1))
+  (lambda (y) (+ x y)))
+```
+```awk
+# VM Instructions
+0 MAKE_ENV 1        # Environment for x
+1 PUSH_CONST N:1
+2 STORE_LOCAL 0     # Store x
+3 MAKE_FUNCTION 5   # Create function
+4 MAKE_CLOSURE 1    # Capture current env
+5 MAKE_ENV 1        # Function body starts here
+6 LOAD_FREE 0       # Load captured x
+7 LOAD_LOCAL 0      # Load parameter y
+8 ADD
+9 RETURN
+```
+
+## Recursive Function
+
+### Factorial
+```scheme
+(define (factorial n)
+  (if (= n 0)
+      1
+      (* n (factorial (- n 1)))))
+```
+```awk
+# VM Instructions
+0 MAKE_FUNCTION 2    # Create factorial function
+1 STORE_GLOBAL 0     # Store in global env
+2 MAKE_ENV 1         # Function body starts
+3 LOAD_LOCAL 0       # Load n
+4 PUSH_CONST N:0
+5 NUM_EQ            # Compare n = 0
+6 JUMP_IF_FALSE 9   # Skip to else branch
+7 PUSH_CONST N:1    # Return 1 for base case
+8 RETURN
+9 LOAD_LOCAL 0      # Load n
+10 LOAD_LOCAL 0     # Load n again
+11 PUSH_CONST N:1
+12 SUB             # Compute n - 1
+13 LOAD_GLOBAL 0   # Load factorial function
+14 TAIL_CALL 1     # Tail call factorial(n-1)
+15 MUL             # Multiply n * factorial(n-1)
+16 RETURN
+```
+
+## Implementation Notes
+
+1. Environment Chain
+- Each MAKE_ENV creates a new frame
+- LOAD_LOCAL counts down the chain for outer references
+- STORE_LOCAL works similarly
+
+2. Closure Creation
+- MAKE_CLOSURE captures current environment
+- LOAD_FREE accesses captured variables
+
+3. Tail Calls
+- TAIL_CALL reuses current stack frame
+- Essential for recursive functions
+
+4. Memory Management
+- CONS allocates in heap
+- Reference counting needed for heap objects
+- Environment frames need reference counting too
+
+These examples show typical compilation patterns. The actual compiler would need to:
+1. Track variable locations
+2. Manage label generation
+3. Detect tail call positions
+4. Handle lexical scoping properly