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


-- | Support for parsing and rendering YAML documents.
--   
--   Please see the README.md file.
@package yaml
@version 0.8.23.1


-- | Low-level, streaming YAML interface. For a higher-level interface, see
--   <a>Data.Yaml</a>.
module Text.Libyaml
data Event
EventStreamStart :: Event
EventStreamEnd :: Event
EventDocumentStart :: Event
EventDocumentEnd :: Event
EventAlias :: !AnchorName -> Event
EventScalar :: !ByteString -> !Tag -> !Style -> !Anchor -> Event
EventSequenceStart :: !Anchor -> Event
EventSequenceEnd :: Event
EventMappingStart :: !Anchor -> Event
EventMappingEnd :: Event
data Style
Any :: Style
Plain :: Style
SingleQuoted :: Style
DoubleQuoted :: Style
Literal :: Style
Folded :: Style
PlainNoTag :: Style
data Tag
StrTag :: Tag
FloatTag :: Tag
NullTag :: Tag
BoolTag :: Tag
SetTag :: Tag
IntTag :: Tag
SeqTag :: Tag
MapTag :: Tag
UriTag :: String -> Tag
NoTag :: Tag
type AnchorName = String
type Anchor = Maybe AnchorName
encode :: MonadResource m => Consumer Event m ByteString
decode :: MonadResource m => ByteString -> Producer m Event
encodeFile :: MonadResource m => FilePath -> Consumer Event m ()
decodeFile :: MonadResource m => FilePath -> Producer m Event
data YamlException
YamlException :: String -> YamlException

-- | problem, context, index, position line, position column
YamlParseException :: String -> String -> YamlMark -> YamlException
[yamlProblem] :: YamlException -> String
[yamlContext] :: YamlException -> String
[yamlProblemMark] :: YamlException -> YamlMark

-- | The pointer position
data YamlMark
YamlMark :: Int -> Int -> Int -> YamlMark
[yamlIndex] :: YamlMark -> Int
[yamlLine] :: YamlMark -> Int
[yamlColumn] :: YamlMark -> Int
instance GHC.Show.Show Text.Libyaml.YamlException
instance GHC.Show.Show Text.Libyaml.YamlMark
instance GHC.Show.Show Text.Libyaml.ToEventRawException
instance GHC.Show.Show Text.Libyaml.EventType
instance GHC.Enum.Enum Text.Libyaml.EventType
instance GHC.Classes.Eq Text.Libyaml.Event
instance GHC.Show.Show Text.Libyaml.Event
instance Data.Data.Data Text.Libyaml.Tag
instance GHC.Read.Read Text.Libyaml.Tag
instance GHC.Classes.Eq Text.Libyaml.Tag
instance GHC.Show.Show Text.Libyaml.Tag
instance Data.Data.Data Text.Libyaml.Style
instance GHC.Classes.Ord Text.Libyaml.Style
instance GHC.Enum.Bounded Text.Libyaml.Style
instance GHC.Enum.Enum Text.Libyaml.Style
instance GHC.Classes.Eq Text.Libyaml.Style
instance GHC.Read.Read Text.Libyaml.Style
instance GHC.Show.Show Text.Libyaml.Style
instance GHC.Exception.Exception Text.Libyaml.ToEventRawException
instance GHC.Exception.Exception Text.Libyaml.YamlException


