Why a document did not become the value the caller asked for.

Two things can go wrong, and they are different things: the YAML may not have been read at all, or it may have been read and not be the shape a type needs. Both carry where — the reader's position, or the path into the document — so a caller can say which line to look at.

The value <code>Show</code> prints, written to the logger it is given.

The value as <code>Debug</code> writes it, for a test's output.

The value as <code>Show</code> writes it, for a person to read.

An implementation of a trait, as the compiler generated it.

Why a document was refused.

YAML's own answer to ambiguity is to be permissive, which is how a configuration file comes to mean something other than what it looks like. This reader refuses instead: anything it cannot resolve to one reading is an error with a position, never a guess.

Where the refusal happened.

Every variant carries a position, so a caller that wants to report the line and column does not have to match all twelve of them to get at it.

Whether two values are the same, as <code>Eq</code> defines it.

The negation of <code>equal</code>.

The value <code>Show</code> prints, written to the logger it is given.

The value as <code>Debug</code> writes it, for a test's output.

The value as <code>Show</code> writes it, for a person to read.

An implementation of a trait, as the compiler generated it.

Where in the source something is: the offset in code units, and the line and column a person counts from one.

Every refusal carries one, because a configuration file that will not load is read by a person who needs to know which line to look at.

Whether two values are the same, as <code>Eq</code> defines it.

The negation of <code>equal</code>.

The value <code>Show</code> prints, written to the logger it is given.

The value as <code>Debug</code> writes it, for a test's output.

The value as <code>Show</code> writes it, for a person to read.

An implementation of a trait, as the compiler generated it.

What to do when a mapping names the same key twice.

YAML 1.2.2 §3.2.1.1 says the keys of a mapping are unique and leaves the handling of a duplicate to the processor. Every loader in reach takes the last one, which is what Last does; First and Reject are here because a configuration file with a key written twice is usually a mistake someone would rather be told about.

Whether two values are the same, as <code>Eq</code> defines it.

The negation of <code>equal</code>.

The value as <code>Debug</code> writes it, for a test's output.

How a document is read: the limits, and what to do with a duplicate key.

The preset is strict. Build another with Flavor::new, or update one in place with { ..strict, depth: 64 }.

Whether two values are the same, as <code>Eq</code> defines it.

A flavor by name, every knob with the preset's value.

The negation of <code>equal</code>.

The value as <code>Debug</code> writes it, for a test's output.

What a node is.

An alias is a node of its own rather than a copy of what it names: a document with an anchor and three aliases is three references, and writing it back as twelve copies would be a different document.

How a collection is laid out.

Block is the style a configuration file is written in: one entry per line, a person can read it and a diff shows one change per line. Flow is the brace and bracket form, which JSON shares and which a machine-generated file often wants. Auto picks per collection: flow when it holds nothing but scalars and the whole of it fits in Style::width, block otherwise. A collection of collections stays block, because that is the shape of a configuration file.

Whether two values are the same, as <code>Eq</code> defines it.

The negation of <code>equal</code>.

The value as <code>Debug</code> writes it, for a test's output.

One node of a document.

This node, anchored.

This node, with the comments written around it.

One document as the events a parser produces for it: +DOC down to -DOC, with a +MAP/+SEQ for a collection, =VAL for a scalar and =ALI for a reference, each nested one space further in than the event that opened it.

The notation is the YAML Test Suite's, which is where it is specified: the style a scalar was written in is the character before its text (:, ', ", |, >), a flow collection carries {} or [], an anchor &name and a tag <tag> come before the value, and control characters are escaped.

This is the document as a parse rather than as a value: a key that is not a string, a key written twice, two documents in one stream — all of them have events, and none of them has a Json. A caller who wants to know whether two documents are the same *document* rather than the same value can compare these.

This node, written in flow style.

A block mapping.

A tree for a Json value: the document a program would write for it.

A scalar of a known kind, keeping the spelling it was read from.

Whether two documents would be written the same way.

The comparison a round trip is: read, write, read again, and the second tree is the first one. Positions are not in the tree, so this is equality of content.

A plain scalar, which is how most of YAML is written.

A block sequence.

This node, written in a particular scalar style.

This node, tagged.

The Json this document denotes, with its aliases expanded.

Which quote a string gets when it needs one.

Minimal quotes only what would otherwise read as something else, which is what makes the output look written rather than generated. Single and Double are for a caller whose output feeds a second reader that is happier with one form.

Whether two values are the same, as <code>Eq</code> defines it.

The negation of <code>equal</code>.

The value as <code>Debug</code> writes it, for a test's output.

What a YAML version resolves an unquoted scalar to.

The three released versions disagree with each other, and the disagreements are all here rather than in the scanner: 1.1 reads yes as a boolean, 014 as twelve and 1:30 as ninety, 1.2 reads all three as strings, and StrictYAML reads every scalar as a string whatever it looks like. A version is a set of rules over one reader, which is why this library has one parser and not four.

