sneak
cf13b275b7
commit e15edaedd786254cf22c291a63a02f7cff33b119
Author: sneak <sneak@sneak.berlin>
Date: Mon Jul 21 15:17:12 2025 +0200
Implement YAML-first interpolation with type preservation
Previously, interpolations were performed during string manipulation before
YAML parsing, which caused issues with quoting and escaping. This commit
fundamentally changes the approach:
- Parse YAML first, then walk the structure to interpolate values
- Preserve types: standalone interpolations can return numbers/booleans
- Mixed content (text with embedded interpolations) always returns strings
- Users control types through YAML syntax, not our quoting logic
- Properly handle nested interpolations without quote accumulation
This gives users explicit control over output types while eliminating
the complex and error-prone manual quoting logic.
61 lines
2.3 KiB
Markdown
61 lines
2.3 KiB
Markdown
# Design: YAML-First Interpolation
|
|
|
|
## Problem Statement
|
|
|
|
The current implementation performs string-based interpolation on the raw YAML file content before parsing. This approach has several issues:
|
|
|
|
1. **Quoting complexity**: We must handle YAML quoting rules manually, leading to edge cases and bugs
|
|
2. **Type loss**: All interpolated values become strings, even if they should be numbers or booleans
|
|
3. **YAML special values**: Values like "no", "yes", "true", "false", "on", "off" require special handling
|
|
4. **Nested interpolation quoting**: Complex logic needed to avoid double-quoting in nested interpolations
|
|
5. **Fragile string manipulation**: Operating on raw YAML text is error-prone
|
|
|
|
## Proposed Solution
|
|
|
|
Parse the YAML file first, then walk the parsed structure to perform interpolations. This approach:
|
|
|
|
1. **Leverages YAML parser**: Let the YAML library handle all parsing, quoting, and escaping
|
|
2. **Preserves types**: Can return actual numbers, booleans, etc. from interpolations
|
|
3. **Simplifies logic**: No string manipulation or quoting logic needed
|
|
4. **Clear semantics**: Users control types through YAML syntax (quoted vs unquoted)
|
|
5. **Robust**: YAML serializer handles all edge cases correctly
|
|
|
|
## Implementation Details
|
|
|
|
### Constraints
|
|
|
|
- Interpolation only occurs in YAML values, not keys
|
|
- Users must properly quote interpolations if they want string output
|
|
- The entire file must be valid YAML before interpolation
|
|
|
|
### Workflow
|
|
|
|
1. Parse YAML file into a data structure (map/slice/scalar)
|
|
2. Recursively walk the structure:
|
|
- For string values: check for `${...}` patterns and interpolate
|
|
- For other types: pass through unchanged
|
|
3. Handle the special `env` key to inject environment variables
|
|
4. Return the modified structure
|
|
|
|
### Type Handling
|
|
|
|
Users control the output type through YAML syntax:
|
|
|
|
```yaml
|
|
# String output (user quotes the interpolation)
|
|
port: "${ENV:PORT}" # Result: "8080" (string)
|
|
|
|
# Numeric output (no quotes)
|
|
port: ${ENV:PORT} # Result: 8080 (number)
|
|
|
|
# Boolean output
|
|
enabled: ${ENV:ENABLED} # Result: true/false (boolean)
|
|
```
|
|
|
|
### Benefits
|
|
|
|
1. **Correctness**: YAML parser handles all edge cases
|
|
2. **Type safety**: Preserves intended types
|
|
3. **Simplicity**: Removes complex string manipulation
|
|
4. **Predictability**: Users have explicit control over types
|
|
5. **Maintainability**: Less code, fewer edge cases |