-- | NOTE: This module is a highly experimental preview release. It may
--   change drastically, or be entirely removed, in a future release.
module Data.Yaml.Parser
newtype YamlParser a
YamlParser :: (AnchorMap -> Either Text a) -> YamlParser a
[unYamlParser] :: YamlParser a -> AnchorMap -> Either Text a
lookupAnchor :: AnchorName -> YamlParser (Maybe YamlValue)
withAnchor :: AnchorName -> Text -> (YamlValue -> YamlParser a) -> YamlParser a
withMapping :: Text -> ([(Text, YamlValue)] -> YamlParser a) -> YamlValue -> YamlParser a
withSequence :: Text -> ([YamlValue] -> YamlParser a) -> YamlValue -> YamlParser a
withText :: Text -> (Text -> YamlParser a) -> YamlValue -> YamlParser a
typeMismatch :: Text -> YamlValue -> YamlParser a
class FromYaml a
fromYaml :: FromYaml a => YamlValue -> YamlParser a
data YamlValue
Mapping :: [(Text, YamlValue)] -> Anchor -> YamlValue
Sequence :: [YamlValue] -> Anchor -> YamlValue
Scalar :: ByteString -> Tag -> Style -> Anchor -> YamlValue
Alias :: AnchorName -> YamlValue
type AnchorMap = Map AnchorName YamlValue
data RawDoc
RawDoc :: YamlValue -> AnchorMap -> RawDoc
parseRawDoc :: (FromYaml a, MonadThrow m) => RawDoc -> m a
(.:) :: FromYaml a => [(Text, YamlValue)] -> Text -> YamlParser a
data YamlParseException
UnexpectedEndOfEvents :: YamlParseException
UnexpectedEvent :: Event -> YamlParseException
FromYamlException :: Text -> YamlParseException
sinkValue :: MonadThrow m => Consumer Event (WriterT AnchorMap m) YamlValue
sinkRawDoc :: MonadThrow m => Consumer Event m RawDoc
readYamlFile :: FromYaml a => FilePath -> IO a
instance GHC.Show.Show Data.Yaml.Parser.YamlParseException
instance GHC.Show.Show Data.Yaml.Parser.RawDoc
instance GHC.Show.Show Data.Yaml.Parser.YamlValue
instance GHC.Base.Functor Data.Yaml.Parser.YamlParser
instance GHC.Base.Applicative Data.Yaml.Parser.YamlParser
instance GHC.Base.Alternative Data.Yaml.Parser.YamlParser
instance GHC.Base.Monoid (Data.Yaml.Parser.YamlParser a)
instance GHC.Base.Monad Data.Yaml.Parser.YamlParser
instance GHC.Base.MonadPlus Data.Yaml.Parser.YamlParser
instance Data.Yaml.Parser.FromYaml Data.Yaml.Parser.YamlValue
instance Data.Yaml.Parser.FromYaml a => Data.Yaml.Parser.FromYaml [a]
instance Data.Yaml.Parser.FromYaml Data.Text.Internal.Text
instance Data.Yaml.Parser.FromYaml GHC.Types.Int
instance GHC.Exception.Exception Data.Yaml.Parser.YamlParseException

module Data.Yaml.Include

-- | Like <a>decodeFile</a> but with support for relative and absolute
--   includes.
--   
--   The syntax for includes follows the form:
--   
--   <pre>
--   somekey: !include ./somefile.yaml
--   </pre>
decodeFile :: FromJSON a => FilePath -> IO (Maybe a)

-- | Like <a>decodeFileEither</a> but with support for relative and
--   absolute includes.
--   
--   The syntax for includes follows the form:
--   
--   <pre>
--   somekey: !include ./somefile.yaml
--   </pre>
decodeFileEither :: FromJSON a => FilePath -> IO (Either ParseException a)


-- | NOTE: This module is a highly experimental preview release. It may
--   change drastically, or be entirely removed, in a future release.
module Data.Yaml.Builder
newtype YamlBuilder
YamlBuilder :: ([Event] -> [Event]) -> YamlBuilder
[unYamlBuilder] :: YamlBuilder -> [Event] -> [Event]
class ToYaml a
toYaml :: ToYaml a => a -> YamlBuilder
mapping :: [(Text, YamlBuilder)] -> YamlBuilder
array :: [YamlBuilder] -> YamlBuilder
string :: Text -> YamlBuilder
bool :: Bool -> YamlBuilder
null :: YamlBuilder
scientific :: Scientific -> YamlBuilder

-- | <i>Deprecated: Use scientific</i>
number :: Scientific -> YamlBuilder
toByteString :: ToYaml a => a -> ByteString
writeYamlFile :: ToYaml a => FilePath -> a -> IO ()
(.=) :: ToYaml a => Text -> a -> (Text, YamlBuilder)
instance Data.Yaml.Builder.ToYaml Data.Yaml.Builder.YamlBuilder
instance Data.Yaml.Builder.ToYaml a => Data.Yaml.Builder.ToYaml [(Data.Text.Internal.Text, a)]
instance Data.Yaml.Builder.ToYaml a => Data.Yaml.Builder.ToYaml [a]
instance Data.Yaml.Builder.ToYaml Data.Text.Internal.Text
instance Data.Yaml.Builder.ToYaml GHC.Types.Int


-- | Prettier YAML encoding.
--   
--   Since 0.8.13
module Data.Yaml.Pretty

-- | Configurable <tt>encode</tt>.
--   
--   Since 0.8.13
encodePretty :: ToJSON a => Config -> a -> ByteString

