How michniks2001/s-lang works
1. What this repository is
- This is a Python-based compiler/toolchain for the S-Lang language.
- The codebase is centered on a classic front-end/back-end pipeline, with the language spec and user-facing examples kept alongside the implementation.
2. Top-level source boundaries
- src/ contains the compiler implementation: lexer.py, parser.py, compiler.py, generator.py, and errors.py.
- stdlib/ contains built-in S-Lang modules shipped with the language runtime surface.
- examples/ holds sample .sl programs used to exercise syntax, modules, I/O, structs, and algorithms.
- docs/ is extensive reference material for features, errors, runtime checks, project structure, and implementation status.
3. Compilation pipeline
- The main data flow is: S-Lang source text → lexical tokens → parsed structure/AST → semantic validation/type checks → generated output.
- lexer.py is responsible for turning raw .sl text into tokens.
- parser.py builds the language structure consumed by later stages.
- compiler.py appears to orchestrate the compilation process, while generator.py handles backend emission.
4. Language semantics live in the compiler, not the examples
- The README shows S-Lang is statically typed, with explicit declarations, structs, functions, arrays, maps, sets, modules, and control flow.
- Those rules imply the compiler carries substantial semantic logic: type matching, const correctness, function signature checking, struct field validation, indexing checks, and operator compatibility.
5. Error handling is a first-class subsystem
- errors.py centralizes structured error types and messages.
- The docs split errors into lexer, parser, semantic, and runtime categories, which suggests each pipeline stage reports failures at its own boundary.
- This is important for architecture diagrams: errors are not an afterthought; they are part of the compiler contract.
6. Module system and code organization
- S-Lang supports include-based module loading and module-qualified names.
- The README defines a search order for module resolution: source directory first, then current working directory, then stdlib/.
- That makes file-system lookup a key boundary in the compiler, especially for local modules under examples/local_modules_test/ and built-in modules in stdlib/.
7. Standard library is source-level, not hidden runtime code
- stdlib/io.sl, stdlib/math.sl, and stdlib/system.sl are authored in S-Lang and treated as standard modules.
- This means the language’s core functionality is exposed through normal module imports rather than a separate host-language API surface.
- The compiler therefore needs to treat stdlib modules as part of the language ecosystem and module resolution path.
8. Runtime safety is part of the generated program
- The README documents runtime checks such as divide-by-zero and array bounds errors, with a flag to disable them for performance.
- That implies the generator likely emits checks into the compiled output, not just compile-time validation.
- In the architecture, runtime safety sits at the boundary between semantic analysis and generated executable behavior.
9. Examples are part of the validation loop
- examples/ provides a progression from basics to a comprehensive showcase, which suggests the repo is used as both a compiler implementation and a language conformance suite.
- test_output.txt likely captures expected output from one of these runs.
- For a diagram, examples should be shown as external inputs into the compiler pipeline, not as internal runtime components.
10. Build and developer tooling
- Makefile is the primary entry point for compiling/running examples, listing examples, and cleaning artifacts.
- pyproject.toml and .python-version indicate the implementation is managed as a Python project.
- This means the repo’s operational boundary is a Python host tool that processes S-Lang source files into executable results.
11. Documentation maps directly to subsystem boundaries
- The docs are organized around language features, implementation status, project structure, error system, and runtime errors.
- That documentation layout mirrors the compiler’s own architectural layers: syntax, semantics, runtime behavior, and packaging/module layout.
- In other words, the repo is not just source code; it includes a specification layer tightly coupled to the implementation.
Main entry points: compiler.py Module loader · errors.py Errors · lexer.py Lexer · parser.py Parser
Components 16
Repo surface
Project metadata, build entrypoints, and shared references.
- README · Top-level language and project overview.
README.md - Makefile · Primary task runner for building, running, and cleaning.
Makefile - Py project · Python packaging and toolchain metadata.
pyproject.toml
Compiler
Python implementation of the S-Lang toolchain.
- Lexer · Converts S-Lang source text into tokens.
src/lexer.py - Parser · Builds the language structure consumed by later stages.
src/parser.py - Compiler · Coordinates compilation, semantic validation, and module handling.
src/compiler.py - Semantics · Performs type checks, signature checks, indexing rules, and other validation.
src/compiler.py - Module loader · Resolves includes and module-qualified names across source and stdlib paths.
src/compiler.py - Generator · Emits compiled output and runtime safety checks.
src/generator.py - Errors · Structured lexer, parser, semantic, and runtime error types.
src/errors.py
Stdlib
Built-in S-Lang modules shipped with the language.
- IO module · Built-in source-level I/O support.
stdlib/io.sl - Math module · Built-in source-level math support.
stdlib/math.sl - System module · Built-in source-level system support.
stdlib/system.sl
Examples
Sample S-Lang programs used to exercise the compiler and modules.
- Showcase · Representative sample programs covering core language features.
examples/10_comprehensive_showcase.sl - Local modules · Example of repository-local module resolution.
examples/local_modules_test/db.sl
Docs
Reference material for features, errors, structure, and status.
- Error docs · Documentation for compiler and runtime error categories.
docs/ERROR_SYSTEM.md
Connections 20
- README → Compiler: defines · Language rules and architecture constrain the compiler.
- README → Module loader: describes · Documents module search order and include behavior.
- Makefile → Showcase: runs · Build and run tasks execute example programs.
- Py project → Compiler: hosts · Project metadata for the Python implementation.
- Showcase → Lexer: input · Example source is fed into the compilation pipeline.
- Local modules → Module loader: imports · Exercises repository-local module lookup.
- Lexer → Parser: tokens · Token stream flows into parsing.
- Parser → Compiler: ast · Parsed structure is handed to orchestration and analysis.
- Compiler → Semantics: checks · Compiler coordinates semantic validation.
- Semantics → Errors: reports · Validation failures become structured diagnostics.
- Parser → Errors: reports · Syntax failures are emitted as structured diagnostics.
- Lexer → Errors: reports · Lexical failures are emitted as structured diagnostics.
- Compiler → Module loader: resolves · Compiler locates included and qualified modules.
- Module loader → IO module: loads · Search path reaches built-in source modules.
- Module loader → Math module: loads · Search path reaches built-in source modules.
- Module loader → System module: loads · Search path reaches built-in source modules.
- Semantics → Generator: approved · Validated programs advance to code generation.
- Generator → Errors: checks · Runtime safety and emission failures are surfaced.
- Generator → Error docs: mirrors · Implementation corresponds to documented error categories.
- Error docs → Compiler: specifies · Documentation mirrors compiler boundaries and behavior.