*

1 files changed, 173 insertions, 0 deletions

diff --git a/awk/scheme/scheme/README.md b/awk/scheme/scheme/README.md
new file mode 100644
index 0000000..a5cdc80
--- /dev/null
+++ b/awk/scheme/scheme/README.md
@@ -0,0 +1,173 @@
+# Awk-Scheme
+
+## Overview
+This is a minimal Scheme implementation supporting basic arithmetic operations, list manipulation, and comparisons. All values are displayed with type tags (e.g., "N:42" for numbers).
+
+## Data Types
+
+### Numbers
+- Represented as: `N:value`
+- Examples: `42`, `-5`, `123`
+```scheme
+scheme> 42
+N:42
+```
+
+### Booleans
+- Represented as: `B:value` (1 for true, 0 for false)
+- Generated by comparison operations
+```scheme
+scheme> (< 1 2)
+B:1
+```
+
+### Nil (Empty List)
+- Represented as: `NIL:`
+- Used for list termination
+```scheme
+scheme> nil
+NIL:
+```
+
+### Pairs
+- Represented as: `P:index`
+- Created using cons
+- Stored in heap with car and cdr values
+
+## Supported Operations
+
+### Arithmetic Operations
+1. Addition: `(+ x y ...)`
+   ```scheme
+   scheme> (+ 1 2)
+   N:3
+   scheme> (+ 1 2 3)
+   N:6
+   ```
+
+2. Subtraction: `(- x y ...)`
+   ```scheme
+   scheme> (- 5 3)
+   N:2
+   scheme> (- 10 2 3)  ; 10 - 2 - 3
+   N:5
+   ```
+
+3. Multiplication: `(* x y ...)`
+   ```scheme
+   scheme> (* 3 4)
+   N:12
+   scheme> (* 2 3 4)
+   N:24
+   ```
+
+4. Division: `(/ x y)`
+   ```scheme
+   scheme> (/ 10 2)
+   N:5
+   ```
+
+### Comparison Operations
+1. Less Than: `(< x y)`
+   ```scheme
+   scheme> (< 1 2)
+   B:1
+   scheme> (< 2 1)
+   B:0
+   ```
+
+2. Equality: `(= x y)`
+   ```scheme
+   scheme> (= 42 42)
+   B:1
+   ```
+
+### List Operations
+1. Cons: `(cons x y)`
+   - Creates a pair from two values
+   ```scheme
+   scheme> (cons 1 2)
+   P:1
+   scheme> (cons 1 nil)
+   P:1
+   ```
+
+2. Car: `(car pair)`
+   - Gets the first element of a pair
+   ```scheme
+   scheme> (car (cons 1 2))
+   N:1
+   ```
+
+3. Cdr: `(cdr pair)`
+   - Gets the second element of a pair
+   ```scheme
+   scheme> (cdr (cons 1 2))
+   N:2
+   ```
+
+### Building Lists
+Lists can be built using nested cons operations with nil as the terminator:
+```scheme
+scheme> (cons 1 (cons 2 (cons 3 nil)))
+P:1  ; This represents the list (1 2 3)
+```
+
+## Expression Structure
+- All expressions must be properly parenthesized
+- Operators come first in a form (prefix notation)
+- Multiple expressions can be evaluated in sequence
+
+## REPL Features
+- Multi-line input supported (continues with "..." prompt until parentheses balance)
+- Ctrl+D to exit
+- Comments start with semicolon (;)
+
+## Error Handling
+The system will report errors for:
+- Stack underflow
+- Type mismatches
+- Unknown operations
+- Division by zero
+- Invalid list operations
+- Malformed expressions
+
+## Examples
+Here are some more complex examples:
+
+1. Nested arithmetic:
+```scheme
+scheme> (+ (* 3 4) (- 10 5))
+N:17
+```
+
+2. List construction and manipulation:
+```scheme
+scheme> (cons (+ 1 2) (cons (* 3 4) nil))
+P:1  ; Represents (3 12)
+```
+
+3. Combined operations:
+```scheme
+scheme> (car (cons (* 2 3) (+ 4 5)))
+N:6
+```
+
+## Limitations
+Current implementation does not support:
+- Variables or definition
+- Functions or lambda expressions
+- Control structures (if, cond)
+- Quote or quasiquote
+- String data type
+- Input/output operations
+- Standard library functions
+
+## Future Enhancements
+Possible additions could include:
+1. Let expressions for local bindings
+2. Function definitions
+3. Conditional expressions
+4. More numeric operations
+5. String support
+6. Additional list operations
\ No newline at end of file