-- | Since 0.8.13
data Config

-- | Since 0.8.13
getConfCompare :: Config -> Text -> Text -> Ordering

-- | Since 0.8.13
setConfCompare :: (Text -> Text -> Ordering) -> Config -> Config

-- | The default configuration: do not sort objects.
--   
--   Since 0.8.13
defConfig :: Config


-- | Provides a high-level interface for processing YAML files.
--   
--   This module reuses most of the infrastructure from the <tt>aeson</tt>
--   package. This means that you can use all of the existing tools for
--   JSON processing for processing YAML files. As a result, much of the
--   documentation below mentions JSON; do not let that confuse you, it's
--   intentional.
--   
--   For the most part, YAML content translates directly into JSON, and
--   therefore there is very little data loss. If you need to deal with
--   YAML more directly (e.g., directly deal with aliases), you should use
--   the <a>Text.Libyaml</a> module instead.
--   
--   For documentation on the <tt>aeson</tt> types, functions, classes, and
--   operators, please see the <tt>Data.Aeson</tt> module of the
--   <tt>aeson</tt> package.
--   
--   Look in the examples directory of the source repository for some
--   initial pointers on how to use this library.
module Data.Yaml

-- | A JSON value represented as a Haskell value.
data Value :: *
Object :: ~Object -> Value
Array :: ~Array -> Value
String :: ~Text -> Value
Number :: ~Scientific -> Value
Bool :: ~Bool -> Value
Null :: Value

-- | A JSON parser.
data Parser a :: * -> *

-- | A JSON "object" (key/value map).
type Object = HashMap Text Value

-- | A JSON "array" (sequence).
type Array = Vector Value
data ParseException
NonScalarKey :: ParseException
UnknownAlias :: AnchorName -> ParseException
[_anchorName] :: ParseException -> AnchorName
UnexpectedEvent :: Maybe Event -> Maybe Event -> ParseException
[_received] :: ParseException -> Maybe Event
[_expected] :: ParseException -> Maybe Event
InvalidYaml :: (Maybe YamlException) -> ParseException
AesonException :: String -> ParseException
OtherParseException :: SomeException -> ParseException
NonStringKeyAlias :: AnchorName -> Value -> ParseException
CyclicIncludes :: ParseException

-- | Alternative to <a>show</a> to display a <a>ParseException</a> on the
--   screen. Instead of displaying the data constructors applied to their
--   arguments, a more textual output is returned. For example, instead of
--   printing:
--   
--   <pre>
--   InvalidYaml (Just (YamlParseException {yamlProblem = "did not find expected ',' or '}'", yamlContext = "while parsing a flow mapping", yamlProblemMark = YamlMark {yamlIndex = 42, yamlLine = 2, yamlColumn = 12}})))
--   </pre>
--   
--   It looks more pleasant to print:
--   
--   <pre>
--   YAML parse exception at line 2, column 12,
--   while parsing a flow mapping:
--   did not find expected ',' or '}'
--   </pre>
--   
--   Since 0.8.11
prettyPrintParseException :: ParseException -> String
data YamlException
YamlException :: String -> YamlException

-- | problem, context, index, position line, position column
YamlParseException :: String -> String -> YamlMark -> YamlException
[yamlProblem] :: YamlException -> String
[yamlContext] :: YamlException -> String
[yamlProblemMark] :: YamlException -> YamlMark

-- | The pointer position
data YamlMark
YamlMark :: Int -> Int -> Int -> YamlMark
[yamlIndex] :: YamlMark -> Int
[yamlLine] :: YamlMark -> Int
[yamlColumn] :: YamlMark -> Int

-- | Create a <a>Value</a> from a list of name/value <a>Pair</a>s. If
--   duplicate keys arise, earlier keys and their associated values win.
object :: [Pair] -> Value
array :: [Value] -> Value
(.=) :: KeyValue kv => forall v. ToJSON v => Text -> v -> kv

-- | Retrieve the value associated with the given key of an <a>Object</a>.
--   The result is <tt>empty</tt> if the key is not present or the value
--   cannot be converted to the desired type.
--   
--   This accessor is appropriate if the key and value <i>must</i> be
--   present in an object for it to be valid. If the key and value are
--   optional, use <a>.:?</a> instead.
(.:) :: FromJSON a => Object -> Text -> Parser a

