137 lines
4.3 KiB
Markdown
137 lines
4.3 KiB
Markdown
# PureYAML Usage
|
|
|
|
PureYAML is a dependency-free Swift package for parsing, emitting, validating,
|
|
and typed-converting the YAML subset currently covered by the test corpus.
|
|
|
|
## Installation
|
|
|
|
The first release target is 0.1.0. After the tag is published, depend on the
|
|
tagged package version:
|
|
|
|
```swift
|
|
.package(url: "https://github.com/mihaelamj/PureYAML.git", .upToNextMinor(from: "0.1.0"))
|
|
```
|
|
|
|
Until that tag exists, use the `main` branch:
|
|
|
|
```swift
|
|
.package(url: "https://github.com/mihaelamj/PureYAML.git", branch: "main")
|
|
```
|
|
|
|
Add the product to the target that reads or writes YAML:
|
|
|
|
```swift
|
|
.product(name: "PureYAML", package: "PureYAML")
|
|
```
|
|
|
|
Then import the library:
|
|
|
|
```swift
|
|
import PureYAML
|
|
```
|
|
|
|
`Package.swift` for PureYAML itself keeps `dependencies: []`. Consumers do not
|
|
need C libraries, generated parser files, JavaScript tooling, or Foundation-only
|
|
support code to use the library target.
|
|
|
|
## Public Entry Points
|
|
|
|
The README examples are mirrored in `Tests/DocumentationExampleTests.swift`.
|
|
Those tests are the executable contract for the short-form examples.
|
|
|
|
| Need | API | Result |
|
|
|---|---|---|
|
|
| Parse YAML into an ordered value tree | `PureYAML.parse(_:)` | `PureYAML.Model.Value` |
|
|
| Emit YAML from a value tree | `PureYAML.dump(_:options:)` | `String` |
|
|
| Validate a value tree | `PureYAML.validate(_:using:strict:)` | `[PureYAML.Validation.Issue]` or a thrown issue collection |
|
|
| Decode a typed value from YAML | `PureYAML.decode(_:from:)` | `Decodable` value |
|
|
| Encode a typed value to a value tree | `PureYAML.encode(_:)` | `PureYAML.Model.Value` |
|
|
| Encode a typed value to YAML | `PureYAML.encodeToYAML(_:options:)` | `String` |
|
|
|
|
## Model Usage
|
|
|
|
Use `PureYAML.Model.Value` when the caller needs to inspect YAML structure,
|
|
preserve mapping order, validate duplicate keys, or handle YAML that does not map
|
|
cleanly to a Swift `Codable` type.
|
|
|
|
The model currently represents:
|
|
|
|
- `null`
|
|
- booleans
|
|
- integers
|
|
- doubles
|
|
- strings
|
|
- ordered mappings
|
|
- sequences
|
|
|
|
Mappings preserve insertion order and retain duplicate keys. That is deliberate:
|
|
validation can report duplicate-key diagnostics instead of losing information by
|
|
collapsing a mapping into a Swift dictionary too early.
|
|
|
|
## Typed Conversion
|
|
|
|
Use typed conversion when the YAML shape is already known. Current coverage
|
|
includes:
|
|
|
|
- scalar `Decodable` and `Encodable` values;
|
|
- keyed mapping-backed structs;
|
|
- optional scalar fields;
|
|
- nested keyed structs;
|
|
- unkeyed sequences;
|
|
- nested sequences;
|
|
- keyed structs with sequence properties;
|
|
- dictionary-like string-keyed mappings where YAML semantics allow them;
|
|
- keyed super coders and default `super` coders.
|
|
|
|
Typed decoding runs the default validator first. Duplicate mapping keys are
|
|
reported before Swift `Decodable` construction starts.
|
|
|
|
## Emitting Options
|
|
|
|
The default dumper emits deterministic block-style YAML with quoted strings.
|
|
Callers can opt into:
|
|
|
|
- conservative plain strings with `.plainWhenSafe`;
|
|
- safe literal block scalars for multiline strings with
|
|
`.literalBlockWhenMultiline`;
|
|
- compact flow collections with `collectionStyle: .flow`.
|
|
|
|
Literal block emission is conservative. If a multiline string would not
|
|
round-trip through the current parser, the dumper keeps it as a quoted scalar.
|
|
|
|
## Validation
|
|
|
|
The default validator rejects duplicate mapping keys anywhere in the value tree.
|
|
Validation issues include:
|
|
|
|
- severity;
|
|
- reason;
|
|
- path.
|
|
|
|
Strict validation treats warnings as failures. Non-strict validation returns
|
|
warnings but still throws when errors are present.
|
|
|
|
Use `PureYAML.Validation.Validator.blank` when the caller wants only
|
|
project-specific validation rules.
|
|
|
|
## Cross-Platform Verification
|
|
|
|
Before relying on a migration, run the same gates used by the repository:
|
|
|
|
```sh
|
|
bash scripts/check-all.sh
|
|
bash scripts/check-linux.sh
|
|
bash scripts/check-wasm.sh
|
|
```
|
|
|
|
`scripts/check-all.sh` includes style, namespacing, forbidden-pattern,
|
|
changelog, roadmap, SwiftFormat, SwiftLint, host build, host tests, Linux build
|
|
and test, and WASM build checks. The explicit Linux and WASM scripts are useful
|
|
when recording release or migration evidence.
|
|
|
|
## Support Boundaries
|
|
|
|
PureYAML is not yet a complete YAML 1.2 implementation. Before replacing another
|
|
YAML stack, read [MIGRATION.md](MIGRATION.md) and compare your input corpus with
|
|
the supported and unsupported behavior listed there.
|