A dialect nobody has published yet — a configuration language of your own, a pre-1.0 variant — is a Rules of your own, passed through Schema. Nothing here is closed.

Whether two values are the same, as <code>Eq</code> defines it.

The negation of <code>equal</code>.

The value as <code>Debug</code> writes it, for a test's output.

How a scalar was written.

A block scalar carries the chomping indicator that was written with it, because | and |- are different strings at the end of a line.

Whether two values are the same, as <code>Eq</code> defines it.

The negation of <code>equal</code>.

What a YAML version does that the scanner cannot decide for it.

The scanner in this package is shared; what a version resolves a scalar to, and what it allows besides, is a Schema.

The one in this package is core, the core schema of §10.2. The v11, v10, strict and any packages beside it are each a schema over the same scanner, which is why a version is a resolver rather than a fork of the reader.

How a document is written: the indentation, the line width, the layout, the quotes, and whether a repeated subtree is written once and referred to after.

The preset is style. Build another with Style::new, or update one in place with { ..style, width: 120 }.

Whether two values are the same, as <code>Eq</code> defines it.

A style by name, every knob with the preset's value.

The negation of <code>equal</code>.

The value as <code>Debug</code> writes it, for a test's output.

YAML 1.0's, which is 1.1 plus the single letters y and n. The 1.1 revision removed them because a lone n is more often a name than a no.

How many nodes the aliases in one document may expand to.

An alias can name a node that itself contains aliases, so a dozen lines can expand to billions of nodes: the "billion laughs" shape, which is what YAML's alias facility costs unless something counts. There is no published value to follow, so this takes the safe side — enough for any document anyone meant to write, far short of exhausting memory. Flavor::new(budget=...) raises it, and aliases=false refuses an alias outright.

The core schema of YAML 1.2.2 §10.2: what this package reads.

YAML 1.2's core schema: nothing but true/false, null, and the decimal, 0o and 0x numbers of §10.2.

How deep a document may nest.

500 is deep enough for any configuration file ever written and shallow enough that a reader which walks the tree cannot be driven off the stack by one that was not. A document that nests deeper than this is not a configuration file, and is refused rather than read.

The same document, all in flow style — the form JSON shares.

How much a nested level is indented.

Two spaces: what almost every configuration file in the wild uses, and what a reader's eye is trained on.

YAML 1.1's type resolution, §10.3 of the 1.1 specification: the booleans, the octal and binary integers, the underscored numbers, and the base-60 form.

The preset: refuse what is ambiguous, take the last of a repeated key, expand aliases within the budget.

The preset: two-space block style, folded at 80 columns, quoting only what has to be quoted, anchors for what repeats.

Block, not Auto: what this writes is a configuration file, and a configuration file is read one entry to a line. Auto is a knob for output whose reader is a machine.

The column a writer folds at.

80: the width yamllint defaults to, which is itself the width of a terminal and of the Python PEP 8 convention the tooling around YAML grew up beside.

The version a stream declares in its first %YAML directive, if it declares one.

A reader may pick its rules from the document itself rather than from the caller, which is what any does. Only the first directive counts: §6.8.1 allows one per document, and the one that decides how the rest is read has to come before the rest.

The same, as UTF-8 bytes — the s on dumps is the one Python puts on the form that answers a string.

The same, as UTF-8 bytes.

Write a Json tree as a YAML document.

Block style by default, which is what a configuration file is written in and what a person reads. A string is quoted only when plain would read back as something else — a number, a boolean, a null, or not at all — so the output looks like a file someone wrote rather than one a program emitted.

This is the reason to have a writer at all: a generator that builds YAML by joining strings gets the escaping wrong the first time a value contains a colon, and gets the indentation wrong the first time a value is a list.

style says how; indent and sort override the two knobs that change from call to call. A flat parameter wins over the record — see "Configuration" in the README.

A stream of documents, each opened by its own ---.

The separator goes before each document rather than between them, which is the one convention that stays correct under concatenation: two streams joined end to end still read as their documents, and appending one is appending lines. A reader of either convention reads this one — a marker before the first document is not an error anywhere — so nothing is given up by choosing it.

A value of type T, written as a YAML document.

The other direction of loads_as, through the same ToJson trait, so a type that writes itself as JSON writes itself as YAML without knowing it.

A stream of values, each written as its own document.

Emit a document as YAML, keeping the styles and comments it was read with.

indent is how far a nested block is indented, and from is how far the root already is — a document embedded in another one needs the second.

A document that was written under an explicit --- gets one back, on a line of its own; the comments above it stay above it.

Every document's events, between the +STR and -STR that open and close a stream — one line per event, which is what makes two streams comparable line by line.

The one document in src, decoded as UTF-8.

