-- 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.21 -- | Low-level, streaming YAML interface. For a higher-level interface, see -- Data.Yaml. 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 decodeFile but with support for relative and absolute -- includes. -- -- The syntax for includes follows the form: -- -- 
--   somekey: !include ./somefile.yaml
--
decodeFile :: FromJSON a => FilePath -> IO (Maybe a) -- | Like decodeFileEither but with support for relative and -- absolute includes. -- -- The syntax for includes follows the form: -- -- 
--   somekey: !include ./somefile.yaml
--
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 -- | Deprecated: Use scientific 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 encode. -- -- 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 aeson -- 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 Text.Libyaml module instead. -- -- For documentation on the aeson types, functions, classes, and -- operators, please see the Data.Aeson module of the -- aeson 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 show to display a ParseException on the -- screen. Instead of displaying the data constructors applied to their -- arguments, a more textual output is returned. For example, instead of -- printing: -- -- 
--   InvalidYaml (Just (YamlParseException {yamlProblem = "did not find expected ',' or '}'", yamlContext = "while parsing a flow mapping", yamlProblemMark = YamlMark {yamlIndex = 42, yamlLine = 2, yamlColumn = 12}})))
--
-- -- It looks more pleasant to print: -- -- 
--   YAML parse exception at line 2, column 12,
--   while parsing a flow mapping:
--   did not find expected ',' or '}'
--
-- -- 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 Value from a list of name/value Pairs. 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 Object. -- The result is empty 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 must be -- present in an object for it to be valid. If the key and value are -- optional, use .:? instead. (.:) :: FromJSON a => Object -> Text -> Parser a -- | Retrieve the value associated with the given key of an Object. -- The result is Nothing if the key is not present or if its value -- is Null, or empty 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 .: instead. (.:?) :: FromJSON a => Object -> Text -> Parser (Maybe a) -- | Helper for use in combination with .:? 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 -- .: instead. -- -- Example usage: -- -- 
--   v1 <- o .:? "opt_field_with_dfl" .!= "default_val"
--   v2 <- o .:  "mandatory_field"
--   v3 <- o .:? "opt_field2"
--
(.!=) :: Parser (Maybe a) -> a -> Parser a parseMonad :: Monad m => (a -> Parser b) -> a -> m b -- | Run a Parser with an Either result type. If the parse -- fails, the Left payload will contain an error message. parseEither :: (a -> Parser b) -> a -> Either String b -- | Run a Parser with a Maybe result type. parseMaybe :: (a -> Parser b) -> a -> Maybe b -- | A type that can be converted to JSON. -- -- An example type and instance: -- -- 
--   -- Allow ourselves to write Text literals.
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord = Coord { x :: Double, y :: Double }
--   
--   instance ToJSON Coord where
--     toJSON (Coord x y) = object ["x" .= x, "y" .= y]
--   
--     toEncoding (Coord x y) = pairs ("x" .= x <> "y" .= y)
--
-- -- Instead of manually writing your ToJSON instance, there are two -- options to do it automatically: -- -- -- -- To use the second, simply add a deriving Generic -- clause to your datatype and declare a ToJSON instance for your -- datatype without giving definitions for toJSON or -- toEncoding. -- -- For example, the previous example can be simplified to a more minimal -- instance: -- -- 
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics
--   
--   data Coord = Coord { x :: Double, y :: Double } deriving Generic
--   
--   instance ToJSON Coord where
--       toEncoding = genericToEncoding defaultOptions
--
-- -- Why do we provide an implementation for toEncoding here? The -- toEncoding function is a relatively new addition to this class. -- To allow users of older versions of this library to upgrade without -- having to edit all of their instances or encounter surprising -- incompatibilities, the default implementation of toEncoding -- uses toJSON. This produces correct results, but since it -- performs an intermediate conversion to a Value, it will be less -- efficient than directly emitting an Encoding. Our one-liner -- definition of toEncoding above bypasses the intermediate -- Value. -- -- If DefaultSignatures doesn't give exactly the results you -- want, you can customize the generic encoding with only a tiny amount -- of effort, using genericToJSON and genericToEncoding -- with your preferred Options: -- -- 
--   instance ToJSON Coord where
--       toJSON     = genericToJSON defaultOptions
--       toEncoding = genericToEncoding defaultOptions
--
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 -- Value using toJSON. 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 must provide an -- implementation for this method. The easiest way to do so is by having -- your types implement Generic using the DeriveGeneric -- extension, and then have GHC generate a method body as follows. -- -- 
--   instance ToJSON Coord where
--       toEncoding = genericToEncoding defaultOptions
--
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 -- Object could be missing a required key, an Array 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: -- -- -- -- An example type and instance: -- -- 
--   -- Allow ourselves to write Text literals.
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord = Coord { x :: Double, y :: Double }
--   
--   instance FromJSON Coord where
--     parseJSON (Object v) = Coord    <$>
--                            v .: "x" <*>
--                            v .: "y"
--   
--     -- We do not expect a non-Object value here.
--     -- We could use mzero to fail, but typeMismatch
--     -- gives a much more informative error message.
--     parseJSON invalid    = typeMismatch "Coord" invalid
--
-- -- Instead of manually writing your FromJSON instance, there are -- two options to do it automatically: -- -- -- -- To use the second, simply add a deriving Generic -- clause to your datatype and declare a FromJSON instance for -- your datatype without giving a definition for parseJSON. -- -- For example, the previous example can be simplified to just: -- -- 
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics
--   
--   data Coord = Coord { x :: Double, y :: Double } deriving Generic
--   
--   instance FromJSON Coord
--
-- -- If DefaultSignatures doesn't give exactly the results you -- want, you can customize the generic decoding with only a tiny amount -- of effort, using genericParseJSON with your preferred -- Options: -- -- 
--   instance FromJSON Coord where
--       parseJSON = genericParseJSON defaultOptions
--
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 decodeEither which returns the -- YamlException. -- -- Since 0.8.3 decodeEither' :: FromJSON a => ByteString -> Either ParseException a -- | A version of decodeFile 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 Data.Yaml. 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 -- -- loadYamlSettings is a high-level API for loading YAML and -- merging environment variables. A yaml value of -- _env:ENV_VAR:default will lookup the environment variable -- ENV_VAR. -- -- 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: -- -- -- -- For example, to load up settings from config/foo.yaml and -- allow overriding from the actual environment, you can use: -- -- 
--   loadYamlSettings ["config/foo.yaml"] [] useEnv
--
loadYamlSettings :: FromJSON settings => [FilePath] -> [Value] -> EnvUsage -> IO settings -- | Same as loadYamlSettings, 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 useEnv, but instead of the actual environment, use the -- provided HashMap as the environment. useCustomEnv :: HashMap Text Text -> EnvUsage -- | Same as requireEnv, but instead of the actual environment, use -- the provided HashMap as the environment. requireCustomEnv :: HashMap Text Text -> EnvUsage -- | A convenience wrapper around applyEnvValue and -- getCurrentEnv applyCurrentEnv :: Bool -> Value -> IO Value -- | Get the actual environment as a HashMap from Text to -- Text. getCurrentEnv :: IO (HashMap Text Text) -- | Override environment variable placeholders in the given Value -- with values from the environment. -- -- If the first argument is True, then all placeholders _must_ -- be provided by the actual environment. Otherwise, default values from -- the Value will be used. applyEnvValue :: Bool -> HashMap Text Text -> Value -> Value instance Data.Semigroup.Semigroup Data.Yaml.Config.MergedValue module Data.Yaml.TH -- | Decode a yaml file at compile time. Only available on GHC -- version 7.8.1 or higher. -- --

