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


-- | JSON to YAML Adapter
--   
--   The <a>YAML 1.2</a> format provides a much richer data-model and
--   feature-set than the <a>JavaScript Object Notation (JSON)</a> 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 <a>HsYAML</a> which allows decoding YAML
--   documents in the more limited JSON data-model while also providing
--   convenience by reusing <a>aeson</a>'s <a>FromJSON</a> instances for
--   decoding the YAML data into native Haskell data types.
@package HsYAML-aeson
@version 0.2.0.0


-- | The <a>YAML 1.2</a> format provides a much richer data-model and
--   feature-set than the <a>JavaScript Object Notation (JSON)</a> 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 <a>Data.YAML</a> which allows decoding YAML
--   documents in the more limited JSON data-model while also providing
--   convenience by reusing <tt>aeson</tt>'s <a>FromJSON</a> instances for
--   decoding the YAML data into native Haskell data types.
module Data.YAML.Aeson

-- | Parse a single YAML document using the <a>coreSchemaResolver</a> and
--   decode to Haskell types using <a>FromJSON</a> 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 <tt>aeson</tt>'s <a>eitherDecode</a> function.
--   
--   See <a>decodeValue</a> for more information about this functions' YAML
--   decoder configuration.
--   
--   <b>NOTE</b>: In contrast to <a>FromYAML</a>-based decoding, error
--   source-locations are not available when errors occur in the
--   <a>FromJSON</a> decoding phase due to limitations of the
--   <a>FromJSON</a> class; in such cases an improper <a>Pos</a> value with
--   a negative <a>posCharOffset</a> will be returned.
decode1 :: FromJSON v => ByteString -> Either (Pos, String) v

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

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

-- | Parse YAML documents into JSON <a>Value</a> ASTs
--   
--   This is a wrapper function equivalent to
--   
--   <pre>
--   <a>decodeValue'</a> <a>coreSchemaResolver</a> identityKeyConv
--   </pre>
--   
--   with <tt>identityKeyConv</tt> being defined as
--   
--   <pre>
--   &gt; identityKeyConv :: Data.Aeson.Value -&gt; Either String Text
--   &gt; identityKeyConv (Data.Aeson.String k) = Right k
--   &gt; identityKeyConv _ = Left "non-String key encountered in YAML mapping"
--   </pre>
--   
--   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 <a>Value</a> ASTs
--   
--   YAML Anchors will be resolved and inlined accordingly. Resulting YAML
--   cycles are not supported and will be treated as a decoding error.
--   
--   <b>NOTE</b>: This decoder ignores YAML tags and relies on the YAML
--   <a>SchemaResolver</a> 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 <a>Scalar</a> into a JSON <a>Value</a>
--   
--   This conversion will return <a>Nothing</a> for <a>SUnknown</a>, i.e.
--   unresolved YAML nodes.
scalarToValue :: Scalar -> Maybe Value

-- | Serialize JSON Value using the YAML 1.2 Core schema to a lazy
--   <a>ByteString</a>.
--   
--   <a>encode1</a> emits exactly one YAML document.
--   
--   See <a>encodeValue</a> for more information about this functions' YAML
--   encoder configuration.
encode1 :: ToJSON v => v -> ByteString

-- | Like <a>encode1</a> but outputs <a>ByteString</a>
encode1Strict :: ToJSON v => v -> ByteString

-- | Dump YAML Nodes as a lazy <a>ByteString</a>
--   
--   Each YAML <a>Node</a> is emitted as a individual YAML Document where
--   each Document is terminated by a <a>DocumentEnd</a> indicator.
--   
--   This is a convenience wrapper over <a>encodeNode</a>`
encodeValue :: [Value] -> ByteString

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