# BASIC Implementation Status - 2026-04-03

> **Note**: This document tracks the PB/BASIC frontend feature set. All features listed are implemented in native C. No Python translators are used. For the current test lane status and session context, see `AGENTS.md`.

## 2026-06-11 Update: Release V4

### Test lane status

```text
Assembly (-S):  211/211 passed
Link+Run (PB):  30/30 passed
Link+Run (B64): 13/13 passed
C Compile (-S): 63/63 passed
Link+Run (C):   1/1 passed
Total:          318/318 (0 expected fails, 0 regressions)
```

### Newly supported in V4

- **String concat fix**: `a & b` in user-defined functions with BYVAL string params now works correctly. Root cause was incorrect relocation offsets in `bestof_str_concat` runtime bytecode.
- **Debug hooks**: `#DEBUG HOOKS ON/OFF`, `#HOOK var sub`, `#ENDHOOK var` directives for variable lifecycle tracing.
- **New types parsed**: `VARIANT`, `OBJECT`, `GUID`, `STRINGZ`, `WSTRINGZ`. Runtime helpers are stubbed/initial; full semantics targeted for V5.
- **CURRENCY float comparison**: runtime and const-fold paths verified.

### V5 blockers / next work

See `docs/V5_TODO.md` for the prioritized V5 release plan.


## 2026-05-15 Update: Feature Wave Complete

### Newly Implemented Features

**Math builtins added:**
- `INT` → `bestof_int()` - floor toward negative infinity
- `FIX` → `bestof_fix()` - truncate toward zero
- `ROUND` → `bestof_round(value, digits)` - round to N decimal places
- `MIN` → `bestof_min(a, b)` - minimum of two values
- `MAX` → `bestof_max(a, b)` - maximum of two values

**String conversion builtins added:**
- `HEX$` → `bestof_hex_s(value, digits)` - hexadecimal string
- `OCT$` → `bestof_oct_s(value)` - octal string
- `BIN$` → `bestof_bin_s(value)` - binary string
- `RND` → `bestof_rnd(n)` - random number with LCG

**Statement handlers added:**
- `INCR var [, inc]` - increment variable
- `DECR var [, dec]` - decrement variable
- `SWAP a, b` - exchange two variables
- `ITERATE FOR|DO|WHILE` - loop continue (companion to EXIT)
- `REPLACE find WITH repl IN var` - string search/replace (fixes hard failure)
- `SELECT CASE ... CASE ... CASE ELSE ... END SELECT` - multi-way branch (largest feature gap)

**Multi-arg builtin:**
- `CHR$(c1, c2, ...)` - multi-character string generation

**System builtins (stub):**
- `DATE$` → `bestof_date_s()` - current date string
- `TIME$` → `bestof_time_s()` - current time string
- `ENVIRON$(name)` → `bestof_environ_s(name)` - environment variable
- `COMMAND$` → `bestof_command_s()` - command line
- `INKEY$` → `bestof_inkey_s()` - non-blocking key read
- `WAITKEY$` → `bestof_waitkey_s()` - blocking key read
- `FORMAT$(value, mask)` → `bestof_format_s(value, mask)` - string formatting

**PILOT improvements:**
- `S:` → `bestof_pilot_beep()` - bell sound
- `U:` → goto label (subroutine call)
- `P:` → label definition
- `D:` → array declaration

**Bugfixes:**
- SIN/COS/TAN/EXP/LOG/SQR now use inline Taylor series (no libm dependency)
- OR/AND operators now use logical `||`/`&&` (short-circuit evaluation)
- SELECT CASE counter uses monotonic IDs (no name collisions)
- MID$ mapping verified correct

**Test file:** `examples/basic/new_features_test.pb` - exercises all new features

## Summary

The current BASIC path is usable for a small translated subset. String command coverage has been significantly expanded in the latest polish wave.

What is real today:

- The shipped PB translator in `frontends/pb_hybrid.py` successfully translates all six shipped BASIC examples.
- String builtins now covered: `LEFT$`, `RIGHT$`, `MID$`, `UCASE$`, `LCASE$`, `TRIM$`, `LTRIM$`, `RTRIM$`, `STR$`, `CHR$`, `SPACE$`, `STRING$`, `INSTR`, `VAL`, `ASC`, `LEN`.
- String operators covered: `&` (concat), `+` (concat when string involved), `=` / `<>` / `<` / `>` / `<=` / `>=` (comparison via `bestof_strcmp`).
- Math builtins covered: `ABS`, `SGN`, `SIN`, `COS`, `TAN`, `ATN`, `EXP`, `LOG`, `SQR`.
- The generated C for the shipped examples compiles successfully with MSVC in this environment.
- Two translated examples were linked and run successfully:
  - `main_only` returned `0`
  - `string_ops` returned `0`

What is not real today:

- The shipped `bestofcc.py` PB route still depends on `clang` plus `lld-link`.
- In this shell, `clang` is not available on `PATH`, so `bestofcc.py` cannot currently produce PB executables here without an explicit tool path.
- Large parts of PBWin command coverage are still missing or only emitted as placeholder C identifiers.

## Verified Current Coverage

These example sources translated successfully through `PBHybridTranslator`:

- `examples/basic/basic_add.bas`
- `examples/basic/factorial.bas`
- `examples/basic/float_ops.pb`
- `examples/basic/main_only.bas`
- `examples/basic/pointer_struct_array.pb`
- `examples/basic/string_ops.pb`

These generated C files compiled successfully with MSVC:

- `out/basic_probe/examples_c/basic_add.c`
- `out/basic_probe/examples_c/factorial.c`
- `out/basic_probe/examples_c/float_ops.c`
- `out/basic_probe/examples_c/main_only.c`
- `out/basic_probe/examples_c/pointer_struct_array.c`
- `out/basic_probe/examples_c/string_ops.c`

These translated executables were built and executed successfully with MSVC:

- `out/basic_probe/main_only.exe`
- `out/basic_probe/string_ops.exe`

## Verified Gaps

### Hard translator failures

These fail in `frontends/pb_hybrid.py` today:

- `REPLACE "a" WITH "z" IN a`
- `OPEN "x.txt" FOR OUTPUT AS #1`
- `MODULE Test ... END MODULE`

### False-positive translation success

These currently "translate" but are not truly implemented semantically:

- `WSTRING`
- `VARIANT`

The current translator emits unresolved or weak C forms such as:

- `WSTRING w = 0;`
- `VARIANT v = 0;`

That means the parser accepts them, but the runtime/type system contract is not actually complete.

## Operational Blockers

1. Product PB compilation still depends on `clang` + `lld-link`.
2. The support runtime in `support/bestof_support_inline.h` is growing but still too small for full PBWin command coverage.
3. `frontends/pb_hybrid.py` mixes parser, sema-ish coercion, and runtime naming in one file, so command growth causes hotspot conflicts.
4. PBWin help coverage is far larger than current implementation.

## Micro Regression Pack

COFF object artifacts from testing are now organized in `regression/micro/`:

| Category | Count | Purpose |
|----------|-------|---------|
| pass/ | 7 objects | Verified linkable and executable |
| fail/ | 2 objects | Known failures (MID$, SIN builtins) |
| notes/ | 2 files | Diagnostic analysis per failure |

See `regression/micro/README.md` and `regression/micro/MANIFEST.md`.

## Immediate Conclusion

The honest current statement is:

- "BASIC can compile a small shipped subset."
- "String and math command coverage is now solid for the freestanding runtime."
- "BASIC command coverage is still far from production target."
- "The fastest path forward is a command-family wave split into strings (done), math (done), I/O, types, modules, runtime ABI, and acceptance/coverage."
