# Namako Programming Language

Namako is a Python-like programming language that compiles to pali assembly for
the ilo virtual computer. It features Python-style syntax with indentation-based
blocks, integer-only arithmetic, and direct compilation to a dual-stack
processor architecture.

## Language Characteristics

- **Syntax Style**: Python-like with significant whitespace/indentation
- **Compilation**: Single-pass compiler to pali assembly
- **Target**: ilo virtual machine (dual-stack processor)
- **Data Types**: 32-bit signed integers and length-prefixed strings/arrays
- **Paradigm**: Procedural with functions

## Indentation

Like Python, Namako uses meaningful indentation to distinguish code blocks.

## Function Definition

```python
def name(parameters):
    ... code ...
```

## Comments

```python
# comments start with # and go to end of line
```

## Variables & Assignment

### Numbers

32-bit signed integers (-2,147,483,647 to 2,147,483,646):

```python
a = 10
b = 20
c = a + b
d = (c * 2) - a
```

### Strings

Length-prefixed strings (first cell contains length):

```python
e = "Hello, World!"
```

### Arrays

Length-prefixed arrays (index 0 contains length):

```python
# Simple assignment at creation
a = [10, 20, 30]

# Empty array, 5 elements, initialized to zero
a = [*5]

# Access and updates
a = [10, 20, 30]
b = a[2]      # Access element at index 2
a[2] = b * 33 # Update element at index 2
```

## Operators

### Arithmetic Operations
- `+` Addition
- `-` Subtraction
- `*` Multiplication
- `/` Division (integer division)
- `%` Modulo

### Comparison Operations
- `==` Equal
- `!=` Not equal
- `<` Less than
- `>` Greater than
- `<=` Less than or equal
- `>=` Greater than or equal

### Bitwise Operations
- `&` Bitwise AND
- `|` Bitwise OR
- `^` Bitwise XOR
- `>>` Right shift (logical)
- `<<` Left shift

### Expression Evaluation

**Left-to-Right Evaluation**: All binary operations are evaluated strictly from
left to right. Use parentheses `()` to control evaluation order.

```python
result = a + b * c        # Left-to-right: (a + b) * c
result = (a + b) * c      # Parentheses explicit
result = a + (b * c)      # Precedence control with parentheses
```

## Conditionals

```python
if a > b:
   ... true ...
else:
   ... false ...
```

## Loops

```python
i = 0
while i < 10:
    i = i + 1
```


## Standard Library

Include standard library modules using the `include` directive:

```python
include std/io.n
```

### I/O Functions (std/io.n)

```python
# Character output
putc(65)        # Output character 'A'

# String output
puts("Hello")   # Output entire string

# Newline and spacing
nl()            # Output newline character
sp()            # Output space character
tab()           # Output tab character

# Number output
print_digit(5)  # Output single digit (0-9)
putn(123)       # Output entire number (handles negative numbers)

# Program termination
exit()          # End program execution
```

## Include System

Namako supports modular programming with an include system:

```python
# Include other namako files
include utils.n      # Relative to current file
include std/io.n     # Standard library

# Use functions from included files
result = utility_function(10, 20)
puts("Result calculated")
```

### Include Features
- **Relative Paths**: Includes resolved relative to current file
- **Search Paths**: Uses NAMAKO_INCLUDE environment variable
- **Circular Protection**: Prevents circular includes automatically
- **Recursive Processing**: Included files can include other files

## Inline Assembly

Direct access to ilo virtual machine instructions:

```python
def square(n):
    asm:
        i lifedumu
        r p_square.n
```

## Variable Scoping

### Global Variables
- Declared at module level
- Accessible from anywhere in the program

```python
global_var = 10
```

### Local Variables
- Declared within functions
- Only accessible within their function scope

```python
def example():
    local_var = 20  # Local to this function
```

### Function Parameters
- Passed by value to functions
- Accessible within the function scope

```python
def add_numbers(a, b):  # a and b are parameters
    return a + b
```

## Memory Model

### Memory Layout
- **Code Section** (address 0+): Program instructions
- **Data Section** (address 32768+): Variables and literals

### Variable Storage
- Global variables: `g_varname`
- Local variables: `l_functionname.varname`
- Function parameters: `p_functionname.paramname`
- String literals: `s_N` (auto-numbered)
- Array literals: `a_N` (auto-numbered)

## Target Architecture: ilo Virtual Machine

- **Type**: Dual-stack processor (data stack + address stack)
- **Memory**: 65,536 cells (32-bit signed integers)
- **Stacks**: 32-element data stack, 256-element address stack
- **Instruction Set**: 30 instructions with bundling support

## Example Programs

### Hello World
```python
include std/io.n

puts("Hello, World!")
nl()
exit()
```

### Function Example
```python
include std/io.n

def add(a, b):
    return a + b

def main():
    result = add(5, 3)
    putn(result)
    nl()

x = 10
y = 20
sum = add(x, y)
putn(sum)
exit()
```

### Array Example
```python
include std/io.n

# Create array with initial values
numbers = [10, 20, 30]

# Access array length and elements
length = numbers[0]  # 3
first = numbers[1]   # 10
second = numbers[2]  # 20

# Modify array elements
numbers[2] = 99

# Create empty array and populate
data = [*5]  # Array of 5 zeros
data[1] = 42
data[2] = 73

putn(data[1])  # Output: 42
exit()
```

### Loop Example
```python
include std/io.n

def count_down(n):
    while n > 0:
        putn(n)
        sp()
        n = n - 1
    nl()

count_down(5)
exit()
```

## Building and Running

Use the provided shell script to compile and run namako programs:

```bash
# Compile and run a namako program
./namako.sh program.n

# The script:
# 1. Compiles program.n to program.pali
# 2. Assembles program.pali to ilo.rom
# 3. Runs ilo.rom with ./ilo
```

## Testing

Run the comprehensive test suite:

```bash
# Run all tests
./tests/run_tests.sh

# Run a single test
./tests/run_single_test.sh tests/basic/01_variables.n
```

Test categories:
- **Basic Tests** (`tests/basic/`): Core language features
- **Integration Tests** (`tests/integration/`): Complex programs
- **Edge Cases** (`tests/edge_cases/`): Boundary conditions

## Language Limitations

1. **No Floating Point**: Only integer arithmetic supported
2. **Static Memory**: No dynamic allocation
3. **Simple Data Types**: Integers, strings, and basic arrays only
4. **No Break/Continue**: Loop control statements not implemented
5. **Integer Division**: All division operations are integer division