Skip to content

README.md

Latest commit

 

History

History
74 lines (59 loc) · 4.28 KB

README.md

File metadata and controls

74 lines (59 loc) · 4.28 KB
Raw

EigenScript documentation map

Start here. Each document has a stable filename and stable headings — link to sections freely.

Try it in your browser: playground/ — interpreter-only WASM build, no install required.

Learn the language

document what it answers
SPEC.md The canonical spec. Every construct with a runnable example and its exact output — all examples are executed by the test suite, so the spec cannot drift from the implementation.
SYNTAX.md Tutorial-style guide to the same material, in prose.
COMPARISON.md EigenScript next to Python / JavaScript / Rust / Lisp, with a porting checklist and before/after transformations (also executed by the suite).
GRAMMAR.md The formal grammar.
LANGUAGE_CONTRACT.md Edge-case promises: exactly what is guaranteed at the boundaries (argument spreading, coercion, subprocess I/O, ...).

Reference

document what it answers
BUILTINS.md Every built-in function: signature, behavior, errors.
STDLIB.md The 73 standard-library modules under lib/.
OBSERVER.md Observer semantics in depth: entropy, dH, predicates, unobserved.
TRACE.md Temporal interrogatives, the trace tape, deterministic replay, and replay's nondeterminism boundary.
DEBUGGING.md The failure→replay→interrogate loop and the --step tape-stepper (step back, trajectories, breakpoints).
DIAGNOSTICS.md Error messages, the linter, and the formatter.

Internals

document what it answers
ARCHITECTURE.md Pipeline overview: lexer → parser → bytecode compiler → stack VM → copy-and-patch JIT.
EMBEDDING.md C embedding API (src/eigs_embed.h): lifecycle, eval, error retrieval, value handles, FFI.
JIT_STAGE5_INLINE_IC.md The JIT's inline fast paths and caches: design + as-built record.
CLOSURE_CYCLE_GC.md The closure-cycle collector: honest env refcounts, the registry/mark-sweep design as built, maintainer invariants, and what still leaks.
TEST_COVERAGE_ANALYSIS.md The coverage program: findings → fixes → residual gaps, with measured numbers.
GAP_ANALYSIS.md Downstream feature-gap tracking.
PACKAGE_SPEC.md The --pkg tool as implemented: add/install/update/verify/list, eigs.json manifest, SHA-pinned lockfile, vendored eigs_modules/.
PACKAGE_DESIGN.md Partially implemented — shipped behavior lives in PACKAGE_SPEC.md; the design intent and open questions are here.

Editor support

editors/vscode/ (TextMate grammar + language config) and editors/vim/ (syntax + ftdetect); make lsp builds the language server (src/eigenlsp — diagnostics, completion, hover, definition, references over stdio).

Examples

  • examples/ — 50+ runnable programs, smoke-tested by the suite, from hello.eigs to a Conway's-Life and STEM simulations.
  • examples/errors/ — programs that fail on purpose, each declaring its expected error message in an # expect-error: header (verified by the suite). Read these to learn what mistakes look like.
  • tests/ — the language's executable semantics: 2,500+ checks, each test file readable as a statement of intended behavior.

Conventions in these docs

  • An untagged ```eigenscript fence is a runnable whole program. It must be followed by an ```output block; the program is executed and its output is checked against that block.
  • A snippet that is not a whole program uses ```eigenscript fragment and declares every free name as name=value on that same opening line, for example ```eigenscript fragment items=[1,2,3].
  • A deliberately exempt example uses ```eigenscript nocheck <reason>. The reason is required on the opening line, so an example is never skipped silently.

See tests/test_doc_examples.py for the full fence grammar and validation rules.