Examples

-- -- 
--   {-# LANGUAGE TemplateHaskell #-}
--   
--   config :: Config
--   config = $$(decodeFile "config.yaml")
--
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 Value from a list of name/value Pairs. 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 Object. -- The result is empty 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 must be -- present in an object for it to be valid. If the key and value are -- optional, use .:? instead. (.:) :: FromJSON a => Object -> Text -> Parser a -- | Retrieve the value associated with the given key of an Object. -- The result is Nothing if the key is not present or if its value -- is Null, or empty 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 .: instead. (.:?) :: FromJSON a => Object -> Text -> Parser (Maybe a) -- | Helper for use in combination with .:? 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 -- .: instead. -- -- Example usage: -- -- 
--   v1 <- o .:? "opt_field_with_dfl" .!= "default_val"
--   v2 <- o .:  "mandatory_field"
--   v3 <- o .:? "opt_field2"
--
(.!=) :: 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 -- Object could be missing a required key, an Array 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: -- -- -- -- An example type and instance: -- -- 
--   -- Allow ourselves to write Text literals.
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord = Coord { x :: Double, y :: Double }
--   
--   instance FromJSON Coord where
--     parseJSON (Object v) = Coord    <$>
--                            v .: "x" <*>
--                            v .: "y"
--   
--     -- We do not expect a non-Object value here.
--     -- We could use mzero to fail, but typeMismatch
--     -- gives a much more informative error message.
--     parseJSON invalid    = typeMismatch "Coord" invalid
--
-- -- Instead of manually writing your FromJSON instance, there are -- two options to do it automatically: -- -- -- -- To use the second, simply add a deriving Generic -- clause to your datatype and declare a FromJSON instance for -- your datatype without giving a definition for parseJSON. -- -- For example, the previous example can be simplified to just: -- -- 
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics
--   
--   data Coord = Coord { x :: Double, y :: Double } deriving Generic
--   
--   instance FromJSON Coord
--
-- -- If DefaultSignatures doesn't give exactly the results you -- want, you can customize the generic decoding with only a tiny amount -- of effort, using genericParseJSON with your preferred -- Options: -- -- 
--   instance FromJSON Coord where
--       parseJSON = genericParseJSON defaultOptions
--
class FromJSON a parseJSON :: FromJSON a => Value -> Parser a parseJSONList :: FromJSON a => Value -> Parser [a]