How ufirstgroup/ymlr works
Project type and purpose
• Type: Open-source library/tool (Elixir package).
• Purpose: Provide a flexible, opinionated YAML encoding API (Ymlr.document!, Ymlr.documents!, etc.) with optional features (comments, atom support, sorted maps).
• Key indicators:
• mix.exs dependency file, lib/ymlr source folder, absence of “frontend/backend” directories → library.
• README describes API functions and benchmarks.
File structure
Top‐level directories and files:
• lib/ymlr/
– encode.ex (low-level emitter)
– encoder.ex (higher-level pipeline)
– ymlr.ex (public API module)
• benchmark/: stand-alone Elixir script to measure performance.
• test/ & test_support/: unit tests and fixtures.
• .github/: CI workflows (code quality, Elixir matrix).
• Config files: mix.exs, .tool-versions, .formatter.exs, .envrc, Nix tooling (flake.nix).
README for additional insights
• Public API functions: Ymlr.document!, Ymlr.documents! and options (atoms, sort_maps).
• Benchmark workflow outlined (script under benchmark/).
• No external services at runtime; purely library.
Main components and their relationships
a. Public API Layer
• Ymlr module (entry points for users)
b. Core Encoding Pipeline
• Ymlr.Encoder – orchestrates options, handles multiple documents, invokes low‐level emitter
• Ymlr.Encode – transforms individual data structures to YAML strings (handles indentation, comments, value quoting)
c. Supporting Components
• Benchmark Script (benchmark/run.exs) – independent process measuring performance
• Test Harness (test/, test_support/) – confirms correctness via fixtures and helpers
• CI/CD (.github/workflows/...) – automates quality checks and publishing
d. External Integrations
• Hex.pm (package publishing)
• Coveralls, Codecov (coverage reporting)
• GitHub Actions (build/test matrix)
Architectural patterns and design principles
• Layered design: Public API → orchestration (Encoder) → low-level emitter (Encode)
• Single responsibility: Each module focuses on one aspect (API surface, pipeline logic, YAML emission)
• Configuration via options: non-intrusive flags (atoms, sort_maps), passed top-down
• Testable units: encode and encoder logic decoupled for targeted tests
Detailed component breakdown to capture
[User App]
→ calls → [Ymlr (Public API)]
→ delegates to → [Ymlr.Encoder (Pipeline OR Multi-doc Handler)]
→ invokes → [Ymlr.Encode (Emitter)]
→ produces → [YAML text]
● Option flags flow top‐down from API through Encoder to Encode.
● Benchmark harness calls API directly (side path).
● Test suite invokes Encoder/Encode modules (side path).
● CI/CD triggers test suite, coverage, benchmark.