HsYAML-aeson- JSON to YAML Adapter

Copyright© Herbert Valerio Riedel 2015-2018
Safe HaskellTrustworthy




The YAML 1.2 format provides a much richer data-model and feature-set than the JavaScript Object Notation (JSON) format. However, sometimes it's desirable to ignore the extra capabilities and treat YAML as if it was merely a more convenient markup format for humans to write JSON data. To this end this module provides a compatibility layer atop Data.YAML which allows decoding YAML documents in the more limited JSON data-model while also providing convenience by reusing aeson's FromJSON instances for decoding the YAML data into native Haskell data types.


Parsing YAML using JSON models

High-level parsing/decoding via FromJSON instances

decode1 :: FromJSON v => ByteString -> Either String v Source #

Parse a single YAML document using the coreSchemaResolver and decode to Haskell types using FromJSON instances.

This operation will fail if the YAML stream does not contain exactly one YAML document. This operation is designed to be the moral equivalent of aeson's eitherDecode function.

See decodeValue for more information about this functions' YAML decoder configuration.

decode1' :: FromJSON v => SchemaResolver -> (Value -> Either String Text) -> ByteString -> Either String v Source #

Variant of decode1 allowing for customization. See decodeValue' for documentation of parameters.

Parsing into JSON AST (Value)

decodeValue :: ByteString -> Either String [Value] Source #

Parse YAML documents into JSON Value ASTs

This is a wrapper function equivalent to

decodeValue' coreSchemaResolver identityKeyConv

with identityKeyConv being defined as

> identityKeyConv :: Data.Aeson.Value -> Either String Text
> identityKeyConv (Data.Aeson.String k) = Right k
> identityKeyConv _ = Left "non-String key encountered in YAML mapping"

which performs no conversion and will fail when encountering YAML Scalars that have not been resolved to a text Scalar (according to the respective YAML schema resolver).

decodeValue' Source #


:: SchemaResolver

YAML Schema resolver to use

-> (Value -> Either String Text)

JSON object key conversion function. This operates on the YAML node as resolved by the SchemaResolver and subsequently converted into a JSON Value according to the scalarToValue conversion. See decodeValue documentation for an example.

-> ByteString

YAML document to parse

-> Either String [Value] 

Parse YAML documents into JSON Value ASTs

YAML Anchors will be resolved and inlined accordingly. Resulting YAML cycles are not supported and will be treated as a decoding error.

NOTE: This decoder ignores YAML tags and relies on the YAML SchemaResolver provided to ensure that scalars have been resolved to the proper known core YAML types.

scalarToValue :: Scalar -> Maybe Value Source #

Convert a YAML Scalar into a JSON Value

This conversion will return Nothing for SUnknown, i.e. unresolved YAML nodes.