Copyright	© Herbert Valerio Riedel 2015-2018
License	GPL-2.0-or-later
Safe Haskell	Trustworthy
Language	Haskell2010

Data.YAML.Aeson

Contents

Parsing YAML using JSON models
Orphan instances

Description

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.

Synopsis

decode1 :: FromJSON v => ByteString -> Either (Pos, String) v
decode1' :: FromJSON v => SchemaResolver -> (Value -> Either String Text) -> ByteString -> Either (Pos, String) v
decode1Strict :: FromJSON v => ByteString -> Either (Pos, String) v
decodeValue :: ByteString -> Either (Pos, String) [Value]
decodeValue' :: SchemaResolver -> (Value -> Either String Text) -> ByteString -> Either (Pos, String) [Value]
scalarToValue :: Scalar -> Maybe Value
encode1 :: ToJSON v => v -> ByteString
encode1Strict :: ToJSON v => v -> ByteString
encodeValue :: [Value] -> ByteString
encodeValue' :: SchemaEncoder -> Encoding -> [Value] -> ByteString

Parsing YAML using JSON models

High-level parsing/decoding via `FromJSON` instances

decode1 :: FromJSON v => ByteString -> Either (Pos, String) v #

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.

NOTE: In contrast to FromYAML-based decoding, error source-locations are not available when errors occur in the FromJSON decoding phase due to limitations of the FromJSON class; in such cases an improper Pos value with a negative posCharOffset will be returned.

Since: 0.2.0

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

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

Since: 0.2.0

decode1Strict :: FromJSON v => ByteString -> Either (Pos, String) v #

Like decode1 but takes a strict ByteString

Since: 0.2.0

Parsing into JSON AST (`Value`)

decodeValue :: ByteString -> Either (Pos, String) [Value] #

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).

Since: 0.2.0

decodeValue' #

Arguments

:: 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 (Pos, 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.

Since: 0.2.0

scalarToValue :: Scalar -> Maybe Value #

Convert a YAML Scalar into a JSON Value

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