bom skips a leading byte-order mark, which YAML 1.2.2 §5.2 allows at the start of a stream and which an editor on Windows will happily write.

Every document in src, decoded as UTF-8.

The one document in src, decoded as UTF-8, as a value of type T.

The one document in src.

Raises Refused::Trailing if a second document follows, which is what tells a caller expecting one file's worth of configuration that it got a stream.

schema says which YAML version reads it; the default is core. A document that opens with %YAML 1.1 is not read as 1.2 by default — pick the version, or let the any package pick it for you.

Every document in src, in order.

A stream with no documents at all is an empty array, not a null: nothing is not the same as one document containing nothing.

The one document in src, as a value of type T.

let config : Config = @moonyaml.loads_as(src)

T is anything that implements core's FromJson, which is the same trait a JSON document is read through: a type written for moonjson needs no second implementation to be read from YAML. That is the point of reading into the same Json tree — the shape of a value is one question, and which text it arrived in is another.

The default schema is 1.2's core. Read a 1.1 file with @moonyaml/v11's schema, or let @moonyaml/any pick it from the document.

One document, as a tree.

Every document in the stream, as trees.

A stream with nothing in it holds no document, which is what loads_all says too; parse is where a single document is owed, and it gives the null one.

Read a document as T, let adjust change it, and write it back.

The three steps a configuration loader actually takes: read what the user wrote, fill in what they left out, write the whole of it back. adjust is where the defaults go, and it is also what says which type this is — a call with no adjust cannot tell.

How YAML 1.1 resolves a scalar: yes/no/on/off are booleans, 014 is twelve, 0b1010 is ten, 1_000 is a thousand, and 1:30 is ninety.

YAML 1.1's schema: the 1.1 types, and the merge key.

The merge key is 1.1's own (§7.1) — a << key whose value is a mapping, or a sequence of mappings, is folded into the mapping around it. It is not in 1.2, which is why this is a schema and not a default.

Write a value as YAML 1.1: a string that 1.1 would read back as a boolean or a number is quoted, so what is written is what is read.

Every document, each opened by its own ---.

The one document in src, decoded as UTF-8 and read as YAML 1.1.

Every document in src, decoded as UTF-8 and read as YAML 1.1.

The one document in src, read as YAML 1.1.

Every document in src, read as YAML 1.1.

How YAML 1.0 resolves a scalar: everything 1.1 does, and y/n — in either case — as booleans.

The 1.1 revision dropped the single letters, because a lone n is more often a name than a no: n: 1 in a table of columns is a heading, not a false. A file that says %YAML 1.0 means the older reading.

YAML 1.0's schema.

Write a value as YAML 1.0.

Every document, each opened by its own ---.

The one document in src, decoded as UTF-8 and read as YAML 1.0.

Every document in src, decoded as UTF-8 and read as YAML 1.0.

The one document in src, read as YAML 1.0.

Every document in src, read as YAML 1.0.

The preset for reading StrictYAML: a repeated key is a fault.

StrictYAML rejects duplicate keys, and it is right to: a mapping that names the same key twice has no reading that a person could have predicted.

How StrictYAML resolves a scalar: as text, always.

This is the whole of StrictYAML's first promise. port: 8080 and port: "8080" are the same string, enabled: yes is the word, and the caller says what a value means by reading it through a schema of its own. Nothing in a document is a number, a boolean or a null because of how it is spelled.

StrictYAML's schema: text scalars, no tags, no anchors, no flow style.

Each of those is a feature StrictYAML removes, and each is removed for the same reason — it makes what a document says depend on something other than the text in front of the reader:

• a tag asks for a type the reader may not have;
• an anchor makes one node appear in two places, so the document is no longer a

tree you can read top to bottom;

• flow style packs structure onto a line, which is where the bracket-matching

mistakes come from.

Write a value as StrictYAML: every scalar is quoted unless it reads back as itself, because in StrictYAML there is nothing else it could be.

The one document in src, decoded as UTF-8 and read as StrictYAML.

The one document in src, read as StrictYAML.

Every document in src, read as StrictYAML.

StrictYAML has no multi-document streams — a file is a document — so this is the same as loads and exists to keep call sites that do not care about the difference working across versions.

The one document in src, decoded as UTF-8 and read with the rules it asks for.

The one document in src, read with the rules it asks for.

Every document in src, read with the rules the first of them asks for.

The schema a stream asks for.

A document that opens with %YAML 1.1 says how it wants to be read, and 1.1's rules are not 1.2's: yes is a boolean there and a string here, 014 is twelve there and fourteen here. Reading it as 1.2 would silently give the caller a different value from the one the file's author wrote, which is the one failure mode a configuration loader must not have.

No directive means 1.2, which is the current release and what a file written without a version marker means today. A directive naming a major version this library does not have is refused, rather than read with the wrong rules.