-- | Retrieve the value associated with the given key of an <a>Object</a>.
--   The result is <a>Nothing</a> if the key is not present or if its value
--   is <a>Null</a>, or <tt>empty</tt> if the value cannot be converted to
--   the desired type.
--   
--   This accessor is most useful if the key and value can be absent from
--   an object without affecting its validity. If the key and value are
--   mandatory, use <a>.:</a> instead.
(.:?) :: FromJSON a => Object -> Text -> Parser (Maybe a)

-- | Helper for use in combination with <a>.:?</a> to provide default
--   values for optional JSON object fields.
--   
--   This combinator is most useful if the key and value can be absent from
--   an object without affecting its validity and we know a default value
--   to assign in that case. If the key and value are mandatory, use
--   <a>.:</a> instead.
--   
--   Example usage:
--   
--   <pre>
--   v1 &lt;- o <a>.:?</a> "opt_field_with_dfl" .!= "default_val"
--   v2 &lt;- o <a>.:</a>  "mandatory_field"
--   v3 &lt;- o <a>.:?</a> "opt_field2"
--   </pre>
(.!=) :: Parser (Maybe a) -> a -> Parser a

-- | <tt><a>withObject</a> expected f value</tt> applies <tt>f</tt> to the
--   <a>Object</a> when <tt>value</tt> is an <a>Object</a> and fails using
--   <tt><a>typeMismatch</a> expected</tt> otherwise.
withObject :: String -> (Object -> Parser a) -> Value -> Parser a

-- | <tt><a>withText</a> expected f value</tt> applies <tt>f</tt> to the
--   <a>Text</a> when <tt>value</tt> is a <a>String</a> and fails using
--   <tt><a>typeMismatch</a> expected</tt> otherwise.
withText :: String -> (Text -> Parser a) -> Value -> Parser a

-- | <tt><a>withArray</a> expected f value</tt> applies <tt>f</tt> to the
--   <a>Array</a> when <tt>value</tt> is an <a>Array</a> and fails using
--   <tt><a>typeMismatch</a> expected</tt> otherwise.
withArray :: String -> (Array -> Parser a) -> Value -> Parser a

-- | <tt><a>withScientific</a> expected f value</tt> applies <tt>f</tt> to
--   the <a>Scientific</a> number when <tt>value</tt> is a <a>Number</a>
--   and fails using <tt><a>typeMismatch</a> expected</tt> otherwise.
withScientific :: String -> (Scientific -> Parser a) -> Value -> Parser a

-- | <tt><a>withBool</a> expected f value</tt> applies <tt>f</tt> to the
--   <a>Bool</a> when <tt>value</tt> is a <a>Bool</a> and fails using
--   <tt><a>typeMismatch</a> expected</tt> otherwise.
withBool :: String -> (Bool -> Parser a) -> Value -> Parser a
parseMonad :: Monad m => (a -> Parser b) -> a -> m b

-- | Run a <a>Parser</a> with an <a>Either</a> result type. If the parse
--   fails, the <a>Left</a> payload will contain an error message.
parseEither :: (a -> Parser b) -> a -> Either String b

-- | Run a <a>Parser</a> with a <a>Maybe</a> result type.
parseMaybe :: (a -> Parser b) -> a -> Maybe b

