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


-- | Support for parsing and rendering YAML documents.
--   
--   README and API documentation are available at
--   <a>https://www.stackage.org/package/yaml</a>
@package yaml
@version 0.11.0.0

module Data.Yaml.Internal
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 Warning
DuplicateKey :: JSONPath -> Warning
parse :: ReaderT JSONPath (ConduitM Event o Parse) Value
decodeHelper :: FromJSON a => ConduitM () Event Parse () -> IO (Either ParseException ([Warning], Either String a))
decodeHelper_ :: FromJSON a => ConduitM () Event Parse () -> IO (Either ParseException ([Warning], a))

-- | Strings which must be escaped so as not to be treated as non-string
--   scalars.
specialStrings :: HashSet Text
isNumeric :: Text -> Bool
textToScientific :: Text -> Either String Scientific
instance GHC.Show.Show Data.Yaml.Internal.Warning
instance GHC.Classes.Eq Data.Yaml.Internal.Warning
instance GHC.Show.Show Data.Yaml.Internal.ParseException
instance GHC.Exception.Exception Data.Yaml.Internal.ParseException

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)

-- | A version of <a>decodeFileEither</a> that returns warnings along with
--   the parse result.
decodeFileWithWarnings :: FromJSON a => FilePath -> IO (Either ParseException ([Warning], 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

namedMapping :: Text -> [(Text, YamlBuilder)] -> YamlBuilder

maybeNamedMapping :: Maybe Text -> [(Text, YamlBuilder)] -> YamlBuilder
array :: [YamlBuilder] -> YamlBuilder

namedArray :: Text -> [YamlBuilder] -> YamlBuilder

maybeNamedArray :: Maybe Text -> [YamlBuilder] -> YamlBuilder
string :: Text -> YamlBuilder

namedString :: Text -> Text -> YamlBuilder

maybeNamedString :: Maybe Text -> Text -> YamlBuilder
bool :: Bool -> YamlBuilder

namedBool :: Text -> Bool -> YamlBuilder

maybeNamedBool :: Maybe Text -> Bool -> YamlBuilder
null :: YamlBuilder

namedNull :: Text -> YamlBuilder

maybeNamedNull :: Maybe Text -> YamlBuilder
scientific :: Scientific -> YamlBuilder

namedScientific :: Text -> Scientific -> YamlBuilder

maybeNamedScientific :: Maybe Text -> Scientific -> YamlBuilder

alias :: Text -> YamlBuilder

-- | <i>Deprecated: Use scientific</i>
number :: Scientific -> YamlBuilder
toByteString :: ToYaml a => a -> ByteString

toByteStringWith :: ToYaml a => FormatOptions -> a -> ByteString
writeYamlFile :: ToYaml a => FilePath -> a -> IO ()

writeYamlFileWith :: ToYaml a => FormatOptions -> FilePath -> a -> IO ()
(.=) :: ToYaml a => Text -> a -> (Text, YamlBuilder)

-- | Contains options relating to the formatting (indendation, width) of
--   the YAML output.
data FormatOptions

-- | Set the maximum number of columns in the YAML output, or
--   <a>Nothing</a> for infinite. By default, the limit is 80 characters.
setWidth :: Maybe Int -> FormatOptions -> FormatOptions
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


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

-- | Encode a value into its YAML representation.
encode :: ToJSON a => a -> ByteString

-- | Encode a value into its YAML representation with custom styling.
encodeWith :: ToJSON a => EncodeOptions -> a -> ByteString

-- | Encode a value into its YAML representation and save to the given
--   file.
encodeFile :: ToJSON a => FilePath -> a -> IO ()

-- | Encode a value into its YAML representation with custom styling and
--   save to the given file.
encodeFileWith :: ToJSON a => EncodeOptions -> FilePath -> a -> IO ()

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

-- | A version of <a>decodeFile</a> which should not throw runtime
--   exceptions.
decodeFileEither :: FromJSON a => FilePath -> IO (Either ParseException a)

-- | A version of <a>decodeFileEither</a> that returns warnings along with
--   the parse result.
decodeFileWithWarnings :: FromJSON a => FilePath -> IO (Either ParseException ([Warning], a))

-- | A version of <a>decodeEither'</a> lifted to MonadThrow
decodeThrow :: (MonadThrow m, FromJSON a) => ByteString -> m a

-- | A version of <a>decodeFileEither</a> lifted to MonadIO
decodeFileThrow :: (MonadIO m, FromJSON a) => FilePath -> m a
decodeHelper :: FromJSON a => ConduitM () Event Parse () -> IO (Either ParseException ([Warning], Either String 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. N.B. This might not fit your usual understanding of
--   "parser". Instead you might like to think of <a>Parser</a> as a "parse
--   result", i.e. a parser to which the input has already been applied.
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

-- | Construct a new <a>Value</a> from a list of <a>Value</a>s.
array :: [Value] -> Value
(.=) :: (KeyValue kv, ToJSON v) => Text -> v -> kv
infixr 8 .=

-- | 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. .
--   <i>Warning</i>: If you are converting from a scientific to an
--   unbounded type such as <a>Integer</a> you may want to add a
--   restriction on the size of the exponent (see
--   <a>withBoundedScientific</a>) to prevent malicious input from filling
--   up the memory of the target system.
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 two 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>, <tt>withNumber</tt>, 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]

-- | Determine whether a string must be quoted in YAML and can't appear as
--   plain text. Useful if you want to use <a>setStringStyle</a>.
isSpecialString :: Text -> Bool

data EncodeOptions

defaultEncodeOptions :: EncodeOptions

-- | Set the string style in the encoded YAML. This is a function that
--   decides for each string the type of YAML string to output.
--   
--   <b>WARNING</b>: You must ensure that special strings (like
--   <tt>"yes"</tt>/<tt>"no"</tt>/<tt>"null"</tt>/<tt>"1234"</tt>) are not
--   encoded with the <a>Plain</a> style, because then they will be decoded
--   as boolean, null or numeric values. You can use <a>isSpecialString</a>
--   to detect them.
--   
--   By default, strings are encoded as follows:
--   
--   <ul>
--   <li>Any string containing a newline character uses the <a>Literal</a>
--   style</li>
--   <li>Otherwise, any special string (see <a>isSpecialString</a>) uses
--   <a>SingleQuoted</a></li>
--   <li>Otherwise, use <a>Plain</a></li>
--   </ul>
setStringStyle :: (Text -> (Tag, Style)) -> EncodeOptions -> EncodeOptions

-- | Set the encoding formatting for the encoded YAML. By default, this is
--   <a>defaultFormatOptions</a>.
setFormat :: FormatOptions -> EncodeOptions -> EncodeOptions

-- | Contains options relating to the formatting (indendation, width) of
--   the YAML output.
data FormatOptions

defaultFormatOptions :: FormatOptions

-- | Set the maximum number of columns in the YAML output, or
--   <a>Nothing</a> for infinite. By default, the limit is 80 characters.
setWidth :: Maybe Int -> FormatOptions -> FormatOptions

-- | <i>Deprecated: Please use decodeEither or decodeThrow, which provide
--   information on how the decode failed</i>
decode :: FromJSON a => ByteString -> Maybe a

-- | <i>Deprecated: Please use decodeFileEither, which does not confused
--   type-directed and runtime exceptions.</i>
decodeFile :: FromJSON a => FilePath -> IO (Maybe a)

-- | <i>Deprecated: Please use decodeEither' or decodeThrow, which provide
--   more useful failures</i>
decodeEither :: FromJSON a => ByteString -> Either String a


-- | 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 GHC.Base.Semigroup Data.Yaml.Config.MergedValue


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


-- | 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 => ConduitM Event o (WriterT AnchorMap m) YamlValue
sinkRawDoc :: MonadThrow m => ConduitM Event o 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.Exception.Exception Data.Yaml.Parser.YamlParseException
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.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.Semigroup (Data.Yaml.Parser.YamlParser a)
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


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

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

data Config

getConfCompare :: Config -> Text -> Text -> Ordering

-- | Sets ordering for object keys
setConfCompare :: (Text -> Text -> Ordering) -> Config -> Config

getConfDropNull :: Config -> Bool

-- | Drop entries with <a>Null</a> value from objects, if set to
--   <a>True</a>
setConfDropNull :: Bool -> Config -> Config

-- | The default configuration: do not sort objects or drop keys
defConfig :: Config

module Data.Yaml.TH

-- | A <tt>QuasiQuoter</tt> for YAML.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   {-# LANGUAGE QuasiQuotes #-}
--   import Data.Yaml.TH
--   
--   value :: Value
--   value = [yamlQQ|
--   name: John Doe
--   age: 23
--   |]
--   </pre>
yamlQQ :: QuasiQuoter

-- | Decode a YAML 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. N.B. This might not fit your usual understanding of
--   "parser". Instead you might like to think of <a>Parser</a> as a "parse
--   result", i.e. a parser to which the input has already been applied.
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

-- | Construct a new <a>Value</a> from a list of <a>Value</a>s.
array :: [Value] -> Value
(.=) :: (KeyValue kv, ToJSON v) => Text -> v -> kv
infixr 8 .=

-- | 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>, <tt>withNumber</tt>, 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]
