Metadata-Version: 2.1
Name: OsakaProgrammingLanguage
Version: 0.1.0
Summary: Osaka Programming Language CLI (interpreter + VM + equivalence lock)
Author: GeorgeBushfan - James Alexander
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE

# OsakaProgrammingLanguage (Osaka Lang)

Osaka Lang is a custom programming language implemented in Python, with:

- an **AST interpreter**
- a **bytecode compiler + VM**
- an **Equivalence Lock** to compare interpreter and VM behavior

You can run it from source (`python3 saka.py`) or as an installed CLI (`osaka`).

---

## Quick Start

```bash
python3 saka.py examples/hello.saka
python3 saka.py --help
```

### Main CLI flags

- `--no-lock` — disable equivalence lock
- `--vm-only` — execute only VM path
- `--interpreter-only` — execute only interpreter path
- `--lock-strict` — fail on lock mismatches
- `--warnings-as-errors` — treat warnings as errors in equivalence checks
- `--debug` — enable debug traces
- `--show-lexer-tokens` — print lexer token stream
- `--repl` — launch interactive Osaka REPL

Example:

```bash
python3 saka.py --show-lexer-tokens tests/equivalence/06_sataandagi.saka
```

Default mode now prints `Say(...)` program output directly. If a program emits no output, Osaka prints:

```text
Tip: Use --debug for traces
```

---

## Install CLI (`osaka`)

Install from local repo:

```bash
python3 -m pip install --upgrade "/Users/example/Desktop/Osaka Lang"
```

Or build a wheel:

```bash
cd "/Users/example/Desktop/Osaka Lang"
python3 -m pip wheel . --no-deps -w dist
python3 -m pip install --upgrade "dist/osakaprogramminglanguage-0.1.0-py3-none-any.whl"
```

Then:

```bash
osaka --help
osaka your_program.saka
osaka --repl
```

---

## Language Guide

### 1) Declarations and kinds

Osaka Lang tracks value kinds:

- `grainsoftruth` → `grain` (uncertain)
- `truthaboutgrain` → `truth` (authoritative)

```saka
grainsoftruth g = 11;
truthaboutgrain t = Americaya(g);
Say(t);
```

### 2) Control flow

`if` and `while` require **truthaboutgrain** conditions at runtime.

```saka
truthaboutgrain ok = 1;
if (ok == 1) {
    Say("ready");
}
```

If a condition evaluates to `grain`, runtime raises an error (for example: `while-condition must be truthaboutgrain`).

### 3) Functions

Both `function` and `func` are accepted.

```saka
func add(a, b) {
    return a + b;
}

truthaboutgrain x = add(2, 3);
Say(x);
```

Current interpreter rule: function parameters are bound as `grain` inside function scope unless promoted.

### 4) Collections

- Lists: `[1, 2, 3]`
- Maps: `{"name": "SATA", "level": 6}`
- Indexing: `arr[i]`, `m["key"]`
- Index assignment: `arr[i] = value;`

```saka
truthaboutgrain nums = [1, 2];
push(nums, 3);
Say(nums);

truthaboutgrain profile = {"name": "SATA"};
Say(profile["name"]);
```

### 5) Mutation & governance built-ins

- `Ah(x)` — acknowledges variable for mutation
- `youknowsealsright(x)` — marks variable as assumed (suppresses mutation warning path)
- `Ivebeengot(x)` — legacy protection (blocks later mutation)
- `Hecho(x)` — freezes a variable when allowed

Typical behavior:

- mutating an initialized variable without `Ah`/assumption can warn
- mutating `Hecho`/`Ivebeengot` variables is blocked
- `Hecho` on `grainsoftruth` emits advisory info in current runtime behavior

### 6) Runtime/system built-ins

- `Getittogether();` — stabilizes unresolved grain state
- `SataAndagi()` — returns runtime info map as truth
- `Americaya(x)` — promotes value to truth (returns promoted value)

```saka
grainsoftruth raw = 42;
Getittogether();
truthaboutgrain stable = Americaya(raw);
Say(stable);
```

### 7) Context progression statements

Parser accepts these as statement-style declarations:

```saka
Escalator reviewLevel2;
Elevator policyLevel;
```

> Note: current parser rules treat `Getittogether` as a callable form with parentheses,
> while `Escalator`/`Elevator` are declaration-style statements.

---

## Standard Library (currently implemented)

- `Say(x)`
- `len(x)`
- `push(list, value)`
- `pop(list)`
- `contains(map, key)`
- `keys(map)`
- `values(map)`
- `slice(list_or_string, start, end)`
- `SataAndagi()`
- `Americaya(x)`

---

## Testing

Run a program through the main CLI:

```bash
python3 saka.py examples/hello.saka
```

Run direct interpreter-vs-VM equivalence harness:

```bash
python3 equiv_lock.py tests/equivalence/06_sataandagi.saka
```

Full test runner (project utility):

```bash
python3 run_tests.py
```

Single equivalence test:

```bash
python3 run_tests.py --filter 06_sataandagi.saka
```

Verifier unit tests:

```bash
python3 -m unittest tests/test_verifier.py
```

---

## Implementation Map (contributors)

- `lexer.py` — tokenization / keywords
- `parser.py` — AST construction
- `ast_nodes.py` — AST node types
- `interpreter.py` — interpreter semantics
- `compiler.py`, `bytecode.py`, `vm.py` — compile + VM execution
- `verifier.py` — bytecode / signature checks
- `equiv_lock.py`, `equiv_test.py` — interpreter vs VM comparison
- `arg_parser.py`, `saka.py` — CLI

When changing language semantics:

1. Update interpreter behavior.
2. Mirror behavior in compiler/VM.
3. Update verifier rules if builtin signatures or op behavior changed.
4. Add/adjust tests (especially `tests/equivalence/`).
5. Re-check equivalence output before shipping.
