A document of a YAML stream.

The version of YAML that a document declares.

A document with the given root, without directives, markers and comments.

A node of a document.

The content of a node.

The properties of a node.

No anchor and no tag.

The tag of a node after the tag handles are expanded.

The style of a scalar: without quotes, in single or double quotes, or a literal (|) or folded (>) block scalar.

The literal or the folded style.

The style of a collection: with indentation, or with brackets and commas.

A node with the given content, without properties and comments.

A scalar in the given style. renderSyntax uses quotes if the style cannot hold the text, and for a block scalar that is a key or an entry of a flow collection.

>>> T.putStr (renderSyntax defaultRenderOptions [document (mappingNode [(plainNode "key", scalarNode Plain "a: b")])])
key: 'a: b'

A plain scalar.

A block sequence.

A block mapping.

The comments and the empty lines that belong to a node.

No comments and no empty lines.

The node with the comments in place of its own. A record update of the field is ambiguous where Commented is in scope.

A value with the comments of its mapping entry:

• before: the lines above the entry,
• inline: the comment at the end of the line of the key, or of the line where a value on several lines ends,
• after: the lines after the value, e.g. after the last entry of a collection.

A Commented value of a mapping entry has the comments of the entry. A block list or mapping under the key has its own comments: the lines below the key up to the last empty line above its first entry. A Commented value inside the first one keeps them, so a type that keeps both nests two Commented values:

>>> input = "# The CI jobs.\njobs:\n  # Run on every push.\n\n  # Check the formatting.\n  - lint\n"

>>> T.putStr input
# The CI jobs.
jobs:
  # Run on every push.

  # Check the formatting.
  - lint

>>> Right entries = decodeText @(M.Map T.Text (Commented (Commented [Commented T.Text]))) input
>>> Just jobs = M.lookup "jobs" entries

>>> jobs.comments
Comments {before = [Comment "The CI jobs."], inline = Nothing, after = []}

>>> jobs.value.comments
Comments {before = [Comment "Run on every push.",EmptyLine], inline = Nothing, after = []}

>>> map (.comments) jobs.value.value
[Comments {before = [Comment "Check the formatting."], inline = Nothing, after = []}]

A value without a key, e.g. an item of a list, has the comments of its node. The comments of a list or a mapping stay with it, not with its first item or key: the lines up to the last empty line above its first entry, and the comment on its first line, e.g. after its tag. A Commented value of the whole list or mapping keeps them.

By the rules in Comments, some lines read back with a change:

• The lines after a text of several lines, which the encoder writes as a block scalar, read back as the lines above the next entry. After the last entry, they belong to the end of the collection around the entry.
• The lines above a list or a mapping without a key can get an empty line below them, e.g. at the top level. The empty line reads back as the last of these lines.
• The lines above the first item of a list or the first key of a mapping that end with an empty line read back as the lines of the list or the mapping. A Commented list or mapping keeps them. Under a key, the inner of two nested Commented values keeps them, as above. Otherwise they are lost.

A comment is lost if its node has no place for it, i.e. if the node does not decode into a node or a Commented value:

• the comments of a key without a Haskell field, e.g. the tag of a constructor;
• a comment at the end of a nested mapping, unless the field that holds the mapping is Commented, because a record has no place for the end of its mapping;
• the comments of a record's mapping above its first key, e.g. a comment at the top of a file above an empty line;
• the comments of the key for a type such as data Name = Name (Commented Text) that derives its instances through Generic, because a derived instance for one constructor with one field without a name does not give the key of its entry to the value inside. Declare such a type as a newtype and derive its instances with deriving newtype, which gives the key to the value.

In a map, use Commented on the key or on the value, not on both. With both, the decoder gives the comments of the key to both, and the encoder writes only those of the value, so a change to the comments of the key is lost.

A change of the value keeps the comments:

>>> input = "# The port.\nport: 80 # the default\n"

>>> :{
either printErrors (T.putStr . encodeText . M.map (fmap (+ 1))) $
  decodeText @(M.Map T.Text (Commented Int)) input
:}
# The port.
port: 81 # the default

The order compares the values first and then the comments, e.g. in a set.

A line of comments.

The offset of a byte in the input text, in its UTF-8 encoding. For an input in UTF-16 or UTF-32, the offset counts the bytes of the text after decodeInput, not the bytes of the input.

The offset of a node that does not come from an input.

A value with the offset of its node, e.g. for the error of a check that runs after the decode. The encoder writes only the value.

documentErrors turns the offsets into errors with lines, columns and paths. It needs the text and the document of the decode, so decode with decodeWithDocument. Here the check gives an offset and a message for each problem:

>>> input = "paths:\n- src\n- /etc\n"

>>> :{
case decodeWithDocument @(M.Map T.Text [Located T.Text]) input of
  Right (config, doc) ->
    let errs =
          [ (p.offset, "the path is outside the repository")
          | p <- concat (M.elems config)
          , "/" `T.isPrefixOf` p.value
          ]
    in printErrors (documentErrors input doc errs)
  Left errs -> printErrors errs
:}
input.yaml:3:3: paths[1]: the path is outside the repository
  |
3 | - /etc
  |   ^

A value that no node gives, e.g. a value of yamlDefault, has noOffset. Its error has no position, and prettyError prints only the file and the message. A value inside an alias has the offset of the alias, i.e. of the place where the document uses the value.

Two equal values at different places are not equal as Located values, e.g. a set keeps both. The equality and the order compare the values first and then the offsets. To compare only the values, e.g. in a test, use the field value.

Copy every text of a document, so that the document does not keep the input alive.

Copy every text of a node, so that the node does not keep the input alive.