This release focuses on enhanced tag support.

• Implemented tag capturing (#183). Applications can use custom tags to express units, priorities, accessibility, or other application-specific semantics for a node. This is supported by new Tagged<T> wrapper that is similar to Commented<T>.
• Unsupported tags can now be rejected rather than ignored (new option reject_unsupported_tags, #180). This aligns the behavior with ruamel.yaml that rejects tags for which it has no constructor (serde-saphyr does not construct this way) that caused discussion on prek.
• Clearly wrongly placed tags like !!int [1] or !!map [1] are now an error.
• Documentation was revised to make sure all examples compile (are not fragments).

Added

• Added granit-parser resource limits to Budget (#172):

  • max_buffered_comment_events (default: 32)
  • simple_key_max_lookahead (default: 1,024 characters)
  • flow_nesting_limit (default: 255)

  The limits are applied to parsers created for strings, readers, standalone budget checks, and
  included YAML sources. When the serde_derived_types feature is enabled, deserializing an older
  Budget representation that omits these fields uses the documented defaults.

Fixes

• Fixed enums tags for struct variants (#177)
• Improved error message wording (#178)

• Fix #170 regression on local type tags
• By fixing granit-parser (use its release 1.0.1), explicitly fix #169 (large scalar deserialization performance regression)

This release is fully API compatible with 1.0.0 and must be a drop-in replacement.

From this release onward, we are adopting the 1.x.x semantic versioning (SemVer) scheme. This means that API changes will be clearly reflected in the version number: the major version indicates breaking changes, the minor version indicates backward-compatible additions, and the patch version indicates backward-compatible fixes. The current compatibility status is indicated by the accompanying badge.

This release adds some #[track_caller] and #[must_use] annotations where looks reasonable. There are not many other changes that is exactly the point: the crate seems serving community well enough.

From this release onward, we are adopting the 1.x.x semantic versioning (SemVer) scheme. This means that API changes will be clearly reflected in the version number: the major version indicates breaking changes, the minor version indicates backward-compatible additions, and the patch version indicates backward-compatible fixes. The current compatibility status is indicated by the accompanying badge.

Some breaking changes were made at this point because this is the last good time to streamline the API. Please raise any issues you find with the API changes, or if you would like to propose something. The goal of the release preview is exactly not to go 2.x.x next week after release.

• Options, SerializerOptions, Budget, and AliasLimits are now #[non_exhaustive]. Construct them with options!, ser_options!, budget!, and alias_limits!.
• Removed the deprecated to_writer and to_writer_with_options APIs. Use to_fmt_writer* for fmt::Write or to_io_writer* for io::Write.
• API compatibility check no guards compatibility with 1.0.0

Also

• Fix core tag enforcement. In the previous version, !!str 42 is accepted as i32(42), and !!int true is accepted as bool(true). Core tag handling is now hardened, and such constructs no longer pass.
• Fix: budget callbacks were sometimes not delivered on immediate breaches

• Summarizing results of automated fuzzing and static analysis, robustness against malformed (bad intent) YAML input was further hardened.
• Docker-compose, whose syntax serde-saphyr emulates, supports property nesting, so implemented nesting support for serde-saphyr as well. In the previous release, "${SET:-${B}}" with SET=value resolves to "value}".
• Fixed incorrect acceptance on Rust's float grammar (inf/Infinity/nan). YAML 1.2 only recognizes the .inf/.nan forms.
• Fixed caret misaligned in secondary snippet windows when line numbers exceed one digit
• FoldStr wrapping now cares not to start a continuation line with a tab
• Error reporting has been improved, showing location in some cases where previous versions were unable.
• Remove base64 create from deserializer dependencies (faster build)
• New version of (also hardened) granit-parser 0.0.7.

Significant extension of property interpolation ( @CommanderStorm)

• Added support for default property interpolation in plain scalars: ${NAME:-default} now resolves to default when NAME is unset or explicitly empty.
• ${VAR}: Values that must be configured (DB URLs, API keys). An unset var is a misconfiguration, not something to paper over -> a loud error at parse time
• ${VAR-fallback}: Empty value is meaningful and distinct from "not configured".
  F.ex. PREFIX="" -> "no prefix".
• ${VAR:-fallback}: The "regular" default, so f.ex. ${PORT:-8080}
• ${VAR+text}: F.ex. ${DEBUG+--verbose} emits the flag whenever DEBUG exists in the environment, regardless of value.
• ${VAR:+text}: Same as above, but differentiating empty <-> null

Also

• Fix #120 LastWins not honored when deserializing struct. This was implemented and well tested, but only with maps.
• Reduced owning of comment strings (parsing very heavily commented YAML while discarding comments should be lighter on resources).
• Fixed indentation enforcement (@CommanderStorm), making sure it also works for multiline scalars.
• Fixed tuple serialization (@CommanderStorm)
• New SingleQuoted<..> and DoubleQuoted<..> wrappers to emit quoted strings. SingleQuoted may provide additional safety, as control characters will be rejected (with error), rather than written as YAML escape sequences. NullableTilde<T> is like Option and emits tilde ( ~ ) rather than null.

Faster compilation times with serde_core

serde-saphyr now avoids compiling serde_derive by default. The crate core uses serde_core instead that allows building serde-saphyr in parallel with serde_derive. However this also means that we needed to drop the previously built-in (de)serialization support for some serde-saphyr own configuration and reporting types like Options. (De)serialization support for these types can be re-enabled with the new feature serde_derived_types:

serde-saphyr = { version = "...", features = ["serde_derived_types"] }

This does not affect normal use of serde-saphyr for user data, you can still serialize and deserialize your own structs as before.

The major extension of this release is comments support.

The long existed wrapper Commented<..> was usable for serialization only until now. Since this release, Commented also captures a comment of the wrapped data structure:

struct DeploymentConfig {
    name: Commented<String>,
    image: Commented<String>,
    ports: Commented<Vec<Commented<u16>>>,
    labels: Commented<BTreeMap<String, Commented<String>>>,
}

would capture all comments for the elements of the structure, like

# deployment manifest
name: checkout
image: registry.example.com/checkout:v1 # container image to deploy
ports: # sequence of exposed ports
  - 80 # public HTTP
  - 443 # public HTTPS
labels: # mapping of Kubernetes labels
  app: checkout # stable app label
  tier: frontend # routing tier
"#;

while assigning them to the relevant YAML element. This became possible after migrating to granit parser 0.0.3, which now captures comments. Comments can be either on the right or above the item they describe.

This release also adds support for figment2 (figment is supported since v0.0.13).

• UTF-16LE, UTF-16BE, UTF-8 with BOM and UTF-8 without BOM are all supported for the Reader - based methods (stabilized)
• Relaxed from_slice to support borrowed deserialization, aligning its behavior with from_str and from_slice_with_options
• Reduce size of Location data structure in huge_documents mode, using 48 bits only for offsets. This silences Clippy warnings, due these some teams needed to box serde-saphyr Error. The maximal size of documents in huge_documents mode is now 256 Tb that is unlikely a problem (default limit is 4 Gb).
• saphyr-parser-bw, whose primary consumer is serde-saphyr, has been renamed to granit-parser, adjusting serde-saphyr dependencies. The granit-parser crate has undergone a security audit followed by additional hardening.

Merge key handling is now configurable via MergeKeyPolicy. There may be communities that

• Indeed have such a strange keys like << as ordinary, and these are even not quoted, maybe in generated YAML. Handling of this case is supported via AsOrdinary variant.
• Took very strict internal policy disallow merge keys in configurations that is their choice, and want to alert about their presence to automate the code review. Handling them as ordinary may result valid YAML with unexpected result, and would not report the error location properly, so there is an Error variant for this case.
• Have legacy code with merge keys, or see nothing wrong with them (default: Merge)

• Fixed deserialization bug (#100) where mixing tagged and #[serde(untagged)] enum variants caused YAML tags to be ignored, leading to incorrect or failed variant resolution.
• Rewritten unit test (ser_coverage_boost.rs) that was triggering the false positive Socket alert (it never ever tried to access the network)
• Fixed taking numbers with preceding or trailing underscores as valid. 100000 is valid and 1000_000 also, but _10, 10_ are no longer. This is consistent with the serializer's auto-quoting policies.
• Publishing to crates.io now uses a trusted publishing workflow.

0.0.24 - remove heavy regex crate

Compare

Choose a tag to compare