Decode a stream with one document. An empty stream is null.

If the input has a syntax error or fails a check that decodeDocument describes, the result has only that error, with its notes, e.g. the first key of a duplicate key. Otherwise the result has every error that the Parser collects, in the order of their positions.

>>> decode @[Int] "- 1\n- 2\n"
Right [1,2]

>>> decode @(Maybe Int) ""
Right Nothing

>>> either printErrors print (decode @[Int] "- 1\n- x\n- true\n")
input.yaml:2:3: [1]: expected an integer, but got a string
  |
2 | - x
  |   ^
input.yaml:3:3: [2]: expected an integer, but got a boolean
  |
3 | - true
  |   ^

Decode every document of a stream. The errors are as for decode, from the first document that fails. The parser reads the whole stream first, so a syntax error in any document comes before the errors of the others.

>>> decodeAll @Int "1\n---\n2\n"
Right [1,2]

Decode a stream with one document. An empty stream is null. The errors are as for decode.

>>> decodeText @Value "ports: [80, 443]\nenabled: yes\n"
Right (Mapping [(String "ports",Sequence [Int 80,Int 443]),(String "enabled",String "yes")])

Decode every document of a stream. The errors are as for decodeAll.

Decode the bytes of a stream to text. The encoding is UTF-8, UTF-16 or UTF-32, detected as the YAML specification describes.

Decode the file as decode does. The file is read as bytes, so the encoding does not depend on the locale. It is UTF-8, UTF-16 or UTF-32, detected as the YAML specification describes.

For the errors, give the same path to prettyError:

decodeFile @Config path >>= \case
  Left errs -> mapM_ (putStrLn . prettyError path) errs
  Right config -> ...

Decode every document of the file as decodeAll does, with the encoding of decodeFile.

Decode a stream with one document as decodeText does, and give the document too, e.g. for documentErrors or to write the file back with its comments. An empty stream is a document with null. A stream of only comments is empty too, so the document does not keep them, as the section Comments says.

Decode a document of a syntax tree, e.g. to read the values of a file and keep its comments from one parse.

As for a parsed input, the decoder checks the document first. The check fails for:

• a duplicate key,
• an undefined alias,
• an alias inside the node that it refers to, e.g. &a [*a],
• aliases beyond the limit in Yamlet.Value,
• a value that is not valid for its tag,
• a float whose exponent in scientific notation is beyond the range from -1000 to 1000.

The text is the input of the document. An error takes its line from the text. For a document that the program built, the text can be empty. If such a document contains the nodes of a parsed input, pass that input, so that their errors get their lines. The errors are as for decode.

The document has the limit of the aliases to itself. For the documents of a stream, use decodeDocuments, so that they share the limit.

Decode the documents of a syntax tree as decodeDocument does, e.g. the documents of a stream from parseDocumentsText. The documents share the limit of the aliases, as the documents of a stream do. The errors are as for decodeAll.

Encode a value as a document.

>>> encode [1, 2 :: Int]
"- 1\n- 2\n"

Encode values as a stream of documents.

Encode a value as a document.

>>> T.putStr (encodeText (mapping ["name" .= ("app" :: T.Text), "ports" .= [80, 443 :: Int]]))
name: app
ports:
- 80
- 443

Encode values as a stream of documents.

>>> T.putStr (encodeAllText [1, 2 :: Int])
1
---
2

Encode a value as a document in the file, in UTF-8. The file is written as bytes, so the encoding does not depend on the locale.

Encode values as a stream of documents in the file, as encodeFile does.

A node of a document.

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.

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.

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

No comments and no empty lines.

A line of comments.