How dart-archive/yaml_edit works
Project type and purpose
• This is an open-source Dart library/package (“yaml_edit”) whose sole purpose is to let users programmatically edit YAML documents in Dart while preserving comments and formatting.
• The README confirms: it exposes a YamlEditor API, uses unit & golden tests, and includes an example for JSON→YAML conversion.
File structure
• Top-level:
• pubspec.yaml (package metadata & dependencies)
• lib/ (public API and implementation)
• example/ (demo code)
• test/ (unit & golden tests + test data)
• CI configs under .github/
• lib/:
• yaml_edit.dart → exports the public API (YamlEditor)
• src/
– editor.dart → core orchestration: parse, apply edits, serialize
– list_mutations.dart & map_mutations.dart → high-level edit operations for lists/maps
– source_edit.dart → low-level text-edit tracking (insertion/deletion spans)
– wrap.dart & strings.dart → formatting helpers for output YAML
– utils.dart & equality.dart → auxiliary functions and deep-equality
– errors.dart → custom exception types
• test/: comprehensive coverage, including “golden tests” (input/output files under test/testdata)
README for additional insights
• Usage shows a simple edit workflow:
Input YAML string → YamlEditor → update() → toString() → Output YAML string
• Mentions limitations (no custom tags, map keys in flow style)
Elements
– Blue rectangles for core library modules (Editor, Mutation, SourceEdit, Serializer)
– Gray for external dependencies (YAML parser, dart:convert)
– Green for client/test code
– From client → API → Core → Mutations → SourceEdit → Serializer → back to client
– From CI → tests → modules
• Labels on each component with file names or class names (e.g., editor.dart → Editor)
Final advice
• Don’t overcomplicate: a few dozen components is fine—better to show every file group than to collapse everything.