$ show cloudbase/powershell-yaml
This is a mature PowerShell module (`powershell-yaml`) that provides high-fidelity YAML serialization and deserialization for PowerShell objects. It wraps the popular YamlDotNet library and extends it with a powerful typed class system (`YamlBase`), custom type converters, metadata preservation (comments, tags, scalar styles, mapping styles), case-sensitive key support via `[YamlKey]` attribute, and duplicate key detection to prevent data loss. The architecture is a hybrid: a PowerShell script module (`powershell-yaml.psm1`) that loads a C# class library compiled for netstandard2.0, providing both synchronous cmdlets (`ConvertTo-Yaml`, `ConvertFrom-Yaml`) and public API functions for metadata manipulation. The C# code uses Assembly Load Context (ALC) isolation for YamlDotNet to avoid conflicts with other modules. The module supports both traditional hashtable output and an enhanced PSCustomObject mode with full round-trip metadata preservation, as well as strongly-typed deserialization into PowerShell classes inheriting from `YamlBase`. This is a production-quality library with extensive test coverage, active maintenance, and well-documented examples.
The LLM identified 3 files worth highlighting for reuse:
Abstract base class for typed YAML objects. Provides metadata storage for comments, tags, and styles; automatic PascalCase-to-hyphenated-case property name conversion; `[YamlKey]` attribute support for custom YAML keys; `[YamlConverter]` attribute for custom type converters. Its `ToDictionary()` and `FromDictionary()` methods use reflection to serialize/deserialize properties, with deep nesting support for nested `YamlBase` objects and arrays. The metadata dictionary uses only ALC-safe types (Dictionary from mscorlib), making it safe for PowerShell class inheritance. This component is reusable as a standalone base for any typed YAML configuration system in PowerShell.
Contains `YamlDocumentParser` (static class) that parses YAML with full metadata preservation using low-level YamlDotNet events. It captures comments (inline and block), tags, scalar styles, mapping styles, and sequence styles into a `YamlMetadataStore` structure. This parser is the foundation for the enhanced PSCustomObject mode and typed mode metadata preservation. Also includes `MetadataAwareSerializer` for writing back with metadata, and `PSObjectMetadataExtensions` for creating enhanced PSCustomObjects. The `BuilderUtils` class configures YamlDotNet serializer with custom type converters (BigInteger, IDictionary, PSObject) and depth-limiting traversal. These components are tightly coupled to YamlDotNet but could be extracted as a library for round-trip YAML editing in any .NET application.
Public API for typed YAML conversion (`FromYaml`, `ToYaml`). Handles deserialization by first parsing YAML with metadata, then converting to `Dictionary<string, object?>`, validating that case-insensitive duplicate keys have explicit `[YamlKey]` mappings, and finally populating the `YamlBase` instance via `FromDictionary()`. Metadata is copied to the instance before and after `FromDictionary` to support custom converters. Serialization uses `ToDictionary()` and emits YAML with style and tag overrides. The `ValidateDuplicateKeysHaveExplicitMappings` method implements a robust guard against data loss. This component is reusable for any typed YAML processing pipeline.