HsYAML-aeson-0.2.0.1: JSON to YAML Adapter
Copyright© Herbert Valerio Riedel 2015-2018
LicenseGPL-2.0-or-later
Safe HaskellTrustworthy
LanguageHaskell2010

Data.YAML.Aeson

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

Parsing YAML using JSON models

High-level parsing/decoding via FromJSON instances

decode1 :: FromJSON v => ByteString -> Either (Pos, 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.

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 Source #

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

Since: 0.2.0

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

Like decode1 but takes a strict ByteString

Since: 0.2.0

Parsing into JSON AST (Value)

decodeValue :: ByteString -> Either (Pos, 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).

Since: 0.2.0

decodeValue' Source #

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 Source #

Convert a YAML Scalar into a JSON Value

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

Encoding/Dumping

encode1 :: ToJSON v => v -> ByteString Source #

Serialize JSON Value using the YAML 1.2 Core schema to a lazy ByteString.

encode1 emits exactly one YAML document.

See encodeValue for more information about this functions' YAML encoder configuration.

Since: 0.2.0

encode1Strict :: ToJSON v => v -> ByteString Source #

Like encode1 but outputs ByteString

Since: 0.2.0

encodeValue :: [Value] -> ByteString Source #

Dump YAML Nodes as a lazy 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

encodeValue' :: SchemaEncoder -> Encoding -> [Value] -> ByteString Source #

Customizable variant of encodeNode

Since: 0.2.0

Orphan instances

ToYAML Value Source #

Since: 0.2.0

Instance details

Methods

toYAML :: Value -> Node ()