-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/

-- | JSON to YAML Adapter
--   
--   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 HsYAML 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.
@package HsYAML-aeson
@version 0.2.0.0

-- | 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.
module Data.YAML.Aeson

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

-- | Variant of decode1 allowing for customization. See
--   decodeValue' for documentation of parameters.
decode1' :: FromJSON v => SchemaResolver -> (Value -> Either String Text) -> ByteString -> Either (Pos, String) v

-- | Like decode1 but takes a strict ByteString
decode1Strict :: FromJSON v => ByteString -> Either (Pos, String) v

-- | 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 :: ByteString -> 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.
decodeValue' :: SchemaResolver -> (Value -> Either String Text) -> ByteString -> Either (Pos, String) [Value]

-- | Convert a YAML Scalar into a JSON Value
--   
--   This conversion will return Nothing for SUnknown, i.e.
--   unresolved YAML nodes.
scalarToValue :: Scalar -> Maybe Value

-- | 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.
encode1 :: ToJSON v => v -> ByteString

-- | Like encode1 but outputs ByteString
encode1Strict :: ToJSON v => v -> 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`
encodeValue :: [Value] -> ByteString

-- | Customizable variant of encodeNode
encodeValue' :: SchemaEncoder -> Encoding -> [Value] -> ByteString
instance Data.YAML.ToYAML Data.Aeson.Types.Internal.Value
