yaml 0.8.16 → 0.8.17
raw patch · 8 files changed
+195/−20 lines, 8 filesdep +raw-strings-qqdep ~basedep ~bytestringnew-component:exe:examples
Dependencies added: raw-strings-qq
Dependency ranges changed: base, bytestring
Files
- ChangeLog.md +8/−0
- Data/Yaml.hs +5/−0
- Data/Yaml/Config.hs +75/−7
- README.md +10/−12
- examples/Config.hs +53/−0
- examples/Main.hs +10/−0
- examples/Simple.hs +13/−0
- yaml.cabal +21/−1
ChangeLog.md view
@@ -1,3 +1,11 @@+## 0.8.17++* `loadYamlSettingsArgs`++## 0.8.16.1++* Slight doc improvement+ ## 0.8.16 Add env variable parsing. `loadYamlSettings` can read config values from the environment with Yaml that specifies an env var.
Data/Yaml.hs view
@@ -1,6 +1,7 @@ {-# LANGUAGE CPP #-} {-# LANGUAGE ScopedTypeVariables #-} {-# LANGUAGE OverloadedStrings #-}+ -- | Provides a high-level interface for processing YAML files. -- -- This module reuses most of the infrastructure from the @aeson@ package.@@ -16,6 +17,10 @@ -- -- 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.+ #if (defined (ghcjs_HOST_OS)) module Data.Yaml {-# WARNING "GHCJS is not supported yet (will break at runtime once called)." #-} #else
Data/Yaml/Config.hs view
@@ -9,16 +9,20 @@ -- -- On a historical note, this code was taken directly from the yesod web framework's configuration module. module Data.Yaml.Config- ( applyCurrentEnv- , getCurrentEnv- , applyEnvValue- , loadYamlSettings+ ( -- * High-level+ loadYamlSettings+ , loadYamlSettingsArgs+ -- ** EnvUsage , EnvUsage , ignoreEnv , useEnv , requireEnv , useCustomEnv , requireCustomEnv+ -- * Lower level+ , applyCurrentEnv+ , getCurrentEnv+ , applyEnvValue ) where @@ -31,7 +35,7 @@ import Data.Aeson import qualified Data.HashMap.Strict as H import Data.Text (Text, pack)-import System.Environment (getEnvironment)+import System.Environment (getArgs, getEnvironment) import Control.Arrow ((***)) import Control.Monad (forM) import Control.Exception (throwIO)@@ -50,6 +54,14 @@ mergeValues (Object x) (Object y) = Object $ H.unionWith mergeValues x y mergeValues x _ = x +-- | 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.+--+-- @since 0.8.16 applyEnvValue :: Bool -- ^ require an environment variable to be present? -> H.HashMap Text Text -> Value -> Value applyEnvValue requireEnv' env =@@ -82,26 +94,62 @@ parseValue val = fromMaybe (String val) $ Y.decode $ encodeUtf8 val +-- | Get the actual environment as a @HashMap@ from @Text@ to @Text@.+--+-- @since 0.8.16 getCurrentEnv :: IO (H.HashMap Text Text) getCurrentEnv = fmap (H.fromList . map (pack *** pack)) getEnvironment +-- | A convenience wrapper around 'applyEnvValue' and 'getCurrentEnv'+--+-- @since 0.8.16 applyCurrentEnv :: Bool -- ^ require an environment variable to be present? -> Value -> IO Value applyCurrentEnv requireEnv' orig = flip (applyEnvValue requireEnv') orig <$> getCurrentEnv +-- | Defines how we want to use the environment variables when loading a config+-- file. Use the smart constructors provided by this module.+--+-- @since 0.8.16 data EnvUsage = IgnoreEnv | UseEnv | RequireEnv | UseCustomEnv (H.HashMap Text Text) | RequireCustomEnv (H.HashMap Text Text) -ignoreEnv, useEnv, requireEnv :: EnvUsage+-- | Do not use any environment variables, instead relying on defaults values+-- in the config file.+--+-- @since 0.8.16+ignoreEnv :: EnvUsage ignoreEnv = IgnoreEnv++-- | Use environment variables when available, otherwise use defaults.+--+-- @since 0.8.16+useEnv :: EnvUsage useEnv = UseEnv++-- | 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.+--+-- @since 0.8.16+requireEnv :: EnvUsage requireEnv = RequireEnv -useCustomEnv, requireCustomEnv :: H.HashMap Text Text -> EnvUsage+-- | Same as 'useEnv', but instead of the actual environment, use the provided+-- @HashMap@ as the environment.+--+-- @since 0.8.16+useCustomEnv :: H.HashMap Text Text -> EnvUsage useCustomEnv = UseCustomEnv++-- | Same as 'requireEnv', but instead of the actual environment, use the+-- provided @HashMap@ as the environment.+--+-- @since 0.8.16+requireCustomEnv :: H.HashMap Text Text -> EnvUsage requireCustomEnv = RequireCustomEnv -- | Load the settings from the following three sources:@@ -111,6 +159,13 @@ -- * Run time environment variables -- -- * The default compile time config file+--+-- 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+--+-- @since 0.8.16 loadYamlSettings :: FromJSON settings => [FilePath] -- ^ run time config files to use, earlier files have precedence@@ -141,3 +196,16 @@ case fromJSON value of Error s -> error $ "Could not convert to AppSettings: " ++ s Success settings -> return settings++-- | Same as @loadYamlSettings@, but get the list of runtime config files from+-- the command line arguments.+--+-- @since 0.8.17+loadYamlSettingsArgs+ :: FromJSON settings+ => [Value] -- ^ any other values to use, usually from compile time config. overridden by files+ -> EnvUsage -- ^ use environment variables+ -> IO settings+loadYamlSettingsArgs values env = do+ args <- getArgs+ loadYamlSettings args values env
README.md view
@@ -2,18 +2,16 @@ Provides support for parsing and emitting Yaml documents. -This package includes the [full libyaml C library version 0.1.5 by Kirill-Simonov](http://pyyaml.org/wiki/LibYAML) in the package so you-don't need to worry about any non-Haskell dependencies.+This package includes the [full libyaml C library version 0.1.5 by Kirill Simonov](http://pyyaml.org/wiki/LibYAML) in the package so you don't need to worry about any non-Haskell dependencies. -The package is broken down into two primary modules.-"Data.Yaml" provides a high-level interface based-around the JSON datatypes provided by the @aeson@-package. "Text.Libyaml" provides a lower-level,-streaming interface. For most users, "Data.Yaml" is recommended.+The package is broken down into two primary modules. `Data.Yaml` provides a high-level interface based around the JSON datatypes provided by the `aeson` package. `Text.Libyaml` provides a lower-level, streaming interface. For most users, `Data.Yaml` is recommended. -Additional modules:+### Examples -* Data.Yaml.Include supports adding `!include` directives to your YAML files.-* DAta.Yaml.Builder and Data.Yaml.Parser allow more fine-grained control of parsing an rendering, as opposed to just using the aeson typeclass and datatype system for parsing and rendering.-* Data.Yaml.Aeson is currently a re-export of Data.Yaml to explicitly choose to use the aeson-compatible API.+Usage examples can be found in the `Data.Yaml` documentation or in the [examples](./examples) directory.++### Additional modules++* `Data.Yaml.Include` supports adding `!include` directives to your YAML files.+* `Data.Yaml.Builder` and `Data.Yaml.Parser` allow more fine-grained control of parsing an rendering, as opposed to just using the aeson typeclass and datatype system for parsing and rendering.+* `Data.Yaml.Aeson` is currently a re-export of `Data.Yaml` to explicitly choose to use the aeson-compatible API.
+ examples/Config.hs view
@@ -0,0 +1,53 @@+{-# LANGUAGE OverloadedStrings #-}+{-# LANGUAGE QuasiQuotes #-}++module Config where++import Data.Text (Text)+import qualified Data.Yaml as Y+import Data.Yaml (FromJSON(..), (.:))+import Text.RawString.QQ+import Data.ByteString (ByteString)+import Control.Applicative++configYaml :: ByteString+configYaml = [r|+resolver: lts-3.7+packages:+ - ./yesod-core+ - ./yesod-static+ - ./yesod-persistent+ - ./yesod-newsfeed+ - ./yesod-form+ - ./yesod-auth+ - ./yesod-auth-oauth+ - ./yesod-sitemap+ - ./yesod-test+ - ./yesod-bin+ - ./yesod+ - ./yesod-eventsource+ - ./yesod-websockets++# Needed for LTS 2+extra-deps:+- wai-app-static-3.1.4.1+|]++data Config =+ Config {+ resolver :: Text+ , packages :: [FilePath]+ , extraDeps :: [Text]+ } deriving (Eq, Show)++instance FromJSON Config where+ parseJSON (Y.Object v) =+ Config <$>+ v .: "resolver" <*>+ v .: "packages" <*>+ v .: "extra-deps"+ parseJSON _ = fail "Expected Object for Config value"++main :: IO ()+main =+ print $ (Y.decode configYaml :: Maybe Config)
+ examples/Main.hs view
@@ -0,0 +1,10 @@+module Main where++import qualified Config+import qualified Simple++main :: IO ()+main = do+ Simple.main+ Config.main+
+ examples/Simple.hs view
@@ -0,0 +1,13 @@+{-# LANGUAGE OverloadedStrings #-}++module Simple where++import qualified Data.Yaml as Y++main :: IO ()+main = do+ print $ (Y.decode "[1,2,3]" :: Maybe [Integer])++-- You can go one step further and decode into a custom type by implementing+-- 'FromJSON' for that type. This is also appropriate where extra+-- normalization, formatting or manipulation of the YAML is required on decode.
yaml.cabal view
@@ -1,5 +1,5 @@ name: yaml-version: 0.8.16+version: 0.8.17 license: BSD3 license-file: LICENSE author: Michael Snoyman <michael@snoyman.com>, Anton Ageev <antage@gmail.com>,Kirill Simonov @@ -29,6 +29,10 @@ description: don't install the yaml2json or json2yaml executables default: False +flag no-examples+ description: don't build the examples+ default: True+ flag system-libyaml description: Use the system-wide libyaml instead of the bundled copy default: False@@ -132,6 +136,22 @@ , mockery , base-compat ghc-options: -Wall++executable examples+ if flag(no-examples)+ Buildable: False+ else+ Buildable: True+ hs-source-dirs: examples+ main-is: Main.hs+ other-modules: Config+ Simple+ build-depends: base+ , bytestring+ , raw-strings-qq+ , text+ , yaml+ ghc-options: -Wall source-repository head type: git