Package dev.omnist.codec

Class YamlCodec

java.lang.Object
dev.omnist.codec.YamlCodec
public final class YamlCodec extends Object
Codec for reading and writing the Omnist Document model as YAML (omnist-spec §7.3), built on SnakeYAML.

Reading: YAML mappings map to Node values; SnakeYAML's default core-schema resolution handles booleans (including YAML 1.1 words like yes/no/on/off) with no customization needed. Timestamps are custom-resolved to distinguish a bare date from a full date-time before falling back to SnakeYAML's own timestamp construction.

Aliases and merge keys are bounded (omnist-spec §2.4.1, D-18 to D-22): the expansion factor of every mapping and sequence (default 50, document.limit.alias-expansion) and, for an input that contains an alias or a merge key, the expanded size of the document (default 1 000 000 value slots, document.limit.expanded-size). Both are checked on the composed node graph before anything is constructed from it; see readWithLimits(String, YamlLimits) and YamlLimits.

Writing: cannot achieve round-trip fidelity for time-kind scalars — no safe bare YAML spelling exists for a time-of-day that doesn't collide with YAML's sexagesimal (base-60) number notation — so time values are written as quoted ISO-8601 strings via the usual format.temporal-stringified adjustment.

This class is stateless; all methods are static.

  • Field Details

    • MAX_INPUT_LENGTH

      public static final int MAX_INPUT_LENGTH
      Maximum accepted input length in characters, guarding against oversized YAML input.
      See Also:

  • Method Details

    • read

      public static Document read(String text)
      Parses YAML text into a Document, with the reference alias limits (YamlLimits.DEFAULT). Equivalent to readWithLimits(text, YamlLimits.DEFAULT).
      Parameters:
      text - the YAML text; must not be null
      Returns:
      the parsed document
      Throws:
      RuntimeException - if the YAML is syntactically invalid, exceeds MAX_INPUT_LENGTH, or crosses a safety limit (see readWithLimits(String, YamlLimits))

    • readWithLimits

      public static Document readWithLimits(String text, YamlLimits limits)
      Parses YAML text into a Document, bounding what its anchors and aliases may expand to (omnist-spec section 2.4.1).

      The text is composed into SnakeYAML's node graph, which describes the anchors and aliases without expanding them, and that graph is checked before anything is constructed from it (D-19), in time linear in the input. In this order:

      1. A merge key whose value is not a mapping or a sequence of mappings is parse.codec-syntax, and wins over every limit code below (D-18a).
      2. An anchored definition that refers to itself, directly or through other definitions, is document.limit.alias-expansion (D-20).
      3. If any mapping or sequence (the root, an inline merge source and an anchored definition included) has an expansion factor W / S above YamlLimits.maxAliasExpansion(), the input is document.limit.alias-expansion at $ (D-18).
      4. If the input contains an alias or a merge key and its root materializes more than YamlLimits.maxExpandedSlots() value slots, the input is document.limit.expanded-size at $ (D-22). An input with neither is exempt however large; one that fails both limits reports step 3.

      W is the structural count of the spec: it ignores key collisions, so a document whose merged keys are overridden can be refused though it materializes fewer slots. A merge of a large block is not free either: a mapping that merges a k-key block and writes one key of its own has an expansion factor of about (k + 2) / 3.

      Parameters:
      text - the YAML text; must not be null
      limits - the alias limits; must not be null
      Returns:
      the parsed document
      Throws:
      RuntimeException - if the YAML is syntactically invalid, exceeds MAX_INPUT_LENGTH, or crosses a safety limit

    • read

      @Deprecated(since="0.1.0-alpha", forRemoval=true) public static Document read(String text, Schema schema)
      Deprecated, for removal: This API element is subject to removal in a future version.
      The schema parameter is ignored for YAML. Use read(String) followed by Materializer.materialize(Document, Schema) if schema-driven coercion is required.

    • write

      public static String write(Document node)
      Serializes a Document to YAML text, non-strict (applying adjustments rather than throwing). Equivalent to write(node, false, null).
      Parameters:
      node - the document to serialize
      Returns:
      the YAML text

    • write

      public static String write(Document node, boolean strict, WriteReport report)
      Serializes a Document to YAML text.
      Parameters:
      node - the document to serialize
      strict - if true, throws when the document contains any adjustment (e.g. a stringified time value); if false, applies the adjustment and continues
      report - if non-null, every adjustment made during writing is appended here
      Returns:
      the YAML text
      Throws:
      WriteException - if strict is true and an adjustment was required

    • check

      public static WriteReport check(Document node)
      Computes what adjustments write(Document) would make to node without actually producing YAML text.
      Parameters:
      node - the document to check
      Returns:
      the adjustments (e.g. stringified time values) that a write of node would require