-- | A type that can be converted to JSON.
--   
--   Instances in general <i>must</i> specify <a>toJSON</a> and
--   <i>should</i> (but don't need to) specify <a>toEncoding</a>.
--   
--   An example type and instance:
--   
--   <pre>
--   -- Allow ourselves to write <a>Text</a> literals.
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord = Coord { x :: Double, y :: Double }
--   
--   instance <a>ToJSON</a> Coord where
--     <a>toJSON</a> (Coord x y) = <a>object</a> ["x" <a>.=</a> x, "y" <a>.=</a> y]
--   
--     <a>toEncoding</a> (Coord x y) = <tt>pairs</tt> ("x" <a>.=</a> x <a>&lt;&gt;</a> "y" <a>.=</a> y)
--   </pre>
--   
--   Instead of manually writing your <a>ToJSON</a> instance, there are two
--   options to do it automatically:
--   
--   <ul>
--   <li><a>Data.Aeson.TH</a> provides Template Haskell functions which
--   will derive an instance at compile time. The generated instance is
--   optimized for your type so it will probably be more efficient than the
--   following option.</li>
--   <li>The compiler can provide a default generic implementation for
--   <a>toJSON</a>.</li>
--   </ul>
--   
--   To use the second, simply add a <tt>deriving <a>Generic</a></tt>
--   clause to your datatype and declare a <a>ToJSON</a> instance. If you
--   require nothing other than <a>defaultOptions</a>, it is sufficient to
--   write (and this is the only alternative where the default
--   <a>toJSON</a> implementation is sufficient):
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import <a>GHC.Generics</a>
--   
--   data Coord = Coord { x :: Double, y :: Double } deriving <a>Generic</a>
--   
--   instance <a>ToJSON</a> Coord where
--       <a>toEncoding</a> = <a>genericToEncoding</a> <a>defaultOptions</a>
--   </pre>
--   
--   If on the other hand you wish to customize the generic decoding, you
--   have to implement both methods:
--   
--   <pre>
--   customOptions = <a>defaultOptions</a>
--                   { <a>fieldLabelModifier</a> = <a>map</a> <a>toUpper</a>
--                   }
--   
--   instance <a>ToJSON</a> Coord where
--       <a>toJSON</a>     = <a>genericToJSON</a> customOptions
--       <a>toEncoding</a> = <a>genericToEncoding</a> customOptions
--   </pre>
--   
--   Previous versions of this library only had the <a>toJSON</a> method.
--   Adding <a>toEncoding</a> had to reasons:
--   
--   <ol>
--   <li>toEncoding is more efficient for the common case that the output
--   of <a>toJSON</a> is directly serialized to a <tt>ByteString</tt>.
--   Further, expressing either method in terms of the other would be
--   non-optimal.</li>
--   <li>The choice of defaults allows a smooth transition for existing
--   users: Existing instances that do not define <a>toEncoding</a> still
--   compile and have the correct semantics. This is ensured by making the
--   default implementation of <a>toEncoding</a> use <a>toJSON</a>. This
--   produces correct results, but since it performs an intermediate
--   conversion to a <a>Value</a>, it will be less efficient than directly
--   emitting an <a>Encoding</a>. (this also means that specifying nothing
--   more than <tt>instance ToJSON Coord</tt> would be sufficient as a
--   generically decoding instance, but there probably exists no good
--   reason to not specify <a>toEncoding</a> in new instances.)</li>
--   </ol>
class ToJSON a

-- | Convert a Haskell value to a JSON-friendly intermediate type.
toJSON :: ToJSON a => a -> Value

-- | Encode a Haskell value as JSON.
--   
--   The default implementation of this method creates an intermediate
--   <a>Value</a> using <a>toJSON</a>. This provides source-level
--   compatibility for people upgrading from older versions of this
--   library, but obviously offers no performance advantage.
--   
--   To benefit from direct encoding, you <i>must</i> provide an
--   implementation for this method. The easiest way to do so is by having
--   your types implement <a>Generic</a> using the <tt>DeriveGeneric</tt>
--   extension, and then have GHC generate a method body as follows.
--   
--   <pre>
--   instance <a>ToJSON</a> Coord where
--       <a>toEncoding</a> = <a>genericToEncoding</a> <a>defaultOptions</a>
--   </pre>
toEncoding :: ToJSON a => a -> Encoding
toJSONList :: ToJSON a => [a] -> Value
toEncodingList :: ToJSON a => [a] -> Encoding

-- | A type that can be converted from JSON, with the possibility of
--   failure.
--   
--   In many cases, you can get the compiler to generate parsing code for
--   you (see below). To begin, let's cover writing an instance by hand.
--   
--   There are various reasons a conversion could fail. For example, an
--   <a>Object</a> could be missing a required key, an <a>Array</a> could
--   be of the wrong size, or a value could be of an incompatible type.
--   
--   The basic ways to signal a failed conversion are as follows:
--   
--   <ul>
--   <li><tt>empty</tt> and <tt>mzero</tt> work, but are terse and
--   uninformative;</li>
--   <li><a>fail</a> yields a custom error message;</li>
--   <li><a>typeMismatch</a> produces an informative message for cases when
--   the value encountered is not of the expected type.</li>
--   </ul>
--   
--   An example type and instance using <a>typeMismatch</a>:
--   
--   <pre>
--   -- Allow ourselves to write <a>Text</a> literals.
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord = Coord { x :: Double, y :: Double }
--   
--   instance <a>FromJSON</a> Coord where
--       <a>parseJSON</a> (<a>Object</a> v) = Coord
--           <a>&lt;$&gt;</a> v <a>.:</a> "x"
--           <a>&lt;*&gt;</a> v <a>.:</a> "y"
--   
--       -- We do not expect a non-<a>Object</a> value here.
--       -- We could use <tt>mzero</tt> to fail, but <a>typeMismatch</a>
--       -- gives a much more informative error message.
--       <a>parseJSON</a> invalid    = <a>typeMismatch</a> "Coord" invalid
--   </pre>
--   
--   For this common case of only being concerned with a single type of
--   JSON value, the functions <a>withObject</a>, <a>withNumber</a>, etc.
--   are provided. Their use is to be preferred when possible, since they
--   are more terse. Using <a>withObject</a>, we can rewrite the above
--   instance (assuming the same language extension and data type) as:
--   
--   <pre>
--   instance <a>FromJSON</a> Coord where
--       <a>parseJSON</a> = <a>withObject</a> "Coord" $ v -&gt; Coord
--           <a>&lt;$&gt;</a> v <a>.:</a> "x"
--           <a>&lt;*&gt;</a> v <a>.:</a> "y"
--   </pre>
--   
--   Instead of manually writing your <a>FromJSON</a> instance, there are
--   two options to do it automatically:
--   
--   <ul>
--   <li><a>Data.Aeson.TH</a> provides Template Haskell functions which
--   will derive an instance at compile time. The generated instance is
--   optimized for your type so it will probably be more efficient than the
--   following option.</li>
--   <li>The compiler can provide a default generic implementation for
--   <a>parseJSON</a>.</li>
--   </ul>
--   
--   To use the second, simply add a <tt>deriving <a>Generic</a></tt>
--   clause to your datatype and declare a <a>FromJSON</a> instance for
--   your datatype without giving a definition for <a>parseJSON</a>.
--   
--   For example, the previous example can be simplified to just:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import <a>GHC.Generics</a>
--   
--   data Coord = Coord { x :: Double, y :: Double } deriving <a>Generic</a>
--   
--   instance <a>FromJSON</a> Coord
--   </pre>
--   
--   The default implementation will be equivalent to <tt>parseJSON =
--   <a>genericParseJSON</a> <a>defaultOptions</a></tt>; If you need
--   different options, you can customize the generic decoding by defining:
--   
--   <pre>
--   customOptions = <a>defaultOptions</a>
--                   { <a>fieldLabelModifier</a> = <a>map</a> <a>toUpper</a>
--                   }
--   
--   instance <a>FromJSON</a> Coord where
--       <a>parseJSON</a> = <a>genericParseJSON</a> customOptions
--   </pre>
class FromJSON a
parseJSON :: FromJSON a => Value -> Parser a
parseJSONList :: FromJSON a => Value -> Parser [a]
encode :: ToJSON a => a -> ByteString
encodeFile :: ToJSON a => FilePath -> a -> IO ()
decode :: FromJSON a => ByteString -> Maybe a
decodeFile :: FromJSON a => FilePath -> IO (Maybe a)
decodeEither :: FromJSON a => ByteString -> Either String a

-- | More helpful version of <a>decodeEither</a> which returns the
--   <a>YamlException</a>.
--   
--   Since 0.8.3
decodeEither' :: FromJSON a => ByteString -> Either ParseException a

-- | A version of <a>decodeFile</a> which should not throw runtime
--   exceptions.
--   
--   Since 0.8.4
decodeFileEither :: FromJSON a => FilePath -> IO (Either ParseException a)
decodeHelper :: FromJSON a => Source Parse Event -> IO (Either ParseException (Either String a))


-- | Just a re-export of <tt>Data.Yaml</tt>. In the future, this will be
--   the canonical name for that module's contents.
module Data.Yaml.Aeson


-- | Functionality for using YAML as configuration files
--   
--   In particular, merging environment variables with yaml values
--   
--   <a>loadYamlSettings</a> is a high-level API for loading YAML and
--   merging environment variables. A yaml value of
--   <tt>_env:ENV_VAR:default</tt> will lookup the environment variable
--   <tt>ENV_VAR</tt>.
--   
--   On a historical note, this code was taken directly from the yesod web
--   framework's configuration module.
module Data.Yaml.Config

-- | Load the settings from the following three sources:
--   
--   <ul>
--   <li>Run time config files</li>
--   <li>Run time environment variables</li>
--   <li>The default compile time config file</li>
--   </ul>
--   
--   For example, to load up settings from <tt>config/foo.yaml</tt> and
--   allow overriding from the actual environment, you can use:
--   
--   <pre>
--   loadYamlSettings ["config/foo.yaml"] [] useEnv
--   </pre>
loadYamlSettings :: FromJSON settings => [FilePath] -> [Value] -> EnvUsage -> IO settings

-- | Same as <tt>loadYamlSettings</tt>, but get the list of runtime config
--   files from the command line arguments.
loadYamlSettingsArgs :: FromJSON settings => [Value] -> EnvUsage -> IO settings

-- | Defines how we want to use the environment variables when loading a
--   config file. Use the smart constructors provided by this module.
data EnvUsage

-- | Do not use any environment variables, instead relying on defaults
--   values in the config file.
ignoreEnv :: EnvUsage

-- | Use environment variables when available, otherwise use defaults.
useEnv :: EnvUsage

-- | Do not use default values from the config file, but instead take all
--   overrides from the environment. If a value is missing, loading the
--   file will throw an exception.
requireEnv :: EnvUsage

-- | Same as <a>useEnv</a>, but instead of the actual environment, use the
--   provided <tt>HashMap</tt> as the environment.
useCustomEnv :: HashMap Text Text -> EnvUsage

-- | Same as <a>requireEnv</a>, but instead of the actual environment, use
--   the provided <tt>HashMap</tt> as the environment.
requireCustomEnv :: HashMap Text Text -> EnvUsage

-- | A convenience wrapper around <a>applyEnvValue</a> and
--   <a>getCurrentEnv</a>
applyCurrentEnv :: Bool -> Value -> IO Value

-- | Get the actual environment as a <tt>HashMap</tt> from <tt>Text</tt> to
--   <tt>Text</tt>.
getCurrentEnv :: IO (HashMap Text Text)

-- | Override environment variable placeholders in the given <tt>Value</tt>
--   with values from the environment.
--   
--   If the first argument is <tt>True</tt>, then all placeholders _must_
--   be provided by the actual environment. Otherwise, default values from
--   the <tt>Value</tt> will be used.
applyEnvValue :: Bool -> HashMap Text Text -> Value -> Value
instance Data.Semigroup.Semigroup Data.Yaml.Config.MergedValue

module Data.Yaml.TH

-- | Decode a <tt>yaml</tt> file at compile time. Only available on GHC
--   version <tt>7.8.1</tt> or higher.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   {-# LANGUAGE TemplateHaskell #-}
--   
--   config :: Config
--   config = $$(<a>decodeFile</a> "config.yaml")
--   </pre>
decodeFile :: forall a. (Lift a, FromJSON a) => FilePath -> Q (TExp a)

-- | A JSON value represented as a Haskell value.
data Value :: *
Object :: ~Object -> Value
Array :: ~Array -> Value
String :: ~Text -> Value
Number :: ~Scientific -> Value
Bool :: ~Bool -> Value
Null :: Value

-- | A JSON parser.
data Parser a :: * -> *

-- | A JSON "object" (key/value map).
type Object = HashMap Text Value

-- | A JSON "array" (sequence).
type Array = Vector Value

-- | Create a <a>Value</a> from a list of name/value <a>Pair</a>s. If
--   duplicate keys arise, earlier keys and their associated values win.
object :: [Pair] -> Value
array :: [Value] -> Value
(.=) :: KeyValue kv => forall v. ToJSON v => Text -> v -> kv

-- | Retrieve the value associated with the given key of an <a>Object</a>.
--   The result is <tt>empty</tt> if the key is not present or the value
--   cannot be converted to the desired type.
--   
--   This accessor is appropriate if the key and value <i>must</i> be
--   present in an object for it to be valid. If the key and value are
--   optional, use <a>.:?</a> instead.
(.:) :: FromJSON a => Object -> Text -> Parser a

-- | Retrieve the value associated with the given key of an <a>Object</a>.
--   The result is <a>Nothing</a> if the key is not present or if its value
--   is <a>Null</a>, or <tt>empty</tt> if the value cannot be converted to
--   the desired type.
--   
--   This accessor is most useful if the key and value can be absent from
--   an object without affecting its validity. If the key and value are
--   mandatory, use <a>.:</a> instead.
(.:?) :: FromJSON a => Object -> Text -> Parser (Maybe a)

-- | Helper for use in combination with <a>.:?</a> to provide default
--   values for optional JSON object fields.
--   
--   This combinator is most useful if the key and value can be absent from
--   an object without affecting its validity and we know a default value
--   to assign in that case. If the key and value are mandatory, use
--   <a>.:</a> instead.
--   
--   Example usage:
--   
--   <pre>
--   v1 &lt;- o <a>.:?</a> "opt_field_with_dfl" .!= "default_val"
--   v2 &lt;- o <a>.:</a>  "mandatory_field"
--   v3 &lt;- o <a>.:?</a> "opt_field2"
--   </pre>
(.!=) :: Parser (Maybe a) -> a -> Parser a

-- | A type that can be converted from JSON, with the possibility of
--   failure.
--   
--   In many cases, you can get the compiler to generate parsing code for
--   you (see below). To begin, let's cover writing an instance by hand.
--   
--   There are various reasons a conversion could fail. For example, an
--   <a>Object</a> could be missing a required key, an <a>Array</a> could
--   be of the wrong size, or a value could be of an incompatible type.
--   
--   The basic ways to signal a failed conversion are as follows:
--   
--   <ul>
--   <li><tt>empty</tt> and <tt>mzero</tt> work, but are terse and
--   uninformative;</li>
--   <li><a>fail</a> yields a custom error message;</li>
--   <li><a>typeMismatch</a> produces an informative message for cases when
--   the value encountered is not of the expected type.</li>
--   </ul>
--   
--   An example type and instance using <a>typeMismatch</a>:
--   
--   <pre>
--   -- Allow ourselves to write <a>Text</a> literals.
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord = Coord { x :: Double, y :: Double }
--   
--   instance <a>FromJSON</a> Coord where
--       <a>parseJSON</a> (<a>Object</a> v) = Coord
--           <a>&lt;$&gt;</a> v <a>.:</a> "x"
--           <a>&lt;*&gt;</a> v <a>.:</a> "y"
--   
--       -- We do not expect a non-<a>Object</a> value here.
--       -- We could use <tt>mzero</tt> to fail, but <a>typeMismatch</a>
--       -- gives a much more informative error message.
--       <a>parseJSON</a> invalid    = <a>typeMismatch</a> "Coord" invalid
--   </pre>
--   
--   For this common case of only being concerned with a single type of
--   JSON value, the functions <a>withObject</a>, <a>withNumber</a>, etc.
--   are provided. Their use is to be preferred when possible, since they
--   are more terse. Using <a>withObject</a>, we can rewrite the above
--   instance (assuming the same language extension and data type) as:
--   
--   <pre>
--   instance <a>FromJSON</a> Coord where
--       <a>parseJSON</a> = <a>withObject</a> "Coord" $ v -&gt; Coord
--           <a>&lt;$&gt;</a> v <a>.:</a> "x"
--           <a>&lt;*&gt;</a> v <a>.:</a> "y"
--   </pre>
--   
--   Instead of manually writing your <a>FromJSON</a> instance, there are
--   two options to do it automatically:
--   
--   <ul>
--   <li><a>Data.Aeson.TH</a> provides Template Haskell functions which
--   will derive an instance at compile time. The generated instance is
--   optimized for your type so it will probably be more efficient than the
--   following option.</li>
--   <li>The compiler can provide a default generic implementation for
--   <a>parseJSON</a>.</li>
--   </ul>
--   
--   To use the second, simply add a <tt>deriving <a>Generic</a></tt>
--   clause to your datatype and declare a <a>FromJSON</a> instance for
--   your datatype without giving a definition for <a>parseJSON</a>.
--   
--   For example, the previous example can be simplified to just:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import <a>GHC.Generics</a>
--   
--   data Coord = Coord { x :: Double, y :: Double } deriving <a>Generic</a>
--   
--   instance <a>FromJSON</a> Coord
--   </pre>
--   
--   The default implementation will be equivalent to <tt>parseJSON =
--   <a>genericParseJSON</a> <a>defaultOptions</a></tt>; If you need
--   different options, you can customize the generic decoding by defining:
--   
--   <pre>
--   customOptions = <a>defaultOptions</a>
--                   { <a>fieldLabelModifier</a> = <a>map</a> <a>toUpper</a>
--                   }
--   
--   instance <a>FromJSON</a> Coord where
--       <a>parseJSON</a> = <a>genericParseJSON</a> customOptions
--   </pre>
class FromJSON a
parseJSON :: FromJSON a => Value -> Parser a
parseJSONList :: FromJSON a => Value -> Parser [a]
