How vberlier/rukt works
Project Type and Purpose
• Project Type: A Rust library crate that implements a domain-specific language (DSL) for token-based scripting using compile-time macros.
• Purpose: To allow users to store and manipulate token trees at compile time, emulating compile-time scripting in Rust. It’s designed to mirror well-established Rust idioms within a macro-based system.
File Structure
• Top-level Directories/Files:
• .github – Contains CI/CD configurations (workflows for testing and releasing).
• Cargo.toml and Cargo.lock – Describe the crate metadata and dependencies.
• LICENSE files – Define the open-source licensing (MIT/Apache-2.0).
• README.md and CHANGELOG.md – Provide documentation and release history.
• Source Code Directory (src):
• lib.rs – Serves as the primary entry point exposing the public API.
• eval.rs – Contains the core evaluation logic that interprets or transforms token trees.
• builtins.rs – Defines built-in token operations (like add, sub, etc.) available in the DSL.
• utils.rs – Provides utility functions to support the evaluation and builtin functionalities.
• Tests Directory:
• Contains integration tests (e.g., tests/rukt.rs) to validate the DSL behaviors.
README for Additional Insights
• The README illustrates usage examples of the rukt macros, emphasizing the compile-time expansion and token manipulation.
• It highlights that the crate is implemented entirely using declarative macros (macro_rules), ensuring simplicity and stability.
• Documentation links indicate separate internal components such as statements, expressions, and builtins, suggesting modular handling within the evaluation flow.
Components and Relationships
a. Main Components:
• Macro Interface: The public facing macros (rukt!) that user code invokes.
• Library API (src/lib.rs): The layer that abstracts and exposes the DSL functionalities.
• Evaluation Module (src/eval.rs): Processes and manipulates token trees at compile time.
• Builtins Module (src/builtins.rs): Houses the built-in operations (e.g., arithmetic operators) that can be applied within the DSL.
• Utilities (src/utils.rs): Contains helper functions supporting the evaluation and builtins.
• Testing Framework: The test module that automates tests, ensuring compilation and correct macro behavior.
• CI/CD Configuration: GitHub workflows managing build, test, and release pipelines.
b. Relationships and Interactions:
• The user writes code using the rukt macro, which directly interfaces with the Macro Interface.
• The Macro Interface calls into the Library API (lib.rs), which orchestrates the evaluation process.
• The Evaluation Module (eval.rs) is responsible for parsing token trees, conducting control flow/expressions, and integrating built-in operations.
• The Builtins Module (builtins.rs) is invoked by the Evaluation Module to process specific token operations.
• The Utility functions (utils.rs) are used by both the Evaluation and Builtins modules to perform common tasks.
• The CI/CD workflows ensure the entire codebase is continuously tested and released according to changes in the code.
c. Architectural Patterns or Design Principles:
• Modularity: Each core function (evaluation, builtins, utility) is separated into its dedicated module.
• Lightweight: No external dependencies and reliance solely on compile-time techniques using macro_rules.
• Declarative Programming: Emphasizes using Rust’s macro system for compile-time logic.
d. Relevant Technologies and Frameworks:
• Rust and Cargo – for building, testing, and publishing the crate.
• GitHub Actions – for automated testing and deployment.
• Declarative macros (macro_rules) – for DSL implementation.