Decode YAML document(s) using the YAML 1.2 Core schema

Each document contained in the YAML stream produce one element of the response list. Here's an example of decoding two concatenated YAML documents:

>>> decode "Foo\n---\nBar" :: Either (Pos,String) [Text]
Right ["Foo","Bar"]

Note that an empty stream doesn't contain any (non-comment) document nodes, and therefore results in an empty result list:

>>> decode "# just a comment" :: Either (Pos,String) [Text]
Right []

decode uses the same settings as decodeNode for tag-resolving. If you need a different custom parsing configuration, you need to combine parseEither and decodeNode` yourself.

The decode as well as the decodeNode functions supports decoding from YAML streams using the UTF-8, UTF-16 (LE or BE), or UTF-32 (LE or BE) encoding (which is auto-detected).

Since: 0.2.0

Convenience wrapper over decode expecting exactly one YAML document

>>> decode1 "---\nBar\n..." :: Either (Pos,String) Text
Right "Bar"

>>> decode1 "Foo\n---\nBar" :: Either (Pos,String) Text
Left (Pos {posByteOffset = 8, posCharOffset = 8, posLine = 3, posColumn = 0},"unexpected multiple YAML documents")

>>> decode1 "# Just a comment" :: Either (Pos,String) Text
Left (Pos {posByteOffset = 0, posCharOffset = 0, posLine = 1, posColumn = 0},"empty YAML stream")

Since: 0.2.0

Like decode but takes a strict ByteString

Since: 0.2.0

Like decode1 but takes a strict ByteString

Since: 0.2.0

A type into which YAML nodes can be converted/deserialized

YAML Parser Monad used by FromYAML

See also parseEither or decode

Run Parser

A common use-case is parseEither parseYAML.

Trigger parsing failure located at a specific Node

Since: 0.2.0.0

Informative failure helper

This is typically used in fall-through cases of parseYAML like so

instance FromYAML ... where
  parseYAML ...  = ...
  parseYAML node = typeMismatch "SomeThing" node

Since: 0.1.1.0

YAML mapping

Retrieve value in Mapping indexed by a !!str Text key.

This parser fails if the key doesn't exist.

Retrieve optional value in Mapping indexed by a !!str Text key.

Nothing is returned if the key is missing or points to a tag:yaml.org,2002:null node. This combinator only fails if the key exists but cannot be converted to the required type.

See also .:!.

Retrieve optional value in Mapping indexed by a !!str Text key.

Nothing is returned if the key is missing. This combinator only fails if the key exists but cannot be converted to the required type.

NOTE: This is a variant of .:? which doesn't map a tag:yaml.org,2002:null node to Nothing.

Defaulting helper to be used with .:? or .:!.

Serialize YAML Node(s) using the YAML 1.2 Core schema to a lazy UTF8 encoded ByteString.

Each YAML Node produces exactly one YAML Document.

Here is an example of encoding a list of strings to produce a list of YAML Documents

>>> encode (["Document 1", "Document 2"] :: [Text])
"Document 1\n...\nDocument 2\n"

If we treat the above list of strings as a single sequence then we will produce a single YAML Document having a single sequence.

>>> encode ([["Document 1", "Document 2"]] :: [[Text]])
"- Document 1\n- Document 2\n"

Alternatively, if you only need a single YAML document in a YAML stream you might want to use the convenience function encode1; or, if you need more control over the encoding, see encodeNode'.

Since: 0.2.0

Convenience wrapper over encode taking exactly one YAML Node. Hence it will always output exactly one YAML Document

Here is example of encoding a list of strings to produce exactly one of YAML Documents

>>> encode1 (["Document 1", "Document 2"] :: [Text])
"- Document 1\n- Document 2\n"

Since: 0.2.0

Like encode but outputs ByteString

Since: 0.2.0

Like encode1 but outputs a strict ByteString

Since: 0.2.0

A type from which YAML nodes can be constructed

Since: 0.2.0.0

Represents a key-value pair in YAML Mappings

See also .= and mapping

Since: 0.2.1

Since: 0.2.0

Since: 0.2.0

Operate on Scalar node (or fail)

Since: 0.2.1

Operate on tag:yaml.org,2002:seq node (or fail)

Operate on tag:yaml.org,2002:bool node (or fail)

Operate on tag:yaml.org,2002:float node (or fail)

Operate on tag:yaml.org,2002:int node (or fail)

Operate on tag:yaml.org,2002:null node (or fail)

Operate on tag:yaml.org,2002:str node (or fail)

Operate on tag:yaml.org,2002:map node (or fail)

Parse and decode YAML document(s) into Node graphs

This is a convenience wrapper over decodeNode`, i.e.

decodeNode = decodeNode' coreSchemaResolver False False

In other words,

• Use the YAML 1.2 Core schema for resolving
• Don't create Anchor nodes
• Disallow cyclic anchor references

Since: 0.2.0

Customizable variant of decodeNode

Since: 0.2.0

Dump YAML Nodes as a lazy UTF8 encoded ByteString

Each YAML Node is emitted as a individual YAML Document where each Document is terminated by a DocumentEnd indicator.

This is a convenience wrapper over encodeNode`

Since: 0.2.0

Customizable variant of encodeNode

NOTE: A leading BOM will be emitted for all encodings other than UTF8.

Since: 0.2.0

YAML Document tree/graph

NOTE: In future versions of this API meta-data about the YAML document might be included as additional fields inside Doc

YAML Document node

Since: 0.2.0

Primitive scalar types as defined in YAML 1.2

Position in parsed YAML source

See also prettyPosWithSource.

NOTE: if posCharOffset is negative the Pos value doesn't refer to a proper location; this may be emitted in corner cases when no proper location can be inferred.

Pretty prints a Pos together with the line the Pos refers and the column position.

The input ByteString must be the same that was passed to the YAML decoding function that produced the Pos value. The String argument is inserted right after the line:column: in the first line. The pretty-printed position result String will be terminated by a trailing newline.

For instance,

prettyPosWithSource somePos someInput " error" ++ "unexpected character\n"

results in

11:7: error
    |
 11 | foo: | bar
    |        ^
unexpected character

Since: 0.2.1

Definition of a YAML 1.2 Schema

A YAML schema defines how implicit tags are resolved to concrete tags and how data is represented textually in YAML.

"Failsafe" schema resolver as specified in YAML 1.2 / 10.1.2. Tag Resolution

Strict JSON schema resolver as specified in YAML 1.2 / 10.2.2. Tag Resolution

Core schema resolver as specified in YAML 1.2 / 10.3.2. Tag Resolution

Since: 0.2.0

"Failsafe" schema encoder as specified in YAML 1.2 / 10.1.2. Tag Resolution

Since: 0.2.0

Strict JSON schema encoder as specified in YAML 1.2 / 10.2.2. Tag Resolution

Since: 0.2.0

Core schema encoder as specified in YAML 1.2 / 10.3.2. Tag Resolution

Since: 0.2.0

Generalised document tree/graph construction

This doesn't yet perform any tag resolution (thus all scalars are represented as Text values). See also decodeNode for a more convenient interface.

Since: 0.2.0

Structure defining how to construct a document tree/graph

Since: 0.2.0

Helper type for Loader

Since: 0.2.0

Unique identifier for identifying nodes

This is allows to observe the alias/anchor-reference structure