rs

Rust Coding Rules for LLML Project

These guidelines are designed to maintain the existing quality, style, and architectural patterns of the codebase.

Project Structure & Modules

• Public API (src/lib.rs): The src/lib.rs file is the public face of the library. It should only contain the public API (llml, llml_with_options, Options struct) and its associated documentation and unit tests.
• Core Logic (src/formatters.rs): All internal formatting logic should reside in the src/formatters.rs module. Functions within this module should remain private to the crate (i.e., not marked with pub).
• Tests:
  • Unit Tests: Place unit tests within the module they are testing, using a #[cfg(test)] mod tests { ... } block.
  • Integration Tests: Place integration tests in the tests/ directory. These tests should only call the public API from lib.rs.
• Examples: Add new usage examples to the examples/ directory.

Coding Style & Formatting

• Formatting: All code must be formatted with rustfmt using the default settings.
• Naming Conventions:
  • Functions & Variables: Use snake_case (e.g., format_value, kebab_key).
  • Types (Structs, Enums): Use PascalCase (e.g., Options).
  • Constants & Statics: Use SCREAMING_SNAKE_CASE (e.g., MULTI_HYPHEN_RE).
• Clarity: Prioritize clear, readable code. Use descriptive variable names.

API Design & Patterns

• Public Functions: The primary public functions are llml (for default options) and llml_with_options (for custom formatting). Maintain this clear separation.
• Configuration: All configuration should be passed via the Options struct. When adding new configuration, extend this struct.
• Optional Configuration: Use Option<Options> for the llml_with_options function signature. Use options.unwrap_or_default() to handle the None case.
• Immutability: Prefer immutable variables (let) over mutable ones (let mut) unless mutability is strictly necessary (e.g., for builders or accumulators).
• Performance:
  • Pass complex types like Value and Options by reference (&) to avoid unnecessary clones.
  • For expensive initializations that can be shared (like Regex), use std::sync::OnceLock.