aboutsummaryrefslogtreecommitdiff
path: root/AGENTS/EXTENDING.md
AgeCommit message (Collapse)Author
2026-10-30docs(types): explain implicit constructors and raw text literalsHEADmain_ov4
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27docs(preprocessor): document switches and library regions_ov4
Add manuals and aliases for all five PP directives, replace the retired #LIB page, and update compiler and shared-editor architecture notes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27docs(memory): describe standard-library allocation and explicit imports_ov4
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21docs(agents): link plain-text references to the split topic files_ov4
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-21docs: document TEMPLATE_ov4
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20docs(strings): document the embedded standard library and STRING values_ov4
Describe -no-std, C_STRING literals, library function semantics and owning string lifetimes in the manuals and contributor guidance. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20docs(agents): align dispatch and object lifetime guidance with code_ov4
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17feat(runtime): write runtime diagnostics to stderr_ov4
Runtime check messages and the unhandled-exception message were printed to stdout by the generated program, so `cpsc x.cps -r >out.txt` captured them. They are now formatted with snprintf and written with write(2). Test expectations and docs are updated accordingly. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-17feat(memory): add tracked MALLOC and FREE builtins_ov4
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-16feat(constants): implement literal constants with lexical scope_ov4
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-16feat(control-flow): implement ordered CASE OF matching_ov4
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-16refactor(types): separate native type registration and imports_ov4
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-16refactor(codegen): split emission by responsibility_ov4
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-16refactor(parser): split expression and control flow parsing_ov4
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-15fix(codegen): restore runtime diagnostics before throwing_ov4
Reuse historical runtime messages and source-line reporting for arithmetic, array, enum, pointer and file checks while preserving anonymous exceptions. Update the manuals and subsystem guidance to describe diagnostic output. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-14docs(toolchain): document LLVM and Clang 23 requirements_ov4
Update build and native-link examples, PATH version-check rules and LLVM API guidance. Record Linux verification and retain the Windows/macOS verification limits. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-14docs(language): document native C types and explicit casts_ov4
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-13docs(language): document exception handling and runtime behavior_ov4
Add the TRY manual for CATCH, ENDTRY, and anonymous THROW. Update runtime error descriptions, language links, and native linking examples; document catch cleanup and embedded runtime integration in the architecture notes. Verify manual generation, rendered output, relative links, and the TRY example. Record Linux LLVM 18 validation and unverified Windows/macOS support. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-13fix: compare strings by content_ov4
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-07-26fix: close type-safety holes found by adversarial review; update docs_ov4
Review findings (all reproduced, then fixed and re-verified): - '^x' leaked as a raw address into any builtin context (s <- ^x printed the variable's bytes as a C string; NOT ^x, '&', and ^x = ^x compiled). Address-of is now rejected everywhere except a pointer-typed target. - A whole-array variable passed the nominal gate as a value of its ELEMENT type (s <- arrayOfSeason stored the raw data pointer; = on it emitted invalid IR). Whole arrays are now rejected as operands and as coercion sources; array parameters are unaffected. - Enum values smuggled into INTEGER through array subscripts and DECLARE bounds (a[Autumn], ARRAY[Spring:Winter]); both now go through emitCoercedExpr like every other INTEGER context. - An array DECLAREd inside an IF/WHILE/REPEAT/FOR body and used after the block was a wild-pointer write (constant bounds) or a verifier dump (runtime bounds). Arrays are now block-scoped: control-flow bodies snapshot and restore the ArrayTable, so escape is a clean compile error. - Duplicate parameter names silently shadowed (BYREF write-back defeated); now a parse error. Trailing comma in parameter lists accepted; now a parse error consistent with every other list. - A variable/array/parameter/function could reuse a TYPE name; reserved. - RETURN with a value inside a PROCEDURE was silently discarded (control did not return); now an error, as is a bare RETURN in a FUNCTION. - INPUT r.f mis-parsed into a three-error cascade; now one clear error. - Assigning to an enum constant now says so instead of 'Unknown variable'. Docs: ARCH/CONVENTIONS/EXTENDING/SUBSYSTEMS/PITFALLS rewritten for the TYPE system (ABI additions, nominal-typing invariants, admission-gate doors, array-parameter ABI, new recipes, new sharp edges); README features/TODO updated — random files are unblocked. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-26feat: implement CIE 9.1 text file handling ↵_ov4
(OPENFILE/READFILE/WRITEFILE/CLOSEFILE/EOF) Front end: OPENFILE/READFILE/WRITEFILE/CLOSEFILE plus reserved mode keywords READ/WRITE/APPEND (RANDOM reserved with a dedicated not-implemented error); statement nodes in new FileAST.h, parsing in new ParserFile.cc; EOF joins the Builtins table as the 12th builtin and CallExprAST now carries a line number for its runtime diagnostics. Runtime: new FileHandler (StringHandler-shaped leaf) lazily synthesizes internal __cps_file_* helper functions and a 16-slot open-file table keyed by filename content (strcmp — STRING '=' is pointer identity). EOF is an fgetc/ungetc peek; READFILE grows a malloc/realloc line buffer and strips a trailing CR; fopen uses text modes so mingw-w64 line translation works. File-free programs get byte-identical IR. All misuse (not open, wrong mode, reopen, fopen failure, read past EOF, table full) dies with the existing "[Fatal] line N:" pattern via a new RuntimeCheck::emitErrorAndExit overload taking runtime printf args. Also fixes a pre-existing ArithmeticHandler hole surfaced by adversarial review: mixed-width integer operands (i1 BOOLEAN / i8 CHAR vs i64) now widen via ZExt instead of emitting invalid IR, and remaining type mismatches get a clean diagnostic; -EOF(f) and -IS_NUM(x) compile. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-26fix: close correctness gaps found by post-refactor adversarial review_ov4
Confirmed by a 17-agent review pass over the refactor diff (12 findings verified against the code and reproduced end-to-end): - marshalCallArgs: BYREF arguments must match the declared parameter type exactly (was: silent bit-reinterpretation, e.g. REAL passed to BYREF INTEGER printed garbage with exit 0); whole-array arguments are rejected (was: callee assignment smashed the array data pointer -> runtime SIGSEGV) - Null guards for CHR/LCASE/UCASE/IS_NUM/NUM_TO_STR/STR_TO_NUM/ASC argument emission (was: compiler SIGSEGV on e.g. CHR(undeclared)), matching the guards MID/RIGHT/LEFT already had - ParseReturnStmt: propagate expression-parse failure (was: diagnostic printed but exit 0) and recognize bare RETURN before ENDWHILE/UNTIL/NEXT (was: bogus diagnostic on legal early return) - emitPrototype rejects FUNCTION/PROCEDURE names that collide with runtime/libc symbols (was: FUNCTION strlen silently hijacked the string runtime; arity mismatch crashed createArgumentAllocas) or with builtins (was: silently shadowed); conflicting redefinitions keep the first signature - FOR STEP is evaluated exactly once, before the loop (was: once per iteration; the runtime-direction refactor had moved it to N+1) - RETURN values are coerced to the declared return type via the signature table (RETURN n in a RETURNS REAL function now compiles) - '&' coerces its operands to STRING (CHAR/number operands work); OUTPUT of a PROCEDURE call reports a clean error AGENTS docs updated to match. All positive samples remain byte-identical to the pre-refactor baseline. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-26refactor: extract ParseBlock/ParseExprList, resync-based error recovery_ov4
Seven copy-pasted statement-block loops collapse into ParseBlock(terminators); five comma-separated expression-list loops collapse into ParseExprList(close, allowEmpty), which also fixes "arr[1 2] <- x" being silently accepted as arr[1,2] on the statement path. Error recovery now lives in one place: syncToStatementStart skips to the next statement-start/block-end token, so a bad statement no longer swallows the first token of the following good one. Drop the dead -1000/-1001 token check in ParsePrototypeArgs. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-26refactor: single builtin registry, retire keyword route for builtins_ov4
All 11 builtins now live in one static {Name, Arity, ReturnTypeName} table in CodeGen.cc: emitExpr checks arity against it (uniform "Error: X expects N args" diagnostics) and getExprTypeInfo reads return types from it, removing the duplicated hard-coded table. LENGTH/MID/RIGHT/LEFT/LCASE/UCASE lose their lexer tokens and ParseStringBuiltin; they parse as ordinary identifier calls exactly like ASC/CHR/IS_NUM/NUM_TO_STR/STR_TO_NUM already did. Behavior note: these six names are no longer reserved words. AGENTS docs updated for the new builtin story and the batch-1 error contract (exit codes, verifyModule, fixed descending FOR). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-26docs: add AGENTS/ architecture docs for AI-assisted development_ov4
ARCH.md holds the overview (pipeline, build/run, layout); details are split into CONVENTIONS.md, EXTENDING.md, SUBSYSTEMS.md and PITFALLS.md. All claims were verified against the source, most also empirically by compiling and running test programs. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>