How teal-language/tl works
Main Project Components
• Compiler Engine: This is the heart of the project and is primarily contained in the single-file core (tl.lua) and its Teal counterpart (tl.tl). It encapsulates the logic that reads, parses, type-checks, and compiles Teal code.
• Command-line Interface (CLI): Teal supports subcommands (such as run, check, gen, warnings) that enable users to invoke the compiler in different modes. This layer also deals with reading command-line arguments, configuration files (tlconfig.lua), and applying compiler options.
• Loader and Integration Module: The compiler supports on-the-fly Teal file compilation with the package loader (via tl.loader()). Represent this as a dedicated component that integrates with Lua’s require() mechanism.
• Build Tool Integration: Although not part of the core code, the README suggests integration with Cyan (a separate build tool designed for Teal). This external dependency layer can be noted as an optional tool that interacts with the compiler.
• Testing & Specification Framework: With a rich “spec” directory subdivided into various subdirectories (api, cli, lang, etc.), this part of the project ensures that each language component (lexer, parser, code generation, inference, subtyping, etc.) is thoroughly tested. It documents expected behavior for all compiler phases.
Detail of the Compiler Engine (Core Pipeline)
• Input: Teal source files (.tl) provided by the user.
• Lexical Analysis: Represent the lexer component (see spec/lang/lexer and related tests). It breaks down the input source code into tokens.
• Parsing: Show the parser module (spec/lang/parser) that converts tokens into an Abstract Syntax Tree (AST).
• Macro Expansion & Code Generation: Include components for macro expansion (spec/lang/macroexp) and code generation (spec/lang/code_gen), where the compiler converts the typed AST into plain Lua code (removing type annotations).
• Error Reporting: There is a dedicated element for error reporting (spec/lang/error_reporting), ensuring that syntax and type errors are well-captured.
Communication / Data Flow Among Components
• For the testing modules in the “spec” directory, indicate that these validate interactions between each of the components.
Architectural and Design Patterns
• The design is modular. Even though the core compiler begins as a single file, the extensive spec directory reflects a clear separation of concerns (e.g., separate modules for lexer, parser, and type system).
• The compiler’s integration as a loader for Lua represents an adapter-like pattern that plugs into Lua’s require mechanism.
• The use of subcommands in the CLI suggests a Command pattern for handling different user inputs.
• The testing framework is organized to mirror the compiler internals, indicating a design that values high-testability and modularity.