Architecture
Zy is a tree-walk interpreter written in Go. Its module is zy and declares Go 1.22. The local interpreter uses the standard library; HTTP serve mode also uses the official MongoDB Go driver.
.zy source -> Lexer -> Tokens -> Parser -> AST -> Interpreter -> Output or ZyError| File | Responsibility |
|---|---|
main.go | Process entry point, interrupt handling, release version and exit status |
internal/cli/cli.go | Command routing, script pipeline, CLI options and help |
internal/cli/format.go | CLI formatting modes and prepared file replacement |
internal/cli/diagnostics.go | Versioned JSON check output |
core/lexer.go | Recognize literals, keywords, operators, source positions |
core/ast.go | Define syntax-tree nodes |
core/parser.go | Recursive-descent statement/expression parsing |
core/interpreter.go | Host options, runtime lifecycle, statement/control-flow evaluation |
core/runtime_values.go | Values, ordered maps, display, kinds and cycle handling |
core/environment.go | Lexical environments and assignment |
core/evaluate.go | Expression evaluation, operators, calls and closures |
core/members.go | Collection/network/agent member dispatch and indexing |
core/builtins.go | Global built-in functions |
core/numeric.go | Checked integers, finite floats, mixed comparison |
core/bounded.go | Counted IPv4 splitting and overflow-safe ranges |
core/methods.go | Method arity guards |
core/stdlib.go | Local I/O, JSON, paths, environment, network allocation |
core/modules.go | Module declarations, bounded dependency graph, isolated scopes and cache |
core/check.go | Non-executing frontend checks with canonical in-memory source overlays |
internal/lsp/ | Stdio protocol, snapshots, UTF-16 diagnostics, formatting, lexical symbols and editor requests |
internal/server/ | HTTP hosting, MongoDB adapter, configuration, middleware, and graceful shutdown |
core/host.go | Host-provided namespaces, handler invocation, and bounded JSON conversion |
core/prepared.go | Immutable parsed entry/import snapshots and portable source digests |
core/format.go / core/source_layout.go | Lossless layout, indentation, token and structural preservation |
core/errors.go | Represent and render located errors |
core/diagnostics.go | Stable diagnostic categories and interchange representation |
core/interpreter_test.go | Execution and diagnostic tests |
Functions capture environments for closures. Member access dispatches collection and networking methods. Built-ins and library namespaces are registered in the global environment. Options inject I/O, script arguments, and cancellation context. Agent methods return simulations and do not invoke providers.
Before evaluation, the module loader reads and parses the complete local dependency graph. CheckProgram stops after that validation. Execution uses the loaded snapshots and caches module instances per run. Each module has its own environment; functions capture both that environment and their source origin. The interpreter shares I/O, arguments, and cancellation across modules. See the module decision.
HTTP hosting prepares the graph once and clones only module runtime state for each request. Host libraries supply MongoDB, sessions, roles, jobs, cache, logging, and metrics; persistent coordination lives in MongoDB. See backend services.
Repository conventions
docs/: user documentation and proposed design;archive/preserves drafts.examples/: runnable programs;tutorials/holds teaching snippets.assets/branding/: temporary identity and original reference asset.bin/: ignored local outputs, including preserved legacy executables..github/workflows/: automation.editors/vscode/: syntax extension, opt-in language client, tokenizer and client tests.tools/: Python archive builder, integrity/smoke checks, and packaging tests.dist/: ignored local archive outputs; no published release is implied.
The root retains main.go, preserving go run . and go build .. CLI implementation and its tests live together in internal/cli/; the root entry point only wires process I/O, cancellation, and the release version. CLI documentation tests run against repository-relative examples.
Add syntax only when a function/library API cannot express the use case clearly. Test boundaries before splitting the large interpreter by responsibility. Decide whether zy/core is a supported embedding API before moving it into internal/.