Metadata-Version: 2.1
Name: OsakaProgrammingLanguage
Version: 0.1.1
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 runtime written in Python with:

- an **AST interpreter**
- a **bytecode compiler + VM**
- an **equivalence lock** for interpreter/VM behavior checks

The package exposes the CLI command:

```bash
osaka
```

---

## Installation

### From PyPI (recommended)

```bash
python3 -m pip install --upgrade OsakaProgrammingLanguage
```

Verify:

```bash
osaka --help
```

### From TestPyPI

```bash
python3 -m pip install --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple \
  OsakaProgrammingLanguage
```

### From local source (development)

```bash
python3 -m pip install --upgrade "/absolute/path/to/Osaka Lang"
```

---

## Quick Start

Run a file:

```bash
osaka examples/hello.saka
```

Run with debug:

```bash
osaka --debug examples/hello.saka
```

Start REPL:

```bash
osaka --repl
```

If a program emits no output, Osaka prints:

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

---

## CLI Reference

- `--no-lock` — disable equivalence lock
- `--vm-only` — run VM path only
- `--interpreter-only` — run interpreter path only
- `--lock-strict` — fail on lock mismatch
- `--warnings-as-errors` — treat warnings as errors in checks
- `--debug` — enable parse and execution trace verbosity
- `--show-lexer-tokens` — print lexer tokens
- `--repl` — interactive interpreter REPL

---

## Language Semantics (Technical)

### Kind system

Every runtime value has a kind:

- `truth` (authoritative)
- `grain` (uncertain)

Declarations:

- `truthaboutgrain x = ...;`
- `grainsoftruth x = ...;`

For arithmetic/concat/comparison flows, results are generally `truth` only when both operands are `truth`; otherwise they degrade to `grain`.

### Control-flow constraints

`if` and `while` conditions must evaluate to `truth` at runtime. Grain conditions raise runtime errors (for example `while-condition must be truthaboutgrain`).

### Mutation governance

- `Ah(x)` — acknowledge variable before mutation
- `youknowsealsright(x)` — assumption marker for mutation pathway
- `Ivebeengot(x)` — legacy lockout (blocks writes)
- `Hecho(x)` — freeze finalized variable

Current behavior includes warnings for mutation without acknowledgement and hard blocks for legacy/frozen variables.

### Functions

Both syntaxes are accepted:

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

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

### Collections

- Lists: `[1, 2, 3]`
- Maps: `{"k": 1}`
- Index read/write: `arr[i]`, `arr[i] = v`, `m["k"]`

Built-ins:

- `len`, `keys`, `values`, `contains`
- `push`, `pop`, `slice`

### Runtime/meta built-ins

- `SataAndagi()` — runtime bootstrap/info map (`truth`)
- `Americaya(x)` — promote returned value to `truth`
- `Getittogether()` — stabilize unresolved grain state

Parser note: `Getittogether` is callable (`Getittogether()`), while `Escalator` / `Elevator` are declaration-style statements.

---

## Architecture

### Front-end

1. `lexer.py` tokenizes source.
2. `parser.py` builds AST (`ast_nodes.py`).

### Interpreter path

- `interpreter.py` executes AST against `runtime.py` state.
- Tracks values, kinds, warnings/errors, traces, and buffered stdout/stderr.

### Compiler + VM path

1. `compiler.py` lowers AST to bytecode (`bytecode.py`).
2. `vm.py` executes bytecode.
3. `verifier.py` checks stack effects, call arity, and block validity.

### Equivalence path

- `equiv_test.py` runs both engines.
- `equiv_lock.py` compares traces and output for drift detection.

---

## Testing and Validation

```bash
python3 run_tests.py
python3 run_tests.py --filter 06_sataandagi.saka
python3 -m unittest tests/test_verifier.py
python3 equiv_lock.py tests/equivalence/06_sataandagi.saka
```

---

## Contributor Map

- `lexer.py` — lexer rules
- `parser.py` — parser + AST construction
- `ast_nodes.py` — AST node definitions
- `interpreter.py` — interpreter semantics
- `compiler.py`, `bytecode.py`, `vm.py` — compile + VM runtime
- `verifier.py` — verifier rules
- `equiv_lock.py`, `equiv_test.py` — equivalence tooling
- `arg_parser.py`, `saka.py` — CLI wiring

When changing language semantics:

1. Update interpreter behavior.
2. Mirror behavior in compiler/VM.
3. Update verifier rules if signatures/ops changed.
4. Update tests, especially in `tests/equivalence/`.
5. Re-run equivalence and verifier checks.

---

## Packaging and Release

Metadata lives in `pyproject.toml`:

- package name: `OsakaProgrammingLanguage`
- console script: `osaka = saka:main`

Typical release flow:

```bash
rm -rf build dist *.egg-info
python3 -m pip install --upgrade build twine
python3 -m build
python3 -m twine check dist/*
python3 -m twine upload dist/*
```

License: MIT (`LICENSE`).
