Data.YAML.Aeson

HsYAML-aeson-0.2.0.1: JSON to YAML Adapter

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
  - High-level parsing/decoding via `FromJSON` instances
  - Parsing into JSON AST (`Value`)
  - Encoding/Dumping
- 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.

## Encoding/Dumping

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

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 #

Like `encode1` but outputs `ByteString`

Since: 0.2.0

encodeValue :: [Value] -> ByteString #

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 #

Customizable variant of `encodeNode`

Since: 0.2.0

# Orphan instances

ToYAML Value # | Since: 0.2.0
Instance details Methods toYAML :: Value -> Node () #