Struct Settings

Source

pub struct Settings { /* private fields */ }

Expand description

All input and output settings.

A value type with private fields and chainable const fn setters, so a configuration can be a const:

use oneyaml_core::{Limits, Settings};
const CFG: Settings = Settings::new().merge_keys(true).max_depth(512);
const UNTRUSTED: Settings = Settings::new().limits(Limits::untrusted());

Settings are always passed explicitly; there are no globals and no environment variables. Every departure from YAML 1.2 is off by default.

§Settings, by the layer that consumes them

merge_keys — YAML 1.1 merge keys (<<). Resolver / Value / serde (later unit).
Other YAML 1.1 behaviours: yaml11_booleans, legacy_octal, sexagesimal, digit_separators, yaml11_int_forms. Resolver.
schema — Core (default), JSON, or Failsafe. Resolver (later unit).
duplicate_keys — tree builder and serde (later unit).
honor_version_directive — %YAML 1.1 switches that document to the Compat::yaml_1_1() behaviours. Resolver (later unit); the parser reports the directive either way.
lenient_inline_colons — parser (consumed now).
resolve_tagged_variant_content — serde deserializer (typed enum reads of !Name value, also through from_value_with and NodeRef::deserialize) and serializer (Layout::SerdeYaml).
limits (Limits) — max_depth, max_scalar_len, max_document_size, and max_documents are enforced by the parser now; alias_budget and alias_byte_budget by Value/serde reads.
emit (Emit) — serializer. The serializer also enforces max_depth on Values and max_typed_depth on Rust types, and refuses the JSON and Failsafe schemas (its output is written for Core).

§Examples

Every setter has a getter of the same name with get_:

use oneyaml_core::{DuplicateKeys, Emit, Limits, Schema, Settings};

// A YAML 1.1 reader for one legacy file, spelled out by hand.
let s = Settings::new()
    .merge_keys(true)
    .yaml11_booleans(true)
    .legacy_octal(true)
    .sexagesimal(true)
    .digit_separators(true)
    .yaml11_int_forms(true)
    .schema(Schema::Core)
    .duplicate_keys(DuplicateKeys::LastWins)
    .honor_version_directive(true)
    .lenient_inline_colons(false)
    .resolve_tagged_variant_content(false)
    .limits(Limits::untrusted())
    .max_depth(64)
    .emit(Emit::new())
    .indent(4);
assert!(s.get_merge_keys() && s.get_yaml11_booleans() && s.get_legacy_octal());
assert!(s.get_sexagesimal() && s.get_digit_separators() && s.get_yaml11_int_forms());
assert_eq!(s.get_schema(), Schema::Core);
assert_eq!(s.get_duplicate_keys(), DuplicateKeys::LastWins);
assert!(s.get_honor_version_directive());
assert!(!s.get_lenient_inline_colons() && !s.get_resolve_tagged_variant_content());
// `max_depth` and `indent` are shortcuts into `limits` and `emit`.
assert_eq!(s.get_limits().get_max_depth(), 64);
assert_eq!(s.get_emit().get_indent(), 4);
// The same 1.1 behaviours as a preset (limits stay the defaults).
let preset = oneyaml_core::Compat::yaml_1_1();
assert!(preset.get_yaml11_booleans() && preset.get_limits() == &Limits::default());

Implementations§

Source §

impl Settings

Source

pub const fn new() -> Settings

YAML 1.2, Core schema, default limits, default output. Same as Settings::default(), usable in const.

Source

pub const fn merge_keys(self, on: bool) -> Settings

YAML 1.1 merge keys (<<), e.g. for docker-compose files and GitLab CI. Off by default. Merges through aliases count toward Limits::alias_budget.

YAML 1.2 has no merge keys: without this setting << is an ordinary string key, as the spec says. Compat::yaml_1_1() turns it on with every other YAML 1.1 behaviour; Compat::serde_yaml() leaves it off, as serde_yaml’s deserializer does. A Document keeps << entries as written and edits them like any other entry.

Source

pub const fn yaml11_booleans(self, on: bool) -> Settings

YAML 1.1 booleans (yes/no/on/off/y/n, …). Off by default.

Source

pub const fn legacy_octal(self, on: bool) -> Settings

YAML 1.1 legacy octal integers (0777). Off by default.

Source

pub const fn sexagesimal(self, on: bool) -> Settings

YAML 1.1 sexagesimal (base-60) numbers (12:30). Off by default.

Source

pub const fn digit_separators(self, on: bool) -> Settings

YAML 1.1 digit separators (1_000). Off by default.

Source

pub const fn yaml11_int_forms(self, on: bool) -> Settings

YAML 1.1 integer forms that YAML 1.2 dropped: binary (0b1010, optionally signed) and a sign on hexadecimal (-0x1F, +0x1f). Off by default. _ separators in these forms still need Settings::digit_separators; 1.1 octal, signed or not (017, -017), is Settings::legacy_octal. A signed 0o (-0o17) is neither YAML 1.1 nor 1.2 and stays a string under every setting.

Source

pub const fn schema(self, schema: Schema) -> Settings

The schema (default Schema::Core).

Source

pub const fn duplicate_keys(self, policy: DuplicateKeys) -> Settings

Duplicate-key handling (default DuplicateKeys::Error).

Source

pub const fn honor_version_directive(self, on: bool) -> Settings

Let %YAML 1.1 switch its document to the YAML 1.1 behaviours of Compat::yaml_1_1(); %YAML 1.0 gets the same preset, 1.1 being the closest supported version. Off by default: such documents are read as YAML 1.2 with a warning.

Source

pub const fn lenient_inline_colons(self, on: bool) -> Settings

Leniency, not YAML: read a same-line : inside an unquoted block value as text instead of an error, e.g. title: The farm: a banana story becomes the string The farm: a banana story. Off by default; when it applies, a warning is always recorded. Flow context is unaffected, and no valid input changes meaning. Not part of any Compat preset.

Source

pub const fn resolve_tagged_variant_content(self, on: bool) -> Settings

serde_yaml compatibility, not YAML 1.2: when a typed enum reads a locally tagged plain scalar (!Name value) as its variant Name, the content is resolved as an untagged plain scalar under the Core schema (with the document’s YAML 1.1 integer, boolean, … settings), so !Square 2.0 reads as Square(2.0) and !Enabled true as Enabled(true). This is how serde_yaml writes a newtype variant around a number, bool, or null; with the setting on, Layout::SerdeYaml writes such variants that way too.

Off by default: YAML 1.2 leaves the meaning of a local tag to the application (§6.9.2), and without the setting a custom-tagged scalar is the tagged string. On in Compat::serde_yaml() only. Only typed enum reads change: Value keeps Tagged("!Square", String("2.0")), untyped reads (deserialize_any) are unchanged, and quoted content stays a string (!Square '2.0' is text; from_value_with cannot tell, as a Value keeps no style, and there resolves to a bool or a number only, never to null). Global and %TAG-expanded tags are not local and never resolve.

Under this setting (with Layout::SerdeYaml) the streaming serializer (to_string_with and friends) writes such a variant as !Name v, while to_value_with followed by emitting the Value writes Name: v: a Value has no enums, and its tagged scalars are strings, so the meaning-level map form is the only Value that reads back as the variant.

Source